HP C++ User Documentation

Standard C++ LibraryCopyright 1996, Rogue Wave Software, Inc.

NAME

  distance  - Computes the distance between two iterators

SYNOPSIS

  #include <iterator>

  template <class ForwardIterator>
  iterator_traits<ForwardIterator>::distance_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 iterator.
  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 provided
  for backward compatibility and to support compilers that do not provide
  partial specialization.  As you may have already deduced, 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.h>
  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;
   }

  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

WARNING

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

  vector <int, allocator,int> > instead of:

  vector <int>

  Also, if your compiler does not support partial specialization then you
  will not be able to use the version of distance that returns the distance.
  Instead you'll have to use the version that increments a reference
  parameter.

SEE ALSO

  sequence, random_iterator

STANDARDS CONFORMANCE

  ANSI X3J16/ISO WG21 Joint C++ Committee