diff --git a/doc/reference.html b/doc/reference.html index 6bf6030..7cee519 100644 --- a/doc/reference.html +++ b/doc/reference.html @@ -1,29 +1,29 @@ -Boost.MultiArray Reference Manual

Boost.MultiArray Reference Manual

Ronald Garcia

Indiana University
Open Systems Lab

Copyright © 2002 The Trustees of Indiana University

Table of Contents

Library Synopsis
MultiArray Concept
Notation
Associated Types
Valid expressions
Complexity guarantees
Invariants
Associated Types for Views
Models
Array Components
multi_array
multi_array_ref
const_multi_array_ref
Auxiliary Components
multi_array_types
extent_range
extent_gen
Global Objects
View and SubArray Generators
Memory Layout Specifiers
Range Checking

Boost.MultiArray is composed of several components. +Boost.MultiArray Reference Manual

Boost.MultiArray Reference Manual

Ronald Garcia

Indiana University
Open Systems Lab

Copyright © 2002 The Trustees of Indiana University

Table of Contents

Library Synopsis
MultiArray Concept
Notation
Associated Types
Valid expressions
Complexity guarantees
Invariants
Associated Types for Views
Models
Array Components
multi_array
multi_array_ref
const_multi_array_ref
Auxiliary Components
multi_array_types
extent_range
extent_gen
Global Objects
View and SubArray Generators
Memory Layout Specifiers
Range Checking

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 -that models MultiArray. multi_array_ref -and const_multi_array_ref are adapter +multi_array is a general purpose container class +that models MultiArray. multi_array_ref +and const_multi_array_ref are adapter classes. Using them, you can manipulate any block of contiguous data as though it were a -multi_array. -const_multi_array_ref differs from -multi_array_ref in that its elements cannot +multi_array. +const_multi_array_ref differs from +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.

Library Synopsis

To use Boost.MultiArray, you must include the header -boost/multi_array.hpp in your source. This file +part of the library interface.

Library Synopsis

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 {
   
   namespace multi_array_types {
-    typedef *implementation-defined* index;
-    typedef *implementation-defined* size_type;
-    typedef *implementation-defined* difference_type;
-    typedef *implementation-defined* index_range;
-    typedef *implementation-defined* extent_range;
-    typedef *implementation-defined* index_gen;
-    typedef *implementation-defined* extent_gen;
+    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;
   }
 
   template <typename ValueType, 
@@ -52,7 +52,7 @@ namespace boost {
   template <std::size_t NumDims> class general_storage_order;
 
 }
-

MultiArray Concept

The MultiArray +

MultiArray Concept

The MultiArray concept defines an interface to hierarchically nested containers. It specifies operations for accessing elements, traversing containers, and creating views @@ -91,39 +91,39 @@ example, given a 3-dimensional "cube" of elements, a 2-dimensional slice can be viewed as if it were an independent MultiArray. -Views are created using index_gen and -index_range objects. -index_ranges denote elements from a certain +Views are created using index_gen and +index_range objects. +index_ranges denote elements from a certain dimension that are to be included in a -view. index_gen aggregates range data and performs +view. index_gen aggregates range data and performs bookkeeping to determine the view type to be returned. -MultiArray's operator[] +MultiArray's operator[] must be passed the result -of N chained calls to -index_gen::operator[], i.e. +of N chained calls to +index_gen::operator[], i.e. 

indices[a0][a1]...[aN];

-where N is the +where N is the MultiArray's dimensionality and -indices an object of type index_gen. +indices an object of type index_gen. The view type is dependent upon the number of degenerate dimensions -specified to index_gen. A degenerate dimension +specified to index_gen. A degenerate dimension occurs when a single-index is specified to -index_gen for a certain dimension. For example, if -indices is an object of type -index_gen, then the following example: +index_gen for a certain dimension. For example, if +indices is an object of type +index_gen, then the following example: 

indices[index_range(0,5)][2][index_range(0,4)];

has a degenerate second dimension. The view generated from the above -specification will have 2 dimensions with shape 5 x 4. -If the "2" above were replaced with -another index_range object, for example: +specification will have 2 dimensions with shape 5 x 4. +If the "2" above were replaced with +another index_range object, for example: 

indices[index_range(0,5)][index_range(0,2)][index_range(0,4)];

@@ -134,8 +134,8 @@ information regarding the memory layout of its contained elements. Its memory model for elements is completely defined by 4 properties: the origin, shape, index bases, and strides. The origin is the address in memory of the element -accessed as a[0][0]...[0], where -a is a MultiArray. The shape is a list of numbers +accessed as a[0][0]...[0], where +a is a MultiArray. The shape is a list of numbers specifying the size of containers at each dimension. For example, the first extent is the size of the outermost container, the second extent is the size of its subcontainers, and so on. The index bases are a @@ -150,41 +150,50 @@ 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). -

Notation

What follows are the descriptions of symbols that will be used -to describe the MultiArray interface.

Table 1. Notation

AA type that is a model of MultiArray -
aAn object of type A
NumDimsThe numeric dimension parameter associated with -A.
DimsSome numeric dimension parameter such that -0<Dims<NumDims. -
indicesAn object created by some number of chained calls -to index_gen::operator[](index_range).
index_listAn object whose type models -Collection
idxA signed integral value.
tmpAn object of type - boost::array<index,NumDims>

Associated Types

-

Table 2. Associated Types

TypeDescription
value_typeThis is the value type of the container. - If NumDims == 1, then this is -element. Otherwise, this is the value type of the +

Notation

What follows are the descriptions of symbols that will be used +to describe the MultiArray interface.

Table 1. Notation

AA type that is a model of MultiArray +
a,bObjects of type A
NumDimsThe numeric dimension parameter associated with +A.
DimsSome numeric dimension parameter such that +0<Dims<NumDims. +
indicesAn object created by some number of chained calls +to index_gen::operator[](index_range).
index_listAn object whose type models +Collection +
idxA signed integral value.
tmpAn object of type + boost::array<index,NumDims>

Associated Types

+

Table 2. Associated Types

TypeDescription
value_typeThis is the value type of the container. + If NumDims == 1, then this is +element. Otherwise, this is the value type of the immediately nested containers. -
reference +
+reference + This is the reference type of the contained value. -If NumDims == 1, then this is -element&. Otherwise, this is the same type as -template subarray<NumDims-1>::type. -
const_reference +If NumDims == 1, then this is +element&. Otherwise, this is the same type as +template subarray<NumDims-1>::type. +
+const_reference + This is the const reference type of the contained value. -If NumDims == 1, then this is -const element&. Otherwise, this is the same +If NumDims == 1, then this is +const element&. Otherwise, this is the same type as -template const_subarray<NumDims-1>::type. -
size_type +template const_subarray<NumDims-1>::type. +
+size_type + This is an unsigned integral type. It is primarily used to specify array shape. -
difference_type +
+difference_type + This is a signed integral type used to represent the distance between two iterators. It is the same type as -std::iterator_traits<iterator>::difference_type. -
iterator -This is an iterator over the values of A. -If NumDims == 1, then it models +std::iterator_traits<iterator>::difference_type. +
iterator +This is an iterator over the values of A. +If NumDims == 1, then it models -Random Access Iterator. +Random Access Iterator. Otherwise it models Random Access Traversal Iterator, @@ -192,72 +201,99 @@ Random Access Traversal Iterator, Readable Iterator, and Writable Iterator. -
const_iterator -This is the const iterator over the values of A. -
reverse_iterator +
+const_iterator + +This is the const iterator over the values of A. +
+reverse_iterator + This is the reversed iterator, used to iterate backwards over the values of -A. -
const_reverse_iterator +A. +
+const_reverse_iterator + This is the reversed const iterator. -A. -
element +A. +
+element + This is the type of objects stored at the base of the hierarchy of MultiArrays. It is the same as -template subarray<1>::value_type
index -This is a signed integral type used for indexing into A. It +template subarray<1>::value_type +
+index + +This is a signed integral type used for indexing into A. It is also used to represent strides and index bases. -
index_gen -This type is used to create a tuple of index_ranges -passed to operator[] to create -an array_view<Dims>::type object. -
index_range +
+index_gen + +This type is used to create a tuple of index_ranges +passed to operator[] to create +an array_view<Dims>::type object. +
+index_range + This type specifies a range of indices over some dimension of a MultiArray. This range will be visible through an -array_view<Dims>::type object. -
template subarray<Dims>::type -This is subarray type with Dims dimensions. -It is the reference type of the (NumDims - Dims) -dimension of A and also models +array_view<Dims>::type object. +
+template subarray<Dims>::type + +This is subarray type with Dims dimensions. +It is the reference type of the (NumDims - Dims) +dimension of A and also models MultiArray. -
template const_subarray<Dims>::type +
+template const_subarray<Dims>::type + This is the const subarray type. -
template array_view<Dims>::type -This is the view type with Dims dimensions. It is -returned by calling operator[](indices). +
+template array_view<Dims>::type + +This is the view type with Dims dimensions. It is +returned by calling operator[](indices). It models MultiArray. -
template -const_array_view<Dims>::type -This is the const view type with Dims dimensions. -

Valid expressions

Table 3. Valid Expressions

ExpressionReturn typeSemantics
a.shape()const size_type* -This returns a list of NumDims elements specifying the +
+template +const_array_view<Dims>::type + +This is the const view type with Dims dimensions. +

Valid expressions

Table 3. Valid Expressions

ExpressionReturn typeSemantics
a.shape()const size_type* +This returns a list of NumDims elements specifying the extent of each array dimension. -
a.strides()const index* -This returns a list of NumDims elements specifying the +
a.strides()const index* +This returns a list of NumDims elements specifying the stride associated with each array dimension. When accessing values, strides is used to calculate an element's location in memory. -
a.index_bases()const index* -This returns a list of NumDims elements specifying the +
a.index_bases()const index* +This returns a list of NumDims elements specifying the numeric index of the first element for each array dimension. -
a.origin()element* if a is mutable, -const element* otherwise. +
a.origin() +element* if a is mutable, +const element* otherwise. This returns the address of the element accessed by the expression -a[0][0]...[0].. If the index bases are positive, +a[0][0]...[0].. If the index bases are positive, this element won't exist, but the address can still be used to locate a valid element given its indices. -
a.num_dimensions()size_typeThis returns the number of dimensions of the array -(note that a.num_dimensions() == NumDims).
a.num_elements()size_typeThis returns the number of elements contained +
a.num_dimensions()size_typeThis returns the number of dimensions of the array +(note that a.num_dimensions() == NumDims).
a.num_elements()size_typeThis returns the number of elements contained in the array. It is equivalent to the following code: 
 std::accumulate(a.shape(),a.shape+a.num_dimensions(),
     size_type(1),std::multiplies<size_type>());
-
a.size()size_type + +
a.size()size_type This returns the number of values contained in -a. It is equivalent to a.shape()[0];
a(index_list)element&; if a is mutable, -const element& otherwise. +a. It is equivalent to a.shape()[0]; +
a(index_list) +element&; if a is mutable, +const element& otherwise. This expression accesses a specific element of -a.index_list is the unique set +a.index_list is the unique set of indices that address the element returned. It is equivalent to the following code (disregarding intermediate temporaries): 
@@ -267,88 +303,96 @@ equivalent to the following code (disregarding intermediate temporaries):
 
     // add the sum of the products to the origin
     *std::accumulate(tmp.begin(), tmp.end(), a.origin());
-
a.begin()iterator if a is mutable, -const_iterator otherwise. + +
a.begin() +iterator if a is mutable, +const_iterator otherwise. This returns an iterator pointing to the beginning of -a.
a.end()iterator if a is mutable, -const_iterator otherwise. +a.
a.end() +iterator if a is mutable, +const_iterator otherwise. This returns an iterator pointing to the end of -a.
a.rbegin()reverse_iterator if a is mutable, -const_reverse_iterator otherwise. +a.
a.rbegin() +reverse_iterator if a is mutable, +const_reverse_iterator otherwise. This returns a reverse iterator pointing to the -beginning of a reversed. -
a.rend()reverse_iterator if a is mutable, -const_reverse_iterator otherwise. +beginning of a reversed. +
a.rend() +reverse_iterator if a is mutable, +const_reverse_iterator otherwise. -This returns a reverse iterator pointing to the end of a +This returns a reverse iterator pointing to the end of a reversed. -
a[idx]reference if a is mutable, -const_reference otherwise. +
a[idx] +reference if a is mutable, +const_reference otherwise. This returns a reference type that is bound to the index -idx value of a. Note that if -i is the index base for this dimension, the above -expression returns the (idx-i)th element (counting +idx value of a. Note that if +i is the index base for this dimension, the above +expression returns the (idx-i)th element (counting from zero). The expression is equivalent to -*(a.begin()+idx-a.index_bases()[0]);. -
a[indices]array_view<Dims>::type if -a is mutable, -const_array_view<Dims>::type otherwise. +*(a.begin()+idx-a.index_bases()[0]);. +
a[indices] +array_view<Dims>::type if +a is mutable, +const_array_view<Dims>::type otherwise. This expression generates a view of the array determined by the -index_range and index values - used to construct indices. -
a == bboolThis performs a lexicographical comparison of the -values of a and b. The element +index_range and index values + used to construct indices. +
a == bboolThis performs a lexicographical comparison of the +values of a and b. The element type must model EqualityComparable for this -expression to be valid.
a < bboolThis performs a lexicographical comparison of the -values of a and b. The element +expression to be valid.
a < bboolThis performs a lexicographical comparison of the +values of a and b. The element type must model LessThanComparable for this -expression to be valid.
a <= bboolThis performs a lexicographical comparison of the -values of a and b. The element +expression to be valid.
a <= bboolThis performs a lexicographical comparison of the +values of a and b. The element type must model EqualityComparable and LessThanComparable for this -expression to be valid.
a > bboolThis performs a lexicographical comparison of the -values of a and b. The element +expression to be valid.
a > bboolThis performs a lexicographical comparison of the +values of a and b. The element type must model EqualityComparable and LessThanComparable for this -expression to be valid.
a >= bboolThis performs a lexicographical comparison of the -values of a and b. The element +expression to be valid.
a >= bboolThis performs a lexicographical comparison of the +values of a and b. The element type must model LessThanComparable for this -expression to be valid.

Complexity guarantees

begin() and end() execute in amortized +expression to be valid.

Complexity guarantees

begin() and end() execute in amortized constant time. -size() executes in at most linear time in the +size() executes in at most linear time in the MultiArray's size. -

Invariants

Table 4. Invariants

Valid range[a.begin(),a.end()) is a valid range. -
Range sizea.size() == std::distance(a.begin(),a.end());. +

Invariants

Table 4. Invariants

Valid range[a.begin(),a.end()) is a valid range. +
Range size +a.size() == std::distance(a.begin(),a.end());.
Completeness Iteration through the range -[a.begin(),a.end()) will traverse across every -value_type of a. +[a.begin(),a.end()) will traverse across every +value_type of a.
Accessor Equivalence -Calling a[a1][a2]...[aN] where N==NumDims +Calling a[a1][a2]...[aN] where N==NumDims yields the same result as calling -a(index_list), where index_list -is a Collection containing the values a1...aN. -

Associated Types for Views

The following MultiArray associated +a(index_list), where index_list +is a Collection containing the values a1...aN. +

Associated Types for Views

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

index_range objects represent half-open +concept are described below.

index_range

index_range objects represent half-open strided intervals. They are aggregated (using an -index_gen object) and passed to -a MultiArray's operator[] +index_gen object) and passed to +a MultiArray's operator[] to create an array view. When creating a view, -each index_range denotes a range of +each index_range denotes a range of valid indices along one dimension of a MultiArray. Elements that are accessed through the set of ranges specified will be included in the constructed view. In some cases, an -index_range is created without specifying start +index_range is created without specifying start or finish values. In those cases, the object is interpreted to start at the beginning of a MultiArray dimension and end at its end.

-index_range objects can be constructed and modified +index_range objects can be constructed and modified several ways in order to allow convenient and clear expression of a -range of indices. To specify ranges, index_range +range of indices. To specify ranges, index_range supports a set of constructors, mutating member functions, and a novel specification involving inequality operators. Using inequality operators, a half open range [5,10) can be specified as follows: @@ -356,84 +400,87 @@ operators, a half open range [5,10) can be specified as follows: 

4 < index_range() <= 9;

and so on. The following describes the -index_range interface. -

Table 5. Notation

iAn object of type index_range.
idx,idx1,idx2,idx3Objects of type index.

Table 6. Associated Types

TypeDescription
indexThis is a signed integral type. It is used to -specify the start, finish, and stride values.
size_typeThis is an unsigned integral type. It is used to -report the size of the range an index_range -represents.

Table 7. Valid Expressions

ExpressionReturn typeSemantics
index_range(idx1,idx2,idx3)index_rangeThis constructs an index_range - representing the interval [idx1,idx2) - with stride idx3.
index_range(idx1,idx2)index_rangeThis constructs an index_range - representing the interval [idx1,idx2) +index_range interface. +

Table 5. Notation

iAn object of type index_range.
idx,idx1,idx2,idx3Objects of type index.

Table 6. Associated Types

TypeDescription
indexThis is a signed integral type. It is used to +specify the start, finish, and stride values.
size_typeThis is an unsigned integral type. It is used to +report the size of the range an index_range +represents.

Table 7. Valid Expressions

ExpressionReturn typeSemantics
index_range(idx1,idx2,idx3)index_rangeThis constructs an index_range + representing the interval [idx1,idx2) + with stride idx3.
index_range(idx1,idx2)index_rangeThis constructs an index_range + representing the interval [idx1,idx2) with unit stride. It is equivalent to - index_range(idx1,idx2,1).
index_range()index_rangeThis construct an index_range -with unspecified start and finish values.
i.start(idx1)index&This sets the start index of i to - idx.
i.finish(idx)index&This sets the finish index of i to - idx.
i.stride(idx)index&This sets the stride length of i to - idx.
i.start()indexThis returns the start index of i.
i.finish()indexThis returns the finish index of i.
i.stride()indexThis returns the stride length of i.
i.get_start(idx)indexIf i specifies a start -value, this is equivalent to i.start(). Otherwise it -returns idx.
i.get_finish(idx)indexIf i specifies a finish -value, this is equivalent to i.finish(). Otherwise it -returns idx.
i.size(idx)size_typeIf i specifies a both finish and + index_range(idx1,idx2,1).
index_range()index_rangeThis construct an index_range +with unspecified start and finish values.
i.start(idx1)index&This sets the start index of i to + idx.
i.finish(idx)index&This sets the finish index of i to + idx.
i.stride(idx)index&This sets the stride length of i to + idx.
i.start()indexThis returns the start index of i.
i.finish()indexThis returns the finish index of i.
i.stride()indexThis returns the stride length of i.
i.get_start(idx)indexIf i specifies a start +value, this is equivalent to i.start(). Otherwise it +returns idx.
i.get_finish(idx)indexIf i specifies a finish +value, this is equivalent to i.finish(). Otherwise it +returns idx.
i.size(idx)size_typeIf i specifies a both finish and start values, this is equivalent to -(i.finish()-i.start())/i.stride(). Otherwise it -returns idx.
i < idxindexThis is another syntax for specifying the finish +(i.finish()-i.start())/i.stride(). Otherwise it +returns idx.
i < idxindexThis is another syntax for specifying the finish value. This notation does not include -idx in the range of valid indices. It is equivalent to -index_range(r.start(), idx, r.stride())
i <= idxindexThis is another syntax for specifying the finish +idx in the range of valid indices. It is equivalent to +index_range(r.start(), idx, r.stride())
i <= idxindexThis is another syntax for specifying the finish value. This notation includes -idx in the range of valid indices. It is equivalent to -index_range(r.start(), idx + 1, r.stride())
idx < iindexThis is another syntax for specifying the start +idx in the range of valid indices. It is equivalent to +index_range(r.start(), idx + 1, r.stride())
idx < iindexThis is another syntax for specifying the start value. This notation does not include -idx in the range of valid indices. It is equivalent to -index_range(idx + 1, i.finish(), i.stride()).
idx <= iindexThis is another syntax for specifying the start +idx in the range of valid indices. It is equivalent to +index_range(idx + 1, i.finish(), i.stride()).
idx <= iindexThis is another syntax for specifying the start value. This notation includes -idx1 in the range of valid indices. It is equivalent to -index_range(idx, i.finish(), i.stride()).
i + idxindexThis expression shifts the start and finish values -of i up by idx. It is equivalent to -index_range(r.start()+idx1, r.finish()+idx, r.stride())
i - idxindexThis expression shifts the start and finish values -of i up by idx. It is equivalent to -index_range(r.start()-idx1, r.finish()-idx, r.stride())

index_gen

index_gen aggregates -index_range objects in order to specify view -parameters. Chained calls to operator[] store +idx1 in the range of valid indices. It is equivalent to +index_range(idx, i.finish(), i.stride()).

i + idxindexThis expression shifts the start and finish values +of i up by idx. It is equivalent to +index_range(r.start()+idx1, r.finish()+idx, r.stride())
i - idxindexThis expression shifts the start and finish values +of i up by idx. It is equivalent to +index_range(r.start()-idx1, r.finish()-idx, r.stride())

index_gen

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,RangesUnsigned integral values.
xAn object of type -template gen_type<Dims,Ranges>::type.
iAn object of type -index_range.
idxObjects of type index.

Table 9. Associated Types

TypeDescription
indexThis is a signed integral type. It is used to -specify degenerate dimensions.
size_typeThis is an unsigned integral type. It is used to -report the size of the range an index_range -represents.
template gen_type::<Dims,Ranges>::typeThis type generator names the result of -Dims chained calls to -index_gen::operator[]. The -Ranges parameter is determined by the number of +

Table 8. Notation

Dims,RangesUnsigned integral values.
xAn object of type +template gen_type<Dims,Ranges>::type.
iAn object of type +index_range.
idxObjects of type index.

Table 9. Associated Types

TypeDescription
indexThis is a signed integral type. It is used to +specify degenerate dimensions.
size_typeThis is an unsigned integral type. It is used to +report the size of the range an index_range +represents.
+template gen_type::<Dims,Ranges>::typeThis type generator names the result of +Dims chained calls to +index_gen::operator[]. The +Ranges parameter is determined by the number of degenerate ranges specified (i.e. calls to -operator[](index)). Note that -index_gen and -gen_type<0,0>::type are the same type.

Table 10. Valid Expressions

ExpressionReturn typeSemantics
index_gen()gen_type<0,0>::typeThis constructs an index_gen +operator[](index)). Note that +index_gen and +gen_type<0,0>::type are the same type.

Table 10. Valid Expressions

ExpressionReturn typeSemantics
index_gen()gen_type<0,0>::typeThis constructs an index_gen object. This object can then be used to generate tuples of -index_range values.
x[i]gen_type<Dims+1,Ranges+1>::typeReturns a new object containing all previous -index_range objects in addition to -i. Chained calls to -operator[] are the means by which -index_range objects are aggregated.
x[idx]gen_type<Dims,Ranges>::typeReturns a new object containing all previous -index_range objects in addition to a degenerate -range, index_range(idx,idx). Note that this is NOT -equivalent to x[index_range(idx,idx)]., which will +index_range values.
x[i]gen_type<Dims+1,Ranges+1>::type +Returns a new object containing all previous +index_range objects in addition to +i. Chained calls to +operator[] are the means by which +index_range objects are aggregated.
x[idx]gen_type<Dims,Ranges>::type +Returns a new object containing all previous +index_range objects in addition to a degenerate +range, index_range(idx,idx). Note that this is NOT +equivalent to x[index_range(idx,idx)]., which will return an object of type -gen_type<Dims+1,Ranges+1>::type. -

Models

  • multi_array
  • multi_array_ref
  • const_multi_array_ref
  • template array_view<Dims>::type
  • template const_array_view<Dims>::type
  • template subarray<Dims>::type
  • template const_subarray<Dims>::type

Array Components

+gen_type<Dims+1,Ranges+1>::type. +

Models

  • multi_array
  • multi_array_ref
  • const_multi_array_ref
  • template array_view<Dims>::type
  • template const_array_view<Dims>::type
  • template subarray<Dims>::type
  • template const_subarray<Dims>::type

Array Components

Boost.MultiArray defines an array class, -multi_array, and two adapter classes, -multi_array_ref and -const_multi_array_ref. The three classes model +multi_array, and two adapter classes, +multi_array_ref and +const_multi_array_ref. The three classes model MultiArray and so they share a lot of functionality. -multi_array_ref differs from -multi_array in that the -multi_array manages its own memory, while -multi_array_ref is passed a block of memory that it +multi_array_ref differs from +multi_array in that the +multi_array manages its own memory, while +multi_array_ref is passed a block of memory that it expects to be externally managed. -const_multi_array_ref differs from -multi_array_ref in that the underlying elements it +const_multi_array_ref differs from +multi_array_ref in that the underlying elements it 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 @@ -453,20 +500,20 @@ operation. const element* data() const;

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 -equivalent to origin(). Note that -const_multi_array_ref only provides the const +equivalent to origin(). Note that +const_multi_array_ref only provides the const version of this function. 

element* origin();
 const element* origin() const;

This returns the origin element of the -multi_array. Note that -const_multi_array_ref only provides the const +multi_array. Note that +const_multi_array_ref only provides the const version of this function. (Required by MultiArray) -

const index* index_bases();

This returns the index bases for the -multi_array. (Required by MultiArray) -

const index* strides();

This returns the strides for the -multi_array. (Required by MultiArray) -

const size_type* shape();

This returns the shape of the -multi_array. (Required by MultiArray) +

const index* index_bases();

This returns the index bases for the +multi_array. (Required by MultiArray) +

const index* strides();

This returns the strides for the +multi_array. (Required by MultiArray) +

const size_type* shape();

This returns the shape of the +multi_array. (Required by MultiArray)

Comparators. 

 bool operator==(const *array-type*& rhs);
 bool operator!=(const *array-type*& rhs);
@@ -476,25 +523,25 @@ bool operator>=(const *array-type*& rhs);
 bool operator<=(const *array-type*& rhs);

Each comparator executes a lexicographical compare over the value types of the two arrays. (Required by MultiArray) -

Preconditions. element must support the +

Preconditions. element must support the comparator corresponding to that called on -multi_array.

Complexity. O(num_elements()).

Modifiers. 

+multi_array.

Complexity. O(num_elements()).

Modifiers. 

 
 template <typename SizeList>
 void reshape(const SizeList& sizes)
-

This changes the shape of the multi_array. The +

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.

SizeList Requirements. SizeList must model +change.

SizeList Requirements. SizeList must model Collection.

Preconditions.  

 std::accumulate(sizes.begin(),sizes.end(),size_type(1),std::times<size_type>()) == this->num_elements();
 sizes.size() == NumDims;

Postconditions.  -std::equal(sizes.begin(),sizes.end(),this->shape) == true; +std::equal(sizes.begin(),sizes.end(),this->shape) == true; 

 
@@ -502,17 +549,17 @@ template <typename BaseList>
 void reindex(const BaseList& values);
-

This changes the index bases of the multi_array to -correspond to the the values in values.

BaseList Requirements. BaseList must model -Collection.

Preconditions. values.size() == NumDims;

Postconditions. std::equal(values.begin(),values.end(),this->index_bases()); -

+

This changes the index bases of the multi_array to +correspond to the the values in values.

BaseList Requirements. BaseList must model +Collection.

Preconditions. values.size() == NumDims;

Postconditions. std::equal(values.begin(),values.end(),this->index_bases()); +

 
 void reindex(index value);

This changes the index bases of all dimensions of the -multi_array to value.

Postconditions.  +multi_array to value.

Postconditions.  

 
 std::count_if(this->index_bases(),this->index_bases()+this->num_dimensions(),
@@ -520,14 +567,14 @@ std::count_if(this->index_bases(),this->index_bases()+this->num_dimensi
               this->num_dimensions();

-

multi_array

-multi_array is a multi-dimensional container that +

multi_array

+multi_array is 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 contains are specified during its construction. The number of elements will remain fixed for the duration of a -multi_array's lifetime, but the shape of the container can -be changed. A multi_array manages its data elements +multi_array's lifetime, but the shape of the container can +be changed. A multi_array manages its data elements using a replaceable allocator.

Model Of.  MultiArray, @@ -544,21 +591,21 @@ class multi_array { public: // types: typedef ValueType element; - typedef *implementation-defined* value_type; - typedef *implementation-defined* reference; - typedef *implementation-defined* const_reference; - typedef *implementation-defined* difference_type; - typedef *implementation-defined* iterator; - typedef *implementation-defined* const_iterator; - typedef *implementation-defined* reverse_iterator; - typedef *implementation-defined* const_reverse_iterator; + typedef *unspecified* value_type; + typedef *unspecified* reference; + typedef *unspecified* const_reference; + typedef *unspecified* difference_type; + typedef *unspecified* iterator; + typedef *unspecified* const_iterator; + typedef *unspecified* reverse_iterator; + typedef *unspecified* const_reverse_iterator; typedef multi_array_types::size_type size_type; typedef multi_array_types::index index; typedef multi_array_types::index_gen index_gen; typedef multi_array_types::index_range index_range; typedef multi_array_types::extent_gen extent_gen; typedef multi_array_types::extent_range extent_range; - typedef *implementation-defined* storage_order_type; + typedef *unspecified* storage_order_type; // template typedefs @@ -655,27 +702,27 @@ explicit multi_array(const ExtentList& sizes, const storage_order_type& store = c_storage_order(), const Allocator& alloc = Allocator());

-This constructs a multi_array using the specified -parameters. sizes specifies the shape of the -constructed multi_array. store +This constructs a multi_array using the specified +parameters. sizes specifies the shape of the +constructed multi_array. store specifies the storage order or layout in memory of the array -dimensions. alloc is used to +dimensions. alloc is used to allocate the contained elements. -

ExtentList Requirements.  -ExtentList must model Collection. -

Preconditions. sizes.size() == NumDims;

+

ExtentList Requirements.  +ExtentList must 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());

-This constructs a multi_array using the specified - parameters. ranges specifies the shape and +This constructs a multi_array using the specified + parameters. ranges specifies the shape and index bases of the constructed multi_array. It is the result of -NumDims chained calls to - extent_gen::operator[]. store +NumDims chained calls to + extent_gen::operator[]. store specifies the storage order or layout in memory of the array -dimensions. alloc is the allocator used to -allocate the memory used to store multi_array +dimensions. alloc is the allocator used to +allocate the memory used to store multi_array elements. 

 multi_array(const multi_array& x);
@@ -685,16 +732,16 @@ multi_array(const const_array_view<NumDims>::type& x);
 multi_array(const multi_array_ref<ValueType,NumDims>& x);
 multi_array(const subarray<NumDims>::type& x);
 multi_array(const array_view<NumDims>::type& x);
-

These constructors all constructs a multi_array and -perform a deep copy of x. -

Complexity.  This performs O(x.num_elements()) calls to -element's copy +

These constructors all constructs a multi_array and +perform a deep copy of x. +

Complexity.  This performs O(x.num_elements()) calls to +element's copy constructor. 

 multi_array();
-

This constructs a multi_array whose shape is (0,...,0) and contains no elements. +

This constructs a multi_array whose shape is (0,...,0) and contains no elements.

Note on Constructors.  -The multi_array construction expressions, +The multi_array construction expressions, 

      multi_array<int,3> A(boost::extents[5][4][3]);

@@ -708,14 +755,14 @@ are equivalent. multi_array& operator=(const multi_array& x); template <class Array> multi_array& operator=(const Array& x); -

This performs an element-wise copy of x -into the current multi_array.

Array Requirements. Array must model MultiArray. +

This performs an element-wise copy of x +into the current multi_array.

Array Requirements. Array must model MultiArray.

Preconditions.  

std::equal(this->shape(),this->shape()+this->num_dimensions(),
 x.shape());

Postconditions.  

(*.this) == x;

Complexity. The assignment operators perform -O(x.num_elements()) calls to element's +O(x.num_elements()) calls to element's copy constructor.

 
@@ -723,13 +770,13 @@ template <typename InputIterator>
 void assign(InputIterator begin, InputIterator end);

This copies the elements in the range -[begin,end) into the array. It is equivalent to -std::copy(begin,end,this->data()). -

Preconditions. std::distance(begin,end) == this->num_elements(); +[begin,end) into the array. It is equivalent to +std::copy(begin,end,this->data()). +

Preconditions. std::distance(begin,end) == this->num_elements();

Complexity.  -The assign member function performs -O(this->num_elements()) calls to -ValueType's copy constructor. +The assign member function performs +O(this->num_elements()) calls to +ValueType's copy constructor. 

multi_array& resize(extent_gen::gen_type<NumDims>::type extents);
 template <typename ExtentList>
@@ -737,30 +784,30 @@ template <typename ExtentList>

This function resizes an array to the shape specified by -extents, which is either a generated list of -extents or a model of the Collection concept. The +extents, which is either a generated list of +extents or a model of the Collection concept. The 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 the -element default constructor. +element default constructor.

Queries. 

 storage_order_type& storage_order() const;

This query returns the storage order object associated with the -multi_array in question. It can be used to construct a new array with the same storage order.

multi_array_ref

-multi_array_ref is a multi-dimensional container +multi_array in question. It can be used to construct a new array with the same storage order.

multi_array_ref

+multi_array_ref is a multi-dimensional container adaptor. It provides the MultiArray interface over any contiguous -block of elements. multi_array_ref exports the -same interface as multi_array, with the exception +block of elements. multi_array_ref exports the +same interface as multi_array, with the exception of the constructors.

Model Of.  -multi_array_ref models +multi_array_ref models MultiArray, CopyConstructible. and depending on the element type, it may also model EqualityComparable and LessThanComparable. Detailed descriptions are provided here only for operations that are -not described in the multi_array reference. +not described in the multi_array reference.

Synopsis. 

 
 namespace boost {
@@ -772,21 +819,21 @@ class multi_array_ref {
 public:
 // types:
   typedef ValueType                             element;
-  typedef *implementation-defined*              value_type;
-  typedef *implementation-defined*              reference;
-  typedef *implementation-defined*              const_reference;
-  typedef *implementation-defined*              difference_type;
-  typedef *implementation-defined*              iterator;
-  typedef *implementation-defined*              const_iterator;
-  typedef *implementation-defined*              reverse_iterator;
-  typedef *implementation-defined*              const_reverse_iterator;
+  typedef *unspecified*                         value_type;
+  typedef *unspecified*                         reference;
+  typedef *unspecified*                         const_reference;
+  typedef *unspecified*                         difference_type;
+  typedef *unspecified*                         iterator;
+  typedef *unspecified*                         const_iterator;
+  typedef *unspecified*                         reverse_iterator;
+  typedef *unspecified*                         const_reverse_iterator;
   typedef multi_array_types::size_type          size_type;
   typedef multi_array_types::index              index;
   typedef multi_array_types::index_gen          index_gen;
   typedef multi_array_types::index_range        index_range;
   typedef multi_array_types::extent_gen         extent_gen;
   typedef multi_array_types::extent_range       extent_range;
-  typedef *implementation-defined*              storage_order_type;
+  typedef *unspecified*                         storage_order_type;
   
   // template typedefs
   template <std::size_t Dims> struct            subarray;
@@ -868,58 +915,58 @@ explicit multi_array_ref(element* data,
                      const storage_order& store = c_storage_order(),
                      const Allocator& alloc = Allocator());

-This constructs a multi_array_ref using the specified -parameters. sizes specifies the shape of the -constructed multi_array_ref. store +This constructs a multi_array_ref using the specified +parameters. sizes specifies the shape of the +constructed multi_array_ref. store specifies the storage order or layout in memory of the array -dimensions. alloc is used to +dimensions. alloc is used to allocate the contained elements. -

ExtentList Requirements.  -ExtentList must model Collection. -

Preconditions. sizes.size() == NumDims;

+

ExtentList Requirements.  +ExtentList must 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());

-This constructs a multi_array_ref using the specified - parameters. ranges specifies the shape and +This constructs a multi_array_ref using the specified + parameters. ranges specifies the shape and index bases of the constructed multi_array_ref. It is the result of -NumDims chained calls to - extent_gen::operator[]. store +NumDims chained calls to + extent_gen::operator[]. store specifies the storage order or layout in memory of the array dimensions. 

 multi_array_ref(const multi_array_ref& x);
-

This constructs a shallow copy of x. +

This constructs a shallow copy of x.

Complexity.  Constant time (for contrast, compare this to -the multi_array class copy constructor. +the multi_array class copy constructor.

Modifiers. 

 multi_array_ref& operator=(const multi_array_ref& x);
 template <class Array> multi_array_ref& operator=(const Array& x);
-

This performs an element-wise copy of x -into the current multi_array_ref.

Array Requirements. Array must model MultiArray. +

This performs an element-wise copy of x +into the current multi_array_ref.

Array Requirements. Array must model MultiArray.

Preconditions.  

std::equal(this->shape(),this->shape()+this->num_dimensions(),
 x.shape());

Postconditions.  

(*.this) == x;

Complexity. The assignment operators perform -O(x.num_elements()) calls to element's -copy constructor.

const_multi_array_ref

-const_multi_array_ref is a multi-dimensional container +O(x.num_elements()) calls to element's +copy constructor.

const_multi_array_ref

+const_multi_array_ref is a multi-dimensional container adaptor. It provides the MultiArray interface over any contiguous -block of elements. const_multi_array_ref exports the -same interface as multi_array, with the exception +block of elements. const_multi_array_ref exports the +same interface as multi_array, with the exception of the constructors.

Model Of.  -const_multi_array_ref models +const_multi_array_ref models MultiArray, CopyConstructible. and depending on the element type, it may also model EqualityComparable and LessThanComparable. Detailed descriptions are provided here only for operations that are -not described in the multi_array reference. +not described in the multi_array reference.

Synopsis. 

 
 namespace boost {
@@ -931,21 +978,21 @@ class const_multi_array_ref {
 public:
 // types:
   typedef ValueType                             element;
-  typedef *implementation-defined*              value_type;
-  typedef *implementation-defined*              reference;
-  typedef *implementation-defined*              const_reference;
-  typedef *implementation-defined*              difference_type;
-  typedef *implementation-defined*              iterator;
-  typedef *implementation-defined*              const_iterator;
-  typedef *implementation-defined*              reverse_iterator;
-  typedef *implementation-defined*              const_reverse_iterator;
+  typedef *unspecified*                         value_type;
+  typedef *unspecified*                         reference;
+  typedef *unspecified*                         const_reference;
+  typedef *unspecified*                         difference_type;
+  typedef *unspecified*                         iterator;
+  typedef *unspecified*                         const_iterator;
+  typedef *unspecified*                         reverse_iterator;
+  typedef *unspecified*                         const_reverse_iterator;
   typedef multi_array_types::size_type          size_type;
   typedef multi_array_types::index              index;
   typedef multi_array_types::index_gen          index_gen;
   typedef multi_array_types::index_range        index_range;
   typedef multi_array_types::extent_gen         extent_gen;
   typedef multi_array_types::extent_range       extent_range;
-  typedef *implementation-defined*              storage_order_type;
+  typedef *unspecified*                         storage_order_type;
   
   // template typedefs
   template <std::size_t Dims> struct            subarray;
@@ -1011,57 +1058,57 @@ explicit const_multi_array_ref(const element* data,
                      const ExtentList& sizes,
                      const storage_order& store = c_storage_order());

-This constructs a const_multi_array_ref using the specified -parameters. sizes specifies the shape of the -constructed const_multi_array_ref. store +This constructs a const_multi_array_ref using the specified +parameters. sizes specifies the shape of the +constructed const_multi_array_ref. store specifies the storage order or layout in memory of the array dimensions. -

ExtentList Requirements.  -ExtentList must model Collection. -

Preconditions. sizes.size() == NumDims;

+

ExtentList Requirements.  +ExtentList must model Collection. +

Preconditions. sizes.size() == NumDims;

explicit const_multi_array_ref(const element* data,
                      extent_gen::gen_type<NumDims>::type ranges,
                      const storage_order& store = c_storage_order());

Effects.  -This constructs a const_multi_array_ref using the specified - parameters. ranges specifies the shape and +This constructs a const_multi_array_ref using the specified + parameters. ranges specifies the shape and index bases of the constructed const_multi_array_ref. It is the result of -NumDims chained calls to - extent_gen::operator[]. store +NumDims chained calls to + extent_gen::operator[]. store specifies the storage order or layout in memory of the array dimensions. 

 const_multi_array_ref(const const_multi_array_ref& x);
-

Effects. This constructs a shallow copy of x. -

Auxiliary Components

multi_array_types

+

Effects. This constructs a shallow copy of x. +

Auxiliary Components

multi_array_types

 namespace multi_array_types {
-  typedef *implementation-defined* index;
-  typedef *implementation-defined* size_type;
-  typedef *implementation-defined* difference_type;
-  typedef *implementation-defined* index_range;
-  typedef *implementation-defined* extent_range;
-  typedef *implementation-defined* index_gen;
-  typedef *implementation-defined* extent_gen;
+  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 +

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 +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

extent_range objects define half open +concept definition. extent_gen and +extent_range are described below. +

extent_range

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 +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). +extent_gen for more details).

Synopsis. 

 class extent_range {
 public:
@@ -1077,24 +1124,24 @@ 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 -[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().

extent_gen

The extent_gen class defines an +};

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().

extent_gen

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 +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 +int values in C++ would be declared as: 

int A[3][4][5],

-a similar multi_array would be declared: +a similar multi_array would be declared: 

multi_array<int,3> A(extents[3][4][5]).

Synopsis. 

 template <std::size_t NumRanges>
@@ -1110,68 +1157,68 @@ public:
 };
 
 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 +

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 +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.

Global Objects

For syntactic convenience, Boost.MultiArray defines two +declaration.

Global Objects

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.

extents

+BOOST_MULTI_ARRAY_NO_GENERATORS before including
+boost/multi_array.hpp.
extents
 namespace boost {
   multi_array_base::extent_gen extents;
 }
 
Boost.MultiArray's array classes use the
-extents global object to specify 
+extents global object to specify 
 array shape during their construction. 
 For example,
-a 3 by 3 by 3 multi_array is constructed as follows:
+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 
+The same array could also be created by explicitly declaring an extent_gen 
 object locally,, but the global object makes this declaration unnecessary.  
-
indices
+
indices
 namespace boost {
   multi_array_base::index_gen  indices;
 }
 
The MultiArray concept specifies an
-index_gen associated type that is used to
+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
+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:
+
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)]];
 

-

View and SubArray Generators

-Boost.MultiArray provides traits classes, subarray_gen, -const_subarray_gen, -array_view_gen, -and const_array_view_gen, for naming of +

View and SubArray Generators

+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 +the correspondence between the array_view_gen +traits class and the array_view type associated to an array: 

@@ -1183,9 +1230,9 @@ void my_function() {
 }

-In the above example, view1_t and -view2_t have the same type. -

Memory Layout Specifiers

+In the above example, view1_t and +view2_t have the same type. +

Memory Layout Specifiers

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 @@ -1210,8 +1257,8 @@ 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) +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]

. @@ -1236,7 +1283,7 @@ int *a = data + 8; int s[] = { -4, 1 };

-Note that in this example a must be explicitly set +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. @@ -1257,63 +1304,63 @@ 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 +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 +(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. -

c_storage_order

+
c_storage_order
 class c_storage_order {
   c_storage_order();
 };
-
c_storage_order is used to specify that an
+

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.

fortran_storage_order

+this library.

fortran_storage_order

 class fortran_storage_order {
   fortran_storage_order();
 };
-

fortran_storage_order is used to specify that +

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.

general_storage_order

+last.

general_storage_order

 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 +

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 +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. -

Range Checking

-By default, the array access methods operator() and -operator[] perform range +

Range Checking

+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 +the BOOST_DISABLE_ASSERTS preprocessor macro prior to including multi_array.hpp in an application.

diff --git a/doc/xml/MultiArray.xml b/doc/xml/MultiArray.xml index ab42ee3..921f334 100644 --- a/doc/xml/MultiArray.xml +++ b/doc/xml/MultiArray.xml @@ -124,8 +124,8 @@ to describe the MultiArray interface. - a - An object of type A + a,b + Objects of type A NumDims diff --git a/doc/xml/const_multi_array_ref.xml b/doc/xml/const_multi_array_ref.xml index a24da04..cd845a6 100644 --- a/doc/xml/const_multi_array_ref.xml +++ b/doc/xml/const_multi_array_ref.xml @@ -38,21 +38,21 @@ class const_multi_array_ref { public: // types: typedef ValueType element; - typedef *implementation-defined* value_type; - typedef *implementation-defined* reference; - typedef *implementation-defined* const_reference; - typedef *implementation-defined* difference_type; - typedef *implementation-defined* iterator; - typedef *implementation-defined* const_iterator; - typedef *implementation-defined* reverse_iterator; - typedef *implementation-defined* const_reverse_iterator; + typedef *unspecified* value_type; + typedef *unspecified* reference; + typedef *unspecified* const_reference; + typedef *unspecified* difference_type; + typedef *unspecified* iterator; + typedef *unspecified* const_iterator; + typedef *unspecified* reverse_iterator; + typedef *unspecified* const_reverse_iterator; typedef multi_array_types::size_type size_type; typedef multi_array_types::index index; typedef multi_array_types::index_gen index_gen; typedef multi_array_types::index_range index_range; typedef multi_array_types::extent_gen extent_gen; typedef multi_array_types::extent_range extent_range; - typedef *implementation-defined* storage_order_type; + typedef *unspecified* storage_order_type; // template typedefs template struct subarray; diff --git a/doc/xml/multi_array.xml b/doc/xml/multi_array.xml index b406acf..21e6df5 100644 --- a/doc/xml/multi_array.xml +++ b/doc/xml/multi_array.xml @@ -36,21 +36,21 @@ class multi_array { public: // types: typedef ValueType element; - typedef *implementation-defined* value_type; - typedef *implementation-defined* reference; - typedef *implementation-defined* const_reference; - typedef *implementation-defined* difference_type; - typedef *implementation-defined* iterator; - typedef *implementation-defined* const_iterator; - typedef *implementation-defined* reverse_iterator; - typedef *implementation-defined* const_reverse_iterator; + typedef *unspecified* value_type; + typedef *unspecified* reference; + typedef *unspecified* const_reference; + typedef *unspecified* difference_type; + typedef *unspecified* iterator; + typedef *unspecified* const_iterator; + typedef *unspecified* reverse_iterator; + typedef *unspecified* const_reverse_iterator; typedef multi_array_types::size_type size_type; typedef multi_array_types::index index; typedef multi_array_types::index_gen index_gen; typedef multi_array_types::index_range index_range; typedef multi_array_types::extent_gen extent_gen; typedef multi_array_types::extent_range extent_range; - typedef *implementation-defined* storage_order_type; + typedef *unspecified* storage_order_type; // template typedefs @@ -136,7 +136,9 @@ public: template void reshape(const SizeList& sizes) template void reindex(const BaseList& values); - void reindex(index value); + void reindex(index value); + template + multi_array& resize(const ExtentList& extents); multi_array& resize(extents_tuple& extents); }; ]]> @@ -327,15 +329,20 @@ O(this->num_elements()) calls to -::type ranges);]]> +::type extents); +template + multi_array& resize(const ExtentList& extents); +]]> -This function resizes an array to the shape specified by -ranges. The 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 -the element default constructor. +This function resizes an array to the shape specified by +extents, which is either a generated list of +extents or a model of the Collection concept. The +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 the +element default constructor. diff --git a/doc/xml/reference.xml b/doc/xml/reference.xml index d59c857..1ca7f76 100644 --- a/doc/xml/reference.xml +++ b/doc/xml/reference.xml @@ -50,13 +50,13 @@ brings the following declarations into scope: index_bases(),this->index_bases()+this->num_dimensions(),