26 Ranges library [ranges]

26.5 Range utilities [range.utility]

26.5.7 Range conversions [range.utility.conv]

26.5.7.1 General [range.utility.conv.general]

The range conversion functions construct an object (usually a container) from a range, by using a constructor taking a range, a from_­range_­t tagged constructor, or a constructor taking a pair of iterators, or by inserting each element of the range into the default-constructed object.
ranges​::​to is applied recursively, allowing the conversion of a range of ranges.
[Example 1: string_view str = "the quick brown fox"; auto words = views::split(str, ' ') | to<vector<string>>(); // words is vector<string>{"the", "quick", "brown", "fox"} — end example]
Let reservable-container be defined as follows: template<class Container> constexpr bool reservable-container = // exposition only sized_­range<Container> && requires(Container& c, range_size_t<Container> n) { c.reserve(n); { c.capacity() } -> same_­as<decltype(n)>; { c.max_size() } -> same_­as<decltype(n)>; };
Let container-insertable be defined as follows: template<class Container, class Ref> constexpr bool container-insertable = // exposition only requires(Container& c, Ref&& ref) { requires (requires { c.push_back(std::forward<Ref>(ref)); } || requires { c.insert(c.end(), std::forward<Ref>(ref)); }); };
Let container-inserter be defined as follows: template<class Ref, class Container> constexpr auto container-inserter(Container& c) { // exposition only if constexpr (requires { c.push_back(declval<Ref>()); }) return back_inserter(c); else return inserter(c, c.end()); }

26.5.7.2 ranges​::​to [range.utility.conv.to]

template<class C, input_­range R, class... Args> requires (!view<C>) constexpr C to(R&& r, Args&&... args);
Returns: An object of type C constructed from the elements of r in the following manner:
template<template<class...> class C, input_­range R, class... Args> constexpr auto to(R&& r, Args&&... args);
Let input-iterator be an exposition-only type: struct input-iterator { // exposition only using iterator_category = input_iterator_tag; using value_type = range_value_t<R>; using difference_type = ptrdiff_t; using pointer = add_pointer_t<range_reference_t<R>>; using reference = range_reference_t<R>; reference operator*() const; pointer operator->() const; input-iterator& operator++(); input-iterator operator++(int); bool operator==(const input-iterator&) const; };
[Note 1:
input-iterator meets the syntactic requirements of Cpp17InputIterator.
— end note]
Let DEDUCE_­EXPR be defined as follows:
  • C(declval<R>(), declval<Args>()...) if that is a valid expression,
  • otherwise, C(from_­range, declval<R>(), declval<Args>()...) if that is a valid expression,
  • otherwise, C(declval<input-iterator>(), declval<input-iterator>(), declval<Args>()...) if that is a valid expression,
  • otherwise, the program is ill-formed.
Returns: to<decltype(DEDUCE_­EXPR)>(std​::​forward<R>(r), std​::​forward<Args>(args)...).

26.5.7.3 ranges​::​to adaptors [range.utility.conv.adaptors]

template<class C, class... Args> requires (!view<C>) constexpr auto to(Args&&... args); template<template<class...> class C, class... Args> constexpr auto to(Args&&... args);
Returns: A range adaptor closure object ([range.adaptor.object]) f that is a perfect forwarding call wrapper ([func.require]) with the following properties:
  • It has no target object.
  • Its bound argument entities bound_­args consist of objects of types decay_­t<Args>... direct-non-list-initialized with std​::​forward<Args>(args)..., respectively.
  • Its call pattern is to<C>(r, bound_­args...), where r is the argument used in a function call expression of f.