123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806 |
- <?xml version="1.0" encoding="utf-8"?>
- <!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
- "http://www.boost.org/tools/boostbook/dtd/boostbook.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">
- ]>
- <library name="MultiArray" dirname="multi_array" id="multi_array"
- xmlns:xi="http://www.w3.org/2001/XInclude"
- last-revision="$Date$">
- <libraryinfo>
- <author>
- <firstname>Ronald</firstname>
- <surname>Garcia</surname>
- <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>
- <librarypurpose>Multidimensional containers and adaptors for
- arrays of contiguous data</librarypurpose>
- <librarycategory name="category:math"/>
- <librarycategory name="category:containers"/>
- </libraryinfo>
- <title>Boost.MultiArray Reference Manual</title>
- <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>
- </library>
|