std::ranges...opy_result,(3)

📦 version 2024.07.05, in nixpkgs unstable, opensuse-leap 16.0

💅 std::ranges::copy, std::ranges::copy_if, std::ranges::copy_result

okay bestie, gather round — this is from the C++ Standard Library manual (yes the actual one, cppreference.com energy), and it's giving "I just want to move my lil elements from point A to point B" and honestly? iconic.

NAME — std::ranges::copy, std::ranges::copy_if, std::ranges::copy_result, and the whole squad, all spelled exactly like this: std::ranges::copy,std::ranges::copy_if,std::ranges::copy_result,

✨ Synopsis ✨

Defined in header <algorithm> — that's the home base, no cap.

Call signature (the whole cast, in order 💖)

template< std::input_iterator I, std::sentinel_for<I> S,
std::weakly_incrementable O >

requires std::indirectly_copyable<I, O>
(1) (since C++20)
constexpr copy_result<I, O>

    copy( I first, S last, O result );
template< ranges::input_range R, std::weakly_incrementable O >

requires std::indirectly_copyable<ranges::iterator_t<R>, O>
(2) (since C++20)
constexpr copy_result<ranges::borrowed_iterator_t<R>, O>

    copy( R&& r, O result );
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 >
(3) (since C++20)
requires std::indirectly_copyable<I, O>
constexpr copy_if_result<I, O>

    copy_if( I first, S last, O result, Pred pred, Proj proj = {}
);
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 >
(4) (since C++20)
requires std::indirectly_copyable<ranges::iterator_t<R>, O>
constexpr copy_if_result<ranges::borrowed_iterator_t<R>, O>

    copy_if( R&& r, O result, Pred pred, Proj proj = {} );

Helper types 🎀

template< class I, class O >
(5) (since C++20)
using copy_result = ranges::in_out_result<I, O>;
template< class I, class O >
(6) (since C++20)
using copy_if_result = ranges::in_out_result<I, O>;

🌸 So what do they actually DO

They copy the elements in the range defined by [first, last) into another range that starts at result. Chef's kiss. 🫶

  1. Copies all the elements in [first, last), starting from first and gliding on through to last - 1. ⚠️ The behavior is undefined if result is inside the range [first, last) — like, do not do that. In that case, ranges::copy_backward may be used instead (that's your escape hatch, bestie).
  2. Only copies the elements where the predicate pred returns true. The relative order of the elements that get copied is preserved — order stays order, always. ⚠️ The behavior is undefined if the source and destination ranges overlap.

2,4) Exactly the same as (1,3) but with r as the source range, as if using ranges::begin(r) as first and ranges::end(r) as last. Same vibe, shorter hand.

🦋 About the niebloids (iykyk)

The function-like entities described on this page are 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.

In practice, they may be implemented as function objects, or with special compiler extensions. Spooky? A little. Real? Very. 💀

💜 Parameters

  • first, last — 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

⭐ Return value

A ranges::in_out_result containing an input iterator equal to last and an output iterator past the last element copied. Two iterators, one cute little package. 🎁

🔥 Complexity

  • 1,2) Exactly last - first assignments.
  • 3,4) Exactly last - first applications of the predicate and projection, and between 0 and last - first assignments — that's one assignment for every element whose predicate returns true, so it depends on your predicate and your input data. Slay, but conditionally. 💅

🌈 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. Efficiency queen behavior.

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). Left = copy, right = copy_backward. Write that down. 📝

🧚 Possible implementation

copy

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

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;

🍓 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 — two birds, one gorgeous little program:

// Run this code

#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

🎀 See also

  • ranges::copy_backward — copies a range of elements in backwards order (C++20) (niebloid)
  • ranges::reverse_copy — creates a copy of a range that is reversed (C++20) (niebloid)
  • ranges::copy_n — copies a number of elements to a new location (C++20) (niebloid)
  • ranges::fill — assigns a range of elements a certain value (C++20) (niebloid)
  • ranges::remove_copy, ranges::remove_copy_if — copies a range of elements omitting those that satisfy specific criteria (C++20) (niebloid)
  • copy, copy_if — copies a range of elements to a new location (function template) (C++11)

and that's the whole page, bestie — every flag, every template, every warning, untouched. now go forth and copy responsibly 🦋

from http://cppreference.com, dated 2024.06.10 — mwah, stan the standard library for me 💖

📦 where this page comes from