std::copy, std::copy_if - cppreference.com (original) (raw)

Copies the elements in the range, defined by [first, last), to another range beginning at d_first (copy destination range).

1. Copies all elements in the range [first, last) starting from first and proceeding to last.

If d_first is in [first, last), the behavior is undefined. In this case, std::copy_backward may be used instead.

1. Copies the elements, but executed according to policy.

This overload participates in overload resolution only if all following conditions are satisfied:

If [first, last) and the copy destination range overlaps, the behavior is undefined.

1. Only copies the elements for which the predicate pred returns true. This copy algorithm is stable: the relative order of the elements that are copied is preserved.

If [first, last) and the copy destination range overlaps, the behavior is undefined.

1. Same as (3), but executed according to policy.

This overload participates in overload resolution only if all following conditions are satisfied:

Contents

• 1 Parameters
• 2 Return value
• 3 Complexity
• 4 Exceptions
• 5 Possible implementation
• 6 Notes
• 7 Example
• 8 Defect reports
• 9 See also

[edit] Parameters

[edit] Return value

Output iterator to the element in the destination range, one past the last element copied.

[edit] Complexity

Given \(\scriptsize N\)N as std::distance(first, last):

1,2) Exactly \(\scriptsize N\)N assignments.

3,4) Exactly \(\scriptsize N\)N applications of the predicate pred, and at most \(\scriptsize N\)N assignments.

For the overloads with an ExecutionPolicy, there may be a performance cost if ForwardIt1's value type is not MoveConstructible.

[edit] Exceptions

The overloads with a template parameter named ExecutionPolicy report errors as follows:

• If execution of a function invoked as part of the algorithm throws an exception and ExecutionPolicy is one of the standard policies, std::terminate is called. For any other ExecutionPolicy, the behavior is implementation-defined.
• If the algorithm fails to allocate memory, std::bad_alloc is thrown.

[edit] Possible implementation

[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 and the iterator types satisfy LegacyContiguousIterator.

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] Example

The following code uses std::copy both to copy the contents of one std::vector to another and to display the resulting std::vector.

#include #include #include #include #include   int main() { std::vector from_vector(10); std::iota(from_vector.begin(), from_vector.end(), 0);
std::vector to_vector; std::copy(from_vector.begin(), from_vector.end(), std::back_inserter(to_vector));   // or, alternatively, // std::vector to_vector(from_vector.size()); // std::copy(from_vector.begin(), from_vector.end(), to_vector.begin()); // either way is equivalent to // std::vector to_vector = from_vector;   std::cout << "to_vector contains: "; std::copy(to_vector.begin(), to_vector.end(), std::ostream_iterator(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(std::cout, " "), [](int x) { return x % 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), [](int x) { return x % 3 == 0; });   for (const int x : 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

[edit] Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

[edit] See also