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 nth predecessor of	iterator i

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

	    * Explicit template	argument lists may not be specified when call-
       ing any of them.
	    * None of them is visible to argument-dependent lookup.
	    *  When  one of them is found by normal unqualified	lookup for the
       name to the left
	      of the function-call operator,  it  inhibits  argument-dependent
       lookup.

	  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 nth predecessor of iterator i
	  3) The nth 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		  2022.07.31		  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.0>

home | help