# std::end, std::cend

< cpp‎ | iterator

定义于头文件 `<array>` |  |
定义于头文件 `<deque>` |  |
定义于头文件 `<forward_list>` |  |
定义于头文件 `<iterator>` |  |
定义于头文件 `<list>` |  |
定义于头文件 `<map>` |  |
定义于头文件 `<regex>` |  |
定义于头文件 `<set>` |  |
定义于头文件 `<span>` |  | (C++20 起)
定义于头文件 `<string>` |  |
定义于头文件 `<string_view>` |  | (C++17 起)
定义于头文件 `<unordered_map>` |  |
定义于头文件 `<unordered_set>` |  |
定义于头文件 `<vector>` |  |
| (1) |
template< class C > auto end( C& c ) -> decltype(c.end()); |  | (C++11 起) (C++17 前)
template< class C > constexpr auto end( C& c ) -> decltype(c.end()); |  | (C++17 起)
| (1) |
template< class C > auto end( const C& c ) -> decltype(c.end()); |  | (C++11 起) (C++17 前)
template< class C > constexpr auto end( const C& c ) -> decltype(c.end()); |  | (C++17 起)
| (2) |
template< class T, std::size_t N > T* end( T (&array)[N] ); |  | (C++11 起) (C++14 前)
template< class T, std::size_t N > constexpr T* end( T (&array)[N] ) noexcept; |  | (C++14 起)
template< class C > constexpr auto cend( const C& c ) noexcept(/* see below */) -> decltype(std::end(c)); | (3) | (C++14 起)

返回指向给定范围结尾（即最末元素的后一元素）的迭代器。

1) 准确返回 c.end() ，典型地是指向 `c` 所代表的序列末尾后一位置的迭代器。若 `C` 是标准容器 (Container) ，则在 `c` 非 const 限定时返回 C::iterator ，否则返回 C::const_iterator 。
2) 返回指向数组 `array` 末尾的指针。
3) 准确返回 std::end(c) ，这里 `c` 始终当做 const 限定。若 `C` 是标准容器 (Container) ，则始终返回 C::const_iterator 。

### 参数

c | - | 拥有 `end` 成员函数的容器或视图
array | - | 任意类型的数组

### 返回值

指向范围结尾的迭代器。注意容器或数组的结尾定义为最后一个合法元素的下一个元素。

### 异常

3)
`noexcept` 说明：
noexcept(noexcept(std::end(c)))

### 重载

可为不暴露适合的 `end()` 成员函数的类或枚举提供 `end` 的自定义重载。标准库已提供下列重载：

std::end(std::initializer_list) (C++11) | 特化 std::end (函数模板)
std::end(std::valarray) (C++11) | 特化的 std::end (函数模板)
begin(std::filesystem::directory_iterator)end(std::filesystem::directory_iterator) | 基于范围的 for 循环支持 (函数)
begin(std::filesystem::recursive_directory_iterator)end(std::filesystem::recursive_directory_iterator) | 基于范围的 for 循环支持 (函数)

类似 `swap` 的使用（于可交换 (Swappable) 描述）， `end` 函数在泛型语境中的典型使用等价于 using std::end; end(arg); ，这允许 ADL 为用户定义类型所选择的重载，和出现于同一重载集中的标准库函数模板。

    template<typename Container, typename Function>
    void for_each(Container&& cont, Function f) {
        using std::begin;
        auto it = begin(cont);
        using std::end;
        auto end_it = end(cont);
        while (it != end_it) {
            f(*it);
            ++it;
        }
    }

实参依赖查找所找到的 `end` 重载能用于定制 std::ranges::end、 std::ranges::cend 及其他依赖于 std::ranges::begin 的定制点对象的行为。 | (C++20 起)

### 注解

(1,3) 准确地反映 C::end() 的行为。若该成员函数无合理的实现，则它们的效果可能令人惊异。

`std::cend` 是为统一成员与非成员范围访问引入的。参阅 LWG 问题 2128 。

若 `C` 是浅 const 的视图，则 `std::cend` 可能返回可变的迭代器。某些用户不期待这种行为。参阅 P2276 与 P2278 。

### 示例

    #include <iostream>
    #include <vector>
    #include <iterator>
    #include <algorithm>

    int main()
    {
        std::vector<int> v = { 3, 1, 4 };
        if (std::find(std::begin(v), std::end(v), 5) != std::end(v)) {
            std::cout << "found a 5 in vector v!\n";
        }

        int a[] = { 5, 10, 15 };
        if (std::find(std::begin(a), std::end(a), 5) != std::end(a)) {
            std::cout << "found a 5 in array a!\n";
        }
    }

输出：

    found a 5 in array a!

### 参阅

begin cbegin (C++11)(C++14) | 返回指向容器或数组起始的迭代器 (函数模板)
ranges::end (C++20) | 返回指示范围结尾的哨位 (定制点对象)
ranges::cend (C++20) | 返回指示只读范围结尾的哨位 (定制点对象)