...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
The Boost Multidimensional Array Library provides a class template for multidimensional arrays, as well as semantically equivalent adaptors for arrays of contiguous data. The classes in this library implement a common interface, formalized as a generic programming concept. The interface design is in line with the precedent set by the C++ Standard Library containers. Boost MultiArray is a more efficient and convenient way to express N-dimensional arrays than existing alternatives (especially the std::vector<std::vector<...>> formulation of N-dimensional arrays). The arrays provided by the library may be accessed using the familiar syntax of native C++ arrays. Additional features, such as resizing, reshaping, and creating views are available (and described below).
The C++ standard library provides several generic containers, but it does not provide any multidimensional array types. The std::vector class template can be used to implement N-dimensional arrays, for example expressing a 2-dimensional array of double elements using the type std::vector<std::vector<double>>, but the resulting interface is unwieldy and the memory overhead can be quite high. Native C++ arrays (i.e. int arr[2][2][2];) do not immediately interoperate well with the C++ Standard Library, and they also lose information at function call boundaries (specifically the extent of the last dimension). Finally, a dynamically allocated contiguous block of elements can be treated as an array, though this method requires manual bookkeeping that is error prone and obfuscates the intent of the programmer.
The Boost MultiArray library enhances the C++ standard containers with versatile multi-dimensional array abstractions. It includes a general array class template and native array adaptors that support idiomatic array operations and interoperate with C++ Standard Library containers and algorithms. The arrays share a common interface, expressed as a generic programming in terms of which generic array algorithms can be implemented.
This document is meant to provide an introductory tutorial and user's guide for the most basic and common usage patterns of MultiArray components. The reference manual provides more complete and formal documentation of library features.
#include "boost/multi_array.hpp" #include <cassert> int main () { // Create a 3D array that is 3 x 4 x 2 typedef boost::multi_array<double, 3> array_type; typedef array_type::index index; array_type A(boost::extents[3][4][2]); // Assign values to the elements int values = 0; for(index i = 0; i != 3; ++i) for(index j = 0; j != 4; ++j) for(index k = 0; k != 2; ++k) A[i][j][k] = values++; // Verify values int verify = 0; for(index i = 0; i != 3; ++i) for(index j = 0; j != 4; ++j) for(index k = 0; k != 2; ++k) assert(A[i][j][k] == verify++); return 0; }
multi_array_ref adapts an existing array of data to provide the multi_array interface. multi_array_ref does not own the data passed to it.
const_multi_array_ref is similar to multi_array_ref but guarantees that the contents of the array are immutable. It can thus wrap pointers of type T const*.
The three components exhibit very similar behavior. Aside from constructor parameters, multi_array and multi_array_ref export the same interface. const_multi_array_ref provides only the constness-preserving portions of the multi_array_ref interface.
Each of the array types - multi_array, multi_array_ref, and const_multi_array_ref - provides a specialized set of constructors. For further information, consult their reference pages.
All of the non-const array types in this library provide assignment operatorsoperator=(). Each of the array types multi_array, multi_array_ref, subarray, and array_view can be assigned from any of the others, so long as their shapes match. The const variants, const_multi_array_ref, const_subarray, and const_array_view, can be the source of a copy to an array with matching shape. Assignment results in a deep (element by element) copy of the data contained within an array.
template <typename Array> void my_function() { typedef typename Array::template array_view<3>::type view1_t; typedef typename boost::array_view_gen<Array,3>::type view2_t; // ... }
The first method involves passing a Collection of extents to a constructor, most commonly a boost::array. The constructor will retrieve the beginning iterator from the container and retrieve N elements, corresponding to extents for the N dimensions. This is useful for writing dimension-independent code.
typedef boost::multi_array<double, 3> array_type; boost::array<array_type::index, 3> shape = {{ 3, 4, 2 }}; array_type A(shape);
The second method involves passing the constructor an extent_gen object, specifying the matrix dimensions. The extent_gen type is defined in the multi_array_types namespace and as a member of every array type, but by default, the library constructs a global extent_gen object boost::extents. In case of concern about memory used by these objects, defining BOOST_MULTI_ARRAY_NO_GENERATORS before including the library header inhibits its construction.
typedef boost::multi_array<double, 3> array_type; array_type A(boost::extents[3][4][2]);
typedef boost::multi_array<double, 3> array_type; array_type A(boost::extents[3][4][2]); A[0][0][0] = 3.14; assert(A[0][0][0] == 3.14);
The second method involves passing a Collection of indices to operator(). N indices will be retrieved from the Collection for the N dimensions of the container.
This can be useful for writing dimension-independent code, and under some compilers may yield higher performance than operator[].typedef boost::multi_array<double, 3> array_type; array_type A(boost::extents[3][4][2]); boost::array<array_type::index,3> idx = {{0,0,0}}; A(idx) = 3.14; assert(A(idx) == 3.14);
By default, both of the above element access methods perform range checking. If a supplied index is out of the range defined for an array, an assertion will abort the program. To disable range checking (for performance reasons in production releases), define the BOOST_DISABLE_ASSERTS preprocessor macro prior to including multi_array.hpp in your application.
Sub-view creation occurs by placing a call to operator[], passing it an index_gen type. The index_gen is populated by passing index_range objects to its operator[]. The index_range and index_gen types are defined in the multi_array_types namespace and as nested members of every array type. Similar to boost::extents, the library by default constructs the object boost::indices. You can suppress this object by defining BOOST_MULTI_ARRAY_NO_GENERATORS before including the library header. A simple sub-view creation example follows.
// myarray = 2 x 3 x 4 // // array_view dims: [base,bound) (dimension striding default = 1) // dim 0: [0,2) // dim 1: [1,3) // dim 2: [0,4) (strided by 2), // typedef boost::multi_array_types::index_range range; // OR typedef array_type::index_range range; array_type::array_view<3>::type myview = myarray[ boost::indices[range(0,2)][range(1,3)][range(0,4,2)] ]; for (array_type::index i = 0; i != 2; ++i) for (array_type::index j = 0; j != 2; ++j) for (array_type::index k = 0; k != 2; ++k) assert(myview[i][j][k] == myarray[i][j+1][k*2]);
By passing an integral value to the index_gen, one may create a subview with fewer dimensions than the original array component (also called slicing).
// myarray = 2 x 3 x 4 // // array_view dims: // [base,stride,bound) // [0,1,2), 1, [0,2,4) // typedef boost::multi_array_types::index_range range; array_type::index_gen indices; array_type::array_view<2>::type myview = myarray[ indices[range(0,2)][1][range(0,4,2)] ]; for (array_type::index i = 0; i != 2; ++i) for (array_type::index j = 0; j != 2; ++j) assert(myview[i][j] == myarray[i][1][j*2]);
An index_range object passed to a slicing operation will inherit its start and/or finish value from the array being sliced if you do not supply one. This conveniently prevents you from having to know the bounds of the array dimension in certain cases. For example, the default-constructed range will take the full extent of the dimension it is used to specify.// [base,stride,bound) // [0,2,4) typedef boost::multi_array_types::index_range range; range a_range; a_range = range(0,4,2); a_range = range().start(0).finish(4).stride(2); a_range = range().start(0).stride(2).finish(4); a_range = 0 <= range().stride(2) < 4; a_range = 0 <= range().stride(2) <= 3;
The following example slicing operations exhibit some of the alternatives shown abovetypedef boost::multi_array_types::index_range range; range a_range; // All elements in this dimension a_range = range(); // indices i where 3 <= i a_range = range().start(3) a_range = 3 <= range(); a_range = 2 < range(); // indices i where i < 7 a_range = range().finish(7) a_range = range() < 7; a_range = range() <= 6;
// take all of dimension 1 // take i < 5 for dimension 2 // take 4 <= j <= 7 for dimension 3 with stride 2 myarray[ boost::indices[range()][range() < 5 ][4 <= range().stride(2) <= 7] ];
c_storage_order, which is the default, will store elements in memory in the same order as a C array would, that is, the dimensions are stored from last to first.
fortran_storage_order will store elements in memory in the same order as FORTRAN would: from the first dimension to the last. Note that with use of this parameter, the array indices will remain zero-based.
typedef boost::multi_array<double,3> array_type; array_type A(boost::extents[3][4][2],boost::fortran_storage_order); call_fortran_function(A.data());
general_storage_order allows one to customize both the order in which dimensions are stored in memory and whether dimensions are stored in ascending or descending order.
typedef boost::general_storage_order<3> storage; typedef boost::multi_array<int,3> array_type; // Store last dimension, then first, then middle array_type::size_type ordering[] = {2,0,1}; // Store the first dimension(dimension 0) in descending order bool ascending[] = {false,true,true}; array_type A(extents[3][4][2],storage(ordering,ascending));
typedef boost::multi_array<double, 3> array_type; typedef boost::multi_array_types::extent_range range; // OR typedef array_type::extent_range range; array_type::extent_gen extents; // dimension 0: 0-based // dimension 1: 1-based // dimension 2: -1 - based array_type A(extents[2][range(1,4)][range(-1,3)]);
An alternative is to first construct the array normally then reset the bases. To set all bases to the same value, use the reindex member function, passing it a single new index value.
typedef boost::multi_array<double, 3> array_type; array_type::extent_gen extents; array_type A(extents[2][3][4]); // change to 1-based A.reindex(1)
An alternative is to set each base separately using the reindex member function, passing it a Collection of index bases.
typedef boost::multi_array<double, 3> array_type; array_type::extent_gen extents; // dimension 0: 0-based // dimension 1: 1-based // dimension 2: (-1)-based array_type A(extents[2][3][4]); boost::array<array_type::index,ndims> bases = {{0, 1, -1}}; A.reindex(bases);
typedef boost::multi_array<double, 3> array_type; array_type::extent_gen extents; array_type A(extents[2][3][4]); boost::array<array_type::index,ndims> dims = {{4, 3, 2}}; A.reshape(dims);
Note that reshaping an array does not affect the indexing.
typedef boost::multi_array<int, 3> array_type; array_type::extent_gen extents; array_type A(extents[3][3][3]); A[0][0][0] = 4; A[2][2][2] = 5; A.resize(extents[2][3][4]); assert(A[0][0][0] == 4); // A[2][2][2] is no longer valid.