std::distance

 

C++

Apoyo de compiladores

Implementaciones independientes y albergadas

Lenguaje

Biblioteca estándar

Encabezados de la biblioteca estándar

Requisitos denominados

Macros de prueba de característica (C++20)

Biblioteca de apoyo del lenguaje

Biblioteca de conceptos(C++20)

Biblioteca de diagnósticos

Biblioteca de gestión de memoria

Biblioteca de metaprogramación(C++11)

Biblioteca de servicios generales

Biblioteca de contenedores

Biblioteca de iteradores

Biblioteca de rangos(C++20)

Biblioteca de algoritmos

Biblioteca de cadenas

Biblioteca de procesamiento de texto

Biblioteca numérica

Biblioteca de fecha y hora

Biblioteca de entrada/salida

Biblioteca del sistema de archivos(C++17)

Biblioteca de apoyo de concurrencia(C++11)

Biblioteca de apoyo de ejecución(C++26)

Especificaciones técnicas

Índice de símbolos

Bibliotecas externas

 

Biblioteca de iteradores

Conceptos de iteradores
indirectly_readable (C++20) indirectly_writable (C++20) weakly_incrementable (C++20) incrementable (C++20) input_or_output_iterator (C++20) sentinel_for (C++20) sized_sentinel_for (C++20)	input_iterator (C++20) output_iterator (C++20) forward_iterator (C++20) bidirectional_iterator (C++20) random_access_iterator (C++20) contiguous_iterator (C++20)
Primitivas de iteradores
iterator_traits input_iterator_tagoutput_iterator_tagforward_iterator_tagbidirectional_iterator_tagrandom_access_iterator_tagcontiguous_iterator_tag (C++20) iterator (en desuso en C++17)	incrementable_traits (C++20) indirectly_readable_traits (C++20) iter_value_titer_difference_titer_reference_titer_rvalue_reference_titer_common_reference_t (C++20)(C++20)(C++20)(C++20)(C++20)
Conceptos de algoritmos y servicios
Conceptos invocables indirectos
indirectly_unary_invocableindirectly_regular_unary_invocable (C++20)(C++20) indirect_unary_predicate (C++20)	indirect_binary_predicate (C++20) indirect_equivalence_relation (C++20) indirect_strict_weak_order (C++20)
Requerimientos comunes de algoritmos
indirectly_movable (C++20) indirectly_movable_storable (C++20) indirectly_copyable (C++20) indirectly_copyable_storable (C++20)	indirectly_swappable (C++20) indirectly_comparable (C++20) permutable (C++20) mergeable (C++20) sortable (C++20)
Servicios
indirect_result_t	projected
Adaptadores de iteradores
reverse_iterator move_iterator (C++11) move_sentinel (C++20) common_iterator (C++20) counted_iterator (C++20) back_insert_iterator front_insert_iterator insert_iterator	make_reverse_iterator (C++14) make_move_iterator (C++11) default_sentinel_tdefault_sentinel (C++20)(C++20) unreachable_sentinel_tunreachable_sentinel (C++20)(C++20) back_inserter front_inserter inserter
Iteradores de flujos
istream_iterator ostream_iterator	istreambuf_iterator ostreambuf_iterator
Puntos de personalización de iteradores
ranges::iter_move (C++20)
ranges::iter_swap (C++20)
Operaciones de iteradores
advance distance prev (C++11) next (C++11)	ranges::advance (C++20) ranges::distance (C++20) ranges::prev (C++20) ranges::next (C++20)
Acceso a rangos
begincbegin (C++11)(C++14) endcend (C++11)(C++14) sizessize (C++17)(C++20)	rbegincrbegin (C++14)(C++14) rendcrend (C++14)(C++14) empty (C++17) data (C++17)

 

Definido en el archivo de encabezado <iterator>
template<class InputIt > typenamestd::iterator_traits<InputIt>::difference_type     distance( InputIt first, InputIt last );		(constexpr desde C++17)

Devuelve el número de saltos desde first hasta last.

Si InputIt no es RandomAccessIterator, el comportamiento no está definido si last no es alcanzable desde first.

Si InputIt es RandomAccessIterator, el comportamiento no está definido si first y last no son alcanzables uno del otro.

Parámetros

first	-	Iterador que apunta al primer elemento.
last	-	Iterador que apunta al final del rango.
Requisitos de tipo
- InputIt debe satisfacer los requisitos de InputIterator. La operación es más eficiente si InputIt cumple además los requisitos de RandomAccessIterator.

Valor de retorno

El número de incrementos necesarios para ir de first a last.

El valor puede ser negativo si se utilizan iteradores de acceso aleatorio y first se puede alcanzar desde last.

(desde C++11)

Complejidad

Lineal.

Sin embargo, si InputIt cumple además los requisitos de RandomAccessIterator, la complejidad es constante.

Posible implementación

Véanse también las implementaciones en libstdc++ y libc++.

Implementación en C++98 implementation vía despacho con etiquetas, con constexpr elminado
namespace detail {template<class It>constexpr// requerido desde C++17typenamestd::iterator_traits<It>::difference_type do_distance(It first, It last, std::input_iterator_tag){typenamestd::iterator_traits<It>::difference_type result =0;while(first != last){++first;++result;}return result;}   template<class It>constexpr// requerido desde C++17typenamestd::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// desde C++17typenamestd::iterator_traits<It>::difference_type distance(It first, It last){return detail::do_distance(first, last, typenamestd::iterator_traits<It>::iterator_category());}
Implementación en C++17 vía ifconstexpr
template<class It>constexprtypenamestd::iterator_traits<It>::difference_type distance(It first, It last){using category =typenamestd::iterator_traits<It>::iterator_category; static_assert(std::is_base_of_v<std::input_iterator_tag, category>);   ifconstexpr(std::is_base_of_v<std::random_access_iterator_tag, category>)return last - first;else{typenamestd::iterator_traits<It>::difference_type result =0;while(first != last){++first;++result;}return result;}}

Ejemplo

Ejecuta este código

#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';// el comportamiento no está definido (hasta LWG940)   staticconstexprauto il ={3, 1, 4};// Desde C++17 `distance` puede usarse en un contexto constexpr. static_assert(std::distance(il.begin(), il.end())==3); static_assert(std::distance(il.end(), il.begin())==-3);}

Salida:

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

Informes de defectos

Los siguientes informes de defectos de cambio de comportamiento se aplicaron de manera retroactiva a los estándares de C++ publicados anteriormente.

ID	Aplicado a	Comportamiento según lo publicado	Comportamiento correcto
LWG 940	C++98	La redacción no era clara para el caso en el que first se puede alcanzar desde last.	Se aclaró.

Véase también

advance	Avanza un iterador en una distancia determinada. (función)
countcount_if	Devuelve el número de elementos que cumplan con un criterio específico. (plantilla de función)
ranges::distance (C++20)	Devuelve la distancia entre un iterador y un centinela, o entre el principio y el fin de un rango. (niebloid)