]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | <sect2 id="multi_array_ref"> |
2 | <title><literal>multi_array_ref</literal></title> | |
3 | ||
4 | <para> | |
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 | |
9 | of the constructors. | |
10 | </para> | |
11 | ||
12 | ||
13 | <formalpara> | |
14 | <title>Model Of.</title> | |
15 | <para> | |
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. | |
23 | </para> | |
24 | </formalpara> | |
25 | ||
26 | <formalpara> | |
27 | <title>Synopsis</title> | |
28 | ||
29 | <programlisting> | |
30 | <![CDATA[ | |
31 | namespace boost { | |
32 | ||
33 | template <typename ValueType, | |
34 | std::size_t NumDims> | |
35 | class multi_array_ref { | |
36 | public: | |
37 | // types: | |
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; | |
54 | ||
55 | // template typedefs | |
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; | |
60 | ||
61 | ||
62 | static const std::size_t dimensionality = NumDims; | |
63 | ||
64 | ||
65 | // constructors and destructors | |
66 | ||
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); | |
73 | ~multi_array_ref(); | |
74 | ||
75 | // modifiers | |
76 | ||
77 | multi_array_ref& operator=(const multi_array_ref& x); | |
78 | template <class Array> multi_array_ref& operator=(const Array& x); | |
79 | ||
80 | // iterators: | |
81 | iterator begin(); | |
82 | iterator end(); | |
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; | |
89 | ||
90 | // capacity: | |
91 | size_type size() const; | |
92 | size_type num_elements() const; | |
93 | size_type num_dimensions() const; | |
94 | ||
95 | // element access: | |
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; | |
104 | ||
105 | // queries | |
106 | element* data(); | |
107 | const element* data() const; | |
108 | element* origin(); | |
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; | |
114 | ||
115 | // comparators | |
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); | |
122 | ||
123 | // modifiers: | |
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); | |
130 | }; | |
131 | ]]> | |
132 | </programlisting> | |
133 | </formalpara> | |
134 | ||
135 | <formalpara> | |
136 | <title>Constructors</title> | |
137 | ||
138 | <variablelist> | |
139 | <varlistentry> | |
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> | |
146 | <listitem> | |
147 | ||
148 | <para> | |
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. | |
155 | </para> | |
156 | ||
157 | <formalpara><title><literal>ExtentList</literal> Requirements</title> | |
158 | <para> | |
159 | <literal>ExtentList</literal> must model <ulink url="../../utility/Collection.html">Collection</ulink>. | |
160 | </para> | |
161 | </formalpara> | |
162 | ||
163 | <formalpara><title>Preconditions</title> | |
164 | <para><literal>sizes.size() == NumDims;</literal></para> | |
165 | </formalpara> | |
166 | ||
167 | </listitem> | |
168 | </varlistentry> | |
169 | ||
170 | <varlistentry> | |
171 | <term> | |
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> | |
176 | <listitem> | |
177 | <para> | |
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 | |
184 | dimensions. | |
185 | </para> | |
186 | </listitem> | |
187 | </varlistentry> | |
188 | ||
189 | ||
190 | <varlistentry> | |
191 | <term><programlisting> | |
192 | <![CDATA[multi_array_ref(const multi_array_ref& x);]]> | |
193 | </programlisting></term> | |
194 | <listitem> | |
195 | <para>This constructs a shallow copy of <literal>x</literal>. | |
196 | </para> | |
197 | ||
198 | <formalpara> | |
199 | <title>Complexity</title> | |
200 | <para> Constant time (for contrast, compare this to | |
201 | the <literal>multi_array</literal> class copy constructor. | |
202 | </para></formalpara> | |
203 | </listitem> | |
204 | </varlistentry> | |
205 | ||
206 | </variablelist> | |
207 | ||
208 | </formalpara> | |
209 | ||
210 | ||
211 | <formalpara> | |
212 | <title>Modifiers</title> | |
213 | ||
214 | <variablelist> | |
215 | <varlistentry> | |
216 | ||
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);]]> | |
220 | </programlisting> | |
221 | </term> | |
222 | ||
223 | <listitem> | |
224 | <para>This performs an element-wise copy of <literal>x</literal> | |
225 | into the current <literal>multi_array_ref</literal>.</para> | |
226 | ||
227 | <formalpara> | |
228 | <title><literal>Array</literal> Requirements</title> | |
229 | <para><literal>Array</literal> must model MultiArray. | |
230 | </para></formalpara> | |
231 | ||
232 | <formalpara> | |
233 | <title>Preconditions</title> | |
234 | <para> | |
235 | <programlisting>std::equal(this->shape(),this->shape()+this->num_dimensions(), | |
236 | x.shape());</programlisting></para> | |
237 | </formalpara> | |
238 | ||
239 | ||
240 | <formalpara> | |
241 | <title>Postconditions</title> | |
242 | <para> | |
243 | <programlisting>(*.this) == x;</programlisting> | |
244 | </para> | |
245 | </formalpara> | |
246 | ||
247 | <formalpara> | |
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> | |
252 | </listitem> | |
253 | </varlistentry> | |
254 | </variablelist> | |
255 | ||
256 | </formalpara> | |
257 | </sect2> |