# GSLinkedList documentation

rfm@gnu.org
2010 Free Software Foundation, Inc.
Software documentation for the GSLinkStore class
GSLinkedList.h
This class extends GSLinkedList by providing storage for unused links and re-using those links when a new link is needed.
This avoids the overhead of allocating/deallocating links and provides an API more like a mutable array.
The unused links
The class used for links
storeFor:
theLinkClass
Creates an instance of a store to be used to create links using the specified class (must be a subclass of GSListLink). If the class is `nil` then GSListLink is used.
addObject:
anObject
Adds an object at the tail of the list (calls -insertObject:after:), making it the last object in the list.
Returns the list link that the object is stored in.
firstObject
Returns the first (head) object in the list or `nil` if the list is empty.
insertObject:
anObject
after:
at
Inserts anObject immediately after the specified link. If at is `nil` the object is inserted at the end of the list (as tail).
Returns the list link that the object is stored in.
insertObject:
anObject
before:
at
Inserts anObject immediately before the specified link. If at is `nil` the object is inserted at the start of the list (as head).
Returns the list link that the object is stored in.
lastObject
Returns the last (tail) object in the list or `nil` if the list is empty.
purge
Removes any unused links from the list (to release the memory they occupied).
removeFirstObject
Removes the first (head) object from the list (or does nothing if the list is empty).
removeLastObject
Removes the last (tail) object from the list (or does nothing if the list is empty).
removeObjectAt:
at
Removes the object in the specified link.
removeObjectAtIndex:
index
Removes the object at the specified position.
Software documentation for the GSLinkedList class
GSLinkedList.h
GSLinkedList manages a list of GSListLink objects.
The notional direction of the list is from head to tail. So the head is considered to be the first link in the list and tail is considered to be the last (head is before tail, tail is after head).
Description forthcoming.
Description forthcoming.
Description forthcoming.
append:
link
Appends link at the end of the linked list managed by the receiver.
Retains the link.
count
Returns the number of links in the list.
empty
Remove all links from the list and release them all.
findEqual:
object
from:
start
back:
aFlag
Searches the linked list returning the link containing object or `nil` if it is not found.
The comparison is performed using the [NSObject -isEqual:] method of object.
If start is `nil` then the whole list is searched.
This method will not find links containing `nil` items.
findIdentical:
object
from:
start
back:
aFlag
Searches the linked list returning the link containing object or `nil` if it is not found.
If start is `nil` then the whole list is searched.
A direct pointer comparison is used to determine equality.
head
Returns the first link in the list.
insert:
link
after:
at
Inserts other immediately after the receiver.
Retains the link.
insert:
link
before:
at
Inserts other immediately before the receiver.
Retains the link.
removeLink:
link
Removes the link from the receiver.
releases the link.
tail
Returns the last link in the list.
Software documentation for the GSListLink class
GSLinkedList.h
GSListLink provides simple doubly linked list functionality to avoid the need to constantly re-invent it (as the OpenStep/Cocoa APIs do not provide this). The emphasis is on speed of operation so instance variables are directly accessible and inline functions are provided to manipulate them (without error cehcking), but you can/should avoid these direct access features unless speed is really critical.
A list may either be 'normal'... (where the head/tail ends of the list have a `nil` pointer to the previous/next link) or 'circular' in which case the list is not terminated.
The GSListLink item carries a minimal payload of a single item which is retained by the link.
The GSListLink owner is an optional pointer to an object which 'owns' the link... a GSLinkedList instance may use this to check link ownership when manipulating links.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
initCircular
Initialise the receiver as a link for a circular linked list.
item
Return the item in the link.
next
Return the next item in the list containing the receiver, or `nil` if there are no more items.
owner
Return the list which owns the receiver or `nil` if the receiver is not in a list.
previous
Return the previous item in the list containing the receiver, or `nil` if there are no more items.
setItem:
anItem
Set an item value by retaining it and releasing any previous value.
GSLinkedList types

Description forthcoming.
GSLinkedList functions

link
at
Inserts link after at in a circular list.
Arguments must not be `nil` and link must not be in a list (ie its next and previous pointers must point to itsself).
link
at
Inserts link before at in a circular list.
Arguments must not be `nil` and link must not be in a list (ie its next and previous pointers must point to itsself).
link
Removes link from any list it is in.
The link argument must not be `nil`.
link
at
Inserts link after at in a normal list.
Arguments must not be `nil` and link must not be in a list (ie its next and previous pointers must both be `nil`).
link
at
Inserts link before at in a normal list.
Arguments must not be `nil` and link must not be in a list (ie its next and previous pointers must both be `nil`).
link
Removes link from the list it is in.
The link argument must not be `nil`.
list
link
Description forthcoming.
anObject
list
at
Adds the object to the list after the specified link.
Calls GSLinkedListInsertAfter() .
Returns the list link that the object is stored in.
anObject
list
at
Adds the object to the list before the specified link.
Calls GSLinkedListInsertBefore() .
Returns the list link that the object is stored in.
list
Description forthcoming.
list
at
Removes the object held in the specified link.
If at is `nil` or is not owned by the list, this does nothing.
object
list
from
back
Searches from list to the end looking for the first link containing object (as determined by using object's [NSObject -isEqual:] method).
If back is `YES`, the search is in the direction from tail to head rather than the normal search from head to tail.
If from is `nil` the list is search from head or tail as appropriate to the direction in which it is searched.
object
list
from
back
Searches from list to the end looking for the first link containing object (as determined by direct pointer comparison).
If back is `YES`, the search is in the direction from tail to head rather than the normal search from head to tail.
If from is `nil` the list is search from head or tail as appropriate to the direction in which it is searched.
list
Returns the first (head) object in the list.
link
list
at
Inserts link immediately after at.
If at is `nil`, inserts at the end of the list (link becomes tail).
Updates the head, tail and count variables of list.
Does not retain link .
link
list
at
Inserts link immediately before at.
If at is `nil`, inserts at the start of the list (link becomes head).
Updates the head, tail and count variables of list.
Does not retain link .
list
Returns the last (tail) object in the list .
link
list
Moves the link to the head of the list (makes it the first object) if it is not already there.
link
list
Moves the link to the tail of the list (makes it the last object) if it is not already there.
link
list
Removes link from the list.
Updates the head, tail and count variables of list.
Does not release link.