To make Sets correctly work, the objects have to implement a pair of comparison methods which must act in a coordinated way :
The message
is expected to report whether newElement is equal to oldElement.[newElement isEqual:oldElement]
The message
should return an integer which is equal for all objects for which isEqual: is true.[newElement hash]
Sets place all objects added to them into a hash table based on the results of sending the objects the hash message. Set assumes that, after being added to a set, objects, and their hash value, will not be changed. If any object does change, it will not be located properly in the set. The result of this is that the object will not be found or that it will be added to the set more than once.
+ newReturns a new empty set.
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 :
Otherwise, this method evalutes aBlock and returns the matching object (the object that was already in the set).
For example, the filter: method is equivalent to :
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.
For example, the method remove: is equivalent to :
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 isTrue, 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 an Object that isFalse. For example,
new:
+ new :(unsigned) n
Returns a new empty set, which can hold at least n elements.
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 set.
deepCopy
- deepCopy
Returns a new copy of the set. The elements in the new set are deep copies of the elements in the original set.
emptyYourself
- emptyYourself
Empties all the members of the set (without freeing them). Returns the receiver.
freeContents
- freeContents
Removes and frees all the members of the set, but doesn't free the set itself. Returns the receiver.
free
- free
Frees the set, but not its elements. Returns nil. Do :
if you want to free the set and its contents.
aSet = [[aSet freeContents] free];
size
- (unsigned) size
Returns the number of elements in the set.
isEmpty
- (BOOL) isEmpty
Whether the number of objects in the set is equal to zero.
idEmpty
- idEmpty
This method is like isEmpty but it returns the Object idTrue if the collection is empty, or idFalse otherwise.
eachElement
- eachElement
Returns a sequence of elements in the set.
aSeq = [aSet eachElement];
while ((anElement = [aSeq next])) {
/* do something */
}
aSeq = [aSeq free];
hash
- (unsigned) hash
Returns a hash value based on the receiver's address and the results of sending the hash message to the contents.
isEqual:
- (BOOL) isEqual : aSet
Returns YES if aSet is a set, 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 if it was not previously in the set, but doesn't inform the caller about the addition because the receiver is always returned.
addNTest:
- addNTest : anObject
Adds anObject if it was not previously in the set. Returns anObject if the addition takes place, otherwise returns nil.
filter:
- filter : anObject
The filter: method has a special purpose. If there is a matching object in the set, then anObject is freed, and the matching object is returned. Otherwise, anObject is added and returned.
add:ifDuplicate:
- add : anObject ifDuplicate : aBlock
Adds and returns anObject, if there was no duplicate previously in the set.
[ set add: anObject ifDuplicate: { [anObject free] }];
replace:
- replace : anObject
If a matching object is found, then anObject replaces that object, and the matching object is returned. If there is no matching object, anObject is added to the receiver, and nil is returned.
remove:
- remove : oldObject
Removes oldObject or the element which matches it using isEqual:. Returns the removed entry, or nil if there is no matching entry.
remove:ifAbsent:
- remove : oldObject ifAbsent : exceptionBlock
Removes oldObject or the element which matches it using isEqual:. Returns the removed entry, or return value of exceptionBlock if there is no matching entry.
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.
[ set 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.
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.
detect:
- detect : aBlock
This message returns the first element in the receiver for which aBlock evaluates to something that isTrue. For example, the following :
Returns nil if there's no element for which aBlock evaluates to something that isTrue.
[ aCollection detect: { id each | [each idEqual:anObject] } ];
detect:ifNone:
- detect : aBlock ifNone : noneBlock
This message returns the first element in the receiver for which aBlock evaluates to something that isTrue.
[ aCollection detect: {id e | [e idEqual: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 isTrue. 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 isTrue.
[ aCollection select: { id each | [each idEqual: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 something that isFalse.
[ aCollection reject: { id each | [each idEqual: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.
find:
- find : anObject
Returns any element in the receiver which isEqual: to anObject. Otherwise, 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 isEqual: and hash to decide whether the object is contained in the set).
includes:
- (BOOL) includes : anObject
This method is equivalent to contains:.
occurrencesOf:
- (unsigned) occurrencesOf : anObject
Returns 1 if anObject is in the receiver, otherwise returns 0. Implementation is in terms of the receiver's find: method (which uses isEqual: and hash).
intersection:
- intersection : aSet
Returns a new set which is the intersection of the receiver and aSet. The new set contains only those elements that were in both the receiver and aSet. The argument aSet need not be an actual Set instance, as long as it implements find: as sets do.
union:
- union : aSet
Returns a new set which is the union of the receiver and aSet. The new set returned has all the elements from both the receiver and aSet. The argument aSet need not be an actual Set instance, as long as it implements eachElement: as sets do.
difference:
- difference : aSet
Returns a new set which is the difference of the receiver and aSet. The new set returned has only those elements in the receiver that are not in aSet.
printToFile:
- printToFile :(FILE *) aFile
Prints a list of the objects in the set by sending each individual object a printToFile: message. Returns the receiver.
fileOutOn:
- fileOutOn : aFiler
Writes out non-nil objects in the Set on aFiler. Returns the receiver.