| <?xml version='1.0' encoding="ISO-Latin-1" ?> |
| <!DOCTYPE article |
| PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" |
| "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" [ |
| <!ENTITY concepts SYSTEM "MultiArray.xml"> |
| <!ENTITY multi_array SYSTEM "multi_array.xml"> |
| <!ENTITY multi_array_ref SYSTEM "multi_array_ref.xml"> |
| <!ENTITY const_multi_array_ref SYSTEM "const_multi_array_ref.xml"> |
| ]> |
| |
| <article> |
| <articleinfo> |
| <title>Boost.MultiArray Reference Manual</title> |
| <author> |
| <surname>Garcia</surname><firstname>Ronald</firstname> |
| <affiliation> |
| <orgname>Indiana University</orgname> |
| <orgdiv>Open Systems Lab</orgdiv> |
| </affiliation> |
| </author> |
| <orgname>BOOST</orgname> |
| <copyright> |
| <year>2002</year> |
| <holder>The Trustees of Indiana University</holder> |
| </copyright> |
| </articleinfo> |
| |
| |
| <para>Boost.MultiArray is composed of several components. |
| The MultiArray concept defines a generic interface to multidimensional |
| containers. |
| <literal>multi_array</literal> is a general purpose container class |
| that models MultiArray. <literal>multi_array_ref</literal> |
| and <literal>const_multi_array_ref</literal> are adapter |
| classes. Using them, |
| you can manipulate any block of contiguous data as though it were a |
| <literal>multi_array</literal>. |
| <literal>const_multi_array_ref</literal> differs from |
| <literal>multi_array_ref</literal> 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.</para> |
| |
| <sect1 id="synopsis"> |
| <title>Library Synopsis</title> |
| <para>To use Boost.MultiArray, you must include the header |
| <filename>boost/multi_array.hpp</filename> in your source. This file |
| brings the following declarations into scope:</para> |
| <programlisting> |
| <![CDATA[namespace boost { |
| |
| 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; |
| } |
| |
| template <typename ValueType, |
| std::size_t NumDims, |
| typename Allocator = std::allocator<ValueType> > |
| class multi_array; |
| |
| template <typename ValueType, |
| std::size_t NumDims> |
| class multi_array_ref; |
| |
| template <typename ValueType, |
| std::size_t NumDims> |
| class const_multi_array_ref; |
| |
| multi_array_types::extent_gen extents; |
| multi_array_types::index_gen indices; |
| |
| template <typename Array, int N> class subarray_gen; |
| template <typename Array, int N> class const_subarray_gen; |
| template <typename Array, int N> class array_view_gen; |
| template <typename Array, int N> class const_array_view_gen; |
| |
| class c_storage_order; |
| class fortran_storage_order; |
| template <std::size_t NumDims> class general_storage_order; |
| |
| }]]> |
| </programlisting> |
| </sect1> |
| |
| &concepts; |
| |
| <sect1 id="array_types"> |
| <title>Array Components</title> |
| <para> |
| Boost.MultiArray defines an array class, |
| <literal>multi_array</literal>, and two adapter classes, |
| <literal>multi_array_ref</literal> and |
| <literal>const_multi_array_ref</literal>. The three classes model |
| MultiArray and so they share a lot of functionality. |
| <literal>multi_array_ref</literal> differs from |
| <literal>multi_array</literal> in that the |
| <literal>multi_array</literal> manages its own memory, while |
| <literal>multi_array_ref</literal> is passed a block of memory that it |
| expects to be externally managed. |
| <literal>const_multi_array_ref</literal> differs from |
| <literal>multi_array_ref</literal> 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 |
| below. |
| </para> |
| |
| <formalpara> |
| <title>Note: Preconditions, Effects, and Implementation</title> |
| <para> |
| 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 |
| implementation of array components; rather, they describe the |
| expected input to and |
| behavior of the specified operations. Failure to meet |
| 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. |
| </para> |
| </formalpara> |
| |
| <formalpara> |
| <title>Queries</title> |
| |
| <variablelist> |
| <varlistentry> |
| <term><programlisting>element* data(); |
| const element* data() const;</programlisting></term> |
| <listitem> |
| <para>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 <literal>origin()</literal>. Note that |
| <literal>const_multi_array_ref</literal> only provides the const |
| version of this function. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><programlisting>element* origin(); |
| const element* origin() const;</programlisting></term> |
| <listitem> |
| <para>This returns the origin element of the |
| <literal>multi_array</literal>. Note that |
| <literal>const_multi_array_ref</literal> only provides the const |
| version of this function. (Required by MultiArray) |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><function>const index* index_bases();</function></term> |
| <listitem> |
| <para>This returns the index bases for the |
| <literal>multi_array</literal>. (Required by MultiArray) |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><function>const index* strides();</function></term> |
| <listitem> |
| <para>This returns the strides for the |
| <literal>multi_array</literal>. (Required by MultiArray) |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><function>const size_type* shape();</function></term> |
| <listitem> |
| <para>This returns the shape of the |
| <literal>multi_array</literal>. (Required by MultiArray) |
| </para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| |
| </formalpara> |
| |
| <formalpara> |
| <title>Comparators</title> |
| <variablelist> |
| <varlistentry> |
| <term><programlisting><![CDATA[ |
| bool operator==(const *array-type*& rhs); |
| bool operator!=(const *array-type*& rhs); |
| bool operator<(const *array-type*& rhs); |
| bool operator>(const *array-type*& rhs); |
| bool operator>=(const *array-type*& rhs); |
| bool operator<=(const *array-type*& rhs);]]></programlisting></term> |
| |
| <listitem> |
| <para>Each comparator executes a lexicographical compare over |
| the value types of the two arrays. |
| (Required by MultiArray) |
| </para> |
| <formalpara> |
| <title>Preconditions</title> |
| <para><literal>element</literal> must support the |
| comparator corresponding to that called on |
| <literal>multi_array</literal>.</para> |
| </formalpara> |
| |
| <formalpara> |
| <title>Complexity</title> |
| <para>O(<literal>num_elements()</literal>).</para> |
| </formalpara> |
| |
| </listitem> |
| </varlistentry> |
| |
| </variablelist> |
| </formalpara> |
| |
| <formalpara> |
| <title>Modifiers</title> |
| |
| <variablelist> |
| |
| <varlistentry> |
| <term> |
| <programlisting> |
| <![CDATA[ |
| template <typename SizeList> |
| void reshape(const SizeList& sizes) |
| ]]> |
| </programlisting> |
| </term> |
| |
| <listitem> |
| <para>This changes the shape of the <literal>multi_array</literal>. 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.</para> |
| |
| <formalpara><title><literal>SizeList</literal> Requirements</title> |
| <para><literal>SizeList</literal> must model |
| <ulink url="../../utility/Collection.html">Collection</ulink>.</para> |
| </formalpara> |
| |
| <formalpara><title>Preconditions</title> |
| <para> |
| <programlisting> |
| <![CDATA[std::accumulate(sizes.begin(),sizes.end(),size_type(1),std::times<size_type>()) == this->num_elements(); |
| sizes.size() == NumDims;]]> |
| </programlisting></para> |
| </formalpara> |
| |
| |
| <formalpara><title>Postconditions</title> |
| <para> |
| <literal>std::equal(sizes.begin(),sizes.end(),this->shape) == true;</literal> |
| </para> |
| </formalpara> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term> |
| <programlisting> |
| <![CDATA[ |
| template <typename BaseList> |
| void reindex(const BaseList& values); |
| ]]> |
| </programlisting> |
| </term> |
| <listitem> |
| <para>This changes the index bases of the <literal>multi_array</literal> to |
| correspond to the the values in <literal>values</literal>.</para> |
| |
| <formalpara> |
| <title><literal>BaseList</literal> Requirements</title> |
| <para><literal>BaseList</literal> must model |
| <ulink url="../../utility/Collection.html">Collection</ulink>.</para> |
| </formalpara> |
| |
| <formalpara> |
| <title>Preconditions</title> |
| <para><literal>values.size() == NumDims;</literal></para> |
| </formalpara> |
| |
| |
| <formalpara> |
| <title>Postconditions</title> |
| <para><literal>std::equal(values.begin(),values.end(),this->index_bases()); |
| </literal></para> |
| </formalpara> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term> |
| <programlisting> |
| <![CDATA[ |
| void reindex(index value); |
| ]]> |
| </programlisting> |
| </term> |
| <listitem> |
| <para>This changes the index bases of all dimensions of the |
| <literal>multi_array</literal> to <literal>value</literal>.</para> |
| |
| <formalpara> |
| <title>Postconditions</title> |
| <para> |
| <programlisting> |
| <![CDATA[ |
| std::count_if(this->index_bases(),this->index_bases()+this->num_dimensions(), |
| std::bind_2nd(std::equal_to<index>(),value)) == |
| this->num_dimensions(); |
| ]]> |
| </programlisting> |
| </para> |
| </formalpara> |
| </listitem> |
| </varlistentry> |
| |
| </variablelist> |
| </formalpara> |
| |
| &multi_array; |
| &multi_array_ref; |
| &const_multi_array_ref; |
| |
| </sect1> |
| |
| |
| <sect1 id="auxiliary"> |
| <title>Auxiliary Components</title> |
| |
| <sect2 id="multi_array_types"> |
| <title><literal>multi_array_types</literal></title> |
| |
| <programlisting> |
| <![CDATA[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; |
| }]]> |
| </programlisting> |
| |
| <para>Namespace <literal>multi_array_types</literal> defines types |
| associated with <literal>multi_array</literal>, |
| <literal>multi_array_ref</literal>, and |
| <literal>const_multi_array_ref</literal> 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 <literal>extent_gen</literal> and |
| <literal>extent_range</literal>, these types fulfill the roles of the |
| same name required by MultiArray and are described in its |
| concept definition. <literal>extent_gen</literal> and |
| <literal>extent_range</literal> are described below. |
| </para> |
| </sect2> |
| |
| |
| <sect2 id="extent_range"> |
| <title><classname>extent_range</classname></title> |
| |
| <para><classname>extent_range</classname> objects define half open |
| intervals. They provide shape and index base information to |
| <literal>multi_array</literal>, <literal>multi_array_ref</literal>, |
| and <literal>const_multi_array_ref</literal> constructors. |
| <classname>extent_range</classname>s are passed in |
| aggregate to an array constructor (see |
| <classname>extent_gen</classname> for more details). |
| </para> |
| |
| <formalpara> |
| <title>Synopsis</title> |
| <programlisting><![CDATA[ |
| 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(); |
| };]]></programlisting> |
| </formalpara> |
| |
| <formalpara> |
| <title>Model Of</title> |
| <para>DefaultConstructible,CopyConstructible</para> |
| </formalpara> |
| |
| <formalpara><title>Methods and Types</title> |
| <variablelist> |
| <varlistentry> |
| <term><function>extent_range(index start, index finish)</function></term> |
| <listitem> |
| <para> This constructor defines the half open interval |
| <literal>[start,finish)</literal>. The expression |
| <literal>finish</literal> must be greater than <literal>start</literal>. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry><term><function>extent_range(index finish)</function></term> |
| <listitem> |
| <para>This constructor defines the half open interval |
| <literal>[0,finish)</literal>. The value of <literal>finish</literal> |
| must be positive.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry><term><function>index start()</function></term> |
| <listitem> |
| <para>This function returns the first index represented by the range</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry><term><function>index finish()</function></term> |
| <listitem> |
| <para>This function returns the upper boundary value of the half-open |
| interval. Note that the range does not include this value.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><function>size_type size()</function></term> |
| <listitem> |
| <para>This function returns the size of the specified range. It is |
| equivalent to <literal>finish()-start()</literal>.</para> |
| </listitem> |
| </varlistentry> |
| |
| </variablelist> |
| </formalpara> |
| </sect2> |
| |
| <sect2 id="extent_gen"> |
| <title><classname>extent_gen</classname></title> |
| <para>The <classname>extent_gen</classname> class defines an |
| interface for aggregating array shape and indexing information to be |
| passed to a <literal>multi_array</literal>, |
| <literal>multi_array_ref</literal>, or <literal>const_multi_array_ref</literal> |
| constructor. Its interface mimics |
| the syntax used to declare built-in array types |
| in C++. For example, while a 3-dimensional array of |
| <classname>int</classname> values in C++ would be |
| declared as: |
| <programlisting>int A[3][4][5],</programlisting> |
| a similar <classname>multi_array</classname> would be declared: |
| <programlisting>multi_array<int,3> A(extents[3][4][5]).</programlisting> |
| </para> |
| |
| <formalpara><title>Synopsis</title> |
| <programlisting><![CDATA[ |
| 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; |
| ]]></programlisting> |
| </formalpara> |
| |
| <formalpara><title>Methods and Types</title> |
| <variablelist> |
| <varlistentry> |
| <term><function>template gen_type<Ranges>::type</function></term> |
| <listitem> |
| <para>This type generator is used to specify the result of |
| <literal>Ranges</literal> chained calls to |
| <literal>extent_gen::operator[].</literal> The types |
| <classname>extent_gen</classname> and |
| <classname>gen_type<0>::type</classname> are the same.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><function>gen_type<NumRanges+1>::type |
| operator[](const extent_range& a_range) const;</function></term> |
| <listitem> |
| <para>This function returns a new object containing all previous |
| <classname>extent_range</classname> objects in addition to |
| <literal>a_range.</literal> <classname>extent_range</classname> |
| objects are aggregated by chained calls to |
| <function>operator[]</function>.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><function>gen_type<NumRanges+1>::type |
| operator[](index idx) const;</function></term> |
| <listitem> |
| <para>This function returns a new object containing all previous |
| <classname>extent_range</classname> objects in addition to |
| <literal>extent_range(0,idx).</literal> This function gives the array |
| constructors a similar syntax to traditional C multidimensional array |
| declaration.</para> |
| </listitem> |
| </varlistentry> |
| |
| </variablelist> |
| </formalpara> |
| </sect2> |
| |
| <sect2> |
| <title>Global Objects</title> |
| <para>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. |
| </para> |
| |
| <para> Under some circumstances, the two global objects may be |
| considered excessive overhead. Their construction can be prevented by |
| defining the preprocessor symbol |
| <literal>BOOST_MULTI_ARRAY_NO_GENERATORS</literal> before including |
| <filename>boost/multi_array.hpp.</filename></para> |
| |
| <sect3 id="extents"> |
| <title><literal>extents</literal></title> |
| |
| <programlisting> |
| <![CDATA[namespace boost { |
| multi_array_base::extent_gen extents; |
| }]]> |
| </programlisting> |
| |
| <para>Boost.MultiArray's array classes use the |
| <literal>extents</literal> global object to specify |
| array shape during their construction. |
| For example, |
| a 3 by 3 by 3 <classname>multi_array</classname> is constructed as follows: |
| <programlisting>multi_array<int,3> A(extents[3][3][3]);</programlisting> |
| The same array could also be created by explicitly declaring an <literal>extent_gen</literal> |
| object locally,, but the global object makes this declaration unnecessary. |
| </para> |
| </sect3> |
| |
| <sect3 id="indices"> |
| <title><literal>indices</literal></title> |
| |
| <programlisting> |
| <![CDATA[namespace boost { |
| multi_array_base::index_gen indices; |
| }]]> |
| </programlisting> |
| |
| <para>The MultiArray concept specifies an |
| <literal>index_gen</literal> associated type that is used to |
| create views. |
| <literal>indices</literal> is a global object that serves the role of |
| <literal>index_gen</literal> for all array components provided by this |
| library and their associated subarrays and views. |
| </para> |
| <para>For example, using the <literal>indices</literal> object, |
| a view of an array <literal>A</literal> is constructed as follows: |
| <programlisting> |
| A[indices[index_range(0,5)][2][index_range(2,4)]]; |
| </programlisting> |
| </para> |
| </sect3> |
| </sect2> |
| |
| <sect2 id="generators"> |
| <title>View and SubArray Generators</title> |
| <para> |
| Boost.MultiArray provides traits classes, <literal>subarray_gen</literal>, |
| <literal>const_subarray_gen</literal>, |
| <literal>array_view_gen</literal>, |
| and <literal>const_array_view_gen</literal>, 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 <literal>array_view_gen</literal> |
| traits class and the <literal>array_view</literal> type associated to |
| an array: |
| |
| <programlisting> |
| 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; |
| // ... |
| } |
| </programlisting> |
| |
| In the above example, <literal>view1_t</literal> and |
| <literal>view2_t</literal> have the same type. |
| </para> |
| </sect2> |
| |
| |
| <sect2 id="memory_layout"> |
| <title>Memory Layout Specifiers</title> |
| <para> |
| 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. |
| </para> |
| |
| <para>For example, consider the two dimensional array shown below in |
| matrix notation: |
| |
| <graphic fileref="matrix.gif"/> |
| |
| Here is how the above array is expressed in C++: |
| <programlisting> |
| int a[3][4] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 }; |
| </programlisting> |
| 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: |
| <programlisting> |
| int a[] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 }; |
| int s[] = { 4, 1 }; |
| </programlisting> |
| |
| With the latter declaration of <literal>a</literal> and |
| strides <literal>s</literal>, element <literal>a(i,j)</literal> |
| of the array can be |
| accessed using the expression |
| <programlisting>*a+i*s[0]+j*s[1]</programlisting>. |
| </para> |
| |
| <para>The same two dimensional array could be laid out by column as follows: |
| |
| <programlisting> |
| int a[] = { 0, 4, 8, 1, 5, 9, 2, 6, 10, 3, 7, 11 }; |
| int s[] = { 3, 1 }; |
| </programlisting> |
| 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. |
| </para> |
| |
| <para>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: |
| |
| <programlisting> |
| int data[] = { 8, 9, 10, 11, 4, 5, 6, 7, 0, 1, 2, 3 }; |
| int *a = data + 8; |
| int s[] = { -4, 1 }; |
| </programlisting> |
| |
| Note that in this example <literal>a</literal> 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. |
| </para> |
| |
| <para> |
| Alternatively, the second dimension, or the columns, could be reversed |
| and the rows stored in ascending order: |
| |
| <programlisting> |
| int data[] = { 3, 2, 1, 0, 7, 6, 5, 4, 11, 10, 9, 8 }; |
| int *a = data + 3; |
| int s[] = { 4, -1 }; |
| </programlisting> |
| </para> |
| |
| <para> |
| Finally, both dimensions could be stored in descending order: |
| |
| <programlisting> |
| int data[] = {11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0}; |
| int *a = data + 11; |
| int s[] = { -4, -1 }; |
| </programlisting> |
| <literal> |
| </literal> |
| </para> |
| |
| <para> |
| All of the above arrays are equivalent. The expression |
| given above for <literal>a(i,j)</literal> 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 <literal>multi_array_ref</literal> or |
| <literal>const_multi_array_ref</literal>) 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. |
| </para> |
| |
| <sect3 id="c_storage_order"> |
| <title><literal>c_storage_order</literal></title> |
| <programlisting> |
| <![CDATA[class c_storage_order { |
| c_storage_order(); |
| };]]> |
| </programlisting> |
| |
| <para><literal>c_storage_order</literal> 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.</para> |
| </sect3> |
| |
| <sect3 id="fortran_storage_order"> |
| <title><literal>fortran_storage_order</literal></title> |
| <programlisting> |
| <![CDATA[class fortran_storage_order { |
| fortran_storage_order(); |
| };]]> |
| </programlisting> |
| |
| <para><literal>fortran_storage_order</literal> 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.</para> |
| </sect3> |
| |
| <sect3 id="general_storage_order"> |
| <title><literal>general_storage_order</literal></title> |
| <programlisting> |
| <![CDATA[template <std::size_t NumDims> |
| class general_storage_order { |
| |
| template <typename OrderingIter, typename AscendingIter> |
| general_storage_order(OrderingIter ordering, AscendingIter ascending); |
| };]]> |
| </programlisting> |
| |
| <para><literal>general_storage_order</literal> 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.</para> |
| |
| <para> |
| <literal>OrderingIter</literal> and <literal>AscendingIter</literal> |
| must model the <literal>InputIterator</literal> concept. Both |
| iterators must refer to a range of <literal>NumDims</literal> |
| elements. <literal>AscendingIter</literal> points to objects |
| convertible to <literal>bool</literal>. A value of |
| <literal>true</literal> means that a dimension is stored in ascending |
| order while <literal>false</literal> means that a dimension is stored |
| in descending order. <literal>OrderingIter</literal> specifies the |
| order in which dimensions are stored. |
| </para> |
| |
| </sect3> |
| </sect2> |
| |
| <sect2 id="range_checking"> |
| <title>Range Checking</title> |
| <para> |
| By default, the array access methods <literal>operator()</literal> and |
| <literal>operator[]</literal> 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 <literal>BOOST_DISABLE_ASSERTS</literal> preprocessor macro prior to |
| including multi_array.hpp in an application. |
| </para> |
| |
| </sect2> |
| </sect1> |
| |
| |
| </article> |