CKTIS / C++
std::prev — an iterator moved backward
std::prev from <iterator> returns a shifted copy of a bidirectional iterator without changing the argument. It moves backward by one step by default; negative n means moving forward. The caller must ensure that the movement stays within valid bounds and that evaluating -n does not overflow.
Version: C++23; repository compiler flag, production runtime not attested
Syntax
#include <iterator>
template<class BidirectionalIterator>
constexpr BidirectionalIterator prev(
BidirectionalIterator x,
typename std::iterator_traits<BidirectionalIterator>::difference_type n = 1);
std::prev(x)
std::prev(x, n)std::prev(x, n) returns an iterator of the same type as x, moved backward by n steps. The default n is 1; n == 0 keeps the position unchanged, and negative n moves forward. The function from <iterator> operates on a copy: it is equivalent to std::advance(x, -n); return x;, so it does not change the supplied iterator.
If the iterator’s difference_type is a narrow signed integer type, unary minus can promote n to int. In that case, std::advance can receive the int result even if it is not representable in the original difference_type. But if n is the minimum value of a signed integer type that is not promoted (such as std::ptrdiff_t when it is not subject to promotion), evaluating -n causes signed overflow and thus undefined behavior, even if the intended movement would stay within valid bounds.
The type must meet the bidirectional iterator requirements, even when n is negative. Random-access iterators take constant time; other bidirectional iterators take time linear in the number of steps. The result is an iterator, not an element value; read the element using * if the result is dereferenceable.
The function does not check bounds. Do not move before the beginning or outside the valid range. std::prev(values.end()) points to the last element only for a nonempty container with a suitable iterator; that backward step is invalid for an empty container. You cannot dereference end() itself.
Do not confuse std::prev with std::ranges::prev: the latter also has an overload taking a boundary bound, which std::prev does not provide. The example uses std::list<int> to demonstrate backward movement, forward movement with negative n, and preservation of the original iterator.
Examples
#include <iostream>
#include <iterator>
#include <list>
int main() {
const std::list<int> values{10, 20, 30, 40};
const auto finish = values.end();
const auto last = std::prev(finish);
const auto earlier = std::prev(finish, 2);
const auto forward = std::prev(earlier, -1);
std::cout << *last << ' ' << *earlier << ' ' << *forward << '\n';
std::cout << std::boolalpha << (finish == values.end()) << '\n';
}
Result
40 30 40 true
The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.