std::ranges::to
定义于头文件 <ranges> |
||
template< class C, ranges::input_range R, class... Args > requires (!ranges::view<C>) |
(1) | (C++23 起) |
template< template< class... > class C, ranges::input_range R, class... Args > |
(2) | (C++23 起) |
template< class C, class... Args > requires (!ranges::view<C> constexpr /*range adaptor closure*/ to( Args&&... args ); |
(3) | (C++23 起) |
template< template< class... > class C, class... Args > constexpr /*range adaptor closure*/ to( Args&&... args ); |
(4) | (C++23 起) |
帮助模板 |
||
template< class Container > constexpr bool /*reservable-container*/ = |
(5) | (仅作说明*) |
template< class Container, class Reference > constexpr bool /*container-appendable*/ = |
(6) | (仅作说明*) |
template< class Reference, class C > constexpr auto /*container-appender*/( C& c ); |
(7) | (仅作说明*) |
template< class R, class T > concept /*container-compatible-range*/ = |
(8) | (仅作说明*) |
Range 转换函数的重载通过调用接受一个 Range 的构造函数、一个 `std::from_range_t` 标签化的 Range 构造函数、一个接受迭代器-哨位对的构造函数,或者通过将源 Range 的每个元素追加到由参数构造的对象中,从作为其第一个参数的源 Range 构造一个新的非视图对象。
C
的对象:C
不满足 input_range
,或 std::convertible_to<ranges::range_reference_t<R>, ranges::range_value_t<C>> 为 trueC
的非视图对象。C
的非视图对象。C
的非视图对象:- 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...>
C
的非视图 Range 对象,并在构造后执行以下等效调用:
if constexpr (ranges::sized_range<R> && /*reservable-container*/<C>) |
(直到 C++26) |
if constexpr (ranges::approximately_sized_range<R> |
(C++26 起) |
如果
R
满足 sized_range
(C++26 前)approximately_sized_range
(C++26 起) 且 C
满足 reservable-container
,则构造的类型为 C
的对象 c 能够以初始存储大小 ranges::size(r)(C++26 前)ranges::reserve_hint(r)(C++26 起) 来预留存储空间,以防止在插入新元素时发生额外的内存分配。 r 的每个元素都被附加到 c 上。如果以下两个条件都为 true,则上述操作有效:
- std::constructible_from<C, Args...>
-
container-appendable
<C, ranges::range_reference_t<R>>
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,这允许在 Range 内进行嵌套的 Range 构造。
令 /*input-iterator*/ 为一个仅用于阐述的类型,它满足 遗留输入迭代器 (LegacyInputIterator)
struct /*input-iterator*/ { |
(仅作说明*) | |
令 /*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>()...),如果该表达式有效。 - 否则,程序格式错误。
(std::forward<R>(r), std::forward<Args>(args)...)。
Reference
的元素可以通过成员函数调用 emplace_back
、push_back
、emplace
或 insert
被追加到 Container
,则为 true。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));
};
R
,其 Range 引用类型必须可转换为 T
。目录 |
[编辑] 参数
r | - | 一个源 Range 对象 |
args | - | 实参列表,用于 (1,2) 构造一个范围,或 (3,4) 绑定到范围适配器闭包对象的最后几个形参 |
类型要求 | ||
-C 必须是 cv-无限定的类类型 (1,3) |
[编辑] 返回值
ranges::to 返回类型
成员对象
返回的对象表现得好像它没有目标对象,只有一个 std::tuple 对象 tup
,该对象使用 std::tuple<std::decay_t<Args>...>(std::forward<Args>(args)...) 构造,但返回对象的赋值行为是未指定的,且名称仅用于阐述。
构造函数
ranges::to
(3,4) 的返回类型表现得好像其复制/移动构造函数执行成员级的复制/移动。如果其所有成员对象(如上所述)都是可复制构造 (CopyConstructible)的,那么它就是可复制构造的,否则如果它们都是可移动构造 (MoveConstructible)的,那么它就是可移动构造的。
成员函数 operator()
给定一个先前调用 range::to</* 见下文 */>(args...) 得到的对象 G
,当一个指代 G
的泛左值 g
在函数调用表达式 g(r) 中被调用时,会发生对所存储对象的调用,如同通过以下方式:
- ranges::to</* 见下文 */>(r, std::get<Ns>(g.tup)...),其中
- r 是一个源范围对象,必须满足
input_range
。 - Ns 是一个整数包 0, 1, ..., (sizeof...(Args) - 1)。
- 如果
g
在调用表达式中是左值,那么它在调用表达式中就是左值,否则是右值。因此 std::move(g)(r) 可以将绑定的实参移动到调用中,而 g(r) 会进行复制。 - 指定的模板实参是 (3)
C
或 (4) 从一个类模板C
推导出的类型,该模板必须不满足view
。
- r 是一个源范围对象,必须满足
如果 g
的类型是 volatile-限定的,那么程序是病态的。
[编辑] 异常
仅当构造非视图对象时抛出异常。
[编辑] 注意
将元素插入容器可能涉及复制,其效率可能低于移动,因为在间接调用期间会产生左值引用。用户可以选择使用 views::as_rvalue 来适配范围,以使其元素在间接调用期间始终产生右值引用,这意味着移动。
使用管道语法时,括号是强制性的。
auto vec = r | std::ranges::to<std::vector>; // Error auto vec = r | std::ranges::to<std::vector>(); // OK
特性测试宏 | 值 | 标准 | 特性 |
---|---|---|---|
__cpp_lib_ranges_to_container |
202202L |
(C++23) | std::ranges::to
|
[编辑] 示例
预览链接:Compiler Explorer
#include <boost/container/devector.hpp> #include <concepts> #include <initializer_list> #include <list> #include <print> #include <ranges> #include <regex> #include <string> #include <vector> #ifndef __cpp_lib_format_ranges #include <format> #include <sstream> auto print_aid(const auto& v) { std::ostringstream out; out << '['; for (int n{}; const auto& e : v) out << (n++ ? ", " : "") << e; out << ']'; return out; } template<typename T> struct std::formatter<std::vector<T>, char> { template<class ParseContext> constexpr ParseContext::iterator parse(ParseContext& ctx) { return ctx.begin(); } template<class FmtContext> FmtContext::iterator format(auto const& s, FmtContext& ctx) const { auto out{print_aid(s)}; return std::ranges::copy(std::move(out).str(), ctx.out()).out; } }; template<typename T> struct std::formatter<std::list<T>, char> { template<class ParseContext> constexpr ParseContext::iterator parse(ParseContext& ctx) { return ctx.begin(); } template<class FmtContext> FmtContext::iterator format(auto const& s, FmtContext& ctx) const { auto out{print_aid(s)}; return std::ranges::copy(std::move(out).str(), ctx.out()).out; } }; #endif 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("{}", vec); auto list = vec | std::views::take(3) | std::ranges::to<std::list<double>>(); std::println("{}", 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); } }
输出
[2, 4, 6, 8] [2, 4, 6]
[编辑] 缺陷报告
下列更改行为的缺陷报告追溯地应用于以前出版的 C++ 标准。
缺陷报告 | 应用于 | 发布时的行为 | 正确的行为 |
---|---|---|---|
LWG 3984 | C++23 | ranges::to 的嵌套构造分支导致如果 R& 不构成 viewable_range ,则程序是病态的 |
使其格式正确 |
LWG 4016 | C++23 | 容器插入分支ranges::to 涉及使用插入迭代器 |
替换为直接附加 元素到容器 |
[编辑] 引用
- C++23 标准 (ISO/IEC 14882:2024)
- 26.5.7 范围转换 [range.utility.conv]