NAME¶

std::end,std::cend - std::end,std::cend

Synopsis¶

Defined in header <array>
Defined in header <deque>
Defined in header <forward_list>
Defined in header <iterator>
Defined in header <list>
Defined in header <map>
Defined in header <regex>
Defined in header <set>
Defined in header <span> (since
C++20)
Defined in header <string>
Defined in header <string_view> (since
C++17)
Defined in header <unordered_map>
Defined in header <unordered_set>
Defined in header <vector>
(since
template< class C > C++11)
auto end( C& c ) -> decltype(c.end()); (until
C++17)
template< class C > (since
constexpr auto end( C& c ) -> decltype(c.end()); C++17)
(since
template< class C > C++11)
auto end( const C& c ) -> decltype(c.end()); (until
C++17)
template< class C > (since
constexpr auto end( const C& c ) -> C++17)
decltype(c.end()); (1)
(since
template< class T, std::size_t N > C++11)
T* end( T (&array)[N] ); (1) (until
C++14)
template< class T, std::size_t N > (since
constexpr T* end( T (&array)[N] ) noexcept; (2) C++14)
template< class C >

constexpr auto cend( const C& c ) noexcept(/* see (3) (since
below */) C++14)

-> decltype(std::end(c));

Returns an iterator to the end (i.e. the element after the last element) of the
given range.

1) Returns exactly c.end(), which is typically an iterator one past the end of the
sequence represented by c. If C is a standard Container, this returns a C::iterator
when c is not const-qualified, and a C::const_iterator otherwise.
2) Returns a pointer to the end of the array array.
3) Returns exactly std::end(c), with c always treated as const-qualified. If C is a
standard Container, this always returns a C::const_iterator.

range-begin-end.svg

Parameters¶

c - a container or view with an end member function
array - an array of arbitrary type

Return value¶

An iterator to the end of the range. Note that the end of a range is defined as the
element following the last valid element.

Exceptions¶

3)
noexcept specification:
noexcept(noexcept(std::end(c)))

Overloads

Custom overloads of end may be provided for classes and enumerations that do not
expose a suitable end() member function, yet can be iterated. The following
overloads are already provided by the standard library:

std::end(std::initializer_list) specializes std::end
(C++11) (function template)
std::end(std::valarray) specializes std::end
(C++11) (function template)
begin(std::filesystem::directory_iterator) range-based for loop support
end(std::filesystem::directory_iterator) (function)
(C++17)
begin(std::filesystem::recursive_directory_iterator) range-based for loop support
end(std::filesystem::recursive_directory_iterator) (function)

Similar to the use of swap (described in Swappable), typical use of the end function
in generic context is an equivalent of using std::end; end(arg);, which lets both
the ADL-selected overloads for user-defined types and the standard library function
templates to appear in the same overload set.

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

Overloads of end found by argument-dependent lookup can be used to
customize the behavior of std::ranges::end, std::ranges::cend, and (since C++20)
other customization pointer objects depending on std::ranges::end.

Notes¶

(1,3) exactly reflect the behavior of C::end(). Their effects may be surprising if
the member function does not have a reasonable implementation.

std::cend is introduced for unification of member and non-member range accesses. See
also LWG issue 2128.

If C is a shallow-const view, std::cend may return a mutable iterator. Such behavior
is unexpected for some users. See also P2276 and P2278.

Example¶

// Run this code

#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";
}
}

Output:¶

found a 5 in array a!

See also¶

begin
cbegin returns an iterator to the beginning of a container or array
(C++11) (function template)
(C++14)
ranges::end returns a sentinel indicating the end of a range
(C++20) (customization point object)
ranges::cend returns a sentinel indicating the end of a read-only range
(C++20) (customization point object)