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

The overloads of the range conversion function construct a new non-view object from a source range as its first argument by calling a constructor taking a range, a std::from_range_t tagged ranged constructor, a constructor taking an iterator-sentinel pair, or by back inserting each element of the source range into the arguments-constructed object.

• ranges::common_range<R>
• If std::iterator_traits<ranges::iterator_t<R>>::iterator_category is valid and denotes a type that satisfies 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));

If the R satisfies sized_range and C satisfies /*reservable-container*/, the constructed object c of type C is able to reserve storage with the initial storage size ranges::size(r) to prevent additional allocations during inserting new elements. Each range reference element of r is back inserted to c through ranges::copy with back inserter adaptor. The operations above are valid if both of the conditions below are true:

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

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

Let /*input-iterator*/ be an exposition only type that satisfies LegacyInputIterator:

struct /*input-iterator*/ {                         // exposition only
  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
};

Let /*DEDUCE-EXPR*/ be defined as follows:

• C(std::declval<R>(), std::declval<Args>()...), if that expression is valid.
• Otherwise, C(std::from_range, std::declval<R>(), std::declval<Args>()...), if that expression is valid.
• Otherwise, C(std::declval</*input-iterator*/>(), std::declval</*input-iterator*/>(), std::declval<Args>()...), if that expression is valid.
• Otherwise, the program is ill-formed.

Parameters

Return value

Exceptions

Only throws if construction of a range object throws.

Notes

The insertion of elements into the container may involve copy which can be more inefficient than move because lvalue references are produced during the indirection call. Users can opt-in to use views::as_rvalue to adapt the range in order for their elements to always produce an rvalue reference during the indirection call which implies move.

Example

#include <algorithm>
#include <concepts>
#include <iostream>
#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::ranges::for_each(vec, [](auto const v){ std::cout << v << ' '; });
}

2 4 6 8

References

• C++23 standard (ISO/IEC 14882:2023):
• 26.5.7 Range conversions [range.utility.conv]