std::ranges::advance
De cppreference.com
<tbody>
</tbody>
| Definido en el archivo de encabezado <iterator>
|
||
| Signatura de la llamada |
||
template< std::input_or_output_iterator I > constexpr void advance( I& i, std::iter_difference_t<I> n ); |
(1) | (desde C++20) |
template< std::input_or_output_iterator I, std::sentinel_for<I> S > constexpr void advance( I& i, S bound ); |
(2) | (desde C++20) |
template< std::input_or_output_iterator I, std::sentinel_for<I> S > constexpr std::iter_difference_t<I> advance( I& i, std::iter_difference_t<I> n, S bound ); |
(3) | (desde C++20) |
1) Incrementa el iterador dado
i n veces.2) Incrementa el iterador dado
i hasta que i == bound.3) Incrementa el iterador dado
i n veces, o hasta que i == bound, lo que suceda primero.Si n es negativo, el iterador se decrementa. En este caso, I debe modelar std::bidirectional_iterator y S debe ser del mismo tipo que I si se proporciona bound; de lo contrario, el comportamiento no está definido.
Las entidades similares a funciones descritas en esta página son niebloids, es decir:
- Las listas de argumentos de plantilla explícitas no se pueden especificar al llamar a cualquiera de ellas.
- Ninguna de ellas es visible para la búsqueda dependiente de argumentos.
- Cuando alguna de ellas se encuentra mediante la búsqueda normal no calificada como el nombre a la izquierda del operador de llamada a función, se inhibe la búsqueda dependiente de argumentos.
En la práctica, pueden implementarse como objetos función o con extensiones de compilador especiales.
Parámetros
| i | - | El iterador a avanzar. |
| bound | - | Centinela que denota el fin del rango del que i es un iterador.
|
| n | - | Número máximo de incrementos de i.
|
Valor de retorno
3) La diferencia entre
n y la distancia real i recorrida.Complejidad
Lineal.
Sin embargo, si I además modela std::random_access_iterator, o S modela std::sized_sentinel_for<I>, o I y S modelan std::assignable_from<I&, S>, la complejidad es constante.
Notas
El comportamiento no está definido si la secuencia especificada de incrementos o decrementos requiere que se incremente un iterador no incrementable (como el iterador posterior al final) o que se decremente un iterador no decrementable (como el iterador frontal o el iterador singular).
Posible implementación
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 no es constexpr hasta C++23
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();
|
Ejemplo
Ejecuta este código
#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) value: " << *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) value: " << *vi << '\n';
std::cout << "4) diff: " << std::ranges::advance(vi, 2, v.end())
<< ", value: " << *vi << '\n';
std::cout << "5) diff: " << std::ranges::advance(vi, 4, v.end())
<< ", vi == v.end(): " << (vi == v.end()) << '\n';
}
Salida:
1) value: 4
2) vi == v.end(): true
3) value: 3
4) diff: 0, value: 4
5) diff: 3, vi == v.end(): true
Véase también
(C++20) |
Incrementa un iterador en una distancia dada o a un límite. (niebloid) |
(C++20) |
Decrementa un iterador en una distancia dada o a un límite. (niebloid) |
(C++20) |
Devuelve la distancia entre un iterador y un centinela, o entre el principio y el fin de un rango. (niebloid) |
| Avanza un iterador en una distancia determinada. (función) |