ObjCltn Specification Sheet

ObjectPak Objective C Class Library

ObjCltn

Inherits from:ObjPak

Class 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.