std::prev (3) - Linux Man Pages

std::prev: std::prev

NAME

std::prev - std::prev

Synopsis


Defined in header <iterator>
template< class BidirIt >
BidirIt prev( (since C++11)
BidirIt it, (until C++17)
typename std::iterator_traits<BidirIt>::difference_type n = 1 );
template< class BidirIt >
constexpr BidirIt prev( (since C++17)
BidirIt it,
typename std::iterator_traits<BidirIt>::difference_type n = 1 );


Return the nth predecessor of iterator it.

Parameters


it - an iterator
n - number of elements it should be descended

Type requirements


-
BidirIt must meet the requirements of LegacyBidirectionalIterator.

Return value


The nth predecessor of iterator it.

Complexity


Linear.
However, if BidirIt additionally meets the requirements of LegacyRandomAccessIterator, complexity is constant.

Possible implementation


  template<class BidirIt>
  BidirIt prev(BidirIt it, typename std::iterator_traits<BidirIt>::difference_type n = 1)
  {
      std::advance(it, -n);
      return it;
  }

Notes


Although the expression --c.end() often compiles, it is not guaranteed to do so: c.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, --c.end() does not compile, while std::prev(c.end()) does.

Example


// Run this code


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


  int main()
  {
      std::vector<int> v{ 3, 1, 4 };


      auto it = v.end();


      auto pv = std::prev(it, 2);


      std::cout << *pv << '\n';
  }

Output:


  1

See also


next increment an iterator
        (function template)
(C++11)
        advances an iterator by given distance
advance (function template)