home | help 
std::ranges::begin(3)	       C++ Standard Libary	   std::ranges::begin(3)

NAME
     std::ranges::begin - std::ranges::begin

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

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

	}
	Call signature
	template< class T >

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

	constexpr std::input_or_output_iterator auto begin(
	T&& t );

	Returns an iterator to the first element of the argument.

	range-begin-end.svg

	If the argument is an lvalue  or  ranges::enable_borrowed_range<std::re-
     move_cv_t<T>>
	is true, then a call to ranges::begin is expression-equivalent to:

	 1. t + 0 if t has an array type.
	       * If std::remove_all_extents_t<std::remove_reference_t<T>> is in-
     complete,
		 then the call to ranges::begin is ill-formed, no diagnostic re-
     quired.
	 2. Otherwise,
	    decay-copy(t.begin())
	    (until C++23)
	    auto(t.begin())
	    (since C++23), if that expression is valid and its type models
	    std::input_or_output_iterator.
	 3. Otherwise,
	    decay-copy(begin(t))
	    (until C++23)
	    auto(begin(t))
	    (since  C++23), if T is a class or enumeration type, that expression
     is valid and
	    its type models std::input_or_output_iterator, where the meaning  of
     begin is
	    established as if by performing argument-dependent lookup only.

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

Notes
	If the argument is an rvalue (i.e. T is an object type) and
	ranges::enable_borrowed_range<std::remove_cv_t<T>> is false, the call to
	ranges::begin is ill-formed, which also results in substitution failure.

	The return type models std::input_or_output_iterator in all cases.

	The  C++20  standard requires that if the underlying begin function call
     returns a
	prvalue, the return value is move-constructed from the materialized tem-
     porary
	object. All implementations directly return the prvalue instead. The re-
     quirement is
	corrected by the post-C++20 proposal P0849R8 to  match	the  implementa-
     tions.

Example
     // Run this code

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

      int main()
      {
	  std::vector v{3, 1, 4};
	  auto vi = std::ranges::begin(v);
	  auto vci = std::ranges::cbegin(v);
	  assert(*vi == 3 and *vi == *vci);
	  ++vi;
	  ++vci; // OK: vci is modifiable object
	  *vi = 42; // OK: vi points to mutable element
	  // *vci = 13; // Error: vci points to immutable element

	  int a[]{-5, 10, 15};
	  auto ai = std::ranges::begin(a); // works with C-arrays as well
	  assert(*ai == -5);
	  *ai = 42; // OK
      }

	Defect reports

	The  following	behavior-changing  defect  reports were applied retroac-
     tively to
	previously published C++ standards.

	  DR	Applied to	     Behavior as published		 Correct
     behavior
	P2602R2 C++20	   there's machinery to  prohibit  certain	 removed
     such machinery
			   non-member begin found by ADL

See also
	ranges::cbegin returns an iterator to the beginning of a read-only 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::begin(3)
home | help