Class: TArrayOf

Declaration: ArrayOf.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TIndexedSequenceOf

Inherited By:

None.

Purpose:

TArrayOf is a concrete class you can use to create collections whose objects are ordered and accessed much like an ordinary array. This class provides operators for finding a particular object and for allowing the collection to dynamically increase in size.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Do not derive classes from TArrayOf.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

Use the subscripting operator and the operators FastAt and FastAtPut with care, as they provide no range checking and do not automatically grow the size of the collection. For 1.0 First() and Last() blindly grab the first and last element in the array, even if the logical size of the array is zero. After 1.0 First() and Last() will do range checking and throw and IndexOutOfBounds exception.

Member Function: TArrayOf::TArrayOf

TArrayOf ()
TArrayOf (const TArrayOf < AType > &)
TArrayOf (TComparator < AType > * adoptedComparator, TStreamer < AType > * adoptedStreamer, CollectionIndex initialsize =0, CollectionIndex growthrate =kGrowthRateForInsertAt, bool autogrow =true)

Interface Category:

API.

Purpose:

Default constructor. The collection is empty and has no defined comparison or streaming operators.
Copy constructor.
Creates a collection and adopts the passed argument's comparison and streaming operators, if they exist.

Calling Context:

Call this function directly anywhere the creation of a TArrayOf is desired.
Call this function directly to copy an object.
Call this function directly to create an empty collection that will use specified arguments for comparison, streaming, size and growth rate.

Parameters:

Takes no parameters.
const TArrayOf < AType > & -The object to be copied.
TComparator < AType > * adoptedComparator -The comparator to be used with this collection.
TStreamer < AType > * adoptedStreamer -The streamer that is used if the collection is streamed.
CollectionIndex initialsize =0 -The initial size of the collection.
CollectionIndex growthrate =kGrowthRateForInsertAt -The growth rate.
bool autogrow =true -A flag that specifies whether the collection can grow beyond the initially defined size.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TArrayOf::~TArrayOf

virtual ~ TArrayOf ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Call this function directly to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TArrayOf::operator=

const TArrayOf < AType > & operator =(const TArrayOf < AType > &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Call this function directly when an object is assigned to another compatible object.

Parameters:

const TArrayOf < AType > & -The object to be copied.

Return Value:

A reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TArrayOf::Fill

void Fill (const AType * obj)

Interface Category:

API.

Purpose:

Fills each element in the collection with the passed object.

Calling Context:

Called to fill the collection with objects. Call this function directly.

Parameters:

const AType * obj -The object to fill the collection with.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The reference to the object is copied, not the object itself.

Member Function: TArrayOf::Grow

void Grow (CollectionIndex howmuch, CollectionIndex extraspace =0, bool addToTop =true)

Interface Category:

API.

Purpose:

Adds space in the collection for more objects, regardless of how the SetAutoGrowFlag has been set.

Calling Context:

Called to increase the size of the collection. Call this function directly.

Parameters:

CollectionIndex howmuch -The number of objects to add space for.
CollectionIndex extraspace =0 -The number of objects to add extra space for. The default is to not add any extra space.
bool addToTop =true -This flag specifies whether to add the new space before the zeroth element or after the last element. The default is to add space after the last element.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TArrayOf::Compress

void Compress (CollectionIndex from, CollectionIndex howmuch)

Interface Category:

API.

Purpose:

Compresses the collection by deleting a range of objects and shifting any remaining objects down.

Calling Context:

Called to compress the contents of the collection by deleting a range of objects. Call this function directly.

Parameters:

CollectionIndex from -The index of the first object to delete.
CollectionIndex howmuch -The number of objects to delete.

Return Value:

None.

Exceptions:

Throws kIndexOutOfBounds if the range specified is not valid.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TArrayOf::Reverse

void Reverse ()

Interface Category:

API.

Purpose:

Reverses the order of the objects in the collection.

Calling Context:

Called to reverse the order of the objects in the collection. Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TArrayOf::Append

AType * Append (const AType * obj)

Interface Category:

API.

Purpose:

Inserts an object to the end of the collection, growing the size of the collection if there is no more space and the autoGrow flag has been set to true.

Calling Context:

Called to add an object to the end of the collection. Call this function directly.

Parameters:

const AType * obj -The object to be added.

Return Value:

A reference to the object added.

Exceptions:

Throws kIndexOutOfBounds if the collection is full and SetAutoGrowFlag is set to false.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TArrayOf::GrowTo

void GrowTo (CollectionIndex maxIndex)

Interface Category:

API.

Purpose:

Increases the size of the collection such that the maximum index is equal to the supplied argument, regardless of how the autoGrow flag has been set.

Calling Context:

Called to increase the size of the collection. Call this function directly.

Parameters:

CollectionIndex maxIndex -The new maximum index.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TArrayOf::SetAutoGrowFlag

void SetAutoGrowFlag (bool autoGrow =true)

Interface Category:

API.

Purpose:

Enables or disables the automatic increase in the collection's size.

Calling Context:

Called to enable or disable the automatic increase in the collection's size. Call this function directly.

Parameters:

bool autoGrow =true -The new setting for the autoGrow flag. The default value is true.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TArrayOf::GetAutoGrowFlag

bool GetAutoGrowFlag () const

Interface Category:

API.

Purpose:

Returns the current setting of the autoGrow flag.

Calling Context:

Called to query the setting of the autoGrow flag. Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the autoGrow flag is been set to true.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TArrayOf::operator==

bool operator ==(const TArrayOf < AType > & arrayOf) const

Interface Category:

API.

Purpose:

Tests whether the contents of this collection are equivalent to the contents of another collection.

Calling Context:

Call this function directly to test the equivalence of the two objects on either side of the ==symbol.

Parameters:

const TArrayOf < AType > & arrayOf -The object to be compared to this object.

Return Value:

Returns true if the contents of this collection are identical to the contents of the other collection.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TArrayOf::operator!=

bool operator != (const TArrayOf < AType > & arrayOf) const

Interface Category:

API.

Purpose:

Tests whether the contents of this collection are equivalent to the contents of another collection.

Calling Context:

Call this function directly to test the equivalence of the two objects on either side of the != symbol.

Parameters:

const TArrayOf < AType > & arrayOf -The object to be compared to this object.

Return Value:

Returns true if the contents of this collection are not identical to the contents of the other collection.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TArrayOf::Find

AType * Find (const AType * obj, CollectionIndex & findresult, long start =-1, long end =-1) const

Interface Category:

API.

Purpose:

Searches the collection for an object that matches the object specified. Optionally, the search can be restricted to a range within the collection.

Calling Context:

Called to locate an object in the collection that matches the specified object. Call this function directly.

Parameters:

const AType * obj -The object to be matched.
CollectionIndex & findresult -Set to the index of the matching object, if a match was found.
long start =-1 -The low bound of the search. If set to -1, the search will start at the beginning of the collection.
long end =-1 -The high bound of the search. If set to -1, the search will stop at the end of the collection.

Return Value:

Returns a reference to the matching object. A NIL reference is returned if no match was found of if the low bound of the search is less than zero.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TArrayOf::FastAt

AType * FastAt (CollectionIndex index) const

Interface Category:

API.

Purpose:

Returns a reference to the object at the index specified. No bounds checking is performed on the index.

Calling Context:

Called to quickly obtain a reference to the object in the collection at the specified index. No bounds checking is performed on the index. Call this function directly.

Parameters:

CollectionIndex index -The index of the object in the collection.

Return Value:

A pointer to the object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Using an invalid index will have unpredictable results.

Member Function: TArrayOf::FastAtPut

void FastAtPut (CollectionIndex index, const AType * obj)

Interface Category:

API.

Purpose:

Quickly adds an object to the collection at the specified index, replacing any object that might be stored there. No bounds checking is performed on the index.

Calling Context:

Called to quickly add an object to the collection. Call this function directly.

Parameters:

CollectionIndex index -The index of the object in the collection to be replaced with the new object.
const AType * obj -The new object.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Using an invalid index will have unpredictable results.

Member Function: TArrayOf::operator[]

AType & operator [] (CollectionIndex index)

Interface Category:

API.

Purpose:

Returns an object by an index. No bounds checking is performed on the index.

Calling Context:

Call this function directly whenever the collection is referenced with the [] operator.

Parameters:

CollectionIndex index -The index of the object to return.

Return Value:

A reference to the object from the collection.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Using an invalid index will have unpredictable results.

Click the icon to mail questions or corrections about this material to Taligent personnel.