Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / C++

std::prev — déplacer un itérateur vers l’arrière

std::prev, défini dans <iterator>, renvoie une copie décalée d’un itérateur bidirectionnel sans modifier l’argument. Par défaut, il recule d’un pas ; un n négatif signifie avancer. L’appelant doit veiller à ce que le déplacement reste dans les limites valides et que l’évaluation de -n ne provoque pas de débordement.

Version : C++23; repository compiler flag, production runtime not attested

Syntaxe

#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) renvoie un itérateur du même type que x, déplacé de n pas vers l’arrière. Par défaut, n vaut 1 ; n == 0 laisse la position inchangée et un n négatif fait avancer. La fonction de <iterator> travaille sur une copie : elle équivaut à std::advance(x, -n); return x; et ne modifie donc pas l’itérateur fourni.

Si le difference_type de l’itérateur est un type entier signé de faible largeur, le moins unaire peut entraîner la promotion de n en int. Dans ce cas, std::advance peut recevoir le résultat de type int, même s’il n’est pas représentable dans le difference_type d’origine. En revanche, si n est la valeur minimale d’un type entier signé qui ne fait pas l’objet d’une promotion (par exemple std::ptrdiff_t en l’absence de promotion), l’évaluation de -n provoque un débordement d’entier signé et donc un comportement indéfini, même si le déplacement prévu resterait dans les limites valides.

Le type doit satisfaire aux exigences des itérateurs bidirectionnels, même lorsque n est négatif. Le déplacement prend un temps constant avec un itérateur à accès aléatoire ; avec les autres itérateurs bidirectionnels, le temps est linéaire en fonction du nombre de pas. Le résultat est un itérateur, pas la valeur d’un élément ; lisez l’élément avec * si le résultat peut être déréférencé.

La fonction ne vérifie pas les limites. Ne reculez pas avant le début et ne sortez pas de la plage valide. std::prev(values.end()) désigne le dernier élément uniquement pour un conteneur non vide doté d’un itérateur adapté ; ce recul est invalide pour un conteneur vide. end() lui-même ne peut pas être déréférencé.

Ne confondez pas std::prev avec std::ranges::prev : cette dernière possède aussi une surcharge qui prend une limite bound, absente de std::prev. L’exemple utilise std::list<int> pour montrer le recul, l’avancée avec un n négatif et la préservation de l’itérateur d’origine.

Exemples

#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';
}

Résultat

40 30 40
true

Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.

Sources