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

 NAME

   iterator_category  - Determines the category that an iterator
   belongs	to. This function	is now obsolete.  It is
   retained in order to provide backward compatibility	and support
   compilers that do not provide partial specialization.

 SYNOPSIS

   #include <iterator>

   template <class T, class Distance>
   inline input_iterator_tag
   iterator_category (const input_iterator<T, Distance>&)

   inline output_iterator_tag iterator_category (const output_iterator&)

   template <class T, class Distance>
   inline forward_iterator_tag
   iterator_category (const forward_iterator<T, Distance>&)

   template <class T, class Distance>
   inline bidirectional_iterator_tag
   iterator_category (const bidirectional_iterator<T, Distance>&)

   template <class T, class Distance>
   inline random_access_iterator_tag
   iterator_category (const random_access_iterator<T, Distance>&)

   template <class T>
   inline random_access_iterator_tag iterator_category (const T*)

 DESCRIPTION

   The iterator_category	family of function templates allows you	to
   determine the category that any	iterator belongs to.  The
   first	five functions take an iterator of a specific type and return
   the	tag for	that type.  The	last takes	a T* and returns
   random_access_iterator_tag.

 TAG TYPES

   input_iterator_tag
   output_iterator_tag
   forward_iterator_tag
   bidirectional_iterator_tag
   random_access_iterator_tag

   The iterator_category	function is particularly useful	for improving
   the efficiency of	algorithms.  An	algorithm can use this
   function	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 returned from iterator_category to
   select from one of	several	different auxiliary functions.
   Because	this is a compile time selection, use of this
   primitive incurs no significant runtime overhead.

   iterator_category is typically used like this:

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

   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.

 SEE ALSO

   Other	iterator primitives:  value_type, distance_type,
   distance,advance, iterator

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