CArray
The CArray class template provides a lightweight, memory-managed wrapper for the classic C-style array:
- The interface is similar to that of std::vector in some respects.
- Index and iterator based element access are supported.
- 0-based subscripting is provided by the [] operator, as in v[ i ].
- 1-based subscripting is provided by the () operator, as in v( i ).
- Subscripting does bounds checking in debug builds.
- Array size and indexing types are std::size_t so very large arrays are supported on 64-bit platforms where std::size_t is a 64-bit unsigned integer.
Shorthand (typedef) names are provided for the common value header so, for example, we use CArray_int instead of CArray< int > on this page.
Construction
CArrays are created in a straightforward fashion:
// CArray with n elements
CArray_int v( n ); // Elements are uninitialized
CArray_int w( n, 0 ); // Initialize elements to 0 |
The first constructor shown does not initialize the elements of built-in types such as int and float, for efficiency when constructing very large arrays that will be initialized after construction.
CArrays can be constructed from C arrays and a length:
int * s = new int[ n ];
...
CArray_int v( s, n ); |
and from an iterator range:
CArray_int v( s.begin(), s.end(), p ); // Chunk size is 2^p |
CArrays can also be default constructed and later sized:
CArray_int v;
...
v.resize( n ); // Now size and allocate it |
CArrays can also be copy constructed from any CArray with assignment-compatible values:
CArray_int v( n );
...
CArray_double z( v );
|
Subscripting
CArray elements can be accessed by 0-based or 1-based index:
CArray_int v( n );
...
int i = v[ 0 ]; // First element
int j = v( 1 ); // First element |
Subscripting accesses to a CArray's elements are bounds-checked via assertions in a debug build.
Front and Back Elements
The first and last elements of a CArray elements can be read or write accessed with the STL-compatible front and back functions:
CArray_int v( n );
...
j = v.front(); // First element
v.back() = k; // Last element |
Assignment
CArrays support assignment of any CArray or std::vector with assignment-compatible values using the operators { =, +=, -= }:
CArray_int v( n );
CArray_double z( n );
... z = v;
...
z += v; |
and assignment of any assignment-compatible value with the operators { =, +=, -=, *=, /= }:
CArray_int v( n );
... v = 123; // All elements set to 123
v += 4.2; // Now all elements are 127 |
Additional assignment functions are available for assigning from an iterator range:
v.assign( s.begin(), s.end() ); |
or assigning a specified number of uniform-value elements:
v.assign( 1000, 123 ); // 1000 elements with value 123 |
Comparison
CArrays can be compared with CArrays and uniform values using the operators { ==, !=, <, <=, >=, > }.
Resizing
CArrays can be resized with the size and resize functions. The resize function preserves the values of the array that fit within the new size range and sets any new values to a specified fill value that defaults to the default-constructed value of the value type. If the values do not need to be preserved the size function is more efficient.
Special Functions
CArrays can be reset to a default-constructed state with the clear member function. Two CArrays can efficiently swap their contents with the swap member and free functions. CArrays have length and length_squared member functions to compute their L2 length and squared length and the normalize function to normalize the array to unit length. The dot_product function computes the dot (inner) product of two CArrays. The distance and distance_squared functions compute the L2 distance and squared distance between two CArrays.
Output
Stream input and output operators are provided.
Debugging
For performance, CArray doesn't check for bounds errors in release builds (when NDEBUG is defined). It is therefore important to test assertion-enabled debug builds of code using CArrays.
|