std::prev

From cppreference.com
< cpp‎ | iterator
 
 
Iterator library
Iterator concepts
Iterator primitives
Algorithm concepts and utilities
Indirect callable concepts
Common algorithm requirements
Utilities
(C++20)
Iterator adaptors
Stream iterators
Iterator customization points
Iterator operations
prev
(C++11)
(C++11)
Range access
(C++11)(C++14)
(C++11)(C++14)
(C++17)(C++20)
(C++14)(C++14)
(C++14)(C++14)
(C++17)
(C++17)
 
Defined in header <iterator>
template< class BidirIt >

BidirIt prev(
  BidirIt it,

  typename std::iterator_traits<BidirIt>::difference_type n = 1 );
(since C++11)
(until C++17)
template< class BidirIt >

constexpr BidirIt prev(
  BidirIt it,

  typename std::iterator_traits<BidirIt>::difference_type n = 1 );
(since C++17)

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

#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

(C++11)
increment an iterator
(function template)
advances an iterator by given distance
(function template)
returns the distance between two iterators
(function template)
decrement an iterator by a given distance or to a bound
(niebloid)