26 Algorithms library [algorithms]

26.7 Mutating sequence operations [alg.modifying.operations]

26.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&& exec,
                        ForwardIterator1 first, ForwardIterator1 last,
                        ForwardIterator2 result);

template<execution-policy Ep, random_access_iterator I, sized_sentinel_for<I> S,
         random_access_iterator O, sized_sentinel_for<O> OutS>
  requires indirectly_copyable<I, O>
  ranges::copy_result<I, O>
    ranges::copy(Ep&& exec, I first, S last, O result, OutS result_last);
template<execution-policy Ep, sized-random-access-range R, sized-random-access-range OutR>
  requires indirectly_copyable<iterator_t<R>, iterator_t<OutR>>
  ranges::copy_result<borrowed_iterator_t<R>, borrowed_iterator_t<OutR>>
    ranges::copy(Ep&& exec, R&& r, OutR&& result_r);

Let result_last be result + (last - first) for the overload in namespace std.

Let N be min(last - first, result_last - result).

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

Effects: Copies elements in the range [first, first + N) into the range [result, result + N).

For each non-negative integer

n < N

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

Returns:

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

Complexity: Exactly N 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);

template<execution-policy Ep, random_access_iterator I, random_access_iterator O,
         sized_sentinel_for<O> OutS>
  requires indirectly_copyable<I, O>
  ranges::copy_n_result<I, O>
    ranges::copy_n(Ep&& exec, I first, iter_difference_t<I> n, O result, OutS result_last);

Let M be max(0, n).

Let result_last be result + M for the overloads with no parameter result_last.

Let N be

min (result_last - result, M)

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:

(17.1)
result + N for the overloads in namespace std.
(17.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 = {});

template<execution-policy Ep, random_access_iterator I, sized_sentinel_for<I> S,
          random_access_iterator O, sized_sentinel_for<O> OutS,
          class Proj = identity, indirect_unary_predicate<projected<I, Proj>> Pred>
  requires indirectly_copyable<I, O>
  ranges::copy_if_result<I, O>
    ranges::copy_if(Ep&& exec, I first, S last, O result, OutS result_last,
                    Pred pred, Proj proj = {});
template<execution-policy Ep, sized-random-access-range R, sized-random-access-range OutR,
          class Proj = identity,
          indirect_unary_predicate<projected<iterator_t<R>, Proj>> Pred>
  requires indirectly_copyable<iterator_t<R>, iterator_t<OutR>>
  ranges::copy_if_result<borrowed_iterator_t<R>, borrowed_iterator_t<OutR>>
    ranges::copy_if(Ep&& exec, R&& r, OutR&& result_r, Pred pred, Proj proj = {});

Let E(i) be:

(19.1)
bool(pred(*i)) for the overloads in namespace std;
(19.2)
bool(invoke(pred, invoke(proj, *i))) for the overloads in namespace ranges.

Let:

(20.1)
M be the number of iterators i in the range [first, last) for which the condition E(i) holds;
(20.2)
result_last be result + M for the overloads with no parameter result_last or result_r;
(20.3)
N be min(M, result_last - result).

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

[Note 1:

For the parallel algorithm overload in namespace std, there can be a performance cost if iterator_traits<ForwardIterator1>::value_type does not meet the Cpp17MoveConstructible (Table 31) requirements.

For the parallel algorithm overloads in namespace ranges, there can be a performance cost if iter_value_t<I> does not model move_constructible .

— end note]

Effects: Copies the first N elements referred to by the iterator i in the range [first, last) for which E(i) is true into the range [result, result + N).

Returns:

(23.1)
result + N for the overloads in namespace std.
(23.2)
{last, result + N} for the overloads in namespace ranges.
(23.3)
Otherwise, {j, result_last} for the overloads in namespace ranges, where j is the iterator in [first, last) for which E(j) holds and there are exactly N iterators i in [first, j) for which E(i) holds.

Complexity: At most 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.201

For each positive integer n ≤ N, performs *(result - n) = *(last - n).

Returns:

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

Complexity: Exactly N assignments.

201)201)

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