set(3) UNIX System V (Apr 20, 1999) set(3)
Set
Inherits from:
Cltn
Class Description
Set instances are sets of objects with no duplicate (in the
sense of isEqual: ) entries. The Dictionary class provides
a key-value based interface to sets, and may sometimes be
more convenient to use.
To make Sets correctly work, the objects have to implement a
pair of comparison methods which must act in a coordinated
way :
The message
[newElement isEqual:oldElement]
is expected to report whether newElement is equal to
oldElement .
The message
[newElement hash]
should return an integer which is equal for all objects for
which isEqual: is true.
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.
Adding Objects
The methods add: , addNTest: , filter: , replace: and
add:ifDuplicate: are used to add objects to a set. The
difference between these methods is the procedure used in
adding, how duplicates are handled and what value is
returned.
Method types
Creation
* new
* new:
* with:
* with:with:
Page 1 (printed 6/28/99)
set(3) UNIX System V (Apr 20, 1999) set(3)
* add:
* copy
* deepCopy
* emptyYourself
* freeContents
* free
Interrogation
* size
* isEmpty
* eachElement
Comparing
* isEqual:
Adding
* add:
* addNTest:
* filter:
* add:ifDuplicate:
* replace:
Removing
* remove:
* remove:ifAbsent:
Testing Contents
* includesAllOf:
* includesAnyOf:
Adding and Removing Contents
* addAll:
* addContentsOf:
* addContentsTo:
* removeAll:
* removeContentsFrom:
* removeContentsOf:
Combining
* intersection:
* union:
* difference:
Converting
* asSet
* asOrdCltn
Using Blocks
* detect:
* detect:ifNone:
* select:
* reject:
Page 2 (printed 6/28/99)
set(3) UNIX System V (Apr 20, 1999) set(3)
* collect:
* count:
Making elements perform
* elementsPerform:
* elementsPerform:with:
* elementsPerform:with:with:
* elementsPerform:with:with:with:
Do Blocks
* do:
* do:until:
Locating
* find:
* contains:
* includes:
* occurrencesOf:
Printing
* printOn:
Archiving
* fileOutOn:
* fileInFrom:
* awakeFrom:
Methods
new
+ new
Returns a new empty set.
new:
+ new :(unsigned) n
Returns a new empty set, which can hold at least n elements.
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
Page 3 (printed 6/28/99)
set(3) UNIX System V (Apr 20, 1999) set(3)
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 :
set = [[set freeContents] free];
if you want to free the set and its contents.
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.
eachElement
- eachElement
Returns a sequence of elements in the set.
seq = [set eachElement];
while ((anElement = [aSeq next])) {
/* do something */
}
aSeq = [aSeq free];
isEqual:
- ( BOOL ) isEqual : set
Returns YES if set is a set, if set has the same number of
elements as the receiver, and if each member of the contents
of set is contained in the receiver's contents.
add:
- add : anObject
Adds anObject if it was not previously in the set, but
Page 4 (printed 6/28/99)
set(3) UNIX System V (Apr 20, 1999) set(3)
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.
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 :
[ 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.
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.
Page 5 (printed 6/28/99)
set(3) UNIX System V (Apr 20, 1999) set(3)
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.
For example, the method remove: is equivalent to :
[ set remove: oldObject ifAbsent: { 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.
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 ).
printOn:
- printOn :(IOD) aFile
Prints a list of the objects in the set by sending each
individual object a printOn: message. Returns the
receiver.
fileOutOn:
Page 6 (printed 6/28/99)
set(3) UNIX System V (Apr 20, 1999) set(3)
- fileOutOn : aFiler
Writes out non-nil objects in the Set on aFiler . Returns
the receiver.
fileInFrom:
- fileInFrom : aFiler
Reads in objects from aFiler . Returns the receiver, which
is a set that is not yet usable (until the set gets the
awakeFrom: message).
awakeFrom:
- awakeFrom : aFiler
Rehashes the contents of the set, which was previously read
from aFiler by the fileInFrom: method. The hash-values of
the objects are possibly process or architecture dependent,
so they are not stored on the filer. Rather, awakeFrom:
recomputes the values.
Page 7 (printed 6/28/99)
