home | help 
std::ranges::cbegin(3)	       C++ Standard Libary	  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  ele-
     ment

	  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 ar-
     ray
	(C++11)       (function template)
	(C++14)

http://cppreference.com 	   2024.06.10		  std::ranges::cbegin(3)
home | help