--- name: "SortCltn" section: "3" platform: "linux" package: "objc-poc" version: "3.1.3-2" release: "Debian 2.2 (Potato)" platforms: ["linux"] url: "https://new.carta.tech/SortCltn" --- # SortCltn(3) ## SortCltn **Inherits from:** Cltn ## Class Description **SortCltn** (alias **SortedCollection** ) instances are groups of objects that are kept in sorted order in a tree (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 **OrdCltn** 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. Finally, the method **sortBy::** creates a SortCltn that will sort its contents with respect to an arbitrary Block. ## 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). ## Sorting collections One use of **SortCltn** instances, is to sort collections of objects. For example, aSortCltn = \[\[SortCltn new\] addAll:aCltn\];\ will sequence of the contents of *aCltn* and will add the members of the collection to a new SortCltn instance. This is equivalent to sorting the collection. To obtain a sorted **OrdCltn** instance (as opposed to a **SortCltn** ), simply convert back like this, aCltn = \[\[OrdCltn new\] addAll:aSortCltn\];\ To filter out duplicate entries, it's also possible to insert a Set instance in the conversion process. ## Method types **Creation** \* new\ \* new:\ \* newDictCompare\ \* sortBy:\ \* sortBlock:\ \* newCmpSel:\ \* with:\ \* with:with:\ \* add:\ \* copy\ \* deepCopy\ \* emptyYourself\ \* freeContents\ \* free **Interrogation** \* size\ \* isEmpty\ \* eachElement **Comparing** \* hash\ \* isEqual: **Adding** \* add:\ \* addNTest:\ \* filter:\ \* replace: **Removing** \* remove: **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:\ \* collect:\ \* count: **Making elements perform** \* elementsPerform:\ \* elementsPerform:with:\ \* elementsPerform:with:with:\ \* elementsPerform:with:with:with: **Do Blocks** \* do:\ \* do:until: **Locating** \* find:\ \* contains: **Printing** \* printOn: **Archiving** \* fileOutOn:\ \* fileInFrom: ## Methods new \+ **new** Returns a new instance that sorts its contents with respect to **compare:** . new: \+ **new** :(unsigned) *n* For this class, this method does not differ from **new** . newDictCompare \+ **newDictCompare** Returns a new instance that sorts its contents with respect to **dictCompare:** . sortBy: \+ **sortBy** : *sortBlock* Returns a new instance that sorts its contents with respect to *sortBlock* . This block should take two objects *a* and *b* as argument, and return a positive value if *a* is greater than *b* , or zero if *a* and *b* are equal, and a negative value if *a* is less than *b* . id c;\ int r;\ c = \[SortCltn sortBy:{ :a:b \| \[a compare:b\] }\];\ sortBlock: \+ **sortBlock** : *sortBlock* Same as **sortBy:** . **Note:** There is a SortedCollection method with a similar name in *Squeak* . newCmpSel: \+ **newCmpSel** :(SEL) *aSel* For backwards compatibility only. **sortBy:** provides a more powerful mechanism to sort given an arbitrary sort block. 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 freeContents\] 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 **SortCltn** 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 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. printOn: \- **printOn** :(IOD) *aFile* Prints a comma separated list of the objects in the set by sending each individual object a **printOn:** message. Returns the receiver. fileOutOn: \- **fileOutOn** : *aFiler* Writes the tree and all its elements to *aFiler* . Returns the receiver. fileInFrom: \- **fileInFrom** : *aFiler* Reads the tree and all its elements from *aFiler* . Returns the receiver.