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;
64
template <typename ExtentList>
65
explicit multi_array_ref(element* data, const ExtentList& sizes,
66
const storage_order_type& store = c_storage_order());
67
explicit multi_array_ref(element* data, const extents_tuple& ranges,
68
const storage_order_type& store = c_storage_order());
69
multi_array_ref(const multi_array_ref& x);
74
multi_array_ref& operator=(const multi_array_ref& x);
75
template <class Array> multi_array_ref& operator=(const Array& x);
80
const_iterator begin() const;
81
const_iterator end() const;
82
reverse_iterator rbegin();
83
reverse_iterator rend();
84
const_reverse_iterator rbegin() const;
85
const_reverse_iterator rend() const;
88
size_type size() const;
89
size_type num_elements() const;
90
size_type num_dimensions() const;
93
template <typename IndexList>
94
element& operator()(const IndexList& indices);
95
template <typename IndexList>
96
const element& operator()(const IndexList& indices) const;
97
reference operator[](index i);
98
const_reference operator[](index i) const;
99
array_view<Dims>::type operator[](const indices_tuple& r);
100
const_array_view<Dims>::type operator[](const indices_tuple& r) const;
104
const element* data() const;
106
const element* origin() const;
107
const size_type* shape() const;
108
const index* strides() const;
109
const index* index_bases() const;
110
const storage_order_type& storage_order() const;
113
bool operator==(const multi_array_ref& rhs);
114
bool operator!=(const multi_array_ref& rhs);
115
bool operator<(const multi_array_ref& rhs);
116
bool operator>(const multi_array_ref& rhs);
117
bool operator>=(const multi_array_ref& rhs);
118
bool operator<=(const multi_array_ref& rhs);
121
template <typename InputIterator>
122
void assign(InputIterator begin, InputIterator end);
123
template <typename SizeList>
124
void reshape(const SizeList& sizes)
125
template <typename BaseList> void reindex(const BaseList& values);
126
void reindex(index value);
133
<title>Constructors</title>
137
<term><programlisting>template <typename ExtentList>
138
explicit multi_array_ref(element* data,
139
const ExtentList& sizes,
140
const storage_order& store = c_storage_order(),
141
const Allocator& alloc = Allocator());
142
</programlisting></term>
146
This constructs a <literal>multi_array_ref</literal> using the specified
147
parameters. <literal>sizes</literal> specifies the shape of the
148
constructed <literal>multi_array_ref</literal>. <literal>store</literal>
149
specifies the storage order or layout in memory of the array
150
dimensions. <literal>alloc</literal> is used to
151
allocate the contained elements.
154
<formalpara><title><literal>ExtentList</literal> Requirements</title>
156
<literal>ExtentList</literal> must model <ulink url="../../utility/Collection.html">Collection</ulink>.
160
<formalpara><title>Preconditions</title>
161
<para><literal>sizes.size() == NumDims;</literal></para>
169
<programlisting><![CDATA[explicit multi_array_ref(element* data,
170
extent_gen::gen_type<NumDims>::type ranges,
171
const storage_order& store = c_storage_order());]]>
172
</programlisting></term>
175
This constructs a <literal>multi_array_ref</literal> using the specified
176
parameters. <literal>ranges</literal> specifies the shape and
177
index bases of the constructed multi_array_ref. It is the result of
178
<literal>NumDims</literal> chained calls to
179
<literal>extent_gen::operator[]</literal>. <literal>store</literal>
180
specifies the storage order or layout in memory of the array
188
<term><programlisting>
189
<![CDATA[multi_array_ref(const multi_array_ref& x);]]>
190
</programlisting></term>
192
<para>This constructs a shallow copy of <literal>x</literal>.
196
<title>Complexity</title>
197
<para> Constant time (for contrast, compare this to
198
the <literal>multi_array</literal> class copy constructor.
209
<title>Modifiers</title>
214
<term><programlisting>
215
<![CDATA[multi_array_ref& operator=(const multi_array_ref& x);
216
template <class Array> multi_array_ref& operator=(const Array& x);]]>
221
<para>This performs an element-wise copy of <literal>x</literal>
222
into the current <literal>multi_array_ref</literal>.</para>
225
<title><literal>Array</literal> Requirements</title>
226
<para><literal>Array</literal> must model MultiArray.
230
<title>Preconditions</title>
232
<programlisting>std::equal(this->shape(),this->shape()+this->num_dimensions(),
233
x.shape());</programlisting></para>
238
<title>Postconditions</title>
240
<programlisting>(*.this) == x;</programlisting>
245
<title>Complexity</title>
246
<para>The assignment operators perform
247
O(<literal>x.num_elements()</literal>) calls to <literal>element</literal>'s
248
copy constructor.</para></formalpara>