ObjSet Specification Sheet


ObjectPak Objective C Class Library

ObjSet

Inherits from:ObjPak

Class Description

ObjSet instances are sets of objects with no duplicate (in the sense of isEqual:) entries. The ObjDic 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. ObjSet 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: and replace: 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

Interrogation

Comparing

Adding

Removing

Adding and Removing Contents

Locating

Combining

Printing

NextStep Archiving

Methods



new

+ new

Returns a new empty set.



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 :

aSet = [[aSet freeObjects] 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.

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.



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.



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.



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.

If aCol is the same object as the receiver, it empties itself using emptyYourself and returns the receiver.



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.



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.



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.



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 ObjSet 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 ObjSet 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.



write:

- write :(NXTypedStream *) stream

Writes the set and all its elements to the typed stream stream. Returns the receiver.



read:

- read :(NXTypedStream *) stream

Reads the set and all its elements from the typed stream stream. The implementation of hash of an element may not change during unarchiving. Returns the receiver.