std::ranges::cbegin(3)

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)