Namespaces
Variants

std::ranges:: 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)
ヘッダーで定義 <iterator>
呼び出しシグネチャ
template < class I, std:: sentinel_for < I > S >

requires ( ! std:: sized_sentinel_for < S, I > )
constexpr std:: iter_difference_t < I >

distance ( I first, S last ) ;
(1) (C++20以降)
template < class I, std:: sized_sentinel_for < std:: decay_t < I >> S >

constexpr std:: iter_difference_t < std:: decay_t < I >>

distance ( I && first, S last ) ;
(2) (C++20以降)
template < ranges:: range R >

constexpr ranges:: range_difference_t < R >

distance ( R && r ) ;
(3) (C++20以降)
1,2) first から last までのホップ数を返します。
3) 符号付き整数として r のサイズを返します。

このページで説明されている関数ライクな実体は、 アルゴリズム関数オブジェクト （非公式には niebloids として知られる）です。つまり：

目次

パラメータ

first - 最初の要素を指すイテレータ
last - 範囲の終端を示す番兵 first が指すイテレータ
r - 距離を計算する範囲

戻り値

1) first から last まで移動するために必要なインクリメントの回数。
2) last - static_cast < const std:: decay_t < I > & > ( first ) .
3) R が ranges:: sized_range をモデルする場合、 ranges:: size ( r ) を返す。それ以外の場合、 ranges :: distance ( ranges:: begin ( r ) , ranges:: end ( r ) ) を返す。

計算量

1) 線形。
2) 定数。
3) R が ranges:: sized_range をモデル化する場合、または std:: sized_sentinel_for < ranges:: sentinel_t < R > , ranges:: iterator_t < R >> がモデル化される場合、計算量は定数時間となる。それ以外の場合は線形時間となる。

実装例 

struct distance_fn
{
    template<class I, std::sentinel_for<I> S>
        requires (!std::sized_sentinel_for<S, I>)
    constexpr std::iter_difference_t<I> operator()(I first, S last) const
    {
        std::iter_difference_t<I> result = 0;
        while (first != last)
        {
            ++first;
            ++result;
        }
        return result;
    }
    template<class I, std::sized_sentinel_for<std::decay<I>> S>
    constexpr std::iter_difference_t<I> operator()(const I& first, S last) const
    {
        return last - first;
    }
    template<ranges::range R>
    constexpr ranges::range_difference_t<R> operator()(R&& r) const
    {
        if constexpr (ranges::sized_range<std::remove_cvref_t<R>>)
            return static_cast<ranges::range_difference_t<R>>(ranges::size(r));
        else
            return (*this)(ranges::begin(r), ranges::end(r));
    }
};
inline constexpr auto distance = distance_fn{};

例

このコードを実行 
#include <cassert>
#include <forward_list>
#include <iterator>
#include <vector>
int main() 
{
    std::vector<int> v{3, 1, 4};
    assert(std::ranges::distance(v.begin(), v.end()) == 3);
    assert(std::ranges::distance(v.end(), v.begin()) == -3);
    assert(std::ranges::distance(v) == 3);
    std::forward_list<int> l{2, 7, 1};
    // auto size = std::ranges::size(l); // error: not a sizable range
    auto size = std::ranges::distance(l); // OK, but aware O(N) complexity
    assert(size == 3);
}

不具合報告

以下の動作変更の欠陥報告書は、以前に公開されたC++規格に対して遡及的に適用されました。

DR 適用対象 公開時の動作 正しい動作
LWG 3392 C++20 オーバーロード (1) はイテレータを値で受け取るため、move-only
イテレータの左辺値とサイズ付きセンチネルは拒否されていた 		オーバーロード (2) を追加
LWG 3664 C++20 LWG issue 3392 の解決により
ranges::distance が配列引数を拒否するようになった 		配列引数を受け入れる

関連項目

(C++20)
イテレータを指定された距離または指定された境界まで進める
(アルゴリズム関数オブジェクト)
(C++20) (C++20)
特定の条件を満たす要素の数を返す
(アルゴリズム関数オブジェクト)
2つのイテレータ間の距離を返す
(関数テンプレート)