Description

Finds the distance between first and last, i.e. the number of
times that first must be incremented until it is equal to
last. [1] The first version of distance, which takes two arguments,
simply returns that distance; the second version, which takes
three arguments and which has a return type of void, increments
n by that distance.

The second version of distance was the one defined in the original
STL, and the first version is the one defined in the
draft C++ standard; the definition was changed because the
older interface was clumsy and error-prone. The older interface
required the use of a temporary variable, and it has semantics
that are somewhat nonintuitive: it increments n by the distance
from first to last, rather than storing that distance in n. [2]

Both interfaces are currently supported [3], for
reasons of backward compatibility, but eventually the older
version will be removed.

Definition

Defined in the standard header iterator, and in the
nonstandard backward-compatibility header iterator.h.

Notes

[3]
The new distance interface uses the iterator_traits class, which
relies on a C++ feature known as partial specialization. Many of
today's compilers don't implement the complete standard; in
particular, many compilers do not support partial specialization. If
your compiler does not support partial specialization, then you will
not be able to use the newer version of distance, or any other STL
components that involve iterator_traits.