...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
namespace multi_array_types { typedef *unspecified* index; typedef *unspecified* size_type; typedef *unspecified* difference_type; typedef *unspecified* index_range; typedef *unspecified* extent_range; typedef *unspecified* index_gen; typedef *unspecified* extent_gen; }
Namespace multi_array_types
defines types
associated with multi_array
,
multi_array_ref
, and
const_multi_array_ref
that are not
dependent upon template parameters. These types find common use with
all Boost.Multiarray components. They are defined
in a namespace from which they can be accessed conveniently.
With the exception of extent_gen
and
extent_range
, these types fulfill the roles of the
same name required by MultiArray and are described in its
concept definition. extent_gen
and
extent_range
are described below.
extent_range
objects define half open
intervals. They provide shape and index base information to
multi_array
, multi_array_ref
,
and const_multi_array_ref
constructors.
extent_range
s are passed in
aggregate to an array constructor (see
extent_gen
for more details).
Synopsis.
class extent_range { public: typedef multi_array_types::index index; typedef multi_array_types::size_type size_type; // Structors extent_range(index start, index finish); extent_range(index finish); ~extent_range(); // Queries index start(); index finish(); size_type size(); };
Model Of. DefaultConstructible,CopyConstructible
Methods and Types.
extent_range(index start, index finish)
This constructor defines the half open interval
[start,finish)
. The expression
finish
must be greater than start
.
extent_range(index finish)
This constructor defines the half open interval
[0,finish)
. The value of finish
must be positive.
index start()
This function returns the first index represented by the range
index finish()
This function returns the upper boundary value of the half-open interval. Note that the range does not include this value.
size_type size()
This function returns the size of the specified range. It is
equivalent to finish()-start()
.
The extent_gen
class defines an
interface for aggregating array shape and indexing information to be
passed to a multi_array
,
multi_array_ref
, or const_multi_array_ref
constructor. Its interface mimics
the syntax used to declare built-in array types
in C++. For example, while a 3-dimensional array of
int
values in C++ would be
declared as:
int A[3][4][5],
a similar multi_array
would be declared:
multi_array<int,3> A(extents[3][4][5]).
Synopsis.
template <std::size_t NumRanges> class *implementation_defined* { public: typedef multi_array_types::index index; typedef multi_array_types::size_type size_type; template <std::size_t NumRanges> class gen_type; gen_type<NumRanges+1>::type operator[](const range& a_range) const; gen_type<NumRanges+1>::type operator[](index idx) const; }; typedef *implementation_defined*<0> extent_gen;
Methods and Types.
template gen_type<Ranges>::type
This type generator is used to specify the result of
Ranges
chained calls to
extent_gen::operator[].
The types
extent_gen
and
gen_type<0>::type
are the same.
gen_type<NumRanges+1>::type
operator[](const extent_range& a_range) const;
This function returns a new object containing all previous
extent_range
objects in addition to
a_range.
extent_range
objects are aggregated by chained calls to
operator[]
.
gen_type<NumRanges+1>::type
operator[](index idx) const;
This function returns a new object containing all previous
extent_range
objects in addition to
extent_range(0,idx).
This function gives the array
constructors a similar syntax to traditional C multidimensional array
declaration.
For syntactic convenience, Boost.MultiArray defines two global objects as part of its interface. These objects play the role of object generators; expressions involving them create other objects of interest.
Under some circumstances, the two global objects may be
considered excessive overhead. Their construction can be prevented by
defining the preprocessor symbol
BOOST_MULTI_ARRAY_NO_GENERATORS
before including
boost/multi_array.hpp.
namespace boost { multi_array_base::extent_gen extents; }
Boost.MultiArray's array classes use the
extents
global object to specify
array shape during their construction.
For example,
a 3 by 3 by 3 multi_array
is constructed as follows:
multi_array<int,3> A(extents[3][3][3]);
The same array could also be created by explicitly declaring an extent_gen
object locally,, but the global object makes this declaration unnecessary.
namespace boost { multi_array_base::index_gen indices; }
The MultiArray concept specifies an
index_gen
associated type that is used to
create views.
indices
is a global object that serves the role of
index_gen
for all array components provided by this
library and their associated subarrays and views.
For example, using the indices
object,
a view of an array A
is constructed as follows:
A[indices[index_range(0,5)][2][index_range(2,4)]];
Boost.MultiArray provides traits classes, subarray_gen
,
const_subarray_gen
,
array_view_gen
,
and const_array_view_gen
, for naming of
array associated types within function templates.
In general this is no more convenient to use than the nested
type generators, but the library author found that some C++ compilers do not
properly handle templates nested within function template parameter types.
These generators constitute a workaround for this deficit.
The following code snippet illustrates
the correspondence between the array_view_gen
traits class and the array_view
type associated to
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; // ... }
In the above example, view1_t
and
view2_t
have the same type.
While a multidimensional array represents a hierarchy of containers of elements, at some point the elements must be laid out in memory. As a result, a single multidimensional array can be represented in memory more than one way.
For example, consider the two dimensional array shown below in matrix notation:
Here is how the above array is expressed in C++:
int a[3][4] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 };
This is an example of row-major storage, where elements of each row are stored contiguously. While C++ transparently handles accessing elements of an array, you can also manage the array and its indexing manually. One way that this may be expressed in memory is as follows:
int a[] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 }; int s[] = { 4, 1 };
With the latter declaration of a
and
strides s
, element a(i,j)
of the array can be
accessed using the expression
*a+i*s[0]+j*s[1]
.
The same two dimensional array could be laid out by column as follows:
int a[] = { 0, 4, 8, 1, 5, 9, 2, 6, 10, 3, 7, 11 }; int s[] = { 3, 1 };
Notice that the strides here are different. As a result, The expression given above to access values will work with this pair of data and strides as well.
In addition to dimension order, it is also possible to store any dimension in descending order. For example, returning to the first example, the first dimension of the example array, the rows, could be stored in reverse, resulting in the following:
int data[] = { 8, 9, 10, 11, 4, 5, 6, 7, 0, 1, 2, 3 }; int *a = data + 8; int s[] = { -4, 1 };
Note that in this example a
must be explicitly set
to the origin. In the previous examples, the
first element stored in memory was the origin; here this is no longer
the case.
Alternatively, the second dimension, or the columns, could be reversed and the rows stored in ascending order:
int data[] = { 3, 2, 1, 0, 7, 6, 5, 4, 11, 10, 9, 8 }; int *a = data + 3; int s[] = { 4, -1 };
Finally, both dimensions could be stored in descending order:
int data[] = {11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0}; int *a = data + 11; int s[] = { -4, -1 };
All of the above arrays are equivalent. The expression
given above for a(i,j)
will yield the same value
regardless of the memory layout.
Boost.MultiArray arrays can be created with customized storage
parameters as described above. Thus, existing data can be adapted
(with multi_array_ref
or
const_multi_array_ref
) as suited to the array
abstraction. A common usage of this feature would be to wrap arrays
that must interoperate with Fortran routines so they can be
manipulated naturally at both the C++ and Fortran levels. The
following sections describe the Boost.MultiArray components used to
specify memory layout.
class c_storage_order { c_storage_order(); };
c_storage_order
is used to specify that an
array should store its elements using the same layout as that used by
primitive C++ multidimensional arrays, that is, from last dimension
to first. This is the default storage order for the arrays provided by
this library.
class fortran_storage_order { fortran_storage_order(); };
fortran_storage_order
is used to specify that
an array should store its elements using the same memory layout as a
Fortran multidimensional array would, that is, from first dimension to
last.
template <std::size_t NumDims> class general_storage_order { template <typename OrderingIter, typename AscendingIter> general_storage_order(OrderingIter ordering, AscendingIter ascending); };
general_storage_order
allows the user to
specify an arbitrary memory layout for the contents of an array. The
constructed object is passed to the array constructor in order to
specify storage order.
OrderingIter
and AscendingIter
must model the InputIterator
concept. Both
iterators must refer to a range of NumDims
elements. AscendingIter
points to objects
convertible to bool
. A value of
true
means that a dimension is stored in ascending
order while false
means that a dimension is stored
in descending order. OrderingIter
specifies the
order in which dimensions are stored.
By default, the array access methods operator()
and
operator[]
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 an application.