There can be no nil entries between the first (at offset 0) and last elements (at size minus one). For this reason, all methods that add objects refuse to add nil's. When entries are added or removed, the offsets of the remaining entries change.
Offsets into collections are traditionally unsigned integers. Methods that return an offset, e.g., offsetOf: and lastOffset return a value of (unsigned)-1 to indicate that an object has not been found.
There are many methods for adding or inserting members into a collection. Although members may be added at any point in the collection, they are generally added at the end using add:.
A member may be searched for using either the find: or findMatching: method. In the first case, the member in the collection must be an exact match. In the second case, the member must match in the sense of the isEqual: method.
+ newReturns a new empty collection.
- copyReturns a new copy of the collection.
- deepCopyReturns a new copy of the collection. The members in the new collection are deep copies of the members in the original collection.
- emptyYourselfRemoves all the members of the collection (without freeing them). Returns the receiver.
- freeContentsRemoves and frees all the members of the receiver, but doesn't free the receiver itself. Returns the receiver.
- freeFrees the collection, but not its contents. Returns nil. Do :
if you want to free the collection and its contents.aCltn = [[aCltn freeObjects] free];
- (unsigned) sizeReturns the number of objects in the collection.
- (BOOL) isEmptyWhether the number of objects in the collection is equal to zero.
- (unsigned) lastOffsetReturns the offset of the last element. If there are no elements it returns (unsigned)-1.
- eachElementReturns a sequence of the elements in the collection.
aSeq = [aCltn eachElement]; while ((anElement = [aSeq next])) { /* do something */ } aSeq = [aSeq free];
- firstElementReturns the first element in the collection. If there are no elements, returns nil.
- lastElementReturns the last element in the collection. If there are no elements, returns nil.
- (unsigned) hashReturns a hash value based on the receiver's address and the results of sending the hash message to the contents.
- (BOOL) isEqual : aCltnReturns YES if aCltn is a collection, and if each member of its contents responds affirmatively to the message isEqual: when compared to the corresponding member of the receiver's contents.
- add : anObjectAdds anObject to the collection as the last element and returns the receiver.
- addFirst : newObjectAdds newObject as the first (zero-th) element of the collection. Returns the receiver. Any elements at this offset or higher are relocated to the next higher offset to make room.
- addLast : newObjectIdentical to the add: method.
- addIfAbsent : anObjectAdds anObject to the collection only if the collection does not have that same object, i.e., one that is pointer equal. Returns the receiver.
- addIfAbsentMatching : anObjectAdds anObject to the collection only if the collection does not have a matching object, i.e., one that is isEqual:. Returns the receiver.
- at :(unsigned ) anOffset insert : anObjectInserts anObject at offset anOffset and returns the receiver. Any elements at this offset or higher are relocated to the next higher offet to make room. If anOffset is greater than the size of the collection, an error is generated.
- insert : newObject after : oldObjectSearches for oldObject in the collection, and inserts newObject after oldObject, moving later elements if necessary to make room. If oldObject is not found, an error is generated. Returns the receiver.
- insert : newObject before : oldObjectFirst searches for oldObject in the collection, and inserts the newObject before oldObject. If oldObject is not found, an error is generated. Returns the receiver.
- after : anObjectSearches for anObject in the collection and, if found, returns the next object. If anObject is the last element in the array, returns nil. Generates an error if anObject cannot be found.
- before : anObjectSearches for anObject in the collection and, if found, returns the object before it. If anObject is the first element in the array, returns nil. Generates an error if anObject cannot be found.
- at :(unsigned ) anOffsetReturns the object at anOffset with anObject and returns the old member at anOffset. Generates an error if anOffset is greater than the size of the collection.
- at :(unsigned ) anOffset put : anObjectReplaces the object at anOffset with anObject and returns the old member at anOffset. Generates an error if anOffset is greater than the size of the collection. Returns nil if anObject is nil.
- removeFirstRemoves the first element. Returns that element or nil if there are no elements.
- removeLastRemoves the last element. Returns that element or nil if there are no elements.
- removeAt :(unsigned ) anOffsetRemoves the object at anOffset. When an object is removed, the remaining elements are adjusted so that there are no nil entries between the first and last element. This adjustment shrinks the collection and changes the offset of the entries. Returns the object removed.
- remove : oldObjectRemoves oldObject from the collection if oldObject is found, and returns oldObject. Otherwise returns nil.
- addContentsTo : aColAdds every element of the receiver to aCol and returns aCol. If aCol is nil, returns nil. The argument aCol need not actually be a collection, as long as it responds to add: in the same way as collections do.
- addContentsOf : aColAdds each member of aCol to the receiver. Returns the receiver. If aCol is nil, no action is taken. The argument aCol need not be a collection, so long as it responds to eachElement in the same way as collections do.
- removeContentsOf : aColRemoves each of the members of aCol from the receiver. Returns the receiver. The argument aCol need not be a collection, as long as it responds to eachElement as collections do.
If aCol is the same object as the receiver, it empties itself using emptyYourself and returns the receiver.
- removeContentsFrom : aColRemoves each of the members of the receiver from aCol. Returns the receiver. The argument aCol need not be a collection, as long as it responds to remove: in the same way as collections.
- find : anObjectReturns the first member which is the same as anObject, i.e., which is pointer equal. If none is found, returns nil.
- findMatching : anObjectReturns the first member which matches anObject, i.e., using isEqual: for comparison. If none is found, returns nil.
- findSTR :(STR ) strValueReturns the first member whose string contents matches strValue, using the isEqualSTR: method for comparison. If none is found, returns nil.
- (BOOL) contains : anObjectReturns YES if the receiver contains anObject. Otherwise, returns NO. Implementation is in terms of the receiver's find: method.
- (unsigned) offsetOf : anObjectSearches for anObject in the contents and returns the offset of the first pointer equal object it finds. Otherwise, returns (unsigned)-1. If anObject is nil, also returns (unsigned)-1.
- printToFile :(FILE *) aFilePrints a list of the objects in the objects by sending each individual object a printToFile: message. Returns the receiver.
- write :(NXTypedStream *) streamWrites the collection and all its elements to the typed stream stream. Returns the receiver.
- read :(NXTypedStream *) streamReads the collection and all its members from the typed stream stream. Returns the receiver.