Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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 */;					   (customiza-
       tion 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	equiv-
       alent 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 con-
       text 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)

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

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::ranges::cbegin&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help