# std::common_iterator

< cpp‎ | iterator

定义于头文件 `<iterator>` |  |
template< std::input_or_output_iterator I, std::sentinel_for<I> S > requires ( !std::same_as<I, S> && std::copyable<I> ) class common_iterator; |  | (C++20 起)

`std::common_iterator` 是含有迭代器或哨位之一并定义适合的比较运算符 operator== ，从而可以将非共用范围（其中 `I` 与 `S` 有别）表示成 `common_range` 的迭代器 `I` / 哨位 `S` 适配器。
能以 `std::common_iterator` 为迭代器/哨位对所表示的序列与期待 `common_range` 式序列的遗留函数间的“桥梁”。

### 成员函数

(构造函数) (C++20) | 构造新的迭代器适配器 (公开成员函数)
operator= (C++20) | 赋值另一迭代器适配器 (公开成员函数)
operator*operator-> (C++20) | 访问被指向的元素 (公开成员函数)
operator++operator++(int) (C++20) | 推进迭代器适配器 (公开成员函数)

### 成员对象

成员名 | 定义
`var` (私有) | std::variant<I, S> 类型对象，名字仅用于阐释

### 非成员函数

operator== (C++20) | 比较底层迭代器或哨位 (函数模板)
operator- (C++20) | 计算二个迭代器适配器间的距离 (函数模板)
iter_move (C++20) | 转型解引用底层迭代器的结果为其所关联的右值引用类型 (函数)
iter_swap (C++20) | 交换二个底层迭代器所指向的对象 (函数模板)

### 辅助类

std::incrementable_traits<std::common_iterator> (C++20) | 计算 std::common_iterator 类型的关联差类型 (类模板特化)
std::iterator_traits<std::common_iterator> (C++20) | 对 std::counted_iterator 类型的属性提供均一的接口 (类模板特化)

### 示例

    #include <algorithm>
    #include <list>
    #include <iostream>
    #include <iterator>
    #include <string>

    template <class ForwardIter>
    void fire(ForwardIter first, ForwardIter last) {
        std::copy(first, last, std::ostream_iterator<std::string>{std::cout, " "});
    }

    int main() {
        std::list<std::string> stars{"Pollux", "Arcturus", "Mira", "Aldebaran", "Sun"};
        using IT = std::common_iterator<
                       std::counted_iterator<std::list<std::string>::iterator>,
                       std::default_sentinel_t>;
        fire( IT(std::counted_iterator(stars.begin(), stars.size()-1)),
              IT(std::default_sentinel) );
    }

输出：

    Pollux Arcturus Mira Aldebaran

### 引用

- C++20 标准（ISO/IEC 14882:2020）：

  - 23.5.4 Common iterators [iterators.common]

### 参阅

ranges::common_range (C++20) | 指定范围拥有相同的迭代器和哨位类型 (概念)
ranges::common_view views::common (C++20) | 转换 `view` 为 `common_range` (类模板) (范围适配器对象)