Boost.MultiArray is composed of several components. +
Boost.MultiArray is composed of several components.
The MultiArray concept defines a generic interface to multidimensional
containers.
multi_array is a general purpose container class
@@ -11,7 +11,7 @@ you can manipulate any block of contiguous data as though it were a
multi_array_ref in that its elements cannot
be modified through its interface. Finally, several auxiliary classes are used
to create and specialize arrays and some global objects are defined as
-part of the library interface.
To use Boost.MultiArray, you must include the header +part of the library interface.
To use Boost.MultiArray, you must include the header
boost/multi_array.hpp in your source. This file
brings the following declarations into scope:
namespace boost {
@@ -52,7 +52,7 @@ namespace boost {
template <std::size_t NumDims> class general_storage_order;
}
-The MultiArray concept defines an interface to hierarchically nested containers. It specifies operations for accessing elements, traversing containers, and creating views @@ -150,17 +150,23 @@ number of possible element layouts. For example, the elements of a 2 dimensional array can be stored by row (i.e., the elements of each row are stored contiguously) or by column (i.e., the elements of each column are stored contiguously). -
What follows are the descriptions of symbols that will be used -to describe the MultiArray interface.
Table 1. Notation
A | A type that is a model of MultiArray
+
+Two concept checking classes for the MultiArray concepts
+( What follows are the descriptions of symbols that will be used +to describe the MultiArray interface. Table 1. Notation
- Table 2. Associated Types
+ Table 2. Associated Types
Table 3. Valid Expressions
Table 3. Valid Expressions
begin() and end() execute in amortized
+type must model LessThanComparable for this
+expression to be valid. |
begin() and end() execute in amortized
constant time.
size() executes in at most linear time in the
MultiArray's size.
-Table 4. Invariants
| Valid range | [a.begin(),a.end()) is a valid range.
+Table 4. Invariants
The following MultiArray associated
+is a Collection containing the values |
The following MultiArray associated types define the interface for creating views of existing MultiArrays. Their interfaces and roles in the -concept are described below.
index_range objects represent half-open
+concept are described below.
index_range objects represent half-open
strided intervals. They are aggregated (using an
index_gen object) and passed to
a MultiArray's operator[]
@@ -403,10 +411,10 @@ operators, a half open range [5,10) can be specified as follows:
The following describes the
index_range interface.
-
Table 6. Associated Types
index_gen aggregates
index_range objects in order to specify view
parameters. Chained calls to operator[] store
range and dimension information used to
instantiate a new view into a MultiArray.
-
Table 8. Notation
Dims,Ranges | Unsigned integral values. | |||||||||||||||||||||||||||||||||||||
x | An object of type
+ Table 8. Notation
Table 9. Associated Types
Table 9. Associated Types
Table 10. Valid Expressions
Table 10. Valid Expressions
|
Boost.MultiArray defines an array class,
multi_array, and two adapter classes,
multi_array_ref and
@@ -487,7 +495,7 @@ adapts cannot be modified through its interface, though some array
properties, including the array shape and index bases, can be altered.
Functionality the classes have in common is described
below.
-
Note: Preconditions, Effects, and Implementation. +
Note: Preconditions, Effects, and Implementation. Throughout the following sections, small pieces of C++ code are used to specify constraints such as preconditions, effects, and postconditions. These do not necessarily describe the underlying @@ -498,7 +506,7 @@ preconditions results in undefined behavior. Not all effects (i.e. copy constructors, etc.) must be mimicked exactly. The code snippets for effects intend to capture the essence of the described operation. -
Queries.
element* data(); +Queries.
This returns a pointer to the beginning of the contiguous block that contains the array's data. If all dimensions of the array are 0-indexed and stored in ascending order, this is @@ -516,7 +524,7 @@ version of this function. (Required by MultiArray)
multi_array. (Required by MultiArray)const size_type* shape();This returns the shape of the
multi_array. (Required by MultiArray) -Comparators.
Comparators.
Each comparator executes a lexicographical compare over the value types of the two arrays. (Required by MultiArray) -
Preconditions.
elementmust support the +Preconditions.
elementmust support the comparator corresponding to that called on -multi_array.Complexity. O(
num_elements()).Modifiers.
- +
multi_array.Complexity. O(
num_elements()).Modifiers.
This changes the shape of the
multi_array. The number of elements and the index bases remain the same, but the number of values at each level of the nested container hierarchy may -change.
SizeListRequirements.SizeListmust model -Collection.Preconditions. +change.
SizeListRequirements.SizeListmust model +Collection.Preconditions.
-std::accumulate(sizes.begin(),sizes.end(),size_type(1),std::multiplies<size_type>()) == this->num_elements(); +std::accumulate(sizes.begin(),sizes.end(),size_type(1),std::times<size_type>()) == this->num_elements(); sizes.size() == NumDims; -Postconditions. +
Postconditions.
std::equal(sizes.begin(),sizes.end(),this->shape) == true;This changes the index bases of the
multi_arrayto -correspond to the the values invalues.
BaseListRequirements.BaseListmust model -Collection.Preconditions.
values.size() == NumDims;Postconditions.
std::equal(values.begin(),values.end(),this->index_bases()); +correspond to the the values invalues.
BaseListRequirements.BaseListmust model +Collection.Preconditions.
values.size() == NumDims;Postconditions.
std::equal(values.begin(),values.end(),this->index_bases());This changes the index bases of all dimensions of the -
multi_arraytovalue.Postconditions. +
multi_arraytovalue.Postconditions.
std::count_if(this->index_bases(),this->index_bases()+this->num_dimensions(), std::bind_2nd(std::equal_to<index>(),value)) == this->num_dimensions(); --
multi_arrayis a multi-dimensional container that supports random access iteration. Its number of dimensions is fixed at compile time, but its shape and the number of elements it @@ -578,11 +586,11 @@ will remain fixed for the duration of amulti_array's lifetime, but the shape of the container can be changed. Amulti_arraymanages its data elements using a replaceable allocator. -Model Of. -MultiArray, -CopyConstructible. Depending on the element type, -it may also model EqualityComparable and LessThanComparable. -
Synopsis.
+Model Of. +MultiArray, +CopyConstructible. Depending on the element type, +it may also model EqualityComparable and LessThanComparable. +
Synopsis.
namespace boost { @@ -608,7 +616,7 @@ public: typedef multi_array_types::extent_gen extent_gen; typedef multi_array_types::extent_range extent_range; typedef *unspecified* storage_order_type; - + // template typedefs template <std::size_t Dims> struct subarray; @@ -617,6 +625,9 @@ public: template <std::size_t Dims> struct const_array_view; + static const std::size_t dimensionality = NumDims; + + // constructors and destructors multi_array(); @@ -699,7 +710,7 @@ public: multi_array& resize(extents_tuple& extents); }; -Constructors.
Constructors.
template <typename ExtentList> explicit multi_array(const ExtentList& sizes, const storage_order_type& store = c_storage_order(), const Allocator& alloc = Allocator()); @@ -710,9 +721,9 @@ constructedmulti_array.sto specifies the storage order or layout in memory of the array dimensions.allocis used to allocate the contained elements. -
ExtentListRequirements. -ExtentListmust model Collection. -Preconditions.
sizes.size() == NumDims;- +
ExtentListRequirements. +ExtentListmust model Collection. +Preconditions.
sizes.size() == NumDims;explicit multi_array(extent_gen::gen_type<NumDims>::type ranges, const storage_order_type& store = c_storage_order(), const Allocator& alloc = Allocator()); @@ -736,34 +747,34 @@ multi_array(const subarray<NumDims>::type& x); multi_array(const array_view<NumDims>::type& x);These constructors all constructs a
multi_arrayand perform a deep copy ofx. -Complexity. This performs O(
x.num_elements()) calls to +Complexity. This performs O(
x.num_elements()) calls toelement's copy constructor.This constructs a
multi_arraywhose shape is (0,...,0) and contains no elements. -Note on Constructors. +
Note on Constructors. The
multi_arrayconstruction expressions,multi_array<int,3> A(boost::extents[5][4][3]); -+
and
boost::array<multi_array_base::index,3> my_extents = {{5, 4, 3}}; multi_array<int,3> A(my_extents); -+
are equivalent. -
Modifiers.
Modifiers.
This performs an element-wise copy of
x-into the currentmulti_array.
ArrayRequirements.Arraymust model MultiArray. -Preconditions. +into the current
multi_array.
ArrayRequirements.Arraymust model MultiArray. +Preconditions.
std::equal(this->shape(),this->shape()+this->num_dimensions(), -x.shape());Postconditions. -
(*.this) == x;-
Complexity. The assignment operators perform +x.shape());
Postconditions. +
(*.this) == x;+
Complexity. The assignment operators perform O(
x.num_elements()) calls toelement's copy constructor.This copies the elements in the range
[begin,end)into the array. It is equivalent tostd::copy(begin,end,this->data()). -Preconditions.
std::distance(begin,end) == this->num_elements();-Complexity. +
Preconditions.
std::distance(begin,end) == this->num_elements();+Complexity. The
assignmember function performs O(this->num_elements()) calls toValueType's copy constructor. @@ -792,25 +803,25 @@ contents of the array are preserved whenever possible; if the new array size is smaller, then some data will be lost. Any new elements created by resizing the array are initialized with theelementdefault constructor. -Queries.
Queries.
This query returns the storage order object associated with the -
multi_arrayin question. It can be used to construct a new array with the same storage order.
multi_array_refis a multi-dimensional container adaptor. It provides the MultiArray interface over any contiguous block of elements.multi_array_refexports the same interface asmulti_array, with the exception of the constructors. -Model Of. +
Model Of.
multi_array_refmodels -MultiArray, -CopyConstructible. +MultiArray, +CopyConstructible. and depending on the element type, it may also model -EqualityComparable and LessThanComparable. +EqualityComparable and LessThanComparable. Detailed descriptions are provided here only for operations that are not described in themulti_arrayreference. -Synopsis.
+Synopsis.
namespace boost { @@ -843,7 +854,10 @@ public: template <std::size_t Dims> struct const_array_view; - // structors + static const std::size_t dimensionality = NumDims; + + + // constructors and destructors template <typename ExtentList> explicit multi_array_ref(element* data, const ExtentList& sizes, @@ -910,7 +924,7 @@ public: void reindex(index value); }; -Constructors.
Constructors.
template <typename ExtentList> explicit multi_array_ref(element* data, const ExtentList& sizes, const storage_order& store = c_storage_order(), @@ -922,9 +936,9 @@ constructedmulti_array_ref.allocis used to allocate the contained elements. -
ExtentListRequirements. -ExtentListmust model Collection. -Preconditions.
sizes.size() == NumDims;- +
ExtentListRequirements. +ExtentListmust model Collection. +Preconditions.
sizes.size() == NumDims;explicit multi_array_ref(element* data, extent_gen::gen_type<NumDims>::type ranges, const storage_order& store = c_storage_order()); @@ -939,36 +953,36 @@ dimensions.This constructs a shallow copy of
x. -Complexity. Constant time (for contrast, compare this to +
Complexity. Constant time (for contrast, compare this to the
multi_arrayclass copy constructor. -Modifiers.
Modifiers.
This performs an element-wise copy of
x-into the currentmulti_array_ref.
ArrayRequirements.Arraymust model MultiArray. -Preconditions. +into the current
multi_array_ref.
ArrayRequirements.Arraymust model MultiArray. +Preconditions.
std::equal(this->shape(),this->shape()+this->num_dimensions(), -x.shape());Postconditions. -
(*.this) == x;-
Complexity. The assignment operators perform +x.shape());
Postconditions. +
(*.this) == x;+
Complexity. The assignment operators perform O(
x.num_elements()) calls toelement's -copy constructor.
const_multi_array_refis a multi-dimensional container adaptor. It provides the MultiArray interface over any contiguous block of elements.const_multi_array_refexports the same interface asmulti_array, with the exception of the constructors. -Model Of. +
Model Of.
const_multi_array_refmodels -MultiArray, -CopyConstructible. +MultiArray, +CopyConstructible. and depending on the element type, it may also model -EqualityComparable and LessThanComparable. +EqualityComparable and LessThanComparable. Detailed descriptions are provided here only for operations that are not described in themulti_arrayreference. -Synopsis.
+Synopsis.
namespace boost { @@ -1054,7 +1068,7 @@ public: void reindex(index value); }; -Constructors.
Constructors.
template <typename ExtentList> explicit const_multi_array_ref(TPtr data, const ExtentList& sizes, const storage_order& store = c_storage_order()); @@ -1064,13 +1078,13 @@ parameters.sizesspecifies the shape of the constructedconst_multi_array_ref.storespecifies the storage order or layout in memory of the array dimensions. -
ExtentListRequirements. -ExtentListmust model Collection. -Preconditions.
sizes.size() == NumDims;- +
ExtentListRequirements. +ExtentListmust model Collection. +Preconditions.
sizes.size() == NumDims;explicit const_multi_array_ref(TPtr data, extent_gen::gen_type<NumDims>::type ranges, const storage_order& store = c_storage_order()); -Effects. +
Effects. This constructs a
const_multi_array_refusing the specified parameters.rangesspecifies the shape and index bases of the constructed const_multi_array_ref. It is the result of @@ -1080,8 +1094,8 @@ specifies the storage order or layout in memory of the array dimensions.Effects. This constructs a shallow copy of
x. -
namespace multi_array_types {
typedef *unspecified* index;
typedef *unspecified* size_type;
@@ -1103,14 +1117,14 @@ With the exception of extent_gen and
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_ranges are passed in
aggregate to an array constructor (see
extent_gen for more details).
-
Synopsis.
+Synopsis.
class extent_range { public: typedef multi_array_types::index index; @@ -1125,14 +1139,14 @@ public: 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 +};
Model Of. DefaultConstructible,CopyConstructible
Methods and Types.
extent_range(index start, index finish)This constructor defines the half open interval
[start,finish). The expressionfinishmust be greater thanstart.extent_range(index finish)This constructor defines the half open interval
[0,finish). The value offinishmust 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
@@ -1144,7 +1158,7 @@ declared as:
int A[3][4][5],
a similar multi_array would be declared:
multi_array<int,3> A(extents[3][4][5]).
-
Synopsis.
+Synopsis.
template <std::size_t NumRanges> class *implementation_defined* { public: @@ -1158,7 +1172,7 @@ public: }; typedef *implementation_defined*<0> extent_gen; -Methods and Types.
template gen_type<Ranges>::typeThis type generator is used to specify the result of +
Methods and Types.
template gen_type<Ranges>::typeThis type generator is used to specify the result of
Rangeschained calls toextent_gen::operator[].The typesextent_genand @@ -1172,7 +1186,7 @@ operator[](index idx) const;This function returns a ne
extent_rangeobjects in addition toextent_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.
@@ -1180,7 +1194,7 @@ expressions involving them create other objects of interest.
considered excessive overhead. Their construction can be prevented by
defining the preprocessor symbol
BOOST_MULTI_ARRAY_NO_GENERATORS before including
-boost/multi_array.hpp.
+boost/multi_array.hpp.namespace boost { multi_array_base::extent_gen extents; } @@ -1192,7 +1206,7 @@ a 3 by 3 by 3multi_arrayis constructed as follomulti_array<int,3> A(extents[3][3][3]);The same array could also be created by explicitly declaring an
extent_genobject locally,, but the global object makes this declaration unnecessary. -
Boost.MultiArray provides traits classes, subarray_gen,
const_subarray_gen,
array_view_gen,
@@ -1233,7 +1247,7 @@ void my_function() {
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 @@ -1321,7 +1335,7 @@ 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(); }; @@ -1329,14 +1343,14 @@ class c_storage_order { 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_orderis 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.
By default, the array access methods operator() and
operator[] perform range
checking. If a supplied index is out of the range defined for an
diff --git a/doc/xml/MultiArray.xml b/doc/xml/MultiArray.xml
index 0cf7580..5978b07 100644
--- a/doc/xml/MultiArray.xml
+++ b/doc/xml/MultiArray.xml
@@ -248,15 +248,17 @@ iterators. It is the same type as