CLASS
ObjSort
SUPERCLASS
ObjPak
DESCRIPTION
ObjSort instances are groups of objects that are kept in sorted order (by default, the first object is the smallest with respect to compare: ). Inserting and searching objects in such a sorted collection can be faster than using, say an ObjCltn object collection.
Creating An Instance
The method new creates an instance that sorts its elements with respect to compare:. The method newDictCompare sends dictCompare: messages to compare pairs of elements.
Adding Objects
Normally, you insert an object with the add: method. This method allows you to add an object to the collection, even when it is equal to an element in the collection (when the comparison method returns zero; because you can use a different method than compare: , this doesn't necessarily mean that isEqual: returns YES).
You can also choose not to add duplicate entries. The addNTest: method adds if the object was absent and returns a value that can be used to test whether the object was found or not. The filter: method frees a new entry when it's a duplicate. The replace: method always replaces duplicates (returning the object that was previously in the collection).
METHOD TYPES
Creation
new
newDictCompare
copy
deepCopy
emptyYourself
freeContents
free
Interrogation
size
isEmpty
eachElement
Comparing
hash
isEqual:
Adding
add:
addNTest:
filter:
replace:
Removing
remove:
Adding and Removing Contents
addContentsTo:
addContentsOf:
removeContentsOf:
removeContentsFrom:
Locating
find:
contains:
Printing
printToFile:
NextStep Archiving
write:
read:
METHODS
new
+ new
Returns a new instance that sorts its contents with respect to compare:.
newDictCompare
+ newDictCompare
Returns a new instance that sorts its contents with respect to dictCompare:.
copy
- copy
Returns a new copy of the object (without copying the elements).
deepCopy
- deepCopy
Returns a new copy of the object. The elements in the new copy are deep copies of the elements in the original object.
emptyYourself
- emptyYourself
Empties all the members of the object (without freeing them). Returns the receiver.
freeContents
- freeContents
Removes and frees the contents of the object, but doesn't free the object itself. Returns the receiver.
free
- free
Frees the object, but not its contents. Returns nil. Do :
aSort = [[aSort freeObjects] free];
if you want to free the object and its contents.
size
- (unsigned) size
Returns the number of elements in the object.
isEmpty
- (BOOL) isEmpty
Whether the number of elements is equal to zero.
eachElement
- eachElement
Returns a sequence of sorted elements. The first element in the sequence is the smallest with respect to the ordering.
aSeq = [aSort 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: aSort
Returns YES if aSort is an ObjSort instance, 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 receiver, keeping the contents of the object sorted. Duplicate entries are allowed. Returns the receiver.
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
If anObject compares equally to some object in the contents of the receiver, 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 that matches (when the compare method returns zero). Returns the removed entry, or nil if there is no matching entry.
Note:
Not implemented
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.
printToFile:
- printToFile: (FILE *) aFile
Prints a comma separated 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. Returns the receiver.