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

NAME
     std::ranges::rbegin - std::ranges::rbegin

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

	    inline constexpr /* unspecified */ rbegin = /*	(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 rbegin(
	T&& t );

	Returns an iterator to the last element of the argument.

	range-rbegin-rend.svg

	If T is an array type  and  std::remove_all_extents_t<std::remove_refer-
     ence_t<T>> is
	incomplete, then the call to ranges::rbegin is ill-formed, no diagnostic
     required.

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

	 1. decay-copy(t.rbegin())
	    (until C++23)
	    auto(t.rbegin())
	    (since C++23), if that expression is valid and its type models
	    std::input_or_output_iterator.
	 2. Otherwise,
	    decay-copy(rbegin(t))
	    (until C++23)
	    auto(rbegin(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
     rbegin is
	    established as if by performing argument-dependent lookup only.
	 3.  Otherwise,   std::make_reverse_iterator(ranges::end(t))   if   both
     ranges::begin(t)
	    and  ranges::end(t)  are  valid expressions, have the same type, and
     that type
	    models std::bidirectional_iterator.

	In all other cases, a call to ranges::rbegin is  ill-formed,  which  can
     result in
	substitution  failure  when  ranges::rbegin(t)	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::rbegin is ill-formed, which also results in  substitution  fail-
     ure.

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

	The  C++20 standard requires that if the underlying rbegin 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 <iostream>
      #include <ranges>
      #include <span>
      #include <vector>

      int main()
      {
	  std::vector<int> v = {3, 1, 4};
	  auto vi = std::ranges::rbegin(v);
	  std::cout << *vi << '\n';
	  *vi = 42; // OK

	  int a[] = {-5, 10, 15};
	  auto ai = std::ranges::rbegin(a);
	  std::cout << *ai << '\n';
	  *ai = 42; // OK

	  // auto x_x = std::ranges::rbegin(std::vector{6, 6, 6});
	  // ill-formed: the argument is an rvalue (see Notes a)

	  auto si = std::ranges::rbegin(std::span{a}); // OK
	  static_assert(std::ranges::enable_borrowed_range<
	      std::remove_cv_t<decltype(std::span{a})>>);
	  *si = 42; // OK
      }

Output:
      4
      15

	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 rbegin found by ADL

See also
	ranges::crbegin returns a reverse iterator to a read-only range
	(C++20) 	(customization point object)
	rbegin		 returns  a  reverse iterator to the beginning of a con-
     tainer or array
	crbegin 	(function template)
	(C++14)

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