List

Overview

The List class holds a sequence of objects which are identified by a positional index. It is intended for managing groups of objects which have either no natural indexing information or for which the associated numeric identifiers form a densely packed set beginning with the index zero.

The List object may expand or shrink to contain varying numbers of objects. It also supports several “iterator” functions, which are used to successively visit each object in the list.

• Definition
  • define() - Define initial length of storage array
  • inquire() - Inquire current length of storage array
• Set and query elements
  • count() - Get number of contained objects
  • allIndices() - Get all indices
  • maxIndex() - Get maximum index
  • insert() - Place object at specified index location
  • add() - Place object in first empty position
  • append() - Place object at the end of sequence
  • get() - Find object at specified location
  • remove() - Remove object from a specified location
  • clear() - Remove all objects from the List object
  • compact() - Reduce storage space if possible
  • forEach() - Call a function one time for each object
  • initializeIterator() - Prepare to successively visit each object
  • nextItem() - Return the next object in the sequence
• General functions
  • getErrorCode() - Return the current error code

Once a List is instanced, an approximate number of objects to be stored may be defined using define(). This allocates an internal array for the storage of object pointers. As objects are inserted the List class will adjust memory as required. The actual size of the allocated storage may be determined by calling inquire().

Each new object is placed in the list by calling insert(), add(), or append(). The total number of objects contained in the list may be found by calling count(). The object at a specified index may be found by calling get(). An object may be removed by calling remove(). The method clear() removes all objects from the list. Unused storage at the end of the internal array may be released by calling compact().

Each object in the list may be processed with an “iterator” construct. The single method forEach() takes a function as its argument and calls that function repeatedly, each time with one object from the list. The pair of methods initializeIterator() and nextItem() are used to visit each element using a loop. Call the first method before the body of the loop to prepare the List object for the iteration. Within the loop body, call nextItem(). It will return a pointer to a new object each time it is called. It will return a NULL pointer when all the objects have been processed.

Class Members Descriptions

The currently available List enumerations and functions are described in detail in this section.

template<typename T>
class List

Randomly Accessible Sequences.

Public Functions

ErrorCode getErrorCode()

Return the current ErrorCode of the List object.

Returns: ErrorCode - The current error code, or NONE if no error.

Status define(int capacity)

Suggest a number of elements to be stored in the List. This is used to allocate the initial array of storage which is used to hold a pointer to each stored object. If the number of inserted elements is greater than this initial estimate, storage space is dynamically expanded to hold the extra objects. This function removes any previously entered objects.

See Also inquire()

Errors

MEMORY is generated if new storage was unable to be allocated.

Parameters:capacity – Estimated number of objects to be held Returns:Status

Status inquire(int *capacity)

Find the current length of the internal storage of the List.

See Also define()

Parameters:capacity – [out] Current length of internal storage Returns:Status

Status count(int *itemCount)

Get the number of objects which have been inserted or appended, and not yet removed.

Parameters:itemCount – [out] Number of objects held in the List object Returns:Status

Status maxIndex(int *index)

Get the maximum index used to store current objects in the List.

See Also allIndices()

Parameters:index – [out] Maximum index Returns:Status

Status allIndices(int indices[])

Get all indices used to store current objects in the List. The number of index values returned will be equal to the number of indices returned by count() .

See Also maxIndex() , count()

Parameters:indices – [out] Array of all indices Returns:Status

Status insert(int index, T *item)

Place the object at the location identified by index, replacing any object which may have been previously placed there.

See Also add() , append() , get()

Errors

• VALUE is generated if index is less than zero.
• MEMORY is generated if new storage was unable to be allocated.

Parameters:

• index – Position in list at which object is to be stored
• item – Pointer to the object

Returns:

Status

Status add(T *item, int *index)

Insert an object into the list at an arbitrarily assigned index. The location at which the object was placed will be returned in the output argument index.

See Also insert() , append()

Parameters:

• item – Pointer to the object
• index – [out] Position in list at which object was stored

Returns:

Status

Status append(T *item)

Place an object at the end of the list.

See Also insert() , add()

Parameters:item – Pointer to the object Returns:Status

Status get(int index, Pointer<T> &item)

Get a pointer to the object located at the position identified by index. Returns a NULL pointer if no object has been placed there, or if a previously inserted object has since been removed from this location.

See Also insert()

Parameters:

• index – Location of the desired object
• item – [out] Object found at location index

Returns:

Status

Status remove(int index)

Remove any object found at the location identified by index. This may introduce a “gap” in the list, which may later be filled with one of the insertion methods.

See Also clear() , compact()

Parameters:index – Location to be emptied Returns:Status

Status clear()

Remove all the objects from the List object.

See Also remove() , compact()

Returns:Status

Status compact()

Release any unused internal storage.

See Also remove() , clear()

Returns:Status

Status initializeIterator()

Initiate the iteration for sequential access to each item in the list. Each call of nextItem() will return a new item from the list together with its associated index. After every object has been visited, nextItem() will return a NULL pointer until the iteration is restarted using initializeIterator() . Objects are visited starting from position zero, and empty positions in the list are skipped over.

See Also nextItem() , forEach()

Returns:Status

Status nextItem(int *index, Pointer<T> &item)

Get the next item from the list together with its associated index. Returns a NULL pointer when all objects have been visited.

See Also initializeIterator() , forEach()

Parameters:

• index – [out] Index of the next item
• item – [out] Object at the index

Returns:

Status

Status forEach(UnaryFunction *function)

Call the supplied function repeatedly, each time using an object from the list as the sole argument to this function. This is useful for deallocating a collection of objects, prior to destroying the List. Objects are visited in numerically increasing order of their position indices. Empty positions in the list are skipped over.

See Also initializeIterator() , nextItem()

Parameters:function – Pointer to function which is to be applied to each object Returns:Status