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

 NAME

   iterator_traits  - Provides basic information	about an iterator.

 SYNOPSIS

   template <class Iterator> struct iterator_traits
   {
     typedef Iterator::value_type value_type;
     typedef Iterator::distance_type distance_type;
     typedef Iterator::iterator::category iterator_category;
   };

   // Specialization
   template <class T> struct iterator_traits<T*>
   {
     typedef T value_type;
     typedef Distance ptrdiff_t;
     typedef Category random_access_iterator_tag;
   };

 DESCRIPTION

   The iterator_traits template and specialization provides a uniform
   way for algorithms to	access information about a particular
   iterator.	 The template depends on an	iterator providing a
   basic interface consisting	of the types value_type,
   distance_type, and iterator_category, or on there	being a	spe-
   cialization for the iterator.	 The library provides one
   specialization (partial) to handle all pointer iterator types.

   iterator_traits are used within algorithms to	provide	local
   variables	of the type pointed to by the iterator, or of the
   iterator's distance type. The traits are is also used to improve the
   efficiency	of algorithms by making use of knowledge about basic
   iterator categories provided	by the iterator_category member.  An
   algorithm can use this "tag" to	select the most efficient
   implementation	an iterator is capable of handling without
   sacrificing the ability to work with a wide range of iterator	types.
   For instance, both the advance and distance primitives use
   iterator_category to maximize their efficiency by using the tag to
   select from one	of several different auxiliary functions.  The
   iterator_category	must therefore be one of the iterator tags
   provided	by the library.

 TAG TYPES

   input_iterator_tag
   output_iterator_tag
   forward_iterator_tag
   bidirectional_iterator_tag
   random_access_iterator_tag iterator_traits::iterator_category
   is typically used like this:

   template <class Iterator>
   void foo(Iterator first, Iterator last)
   {
    __foo(begin,end,
 	 iterator_traits<Iterator>::iterator_category);
   }

   template <class Iterator>
   void __foo(Iterator first, Iterator last,
 	    input_iterator_tag>
   {
     // Most general implementation
   }

   template <class Iterator>
   void __foo(Iterator first, Iterator last,
 	    bidirectional_iterator_tag>
   {
     // Implementation takes advantage of bi-diretional
     // capability of the iterators
   }

   _etc.

   See the iterator section in the Class	Reference for a	description of
   iterators and the capabilities associated with each type of iterator
   tag.

 WARNING

   If your compiler does	not support partial specialization then	this
   template and specialization will not be available to you.  Instead
   you	will need to use the distance_type, value_type, and
   iterator_category families of function templates.  The Rogue Wave
   Standard C++ Library also provides alternate implementations of the
   distance,	advance, and count functions when partial
   specialization is not	supported by a particular compiler.

 SEE ALSO

   value_type, distance_type, iterator_category,	distance,advance,
   iterator

 STANDARDS CONFORMANCE
   ANSI X3J16/ISO WG21 Joint C++	Committee