std::distance

Defined in header `<iterator>`
template< class InputIt > typename std::iterator_traits<InputIt>::difference_type distance( InputIt first, InputIt last );

Returns the number of elements between first and last.

The behavior is undefined if `last` is not reachable from `first` by (possibly repeatedly) incrementing `first`.	(until C++11)
If `InputIt` is not `RandomAccessIterator`, the behavior is undefined if `last` is not reachable from `first` by (possibly repeatedly) incrementing `first`. If `InputIt` is `RandomAccessIterator`, the behavior is undefined if `last` is not reachable from `first` and `first` is not reachable from `last`.	(since C++11)

Parameters

first	-	iterator pointing to the first element
last	-	iterator pointing to the end of the range
Type requirements
- `InputIt` must meet the requirements of `InputIterator`. The operation is more efficient if `InputIt` additionally meets the requirements of `RandomAccessIterator`

Return value

The number of increments needed to go from first to last. The value may be negative if random-access iterators are used and first is reachable from last (since C++11).

Complexity

Linear.

However, if InputIt additionally meets the requirements of RandomAccessIterator, complexity is constant.

Example

#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';
}

Output:

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

std::distance

Parameters

Return value

Complexity

Example

See also