Knowledge baseExam Center
ENEnglish
Choose language13

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.

Sources