std::ranges::copy, std::ranges::copy_if, std::ranges::copy_result, std::ranges::copy_if_result
| Defined in header <algorithm>
|
||
| Call signature |
||
template< std::input_iterator I, std::sentinel_for<I> S, std::weakly_incrementable O > requires std::indirectly_copyable<I, O> |
(1) | (since C++20) |
| template< ranges::input_range R, std::weakly_incrementable O > requires std::indirectly_copyable<ranges::iterator_t<R>, O> |
(2) | (since C++20) |
template< std::input_iterator I, std::sentinel_for<I> S, std::weakly_incrementable O, class Proj = std::identity, |
(3) | (since C++20) |
| template< ranges::input_range R, std::weakly_incrementable O, class Proj = std::identity, |
(4) | (since C++20) |
| Helper types |
||
| template< class I, class O > using copy_result = ranges::in_out_result<I, O>; |
(5) | (since C++20) |
| template< class I, class O > using copy_if_result = ranges::in_out_result<I, O>; |
(6) | (since C++20) |
Copies the elements in the range, defined by [first, last), to another range beginning at result.
[first, last) starting from first and proceeding to last - 1. The behavior is undefined if result is within the range [first, last). In this case, ranges::copy_backward may be used instead.The function-like entities described on this page are algorithm function objects (informally known as niebloids), that is:
- Explicit template argument lists cannot be specified when calling any of them.
- None of them are visible to argument-dependent lookup.
- When any of them are found by normal unqualified lookup as the name to the left of the function-call operator, argument-dependent lookup is inhibited.
Contents |
[edit] Parameters
| first, last | - | the iterator-sentinel pair defining the range of elements to copy |
| r | - | the range of elements to copy |
| result | - | the beginning of the destination range. |
| pred | - | predicate to apply to the projected elements |
| proj | - | projection to apply to the elements |
[edit] Return value
A ranges::in_out_result containing an input iterator equal to last and an output iterator past the last element copied.
[edit] Complexity
[edit] Notes
In practice, implementations of ranges::copy avoid multiple assignments and use bulk copy functions such as std::memmove if the value type is TriviallyCopyable and the iterator types satisfy contiguous_iterator.
When copying overlapping ranges, ranges::copy is appropriate when copying to the left (beginning of the destination range is outside the source range) while ranges::copy_backward is appropriate when copying to the right (end of the destination range is outside the source range).
[edit] Possible implementation
| copy (1)(2) |
|---|
struct copy_fn { template<std::input_iterator I, std::sentinel_for<I> S, std::weakly_incrementable O> requires std::indirectly_copyable<I, O> constexpr ranges::copy_result<I, O> operator()(I first, S last, O result) const { for (; first != last; ++first, (void)++result) *result = *first; return {std::move(first), std::move(result)}; } template<ranges::input_range R, std::weakly_incrementable O> requires std::indirectly_copyable<ranges::iterator_t<R>, O> constexpr ranges::copy_result<ranges::borrowed_iterator_t<R>, O> operator()(R&& r, O result) const { return (*this)(ranges::begin(r), ranges::end(r), std::move(result)); } }; inline constexpr copy_fn copy; |
| copy_if (3)(4) |
struct copy_if_fn { template<std::input_iterator I, std::sentinel_for<I> S, std::weakly_incrementable O, class Proj = std::identity, std::indirect_unary_predicate<std::projected<I, Proj>> Pred> requires std::indirectly_copyable<I, O> constexpr ranges::copy_if_result<I, O> operator()(I first, S last, O result, Pred pred, Proj proj = {}) const { for (; first != last; ++first) if (std::invoke(pred, std::invoke(proj, *first))) { *result = *first; ++result; } return {std::move(first), std::move(result)}; } template<ranges::input_range R, std::weakly_incrementable O, class Proj = std::identity, std::indirect_unary_predicate< std::projected<ranges::iterator_t<R>, Proj>> Pred> requires std::indirectly_copyable<ranges::iterator_t<R>, O> constexpr ranges::copy_if_result<ranges::borrowed_iterator_t<R>, O> operator()(R&& r, O result, Pred pred, Proj proj = {}) const { return (*this)(ranges::begin(r), ranges::end(r), std::move(result), std::ref(pred), std::ref(proj)); } }; inline constexpr copy_if_fn copy_if; |
[edit] Example
The following code uses ranges::copy to both copy the contents of one std::vector to another and to display the resulting std::vector.
#include <algorithm> #include <iostream> #include <iterator> #include <numeric> #include <vector> int main() { std::vector<int> source(10); std::iota(source.begin(), source.end(), 0); std::vector<int> destination; std::ranges::copy(source.begin(), source.end(), std::back_inserter(destination)); // or, alternatively, // std::vector<int> destination(source.size()); // std::ranges::copy(source.begin(), source.end(), destination.begin()); // either way is equivalent to // std::vector<int> destination = source; std::cout << "Destination contains: "; std::ranges::copy(destination, std::ostream_iterator<int>(std::cout, " ")); std::cout << '\n'; std::cout << "Odd numbers in destination are: "; std::ranges::copy_if(destination, std::ostream_iterator<int>(std::cout, " "), [](int x) { return (x % 2) == 1; }); std::cout << '\n'; }
Output:
Destination contains: 0 1 2 3 4 5 6 7 8 9 Odd numbers in destination are: 1 3 5 7 9
[edit] See also
| (C++20) |
copies a range of elements in backwards order (algorithm function object) |
| (C++20) |
creates a copy of a range that is reversed (algorithm function object) |
| (C++20) |
copies a number of elements to a new location (algorithm function object) |
| (C++20) |
assigns a range of elements a certain value (algorithm function object) |
| (C++20)(C++20) |
copies a range of elements omitting those that satisfy specific criteria (algorithm function object) |
| (C++11) |
copies a range of elements to a new location (function template) |
