std::prev(3)

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>
   constexpr // since C++17
   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 or its operator-- is lvalue-ref-qualified, --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';
     it = v.begin();
     pv = std::prev(it, -2);
     std::cout << *pv << '\n';
 }

Output:
 1
 4

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