std::ranges:: advance

Wenn n negativ ist, wird der Iterator dekrementiert. In diesem Fall muss I das Konzept std::bidirectional_iterator modellieren, und S muss denselben Typ wie I aufweisen, falls bound angegeben ist; andernfalls ist das Verhalten undefiniert.

Die auf dieser Seite beschriebenen funktionsähnlichen Entitäten sind algorithm function objects (informell bekannt als niebloids ), das heißt:

• Explizite Template-Argumentlisten können beim Aufruf keiner von ihnen angegeben werden.
• Keiner von ihnen ist sichtbar für argument-dependent lookup .
• Wenn einer von ihnen durch normal unqualified lookup als Name links vom Funktionsaufrufoperator gefunden wird, wird argument-dependent lookup unterdrückt.

Parameter

Rückgabewert

Komplexität

Linear.

Wenn jedoch I zusätzlich std::random_access_iterator modelliert, oder S std:: sized_sentinel_for < I > modelliert, oder I und S std:: assignable_from < I & , S > modellieren, ist die Komplexität konstant.

Hinweise

Das Verhalten ist undefiniert, wenn die spezifizierte Sequenz von Inkrementierungen oder Dekrementierungen erfordern würde, dass ein nicht-inkrementierbarer Iterator (wie der past-the-end-Iterator) inkrementiert wird, oder dass ein nicht-dekrementierbarer Iterator (wie der front-Iterator oder der singular Iterator) dekrementiert wird.

Mögliche Implementierung

struct advance_fn
{
    template<std::input_or_output_iterator I>
    constexpr void operator()(I& i, std::iter_difference_t<I> n) const
    {
        if constexpr (std::random_access_iterator<I>)
            i += n;
        else
        {
            while (n > 0)
            {
                --n;
                ++i;
            }
            if constexpr (std::bidirectional_iterator<I>)
            {
                while (n < 0)
                {
                    ++n;
                    --i;
                }
            }
        }
    }
    template<std::input_or_output_iterator I, std::sentinel_for<I> S>
    constexpr void operator()(I& i, S bound) const
    {
        if constexpr (std::assignable_from<I&, S>)
            i = std::move(bound);
        else if constexpr (std::sized_sentinel_for<S, I>)
            (*this)(i, bound - i);
        else
            while (i != bound)
                ++i;
    }
    template<std::input_or_output_iterator I, std::sentinel_for<I> S>
    constexpr std::iter_difference_t<I>
    operator()(I& i, std::iter_difference_t<I> n, S bound) const
    {
        if constexpr (std::sized_sentinel_for<S, I>)
        {
            // std::abs ist erst ab C++23 constexpr
            auto abs = [](const std::iter_difference_t<I> x) { return x < 0 ? -x : x; };
            if (const auto dist = abs(n) - abs(bound - i); dist < 0)
            {
                (*this)(i, bound);
                return -dist;
            }
            (*this)(i, n);
            return 0;
        }
        else
        {
            while (n > 0 && i != bound)
            {
                --n;
                ++i;
            }
            if constexpr (std::bidirectional_iterator<I>)
            {
                while (n < 0 && i != bound)
                {
                    ++n;
                    --i;
                }
            }
            return n;
        }
    }
};
inline constexpr auto advance = advance_fn();

Beispiel

#include <iostream>
#include <iterator>
#include <vector>
int main()
{
    std::vector<int> v {3, 1, 4};
    auto vi = v.begin();
    std::ranges::advance(vi, 2);
    std::cout << "1) Wert: " << *vi << '\n' << std::boolalpha;
    std::ranges::advance(vi, v.end());
    std::cout << "2) vi == v.end(): " << (vi == v.end()) << '\n';
    std::ranges::advance(vi, -3);
    std::cout << "3) Wert: " << *vi << '\n';
    std::cout << "4) Differenz: " << std::ranges::advance(vi, 2, v.end())
              << ", Wert: " << *vi << '\n';
    std::cout << "5) Differenz: " << std::ranges::advance(vi, 4, v.end())
              << ", vi == v.end(): " << (vi == v.end()) << '\n';
}

1) Wert: 4
2) vi == v.end(): true
3) Wert: 3
4) Differenz: 0, Wert: 4
5) Differenz: 3, vi == v.end(): true

Siehe auch