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.
This (factory) method has the same name as the instance method add: and can be used as follows, in circumstances when the user does not want to allocate a collection unless it is actually used :
If anOffset is greater than the size of the collection, an Offset out of bounds. exception is raised. The default handler aborts the process.
If oldObject is not in the collection, a Could not find object. exception is raised. The default handler aborts the process.
If oldObject is not in the collection, a Could not find object exception is raised. The default handler aborts the process.
If anObject is not in the collection, a Could not find object exception is raised. The default handler aborts the process.
If anObject is not in the collection, a Could not find object exception is raised. The default handler aborts the process.
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.
Note: Method name for ICpak101 compatibility.
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.
See also: addAll:
If aCol is the same object as the receiver, it empties itself using emptyYourself and returns the receiver.
Evaluates noneBlock if there's no element for which aBlock evaluates to something that is non-nil, and returns the return value of that block. For example,
This message will return a subset of the receiver containing all elements for which testBlock evaluates to nil. For example,
Often, the Block would, as a side-effect, modify a variable, as in:
Typically the Block will modify the variable flag when some condition holds:
Note: To get the behavior of the method contains: of the Set class (which uses isEqual:), use findMatching: or includes:.
new:
+ new :(unsigned) n
Returns a new empty collection, which can hold at least n elements without having to expand.
with:
+ with :(int) nArgs,...
Returns a new object with nArgs elements. For example,
creates a collection and adds anObject and otherObject to it. In a similar way, Set or Tree instances can be created like this.
id myCollection = [OrdCltn with:2,anObject,otherObject];
with:with:
+ with : firstObject with : nextObject
This method is equivalent to with: 2,firstObject,nextObject.
add:
+ add : firstObject
This method is equivalent to with: 1,firstObject.
This shows that creation of the collection is delayed until it is actually needed. If the collection already exists, objects are simply added, using the instance method add:.
myCollection = [ (myCollection)?myCollection:OrdCltn add:myObject ];
copy
- copy
Returns a new copy of the collection.
deepCopy
- deepCopy
Returns a new copy of the collection. The members in the new collection are deep copies of the members in the original collection.
emptyYourself
- emptyYourself
Removes all the members of the collection (without freeing them). Returns the receiver.
freeContents
- freeContents
Removes and frees all the members of the receiver, but doesn't free the receiver itself. Returns the receiver.
free
- free
Frees the collection, but not its contents. Returns nil. Do :
if you want to free the collection and its contents.
aCltn = [[aCltn freeContents] free];
size
- (unsigned) size
Returns the number of objects in the collection.
isEmpty
- (BOOL) isEmpty
Whether the number of objects in the collection is equal to zero.
lastOffset
- (unsigned) lastOffset
Returns the offset of the last element. If there are no elements it returns (unsigned)-1.
eachElement
- eachElement
Returns a sequence of the elements in the collection.
aSeq = [aCltn eachElement];
while ((anElement = [aSeq next])) {
/* do something */
}
aSeq = [aSeq free];
firstElement
- firstElement
Returns the first element in the collection. If there are no elements, returns nil.
lastElement
- lastElement
Returns the last element in the collection. If there are no elements, returns nil.
isEqual:
- (BOOL) isEqual : aCltn
Returns 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:
- add : anObject
Adds anObject to the collection as the last element and returns the receiver.
addFirst:
- addFirst : newObject
Adds 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:
- addLast : newObject
Identical to the add: method.
addIfAbsent:
- addIfAbsent : anObject
Adds 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:
- addIfAbsentMatching : anObject
Adds anObject to the collection only if the collection does not have a matching object, i.e., one that is isEqual:. Returns the receiver.
at:insert:
- at :(unsigned ) anOffset insert : anObject
Inserts 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.
insert:after:
- insert : newObject after : oldObject
Searches for oldObject in the collection, and inserts newObject after oldObject, moving later elements if necessary to make room. Returns the receiver.
insert:before:
- insert : newObject before : oldObject
First searches for oldObject in the collection, and inserts the newObject before oldObject. Returns the receiver.
after:
- after : anObject
Searches for anObject in the collection and, if found, returns the next object. If anObject is the last element in the array, returns nil.
before:
- before : anObject
Searches for anObject in the collection and, if found, returns the object before it. If anObject is the first element in the array, returns nil.
at:
- at :(unsigned ) anOffset
Returns the object at anOffset with anObject and returns the old member at anOffset.
at:put:
- at :(unsigned ) anOffset put : anObject
Replaces 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.
removeFirst
- removeFirst
Removes the first element. Returns that element or nil if there are no elements.
removeLast
- removeLast
Removes the last element. Returns that element or nil if there are no elements.
removeAt:
- removeAt :(unsigned ) anOffset
Removes 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.
removeAtIndex:
- removeAtIndex :(unsigned ) anOffset
Same as removeAt:. Method name for Smalltalk compatibility.
remove:
- remove : oldObject
Removes oldObject from the collection if oldObject is found, and returns oldObject. Otherwise returns nil.
remove:ifAbsent:
- remove : oldObject ifAbsent : exceptionBlock
Removes 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 } ];
includesAllOf:
- (BOOL) includesAllOf : aCol
Answer whether all the elements of aCol are in the receiver, by sending includes: for each individual element.
includesAnyOf:
- (BOOL) includesAnyOf : aCol
Answer whether any element of aCol is in the receiver, by sending includes: for each individual element.
addContentsTo:
- addContentsTo : aCol
Adds 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:
- addContentsOf : aCol
Adds 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.
addAll:
- addAll : aCol
This method is equivalent to addContentsOf:.
removeContentsOf:
- removeContentsOf : aCol
Removes 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.
removeContentsFrom:
- removeContentsFrom : aCol
Removes 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.
removeAll:
- removeAll : aCol
This method is equivalent to removeContentsOf:.
asSet
- asSet
Creates a Set instance and adds the contents of the object to the set.
asOrdCltn
- asOrdCltn
Creates a OrdCltn instance and adds the contents of the object to the set.
detect:
- detect : aBlock
This message returns the first element in the receiver for which aBlock evaluates to something that is non-nil . For example, the following :
Returns nil if there's no element for which aBlock evaluates to something that non-nil.
[ aCltn detect: { :each | [each isEqual:anObject] } ];
detect:ifNone:
- detect : aBlock ifNone : noneBlock
This message returns the first element in the receiver for which aBlock evaluates to something that is non-nil.
[ aCltn detect: { :e | [e isEqual:anObject]} ifNone: {anObject} ];
select:
- select : testBlock
This message will return a subset of the receiver containing all elements for which testBlock evaluates to an Object that is non-nil. For example,
Returns a new empty instance of the same class as the receiver, if there's no element for which testBlock evaluates to something that is non-nil.
[ aCltn select: { :each | [each isEqual:anObject] } ];
reject:
- reject : testBlock
Complement of select:
Returns a new empty instance of the same class as the receiver, if there's no element for which testBlock evaluates to nil.
[ aCltn reject: { :each | [each isEqual:anObject] } ];
collect:
- collect : transformBlock
This message creates and returns a new collection of the same size and type as the receiver. The elements are the result of performing transformBlock on each element in the receiver (elements for which the Block would return nil are filtered out).
count:
- (unsigned) count : aBlock
Evaluate aBlock with each of the receiver's elements as the argument. Return the number that answered a non-nil value.
elementsPerform:
- elementsPerform :(SEL) aSelector
Send aSelector to all objects in the collection, starting from the object at offset 0. For Stepstone compatibility. Producer uses this.
elementsPerform:with:
- elementsPerform :(SEL) aSelector with : anObject
Send aSelector to all objects in the collection, starting from the object at offset 0. For Stepstone compatibility. Producer uses this.
elementsPerform:with:with:
- elementsPerform :(SEL) aSelector with : anObject with : otherObject
Send aSelector to all objects in the collection, starting from the object at offset 0. For Stepstone compatibility. Producer uses this.
elementsPerform:with:with:with:
- elementsPerform :(SEL) aSelector with : anObject with : otherObject with : thirdObj
Send aSelector to all objects in the collection, starting from the object at offset 0. For Stepstone compatibility. ICpak201 uses this.
do:
- do : aBlock
Evaluates 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.
int count = 0;
[contents do: { :what | if (what == anObject) count++; }];
do:until:
- do : aBlock until :(BOOL*) flag
Evaluates 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.
BOOL found = NO;
[contents do:{ :what | if (what == findObject) found=YES;} until:&found];
if (found) { ... }
reverseDo:
- reverseDo : aBlock
Like do: but specific to OrdCltn : works from the element at the last offset towards the element at offset 0.
find:
- find : anObject
Returns the first member which is the same as anObject, i.e., which is pointer equal. If none is found, returns nil.
findMatching:
- findMatching : anObject
Returns the first member which matches anObject, i.e., using isEqual: for comparison. If none is found, returns nil.
includes:
- (BOOL) includes : anObject
This 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:
- findSTR :(STR ) strValue
Returns the first member whose string contents matches strValue, using the isEqualSTR: method for comparison. If none is found, returns nil.
contains:
- (BOOL) contains : anObject
Returns YES if the receiver contains anObject. Otherwise, returns NO. Implementation is in terms of the receiver's find: method (which uses isSame, not isEqual:).
offsetOf:
- (unsigned) offsetOf : anObject
Searches 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:
- printOn :(IOD) aFile
Prints a list of the objects in the objects by sending each individual object a printOn: message. Returns the receiver.
fileOutOn:
- fileOutOn : aFiler
Writes the collection on aFiler. Returns the receiver.
fileInFrom:
- fileInFrom : aFiler
Reads a string object from aFiler. Returns the receiver.