|
PSCF v1.1
|
Container and iterator class templates. More...
Modules | |
| Object Arrays | |
| Array containers that store objects by value, and related iterators. | |
| Pointer Arrays | |
| Array containers that store pointers to objects, and related iterators. | |
| Matrix Containers | |
| Two-dimensional array containers that store by objects value. | |
| Linked List | |
| A simple linked list implementation and associated iterator. | |
| Iterators | |
| Iterators for use with particular containers. | |
Container and iterator class templates.
This module contains a set of simple container templates, some of which are similar to containers provided by the C++ standard library. Bounds checking of indices for all array containers can be turned on (for safety) or off (for speed) by defining or not defining the UTIL_DEBUG preprocessor macro.
Containers templates whose name contains the string 'Array' are one dimensional array containers, much like C arrays. All such containers overload the subscript [] operator so as to return an object by reference, using the same syntax as a C array or a std::vector: If A is an array, then A[i] is a reference to the ith element of A.
Container templates whose name contains the string 'Matrix' are two dimensional arrays. These overload the (int, int) operator to access elements: If M is a Matrix, then M(i, j) is a reference to the element in column j of row i of A.
The names of many containers have prefixes before the word Array or Matrix that indicates policies for memory allocation and management.
Containers templates whose name begins with the letter 'D' (such as DArray, DSArray, DPArray, and DMatrix) use dynamically allocated memory. The declaration "DArray<int> A" declares a dynamically allocated array of integers. Memory must be explicitly allocated for these containers by calling the "allocate" method after the container is instantiated and before it is used. Dynamically allocated containers can only be allocated once and are not resizable. Attempting to allocate a container more than once is as an error, and causes an Exception to be thrown.
Containers templates whose name begins with a letter 'F' (such as FArray, FSArray, FPArray, and FMatrix) are fixed size containers. The capacity of each such container is determined at compile time by a template parameter or parameters. Thus, for example,
declares a fixed size array of four integers, much like the declaration "int V[4]" of a fixed size C array.
The letter "S" in the names of DSArray and FSArray indicate that these are "sized" arrays. These arrays have a variable logical size that is less than or equal to the physical capacity. The logical size is the current number of elements, which are always stored contiguously from index 0 to index size - 1. Accessing an element with index greater than or equal to size is an error, and will cause an Exception to be thrown if debugging is enabled. The capacity of an array is the number of elements for which memory has been allocated. The size of such an array is initially set to zero, and elements are added sequentially by the append() method, which adds a new element at the end of the array and increments the size counter. Once the size reaches the array capacity, attempting to append another element will cause an Exception to be thrown.
Array containers whose name includes the prefix G are sized arrays with a capacity that can grow (G="growable") as needed as elements are appended. The "GArray" template thus implements a dynamic array very similiar to the standard library std::vector. Automatic resizing changes the address of the beginning of the array, and invalidates all iterators and pointers to elements.
Container templates whose name contains the prefix "P" are pointer arrays. A pointer array is a container that stores pointers to objects that are instantiated outside of the array, rather than storing actual objects. The containers DPArray and FPArray are dynamically allocated fixed size pointer arrays, respectively. The GPArray array is a growable pointer array, which can grow without bound. The pointer arrays are all similar to "sized" arrays in that they have a logical size that must be less than or equal to their capacity, and in that elements must can be added to the end of an initially empty array by function "append(T& )". Pointer arrays use the same interface for the subscript operator (which returns a reference) and the append function (which takes a reference parameter) as that used by the sized and object arrays. A pointer array of type DPArray< T > is thus different from a sized array of pointers, of type DSArray<T*>, because DPArray< T > overloads the [] operator to return a reference to an object of type T that is referenced by a private pointer, whereas the subscript operator for a DSArray<T*> returns an actual pointer.
1.9.5