命名空间
变体
操作

std::ranges::to

来自 cppreference.cn
< cpp‎ | ranges
 
 
范围库 (Ranges library)
范围适配器 (Range adaptors)
 
定义于头文件 <ranges>
template< class C, ranges::input_range R, class... Args >

    requires (!ranges::view<C>)

constexpr C to( R&& r, Args&&... args );
(1) (C++23 起)
template< template< class... > class C,

          ranges::input_range R, class... Args >

constexpr auto to( R&& r, Args&&... 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*/ =
    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)>;

    };
(5) (仅作说明*)
template< class Container, class Reference >

constexpr bool /*container-appendable*/ =
    requires (Container& c, Reference&& ref)
    {
        requires
        (
            requires { c.emplace_back(std::forward<Reference>(ref)); }     ||
            requires { c.push_back(std::forward<Reference>(ref)); }        ||
            requires { c.emplace(c.end(), std::forward<Reference>(ref)); } ||
            requires { c.insert(c.end(), std::forward<Reference>(ref)); }
        );

    };
(6) (仅作说明*)
template< class Reference, class C >
constexpr auto /*container-appender*/( C& c );
(7) (仅作说明*)
template< class R, class T >

concept /*container-compatible-range*/ =
    ranges::input_range<R> &&

    std::convertible_to<ranges::range_reference_t<R>, T>;
(8) (仅作说明*)

Range 转换函数的重载通过调用接受一个 Range 的构造函数、一个 `std::from_range_t` 标签化的 Range 构造函数、一个接受迭代器-哨位对的构造函数,或者通过将源 Range 的每个元素追加到由参数构造的对象中,从作为其第一个参数的源 Range 构造一个新的非视图对象。

1) 以下列方式,从 r 的元素构造一个类型为 C 的对象:
1) 如果 std::constructible_from<C, R, Args...>true,则如同通过从源 Range std::forward<R>(r) 和其余函数参数 std::forward<Args>(args)... 进行直接初始化(而非直接列表初始化)来构造一个类型为 C 的非视图对象。
2) 否则,如果 std::constructible_from<C, std::from_range_t, R, Args...>true,则如同通过从额外的消歧义标签 std::from_range、源 Range std::forward<R>(r) 和其余函数参数 std::forward<Args>(args)... 进行直接初始化(而非直接列表初始化)来构造一个类型为 C 的非视图对象。
3) 否则,如果以下所有条件都为 true,则如同通过从迭代器-哨位对(ranges::begin(r) 作为迭代器,ranges::end(r) 作为哨位,其中迭代器和哨位类型相同。换句话说,源 Range 必须是 common range)和其余函数参数 std::forward<Args>(args)... 进行直接初始化(而非直接列表初始化)来构造一个类型为 C 的非视图对象:
4) 否则,如同通过从其余函数参数 std::forward<Args>(args)... 进行直接初始化(而非直接列表初始化)来构造一个类型为 C 的非视图 Range 对象,并在构造后执行以下等效调用:

if constexpr (ranges::sized_range<R> && /*reservable-container*/<C>)
    c.reserve(static_cast<ranges::range_size_t<C>>(ranges::size(r)));
ranges::for_each(r, /*container-appender*/(c));

(直到 C++26)

if constexpr (ranges::approximately_sized_range<R>
           && /*reservable-container*/<C>)
    c.reserve(static_cast<ranges::range_size_t<C>>(ranges::reserve_hint(r)));
ranges::for_each(r, /*container-appender*/(c));

(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,则上述操作有效:

b) 否则,返回表达式等价于

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 构造。

否则,程序格式错误。
2)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;                      // 未定义
    pointer operator->() const;                       // 未定义
    /*input-iterator*/& operator++();                 // 未定义
    /*input-iterator*/ operator++(int);               // 未定义
    bool operator==(const /*input-iterator*/&) const; // 未定义

};
(仅作说明*)

/*DEDUCE-EXPR*/ 定义如下:

该调用等价于 to<decltype(/*DEDUCE-EXPR*/)>
    (std::forward<R>(r), std::forward<Args>(args)...)
3,4) 返回一个完美转发调用包装器,它同时也是一个 Range 适配器闭包对象 (RangeAdaptorClosureObject)
5) 如果满足 ranges::sized_range 并且有资格进行预留,则为 true
6) 如果一个类型为 Reference 的元素可以通过成员函数调用 emplace_backpush_backemplaceinsert 被追加到 Container,则为 true
7) 返回一个函数对象,调用该返回的函数对象在表达式上等价于向容器中追加一个元素。返回表达式等价于

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

8) 用于容器的定义中,构造一个输入 Range R,其 Range 引用类型必须可转换为 T

目录

[编辑] 参数

r - 一个源 Range 对象
args - 实参列表,用于 (1,2) 构造一个范围,或 (3,4) 绑定到范围适配器闭包对象的最后几个形参
类型要求
-
C 必须是 cv-无限定的类类型 (1,3)

[编辑] 返回值

1,2) 一个构造好的非视图对象。
3,4) 一个未指定类型的范围适配器闭包对象,具有以下属性

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

如果 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]