CPArray Overview

The CPArray class template provides a lightweight memory-managed wrapper for the classic C-style array with a proxy capability:

• 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.
• CPArrays can be owners of their data or proxies to other CPArrays. Proxies have zero lookup overhead compared to owning CPArrays, CArrays, or C-style arrays.

Shorthand (typedef) names are provided for the common value header so, for example, we use CPArray_int instead of CPArray< int > on this page.

Construction

CPArrays are created in a straightforward fashion:

// CPArray with n elements
CPArray_int v( n ); // Elements are uninitialized
CPArray_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.

CPArrays can be constructed from C arrays and a length:

int * s = new int[ n ];
...
CPArray_int v( s, n );

and from an iterator range:

CPArray_int v( s.begin(), s.end(), p ); // Chunk size is 2^p

CPArrays can also be default constructed and later sized:

CPArray_int v;
...
v.resize( n ); // Now size and allocate it

CPArrays can also be copy constructed from any CPArray with assignment-compatible values:

CPArray_int v( n );
...
CPArray_double z( v );

Proxy CPArrays can constructed from a CPArray holding the same type using the Proxy named constructor:

CPArray_int v( n );
...
CPArray_int y( CPArray_int::Proxy( v ) );
CPArray_int z( CPArray_int::Proxy( v, n-9 ) ); // Proxy size can be smaller

Subscripting

CPArray elements can be accessed by 0-based or 1-based index:

CPArray_int v( n );
...
int i = v[ 0 ]; // First element
int j = v( 1 ); // First element

Subscripting accesses to a CPArray's elements are bounds-checked via assertions in a debug build.

Front and Back Elements

The first and last elements of a CPArray elements can be read or write accessed with the STL-compatible front and back functions:

CPArray_int v( n );
...
j = v.front(); // First element
v.back() = k; // Last element

Assignment

CPArrays support assignment of any CPArray or std::vector with assignment-compatible values using the operators { =, +=, -= }:

CPArray_int v( n );
CPArray_double z( n );
...
z = v;
...
z += v;

and assignment of any assignment-compatible value with the operators { =, +=, -=, *=, /= }:

CPArray_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

Proxy CPArrays cannot be assigned arrays of a different size.

Comparison

CPArrays can be compared with CPArrays and uniform values using the operators { ==, !=, <, <=, >=, > }.

Resizing

CPArrays 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. Proxy CPArrays cannot be resized.

Special Functions

CPArrays can be reset to a default-constructed state with the clear member function. Two CPArrays can efficiently swap their contents with the swap member and free functions. CPArrays have length and length_squared member functions to compute their L₂ 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 CPArrays. The distance and distance_squared functions compute the L₂ distance and squared distance between two CPArrays.

CPArrays can be made into proxies with the attach member function and made into non-proxies with the detach member function.

Debugging

For performance, CPArray 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 CPArrays.

Output

A stream output operator is provided in CPArray.io.hh.