Portable Object Compiler (c) 1997,98.  All Rights Reserved.

Sequence

Inherits from: Object

Class Description

Sequences are used to loop or sequence over a group of objects.  Typically, an Sequence instance is generated by using some method like OrdCltn's eachElement.  Then, within a loop, one can send next messages to the sequence until the end is reached (when the next method returns nil).  Finally, after using the sequence, you have to free the sequence object.

Warning

Using a sequence can lead to problems if, in sequencing over a collection, that collection is modified, e.g., as in the following :

id item;
id aSeq;

aSeq = [aCol eachElement];
while ((item = [aSeq next])) [aCol add:something]; /* WRONG !!! */
aSeq = [aSeq free];

You may not modify a group of objects while sequencing over its contents.

Method types

Creation	- copy
	- free

Interrogation	- size

Accessing	- next
	- peek
	- previous
	- first
	- last

Printing	- printOn:

Performing	- do:

Methods

copy
-copy

Returns a copy of the sequence.  Can be used independently of the original sequence.

free
-free

Frees the receiver, but not the objects in the collection being sequenced over.

size
- (unsigned)size

Returns the total number of items in the sequence.

next
-next

Returns the next object in the sequence if there is one and advances the sequence.  When it reaches the end of the sequence, returns nil.

peek
-peek

Returns the next object in the sequence if there is one, but does not advance the sequence.  When it reaches the end of the sequence, returns nil.

previous
-previous

Returns the object that was returned by the last next message.  If there were no next messages since the sequence was created, or the sequence is empty, returns nil.  Doesn't affect the current position in the sequence.

first
-first

Returns the first object in the sequence, unlesss there are no members in the sequence, in which case it returns nil.  Doesn't affect the current position in the sequence.

last
-last

Returns the last object in the sequence, unlesss there are no members in the sequence, in which case it returns nil.  Doesn't affect the current position in the sequence.

printOn:
-printOn:(IOD)aFile

Prints a newline separated list of the objects in the sequence to aFile, by sending each individual object a printOn: message.  Returns the sequence when there are no more elements left.

do:
-do:aBlock

Performs aBlock for the remaining members of a sequence.  aBlock should take one argument, which is the element.  Typically used as in,

[[aDictionary eachValue] do:{ :each | [each show]; }];