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

FreeBSD Manual Pages

  
 
  

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

NAME
       std::ranges::prev - std::ranges::prev

Synopsis
	  Defined in header <iterator>
	  Call signature
	  template<  std::bidirectional_iterator  I >			   (1)
       (since C++20)
	  constexpr I prev( I i	);
	  template< std::bidirectional_iterator	I  >			   (2)
       (since C++20)
	  constexpr I prev( I i, std::iter_difference_t<I> n );
	  template<  std::bidirectional_iterator  I >			   (3)
       (since C++20)
	  constexpr I prev( I i, std::iter_difference_t<I> n, I	bound );

	  Return the n^th predecessor of iterator i.

	  The function-like entities described on  this	 page  are  niebloids,
       that is:

	    *  Explicit	template argument lists	cannot be specified when call-
       ing any of them.
	    * None of them are visible to argument-dependent lookup.
	    * When any of them are found by normal unqualified lookup  as  the
       name to the left
	      of  the function-call operator, argument-dependent lookup	is in-
       hibited.

	  In practice, they may	be implemented as function  objects,  or  with
       special compiler
	  extensions.

Parameters
	  i	- an iterator
	  n	- number of elements i should be descended
	  bound	- iterator denoting the	beginning of the range i points	to

Return value
	  1) The predecessor of	i.
	  2) The n^th predecessor of iterator i.
	  3)  The  n^th	 predecessor of	iterator i, or the first iterator that
       compares	equal to
	  bound, whichever is first.

Complexity
	  1) Constant.
	  2,3) Constant	if I models std::random_access_iterator<I>;  otherwise
       linear.

Possible implementation
	  struct prev_fn
	  {
	      template<std::bidirectional_iterator I>
	      constexpr	I operator()(I i) const
	      {
		  --i;
		  return i;
	      }

	      template<std::bidirectional_iterator I>
	      constexpr	I operator()(I i, std::iter_difference_t<I> n) const
	      {
		  ranges::advance(i, -n);
		  return i;
	      }

	      template<std::bidirectional_iterator I>
	      constexpr	 I  operator()(I  i,  std::iter_difference_t<I>	 n,  I
       bound) const
	      {
		  ranges::advance(i, -n, bound);
		  return i;
	      }
	  };

	  inline constexpr auto	prev = prev_fn();

Notes
	  Although the expression --r.end() often compiles for containers,  it
       is not
	  guaranteed  to  do so: r.end() is an rvalue expression, and there is
       no iterator
	  requirement that specifies that decrement of an rvalue is guaranteed
       to work.	In
	  particular, when iterators are implemented as	pointers or its	opera-
       tor-- is
	  lvalue-ref-qualified,	  --r.end()   does    not    compile,	 while
       ranges::prev(r.end()) does.

	  This is further exacerbated by ranges	that do	not model ranges::com-
       mon_range. For
	  example,  for	 some  underlying  ranges, ranges::transform_view::end
       doesn't have the
	  same return type as ranges::transform_view::begin, and so  --r.end()
       won't compile.
	  This	isn't  something that ranges::prev can aid with, but there are
       workarounds.

Example
       // Run this code

	#include <iostream>
	#include <iterator>
	#include <vector>

	int main()
	{
	    std::vector<int> v{3, 1, 4};
	    auto pv = std::ranges::prev(v.end(), 2);
	    std::cout << *pv <<	'\n';

	    pv = std::ranges::prev(pv, 42, v.begin());
	    std::cout << *pv <<	'\n';
	}

Output:
	1
	3

See also
	  ranges::next	  increment an iterator	by a given distance  or	 to  a
       bound
	  (C++20)	  (niebloid)
	  ranges::advance advances an iterator by given	distance or to a given
       bound
	  (C++20)	  (niebloid)
	  prev		  decrement an iterator
	  (C++11)	  (function template)

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

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

home | help