Man Page distance.3

                       Standard C++ Library
             Copyright 1998, Rogue Wave Software, Inc.

NAME

     distance

      - Computes the distance between two iterators.

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 com-
     pilers 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  parame-
     ters,  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  incre-
     ments 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