C++ Reference ยท Algorithms
C++23 std::ranges::to
Reference for std::ranges::to: turn any range or view pipeline into a vector, set, map or string. Syntax, nested ranges, pipe form and common compile errors.
Views are lazy: a pipeline such as numbers | filter(...) | transform(...) does not hold any data of its own. When you want the results stored in a real container, you materialize the range. In C++23 that is a one-liner: std::ranges::to<std::vector>(range), or in the pipe form range | std::ranges::to<std::vector>().
std::ranges::to lives in <ranges>. You name the target container, either as a complete type (std::vector<int>) or as a class template (std::vector, with the element type deduced from the range). It works with every standard container, std::string, and your own containers if they can be constructed from a range or an iterator pair.
auto evens = numbers | std::views::filter([](int n) { return n % 2 == 0; }) | std::ranges::to<std::vector>();
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Syntax
// Container is a complete type template<class C, input_range R, class... Args> constexpr C std::ranges::to(R&& r, Args&&... args); // Container is a class template: the element type is deduced from R template<template<class...> class C, input_range R, class... Args> constexpr auto std::ranges::to(R&& r, Args&&... args); // Pipe forms template<class C, class... Args> constexpr auto std::ranges::to(Args&&... args); r | std::ranges::to<std::vector>();
| Name | Description |
|---|---|
C |
The target container: a type (std::vector<int>) or a template name (std::vector). |
r |
The source range. It must be an input range. |
args... |
Extra arguments forwarded to the container's constructor, such as an allocator. |
Returns: the new container, with the elements of the range converted to its value type.
Errors / undefined behavior: none of its own. If the container cannot be built from the range, you get a compile error. Converting elements follows the usual conversion rules.
Usage notes
- How it constructs. The library tries the cheapest way: a constructor taking
std::from_range_t(C++23 containers all have one), then a range-based iterator-pair constructor, then reserving space and inserting one by one (push_back,insert). The container's own size estimate is used when the range is sized, so avectorallocates once. - Nested ranges. If the container's elements are themselves ranges (such as
vector<string>from a range of subranges),toconverts the inner ranges too, recursively. That is whysplitpieces can becomestd::stringdirectly. - Common ranges are not required, unlike the old iterator-pair constructors. A view with a sentinel works.
- Containers of pairs. For
std::mapandstd::unordered_mapthe range must producepairs (or things convertible to one), as in the first example. Aviews::zipyields tuple-like elements, so check that your library converts them, or map them tostd::pairwithtransform. - A view of references.
std::vector<int>built fromv | views::filter(...)copies theints. To store references, usestd::vector<std::reference_wrapper<T>>yourself. - Not a view. The result owns its data and is independent of the source, which is the point: it is the safe way to return the result of a pipeline from a function.
- Without C++23. Use the iterator-pair constructor on a
std::ranges::common_view, orstd::ranges::copyinto a container, or a loop callingpush_back. - Compile errors. "no match for call to
to" almost always means the element type is wrong for the container (for example, a map needs pairs) or a template name was used when the element type could not be deduced. - Performance. A pipeline evaluated through
toruns exactly once. For large data with a known size, passing the range straight to a container does one allocation; chainingfilterloses the size and may reallocate as the vector grows.
Related
- Range views, Composing views, C++23 range additions,
std::vector,std::map - Lessons: Ranges, Vectors