25 Algorithms library [algorithms]

25.7 Mutating sequence operations [alg.modifying.operations]

25.7.1 Copy [alg.copy]

template<class InputIterator, class OutputIterator>
  constexpr OutputIterator copy(InputIterator first, InputIterator last,
                                OutputIterator result);

template<input_iterator I, sentinel_for<I> S, weakly_incrementable O>
  requires indirectly_copyable<I, O>
  constexpr ranges::copy_result<I, O> ranges::copy(I first, S last, O result);
template<input_range R, weakly_incrementable O>
  requires indirectly_copyable<iterator_t<R>, O>
  constexpr ranges::copy_result<borrowed_iterator_t<R>, O> ranges::copy(R&& r, O result);

Let N be last - first.

Preconditions: result is not in the range [first, last).

Effects: Copies elements in the range [first, last) into the range [result, result + N) starting from first and proceeding to last.

For each non-negative integer

n < N

, performs *(result + n) = *(first + n).

Returns:

(4.1)
result + N for the overload in namespace std.
(4.2)
{last, result + N} for the overloads in namespace ranges.

Complexity: Exactly N assignments.

🔗

template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2>
  ForwardIterator2 copy(ExecutionPolicy&& policy,
                        ForwardIterator1 first, ForwardIterator1 last,
                        ForwardIterator2 result);

Preconditions: The ranges [first, last) and [result, result + (last - first)) do not overlap.

Effects: Copies elements in the range [first, last) into the range [result, result + (last - first)).

For each non-negative integer n < (last - first), performs *(result + n) = *(first + n).

Returns: result + (last - first).

Complexity: Exactly last - first assignments.

🔗

template<class InputIterator, class Size, class OutputIterator>
  constexpr OutputIterator copy_n(InputIterator first, Size n,
                                  OutputIterator result);
template<class ExecutionPolicy, class ForwardIterator1, class Size, class ForwardIterator2>
  ForwardIterator2 copy_n(ExecutionPolicy&& exec,
                          ForwardIterator1 first, Size n,
                          ForwardIterator2 result);

template<input_iterator I, weakly_incrementable O>
  requires indirectly_copyable<I, O>
  constexpr ranges::copy_n_result<I, O>
    ranges::copy_n(I first, iter_difference_t<I> n, O result);

Let N be

max (0, n)

Mandates: The type Size is convertible to an integral type ([conv.integral], [class.conv]).

Effects: For each non-negative integer

i < N

, performs *(result + i) = *(first + i).

Returns:

(13.1)
result + N for the overloads in namespace std.
(13.2)
{first + N, result + N} for the overload in namespace ranges.

Complexity: Exactly N assignments.

🔗

template<class InputIterator, class OutputIterator, class Predicate>
  constexpr OutputIterator copy_if(InputIterator first, InputIterator last,
                                   OutputIterator result, Predicate pred);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
         class Predicate>
  ForwardIterator2 copy_if(ExecutionPolicy&& exec,
                           ForwardIterator1 first, ForwardIterator1 last,
                           ForwardIterator2 result, Predicate pred);

template<input_iterator I, sentinel_for<I> S, weakly_incrementable O, class Proj = identity,
         indirect_unary_predicate<projected<I, Proj>> Pred>
  requires indirectly_copyable<I, O>
  constexpr ranges::copy_if_result<I, O>
    ranges::copy_if(I first, S last, O result, Pred pred, Proj proj = {});
template<input_range R, weakly_incrementable O, class Proj = identity,
         indirect_unary_predicate<projected<iterator_t<R>, Proj>> Pred>
  requires indirectly_copyable<iterator_t<R>, O>
  constexpr ranges::copy_if_result<borrowed_iterator_t<R>, O>
    ranges::copy_if(R&& r, O result, Pred pred, Proj proj = {});

Let E be:

(15.1)
bool(pred(*i)) for the overloads in namespace std;
(15.2)
bool(invoke(pred, invoke(proj, *i))) for the overloads in namespace ranges,

and N be the number of iterators i in the range [first, last) for which the condition E holds.

Preconditions: The ranges [first, last) and [result, result + (last - first)) do not overlap.

[Note

For the overload with an ExecutionPolicy, there may be a performance cost if iterator_traits<ForwardIterator1>::value_type is not Cpp17MoveConstructible (Table 28).

— end note

]

Effects: Copies all of the elements referred to by the iterator i in the range [first, last) for which E is true.

Returns:

(18.1)
result + N for the overloads in namespace std.
(18.2)
{last, result + N} for the overloads in namespace ranges.

Complexity: Exactly last - first applications of the corresponding predicate and any projection.

Remarks: Stable ([algorithm.stable]).

🔗

template<class BidirectionalIterator1, class BidirectionalIterator2>
  constexpr BidirectionalIterator2
    copy_backward(BidirectionalIterator1 first,
                  BidirectionalIterator1 last,
                  BidirectionalIterator2 result);

template<bidirectional_iterator I1, sentinel_for<I1> S1, bidirectional_iterator I2>
  requires indirectly_copyable<I1, I2>
  constexpr ranges::copy_backward_result<I1, I2>
    ranges::copy_backward(I1 first, S1 last, I2 result);
template<bidirectional_range R, bidirectional_iterator I>
  requires indirectly_copyable<iterator_t<R>, I>
  constexpr ranges::copy_backward_result<borrowed_iterator_t<R>, I>
    ranges::copy_backward(R&& r, I result);

Let N be last - first.

Preconditions: result is not in the range (first, last].

Effects: Copies elements in the range [first, last) into the range [result - N, result) starting from last - 1 and proceeding to first.231

For each positive integer

n \leq N

, performs *(result - n) = *(last - n).

Returns:

(24.1)
result - N for the overload in namespace std.
(24.2)
{last, result - N} for the overloads in namespace ranges.

Complexity: Exactly N assignments.

231)

copy_backward should be used instead of copy when last is in the range [result - N, result).

⮥