utiltools/X86MAC64/cuda/include/thrust/iterator/constant_iterator.h

   1 /*
   2  *  Copyright 2008-2012 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(void)
  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__
 120     constant_iterator(void)
 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__
 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())
 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())
 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__
 176     Value const& value(void) const
 177     { return m_value; }
 178
 179     /*! \cond
 180      */
 181
 182   protected:
 183     __host__ __device__
 184     Value const& value_reference(void) const
 185     { return m_value; }
 186
 187     __host__ __device__
 188     Value & value_reference(void)
 189     { return m_value; }
 190
 191   private: // Core iterator interface
 192     __host__ __device__
 193     reference dereference(void) 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__
 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