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.
+new:(unsigned)nReturns a new empty collection, which can hold at least n elements without having to expand.
-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 freeContents] 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.
- (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 )anOffsetinsert: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 Offset out of bounds. exception is raised. The default handler aborts the process.
-insert:newObjectafter:oldObjectSearches for oldObject in the collection, and inserts newObject after oldObject, moving later elements if necessary to make room. Returns the receiver.
If oldObject is not in the collection, a Could not find object. exception is raised. The default handler aborts the process.
-insert:newObjectbefore:oldObjectFirst searches for oldObject in the collection, and inserts the newObject before oldObject. Returns the receiver.
If oldObject is not in the collection, a Could not find object exception is raised. The default handler aborts the process.
-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.
If anObject is not in the collection, a Could not find object exception is raised. The default handler aborts the process.
-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.
If anObject is not in the collection, a Could not find object exception is raised. The default handler aborts the process.
-at:(unsigned )anOffsetReturns the object at anOffset. The first object is at offset 0 and the last object is at size minus one.
If offset is greater than the last offset in the collection, a Index out of bounds exception is raised. The default handler aborts the process.
-at:(unsigned )anOffsetput: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.
Note: Method name for ICpak101 compatibility.
-removeAtIndex:(unsigned )anOffsetSame as removeAt:. Method name for Smalltalk compatibility.
-remove:oldObjectRemoves oldObject from the collection if oldObject is found, and returns oldObject. Otherwise returns nil.
Note: The remove: method of the OrdCltn class is implemented to remove an exact match. The Set class uses a match in the sense of isEqual: instead.
-remove:oldObjectifAbsent:exceptionBlockRemoves oldObject from the collection if oldObject is found, and returns oldObject. Otherwise evaluates exceptionBlock and returns its return value. For example, the method remove: is equivalent to the following :
Note: The remove: method of the OrdCltn class is implemented to remove an exact match. The Set class uses a match in the sense of isEqual: instead.[ aCltn remove: oldObject ifAbsent: { nil } ];
-do:aBlockEvaluates aBlock for each element in the collection and returns self. aBlock must be a block taking one object (element) as argument; the return value of the block is ignored by this method.
Often, the Block would, as a side-effect, modify a variable, as in:
int count = 0; [contents do: { :what | if (what == anObject) count++; }];
-do:aBlockuntil:(BOOL*)flagEvaluates aBlock for each element in the collection, or until the variable pointed to by flag becomes true, and returns self. aBlock must be a block taking one object (element) as argument; the return value of the block is ignored by this method.
Typically the Block will modify the variable flag when some condition holds:
BOOL found = NO; [contents do:{ :what | if (what == findObject) found=YES;} until:&found]; if (found) { ... }
-reverseDo:aBlockLike do: but specific to OrdCltn : works from the element at the last offset towards the element at offset 0.
-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.
- (BOOL)includes:anObjectThis method returns YES if anObject is in the collection (in the sense of isEqual:). It has therefore the same semantics as includes: of the Set class.
-findSTR:(STR )aStringReturns the first member whose string contents matches aString, 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 (which uses isSame, not isEqual:).
Note: To get the behavior of the method contains: of the Set class (which uses isEqual:), use findMatching: or includes:.
- (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.
-printOn:(IOD)aFilePrints a list of the objects in the objects by sending each individual object a printOn: message. Returns the receiver.
-fileOutOn:aFilerWrites the collection on aFiler. Returns the receiver.
-fileInFrom:aFilerReads a string object from aFiler. Returns the receiver.