--- name: "ObjSort" section: "3" platform: "linux" package: "objpak-dev" version: "1.1.1-1" release: "Debian 1.3 (Bo)" platforms: ["linux"] url: "https://new.carta.tech/ObjSort" --- # ObjSort(3) ## 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.