`<iterator>` 函数

项目
10/15/2023

`advance`

使迭代器递增指定数量的位置。

template <class InputIterator, class Distance>
void advance(InputIterator& InIt, Distance Off);

参数

InIt
要递增的迭代器，且必须满足输入迭代器的需求。

Off
可转换为迭代器的距离类型的整型值，用于指定要将迭代器位置前移的递增数。

备注

范围必须非奇数，这种情况下，迭代器必须可解引用或超过结尾。

如果InputIterator满足双向迭代器类型的需求，Off可以是负数。如果InputIterator为输入迭代器类型或向前迭代器类型，Off必须为非负数。

当 InputIterator 满足随机访问迭代器的需求时，前移函数具有固定复杂度；否则具有线性复杂度，因此可能会产生较高的成本。

示例

// iterator_advance.cpp
// compile with: /EHsc
#include <iterator>
#include <list>
#include <iostream>

int main()
{
    using namespace std;

    list<int> L;
    for (int i = 1; i < 9; ++i)
    {
        L.push_back(i);
    }
    list<int>::iterator LPOS = L.begin();

    cout << "The list L is: ( ";
    for (auto L_Iter = L.begin(); L_Iter != L.end(); L_Iter++)
    {
        cout << *L_Iter << " ";
    }
    cout << ")." << endl;

    cout << "The iterator LPOS initially points to the first element: "
        << *LPOS << "." << endl;

    advance(LPOS, 4);
    cout << "LPOS is advanced 4 steps forward to point"
        << " to the fifth element: "
        << *LPOS << "." << endl;

    advance(LPOS, -3);
    cout << "LPOS is moved 3 steps back to point to the "
        << "2nd element: " << *LPOS << "." << endl;
}

The list L is: ( 1 2 3 4 5 6 7 8 ).
The iterator LPOS initially points to the first element: 1.
LPOS is advanced 4 steps forward to point to the fifth element: 5.
LPOS is moved 3 steps back to point to the 2nd element: 2.

`back_inserter`

创建一个可以在指定容器的后面插入元素的迭代器。

template <class Container>
back_insert_iterator<Container> back_inserter(Container& Cont);

参数

Cont
一个容器，将向其执行后插入。

返回值

与容器对象 Cont 关联的 back_insert_iterator。

备注

C++ 标准库中，此自变量必须引用具有成员函数push_back: deque 类、list 类或vector 类的三个序列容器中的一个容器。

示例

// iterator_back_inserter.cpp
// compile with: /EHsc
#include <iterator>
#include <vector>
#include <iostream>

int main()
{
    using namespace std;

    vector<int> vec;
    for (int i = 0; i < 3; ++i)
    {
        vec.push_back(i);
    }

    cout << "The initial vector vec is: ( ";
    for (auto vIter = vec.begin(); vIter != vec.end(); vIter++)
    {
        cout << *vIter << " ";
    }
    cout << ")." << endl;

    // Insertions can be done with template function
    back_insert_iterator<vector<int> > backiter(vec);
    *backiter = 30;
    backiter++;
    *backiter = 40;

    // Alternatively, insertions can be done with the
    // back_insert_iterator member function
    back_inserter(vec) = 500;
    back_inserter(vec) = 600;

    cout << "After the insertions, the vector vec is: ( ";
    for (auto vIter = vec.begin(); vIter != vec.end(); vIter++)
    {
        cout << *vIter << " ";
    }
    cout << ")." << endl;
}

The initial vector vec is: ( 0 1 2 ).
After the insertions, the vector vec is: ( 0 1 2 30 40 500 600 ).

`begin`

检索一个指向指定容器中第一个元素的迭代器。

template <class Container>
auto begin(Container& cont)  `
   -> decltype(cont.begin());

template <class Container>
auto begin(const Container& cont)   `
   -> decltype(cont.begin());

template <class Ty, class Size>
Ty *begin(Ty (& array)[Size]);

参数

cont
容器。

array
Ty 类型对象的数组。

返回值

前两个模板函数返回 cont.begin()。第一个函数为非常量；第二个函数为常量。

第三个模板函数返回 array。

示例

当需要多个泛型行为时，我们建议使用此模板函数来代替容器成员 begin()。

// cl.exe /EHsc /nologo /W4 /MTd
#include <algorithm>
#include <functional>
#include <iostream>
#include <iterator>
#include <vector>

template <typename C> void reverse_sort(C& c)
{
    std::sort(std::begin(c), std::end(c), std::greater<>());
}

template <typename C> void print(const C& c)
{
    for (const auto& e : c)
    {
        std::cout << e << " ";
    }
    std::cout << "\n";
}

int main() 
{
    std::vector<int> v = { 11, 34, 17, 52, 26, 13, 40, 20, 10, 5, 16, 8, 4, 2, 1 };

    print(v);
    reverse_sort(v);
    print(v);

    std::cout << "--\n";

    int arr[] = { 23, 70, 35, 106, 53, 160, 80, 40, 20, 10, 5, 16, 8, 4, 2, 1 };

    print(arr);
    reverse_sort(arr);
    print(arr);
}

11 34 17 52 26 13 40 20 10 5 16 8 4 2 1
52 40 34 26 20 17 16 13 11 10 8 5 4 2 1
--
23 70 35 106 53 160 80 40 20 10 5 16 8 4 2 1
160 106 80 70 53 40 35 23 20 16 10 8 5 4 2 1

除常规数组外，函数 reverse_sort 支持任何类型的容器，因为它调用 begin() 的非成员版本。编码reverse_sort以使用容器成员begin()：

template <typename C>
void reverse_sort(C& c) {
    using std::begin;
    using std::end;

    std::sort(c.begin(), c.end(), std::greater<>());

}

然后向其发送数组，导致此编译器错误：

error C2228: left of '.begin' must have class/struct/union

`cbegin`

检索指向指定容器中第一个元素的常量（只读）迭代器。

template <class Container>
auto cbegin(const Container& cont)
   -> decltype(cont.begin());

参数

cont
容器或initializer_list。

返回值

一个 cont.begin() 常数。

备注

此函数适用于initializer_list和所有 C++ 标准库容器。

可以使用此成员函数替代 begin() 模板函数，以保证返回值为 const_iterator。它一般与 auto 类型推导关键字一起使用，如以下示例所示。在此示例中，将 Container 视为可修改（非 const）容器或支持 begin() 与 cbegin() 的任何类型的 initializer_list。

auto i1 = Container.begin();
// i1 is Container<T>::iterator
auto i2 = Container.cbegin();

// i2 is Container<T>::const_iterator

`cend`

检索指向指定容器中最后元素之后的元素的常量（只读）迭代器。

template <class Container>
auto cend(const Container& cont)
   -> decltype(cont.end());

参数

cont
容器或initializer_list。

返回值

一个 cont.end() 常数。

备注

此函数适用于initializer_list和所有 C++ 标准库容器。

可以使用此成员函数替代 end() 模板函数，以保证返回值为 const_iterator。它一般与 auto 类型推导关键字一起使用，如以下示例所示。在此示例中，将 Container 视为可修改（非 const）容器或支持 end() 与 cend() 的任何类型的 initializer_list。

auto i1 = Container.end();
// i1 is Container<T>::iterator
auto i2 = Container.cend();

// i2 is Container<T>::const_iterator

`crbegin`

从容器末尾开始，获取容器元素的反向只读迭代器。

template <class C> constexpr auto crbegin(const C& c) -> decltype(std::rbegin(c));

参数

C
容器类型。

c
容器实例。

返回值

此迭代器按相反顺序返回容器的元素，从容器的末尾开始。

包含元素 10、20 和 30 的向量的图片。在最左边的元素（最左边的元素包含数字 10）之前有一个假想框，表示 sentinel。它标记为“crend()”。向量中的第一个元素包含数字 10，并标记为“last element”。向量中最右边的元素包含 30 并标记为“crbegin()”。

示例： `crbegin`

#include <vector>
#include <iostream>

int main()
{
    std::vector<int> v{10, 20, 30};
    for (auto i = std::crbegin(v); i != std::crend(v); ++i)
    {
        std::cout << *i << ' '; // outputs 30 20 10
    }
    // v[1] = 100; // error because the iterator is const
}

30 20 10

`crend`

获取只读反向元素序列末尾的 sentinel。

template <class C> constexpr auto crend(const C& c) -> decltype(std::rend(c));

参数

C
容器类型。

c
容器实例。

返回值

sentinel 紧随容器反向视图中的最后一个元素。

`crend` 例

#include <vector>
#include <iostream>

int main()
{
    std::vector<int> v{10, 20, 30};
    auto vi = std::crend(v);
    --vi; // get off the sentinel and onto the last element in the reversed range
    std::cout << *vi; // outputs 10
    // vi[0] = 300; // error because the iterator is const
}

`data`

获取指向容器中第一个元素的指针。

1) template <class C> constexpr auto data(C& c) -> decltype(c.data());
2) template <class C> constexpr auto data(const C& c) -> decltype(c.data());
3) template <class T, size_t N> constexpr T* data(T (&array)[N]) noexcept;
4) template <class E> constexpr const E* data(initializer_list<E> il) noexcept;

参数

C
容器类型。

c
容器实例。

E
初始值设定项列表的元素类型。

il
初始值设定项列表。

N
数组中的元素数。

T
数组中的数据类型。

返回值

1, 2) 基于容器类型指向第一个元素的指针。例如，如果容器是整数向量，返回值的类型为int *。

3) 指向作为数组的第一个元素的指针。

4) 指向初始值设定项列表的第一个元素的指针。

示例 `data`

#include <vector>
#include <iostream>

int main()
{
    std::vector<int> v{ 10, 20, 30 };
    std::string src{ "a string" };

    const char *charPtr = std::data(src);
    int* intPtr = std::data(v);
    std::cout << charPtr << ", " << *intPtr << '\n'; // a string, 10
}

a string, 10

`distance`

确定两个迭代器定址位置之间的增量数。

template <class InputIterator>
typename iterator_traits<InputIterator>::difference_type distance(InputIterator first, InputIterator last);

参数

first
第一个迭代器，将要确定其与第二个迭代器之间的距离。

last
第二个迭代器，将要确定其与第一个迭代器之间的距离。

返回值

first必须递增到等于last时的次数。

备注

当 InputIterator 满足随机访问迭代器的需求时，距离函数具有固定复杂度；否则具有线性复杂度，因此可能会产生较高的成本。

示例

// iterator_distance.cpp
// compile with: /EHsc
#include <iterator>
#include <list>
#include <iostream>

int main()
{
    using namespace std;

    list<int> L;
    for (int i = -1; i < 9; ++i)
    {
        L.push_back(2 * i);
    }
    list <int>::iterator L_Iter, LPOS = L.begin();

    cout << "The list L is: ( ";
    for (L_Iter = L.begin(); L_Iter != L.end(); L_Iter++)
    {
        cout << *L_Iter << " ";
    }
    cout << ")." << endl;

    cout << "The iterator LPOS initially points to the first element: "
         << *LPOS << "." << endl;

    advance(LPOS, 7);
    cout << "LPOS is advanced 7 steps forward to point "
        << " to the eighth element: "
        << *LPOS << "." << endl;

    list<int>::difference_type Ldiff;
    Ldiff = distance(L.begin(), LPOS);
    cout << "The distance from L.begin( ) to LPOS is: "
        << Ldiff << "." << endl;
}

The list L is: ( -2 0 2 4 6 8 10 12 14 16 ).
The iterator LPOS initially points to the first element: -2.
LPOS is advanced 7 steps forward to point  to the eighth element: 12.
The distance from L.begin( ) to LPOS is: 7.

`empty`

template <class C> constexpr auto empty(const C& c) -> decltype(c.empty());
template <class T, size_t N> constexpr bool empty(const T (&array)[N]) noexcept;
template <class E> constexpr bool empty(initializer_list<E> il) noexcept;

参数

C
容器类型。

c
容器实例。

E
初始值设定项列表的元素类型。

il
初始值设定项列表。

N
数组中的元素数。

T
数组中的数据类型。

返回值

如果容器没有任何元素，则返回 true；否则返回 false。

示例

#include <vector>
#include <iostream>

int main()
{
    std::vector<int> v{ 10,20,30 };
    std::vector<int> v2;

    std::cout << std::boolalpha << std::empty(v); // outputs false
    std::cout << std::boolalpha << ", " << std::empty(v2); // outputs true
}

false, true

`end`

检索指向指定容器中最后一个元素之后的元素的迭代器。

template <class Container>
auto end(Container& cont)
   -> decltype(cont.end());

template <class Container>
auto end(const Container& cont)
   -> decltype(cont.end());

template <class Ty, class Size>
Ty *end(Ty (& array)[Size]);

参数

cont
容器。

array
Ty 类型对象的数组。

返回值

前两个模板函数返回 cont.end()（第一个为非常量函数，第二个为常量函数）。

第三个模板函数返回 array + Size。

备注

有关代码示例，请参阅 begin。

`front_inserter`

创建一个可以在指定容器前面插入元素的迭代器。

template <class Container>
front_insert_iterator<Container> front_inserter(Container& Cont);

参数

Cont
其前部要插入元素的容器对象。

返回值

与容器对象 Cont 关联的 front_insert_iterator。

备注

也可使用 front_insert_iterator 类的成员函数 front_insert_iterator。

C++ 标准库中，此自变量必须引用具有成员函数 push_back: deque 类或“列表类”的两个序列容器中的一个容器。

示例

// iterator_front_inserter.cpp
// compile with: /EHsc
#include <iterator>
#include <list>
#include <iostream>

int main()
{
    using namespace std;

    list<int> L;
    for (int i = -1; i < 9; ++i)
    {
        L.push_back(i);
    }

    cout << "The list L is:\n ( ";
    for (auto L_Iter = L.begin(); L_Iter != L.end(); L_Iter++)
    {
        cout << *L_Iter << " ";
    }
    cout << ")." << endl;

    // Using the template function to insert an element
    front_insert_iterator<list <int>> Iter(L);
    *Iter = 100;

    // Alternatively, you may use the front_insert member function
    front_inserter(L) = 200;

    cout << "After the front insertions, the list L is:\n ( ";
    for (auto L_Iter = L.begin(); L_Iter != L.end(); L_Iter++)
    {
        cout << *L_Iter << " ";
    }
    cout << ")." << endl;
}

The list L is:
( -1 0 1 2 3 4 5 6 7 8 ).
After the front insertions, the list L is:
( 200 100 -1 0 1 2 3 4 5 6 7 8 ).

`inserter`

一个帮助程序模板函数，允许使用 inserter(Cont, Where) 而非 insert_iterator<Container>(Cont, Where)。

template <class Container>
insert_iterator<Container>
inserter(
    Container& Cont,
    typename Container::iterator Where);

参数

Cont
要向其添加新元素的容器。

Where
定位插入点的迭代器。

备注

此模板函数返回 insert_iterator<Container>(Cont, Where)。

示例

// iterator_inserter.cpp
// compile with: /EHsc
#include <iterator>
#include <list>
#include <iostream>

int main()
{
    using namespace std;

    list<int> L;
    for (int i = 2; i < 5; ++i)
    {
        L.push_back(10 * i);
    }

    cout << "The list L is:\n ( ";
    for (auto L_Iter = L.begin(); L_Iter != L.end(); L_Iter++)
    {
        cout << *L_Iter << " ";
    }
    cout << ")." << endl;

    // Using the template version to insert an element
    insert_iterator<list<int>> Iter(L, L.begin());
    *Iter = 1;

    // Alternatively, using the member function to insert an element
    inserter(L, L.end()) = 500;

    cout << "After the insertions, the list L is:\n ( ";
    for (auto L_Iter = L.begin(); L_Iter != L.end(); L_Iter++)
    {
        cout << *L_Iter << " ";
    }
    cout << ")." << endl;
}

The list L is:
( 20 30 40 ).
After the insertions, the list L is:
( 1 20 30 40 500 ).

`make_checked_array_iterator`

创建可由其他算法使用的 checked_array_iterator。

注意

该函数是 C++ 标准库的 Microsoft 扩展。使用该函数实现的代码不可移植到不支持该 Microsoft 扩展的 C++ 标准生成环境中。

template <class Iter>
checked_array_iterator<Iter>
    make_checked_array_iterator(
Iter Ptr,
    size_t Size,
    size_t Index = 0);

参数

Ptr
指向目标数组的指针。

Size
目标数组的大小。

Index
数组的可选索引。

返回值

checked_array_iterator 的一个实例。

备注

make_checked_array_iterator 函数在 stdext 命名空间中定义。

此函数采用原始指针（此指针通常会导致有关边界溢出的问题），并将其包装在执行检查的 checked_array_iterator 类中。由于此类标记为已检查，因此 C++ 标准库不会对此发出警告。有关详细信息和代码示例，请参阅经过检查的迭代器。

示例

在下面的示例中，将创建一个 vector，并在其中填充 10 项。矢量内容通过复制算法复制到数组，随后使用 make_checked_array_iterator 指定目标。这在有意违反边界后进行，因此将触发调试断言失败。

// make_checked_array_iterator.cpp
// compile with: /EHsc /W4 /MTd

#include <algorithm>
#include <iterator> // stdext::make_checked_array_iterator
#include <memory> // std::make_unique
#include <iostream>
#include <vector>
#include <string>

using namespace std;

template <typename C> void print(const string& s, const C& c)
{
    cout << s;

    for (const auto& e : c) 
    {
        cout << e << " ";
    }

    cout << endl;
}

int main()
{
    const size_t dest_size = 10;
    // Old-school but not exception safe, favor make_unique<int[]>
    // int* dest = new int[dest_size];
    unique_ptr<int[]> updest = make_unique<int[]>(dest_size);
    int* dest = updest.get(); // get a raw pointer for the demo

    vector<int> v;

    for (int i = 0; i < dest_size; ++i) 
    {
        v.push_back(i);
    }
    print("vector v: ", v);

    copy(v.begin(), v.end(), stdext::make_checked_array_iterator(dest, dest_size));

    cout << "int array dest: ";
    for (int i = 0; i < dest_size; ++i)
    {
        cout << dest[i] << " ";
    }
    cout << endl;

    // Add another element to the vector to force an overrun.
    v.push_back(10);

    // ! The next line causes a debug assertion when it executes.
    copy(v.begin(), v.end(), stdext::make_checked_array_iterator(dest, dest_size));
}

`make_move_iterator`

创建一个将所提供的迭代器包含在内作为 stored 迭代器的 move iterator。

template <class Iterator>
move_iterator<Iterator>
make_move_iterator(const Iterator& It);

参数

It
存储在新移动迭代器中的迭代器。

备注

模板函数返回 move_iterator <Iterator>(_It)。

`make_unchecked_array_iterator`

创建可由其他算法使用的 unchecked_array_iterator。

注意

该函数是 C++ 标准库的 Microsoft 扩展。使用该函数实现的代码不可移植到不支持该 Microsoft 扩展的 C++ 标准生成环境中。

template <class Iter>
unchecked_array_iterator<Iter>
    make_unchecked_array_iterator(Iter Ptr);

参数

Ptr
指向目标数组的指针。

返回值

unchecked_array_iterator 的一个实例。

备注

make_unchecked_array_iterator 函数在 stdext 命名空间中定义。

该函数采用原始指针并将其包装在不执行检查的类中，因此没有进行任何优化，但它还静默处理编译器警告，例如 C4996。因此，这是一个有针对性的方法，既可处理未经检查的指针警告，又无需从全局静默处理这些警告或产生检查成本。有关详细信息和代码示例，请参阅经过检查的迭代器。

示例

在下面的示例中，将创建一个 vector，并在其中填充 10 项。矢量内容通过复制算法复制到数组，随后使用 make_unchecked_array_iterator 指定目标。

// make_unchecked_array_iterator.cpp
// compile with: /EHsc /W4 /MTd

#include <algorithm>
#include <iterator> // stdext::make_unchecked_array_iterator
#include <iostream>
#include <vector>
#include <string>

using namespace std;

template <typename C> void print(const string& s, const C& c)
{
    cout << s;

    for (const auto& e : c) 
    {
        cout << e << " ";
    }

    cout << endl;
}

int main()
{
    const size_t dest_size = 10;
    int* dest = new int[dest_size];
    vector<int> v;

    for (int i = 0; i < dest_size; ++i) 
    {
        v.push_back(i);
    }
    print("vector v: ", v);

    // COMPILER WARNING SILENCED: stdext::unchecked_array_iterator is marked as checked in debug mode
    // (it performs no checking, so an overrun will trigger undefined behavior)
    copy(v.begin(), v.end(), stdext::make_unchecked_array_iterator(dest));

    cout << "int array dest: ";
    for (int i = 0; i < dest_size; ++i)
    {
        cout << dest[i] << " ";
    }
    cout << endl;

    delete[] dest;
}

vector v: 0 1 2 3 4 5 6 7 8 9
int array dest: 0 1 2 3 4 5 6 7 8 9

`next`

迭代指定的次数并返回新的迭代器位置。

template <class InputIterator>
InputIterator next(
    InputIterator first,
    typename iterator_traits<InputIterator>::difference_type off = 1);

参数

first
当前位置。

off
循环访问次数。

返回值

循环访问 off 次后返回新的迭代器位置。

备注

模板函数返回 next 递增 off 次数

`prev`

反向迭代指定的次数并返回新的迭代器位置。

template <class BidirectionalIterator>
BidirectionalIterator prev(
    BidirectionalIterator first,
    typename iterator_traits<BidirectionalIterator>::difference_type off = 1);

参数

first
当前位置。

off
循环访问次数。

备注

模板函数返回 next 递减 off 次数。

`rbegin`

获取迭代器，该迭代器按相反顺序返回容器的元素。

template <class C> constexpr auto rbegin(C& c) -> decltype(c.rbegin());
template <class C> constexpr auto rbegin(const C& c) -> decltype(c.rbegin());

参数

C
容器类型。

c
容器实例。

返回值

返回的迭代器按相反顺序显示容器的元素，从反向范围的末尾开始。

包含元素 10、20 和 30 的向量的图片。在最左边的元素（最左边的元素包含数字 10）之前有一个假想框，表示 sentinel。它标记为“rend()”。向量中的第一个元素包含数字 10，并标记为“last element”。向量中最右边的元素包含 30 并标记为“rbegin()”。

示例 `rbegin`

#include <vector>
#include <iostream>

int main()
{
    std::vector<int> v{ 10, 20, 30 };

	for (auto e = std::rbegin(v); e != std::rend(v); ++e)
	{
		std::cout << *e << ' '; // outputs 30 20 10
	}
}

30 20 10

`rend`

获取反向元素序列末尾的 sentinel。

template <class C> constexpr auto rend(C& c)-> decltype(c.rend());
template <class C> constexpr auto rend(const C& c) -> decltype(c.rend());

参数

C
容器类型。

c
容器实例。

返回值

指向容器末尾 sentinel 的反向迭代器。 sentinel 紧随容器反向视图中的最后一个元素：

`rend` 例

#include <vector>
#include <iostream>

int main()
{
    std::vector<int> v{10, 20, 30};
    auto vi = std::rend(v);
    --vi; // get off the sentinel and onto the last element in the reversed range
    std::cout << *vi; // outputs 10
}

`size`

template <class C> constexpr auto size(const C& c)
    -> decltype(c.size());
template <class T, size_t N> constexpr size_t size(const T (&array)[N]) noexcept;

参数

C
容器类型。

c
容器实例。

N
数组中的元素数。

T
数组中的数据类型。

返回值

容器中的元素数作为无符号整数值。

示例 `size`

#include <vector>
#include <iostream>

int main()
{
    std::vector<int> v{ 10, 20, 30 };
    size_t s = std::size(v);
    std::cout << s; // outputs 3
}

通过

<iterator> 函数

advance

参数

备注

示例

back_inserter

参数

返回值

备注

示例

begin

参数

返回值

示例

cbegin

参数

返回值

备注

cend

参数

返回值

备注

crbegin

参数

返回值

示例： crbegin

crend

参数

返回值

crend 例

data

参数

返回值

示例 data

distance

参数

返回值

备注

示例

empty

参数

返回值

示例

end

参数

返回值

备注

front_inserter

参数

返回值

备注

示例

inserter

参数

备注

示例

make_checked_array_iterator

参数

返回值

备注

示例

make_move_iterator

参数

备注

make_unchecked_array_iterator

参数

返回值

备注

示例

next

参数

返回值

备注

prev

参数

备注

rbegin

参数

返回值

`<iterator>` 函数

`advance`

`back_inserter`

`begin`

`cbegin`

`cend`

`crbegin`

示例： `crbegin`

`crend`

`crend` 例

`data`

示例 `data`

`distance`

`empty`

`end`

`front_inserter`

`inserter`

`make_checked_array_iterator`

`make_move_iterator`

`make_unchecked_array_iterator`

`next`

`prev`

`rbegin`

示例 `rbegin`

`rend`

`rend` 例

`size`

示例 `size`