Namespaces
Variants

std:: distance

From cppreference.net
C++
Iterator library
Iterator concepts
Iterator primitives
Algorithm concepts and utilities
Indirect callable concepts
Common algorithm requirements
(C++20)
(C++20)
(C++20)
Utilities
(C++20)
Iterator adaptors
Range access
(C++11) (C++14)
(C++14) (C++14)
(C++11) (C++14)
(C++14) (C++14)
(C++17) (C++20)
(C++17)
(C++17)
Défini dans l'en-tête <iterator>
template < class InputIt >

typename std:: iterator_traits < InputIt > :: difference_type

distance ( InputIt first, InputIt last ) ;
(constexpr depuis C++17)

Retourne le nombre de sauts de first à last .

Si InputIt n'est pas un LegacyRandomAccessIterator , le comportement est indéfini si last n'est pas atteignable depuis first .

Si InputIt est un LegacyRandomAccessIterator , le comportement est indéfini si first et last ne sont pas accessibles l'un depuis l'autre.

Table des matières

Paramètres

first - itérateur pointant vers le premier élément
last - itérateur pointant vers la fin de la plage
Exigences de type
-
InputIt doit satisfaire aux exigences de LegacyInputIterator . L'opération est plus efficace si InputIt satisfait également aux exigences de LegacyRandomAccessIterator .

Valeur de retour

Le nombre d'incréments nécessaires pour passer de first à last .

La valeur peut être négative si des itérateurs à accès aléatoire sont utilisés et first est accessible depuis last .

(depuis C++11)

Complexité

Linéaire.

Cependant, si InputIt satisfait également aux exigences de LegacyRandomAccessIterator , la complexité est constante.

Implémentation possible

Voir aussi les implémentations dans libstdc++ et libc++ .

Implémentation C++98 via tag dispatch, avec constexpr supprimé 
namespace detail
{
    template<class It>
    constexpr // requis depuis C++17
    typename std::iterator_traits<It>::difference_type 
        do_distance(It first, It last, std::input_iterator_tag)
    {
        typename std::iterator_traits<It>::difference_type result = 0;
        while (first != last)
        {
            ++first;
            ++result;
        }
        return result;
    }
    template<class It>
    constexpr // requis depuis C++17
    typename std::iterator_traits<It>::difference_type 
        do_distance(It first, It last, std::random_access_iterator_tag)
    {
        return last - first;
    }
} // namespace detail
template<class It>
constexpr // depuis C++17
typename std::iterator_traits<It>::difference_type 
    distance(It first, It last)
{
    return detail::do_distance(first, last,
                               typename std::iterator_traits<It>::iterator_category());
}
Implémentation C++17 via if constexpr 
template<class It>
constexpr typename std::iterator_traits<It>::difference_type
    distance(It first, It last)
{
    using category = typename std::iterator_traits<It>::iterator_category;
    static_assert(std::is_base_of_v<std::input_iterator_tag, category>);
    if constexpr (std::is_base_of_v<std::random_access_iterator_tag, category>)
        return last - first;
    else
    {
        typename std::iterator_traits<It>::difference_type result = 0;
        while (first != last)
        {
            ++first;
            ++result;
        }
        return result;
    }
}

Exemple

Exécuter ce code 
#include <iostream>
#include <iterator>
#include <vector>
int main() 
{
    std::vector<int> v{3, 1, 4};
    std::cout << "distance(first, last) = "
              << std::distance(v.begin(), v.end()) << '\n'
              << "distance(last, first) = "
              << std::distance(v.end(), v.begin()) << '\n';
              // le comportement est indéfini (jusqu'à LWG940)
    static constexpr auto il = {3, 1, 4};
    // Depuis C++17 `distance` peut être utilisé dans un contexte constexpr.
    static_assert(std::distance(il.begin(), il.end()) == 3);
    static_assert(std::distance(il.end(), il.begin()) == -3);
}

Sortie : 

distance(first, last) = 3
distance(last, first) = -3

Rapports de défauts

Les rapports de défauts modifiant le comportement suivants ont été appliqués rétroactivement aux normes C++ précédemment publiées.

DR Applicable à Comportement publié Comportement corrigé
LWG 940 C++98 la formulation était ambiguë pour le cas où first est accessible depuis last clarifié

Voir aussi

avance un itérateur d'une distance donnée
(modèle de fonction)
retourne le nombre d'éléments satisfaisant des critères spécifiques
(modèle de fonction)
(C++20)
retourne la distance entre un itérateur et un sentinelle, ou entre le début et la fin d'une plage
(objet fonction algorithme)