NAME¶

std::ranges::cbegin - std::ranges::cbegin

Synopsis¶

Defined in header <ranges>
Defined in header <iterator>
inline namespace /* unspecified */ {

inline constexpr /* unspecified */ cbegin = /* (since C++20)
unspecified */; (customization point object)

}
Call signature
template< class T >

requires /* see below */ (since C++20)

constexpr /* see below */ auto cbegin( T&& t );

Returns an iterator to the first element of the const-qualified (until C++23)
argument.
Returns a constant iterator to the first element of the argument. (since C++23)

range-begin-end.svg

Let CT be

* const std::remove_reference_t<T>& if the argument is an lvalue (i.e. T is
an lvalue reference type), (until
* const T otherwise. C++23)

A call to ranges::cbegin is expression-equivalent to
ranges::begin(static_cast<CT&&>(t)).
If the argument is an lvalue or
ranges::enable_borrowed_range<std::remove_cv_t<T>> is true, then a call to
ranges::cbegin is expression-equivalent to:

* std::const_iterator<decltype(U)>(U) for some expression U equivalent to (since
ranges::begin(/*possibly-const-range*/(t)). C++23)

In all other cases, a call to ranges::cbegin is ill-formed, which can result
in substitution failure when the call appears in the immediate context of a
template instantiation.

The return type models std::input_or_output_iterator
and constant-iterator
(since C++23) in all cases.

Notes¶

For an lvalue range e of type T, ranges::cbegin(e) is equivalent to

ranges::begin(std::as_const(e)). (until C++23)
* ranges::begin(e) if T models constant_range.
* Otherwise, ranges::begin(std::as_const(e)) if const T models (since C++23)
constant_range.
* Otherwise, std::basic_const_iterator(ranges::begin(e)).

Example¶

// Run this code

#include <cassert>
#include <ranges>
#include <vector>

int main()
{
std::vector v{3, 1, 4};
auto vi = std::ranges::cbegin(v);
assert(3 == *vi);
++vi; // OK, constant-iterator object is mutable
assert(1 == *vi);
// *vi = 13; // Error: constant-iterator points to an immutable element

int a[]{3, 1, 4};
auto ai = std::ranges::cbegin(a); // cbegin works with C-arrays as well
assert(3 == *ai and *(ai + 1) == 1);
// *ai = 13; // Error: read-only variable is not assignable
}

See also¶

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