std::ranges::to

template< class C, ranges::input_range R, class... Args >
    requires (!ranges::view<C>)
constexpr C to( R&& r, Args&&... args );

template< template< class... > class C,
          ranges::input_range R, class... Args >
constexpr auto to( R&& r, Args&&... args );

template< class C, class... Args >
    requires (!ranges::view<C>)
constexpr /*range adaptor closure*/ to( Args&&... args );

template< template< class... > class C, class... Args >
constexpr /*range adaptor closure*/ to( Args&&... args );

template< class Container >
constexpr bool /*reservable-container*/ =
    ranges::sized_range<Container> &&
    requires (Container& c, ranges::range_size_t<Container> n)
    {
        c.reserve(n);
        { c.capacity() } -> std::same_as<decltype(n)>;
        { c.max_size() } -> std::same_as<decltype(n)>;
    };

template< class Container, class Reference >
constexpr bool /*container-appendable*/ =
    requires (Container& c, Reference&& ref)
    {
        requires
        (
            requires { c.emplace_back(std::forward<Reference>(ref)); }     ||
            requires { c.push_back(std::forward<Reference>(ref)); }        ||
            requires { c.emplace(c.end(), std::forward<Reference>(ref)); } ||
            requires { c.insert(c.end(), std::forward<Reference>(ref)); }
        );
    };

template< class Reference, class C >
constexpr auto /*container-appender*/( C& c );

template< class R, class T >
concept /*container-compatible-range*/ =
    ranges::input_range<R> &&
    std::convertible_to<ranges::range_reference_t<R>, T>;

1) Создаёт объект типа C из элементов r следующим образом:

a) Если C не удовлетворяет input_range или std::convertible_to<ranges::range_reference_t<R>, ranges::range_value_t<C>> имеет значение true:

1) Создание объекта, не являющегося представлением, как если бы выполнялась прямая инициализация (но не прямая инициализация списком) объекта типа C исходным диапазоном std::forward<R>(r) и остальными функциональными аргументами std::forward<Args>(args)..., если std::constructible_from<C, R, Args...> имеет значение true.

2) В противном случае создание объекта, не являющегося представлением, как если бы выполнялась прямая инициализация (но не прямая инициализация списком) объекта типа C дополнительным тегом устранения неоднозначности std::from_range, исходным диапазоном std::forward<R>(r) и остальными функциональными аргументами std::forward<Args>(args)..., если std::constructible_from<C, std::from_range_t, R, Args...> имеет значение true.

b) В противном случае возвращаемое выражение эквивалентно

to<C>(ranges::ref_view(r) | views::transform([](auto&& elem)
{
    return to<ranges::range_value_t<C>>(std::forward<decltype(elem)>(elem));
}), std::forward<Args>(args)...)

Это позволяет создавать вложенные диапазоны внутри диапазона, если ranges::input_range<ranges::range_reference_t<C>> имеет значение true. В противном случае программа некорректна.

struct /*input-iterator*/
{
    using iterator_category = std::input_iterator_tag;
    using value_type = ranges::range_value_t<R>;
    using difference_type = std::ptrdiff_t;
    using pointer = std::add_pointer_t<ranges::range_reference_t<R>>;
    using reference = ranges::range_reference_t<R>;
    reference operator*() const;                      // not defined
    pointer operator->() const;                       // not defined
    /*input-iterator*/& operator++();                 // not defined
    /*input-iterator*/ operator++(int);               // not defined
    bool operator==(const /*input-iterator*/&) const; // not defined
};

3,4) Возвращает обёртку вызова с идеальной передачей аргументов, которая также является объектом замыкания адаптера диапазона (RangeAdaptorClosureObject).

5) Является true, если удовлетворяет ranges::sized_range и может резервировать память.

6) Является true, если один элемент типа Reference может быть добавлен в Container посредством вызова функции-члена emplace_back, push_back, emplace или insert.

7) Возвращает функциональный объект, вызов которого эквивалентен по выражению добавлению одного элемента в контейнер. Возвращаемое выражение эквивалентно

return [&c]<class Reference>(Reference&& ref)
{
    if constexpr (requires { c.emplace_back(std::declval<Reference>()); })
        c.emplace_back(std::forward<Reference>(ref));
    else if constexpr (requires { c.push_back(std::declval<Reference>()); })
        c.push_back(std::forward<Reference>(ref));
    else if constexpr (requires { c.emplace(c.end(),
                                            std::declval<Reference>()); })
        c.emplace(c.end(), std::forward<Reference>(ref));
    else
        c.insert(c.end(), std::forward<Reference>(ref));
};

8) Используется в определении контейнеров при создании входного диапазона R, тип ссылки на элементы которого должен быть преобразуем в T.

1,2) Созданный объект, не являющийся представлением.

3,4) Объект замыкания адаптера диапазона неуказанного типа со следующими свойствами:

Тип возвращаемого значения ranges::to

Объекты-члены

Возвращённый объект ведёт себя так, как если бы у него не было целевого объекта и он содержал объект std::tuple tup, созданный с помощью std::tuple<std::decay_t<Args>...>(std::forward<Args>(args)...); при этом поведение присваивания возвращённого объекта не указано, а имена приведены только для иллюстрации.

Конструкторы

Тип возвращаемого значения ranges::to (3,4) ведёт себя так, как если бы его конструкторы копирования/перемещения выполняли поэлементное копирование/перемещение. Он удовлетворяет требованиям CopyConstructible, если все его объекты-члены (указанные выше) удовлетворяют требованиям CopyConstructible, и в противном случае удовлетворяет требованиям MoveConstructible.

Функция-член operator()

Если объект G, полученный при более раннем вызове range::to</* see below */>(args...), вызывается в выражении вызова функции g(r) через glvalue g, обозначающее G, то сохранённый объект вызывается так, как если бы выполнялось

• ranges::to</* see below */>(r, std::get<Ns>(g.tup)...), где
• r — объект исходного диапазона, который должен удовлетворять требованиям input_range.
• Ns — целочисленный набор 0, 1, ..., (sizeof...(Args) - 1).
• g является lvalue в выражении вызова, если он является lvalue в этом выражении, и в противном случае является rvalue. Таким образом, std::move(g)(r) может переместить привязанные аргументы в вызов, тогда как g(r) скопировал бы их.
• Указанный аргумент шаблона — это (3) C или (4) выведенный тип из шаблона класса C, который не должен удовлетворять требованиям view.

Программа некорректна, если g имеет тип с квалификатором volatile.

auto vec = r | std::ranges::to<std::vector>;   // Error
auto vec = r | std::ranges::to<std::vector>(); // OK

#include <boost/container/devector.hpp>
#include <concepts>
#include <initializer_list>
#include <list>
#include <print>
#include <ranges>
#include <regex>
#include <string>
#include <vector>

int main()
{
    auto vec = std::views::iota(1, 5)
             | std::views::transform([](int v){ return v * 2; })
             | std::ranges::to<std::vector>();

    static_assert(std::same_as<decltype(vec), std::vector<int>>);
    std::println("1) {}", vec);

    auto list = vec | std::views::take(3) | std::ranges::to<std::list<double>>();
    std::println("2) {}", list);
}

void ctor_demos()
{
    // 1.a.1) Direct init
    {
        char array[]{'a', 'b', '\0', 'c'};

        // Argument type is convertible to result value type:
        auto str_to = std::ranges::to<std::string>(array);
        // Equivalent to
        std::string str(array);

        // Result type is not an input range:
        auto re_to = std::ranges::to<std::regex>(array);
        // Equivalent to
        std::regex re(array);
    }

    // 1.a.2) from_range ctor
    {
        auto list = {'a', 'b', '\0', 'c'};

        // Argument type is convertible to result value type:
        auto str_to = std::ranges::to<std::string>(list);
        // Equivalent to
        // std::string str(std::from_range, list);

        // Result type is not an input range:
        [[maybe_unused]]
        auto pair_to = std::ranges::to<std::pair<std::from_range_t, bool>>(true);
        // Equivalent to
        std::pair<std::from_range_t, bool> pair(std::from_range, true);
    }

    // 1.a.3) iterator pair ctor
    {
        auto list = {'a', 'b', '\0', 'c'};

        // Argument type is convertible to result value type:
        auto devector_to = std::ranges::to<boost::container::devector<char>>(list);
        // Equivalent to
        boost::container::devector<char> devector(std::ranges::begin(list),
                                                  std::ranges::end(list));

        // Result type is not an input range:
        std::regex re;
        auto it_to = std::ranges::to<std::cregex_iterator>(list, re);
        // Equivalent to
        std::cregex_iterator it(std::ranges::begin(list), std::ranges::end(list), re);
    }
}

1) [2, 4, 6, 8]
2) [2, 4, 6]