## distance

    Iterator Operation

- Summary
- Data Type and Member Function Indexes
- Synopsis
- Description
- Example
- Warnings
- See Also

### Summary

Computes the distance between two iterators.

### Data Type and Member Function Indexes
(exclusive of constructors and destructors)

None

### Synopsis

    #include <iterator>
    template <class ForwardIterator>
     iterator_traits<ForwardIterator>::difference_type
     distance (ForwardIterator first,
                    ForwardIterator last);

    template <class ForwardIterator, class Distance>
     void distance (ForwardIterator first,
                    ForwardIterator last,
                    Distance& n);

### Description

The distance template function computes the distance between two iterators. The first version returns that value, while the second version increments `n` by that value. The last iterator must be reachable from the first iterator.

Note that the second version of this function is obsolete. It is included for backward compatibility and to support compilers that do not include partial specialization. The first version of the function is not available with compilers that do not support partial specialization, since it depends on `iterator_traits`, which itself depends on that particular language feature.

### Example

    //
    // distance.cpp
    //

     #include <iterator>
     #include <vector>
     #include <iostream>
     using namespace std;
     int main()
     {
       //
       //Initialize a vector using an array
       //
       int arr[6] = {3,4,5,6,7,8};
       vector<int> v(arr,arr+6);
       //
       //Declare a list iterator, s.b. a ForwardIterator
       //
       vector<int>::iterator itr = v.begin()+3;
       //
       //Output the original vector
       //
       cout << "For the vector: ";
       copy(v.begin(),v.end(),
            ostream_iterator<int,char>(cout," "));
       cout << endl << endl;

       cout << "When the iterator is initialized to point to "
            << *itr << endl;
       //
       // Use of distance
       //
       vector<int>::difference_type dist = 0;
       distance(v.begin(), itr, dist);
       cout << "The distance between the beginning and itr is "
            << dist << endl;
       return 0;
     }

Program Output

    For the vector: 3 4 5 6 7 8
    When the iterator is initialized to point to 6
    The distance between the beginning and itr is 3

### Warnings

If your compiler does not support default template parameters, then you always need to supply the `Allocator` template argument. For instance, you have to write:

`vector <int, allocator,int> >`

instead of:

`vector <int>`

If your compiler does not support partial specialization, then you can't use the version of distance that returns the distance. Instead you have to use the version that increments a reference parameter.

If your compiler does not support namespaces, then you do not need the using declaration for `std`.

### See Also

Sequences, Random Access Iterators

Copyright (c) 1998, Rogue Wave Software, Inc.
Send mail to report errors or comment on the documentation.
OEM Release, June 1998