2 * Copyright 2008-2013 NVIDIA Corporation
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
18 /*! \file adjacent_difference.h
19 * \brief Compute difference between consecutive elements of a range
24 #include <thrust/detail/config.h>
25 #include <thrust/detail/execution_policy.h>
31 /*! \addtogroup transformations Transformations
36 /*! \p adjacent_difference calculates the differences of adjacent elements in the
37 * range <tt>[first, last)</tt>. That is, <tt>\*first</tt> is assigned to
38 * <tt>\*result</tt>, and, for each iterator \p i in the range
39 * <tt>[first + 1, last)</tt>, the difference of <tt>\*i</tt> and <tt>*(i - 1)</tt>
40 * is assigned to <tt>\*(result + (i - first))</tt>.
42 * This version of \p adjacent_difference uses <tt>operator-</tt> to calculate
45 * The algorithm's execution is parallelized as determined by \p exec.
47 * \param exec The execution policy to use for parallelization.
48 * \param first The beginning of the input range.
49 * \param last The end of the input range.
50 * \param result The beginning of the output range.
51 * \return The iterator <tt>result + (last - first)</tt>
53 * \tparam DerivedPolicy The name of the derived execution policy.
54 * \tparam InputIterator is a model of <a href="http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a>,
55 * and \c x and \c y are objects of \p InputIterator's \c value_type, then \c x - \c is defined,
56 * and \p InputIterator's \c value_type is convertible to a type in \p OutputIterator's set of \c value_types,
57 * and the return type of <tt>x - y</tt> is convertible to a type in \p OutputIterator's set of \c value_types.
58 * \tparam OutputIterator is a model of <a href="http://www.sgi.com/tech/stl/OutputIterator.html">Output Iterator</a>.
60 * \remark Note that \p result is permitted to be the same iterator as \p first. This is
61 * useful for computing differences "in place".
63 * The following code snippet demonstrates how to use \p adjacent_difference to compute
64 * the difference between adjacent elements of a range using the \p thrust::device execution policy:
67 * #include <thrust/adjacent_difference.h>
68 * #include <thrust/device_vector.h>
69 * #include <thrust/execution_policy.h>
71 * int h_data[8] = {1, 2, 1, 2, 1, 2, 1, 2};
72 * thrust::device_vector<int> d_data(h_data, h_data + 8);
73 * thrust::device_vector<int> d_result(8);
75 * thrust::adjacent_difference(thrust::device, d_data.begin(), d_data.end(), d_result.begin());
77 * // d_result is now [1, 1, -1, 1, -1, 1, -1, 1]
80 * \see http://www.sgi.com/tech/stl/adjacent_difference.html
83 template<typename DerivedPolicy, typename InputIterator, typename OutputIterator>
84 OutputIterator adjacent_difference(const thrust::detail::execution_policy_base<DerivedPolicy> &exec,
85 InputIterator first, InputIterator last,
86 OutputIterator result);
88 /*! \p adjacent_difference calculates the differences of adjacent elements in the
89 * range <tt>[first, last)</tt>. That is, <tt>*first</tt> is assigned to
90 * <tt>\*result</tt>, and, for each iterator \p i in the range
91 * <tt>[first + 1, last)</tt>, <tt>binary_op(\*i, \*(i - 1))</tt> is assigned to
92 * <tt>\*(result + (i - first))</tt>.
94 * This version of \p adjacent_difference uses the binary function \p binary_op to
95 * calculate differences.
97 * The algorithm's execution is parallelized as determined by \p exec.
99 * \param exec The execution policy to use for parallelization.
100 * \param first The beginning of the input range.
101 * \param last The end of the input range.
102 * \param result The beginning of the output range.
103 * \param binary_op The binary function used to compute differences.
104 * \return The iterator <tt>result + (last - first)</tt>
106 * \tparam DerivedPolicy The name of the derived execution policy.
107 * \tparam InputIterator is a model of <a href="http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a>,
108 * and \p InputIterator's \c value_type is convertible to \p BinaryFunction's \c first_argument_type and \c second_argument_type,
109 * and \p InputIterator's \c value_type is convertible to a type in \p OutputIterator's set of \c value_types.
110 * \tparam OutputIterator is a model of <a href="http://www.sgi.com/tech/stl/OutputIterator.html">Output Iterator</a>.
111 * \tparam BinaryFunction's \c result_type is convertible to a type in \p OutputIterator's set of \c value_types.
113 * \remark Note that \p result is permitted to be the same iterator as \p first. This is
114 * useful for computing differences "in place".
116 * The following code snippet demonstrates how to use \p adjacent_difference to compute
117 * the sum between adjacent elements of a range using the \p thrust::device execution policy:
120 * #include <thrust/adjacent_difference.h>
121 * #include <thrust/functional.h>
122 * #include <thrust/device_vector.h>
123 * #include <thrust/execution_policy.h>
125 * int h_data[8] = {1, 2, 1, 2, 1, 2, 1, 2};
126 * thrust::device_vector<int> d_data(h_data, h_data + 8);
127 * thrust::device_vector<int> d_result(8);
129 * thrust::adjacent_difference(thrust::device, d_data.begin(), d_data.end(), d_result.begin(), thrust::plus<int>());
131 * // d_data is now [1, 3, 3, 3, 3, 3, 3, 3]
134 * \see http://www.sgi.com/tech/stl/adjacent_difference.html
135 * \see inclusive_scan
137 template<typename DerivedPolicy, typename InputIterator, typename OutputIterator, typename BinaryFunction>
138 OutputIterator adjacent_difference(const thrust::detail::execution_policy_base<DerivedPolicy> &exec,
139 InputIterator first, InputIterator last,
140 OutputIterator result,
141 BinaryFunction binary_op);
143 /*! \p adjacent_difference calculates the differences of adjacent elements in the
144 * range <tt>[first, last)</tt>. That is, <tt>\*first</tt> is assigned to
145 * <tt>\*result</tt>, and, for each iterator \p i in the range
146 * <tt>[first + 1, last)</tt>, the difference of <tt>\*i</tt> and <tt>*(i - 1)</tt>
147 * is assigned to <tt>\*(result + (i - first))</tt>.
149 * This version of \p adjacent_difference uses <tt>operator-</tt> to calculate
152 * \param first The beginning of the input range.
153 * \param last The end of the input range.
154 * \param result The beginning of the output range.
155 * \return The iterator <tt>result + (last - first)</tt>
157 * \tparam InputIterator is a model of <a href="http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a>,
158 * and \c x and \c y are objects of \p InputIterator's \c value_type, then \c x - \c is defined,
159 * and \p InputIterator's \c value_type is convertible to a type in \p OutputIterator's set of \c value_types,
160 * and the return type of <tt>x - y</tt> is convertible to a type in \p OutputIterator's set of \c value_types.
161 * \tparam OutputIterator is a model of <a href="http://www.sgi.com/tech/stl/OutputIterator.html">Output Iterator</a>.
163 * \remark Note that \p result is permitted to be the same iterator as \p first. This is
164 * useful for computing differences "in place".
166 * The following code snippet demonstrates how to use \p adjacent_difference to compute
167 * the difference between adjacent elements of a range.
170 * #include <thrust/adjacent_difference.h>
171 * #include <thrust/device_vector.h>
173 * int h_data[8] = {1, 2, 1, 2, 1, 2, 1, 2};
174 * thrust::device_vector<int> d_data(h_data, h_data + 8);
175 * thrust::device_vector<int> d_result(8);
177 * thrust::adjacent_difference(d_data.begin(), d_data.end(), d_result.begin());
179 * // d_result is now [1, 1, -1, 1, -1, 1, -1, 1]
182 * \see http://www.sgi.com/tech/stl/adjacent_difference.html
183 * \see inclusive_scan
185 template <typename InputIterator, typename OutputIterator>
186 OutputIterator adjacent_difference(InputIterator first, InputIterator last,
187 OutputIterator result);
189 /*! \p adjacent_difference calculates the differences of adjacent elements in the
190 * range <tt>[first, last)</tt>. That is, <tt>*first</tt> is assigned to
191 * <tt>\*result</tt>, and, for each iterator \p i in the range
192 * <tt>[first + 1, last)</tt>, <tt>binary_op(\*i, \*(i - 1))</tt> is assigned to
193 * <tt>\*(result + (i - first))</tt>.
195 * This version of \p adjacent_difference uses the binary function \p binary_op to
196 * calculate differences.
198 * \param first The beginning of the input range.
199 * \param last The end of the input range.
200 * \param result The beginning of the output range.
201 * \param binary_op The binary function used to compute differences.
202 * \return The iterator <tt>result + (last - first)</tt>
204 * \tparam InputIterator is a model of <a href="http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a>,
205 * and \p InputIterator's \c value_type is convertible to \p BinaryFunction's \c first_argument_type and \c second_argument_type,
206 * and \p InputIterator's \c value_type is convertible to a type in \p OutputIterator's set of \c value_types.
207 * \tparam OutputIterator is a model of <a href="http://www.sgi.com/tech/stl/OutputIterator.html">Output Iterator</a>.
208 * \tparam BinaryFunction's \c result_type is convertible to a type in \p OutputIterator's set of \c value_types.
210 * \remark Note that \p result is permitted to be the same iterator as \p first. This is
211 * useful for computing differences "in place".
213 * The following code snippet demonstrates how to use \p adjacent_difference to compute
214 * the sum between adjacent elements of a range.
217 * #include <thrust/adjacent_difference.h>
218 * #include <thrust/functional.h>
219 * #include <thrust/device_vector.h>
221 * int h_data[8] = {1, 2, 1, 2, 1, 2, 1, 2};
222 * thrust::device_vector<int> d_data(h_data, h_data + 8);
223 * thrust::device_vector<int> d_result(8);
225 * thrust::adjacent_difference(d_data.begin(), d_data.end(), d_result.begin(), thrust::plus<int>());
227 * // d_data is now [1, 3, 3, 3, 3, 3, 3, 3]
230 * \see http://www.sgi.com/tech/stl/adjacent_difference.html
231 * \see inclusive_scan
233 template <typename InputIterator, typename OutputIterator, typename BinaryFunction>
234 OutputIterator adjacent_difference(InputIterator first, InputIterator last,
235 OutputIterator result,
236 BinaryFunction binary_op);
241 } // end namespace thrust
243 #include <thrust/detail/adjacent_difference.inl>