1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
|
.. index::
single: Iterators
.. _iterators:
Iterators
---------
.. cpp:namespace:: zfp
.. cpp:class:: array1::const_iterator
.. cpp:class:: array2::const_iterator
.. cpp:class:: array3::const_iterator
.. cpp:class:: array4::const_iterator
.. cpp:class:: array1::iterator : public array1::const_iterator
.. cpp:class:: array2::iterator : public array2::const_iterator
.. cpp:class:: array3::iterator : public array3::const_iterator
.. cpp:class:: array4::iterator : public array4::const_iterator
Iterators provide a mechanism for traversing a possibly
multi-dimensional array---or a :ref:`view <views>` of a subset of an
array---without having to track array indices or bounds.
They are also the preferred mechanism, compared to nested index loops, for
initializing arrays, because they sequentially visit the array one block
at a time. This allows all elements of a block to be initialized together
and ensures that the block is not compressed to memory before it has been
fully initialized, which might otherwise result in poor compression and,
consequently, larger compression errors than when the entire block is
initialized as a whole. Note that the iterator traversal order differs in
this respect from traversal by :ref:`pointers <pointers>`.
Blocks are visited in raster order similarly to how individual array
elements are indexed, that is, first by *x*, then by *y*, then by *z*,
etc. Within each block, elements are visited in the same raster
order. All |4powd| values in a block are visited before moving on to the
next block (see :numref:`view-indexing`).
As of |zfp| |raiterrelease|, all iterators provided by |zfp| are random
access iterators (previously, multi-dimensional array iterators were only
forward iterators). |zfp| iterators are
`STL <http://www.cplusplus.com/reference/stl/>`_ compliant and can
be used in STL algorithms that support random access iterators.
|zfp| |crpirelease| adds :code:`const` qualified versions of iterators,
given by the :code:`const_iterator` class. Such iterators are available
also for :ref:`read-only arrays <carray_classes>`.
Per STL mandate, the iterators define several types:
.. cpp:namespace:: zfp::arrayANY
.. cpp:type:: iterator::value_type
The scalar type associated with the array that the iterator points into.
----
.. cpp:type:: iterator::difference_type
Difference between two iterators in number of array elements.
----
.. cpp:type:: iterator::reference
The :ref:`reference <references>` type associated with the iterator's parent
array class.
----
.. cpp:type:: iterator::pointer
The :ref:`pointer <pointers>` type associated with the iterator's parent
array class.
----
.. cpp:type:: iterator::iterator_category
Type of iterator: :cpp:type:`std::random_access_iterator_tag`.
For const iterators, the following additional types are defined:
.. cpp:type:: const_iterator::const_reference
The immutable reference type associated with the iterator's container class.
.. cpp:type:: const_iterator::const_pointer
The immutable pointer type associated with the iterator's container class.
The following operations are defined on iterators:
.. cpp:function:: iterator iterator::operator=(const iterator& it)
.. cpp:function:: const_iterator const_iterator::operator=(const const_iterator& it)
Assignment (copy) operator. Make the iterator point to the same element
as *it*.
----
.. cpp:function:: reference iterator::operator*() const
.. cpp:function:: const_reference const_iterator::operator*() const
Dereference operator. Return (const) reference to the value pointed to by
the iterator.
----
.. cpp:function:: reference iterator::operator[](difference_type d) const
.. cpp:function:: const_reference const_iterator::operator[](difference_type d) const
Offset dereference operator. Return (const) reference to the value *d*
elements relative to the current element in the iteration sequence (*d* may
be negative). This operator executes in constant time regardless of array
dimensionality but is more costly than sequential iteration via
:cpp:func:`iterator::operator++`.
----
.. cpp:function:: iterator iterator::operator+(difference_type d) const
.. cpp:function:: const_iterator const_iterator::operator+(difference_type d) const
Return a new iterator that has been incremented by *d*.
----
.. cpp:function:: iterator iterator::operator-(difference_type d) const
.. cpp:function:: const_iterator const_iterator::operator-(difference_type d) const
Return a new iterator that has been decremented by *d*.
----
.. cpp:function:: difference_type iterator::operator-(const iterator& it) const
.. cpp:function:: difference_type const_iterator::operator-(const const_iterator& it) const
Return difference between this iterator and *it* in number of elements.
The difference *p* |minus| *q* between two iterators, *p* and *q*, is
negative if *p* < *q*. The iterators must refer to elements in the same
array.
----
.. cpp:function:: bool iterator::operator==(const iterator& it) const
.. cpp:function:: bool const_iterator::operator==(const const_iterator& it) const
Return true if the two iterators point to the same element.
----
.. cpp:function:: bool iterator::operator!=(const iterator& it) const
.. cpp:function:: bool const_iterator::operator!=(const const_iterator& it) const
Return true if the two iterators do not point to the same element.
----
.. _iter_inequalities:
.. cpp:function:: bool iterator::operator<=(const iterator& it) const
.. cpp:function:: bool iterator::operator>=(const iterator& it) const
.. cpp:function:: bool iterator::operator<(const iterator& it) const
.. cpp:function:: bool iterator::operator>(const iterator& it) const
.. cpp:function:: bool const_iterator::operator<=(const const_iterator& it) const
.. cpp:function:: bool const_iterator::operator>=(const const_iterator& it) const
.. cpp:function:: bool const_iterator::operator<(const const_iterator& it) const
.. cpp:function:: bool const_iterator::operator>(const const_iterator& it) const
Return true if the two iterators satisfy the given relationship.
For two iterators, *p* and *q*, within the same array, *p* < *q*
if and only if *q* can be reached by incrementing *p* one or more times.
----
.. cpp:function:: iterator& iterator::operator++()
.. cpp:function:: const_iterator& const_iterator::operator++()
Prefix increment (:code:`++it`). Return a reference to the
incremented iterator.
----
.. cpp:function:: iterator iterator::operator++(int)
.. cpp:function:: const_iterator const_iterator::operator++(int)
Postfix increment (:code:`it++`). Return the value of the iterator
before being incremented.
----
.. cpp:function:: iterator& iterator::operator--()
.. cpp:function:: const_iterator& const_iterator::operator--()
Prefix decrement (:code:`--it`). Return a reference to the
decremented iterator.
----
.. cpp:function:: iterator iterator::operator--(int)
.. cpp:function:: const_iterator const_iterator::operator--(int)
Postfix decrement (:code:`it--`). Return the value of the
iterator before being decremented.
----
.. cpp:function:: iterator iterator::operator+=(difference_type d)
.. cpp:function:: const_iterator const_iterator::operator+=(difference_type d)
Increment iterator *d* times. Return value of incremented iterator.
Although :cpp:expr:`++it` and :cpp:expr:`it += 1` are semantically
equivalent, the former is more efficient for multidimensional arrays.
----
.. cpp:function:: iterator iterator::operator-=(difference_type d)
.. cpp:function:: const_iterator const_iterator::operator-=(difference_type d)
Decrement iterator *d* times. Return value of decremented iterator.
Although :cpp:expr:`--it` and :cpp:expr:`it -= 1` are semantically
equivalent, the former is more efficient for multidimensional arrays.
----
.. cpp:function:: size_t iterator::i() const
.. cpp:function:: size_t iterator::j() const
.. cpp:function:: size_t iterator::k() const
.. cpp:function:: size_t iterator::l() const
.. cpp:function:: size_t const_iterator::i() const
.. cpp:function:: size_t const_iterator::j() const
.. cpp:function:: size_t const_iterator::k() const
.. cpp:function:: size_t const_iterator::l() const
Return array index or local view index of element pointed to by the
iterator.
:cpp:func:`iterator::i` is defined for all arrays.
:cpp:func:`iterator::j` is defined only for 2D, 3D, and 4D arrays.
:cpp:func:`iterator::k` is defined only for 3D and 4D arrays.
:cpp:func:`iterator::l` is defined only for 4D arrays.
|
