--- name: "OrdCltn" section: "3" platform: "linux" package: "objc-poc" version: "3.1.3-2" release: "Debian 2.2 (Potato)" platforms: ["linux"] url: "https://new.carta.tech/OrdCltn" --- # OrdCltn(3) ## OrdCltn **Inherits from:** Cltn ## Class Description **OrdCltn** (alias **OrderedCollection** ) instances are ordered collections of objects : you can access, add or remove elements at a specified offset in the array of elements. **OrdCltn** takes care of the memory allocation issues to hold the objects. There can be no **nil** entries between the first (at offset 0) and last elements (at **size** minus one). For this reason, all methods that add objects refuse to add **nil** 's. When entries are added or removed, the offsets of the remaining entries change. Offsets into collections are traditionally unsigned integers. Methods that return an offset, e.g., **offsetOf:** and **lastOffset** return a value of (unsigned)-1 to indicate that an object has not been found. There are many methods for adding or inserting members into a collection. Although members may be added at any point in the collection, they are generally added at the end using **add:** . A member may be searched for using either the **find:** or **findMatching:** method. In the first case, the member in the collection must be an exact match. In the second case, the member must match in the sense of the **isEqual:** method. ## Method types **Creation** \* new\ \* new:\ \* with:\ \* with:with:\ \* add:\ \* copy\ \* deepCopy\ \* emptyYourself\ \* freeContents\ \* free **Interrogation** \* size\ \* isEmpty\ \* lastOffset\ \* eachElement\ \* firstElement\ \* lastElement **Comparing** \* isEqual: **Adding** \* add:\ \* addFirst:\ \* addLast:\ \* addIfAbsent:\ \* addIfAbsentMatching: **Insertion** \* at:insert:\ \* insert:after:\ \* insert:before: **Relative Accessing** \* after:\ \* before:\ \* at:\ \* at:put: **Removing** \* removeFirst\ \* removeLast\ \* removeAt:\ \* removeAtIndex:\ \* 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:\ \* collect:\ \* count: **Making elements perform** \* elementsPerform:\ \* elementsPerform:with:\ \* elementsPerform:with:with:\ \* elementsPerform:with:with:with: **Do Blocks** \* do:\ \* do:until:\ \* reverseDo: **Locating** \* find:\ \* findMatching:\ \* includes:\ \* findSTR:\ \* contains:\ \* offsetOf: **Printing** \* printOn: **Archiving** \* fileOutOn:\ \* fileInFrom: ## Methods new \+ **new** Returns a new empty collection. new: \+ **new** :(unsigned) *n* Returns a new empty collection, which can hold at least *n* elements without having to expand. copy \- **copy** Returns a new copy of the collection. deepCopy \- **deepCopy** Returns a new copy of the collection. The members in the new collection are deep copies of the members in the original collection. emptyYourself \- **emptyYourself** Removes all the members of the collection (without freeing them). Returns the receiver. freeContents \- **freeContents** Removes and frees all the members of the receiver, but doesn't free the receiver itself. Returns the receiver. free \- **free** Frees the collection, but not its contents. Returns **nil** . Do : aCltn = \[\[aCltn freeContents\] free\];\ if you want to free the collection and its contents. size \- ( unsigned ) **size** Returns the number of objects in the collection. isEmpty \- ( BOOL ) **isEmpty** Whether the number of objects in the collection is equal to zero. lastOffset \- ( unsigned ) **lastOffset** Returns the offset of the last element. If there are no elements it returns (unsigned)-1. eachElement \- **eachElement** Returns a sequence of the elements in the collection. aSeq = \[aCltn eachElement\];\ while ((anElement = \[aSeq next\])) {\ /\* do something \*/\ }\ aSeq = \[aSeq free\];\ firstElement \- **firstElement** Returns the first element in the collection. If there are no elements, returns **nil** . lastElement \- **lastElement** Returns the last element in the collection. If there are no elements, returns **nil** . isEqual: \- ( BOOL ) **isEqual** : *aCltn* Returns YES if *aCltn* is a collection, 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 collection as the last element and returns the receiver. addFirst: \- **addFirst** : *newObject* Adds *newObject* as the first (zero-th) element of the collection. Returns the receiver. Any elements at this offset or higher are relocated to the next higher offset to make room. addLast: \- **addLast** : *newObject* Identical to the **add:** method. addIfAbsent: \- **addIfAbsent** : *anObject* Adds *anObject* to the collection only if the collection does not have that same object, i.e., one that is pointer equal. Returns the receiver. addIfAbsentMatching: \- **addIfAbsentMatching** : *anObject* Adds *anObject* to the collection only if the collection does not have a matching object, i.e., one that is **isEqual:** . Returns the receiver. at:insert: \- **at** :(unsigned ) *anOffset* **insert** : *anObject* Inserts *anObject* at offset *anOffset* and returns the receiver. Any elements at this offset or higher are relocated to the next higher offet to make room. If *anOffset* is greater than the size of the collection, an *Offset out of bounds.* exception is raised. The default handler aborts the process. insert:after: \- **insert** : *newObject* **after** : *oldObject* Searches for *oldObject* in the collection, and inserts *newObject* after *oldObject* , moving later elements if necessary to make room. Returns the receiver. If *oldObject* is not in the collection, a *Could not find object.* exception is raised. The default handler aborts the process. insert:before: \- **insert** : *newObject* **before** : *oldObject* First searches for *oldObject* in the collection, and inserts the *newObject* before *oldObject* . Returns the receiver. If *oldObject* is not in the collection, a *Could not find object* exception is raised. The default handler aborts the process. after: \- **after** : *anObject* Searches for *anObject* in the collection and, if found, returns the next object. If *anObject* is the last element in the array, returns **nil** . If *anObject* is not in the collection, a *Could not find object* exception is raised. The default handler aborts the process. before: \- **before** : *anObject* Searches for *anObject* in the collection and, if found, returns the object before it. If *anObject* is the first element in the array, returns **nil** . If *anObject* is not in the collection, a *Could not find object* exception is raised. The default handler aborts the process. at: \- **at** :(unsigned ) *anOffset* Returns the object at *anOffset* . The first object is at offset 0 and the last object is at **size** minus one. If *offset* is greater than the last offset in the collection, a *Index out of bounds* exception is raised. The default handler aborts the process. at:put: \- **at** :(unsigned ) *anOffset* **put** : *anObject* Replaces the object at *anOffset* with *anObject* and returns the old member at *anOffset* . Generates an error if *anOffset* is greater than the size of the collection. Returns **nil** if *anObject* is **nil** . removeFirst \- **removeFirst** Removes the first element. Returns that element or **nil** if there are no elements. removeLast \- **removeLast** Removes the last element. Returns that element or **nil** if there are no elements. removeAt: \- **removeAt** :(unsigned ) *anOffset* Removes the object at *anOffset* . When an object is removed, the remaining elements are adjusted so that there are no **nil** entries between the first and last element. This adjustment shrinks the collection and changes the offset of the entries. Returns the object removed. **Note:** Method name for ICpak101 compatibility. removeAtIndex: \- **removeAtIndex** :(unsigned ) *anOffset* Same as **removeAt:** . Method name for Smalltalk compatibility. remove: \- **remove** : *oldObject* Removes *oldObject* from the collection if *oldObject* is found, and returns *oldObject* . Otherwise returns **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. remove:ifAbsent: \- **remove** : *oldObject* **ifAbsent** : *exceptionBlock* Removes *oldObject* from the collection if *oldObject* is found, and returns *oldObject* . Otherwise evaluates *exceptionBlock* and returns its return value. For example, the method **remove:** is equivalent to the following : \[ aCltn 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. do: \- **do** : *aBlock* Evaluates *aBlock* for each element in the collection and returns **self** . *aBlock* must be a block taking one object (element) as argument; the return value of the block is ignored by this method. Often, the Block would, as a side-effect, modify a variable, as in: int count = 0;\ \[contents do: { :what \| if (what == anObject) count++; }\];\ do:until: \- **do** : *aBlock* **until** :(BOOL\*) *flag* Evaluates *aBlock* for each element in the collection, or until the variable pointed to by *flag* becomes true, and returns **self** . *aBlock* must be a block taking one object (element) as argument; the return value of the block is ignored by this method. Typically the Block will modify the variable *flag* when some condition holds: BOOL found = NO;\ \[contents do:{ :what \| if (what == findObject) found=YES;} until:&found\];\ if (found) { ... }\ reverseDo: \- **reverseDo** : *aBlock* Like **do:** but specific to **OrdCltn** : works from the element at the last offset towards the element at offset 0. find: \- **find** : *anObject* Returns the first member which is the same as *anObject* , i.e., which is pointer equal. If none is found, returns **nil** . findMatching: \- **findMatching** : *anObject* Returns the first member which matches *anObject* , i.e., using **isEqual:** for comparison. If none is found, returns **nil** . includes: \- ( BOOL ) **includes** : *anObject* This method returns YES if *anObject* is in the collection (in the sense of **isEqual:** ). It has therefore the same semantics as **includes:** of the **Set** class. findSTR: \- **findSTR** :(STR ) *aString* Returns the first member whose string contents matches *aString* , using the **isEqualSTR:** method for comparison. If none is found, 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 **isSame** , not **isEqual:** ). **Note:** To get the behavior of the method **contains:** of the Set class (which uses **isEqual:** ), use **findMatching:** or **includes:** . offsetOf: \- ( unsigned ) **offsetOf** : *anObject* Searches for *anObject* in the contents and returns the offset of the **first** pointer equal object it finds. Otherwise, returns (unsigned)-1. If *anObject* is **nil** , also returns (unsigned)-1. printOn: \- **printOn** :(IOD) *aFile* Prints a list of the objects in the objects by sending each individual object a **printOn:** message. Returns the receiver. fileOutOn: \- **fileOutOn** : *aFiler* Writes the collection on *aFiler* . Returns the receiver. fileInFrom: \- **fileInFrom** : *aFiler* Reads a string object from *aFiler* . Returns the receiver.