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-insertable*/ = requires (Container& c, Reference&& ref)
{
    requires (requires { c.push_back(std::forward<Reference>(ref)); } ||
              requires { c.insert(c.end(), std::forward<Reference>(ref)); });
};

template< class Reference, class C >
constexpr auto /*container-inserter*/( C& c )
{
    if constexpr (requires { c.push_back(std::declval<Reference>()); })
        return std::back_inserter(c);
    else
        return std::inserter(c, c.end());
}

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

Перегрузки функции преобразования диапазона создают новый объект без представления из исходного диапазона в качестве первого аргумента, вызывая конструктор, принимающий диапазон, конструктор, принимающий метку диапазона std::from_range_t, конструктор, принимающий пару итератор-конечный итератор, или путём добавления каждого элемента исходного диапазона в создаваемый объект.

• ranges::common_range<R>
• Если std::iterator_traits<ranges::iterator_t<R>>::iterator_category является корректным и обозначает тип, который удовлетворяет std::derived_from<std::input_iterator_tag>
• std::constructible_from<C, ranges::iterator_t<R>, ranges::sentinel_t<R>, Args...>

if constexpr (ranges::sized_range<R> && /*reservable-container*/<C>)
c.reserve(static_cast<ranges::range_size_t<C>>(ranges::size(r)));
ranges::copy(r, /*container-inserter*/<ranges::range_reference_t<R>>(c));
Если R удовлетворяет sized_range и C удовлетворяет /*reservable-container*/, созданный объект c типа C способен зарезервировать память с начальным размером ranges::size(r) для предотвращения дополнительных выделений при добавлении новых элементов. Каждый элемент диапазона r добавляется в конец c с помощью адаптера back inserter ranges::copy. Данные операции допустимы, если оба следующих условия выполняются:

• std::constructible_from<C, Args...>
• /*container-insertable*/<C, ranges::range_reference_t<R>>

Пусть /*input-iterator*/ — тип только для иллюстрации, который удовлетворяет LegacyInputIterator:

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
};

Пусть /*DEDUCE-EXPR*/ определяется следующим образом:

• C(std::declval<R>(), std::declval<Args>()...), если это выражение корректно.
• В противном случае, C(std::from_range, std::declval<R>(), std::declval<Args>()...), если это выражение корректно.
• В противном случае, C(std::declval</*input-iterator*/>(), std::declval</*input-iterator*/>(), std::declval<Args>()...), если это выражение корректно.
• В противном случае, программа некорректна.

Параметры

Возвращаемое значение

Исключения

Бросает исключение только в случае возникновения исключения при создании объекта без представления.

Примечания

Добавление элементов в контейнер может включать копирование, что может быть менее эффективным, чем перемещение, потому что во время косвенного вызова генерируются lvalue ссылки. Пользователи могут включить использование views::as_rvalue для адаптации диапазона, чтобы его элементы всегда генерировали ссылку rvalue во время косвенного вызова, что подразумевает перемещение.

Скобки обязательны при использовании синтаксиса конвейера.

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

Пример

#include <concepts>
#include <list>
#include <print>
#include <ranges>
#include <vector>
 
int main()
{
    auto vec = std::views::iota(1, 5)
             | std::views::transform([](auto const v){ return v * 2; })
             | std::ranges::to<std::vector>();
 
    static_assert(std::same_as<decltype(vec), std::vector<int>>);
    std::println("{}", vec);
 
    auto lst = vec | std::views::take(3) | std::ranges::to<std::list<double>>();
    std::println("{}", lst);
}

[2, 4, 6, 8]
[2, 4, 6]

Ссылки

• Стандарт C++23 (ISO/IEC 14882:2023):
• 26.5.7 Преобразования диапазонов [range.utility.conv]