1 <sect2 id=
"multi_array_ref">
2 <title><literal>multi_array_ref
</literal></title>
5 <literal>multi_array_ref
</literal> is a multi-dimensional container
6 adaptor. It provides the MultiArray interface over any contiguous
7 block of elements.
<literal>multi_array_ref
</literal> exports the
8 same interface as
<literal>multi_array
</literal>, with the exception
14 <title>Model Of.
</title>
16 <literal>multi_array_ref
</literal> models
17 <link linkend=
"MultiArray">MultiArray
</link>,
18 <ulink url=
"../../../libs/utility/CopyConstructible.html">CopyConstructible
</ulink>.
19 and depending on the element type, it may also model
20 <ulink url=
"http://www.sgi.com/tech/stl/EqualityComparable.html">EqualityComparable
</ulink> and
<ulink url=
"http://www.sgi.com/tech/stl/LessThanComparable.html">LessThanComparable
</ulink>.
21 Detailed descriptions are provided here only for operations that are
22 not described in the
<literal>multi_array
</literal> reference.
27 <title>Synopsis
</title>
33 template
<typename ValueType,
35 class multi_array_ref {
38 typedef ValueType element;
39 typedef *unspecified* value_type;
40 typedef *unspecified* reference;
41 typedef *unspecified* const_reference;
42 typedef *unspecified* difference_type;
43 typedef *unspecified* iterator;
44 typedef *unspecified* const_iterator;
45 typedef *unspecified* reverse_iterator;
46 typedef *unspecified* const_reverse_iterator;
47 typedef multi_array_types::size_type size_type;
48 typedef multi_array_types::index index;
49 typedef multi_array_types::index_gen index_gen;
50 typedef multi_array_types::index_range index_range;
51 typedef multi_array_types::extent_gen extent_gen;
52 typedef multi_array_types::extent_range extent_range;
53 typedef *unspecified* storage_order_type;
56 template
<std::size_t Dims
> struct subarray;
57 template
<std::size_t Dims
> struct const_subarray;
58 template
<std::size_t Dims
> struct array_view;
59 template
<std::size_t Dims
> struct const_array_view;
62 static const std::size_t dimensionality = NumDims;
65 // constructors and destructors
67 template
<typename ExtentList
>
68 explicit multi_array_ref(element* data, const ExtentList& sizes,
69 const storage_order_type& store = c_storage_order());
70 explicit multi_array_ref(element* data, const extents_tuple& ranges,
71 const storage_order_type& store = c_storage_order());
72 multi_array_ref(const multi_array_ref& x);
77 multi_array_ref& operator=(const multi_array_ref& x);
78 template
<class Array
> multi_array_ref& operator=(const Array& x);
83 const_iterator begin() const;
84 const_iterator end() const;
85 reverse_iterator rbegin();
86 reverse_iterator rend();
87 const_reverse_iterator rbegin() const;
88 const_reverse_iterator rend() const;
91 size_type size() const;
92 size_type num_elements() const;
93 size_type num_dimensions() const;
96 template
<typename IndexList
>
97 element& operator()(const IndexList& indices);
98 template
<typename IndexList
>
99 const element& operator()(const IndexList& indices) const;
100 reference operator[](index i);
101 const_reference operator[](index i) const;
102 array_view
<Dims>::type operator[](const indices_tuple& r);
103 const_array_view
<Dims>::type operator[](const indices_tuple& r) const;
107 const element* data() const;
109 const element* origin() const;
110 const size_type* shape() const;
111 const index* strides() const;
112 const index* index_bases() const;
113 const storage_order_type& storage_order() const;
116 bool operator==(const multi_array_ref& rhs);
117 bool operator!=(const multi_array_ref& rhs);
118 bool operator<(const multi_array_ref& rhs);
119 bool operator
>(const multi_array_ref& rhs);
120 bool operator
>=(const multi_array_ref& rhs);
121 bool operator<=(const multi_array_ref& rhs);
124 template
<typename InputIterator
>
125 void assign(InputIterator begin, InputIterator end);
126 template
<typename SizeList
>
127 void reshape(const SizeList& sizes)
128 template
<typename BaseList
> void reindex(const BaseList& values);
129 void reindex(index value);
136 <title>Constructors
</title>
140 <term><programlisting>template
<typename ExtentList
>
141 explicit multi_array_ref(element* data,
142 const ExtentList
& sizes,
143 const storage_order
& store = c_storage_order(),
144 const Allocator
& alloc = Allocator());
145 </programlisting></term>
149 This constructs a
<literal>multi_array_ref
</literal> using the specified
150 parameters.
<literal>sizes
</literal> specifies the shape of the
151 constructed
<literal>multi_array_ref
</literal>.
<literal>store
</literal>
152 specifies the storage order or layout in memory of the array
153 dimensions.
<literal>alloc
</literal> is used to
154 allocate the contained elements.
157 <formalpara><title><literal>ExtentList
</literal> Requirements
</title>
159 <literal>ExtentList
</literal> must model
<ulink url=
"../../utility/Collection.html">Collection
</ulink>.
163 <formalpara><title>Preconditions
</title>
164 <para><literal>sizes.size() == NumDims;
</literal></para>
172 <programlisting><![CDATA[explicit multi_array_ref(element* data,
173 extent_gen::gen_type
<NumDims>::type ranges,
174 const storage_order& store = c_storage_order());]]
>
175 </programlisting></term>
178 This constructs a
<literal>multi_array_ref
</literal> using the specified
179 parameters.
<literal>ranges
</literal> specifies the shape and
180 index bases of the constructed multi_array_ref. It is the result of
181 <literal>NumDims
</literal> chained calls to
182 <literal>extent_gen::operator[]
</literal>.
<literal>store
</literal>
183 specifies the storage order or layout in memory of the array
191 <term><programlisting>
192 <![CDATA[multi_array_ref(const multi_array_ref& x);]]
>
193 </programlisting></term>
195 <para>This constructs a shallow copy of
<literal>x
</literal>.
199 <title>Complexity
</title>
200 <para> Constant time (for contrast, compare this to
201 the
<literal>multi_array
</literal> class copy constructor.
212 <title>Modifiers
</title>
217 <term><programlisting>
218 <![CDATA[multi_array_ref& operator=(const multi_array_ref& x);
219 template
<class Array
> multi_array_ref& operator=(const Array& x);]]
>
224 <para>This performs an element-wise copy of
<literal>x
</literal>
225 into the current
<literal>multi_array_ref
</literal>.
</para>
228 <title><literal>Array
</literal> Requirements
</title>
229 <para><literal>Array
</literal> must model MultiArray.
233 <title>Preconditions
</title>
235 <programlisting>std::equal(this-
>shape(),this-
>shape()+this-
>num_dimensions(),
236 x.shape());
</programlisting></para>
241 <title>Postconditions
</title>
243 <programlisting>(*.this) == x;
</programlisting>
248 <title>Complexity
</title>
249 <para>The assignment operators perform
250 O(
<literal>x.num_elements()
</literal>) calls to
<literal>element
</literal>'s
251 copy constructor.
</para></formalpara>