Release 0.9 Copyright ©1994 by Don Yacktman. All Rights Reserved.
MiscLinkedList |
Inherits From: | Object | |
Declared In: | misckit/MiscLinkedList.h | |
Protocols: | NXTransport |
Class Description |
The MiscLinkedList is an implementation of a doubly-linked list. This type of data structure is useful for storing sparse
data that will be traversed often. (Linked lists are very memory efficient when dealing with sparse data, unlike hashing
and some array schemes.) If fast random access is desired, a linked list may not be suitable for the application. The
MiscLinkedList is much faster than the NeXT List object for insertion and deletion, but it suffers in performance when
searching for a specific node (random access). Traversing the List from one end to the other is about the same, but
slightly faster for the NeXT List object.
The MiscLinkedList can store any type of objects--or a mixture of different object types. A single object may be stored in the list in multiple places, as well. Using a MiscLinkedList is simple. First create a new list using the standard +alloc and -init methods. Once created, the list has references to both the start and the end of the list as well as a pointer to the "current" node. The pointer to the current node is akin to a cursor: most operations on the MiscLinkedList will occur at this node or immediately before or after it. To add objects to a MiscLinkedList, use the -insertObjectAfter: or -insertObjectBefore methods. They will insert the object either before or after the current node in the list. You can also insert a complete MiscLinkedList or a List into a MiscLinkedList. To do this, use one of the -insertList:, -insertListAtFront:, and -appendList: methods. To remove an object, use -deleteObject. You can also change the ordering of nodes in the list. A node my be swapped with it's neighbor with either -swapWithNext or -swapWithPrevious. A node may be moved to the front or end of the list by using -moveToFirst or -moveToLast. The current object may be replaced with a new object by using the -setObject: method. To traverse the list, use -goFirst, -goLast, -goNext, or -goPrevious. Note that many of the methods which traverse the list might alter the current node; this is documented below for every method in which it occurs. All objects in a MiscLinkedList may be broadcast a messgae with -makeObjectsPerform: and -makeObjectsPerform:with:. You can find out how many objects are in the MiscLinkedList via the -count or -getLength methods. (They are identical.) There are also several methods which are similiar to the List object. You can compare lists with the -isEqual method. You can replace and remove objects, given their id, with -replaceObject:with: and -removeObject: respectively. You can add objects uniquely with -addObjectIfAbsent:. For convenience, there are also methods to operate on the front and end of a MiscLinkedList: -firstObject, -removeFirstObject, -lastObject, and -removeLastObject. You can also use -addObject: to append objects to a MiscLinkedList. A MiscLinkedList implements the NXTransport protocol, allowing it to be copied over a Distributed Objects connection. It also understands -read: and -write: which allows it to be archived to a stream. Internally, the MiscLinkedList uses a special class, the MiscLinkedListNode, to keep track of the actual list. Each node contains a pointer to the next and previous node and a pointer to the object it contains. Normally you won't need to worry about these nodes; their use allows any kind of object to be added to the list without it needing to know about linked lists and it allows an object to appear in the list multiple times. (This is better than requiring an object to have pointers to the next and previous object itself.) If you need to add special capabilities to a MiscLinkedList, however, you may wish to subclass the MiscLinkedListNode to facilitate this. See the documentation for that class if you need more information about this. The MiscLinkedList may be initialized to deal with a different node class by using the -initForClass: method. You can access the current node object, rather than the object it contains, with the -getNode method. Under normal circumstances, this shouldn't ever be necessary. When you are finished with the MiscLinkedList, you can free it with -free, which frees the MiscLinkedList and it's nodes, but not the objects it contains. If you wish to free the objects, first send a -freeObjects message Note that it is unwise to send -freeObjects if an object appears in the list more than once, since the MiscLinkedList will attempt to free the object more than once. The -empty method will empty out a MiscLinkedList without freeing the objects it contains (but it will free the nodes). |
Instance Variables |
id current_node; id first_node; id last_node; id node_class; int node_length; |
current_node | Pointer to the "current" node in the list. Most actions are performed in the vicinity of the node this points to. | |
first_node | Pointer to the last node of the list. | |
last_node | Pointer to the last node of the list. | |
node_class | The class object used to create new nodes; this should ideally be either a MiscLinkedListNode subclass or respond to all the same methods as the MiscLinkedListNode, since MiscLinkedList doesn't check -respondsTo:. | |
node_length | The number of nodes (objects) in the MiscLinkedList |
Method Types |
Initializing and freeing | - empty - freeNodes - freeObjects - init - initForClass: | |
Getting size | - count - getLength | |
Changing which is the current node | - firstObject - goFirst - goLast - goNext - goPrevious - lastObject | |
Manipulating the current node | - getNode - getObject - moveToFirst - moveToLast - setObject: - swapWithNext - swapWithPrevious | |
Adding and deleting objects | - addObject: - addObjectIfAbsent: - deleteObject - insertObjectAfter: - insertObjectBefore: - removeLastObject - removeFirstObject - removeObject: - replaceObject: | |
Adding an entire MiscLinkedList | - appendList: - insertList: - insertListAtFront: | |
Comparing MiscLinkedLists | - isEqual: | |
Sending messages to the objects | - makeObjectsPerform: - makeObjectsPerform:with: | |
Archiving a MiscLinkedList | - read: - write: |
Instance Methods |
addObject: |
- addObject:anObject |
Adds anObject to the end of the list. Returns self.
See also: -addObjectIfAbsent: and -removeObject:
addObjectIfAbsent: |
- addObjectIfAbsent:anObject |
Adds anObject to the end of the list if anObject is not already anywhere in the list. Returns self.
See also: -addObject: and -removeObject:
appendList: |
- appendList:this_list |
Insert the list this_list after the last node of the receiving list. The objects that were in this_list are left in the same
order when inserted into the receiver. The list this_list is left unchanged. The list this_list may be either a
MiscLinkedList, a List, or subclasses thereof. Returns self.
See also: -insertList: and -insertListAtFront:
count |
- (unsigned int)count |
Returns the number of objects (nodes) in the list.
See also: -getLength
deleteObject |
- deleteObject |
Deletes the current node and object. The node previous to the deleted node becomes the current node unless the
deleted node was the first node. In that case, the first node in the list will be the current node. Returns self.
See also: -removeFirstObject, -removeLastObject, and -removeObject:
empty |
- empty |
Empties the list of all objects and frees all the nodes that made up the list. The objects in the list are not freed.
See also: -free, -freeObjects, and -freeNodes
firstObject |
- firstObject |
Returns the first object in the list.
See also: -getObject and -lastObject
free |
- free |
Frees all the nodes in the list and the list itself.
See also: -empty, -free, and -freeNodes
freeObjects |
- freeObjects |
Frees all the objects in the list and the nodes associated with them. Returns self.
See also: -empty, -free, and -freeNodes
freeNodes |
- freeNodes |
Frees all the nodes in the receiver but does not free the objects that were in the nodes. Returns self.
See also: -empty, -free, and -freeObjects
getLength |
- (int)getLength |
Returns the number of objects (nodes) in the list.
See also: -count
getNode |
- getNode |
Returns the current node. Under most circumstances you shouldn't need to use this method.
See also: -getObject
getObject |
- getObject |
Returns the object stored in the current node.
See also: -firstObject, -getNode, and -lastObject
goFirst |
- goFirst |
Make the first node of the list the current node. Returns nil if there are no objects in the list, otherwise returns self.
See also: -goLast, -goNext, and -goPrevious
goLast |
- goLast |
Make the last node of the list the current node. Returns nil if there are no objects in the list, otherwise returns self.
See also: -goFirst, -goNext, and -goPrevious
goNext |
- goNext |
Make the node after the current node become the current node. If already at the end of the list, nil is returned.
Otherwise, returns self.
See also: -goFirst, -goLast, and -goPrevious
goPrevious |
- goPrevious |
Make the node before the current node become the current node. If already at the start of the list, nil is returned.
Otherwise, returns self.
See also: -goFirst, -goLast, and -goNext
init |
- init |
Initialize the receiving instance of MiscLinkedList with the MiscLinkedListNode class as the class used to create new
nodes in the list. Returns self.
See also: -initForClass:
initForClass: |
- initForClass:this_class |
Initialize the receiving instance of MiscLinkedList with the class this_class as the class used to create new nodes in
the list. Returns self.
See also: -init
insertList: |
- insertList:this_list |
Insert the list this_list before the current node of the receiving list. The objects that were in this_list are left in the
same order when inserted into the receiver. The list this_list is left unchanged. The list this_list may be either a
MiscLinkedList, a List, or subclasses thereof. Returns self.
See also: -appendList: and -insertListAtFront:
insertListAtFront: |
- insertListAtFront:this_list |
Insert the list this_list at the front of the receiving list. The objects that were in this_list are left in the same order
when inserted into the receiver. The list this_list is left unchanged. The list this_list may be either a MiscLinkedList,
a List, or subclasses thereof. Returns self.
See also: -appendList: and -insertList:
insertObjectAfter: |
- insertObjectAfter:this_object |
Insert this_object into the list after the current object/node. Returns this_object.
See also: -insertObjectBefore:
insertObjectBefore: |
- insertObjectBefore:this_object |
Insert this_object into the list before the current object/node. Returns this_object.
See also: -insertObjectAfter:
isEqual: |
- (BOOL)isEqual:anObject |
Returns YES if anObject is the same class as the receiver and contains the exact same set of objects as determined by
sending -isEqual: to each of the objects in the list. Returns NO otherwise.
lastObject |
- lastObject |
Returns the last object in the list.
See also: -firstObject and -getObject
makeObjectsPerform: |
- makeObjectsPerform:(SEL)aSelector |
Traverses the list from the first to the last node, sending the aSelector message to each object in the list. Returns self.
See also: -makeObjectsPerform:with:
makeObjectsPerform:with: |
- makeObjectsPerform:(SEL)aSelector with:anObject |
Traverses the list from the first to the last node, sending the aSelector message with the argument anObject to each
object in the list. Returns self.
See also: -makeObjectsPerform:
moveToFirst |
- moveToFirst |
Moves the current node to the front of the MiscLinkedList. Returns self. If there is no current node, then nil is
returned.
See also: -moveToLast, -swapWithPrevious, and -swapWithNext
moveToLast |
- moveToLast |
Moves the current node to the end of the MiscLinkedList. Returns self. If there is no current node, then nil is returned.
See also: -moveToFirst, -swapWithPrevious, and -swapWithNext
read: |
- read:(NXTypedStream *)stream |
Unarchives the receiving MiscLinkedList and all the objects it contains from stream. Returns self.
See also: -write:
removeFirstObject |
- removeFirstObject |
Removes the first object from the list. The removed object is returned.
See also: -deleteObject, -removeLastObject, and -removeObject:
removeLastObject |
- removeLastObject |
Removes the last object from the list. The removed object is returned.
See also: -deleteObject, -removeFirstObject, and -removeObject:
removeObject: |
- removeObject:anObject |
Searches through the list for the first occurrence of anObject and removes it from the list. Returns anObject.
See also: -addObject:, -addObjectIfAbsent:, -deleteObject, -removeFirstObject, and -removeLastObject
replaceObject:with: |
- replaceObject:anObject with:newObject |
Searches from the start of the list for the first occurrence of anObject and replaces it with newObject. Returns
anObject. This method will change the current node; the replaced object's node becomes the new current node.
See also: -setObject:
setObject: |
- setObject:this_object |
Sets the object in the current node to this_object. Returns the object which was replaced.
See also: -replaceObject:with:
swapWithNext |
- swapWithNext |
Swaps the current node with the node just after of it the MiscLinkedList. Returns self. If there is no current node or no
next node, then nil is returned.
See also: -moveToFirst, -moveToLast, and -swapWithPrevious
swapWithPrevious |
- swapWithPrevious |
Swaps the current node with the node in front of it the MiscLinkedList. Returns self. If there is no current node or no
previous node, then nil is returned.
See also: -moveToFirst, -moveToLast, and -swapWithNext
write: |
- write:(NXTypedStream *)stream |
Archives the receiving MiscLinkedList and all the objects it contains to stream. Returns self.
See also: -read: |