CArrayA
The CArrayA class template provides a lightweight, memory-managed, alignable 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.
- Array data is aligned if OBJEXXFCL_ALIGN is defined when building.
Shorthand (typedef) names are provided for the common value header so, for example, we use CArrayA_int instead of CArrayA< int > on this page.
Construction
CArrayAs are created in a straightforward fashion:
// CArrayA with n elements
CArrayA_int v( n ); // Elements are uninitialized
CArrayA_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.
CArrayAs can be constructed from C arrays and a length:
int * s = new int[ n ];
...
CArrayA_int v( s, n ); |
and from an iterator range:
CArrayA_int v( s.begin(), s.end(), p ); // Chunk size is 2^p |
CArrayAs can also be default constructed and later sized:
CArrayA_int v;
...
v.resize( n ); // Now size and allocate it |
CArrayAs can also be copy constructed from any CArrayA with assignment-compatible values:
CArrayA_int v( n );
...
CArrayA_double z( v );
|
Subscripting
CArrayA elements can be accessed by 0-based or 1-based index:
CArrayA_int v( n );
...
int i = v[ 0 ]; // First element
int j = v( 1 ); // First element |
Subscripting accesses to a CArrayA's elements are bounds-checked via assertions in a debug build.
Front and Back Elements
The first and last elements of a CArrayA elements can be read or write accessed with the STL-compatible front and back functions:
CArrayA_int v( n );
...
j = v.front(); // First element
v.back() = k; // Last element |
Assignment
CArrayAs support assignment of any CArrayA or std::vector with assignment-compatible values using the operators { =, +=, -= }:
CArrayA_int v( n );
CArrayA_double z( n );
... z = v;
...
z += v; |
and assignment of any assignment-compatible value with the operators { =, +=, -=, *=, /= }:
CArrayA_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
CArrayAs can be compared with CArrayAs and uniform values using the operators { ==, !=, <, <=, >=, > }.
Resizing
CArrayAs 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
CArrayAs can be reset to a default-constructed state with the clear member function. Two CArrayAs can efficiently swap their contents with the swap member and free functions. CArrayAs 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 CArrayAs. The distance and distance_squared functions compute the L2 distance and squared distance between two CArrayAs.
Output
Stream input and output operators are provided.
Debugging
For performance, CArrayA 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 CArrayAs.
|