OLVector Class Reference
[Containers]

A growable array of objects. More...

#import <ObjectiveLib/Vector.h>

Inheritance diagram for OLVector:

Inheritance graph
[legend]
List of all members.

Public Member Functions

(void) - assign:filledWith:
 Assign objects to the vector.
(void) - assignAt:value:
 Assign object to the position at index.
(void) - assignFrom:to:
 Assign a range of objects to the vector.
(id) - at:
 Return the object at index.
(id) - back
 Return the last object in the vector.
(OLArrayIterator *) - begin
 Return an iterator pointing to the beginning of the sequence.
(unsigned) - capacity
 Return the current capacity of the vector.
(void) - clear
 Remove all elements.
(int) - compare:
 Compare this vector to another object.
(id) - copyWithZone:
 Make a copy of this vector allocating memory from the given zone.
(BOOL) - empty
 Test whether the vector is empty.
(void) - encodeWithCoder:
 Encode the vector.
(OLArrayIterator *) - end
 Return an iterator pointing to one position beyond the end of the sequence.
(OLArrayIterator *) - erase:
 Remove the element designated by where.
(OLArrayIterator *) - eraseFrom:to:
 Remove a range of elements.
(id) - front
 Return the first object in the vector.
(void) - insertAt:count:filledWith:
 Insert a number of objects into the vector.
(void) - insertAt:from:to:
 Insert a range of objects into the vector.
(OLArrayIterator *) - insertAt:value:
 Insert an object into the vector.
(BOOL) - isEqual:
 Return whether this vector is equal to another one.
(unsigned) - maxSize
 Return the maxiumum number of objects that can be stored in a vector.
(void) - popBack
 Remove the last element in the vector.
(void) - pushBack:
 Insert object at the end of the sequence.
(OLReverseRandomIterator *) - rbegin
 Return a reverse iterator pointing to the end of the sequence.
(OLReverseRandomIterator *) - rend
 Return a reverse iterator pointing to the beginning of the sequence.
(void) - reserve:
 Reserve storage.
(void) - resize:filledWith:
 Resize the vector to newsize.
(unsigned) - size
 Return the number of elements in the vector.
(void) - swap:
 Swap this vector with another one.
(void) - writeSelfToStream:
 Write the object to a stream.
Initializers and Deallocators
(void) - dealloc
 Finalize the vector and deallocate any allocated memory.
(id) - init
 Initialize the vector.
(id) - initFrom:to:
 Initialize the vector.
(id) - initWithCapacity:
 Initialize the vector.
(id) - initWithCoder:
 Initialize the vector.
(id) - initWithObjectInStream:
 Initialize the object.
(id) - initWithSize:filledWith:
 Initialize the vector.
(id) - initWithVector:
 Initialize the vector.

Static Public Member Functions

(id) + vector
 Create and return a new vector.
(id) + vectorFrom:to:
 Create and return a new vector.
(id) + vectorWithCapacity:
 Create and return a new vector.
(id) + vectorWithSize:filledWith:
 Create and return a new vector.
(id) + vectorWithVector:
 Create and return a new vector.

Protected Attributes

id * begin
 The beginning of the sequence.
id * end
 The end of the sequence.
id * endOfCapacity
 The end of storage capacity.

Detailed Description

A growable array of objects.

A vector is essentially an array of objects that provides random access to its elements and is optimized for insertion and removable at the end of the sequence. The capacity of the vector will grow as needed, so memory management is entirely automatic. It also serves as a suitable container for OLBackInsertIterator and OLInsertIterator.

See also:
OLArrayIterator, OLBoolVector


Member Function Documentation

- (void) assign: (unsigned)  count
filledWith: (id)  value 

Assign objects to the vector.

The current contents of the vector are removed, and the vector is filled with count elements of value.

Parameters:
count the number of elements to assign
value the object to be copied into the vector

- (void) assignAt: (unsigned)  index
value: (id)  object 

Assign object to the position at index.

The object currently in possession of the position at index is removed and replaced with object.

Note:
The range of the vector is not checked prior to performing this operation. Using values of index that do not lie within the vector's range will produce undefined results.
Parameters:
index the index to which to assign
object the object to put at index

- (void) assignFrom: (OLForwardIterator *)  first
to: (OLForwardIterator *)  last 

Assign a range of objects to the vector.

The current contents of the vector are removed, and all elements in the range [first, last) are inserted into the vector.

Parameters:
first the first in the range of objects to assign
last one beyond the last in the range of objects to assign

- (id) at: (unsigned)  index  

Return the object at index.

A reference to the object is returned, though the vector still owns the object in question.

Note:
The range of the vector is not checked prior to performing this operation. Using values of index that do not lie within the vector's range will produce undefined results.
Parameters:
index the index of the object to look up
Returns:
a reference to the object at index

- (id) back  

Return the last object in the vector.

A reference to the object is returned, though the vector still owns the object in question.

Note:
The results of this message are undefined if the vector is empty.
Returns:
the last object

- (OLArrayIterator*) begin  

Return an iterator pointing to the beginning of the sequence.

Note:
If OpenStep is present the returned object will be autoreleased before being returned.
Returns:
an iterator pointing to the first element

- (unsigned) capacity  

Return the current capacity of the vector.

The capacity represents the maximum number of elements that the vector can hold before allocation of new memory will be required.

Returns:
the capacity

- (void) clear  

Remove all elements.

- (int) compare: (id)  other  

Compare this vector to another object.

If the other object is of type OLVector the two vectors are lexicographically compared.

Parameters:
other the object with which to compare this one
Returns:
a value greater than, equal to, or less than zero accoringly as this object is greater than, equal to, or less than other

- (id) copyWithZone: (NSZone *)  zone  

Make a copy of this vector allocating memory from the given zone.

Parameters:
zone the zone from which to allocate memory
Returns:
the copy

- (void) dealloc  

Finalize the vector and deallocate any allocated memory.

- (BOOL) empty  

Test whether the vector is empty.

Returns:
YES if the vector is empty, NO otherwise

- (void) encodeWithCoder: (NSCoder *)  encoder  

Encode the vector.

The vector is saved to an archive using encoder. The vector will be retrieved from the archive using the initializer initWithCoder:.

Parameters:
encoder the coder which will save the bit set to the archive

- (OLArrayIterator*) end  

Return an iterator pointing to one position beyond the end of the sequence.

Note:
If OpenStep is present the returned object will be autoreleased before being returned.
Returns:
an iterator pointing to one position beyond the last element

- (OLArrayIterator*) erase: (OLArrayIterator *)  where  

Remove the element designated by where.

Precondition:
where must point to an element in this vector.
Note:
If OpenStep is present the returned object will be autoreleased before being returned.
Parameters:
where an iterator designating the element to remove
Returns:
an iterator indicating the next element in the sequence remaining after where

- (OLArrayIterator*) eraseFrom: (OLArrayIterator *)  first
to: (OLArrayIterator *)  last 

Remove a range of elements.

All elements in the range [first, last) will be removed from the vector.

Precondition:
first and last must refer to elements in this vector.
Note:
If OpenStep is present the returned object will be autoreleased before being returned.
Parameters:
first the first in the range of elements to remove
last one position beyond the last in the range of elements to remove
Returns:
an iterator indicating the next element in the sequence remaining after removal of the range

- (id) front  

Return the first object in the vector.

A reference to the object is returned, though the vector still owns the object in question.

Note:
The results of this message are undefined if the vector is empty.
Returns:
the first object

- (id) init  

Initialize the vector.

The vector is empty and the capacity is initially zero.

Returns:
a reference to this vector

- (id) initFrom: (OLForwardIterator *)  first
to: (OLForwardIterator *)  last 

Initialize the vector.

The vector inserts all elements referred to in the range [first, last).

Parameters:
first the first in the range of elements to insert
last one beyond the last in the range of elements to insert
Returns:
a reference to this vector

- (id) initWithCapacity: (unsigned)  capacity  

Initialize the vector.

The initial capacity is set to capacity.

Parameters:
capacity the initial capacity of the vector
Returns:
a reference to this vector

- (id) initWithCoder: (NSCoder *)  decoder  

Initialize the vector.

This initializer creates a new vector from an archive and returns it.

Postcondition:
The vector returned will be identical to the vector saved to the archive using the encodeWithCoder: message.
Parameters:
decoder the coder which will decode the archived vector
Returns:
a reference to this vector

- (id) initWithObjectInStream: (OLObjectInStream *)  stream  

Initialize the object.

Each instance variable is read from stream and all other initialization is performed.

Parameters:
stream the stream from which to read
Returns:
a reference to this object

Reimplemented from < OLStreamable >.

- (id) initWithSize: (unsigned)  size
filledWith: (id)  value 

Initialize the vector.

The initial size of the vector will be size, and value will be copied into the vector size times.

Parameters:
size the number of elements to insert
value the object to be copied
Returns:
a reference to this vector

- (id) initWithVector: (OLVector *)  vector  

Initialize the vector.

All of the elements of vetor are copied into the current vector.

Parameters:
vector the vector to copy
Returns:
a reference to this vector

- (void) insertAt: (OLArrayIterator *)  where
count: (unsigned)  num
filledWith: (id)  value 

Insert a number of objects into the vector.

num objects of value will be inserted just before the position referred to by where. Thus, it is valid to use an iterator returned by end as an argument.

Precondition:
where must refer to a position in this vector
Parameters:
where the position at which to insert the objects
num the number of objects to insert
value the object to be copied into the vector

- (void) insertAt: (OLArrayIterator *)  where
from: (OLForwardIterator *)  first
to: (OLForwardIterator *)  last 

Insert a range of objects into the vector.

All objects in the range [first, last) are inserted just before the position referred to by where. Thus, it is valid to use an iterator returned by end as an argument.

Parameters:
where the position at which to insert the objects
first the first in the range of objects to insert
last one position beyond the last in the range of objects to insert

- (OLArrayIterator*) insertAt: (OLArrayIterator *)  where
value: (id)  object 

Insert an object into the vector.

The object will be inserted just before the position referred to by where. Thus, it is valid to use an iterator returned by end as an argument.

Precondition:
where must refer to a position in this vector.
Note:
If OpenStep is present the returned object will be autoreleased before being returned.
Parameters:
where the position at which to insert object
object the object to insert
Returns:
an iterator pointing to the newly inserted object

- (BOOL) isEqual: (id)  object  

Return whether this vector is equal to another one.

Two vectors are considered equal if they both contain the same number of objects that all return YES to the message isEqual: and they are in the same order.

Parameters:
object the object to test
Returns:
YES if object is equal to this vector

Reimplemented from < OLBackInserter >.

- (unsigned) maxSize  

Return the maxiumum number of objects that can be stored in a vector.

This limit is theoretical, meaning that there is no guarantee that you can insert this many objects into any given vector. The memory conditions of the run-time system play an important role.

Returns:
the maximum number of objects for a vector

- (void) popBack  

Remove the last element in the vector.

Note:
If there are no elements in the vector, then the behavior of this message is undefined.

- (void) pushBack: (id)  object  

Insert object at the end of the sequence.

Parameters:
object the object to insert

Reimplemented from < OLBackInserter >.

- (OLReverseRandomIterator*) rbegin  

Return a reverse iterator pointing to the end of the sequence.

Advancing the returned iterator will move backwards through the sequence to the point indicated by the iterator returned by rend.

Note:
If OpenStep is present the returned object will be autoreleased before being returned.
Returns:
a reverse iterator for the end of the sequence

- (OLReverseRandomIterator*) rend  

Return a reverse iterator pointing to the beginning of the sequence.

This iterator indicates one position beyond the last position that may be referenced by a reverse iterator.

Note:
If OpenStep is present the returned object will be autoreleased before being returned.
Returns:
a reverse iterator for the beginning of the sequence

- (void) reserve: (unsigned)  count  

Reserve storage.

If count is less than the current capacity of the vector, then this message does nothing. If count is greater than the current capacity, then count - capacity elements of storage will be added to the container. This may invalidate iterators that are currently active. This operation will not affect the size, or number of elements actually stored, only the capacity.

Parameters:
count the total number of desired spaces in the vector

- (void) resize: (unsigned)  newsize
filledWith: (id)  value 

Resize the vector to newsize.

If newsize is smaller than the current size, then the sequence will be truncated. If newsize is larger than the current size, then value will be inserted at the end of the vector as many times as necessary to fill the new size.

Parameters:
newsize the new size of the vector
value the value with which to fill new elements, if necessary

- (unsigned) size  

Return the number of elements in the vector.

Returns:
the number of elements

- (void) swap: (OLVector *)  right  

Swap this vector with another one.

All elements in right will be placed into this vector, and all elements in this vector will be placed in right.

Parameters:
right the vector with which to swap this one

+ (id) vector  

Create and return a new vector.

Note:
If OpenStep is present the returned object will be autoreleased before being returned.
Returns:
a new vector

+ (id) vectorFrom: (OLForwardIterator *)  first
to: (OLForwardIterator *)  last 

Create and return a new vector.

The vector is initialized with the contents of the range [first, last).

Note:
If OpenStep is present the returned object will be autoreleased before being returned.
Parameters:
first the first in the range of elements to insert
last one beyond the last in the range of elements to insert
Returns:
a new vector

+ (id) vectorWithCapacity: (unsigned)  capacity  

Create and return a new vector.

The initial capacity will be no less than capacity.

Note:
If OpenStep is present the returned object will be autoreleased before being returned.
Parameters:
capacity the minimum capacity of the new vector
Returns:
a new vector

+ (id) vectorWithSize: (unsigned)  size
filledWith: (id)  value 

Create and return a new vector.

The new vector will have a size of size, and each element will be set to value.

Note:
If OpenStep is present the returned object will be autoreleased before being returned.
Parameters:
size the size of the new vector
value the value with which to fill the new vector
Returns:
a new vector

+ (id) vectorWithVector: (OLVector *)  right  

Create and return a new vector.

The vector is initialized with the contents of right.

Note:
If OpenStep is present the returned object will be autoreleased before being returned.
Parameters:
right the vector that should be copied into the new one
Returns:
a new vector

- (void) writeSelfToStream: (OLObjectOutStream *)  stream  

Write the object to a stream.

All instance variables are written to stream.

Parameters:
stream the stream to which to write.

Reimplemented from < OLStreamable >.


Member Data Documentation

- (id*) begin [protected]

The beginning of the sequence.

- (id*) end [protected]

The end of the sequence.

- (id*) endOfCapacity [protected]

The end of storage capacity.


The documentation for this class was generated from the following file:
ObjectiveLibGenerated Sun Apr 22 15:13:57 2007, © 2004-2007 Will Mason
SourceForge.net Logo