1 /*
2 * Copyright 2008-2013 NVIDIA Corporation
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17
18 /*! \file thrust/iterator/constant_iterator.h
19 * \brief An iterator which returns a constant value when
20 * dereferenced
21 */
22
23 #pragma once
24
25 #include <thrust/detail/config.h>
26 #include <thrust/iterator/detail/constant_iterator_base.h>
27 #include <thrust/iterator/iterator_facade.h>
28
29 namespace thrust
30 {
31
32 /*! \addtogroup iterators
33 * \{
34 */
35
36 /*! \addtogroup fancyiterator Fancy Iterators
37 * \ingroup iterators
38 * \{
39 */
40
41 /*! \p constant_iterator is an iterator which represents a pointer into a range
42 * of constant values. This iterator is useful for creating a range filled with the same
43 * value without explicitly storing it in memory. Using \p constant_iterator saves both
44 * memory capacity and bandwidth.
45 *
46 * The following code snippet demonstrates how to create a \p constant_iterator whose
47 * \c value_type is \c int and whose value is \c 10.
48 *
49 * \code
50 * #include <thrust/iterator/constant_iterator.h>
51 *
52 * thrust::constant_iterator<int> iter(10);
53 *
54 * *iter; // returns 10
55 * iter[0]; // returns 10
56 * iter[1]; // returns 10
57 * iter[13]; // returns 10
58 *
59 * // and so on...
60 * \endcode
61 *
62 * This next example demonstrates how to use a \p constant_iterator with the
63 * \p thrust::transform function to increment all elements of a sequence by the
64 * same value. We will create a temporary \p constant_iterator with the function
65 * \p make_constant_iterator function in order to avoid explicitly specifying
66 * its type:
67 *
68 * \code
69 * #include <thrust/iterator/constant_iterator.h>
70 * #include <thrust/transform.h>
71 * #include <thrust/functional.h>
72 * #include <thrust/device_vector.h>
73 *
74 * int main()
75 * {
76 * thrust::device_vector<int> data(4);
77 * data[0] = 3;
78 * data[1] = 7;
79 * data[2] = 2;
80 * data[3] = 5;
81 *
82 * // add 10 to all values in data
83 * thrust::transform(data.begin(), data.end(),
84 * thrust::make_constant_iterator(10),
85 * data.begin(),
86 * thrust::plus<int>());
87 *
88 * // data is now [13, 17, 12, 15]
89 *
90 * return 0;
91 * }
92 * \endcode
93 *
94 * \see make_constant_iterator
95 */
96 template<typename Value,
97 typename Incrementable = use_default,
98 typename System = use_default>
99 class constant_iterator
100 : public detail::constant_iterator_base<Value, Incrementable, System>::type
101 {
102 /*! \cond
103 */
104 friend class thrust::iterator_core_access;
105 typedef typename detail::constant_iterator_base<Value, Incrementable, System>::type super_t;
106 typedef typename detail::constant_iterator_base<Value, Incrementable, System>::incrementable incrementable;
107 typedef typename detail::constant_iterator_base<Value, Incrementable, System>::base_iterator base_iterator;
108
109 public:
110 typedef typename super_t::reference reference;
111 typedef typename super_t::value_type value_type;
112
113 /*! \endcond
114 */
115
116 /*! Null constructor initializes this \p constant_iterator's constant using its
117 * null constructor.
118 */
119 __host__ __device__
constant_iterator()120 constant_iterator()
121 : super_t(), m_value() {}
122
123 /*! Copy constructor copies the value of another \p constant_iterator into this
124 * \p constant_iterator.
125 *
126 * \p rhs The constant_iterator to copy.
127 */
128 __host__ __device__
constant_iterator(constant_iterator const & rhs)129 constant_iterator(constant_iterator const &rhs)
130 : super_t(rhs.base()), m_value(rhs.m_value) {}
131
132 /*! Copy constructor copies the value of another \p constant_iterator with related
133 * System type.
134 *
135 * \param rhs The \p constant_iterator to copy.
136 */
137 template<typename OtherSystem>
138 __host__ __device__
139 constant_iterator(constant_iterator<Value,Incrementable,OtherSystem> const &rhs,
140 typename thrust::detail::enable_if_convertible<
141 typename thrust::iterator_system<constant_iterator<Value,Incrementable,OtherSystem> >::type,
142 typename thrust::iterator_system<super_t>::type
143 >::type * = 0)
144 : super_t(rhs.base()), m_value(rhs.value()) {}
145
146 /*! This constructor receives a value to use as the constant value of this
147 * \p constant_iterator and an index specifying the location of this
148 * \p constant_iterator in a sequence.
149 *
150 * \p v The value of this \p constant_iterator's constant value.
151 * \p i The index of this \p constant_iterator in a sequence. Defaults to the
152 * value returned by \c Incrementable's null constructor. For example,
153 * when <tt>Incrementable == int</tt>, \c 0.
154 */
155 __host__ __device__
156 constant_iterator(value_type const& v, incrementable const &i = incrementable())
super_t(base_iterator (i))157 : super_t(base_iterator(i)), m_value(v) {}
158
159 /*! This constructor is templated to allow construction from a value type and
160 * incrementable type related this this \p constant_iterator's respective types.
161 *
162 * \p v The value of this \p constant_iterator's constant value.
163 * \p i The index of this \p constant_iterator in a sequence. Defaults to the
164 * value returned by \c Incrementable's null constructor. For example,
165 * when <tt>Incrementable == int</tt>, \c 0.
166 */
167 template<typename OtherValue, typename OtherIncrementable>
168 __host__ __device__
169 constant_iterator(OtherValue const& v, OtherIncrementable const& i = incrementable())
super_t(base_iterator (i))170 : super_t(base_iterator(i)), m_value(v) {}
171
172 /*! This method returns the value of this \p constant_iterator's constant value.
173 * \return A \c const reference to this \p constant_iterator's constant value.
174 */
175 __host__ __device__
value()176 Value const& value() const
177 { return m_value; }
178
179 /*! \cond
180 */
181
182 protected:
183 __host__ __device__
value_reference()184 Value const& value_reference() const
185 { return m_value; }
186
187 __host__ __device__
value_reference()188 Value & value_reference()
189 { return m_value; }
190
191 private: // Core iterator interface
192 __host__ __device__
dereference()193 reference dereference() const
194 {
195 return m_value;
196 }
197
198 private:
199 Value m_value;
200
201 /*! \endcond
202 */
203 }; // end constant_iterator
204
205
206 /*! This version of \p make_constant_iterator creates a \p constant_iterator
207 * from values given for both value and index. The type of \p constant_iterator
208 * may be inferred by the compiler from the types of its parameters.
209 *
210 * \param x The value of the returned \p constant_iterator's constant value.
211 * \param i The index of the returned \p constant_iterator within a sequence.
212 * The type of this parameter defaults to \c int. In the default case,
213 * the value of this parameter is \c 0.
214 *
215 * \return A new \p constant_iterator with constant value & index as given
216 * by \p x & \p i.
217 *
218 * \see constant_iterator
219 */
220 template<typename V, typename I>
221 inline __host__ __device__
222 constant_iterator<V,I> make_constant_iterator(V x, I i = int())
223 {
224 return constant_iterator<V,I>(x, i);
225 } // end make_constant_iterator()
226
227
228 /*! This version of \p make_constant_iterator creates a \p constant_iterator
229 * using only a parameter for the desired constant value. The value of the
230 * returned \p constant_iterator's index is set to \c 0.
231 *
232 * \param x The value of the returned \p constant_iterator's constant value.
233 * \return A new \p constant_iterator with constant value equal to \p x and
234 * index equal to \c 0.
235 * \see constant_iterator
236 */
237 template<typename V>
238 inline __host__ __device__
make_constant_iterator(V x)239 constant_iterator<V> make_constant_iterator(V x)
240 {
241 return constant_iterator<V>(x, 0);
242 } // end make_constant_iterator()
243
244 /*! \} // end fancyiterators
245 */
246
247 /*! \} // end iterators
248 */
249
250 } // end namespace thrust
251
252