Defined in header
template<classInputIt,classOutputIt>OutputItcopy(InputItfirst,InputItlast,OutputItd_first); (1)(constexpr since C++20)template<classInputIt,classOutputIt,classUnaryPred>OutputItcopy_if(InputItfirst,InputItlast,OutputItd_first,UnaryPredpred); (2)(constexpr since C++20)template<classExecutionPolicy,classForwardIt1,classForwardIt2>ForwardIt2copy(ExecutionPolicy&&policy,ForwardIt1first,ForwardIt1last,ForwardIt2d_first); (3) (since C++17)template<classExecutionPolicy,classForwardIt1,classForwardIt2,classUnaryPred>ForwardIt2copy_if(ExecutionPolicy&&policy,ForwardIt1first,ForwardIt1last,ForwardIt2d_first,UnaryPredpred); (4) (since C++17)Copies the elements in the source range [first, last) to the destination range beginning at d_first.
1)copy copies all elements in the source range, starting from first and proceeding to last.
If d_first is in the source range, the behavior is undefined.
2)copy_if only copies the elements for which the predicate pred returns true in the source range, starting from first and proceeding to last.
If the source and destination ranges overlap, the behavior is undefined.
3,4) Same as (1,2), but the copy order is determined by policy.
These overloads participate in overload resolution only if the value of the following expression is true:
std::is_execution_policy_v<std::decay_t<ExecutionPolicy>>
(until C++20)std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>>
(since C++20) If the source and destination ranges overlap, the behavior is undefined.
Parameters
first, last - the pair of iterators defining the source
d_first - the beginning of the destination range pred - unary predicate which returns true for the required elements. The expression pred(v) must be convertible to bool for every argument v of type (possibly const) VT, where VT is the value type of InputIt, regardless of
, and must not modify v. Thus, a parameter type of VT&is not allowed, nor is VT unless for VT a move is equivalent to a copy(since C++11).
policy - the
to use Type requirements -InputIt must meet the requirements of
. -OutputIt must meet the requirements of
. -ForwardIt1, ForwardIt2 must meet the requirements of
. -UnaryPred must meet the requirements of
. Return value
The past-the-end iterator of the destination range.
Complexity
Given N as std::distance(first,last):
1,3) Exactly N assignments.
2,4) Exactly N applications of pred, and at most N assignments.
Exceptions
3,4) During the execution process:
If the temporary memory resources required for parallelization are not available,
is thrown.
If an uncaught exception is thrown while accessing objects via an algorithm argument, the behavior is determined by the execution policy (for
,
is invoked).
Notes
In practice, implementations of std::copy avoid multiple assignments and use bulk copy functions such as
if the value type is
and the iterator types satisfy
.
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).
std::copy_if is stable. The relative order of the elements that are copied is preserved.
For parallel algorithm overloads, there may be a performance cost if ForwardIt1's value type is not
.
Possible implementation
template<classInputIt,classOutputIt>OutputItcopy(InputItfirst,InputItlast,OutputItd_first){for(;first!=last;(void)++first,(void)++d_first)*d_first=*first;returnd_first;}
template<classInputIt,classOutputIt,classUnaryPred>OutputItcopy_if(InputItfirst,InputItlast,OutputItd_first,UnaryPredpred){for(;first!=last;++first)if(pred(*first)){*d_first=*first;++d_first;}returnd_first;}Example
The following code uses std::copy both to copy the contents of one
to another and to display the resulting
.
Run this code
#include<algorithm>#include<iostream>#include<iterator>#include<numeric>#include<vector>intmain(){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';std::cout<<"odd numbers in to_vector are: ";std::copy_if(to_vector.begin(),to_vector.end(),std::ostream_iterator<int>(std::cout," "),[](intx){returnx%2!=0;});std::cout<<'\n';std::cout<<"to_vector contains these multiples of 3: ";to_vector.clear();std::copy_if(from_vector.begin(),from_vector.end(),std::back_inserter(to_vector),[](intx){returnx%3==0;});for(constintx:to_vector)std::cout<<x<<' ';std::cout<<'\n';}Possible output:
to_vector contains: 0 1 2 3 4 5 6 7 8 9 odd numbers in to_vector are: 1 3 5 7 9 to_vector contains these multiples of 3: 0 3 6 9 Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR Applied to Behavior as published Correct behavior
C++11 the return value of std::copy_if was not specified specified
C++11 the stability of std::copy_if was not defined defined See also
(C++20)(C++20)
copies a range of elements to a new location
(algorithm function object)
copies a range of elements in backwards order
(function template & algorithm function object)
(C++20)
creates a copy of a range that is reversed
(function template & algorithm function object)
(C++20)
(C++11)
copies a number of elements to a new location
(function template & algorithm function object)
(C++20)
copy-assigns the given value to every element in a range
(function template & algorithm function object)
(C++20)
copies a range of elements omitting those that satisfy specific criteria
(function template & algorithm function object)
ranges::remove_copyranges::remove_copy_if
(C++20)(C++20)