.TH "cltn" 3 "Oct 12, 2003"
.SH Cltn
.PP
.B
Inherits from:

Object
.SH Class Description
.PP
This is an abstract superclass for collection classes\&.
.PP
It is useful for implementing functionality, that is inherited by such classes as:
.RS 3
.br
* OrdCltn (Collection)
.br
* Set
.br
* Stack
.br
* SortCltn (Tree)
.RE
.PP
In addition, this class is necessary for compatibility with Stepstone\&'s ICpak101\&.
.SH Method types
.PP 
.B
Testing Contents
.RS 3
.br
* includesAllOf:
.br
* includesAnyOf:
.RE
.PP 
.B
Adding and Removing Contents
.RS 3
.br
* addAll:
.br
* addContentsOf:
.br
* addContentsTo:
.br
* removeAll:
.br
* removeContentsFrom:
.br
* removeContentsOf:
.RE
.PP 
.B
Combining
.RS 3
.br
* intersection:
.br
* union:
.br
* difference:
.RE
.PP 
.B
Converting
.RS 3
.br
* asSet
.br
* asOrdCltn
.RE
.PP 
.B
Using Blocks
.RS 3
.br
* detect:
.br
* detect:ifNone:
.br
* select:
.br
* reject:
.br
* collect:
.br
* count:
.RE
.PP 
.B
Making elements perform
.RS 3
.br
* elementsPerform:
.br
* elementsPerform:with:
.br
* elementsPerform:with:with:
.br
* elementsPerform:with:with:with:
.RE
.PP 
.B
Do Blocks
.RS 3
.br
* do:
.br
* do:until:
.RE
.SH Methods
.PP 
with:
.RS 1
+
.B
with
:(int)
.I
nArgs,\&.\&.\&.
.RE
.PP
Returns a new object with 
.I
nArgs
elements\&.  For example,
.RS 3

id aCltn = [OrdCltn with:2,anObject,otherObject];
.br

.RE
.PP
creates a collection and adds 
.I
anObject
and 
.I
otherObject
to it\&.  In a similar way, 
.B
Set
or 
.B
SortCltn
instances can be created like this\&.
.PP 
with:with:
.RS 1
+
.B
with
:
.I
firstObject
.B
with
:
.I
nextObject
.RE
.PP
This method is equivalent to 
.B
with:
2,
.I
firstObject
,
.I
nextObject
\&. 
.PP 
add:
.RS 1
+
.B
add
:
.I
firstObject
.RE
.PP
This method is equivalent to 
.B
with:
1,
.I
firstObject
\&. 
.PP
This (factory) method has the same name as the instance method 
.B
add:
and can be used as follows, in circumstances when the user does not want to allocate a collection unless it is actually used :
.RS 3

aCltn = [ (aCltn)?aCltn:OrdCltn add:myObject ];
.br

.RE
.PP
This shows that creation of the collection is delayed until it is actually needed\&.  If the collection already exists, objects are simply added, using the instance method 
.B
add:
\&.
.PP 
includesAllOf:
.RS 1
- (
BOOL
)
.B
includesAllOf
:
.I
aCltn
.RE
.PP
Answer whether all the elements of 
.I
aCltn
are in the receiver, by sending 
.B
includes:
for each individual element\&.
.PP 
includesAnyOf:
.RS 1
- (
BOOL
)
.B
includesAnyOf
:
.I
aCltn
.RE
.PP
Answer whether any element of 
.I
aCltn
is in the receiver, by sending 
.B
includes:
for each individual element\&.
.PP 
addAll:
.RS 1
-
.B
addAll
:
.I
aCltn
.RE
.PP
Adds each member of 
.I
aCltn
to the receiver\&.  If 
.I
aCltn
is 
.B
nil
, no action is taken\&.  The argument 
.I
aCltn
need not be a collection, so long as it responds to 
.B
eachElement
in the same way as collections do\&.  Returns the receiver\&.
.PP
.B
Note:

If 
.I
aCltn
is the same object as the receiver, a 
.B
addYourself
message is sent to the object\&.
.PP 
addContentsOf:
.RS 1
-
.B
addContentsOf
:
.I
aCltn
.RE
.PP
This method is equivalent to 
.B
addAll:
and is provided for Stepstone ICpak101 compatibility\&.
.PP 
addContentsTo:
.RS 1
-
.B
addContentsTo
:
.I
aCltn
.RE
.PP
This method is equivalent to 
.B
addAll:
, but with argument and receiver interchanged, and is provided for Stepstone ICpak101 compatibility\&.
.PP 
removeAll:
.RS 1
-
.B
removeAll
:
.I
aCltn
.RE
.PP
Removes all of the members of 
.I
aCltn
from the receiver\&. The argument 
.I
aCltn
need not be a collection, as long as it responds to 
.B
eachElement
as collections do\&.  Returns the receiver\&. 
.PP
.B
Note:

If 
.I
aCltn
is the same object as the receiver, it empties itself using 
.B
emptyYourself
and returns the receiver\&.
.PP 
removeContentsFrom:
.RS 1
-
.B
removeContentsFrom
:
.I
aCltn
.RE
.PP
This method is equivalent to 
.B
removeAll:
, and is provided for compatibility with Stepstone ICpak101\&.
.PP 
removeContentsOf:
.RS 1
-
.B
removeContentsOf
:
.I
aCltn
.RE
.PP
This method is equivalent to 
.B
removeAll:
, and is provided for compatibility with Stepstone ICpak101\&.
.PP 
intersection:
.RS 1
-
.B
intersection
:
.I
bag
.RE
.PP
Returns a new Collection which is the intersection of the receiver and 
.I
bag
\&.  The new Collection contains only those elements that were in both the receiver and 
.I
bag
\&.  The argument 
.I
bag
need not be an actual 
.B
Set
or 
.B
Bag
instance, as long as it implements 
.B
find:
as Sets do\&.
.PP 
union:
.RS 1
-
.B
union
:
.I
bag
.RE
.PP
Returns a new Collection which is the union of the receiver and 
.I
bag
\&.  The new Collection returned has all the elements from both the receiver and 
.I
bag
\&.  The argument 
.I
bag
need not be an actual 
.B
Set
or 
.B
Bag
instance, as long as it implements 
.B
eachElement:
as Sets and Bags do\&.
.PP 
difference:
.RS 1
-
.B
difference
:
.I
bag
.RE
.PP
Returns a new Collection which is the difference of the receiver and 
.I
bag
\&.  The new Collection returned has only those elements in the receiver that are not in 
.I
bag
\&.
.PP 
asSet
.RS 1
-
.B
asSet
.RE
.PP
Creates a 
.B
Set
instance and adds the contents of the object to the set\&.
.PP 
asOrdCltn
.RS 1
-
.B
asOrdCltn
.RE
.PP
Creates a 
.B
OrdCltn
instance and adds the contents of the object to the set\&.
.PP 
detect:
.RS 1
-
.B
detect
:
.I
aBlock
.RE
.PP
This message returns the first element in the receiver for which 
.I
aBlock
evaluates to something that is non-nil \&.  For example, the following :
.RS 3

[ aCltn detect: { :each | [each isEqual:anObject] } ];
.br

.RE
.PP
Returns 
.B
nil
if there\&'s no element for which 
.I
aBlock
evaluates to something that non-nil\&.
.PP 
detect:ifNone:
.RS 1
-
.B
detect
:
.I
aBlock
.B
ifNone
:
.I
noneBlock
.RE
.PP
This message returns the first element in the receiver for which 
.I
aBlock
evaluates to something that is non-nil\&.
.PP
Evaluates 
.I
noneBlock
if there\&'s no element for which 
.I
aBlock
evaluates to something that is non-nil, and returns the return value of that block\&.  For example,
.RS 3

[ aCltn detect: { :e | [e isEqual:anObject]} ifNone: {anObject} ];
.br

.RE
.PP 
select:
.RS 1
-
.B
select
:
.I
testBlock
.RE
.PP
This message will return a subset of the receiver containing all elements for which 
.I
testBlock
evaluates to an Object that is non-nil\&.  For example,
.RS 3

[ aCltn select: { :each | [each isEqual:anObject] } ];
.br

.RE
.PP
Returns a new empty instance of the same class as the receiver, if there\&'s no element for which 
.I
testBlock
evaluates to something that is non-nil\&. 
.PP 
reject:
.RS 1
-
.B
reject
:
.I
testBlock
.RE
.PP
Complement of 
.B
select:
.PP
This message will return a subset of the receiver containing all elements for which 
.I
testBlock
evaluates to nil\&.  For example,
.RS 3

[ aCltn reject: { :each | [each isEqual:anObject] } ];
.br

.RE
.PP
Returns a new empty instance of the same class as the receiver, if there\&'s no element for which 
.I
testBlock
evaluates to nil\&.
.PP 
collect:
.RS 1
-
.B
collect
:
.I
transformBlock
.RE
.PP
This message creates and returns a new collection of the same size and type as the receiver\&. The elements are the result of performing 
.I
transformBlock
on each element in the receiver (elements for which the Block would return 
.B
nil
are filtered out)\&.
.PP 
count:
.RS 1
- (
unsigned
)
.B
count
:
.I
aBlock
.RE
.PP
Evaluate 
.I
aBlock
with each of the receiver\&'s elements as the argument\&.  Return the number that answered a non-
.B
nil
value\&.
.PP 
elementsPerform:
.RS 1
-
.B
elementsPerform
:(SEL)
.I
aSelector
.RE
.PP
Send 
.I
aSelector
to all objects in the collection, starting from the object at offset 
.I
0
\&.  For Stepstone compatibility\&.  Producer uses this\&.
.PP 
elementsPerform:with:
.RS 1
-
.B
elementsPerform
:(SEL)
.I
aSelector
.B
with
:
.I
anObject
.RE
.PP
Send 
.I
aSelector
to all objects in the collection, starting from the object at offset 
.I
0
\&.  For Stepstone compatibility\&.  Producer uses this\&.
.PP 
elementsPerform:with:with:
.RS 1
-
.B
elementsPerform
:(SEL)
.I
aSelector
.B
with
:
.I
anObject
.B
with
:
.I
otherObject
.RE
.PP
Send 
.I
aSelector
to all objects in the collection, starting from the object at offset 
.I
0
\&.  For Stepstone compatibility\&.  Producer uses this\&.
.PP 
elementsPerform:with:with:with:
.RS 1
-
.B
elementsPerform
:(SEL)
.I
aSelector
.B
with
:
.I
anObject
.B
with
:
.I
otherObject
.B
with
:
.I
thirdObj
.RE
.PP
Send 
.I
aSelector
to all objects in the collection, starting from the object at offset 
.I
0
\&.  For Stepstone compatibility\&.  ICpak201 uses this\&.
.PP 
do:
.RS 1
-
.B
do
:
.I
aBlock
.RE
.PP
Evaluates 
.I
aBlock
for each element in the collection and returns 
.B
self
\&.  
.I
aBlock
must be a block taking one object (element) as argument; the return value of the block is ignored by this method\&.
.PP
Often, the Block would, as a side-effect, modify a variable, as in:
.RS 3

int count = 0;
.br
[contents do: { :what | if (what == anObject) count++; }];
.br

.RE
.PP 
do:until:
.RS 1
-
.B
do
:
.I
aBlock
.B
until
:(BOOL*)
.I
flag
.RE
.PP
Evaluates 
.I
aBlock
for each element in the collection, or until the variable pointed to by 
.I
flag
becomes true, and returns 
.B
self
\&.  
.I
aBlock
must be a block taking one object (element) as argument; the return value of the block is ignored by this method\&.
.PP
Typically the Block will modify the variable 
.I
flag
when some condition holds:
.RS 3

BOOL found = NO;
.br
[contents do:{ :what | if (what == findObject) found=YES;} until:&found];
.br
if (found) { \&.\&.\&. }
.br

.RE