std::copy, std::copy_if
| Defined in header <algorithm>
|
||
| template< class InputIt, class OutputIt > OutputIt copy( InputIt first, InputIt last, OutputIt d_first ); |
(1) | |
| template< class InputIt, class OutputIt, class UnaryPredicate > OutputIt copy_if( InputIt first, InputIt last, |
(2) | (since C++11) |
Copies the elements in the range, defined by [first, last), to another range beginning at d_first. The second function only copies the elements for which the predicate pred returns true. The order of the elements that are not removed is preserved.
For std::copy, the behavior is undefined if d_first is within the range [first, last). In this case, std::copy_backward may be used instead.
For std::copy_if, the behavior is undefined if the source and the destination ranges overlap.
Contents |
[edit] Parameters
| first, last | - | the range of elements to copy |
| d_first | - | the beginning of the destination range. |
| pred | - | unary predicate which returns true for the required elements. The signature of the predicate function should be equivalent to the following: bool pred(const Type &a); The signature does not need to have const &, but the function must not modify the objects passed to it. |
| Type requirements | ||
-InputIt must meet the requirements of InputIterator.
| ||
-OutputIt must meet the requirements of OutputIterator.
| ||
-UnaryPredicate must meet the requirements of Predicate.
| ||
[edit] Return value
Output iterator to the element in the destination range, one past the last element copied.
[edit] Complexity
1) Exactly last - first assignments
2) Exactly last - first applications of the predicate
[edit] Notes
In practice, implementations of std::copy avoid multiple assignments and use bulk copy functions such as std::memmove if the value type is TriviallyCopyable
When copying overlapping ranges, std::copy is appropriate when copying to the left (beginning of the destination range is outside the source range) while std::copy_backward is appropriate when copying to the right (end of the destination range is outside the source range).
[edit] Possible implementation
| First version |
|---|
template<class InputIt, class OutputIt> OutputIt copy(InputIt first, InputIt last, OutputIt d_first) { while (first != last) { *d_first++ = *first++; } return d_first; } |
| Second version |
template<class InputIt, class OutputIt, class UnaryPredicate> OutputIt copy_if(InputIt first, InputIt last, OutputIt d_first, UnaryPredicate pred) { while (first != last) { if (pred(*first)) *d_first++ = *first; first++; } return d_first; } |
[edit] Example
The following code uses copy to both copy the contents of one vector to another and to display the resulting vector:
#include <algorithm> #include <iostream> #include <vector> #include <iterator> #include <numeric> int main() { std::vector<int> from_vector(10); std::iota(from_vector.begin(), from_vector.end(), 0); std::vector<int> to_vector; std::copy(from_vector.begin(), from_vector.end(), std::back_inserter(to_vector)); // or, alternatively, // std::vector<int> to_vector(from_vector.size()); // std::copy(from_vector.begin(), from_vector.end(), to_vector.begin()); // either way is equivalent to // std::vector<int> to_vector = from_vector; std::cout << "to_vector contains: "; std::copy(to_vector.begin(), to_vector.end(), std::ostream_iterator<int>(std::cout, " ")); std::cout << '\n'; }
Output:
to_vector contains: 0 1 2 3 4 5 6 7 8 9
[edit] See also
| copies a range of elements in backwards order (function template) | |
| (C++11) |
copies a number of elements to a new location (function template) |
| assigns a range of elements a certain value (function template) | |
| copies a range of elements omitting those that satisfy specific criteria (function template) | |
| (parallelism TS) |
parallelized version of std::copy (function template) |
| (parallelism TS) |
parallelized version of std::copy_if (function template) |