--- name: "ObjCltn" section: "3" platform: "linux" package: "objpak-dev" version: "1.1.1-1" release: "Debian 1.3 (Bo)" platforms: ["linux"] url: "https://new.carta.tech/ObjCltn" --- # ObjCltn(3) ## CLASS **ObjCltn** ## SUPERCLASS ObjPak ## DESCRIPTION **ObjCltn** instances are ordered collections of objects : you can access, add or remove elements at a specified offset in the array of elements. **ObjCltn** 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\ copy\ deepCopy\ emptyYourself\ freeContents\ free\ **Interrogation** size\ isEmpty\ lastOffset\ eachElement\ firstElement\ lastElement\ **Comparing** hash\ 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:\ remove:\ **Adding and Removing Contents** addContentsTo:\ addContentsOf:\ removeContentsOf:\ removeContentsFrom:\ **Locating** find:\ findMatching:\ findSTR:\ contains:\ offsetOf:\ **Printing** printToFile:\ **NextStep Archiving** write:\ read:\ ## METHODS **new** \+ **new** Returns a new empty collection. **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 freeObjects\] 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.** **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:** *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 error is generated. **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. If *oldObject* is not found, an error is generated. Returns the receiver. **insert:before:** \- **insert:** *newObject* **before:** *oldObject* First searches for *oldObject* in the collection, and inserts the *newObject* before *oldObject.* If *oldObject* is not found, an error is generated. Returns the receiver. **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.** Generates an error if *anObject* cannot be found. **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.** Generates an error if *anObject* cannot be found. **at:** \- **at:** (unsigned ) *anOffset* Returns 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. **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. **remove:** \- **remove:** *oldObject* Removes *oldObject* from the collection if *oldObject* is found, and returns *oldObject.* Otherwise returns **nil.** **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 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.** **findSTR:** \- **findSTR:** (STR ) *strValue* Returns the first member whose string contents matches *strValue* , 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. **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. **printToFile:** \- **printToFile:** (FILE \*) *aFile* Prints a list of the objects in the objects by sending each individual object a **printToFile:** message. Returns the receiver. **write:** \- **write:** (NXTypedStream \*) *stream* Writes the collection and all its elements to the typed stream *stream.* Returns the receiver. **read:** \- **read:** (NXTypedStream \*) *stream* Reads the collection and all its members from the typed stream *stream.* Returns the receiver.