Compaq C++ User Documentation

| United States

cxxlstd$help.HLP

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

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

    NAME

      iterator

       - Base iterator class.

    SYNOPSIS

      #include <iterator>

      template <class Category, class T,  class Distance
      RWSTD_SIMPLE_DEFAULT(ptrdiff_t)>
      struct iterator
      {
        typedef T value_type;
        typedef Distance distance_type;
        typedef Category iterator_category;
      };

    DESCRIPTION

      The iterator structure provides a base class from which all other
      iterator types	can be derived.	 This structure	defines	an
      interface that consists of three	public types: value_type,
      distance_type, and iterator_category. These	types are used
      primarily by classes derived from iterator  and by the
      iterator_traits class.

      See the iterators section in the Class Reference for a description
      of iterators and	the capabilities associated with various
      types.

    SEE ALSO

      iterator_traits

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

    iterator_category
    			   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

    iterator_traits
    			   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

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

    NAME

      back_insert_iterator,	back_inserter  - An insert iterator used to
      insert items	at the end of a	collection.

    SYNOPSIS

      #include <iterator>

      template <class Container>
      class	back_insert_iterator : public output_iterator;

    DESCRIPTION

      Insert iterators let you insert new elements into a collection
      rather	than copy a new element's value over the value of an
      existing element.  The class	back_insert_iterator is	used to	insert
      items at	the end	of a collection.	 The function
      back_inserter creates an instance	of a back_insert_iterator for
      a particular	collection type.  A back_insert_iterator can be used
      with	vectors, deques, and lists, but	not with maps or sets.

    INTERFACE

      template <class Container>
      class	back_insert_iterator : public output_iterator {

      protected:
        Container& container;
      public:
        back_insert_iterator (Container&);
        back_insert_iterator<Container>&
         operator= (const Container::value_type&);
        back_insert_iterator<Container>& operator* ();
        back_insert_iterator<Container>& operator++	();
        back_insert_iterator<Container> operator++ (int);
      };

      template <class Container>
      back_insert_iterator<Container> back_inserter	(Container&);

    CONSTRUCTOR

      back_insert_iterator (Container& x); Constructor.  Creates an
      instance of a back_insert_iterator associated with container x.

    OPERATORS

      back_insert_iterator<Container>& operator= (const
      Container::value_type& value); Inserts a copy of value on	the
      end	of the container, and returns *this.

      back_insert_iterator<Container>&
      operator* ();
         Returns *this.

      back_insert_iterator<Container>&
      operator++ ();
      back_insert_iterator<Container>
      operator++ (int);
         Increments	the input iterator and returns *this.

    HELPER FUNCTION

      template <class Container> back_insert_iterator<Container>
      back_inserter	(Container& x) Returns a back_insert_iterator that
      will insert elements at the end of container x.  This	function
      allows	you to create insert iterators inline.

    EXAMPLE

      //
      // ins_itr.cpp
      //
       #include <iterator>
       #include <deque>
       #include <iostream.h>

      int main ()
       {
         //
         //	Initialize a deque using an array.
         //
        int	arr[4] = { 3,4,7,8 };
        deque<int> d(arr+0,	arr+4);
         //
         //	Output the original deque.
         //
        cout << "Start with	a deque: " << endl << "	    ";
        copy(d.begin(), d.end(),
    	 ostream_iterator<int,char>(cout," "));
         //
         //	Insert into the	middle.
         //
        insert_iterator<deque<int> > ins(d,	d.begin()+2);
         *ins = 5; *ins = 6;
         //
         //	Output the new deque.
         //
        cout << endl << endl;
        cout << "Use an insert_iterator: " << endl << "	";
        copy(d.begin(), d.end(),
    	 ostream_iterator<int,char>(cout," "));
         //
         //	A deque	of four	1s.
         //
        deque<int> d2(4, 1);
         //
         //	Insert d2 at front of d.
         //
        copy(d2.begin(), d2.end(), front_inserter(d));
         //
         //	Output the new deque.
         //
        cout << endl << endl;
        cout << "Use a front_inserter: " <<	endl <<	"     ";
        copy(d.begin(), d.end(),
    	 ostream_iterator<int,char>(cout," "));
         //
         //	Insert d2 at back of d.
         //
         copy(d2.begin(), d2.end(),	back_inserter(d));
         //
         //	Output the new deque.
         //
        cout << endl << endl;
        cout << "Use a back_inserter: " << endl << "     ";
        copy(d.begin(), d.end(),
    	 ostream_iterator<int,char>(cout," "));
        cout << endl;

        return 0;
       }

      Output :
      Start	with a deque:
          3	4 7 8
      Use an insert_iterator:
          3	4 5 6 7	8
      Use a	front_inserter:
          1	1 1 1 3	4 5 6 7	8
      Use a	back_inserter:
          1	1 1 1 3	4 5 6 7	8 1 1 1	1

    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>

    SEE ALSO

      insert iterators

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

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

    NAME

      back_insert_iterator,	back_inserter  - An insert iterator used to
      insert items	at the end of a	collection.

    SYNOPSIS

      #include <iterator>

      template <class Container>
      class	back_insert_iterator : public output_iterator;

    DESCRIPTION

      Insert iterators let you insert new elements into a collection
      rather	than copy a new element's value over the value of an
      existing element.  The class	back_insert_iterator is	used to	insert
      items at	the end	of a collection.	 The function
      back_inserter creates an instance	of a back_insert_iterator for
      a particular	collection type.  A back_insert_iterator can be used
      with	vectors, deques, and lists, but	not with maps or sets.

    INTERFACE

      template <class Container>
      class	back_insert_iterator : public output_iterator {

      protected:
        Container& container;
      public:
        back_insert_iterator (Container&);
        back_insert_iterator<Container>&
         operator= (const Container::value_type&);
        back_insert_iterator<Container>& operator* ();
        back_insert_iterator<Container>& operator++	();
        back_insert_iterator<Container> operator++ (int);
      };

      template <class Container>
      back_insert_iterator<Container> back_inserter	(Container&);

    CONSTRUCTOR

      back_insert_iterator (Container& x);
         Constructor.  Creates an instance of a back_insert_iterator
         associated with container x.

    OPERATORS

      back_insert_iterator<Container>&
      operator= (const Container::value_type& value);
         Inserts a copy of value on	the end	of the container, and returns
         *this.

      back_insert_iterator<Container>&
      operator* ();
         Returns *this.

      back_insert_iterator<Container>&
      operator++ ();
      back_insert_iterator<Container>
      operator++ (int);
         Increments	the input iterator and returns *this.

    HELPER FUNCTION

      template <class Container>
      back_insert_iterator<Container>
      back_inserter	(Container& x)
         Returns a back_insert_iterator that will insert elements at the
         end of container x.  This	function allows	you to create insert
         iterators inline.

    EXAMPLE

      //
      // ins_itr.cpp
      //
       #include <iterator>
       #include <deque>
       #include <iostream.h>

      int main ()
       {
         //
         //	Initialize a deque using an array.
         //
        int	arr[4] = { 3,4,7,8 };
        deque<int> d(arr+0,	arr+4);
         //
         //	Output the original deque.
         //
        cout << "Start with	a deque: " << endl << "	    ";
        copy(d.begin(), d.end(),
    	 ostream_iterator<int,char>(cout," "));
         //
         //	Insert into the	middle.
         //
        insert_iterator<deque<int> > ins(d,	d.begin()+2);
         *ins = 5; *ins = 6;
         //
         //	Output the new deque.
         //
        cout << endl << endl;
        cout << "Use an insert_iterator: " << endl << "	";
        copy(d.begin(), d.end(),
    	 ostream_iterator<int,char>(cout," "));
         //
         //	A deque	of four	1s.
         //
        deque<int> d2(4, 1);
         //
         //	Insert d2 at front of d.
         //
        copy(d2.begin(), d2.end(), front_inserter(d));
         //
         //	Output the new deque.
         //
        cout << endl << endl;
        cout << "Use a front_inserter: " <<	endl <<	"     ";
        copy(d.begin(), d.end(),
    	 ostream_iterator<int,char>(cout," "));
         //
         //	Insert d2 at back of d.
         //
         copy(d2.begin(), d2.end(),	back_inserter(d));
         //
         //	Output the new deque.
         //
        cout << endl << endl;
        cout << "Use a back_inserter: " << endl << "     ";
        copy(d.begin(), d.end(),
    	 ostream_iterator<int,char>(cout," "));
        cout << endl;

        return 0;
       }

      Output :
      Start	with a deque:
          3	4 7 8
      Use an insert_iterator:
          3	4 5 6 7	8
      Use a	front_inserter:
          1	1 1 1 3	4 5 6 7	8
      Use a	back_inserter:
          1	1 1 1 3	4 5 6 7	8 1 1 1	1

    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>

    SEE ALSO

      insert iterators

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

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

    NAME

      Bidirectional_Iterators  - An	iterator that can both read and	write
      and can traverse a container in both directions

    DESCRIPTION

      For a	complete discussion of iterators, see the Iterators section of
      this reference.

      Iterators are	a generalization of pointers that allow	a C++ program
      to uniformly interact with different data structures.  Bidirectional
      iterators can move both	forwards and backwards through a
      container, and	have the ability to both read and write data.
      These iterators	satisfy	the requirements	listed below.

      KEY TO ITERATOR REQUIREMENTS

      The following	key pertains to	the iterator descriptions listed below:

      a and	b   values of type X

      n   value of distance	type

      u, Distance, tmp and m   identifiers

      r   value of type X&

      t   value of type T

      REQUIREMENTS FOR BIDIRECTIONAL ITERATORS

      A bidirectional iterator must	meet all the requirements listed
      below.	 Note that most of these requirements are also the
      requirements for	forward iterators.

      X u	u might	have a singular	value

      X()	X() might be singular

      X(a)	 copy constructor, a ==	X(a).

      X u(a)   copy	constructor, u == a

      X u =	a   assignment,	u == a

      a == b, a != b   return value	convertible to bool

      a->m	 equivalent to (*a).m

      *a   return value convertible	to T&

      ++r	returns	X&

      r++	return value convertible to const X&

      *r++	 returns T&

      --r	returns	X&

      r--	return value convertible to const X&

      *r--	 returns T&

      Like forward iterators, bidirectional	iterators have the condition
      that a == b implies *a== *b.

      There	are no restrictions on the number of passes an algorithm may
      make through the structure.

    SEE ALSO

      Containers, Iterators, Forward Iterators

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

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

    NAME

      Forward_Iterators  - A forward-moving	iterator that can both read
      and write.

    DESCRIPTION

      For a	complete discussion of iterators, see the Iterators section of
      this reference.

      Iterators are	a generalization of pointers that allow	a C++ program
      to uniformly interact with different data structures.  Forward
      iterators are forward moving, and have	the ability to both
      read and write data.  These iterators satisfy the	requirements
      listed below.

    KEY TO ITERATOR	REQUIREMENTS

      The following	key pertains to	the iterator requirements listed below:

      a and	b   values of type X

      n   value of distance	type

      u, Distance, tmp and m   identifiers

      r   value of type X&

      t   value of type T

    REQUIREMENTS FOR FORWARD ITERATORS

      The following	expressions must be valid for forward iterators:

      X u	u might	have a singular	value

      X()	X() might be singular

      X(a)	 copy constructor, a ==	X(a).

      X u(a)   copy	constructor, u == a

      X u =	a   assignment,	u == a

      a == b, a != b   return value	convertible to bool

      *a   return value convertible	to T&

      a->m	 equivalent to (*a).m

      ++r	returns	X&

      r++	return value convertible to const X&

      *r++	 returns T&

      Forward iterators have the condition that a == b implies *a == *b.

      There	are no restrictions on the number of passes an algorithm may
      make through the structure.

    SEE ALSO

      Iterators, Bidirectional Iterators

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

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

    NAME

      front_insert_iterator, front_inserter	 - An insert iterator used to
      insert items	at the beginning of a collection.

    SYNOPSIS

      #include <iterator>

      template <class Container>
      class	front_insert_iterator :	public output_iterator ;

    DESCRIPTION

      Insert iterators let you insert new elements into a collection
      rather	than copy a new element's value over the value of an
      existing element.  The class	front_insert_iterator is used to
      insert	items at the beginning of a collection.  The function
      front_inserter creates an instance of a front_insert_iterator	for a
      particular collection type.  A front_insert_iterator	can be used
      with deques	and lists, but not with	maps or sets.

      Note that a front_insert_iterator makes each element that it inserts
      the new front of the container.  This has	the effect of
      reversing	the order of the inserted elements.  For example, if
      you use a front_insert_iterator to insert "1" then "2" then "3" onto
      the	front of container exmpl, you will find,	after the
      three	insertions, that the first three elements of exmpl are "3 2
      1".

    INTERFACE

      template <class Container>
      class	front_insert_iterator :	public output_iterator {

      public:
        explicit front_insert_iterator (Container&);
        front_insert_iterator<Container>&
         operator= (const typename Container::value_type&);
        front_insert_iterator<Container>& operator*	();
        front_insert_iterator<Container>& operator++ ();
        front_insert_iterator<Container> operator++	(int);
      };

      template <class Container>
       front_insert_iterator<Container> front_inserter (Container&);

    CONSTRUCTOR

      explicit
      front_insert_iterator(Container& x);
         Constructor.  Creates an instance of a front_insert_iterator
         associated with container x.

    OPERATORS

      front_insert_iterator<Container>&
      operator=(const typename Container::value_type& value);
         Assignment	Operator. Inserts a copy of value on the front of the
         container, and returns *this.

      front_insert_iterator<Container>&
      operator*();
         Returns *this (the	input iterator itself).

      front_insert_iterator<Container>&
      operator++();

      front_insert_iterator<Container>
      operator++(int);
         Increments	the insert iterator and	returns	*this.

    NON-MEMBER FUNCTION

      template <class Container>
      front_insert_iterator<Container>
      front_inserter(Container& x)
         Returns a front_insert_iterator that will insert elements at the
         beginning of container x.  This	function allows	you to create
         front insert iterators inline.

    EXAMPLE

      //
      // ins_itr.cpp
      //
      #include <iterator>
      #include <deque>
      #include <iostream.h>

      int main ()
       {
         //
         //	Initialize a deque using an array.
         //
        int	arr[4] = { 3,4,7,8 };
        deque<int> d(arr+0,	arr+4);
         //
         //	Output the original deque.
         //
        cout << "Start with	a deque: " << endl << "	    ";
        copy(d.begin(), d.end(), ostream_iterator<int>(cout," "));
         //
         //	Insert into the	middle.
         //
        insert_iterator<deque<int> > ins(d,	d.begin()+2);
         *ins = 5; *ins = 6;
         //
         //	Output the new deque.
         //
        cout << endl << endl;
        cout << "Use an insert_iterator: " << endl << "	";
        copy(d.begin(), d.end(), ostream_iterator<int>(cout," "));
         //
         //	A deque	of four	1s.
         //
        deque<int> d2(4, 1);
         //
         //	Insert d2 at front of d.
         //
        copy(d2.begin(), d2.end(), front_inserter(d));
         //
         //	Output the new deque.
         //
        cout << endl << endl;
        cout << "Use a front_inserter: " <<	endl <<	"     ";
        copy(d.begin(), d.end(), ostream_iterator<int>(cout," "));
         //
         //	Insert d2 at back of d.
         //
        copy(d2.begin(), d2.end(), back_inserter(d));
         //
         //	Output the new deque.
         //
        cout << endl << endl;
        cout << "Use a back_inserter: " << endl << "     ";
        copy(d.begin(), d.end(), ostream_iterator<int>(cout," "));
        cout << endl;

        return 0;
       }

      Output :
      Start	with a deque:
          3	4 7 8
      Use an insert_iterator:
          3	4 5 6 7	8
      Use a	front_inserter:
          1	1 1 1 3	4 5 6 7	8
      Use a	back_inserter:
          1	1 1 1 3	4 5 6 7	8 1 1 1	1

      WARNINGS

      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:

      deque<int, allocator<int> >

      instead of:

      deque<int>

    SEE ALSO

      Insert Iterators

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

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

    NAME

      Input_Iterators  - A read-only, forward moving iterator.

    DESCRIPTION

      For a	complete discussion of iterators, see the Iterators section of
      this reference.

      Iterators are	a generalization of pointers that allow	a C++ program
      to uniformly interact with different data structures.  Input
      iterators are read-only,	forward	moving iterators that satisfy
      the requirements listed below.

    KEY TO ITERATOR	REQUIREMENTS

      The following	key pertains to	the iterator requirement descriptions
      listed below:

      a and	b   values of type X

      n   value of distance	type

      u, Distance, tmp and m   identifiers

      r   value of type X&

      t   value of type T

    REQUIREMENTS FOR INPUT ITERATORS

      The following	expressions must be valid for input iterators:

      X u(a)   copy	constructor, u == a

      X u =	a   assignment,	u == a

      a == b, a != b   return value	convertible to bool

      *a   a == b implies *a == *b

      ++r	returns	X&

      r++	return value convertible to const X&

      *r++	 returns type T

      a -> m   returns (*a).m

      For input iterators, a == b does not imply that ++a == ++b.

      Algorithms using input iterators should be single pass algorithms.
      That is they should not pass through the same	iterator twice.

      The value of type T does not have to be an lvalue.

    SEE ALSO

      iterators, output iterators

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

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

    NAME

      insert_iterator, inserter  - An insert iterator used to insert items
      into a collection rather than overwrite the collection.

    SYNOPSIS

      #include <iterator>

      template <class Container>
      class	insert_iterator	: public output_iterator;

    DESCRIPTION

      Insert iterators let you insert new elements into a collection
      rather	than copy a new element's value over the value of an
      existing element.  The class	insert_iterator	is used	to insert
      items	into a specified location of a collection.	 The function
      inserter creates an instance of an insert_iterator given	a
      particular collection	type and iterator.  An insert_iterator can be
      used with vectors, deques, lists, maps	and sets.

    INTERFACE

      template <class Container>
      class	insert_iterator	: public output_iterator {

      public:
        insert_iterator (Container&, typename Container::iterator);
        insert_iterator<Container>&
         operator= (const typename Container::value_type&);
        insert_iterator<Container>&	operator* ();
        insert_iterator<Container>&	operator++ ();
        insert_iterator<Container>&	operator++ (int);
      };

      template <class Container, class Iterator>
      insert_iterator<Container> inserter (Container&, Iterator)

    CONSTRUCTOR

      insert_iterator(Container& x,	typename Container::iterator i);
         Constructor.  Creates an instance of an insert_iterator
         associated	with container x and iterator i.

    OPERATORS

      insert_iterator<Container>&
      operator=(const typename Container::value_type& value);
         Assignment	operator. Inserts a copy of value into the container
         at	the location specified	by the insert_iterator,	increments the
         iterator, and returns *this.

      insert_iterator<Container>&
      operator*();
         Returns *this (the	input iterator itself).

      insert_iterator<Container>&
      operator++();
      insert_iterator<Container>&
      operator++(int);
         Increments	the insert iterator and	returns	*this.

    NON-MEMBER FUNCTION

      template <class Container, class Iterator>
      insert_iterator<Container>
      inserter(Container& x, Iterator i);
         Returns an	insert_iterator	that will insert elements into
         container x at location i.  This function	allows you to create
         insert iterators inline.

    EXAMPLE

       #include <iterator>
       #include <vector>
       #include <iostream.h>
      int main()
       {
         //Initialize a vector using an array
        int	arr[4] = {3,4,7,8};
        vector<int>	v(arr,arr+4);
         //Output the original vector
        cout << "Start with	a vector: " << endl << "     ";
        copy(v.begin(),v.end(),ostream_iterator<int,char>(cout," "));
         //Insert into the middle
         insert_iterator<vector<int> >  ins(v, v.begin()+2);
         *ins = 5;
         *ins = 6;
         //Output the new vector
        cout << endl << endl;
        cout << "Use an insert_iterator: " << endl << "	";
        copy(v.begin(),v.end(),ostream_iterator<int,char>(cout," "));
        return 0;
       }

    WARNINGS

      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>

    SEE ALSO

      back_insert_iterator,	front_insert_iterator, Insert Iterators

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

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

    NAME

      insert_iterator, inserter  - An insert iterator used to insert items
      into a collection rather than overwrite the collection.

    SYNOPSIS

      #include <iterator>

      template <class Container>
      class	insert_iterator	: public output_iterator;

    DESCRIPTION

      Insert iterators let you insert new elements into a collection
      rather	than copy a new element's value over the value of an
      existing element.  The class	insert_iterator	is used	to insert
      items	into a specified location of a collection.	 The function
      inserter creates an instance of an insert_iterator given	a
      particular collection	type and iterator.  An insert_iterator can be
      used with vectors, deques, lists, maps	and sets.

    INTERFACE

      template <class Container>
      class	insert_iterator	: public output_iterator {

      public:
        insert_iterator (Container&, typename Container::iterator);
        insert_iterator<Container>&
         operator= (const typename Container::value_type&);
        insert_iterator<Container>&	operator* ();
        insert_iterator<Container>&	operator++ ();
        insert_iterator<Container>&	operator++ (int);
      };

      template <class Container, class Iterator>
      insert_iterator<Container> inserter (Container&, Iterator)

    CONSTRUCTOR

      insert_iterator(Container& x,	typename Container::iterator i);
         Constructor.  Creates an instance of an insert_iterator
         associated	with container x and iterator i.

    OPERATORS

      insert_iterator<Container>&
      operator=(const typename Container::value_type& value);
         Assignment	operator. Inserts a copy of value into the container
         at	the location specified	by the insert_iterator,	increments the
         iterator, and returns *this.

      insert_iterator<Container>&
      operator*();
         Returns *this (the	input iterator itself).

      insert_iterator<Container>&
      operator++();
      insert_iterator<Container>&
      operator++(int);
         Increments	the insert iterator and	returns	*this.

    NON-MEMBER FUNCTION

      template <class Container, class Iterator>
      insert_iterator<Container>
      inserter(Container& x, Iterator i);
         Returns an	insert_iterator	that will insert elements into
         container x at location i.  This function	allows you to create
         insert iterators inline.

    EXAMPLE

       #include <iterator>
       #include <vector>
       #include <iostream.h>
      int main()
       {
         //Initialize a vector using an array
        int	arr[4] = {3,4,7,8};
        vector<int>	v(arr,arr+4);
         //Output the original vector
        cout << "Start with	a vector: " << endl << "     ";
        copy(v.begin(),v.end(),ostream_iterator<int,char>(cout," "));
         //Insert into the middle
         insert_iterator<vector<int> >  ins(v, v.begin()+2);
         *ins = 5;
         *ins = 6;
         //Output the new vector
        cout << endl << endl;
        cout << "Use an insert_iterator: " << endl << "	";
        copy(v.begin(),v.end(),ostream_iterator<int,char>(cout," "));
        return 0;
       }

    WARNINGS

      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>

    SEE ALSO

      back_insert_iterator,	front_insert_iterator, Insert Iterators

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

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

    NAME

      Insert_Iterators  - Iterator adaptor that allows an iterator to
      insert into a container rather than overwrite elements in	the
      container.

    SYNOPSIS

      #include <iterator>

      template <class Container>
      class	insert_iterator	: public output_iterator;

      template <class Container>
      class	back_insert_iterator:public output_iterator;

      template <class Container>
      class	front_insert_iterator :	public output_iterator;

    DESCRIPTION

      Insert iterators are iterator	adaptors that let an iterator insert
      new elements	into a collection rather than overwrite	existing
      elements when copying to a container.  There are several types of
      insert iterator classes.

      +	  The class back_insert_iterator is used to insert items
           at the	end of a collection.	 The  function back_inserter
           can be used with an iterator	inline,	to create an instance
           of a back_insert_iterator for a particular collection type.

      +	  The class front_insert_iterator is used to insert items
           at the start of	a collection.  The function front_inserter
           creates an instance	of a front_insert_iterator for a
           particular collection type.

      +	  An insert_iterator inserts new items into a collection at
           a location defined by an iterator supplied to the constructor.
           Like the other insert iterators, insert_iterator has a helper
           function called inserter, which takes a collection and an
           iterator into that collection, and creates an instance of
           the insert_iterator.

    INTERFACE

      template <class Container>
      class	insert_iterator	: public output_iterator {

      public:
        insert_iterator (Container&, typename Container::iterator);
        insert_iterator<Container>&
         operator= (const typename Container::value_type&);
        insert_iterator<Container>&	operator* ();
        insert_iterator<Container>&	operator++ ();
        insert_iterator<Container>&	operator++ (int);
      };

      template <class Container>
      class	back_insert_iterator : public output_iterator {

      public:
        explicit back_insert_iterator (Container&);
        back_insert_iterator<Container>&
         operator= (const typename Container::value_type&);
        back_insert_iterator<Container>& operator* ();
        back_insert_iterator<Container>& operator++	();
        back_insert_iterator<Container> operator++ (int);
      };

      template <class Container>
      class	front_insert_iterator :	public output_iterator {

      public:
        explicit front_insert_iterator (Container&);
        front_insert_iterator<Container>&
         operator= (const typename Container::value_type&);
        front_insert_iterator<Container>& operator*	();
        front_insert_iterator<Container>& operator++ ();
        front_insert_iterator<Container> operator++	(int);
      };

      template <class Container, class Iterator>
      insert_iterator<Container> inserter (Container&, Iterator);

      template <class Container>
      back_insert_iterator<Container> back_inserter	(Container&);

      template <class Container>
      front_insert_iterator<Container> front_inserter (Container&);

    SEE ALSO

      back_insert_iterator,	front_insert_iterator, insert_iterator

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

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

    NAME

      istream_iterator  - Stream iterator that provides iterator
      capabilities for istreams.  This iterator allows generic algorithms
      to	be used	directly on streams.

    SYNOPSIS

      #include <iterator>

      template <class T, class charT, class	traits = ios_traits<charT>,
    	   class Distance = ptrdiff_t>
      class	istream_iterator : public iterator<input_iterator_tag,
    				T,Distance>;

    DESCRIPTION

      Stream iterators provide the standard	iterator interface for input
      and output streams.

      The class istream_iterator reads elements from an input stream
      (using operator >>).	 A value of type T is retrieved	and stored
      when	the iterator is constructed and each time operator++ is
      called.  The iterator will	be equal	to the end-of-stream
      iterator value if the end-of-file is reached. Use the constructor
      with no arguments	to create an end-of-stream iterator. The only
      valid use of	this iterator is to compare to other iterators when
      checking for end of file.  Do	not attempt to dereference the
      end-of-stream iterator;  it	plays the same role as the
      past-the-end	iterator provided by the end() function of
      containers.  Since an istream_iterator is an input iterator, you
      cannot assign to the value returned by dereferencing the iterator.
      This also means that istream_iterators can	only be	used for sin-
      gle pass algorithms.

      Since	a new value is read every time the operator++ is used on an
      istream_iterator, that operation is not equality-preserving.	This
      means that i == j does not mean that ++i ==	++j  (although two
      end-of-stream iterators are	always equal).

    INTERFACE

      template <class T, class charT, class	traits = ios_traits<charT>
    	   class Distance = ptrdiff_t>
      class	istream_iterator : public iterator<input_iterator_tag,
    					   T, Distance>
       {

      public:
         typedef T value_type;
         typedef charT char_type;
         typedef traits traits_type;
         typedef basic_istream<charT,traits> istream_type;

         istream_iterator();
         istream_iterator (istream_type&);
         istream_iterator
    	    (const stream_iterator<T,charT,traits,Distance>&);
          ~istream_itertor ();

         const T& operator*() const;
         const T* operator ->() const;
         istream_iterator <T,charT,traits,Distance>& operator++();
         istream_iterator <T,charT,traits,Distance>	 operator++ (int)
       };

      // Non-member	Operators

      template <class T, class charT, class	traits,	class Distance>
      bool operator==(const	istream_iterator<T,charT,traits,Distance>&,
    		const istream_iterator<T,charT,traits,Distance>&);

      template <class T, class charT, class	traits,	 class Distance>
      bool operator!=(const	istream_iterator<T,charT,traits,Distance>&,
    		const istream_iterator<T,charT,traits,Distance>&);

    TYPES

      value_type;
         Type of value to stream in.

      char_type;
         Type of character the stream is built on.

      traits_type;
         Traits used to build the stream.

      istream_type;
         Type of stream this iterator is constructed on.

    CONSTRUCTORS

      istream_iterator(); Construct an end-of-stream	iterator.
      This	iterator can be	used to	compare against an end-of-stream
      condition. Use it to	provide	end iterators to	algorithms

      istream_iterator(istream& s);
         Construct an istream_iterator on the given	stream.

      istream_iterator(const istream_iterator& x);
         Copy constructor.

    DESTRUCTORS

      ~istream_iterator();
         Destructor.

    OPERATORS

      const	T&
      operator*() const;
         Return the	current	value stored by	the iterator.

      const	T*
      operator->() const;
         Return a pointer to the current value stored by the iterator.

      istream_iterator& operator++()
      istream_iterator operator++(int)
         Retrieve the next element from the	input stream.

    NON-MEMBER OPERATORS

      bool
      operator==(const istream_iterator<T,charT,traits,Distance>& x,
    	     const istream_iterator<T,charT,traits,Distance>& y)
    		Equality operator. Returns true	if x is	the same as y.

      bool
      operator!=(const istream_iterator<T,charT,traits,Distance>& x,
    	     const istream_iterator<T,charT,traits,Distance>& y)
    		Inequality operator. Returns true if x is not the same
                    as y.

    EXAMPLE

      //
      // io_iter.cpp
      //
       #include <iterator>
       #include <vector>
       #include <numeric>
       #include <iostream.h>

      int main ()
       {
        vector<int>	d;
        int	total =	0;
         //
         //	Collect	values from cin	until end of file
         //	Note use of default constructor	to get ending iterator
         //
        cout << "Enter a sequence of integers (eof to quit): " ;
        copy(istream_iterator<int,char>(cin),
    	  istream_iterator<int,char>(),
    	 inserter(d,d.begin()));
         //
         //	stream the whole vector	and the	sum to cout
         //
        copy(d.begin(),d.end()-1,
    	 ostream_iterator<int,char>(cout," + "));
        if (d.size())
          cout << *(d.end()-1) << "	= " <<
    	   accumulate(d.begin(),d.end(),total) << endl;
        return 0;
       }

    WARNING

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

      vector<int, allocator<int> >

      instead of :

      vector<int>

    SEE ALSO

      iterators, ostream_iterators

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

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

    NAME

      istreambuf_iterator

    SYNOPSIS

      #include <streambuf>
      template<class charT,	class traits = char_traits<charT> >
      class	istreambuf_iterator
      : public input_iterator

    DESCRIPTION

      The template class istreambuf_iterator reads successive characters
      from the stream buffer	for which it was constructed.
      operator*	provides access	to the current input character, if
      any, and operator++ advances to the next input	character. If
      the end of stream	is reached, the	iterator becomes equal	to the
      end of stream iterator value, which is constructed by the default
      constructor, istreambuf_iterator(). An istreambuf_iterator object
      can be used only for one-pass-algorithms.

    INTERFACE

      template<class charT,	class traits = char_traits<charT> >
      class	istreambuf_iterator
      : public input_iterator {

      public:

       typedef charT			  char_type;
       typedef typename traits::int_type	  int_type;
       typedef traits			  traits_type;
       typedef basic_streambuf<charT, traits> streambuf_type;
       typedef basic_istream<charT,	traits>	  istream_type;

       class proxy;

       istreambuf_iterator() throw();
       istreambuf_iterator(istream_type& s)	 throw();
       istreambuf_iterator(streambuf_type *s) throw();
       istreambuf_iterator(const proxy& p) throw();

       char_type operator*();
       istreambuf_iterator<charT, traits>& operator++();
       proxy operator++(int);
       bool	equal(istreambuf_iterator<charT, traits>& b);

      };

      template<class charT,	class traits>
      bool operator==(istreambuf_iterator<charT, traits>& a,
    		 istreambuf_iterator<charT, traits>& b);

    TYPES

      char_type
         The type char_type	is a synonym for the template parameter	charT.

      int_type
         The type int_type is a synonym of type traits::in_type.

      istream_type
         The type istream_type is an instantiation of class	basic_istream on
         types charT and traits:

           typedef basic_istream<charT, traits>   istream_type;

      streambuf_type
         The type streambuf_type is	an instantiation of class basic_streambuf
         on types charT and traits:

           typedef basic_streambuf<charT, traits> streambuf_type;

      traits_type
         The type traits_type is a synonym for the template	parameter traits.

    NESTED CLASS PROXY

      Class	istreambuf_iterator<charT,traits>::proxy provides a temporary
      placeholder as the	return value of	the post-increment operator.
      It	keeps the character pointed to by the previous value of	the
      iterator for some possible future access.

    CONSTRUCTORS

      istreambuf_iterator()
       throw();
          Constructs the end of stream iterator.

      istreambuf_iterator(istream_type& s)
       throw();
          Constructs an istreambuf_iterator	that inputs characters using
         the basic_streambuf object pointed to	by s.rdbuf(). If
         s.rdbuf()  is a	null pointer, the istreambuf_iterator is the
         end-of-stream  iterator.

      istreambuf_iterator(streambuf_type *s)
       throw();
          Constructs an istreambuf_iterator	that inputs characters using
         the basic_streambuf object pointed at	by s. If s is a	null
         pointer, the istreambuf_iterator is the end-of-stream iterator.

      istreambuf_iterator(const proxy& p)
       throw();
         Constructs an istreambuf_iterator	that uses the basic_streambuf
         object embedded in the proxy object.

    MEMBER OPERATORS

      char_type
      operator*();
         Returns the character pointed at by the input sequence of the
         attached stream buffer. If no character is available, the
         iterator  becomes equal to	the end-of-stream iterator.

      istreambuf_iterator<charT, traits>&
      operator++();
         Increments	the input sequence of the attached stream buffer to
         point to the next character. If the	current	character is
         the  last one, the iterator becomes equal to the end-of-stream
         iterator.

      proxy
      operator++(int);
         Increments	the input sequence of the attached stream buffer to
         point to the next character. If the	current	character is
         the  last one, the iterator becomes equal to the end-of-stream
         iterator.  The proxy	object returned contains the character
         pointed at before  carrying	out the post-increment
         operator.

    PUBLIC MEMBER FUNCTION

      bool
      equal(istreambuf_iterator<charT, traits>& b);
         Returns true if and only if both iterators	are at end of stream,
         or neither is at	end of stream, regardless of what stream
         buffer	object they are using.

    NON MEMBER FUNCTIONS

      template<class charT,	class traits>
      bool
      operator==(istreambuf_iterator<charT,	traits>& a,
    		 istreambuf_iterator<charT, traits>& b);
    		    Returns a.equal(b).

    EXAMPLES

      //
      // stdlib/examples/manual/istreambuf_iterator.cpp
      //
      #include<iostream>
      #include<fstream>

      void main ( )
      {
       using namespace std;

        // open the	file is_iter.out for reading and writing
       ofstream out("is_iter.out", ios_base::out | ios_base::in );

        // output the example sentence into	the file
       out << "Ceci	est un simple example pour demontrer le" << endl;
       out << "fonctionement de istreambuf_iterator";

        // seek to the beginning of	the file
       out.seekp(0);

        // construct an istreambuf_iterator	pointing to
        // the ofstream object underlying stream buffer
       istreambuf_iterator<char> iter(out.rdbuf());

        // construct an end	of stream iterator
       istreambuf_iterator<char> end_of_stream_iterator;

       cout	<< endl;

        // output the content of the file
       while( !iter.equal(end_of_stream_iterator) )

        // use both	operator++ and operator*
       cout	<< *iter++;

       cout	<< endl;

      }

    SEE ALSO

      basic_streambuf, basic_istream,
      ostreambuf_iterator

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 24.4.3

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

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

    NAME

      ostream_iterator  - Stream iterators	provide	 iterator capabilities
      for ostreams and istreams.  They allow generic algorithms	to be
      used directly on streams.

    SYNOPSIS

      #include <ostream>

      template <class T, class charT,
    	   class traits	= char_traits<charT> >
      class	ostream_iterator
       : public iterator<output_iterator_tag,void,void>;

    DESCRIPTION

      Stream iterators provide the standard	iterator interface for input
      and output streams.

      The class ostream_iterator  writes elements to an output stream.  If
      you use the constructor that has a second, char *	argument, then
      that string will	be  written  after  every element .  (The
      string must be null-terminated.) Since an	ostream	iterator is an
      output iterator,	it is not possible to get an element out of
      the	iterator.  You can only	assign to it.

    INTERFACE

      template <class T, class charT,
    	   class traits	= char_traits<charT> >
      class	ostream_iterator
         : public iterator<output_iterator_tag,void,void>
      {
      public:
       typedef T value_type;
       typedef charT char_type;
       typedef traits traits_type;
       typedef basic_ostream<charT,traits> ostream_type;

         ostream_iterator(ostream&);
         ostream_iterator (ostream&, const char*);
         ostream_iterator (const
    	     ostream_iterator<T,charT,char_traits<charT> >&);
          ~ostream_itertor ();

         ostream_iterator<T,charT,char_traits<charT> >&
    	  operator=(const T&);
         ostream_iterator<T,charT,char_traits<charT> >&
    	  operator* () const;
         ostream_iterator<T,charT,char_traits<charT> >& operator++ ();
         ostream_iterator<T,charT,char_traits<charT> >  operator++ (int);
       };

    TYPES

      value_type;
         Type of value to stream in.

      char_type;
         Type of character the stream is built on.

      traits_type;
         Traits used to build the stream.

      ostream_type;
         Type of stream this iterator is constructed on.

    CONSTRUCTORS

      ostream_iterator (ostream& s);
         Construct an ostream_iterator on the given	stream.

      ostream_iterator (ostream& s,	const char* delimiter);
         Construct an ostream_iterator on the given	stream.	 The null
         terminated string delimitor is written to the stream after
         every element.

      ostream_iterator (const ostream_iterator<T>& x);
          Copy constructor.

    DESTRUCTOR

      ~ostream_iterator ();
          Destructor

    OPERATORS

      const	T&

      operator= (const T& value);
          Shift the	value T	onto the output	stream.

      const	T& ostream_iterator<T>&
      operator* ();
      ostream_iterator<T>&
      operator++();
      ostream_iterator<T>
      operator++ (int);
         These operators all do nothing.  They simply allow	 the iterator
         to be used in common constructs.

    EXAMPLE

       #include <iterator>
       #include <numeric>
       #include <deque>
       #include <iostream.h>

      int main ()
       {
         //
         //	Initialize a vector using an array.
         //
        int	arr[4] = { 3,4,7,8 };
        int	total=0;
        deque<int> d(arr+0,	arr+4);
         //
         //	stream the whole vector	and a sum to cout
         //
        copy(d.begin(),d.end()-1,
    	  ostream_iterator<int,char>(cout," + "));
        cout << *(d.end()-1) << " =	" <<
    	   accumulate(d.begin(),d.end(),total) << endl;
        return 0;
       }

    WARNING

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

      deque<int, allocator<int> >

      instead of :

      deque<int>

    SEE ALSO

      istream_iterator, iterators

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

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

    NAME

      ostreambuf_iterator

    SYNOPSIS

      #include <streambuf>
      template<class charT,	class traits = char_traits<charT> >
      class	ostreambuf_iterator
      : public output_iterator

    DESCRIPTION

      The template class ostreambuf_iterator writes	successive characters
      onto the stream buffer object from	which it was constructed. The
      operator=	is used to write	the characters and in case of
      failure the member function failed() returns true.

    INTERFACE

      template<class charT,	class traits = char_traits<charT> >
      class	ostreambuf_iterator
      : public output_iterator {

      public:

       typedef charT			  char_type;
       typedef traits			  traits_type;
       typedef basic_streambuf<charT, traits> streambuf_type;
       typedef basic_ostream<charT,	traits>	  ostream_type;

       ostreambuf_iterator(ostream_type& s)	throw();

       ostreambuf_iterator(streambuf_type *s) throw();

       ostreambuf_iterator&	operator*();
       ostreambuf_iterator&	operator++();
       ostreambuf_iterator operator++(int);

       ostreambuf_iterator&	operator=(charT	c);

       bool	failed(	) const	throw();

      };

    TYPES

      char_type
         The type char_type	is a synonym for the template parameter	charT.

      ostream_type
         The type ostream_type is an instantiation of class	basic_ostream
         on types charT and traits:

           typedef basic_ostream<charT, traits>   ostream_type;

      streambuf_type
         The type streambuf_type is	an instantiation of class
         basic_streambuf on types charT and traits:

           typedef basic_streambuf<charT, traits> streambuf_type;

      traits_type
         The type traits_type is a synonym for the template	parameter
         traits.

    CONSTRUCTORS

      ostreambuf_iterator(ostream_type& s) throw();
         Constructs	an ostreambuf_iterator that uses the basic_streambuf
         object pointed at	by s.rdbuf()to output characters. If s.rdbuf()
         is a null pointer, calls to the member function failed() return
         true.

      ostreambuf_iterator(streambuf_type *s) throw();
         Constructs	an ostreambuf_iterator that uses the basic_streambuf
         object pointed at	by s to	output characters. If s	is a null
         pointer, calls to the member	function failed() return true.

    MEMBER OPERATORS

      ostreambuf_iterator&
      operator=(charT c);
         Inserts the character c into the output sequence of the attached
         stream buffer. If	the operation fails, calls to the member
         function  failed() return true.

      ostreambuf_iterator&
      operator++();
         Returns *this.

      ostreambuf_iterator
      operator++(int);
         Returns *this.

      ostreambuf_iterator
      operator*();
         Returns *this.

    PUBLIC MEMBER FUNCTION

      bool
      failed() const
       throw();
          Returns true if the iterator failed inserting a characters or
          false otherwise.

    EXAMPLES

      //
      // stdlib/examples/manual/ostreambuf_iterator.cpp
      //
      #include<iostream>
      #include<fstream>

      void main ( )
      {
       using namespace std;

        // create a	filebuf	object
       filebuf  buf;

        // open the	file iter_out and link it to the filebuf object
       buf.open("iter_out",	ios_base::in | ios_base::out );

        // create an ostreambuf_iterator and link it to
        // the filebuf object
       ostreambuf_iterator<char> out_iter(&buf);

        // output into the file using the ostreambuf_iterator
       for(char i=64; i<128; i++ )
        out_iter = i;

        // seek to the beginning of	the file
       buf.pubseekpos(0);

        // create an istreambuf_iterator and link it to
        // the filebuf object
       istreambuf_iterator<char> in_iter(&buf);

        // construct an end	of stream iterator
       istreambuf_iterator<char> end_of_stream_iterator;

       cout	<< endl;

        // output the content of the file
       while( !in_iter.equal(end_of_stream_iterator) )

        // use both	operator++ and operator*
       cout	<< *in_iter++;

       cout	<< endl;

      }

    SEE ALSO

      basic_streambuf, basic_ostream,
      istreambuf_iterator

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 24.4.4

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

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

    NAME

      Output_Iterators  - A	write-only, forward moving iterator.

    DESCRIPTION

      For a	complete discussion of iterators, see the Iterators section of
      this reference.

      Iterators are	a generalization of pointers that allow	a C++ program
      to uniformly interact with different data structures.  Output
      iterators are write-only, forward moving iterators that satisfy the
      requirements listed below.  Note that unlike other iterators used
      with the standard library, output iterators cannot be constant.

    KEY TO ITERATOR	REQUIREMENTS

      The following	key pertains to	the iterator requirements listed
      below:

      a and	b   values of type X

      n   value of distance	type

      u, Distance, tmp and m   identifiers

      r   value of type X&

      t   value of type T

    REQUIREMENTS FOR OUTPUT	ITERATORS

      The following	expressions must be valid for output iterators:

      X(a)	 copy constructor, a ==	X(a).

      X u(a)   copy	constructor, u == a

      X u =	a   assignment,	u == a

      *a = t   result is not used

      ++r	returns	X&

      r++	return value convertible to const X&

      *r++ = t   result is not used

      The only valid use for the operator *	is on the left hand side of
      the assignment statement.

      Algorithms using output iterators should be single pass algorithms.
      That is, they should not pass through the same iterator twice.

    SEE ALSO

      Iterators, Input Iterators

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

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

    NAME

      Random_Access_Iterators  - An	iterator that reads and	writes,	and
      provides random access	to a container.

    DESCRIPTION

      For a	complete discussion of iterators, see the Iterators section of
      this reference.

      Iterators are	a generalization of pointers that allow	a C++ program
      to uniformly interact with different data structures.  Random
      access iterators can read and write, and provide random access
      to the containers they serve. These	iterators satisfy the
      requirements listed below.

    KEY TO ITERATOR	REQUIREMENTS

      The following	key pertains to	the iterator requirements listed
      below:

      a and	b   values of type X

      n   value of distance	type

      u, Distance, tmp and m   identifiers

      r   value of type X&

      t   value of type T

    REQUIREMENTS FOR RANDOM	ACCESS ITERATORS

      The following	expressions must be valid for random access iterators:

      X u	u might	have a singular	value

      X()	X() might be singular

      X(a)	 copy constructor, a ==	X(a).

      X u(a)   copy	constructor, u == a

      X u =	a   assignment,	u == a

      a == b, a != b   return value	convertible to bool

      *a   return value convertible	to T&

      a->m	 equivalent to (*a).m

      ++r	returns	X&

      r++	return value convertible to const X&

      *r++	 returns T&

      --r	returns	X&

      r--	return value convertible to const X&

      *r--	 returns T&

      r += n   Semantics of	--r or ++r n times depending on	the sign
               of n

      a + n, n + a	 returns type X

      r -= n   returns X&, behaves as r += -n

      a - n	  returns type X

      b - a	  returns Distance

      a[n]	 *(a+n), return	value convertible to T

      a < b	  total	ordering relation

      a > b	  total	ordering relation opposite to <

      a <= b   !(a < b)

      a >= b   !(a > b)

      Like forward iterators, random access	iterators have the condition
      that  a == b implies *a == *b.

      There	are no restrictions on the number of passes an algorithm may
      make through the structure.

      All relational operators return a value convertible to bool.

    SEE ALSO

      Iterators, Forward Iterators,	Bidirectional Iterators

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

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

    NAME

      raw_storage_iterator	- Enables iterator-based algorithms to store
      results into uninitialized memory.

    SYNOPSIS

      #include <memory>

      template <class OutputIterator, class	T>
      class	raw_storage_iterator : public output_iterator {

      public:
        explicit raw_storage_iterator (OutputIterator);
        raw_storage_iterator<OutputIterator, t>& operator*();
        raw_storage_iterator<OutputIterator, T>&
          operator=	(const T&);
        raw_storage_iterator<OutputIterator>& operator++();
        raw_storage_iterator<OutputIterator> operator++ (int);
      };

    DESCRIPTION

      Class	raw_storage_iterator enables iterator-based algorithms to
      store	their results in uninitialized memory.  The	template
      parameter, OutputIterator is required to have its operator* return
      an object for which operator& is both defined and returns a
      pointer	to T.

    CONSTRUCTOR

      raw_storage_iterator (OutputIterator x);
         Initializes the iterator to point to the same value that x
         points to.

    MEMBER OPERATORS

      raw_storage_iterator <OutputIterator,	T>&
        operator =(const T&	element);
           Constructs an instance of T, initialized	to the value element ,
           at the location	pointed	to by the iterator.

      raw_storage_iterator <OutputIterator,	T>&
      operator++();
          Pre-increment:  advances the iterator and	returns	a reference
          to the updated iterator.

      raw_storage_iterator<OutputIterator>
       operator++ (int);

         Post-increment:  advances the iterator and	returns	the old
         value of the iterator.

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

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

    NAME

      reverse_bidirectional_iterator, reverse_iterator  - An iterator that
      traverses a collection backwards.

    SYNOPSIS

      #include <iterator>

      template <class BidirectionalIterator,
    	   class T,
    	   class Reference = T&,
    	   class Pointer = T*
    	   class Distance = ptrdiff_t>
      class	reverse_bidirectional_iterator : public
           iterator<bidirectional_iterator_tag,T, Distance>	;

      template <class RandomAccessIterator,
    	   class T,
    	   class Reference = T&,
    	   class Pointer = T*,
    	   class Distance = ptrdiff_t>
      class	reverse_iterator : public
    	iterator<random_access_iterator_tag,T,Distance>;

    DESCRIPTION

      The iterators	reverse_iterator  and reverse_bidirectional_iterator
      correspond to	random_access_iterator and bidirectional_iterator,
      except they traverse	the collection they point to in	the opposite
      direction.	 The fundamental relationship between a reverse
      iterator and its corresponding iterator i is	established by the
      identity:

      &*(reverse_iterator(i)) == &*(i-1);

      This mapping is dictated by the fact that, while there is always a
      pointer past the end of a container, there might not be a valid
      pointer before its beginning.

      The following	are true for reverse_bidirectional_iterators :

      +	  These	iterators may be instantiated with the default
           constructor or by a single argument constructor	that
           initializes the new reverse_bidirectional_iterator with a
           bidirectional_iterator.

      +	  operator* returns a reference	to the current value pointed to.

      +	  operator++ advances the iterator to the previous item
           (--current) and returns a reference to *this.

      +	  operator++(int) advances the iterator	to the	previous
           item (--current)	and returns the	old value of *this.

      +	  operator-- advances the iterator to the following item
           (++current) and returns a reference to *this.

      +	  operator--(int) Advances the iterator	to the following item
           (++current) and returns the old value of	*this.

      +	  operator== This non-member operator returns true if the
           iterators x and y point to the same item.

      The following	are true for reverse_iterators :

      +	  These	iterators may be instantiated with the default
           constructor or by a single argument constructor	which
           initializes the new reverse_iterator	with a
           random_access_iterator.

      +	  operator* returns a reference	to the current value pointed
           to.

      +	  operator++ advances the iterator to the previous item
           (--current) and returns a reference to *this.

      +	  operator++(int) advances the iterator	to the previous	item
           (--current)	and returns the	old value of *this.

      +	  operator-- advances the iterator to the  following  item
           (++current) and returns a reference to *this.

      +	  operator--(int) advances the iterator	to the following item
           (++current) and returns the old value of	*this.

      +	  operator== is	a non-member operator returns true if  the
           iterators x and y point to	the same item.

      +	  operator!= is	a non-member operator returns  !(x==y).

      +	  operator< is a non-member operator returns true if  the
           iterator x precedes	the iterator y.

      +	  operator> is a non-member operator returns y < x.

      +	  operator<= is	a non-member operator returns !(y < x).

      +	  operator>= is	a non-member operator returns !(x < y).

      +	  The remaining	operators (<, +, - , +=, -=) are redefined
           to behave exactly as they would in	a random_access_iterator,
           except with the sense of	 direction reversed.

    COMPLEXITY

      All iterator operations are required to take at most amortized
      constant time.

    INTERFACE

      template <class BidirectionalIterator,
    	   class T,
    	   class Reference = T&,
    	   class Pointer = T*,
    	   class Distance = ptrdiff_t>
      class	reverse_bidirectional_iterator
         : public iterator<bidirectional_iterator_tag,T, Distance> {
         typedef reverse_bidirectional_iterator<BidirectionalIterator, T,
    					    Reference,
    					    Pointer, Distance> self;
         friend bool operator== (const self&, const	self&);
       public:
         reverse_bidirectional_iterator ();
         explicit reverse_bidirectional_iterator
    	(BidirectionalIterator);
         BidirectionalIterator base	();
         Reference operator* ();
         self& operator++ ();
         self operator++ (int);
         self& operator-- ();
         self operator-- (int);
        };

      // Non-member	Operators

       template <class BidirectionalIterator,
    	     class T, class Reference,
    	     class Pointer, class Distance>
       bool	operator== (
          const reverse_bidirectional_iterator
    	  <BidirectionalIterator,T,Reference,Pointer,Distance>&,
           const reverse_bidirectional_iterator
    	  <BidirectionalIterator,T,Reference,Pointer,Distance>&);

      template <class BidirectionalIterator,
    	     class T, class Reference,
    	     class Pointer, class Distance>
       bool	operator!= (
          const reverse_bidirectional_iterator
    	  <BidirectionalIterator,T,Reference,Pointer,Distance>&,
           const reverse_bidirectional_iterator
    	  <BidirectionalIterator,T,Reference,Pointer,Distance>&);

      template <class RandomAccessIterator,
    	   class T,
    	   class Reference = T&,
    	   class Pointer = T*,
    	   class Distance = ptrdiff_t>
      class	reverse_iterator
         : public iterator<random_access_iterator_tag,T,Distance> {

         typedef reverse_iterator<RandomAccessIterator, T, Reference,
    			      Pointer, Distance> self;

         friend bool operator==    (const self&, const self&);
         friend bool operator<     (const self&, const self&);
         friend Distance operator- (const self&, const self&);
         friend self operator+     (Distance, const	self&);

      public:
         reverse_iterator ();
         explicit reverse_iterator (RandomAccessIterator);
         RandomAccessIterator base ();
         Reference operator* ();
         self& operator++ ();
         self operator++ (int);
         self& operator-- ();
         self operator-- (int);

         self  operator+ (Distance)	const;
         self& operator+= (Distance);
         self operator- (Distance) const;
         self& operator-= (Distance);
         Reference operator[] (Distance);
      };

      // Non-member	Operators

         template <class RandomAccessIterator, class T,
    	       class Reference,	class Pointer,
    	       class Distance> bool operator== (
    	 const reverse_iterator<RandomAccessIterator, T,
    				Reference, Pointer,
    				Distance>&,
    	 const reverse_iterator<RandomAccessIterator, T,
    				Reference, Pointer,
    				Distance>&);

      template <class RandomAccessIterator,	class T,
    	       class Reference,	class Pointer,
    	       class Distance> bool operator!= (
    	 const reverse_iterator<RandomAccessIterator, T,
    				Reference, Pointer,
    				Distance>&,
    	 const reverse_iterator<RandomAccessIterator, T,
    				Reference, Pointer,
    				Distance>&);

          template <class RandomAccessIterator, class T,
    		class Reference, class Pointer,
    		class Distance>	bool operator< (
    	  const	reverse_iterator<RandomAccessIterator, T,
    				 Reference, Pointer,
    				 Distance>&,
    	  const	reverse_iterator<RandomAccessIterator, T,
    				 Reference, Pointer,
    				 Distance>&);

      template <class RandomAccessIterator,	class T,
    		class Reference, class Pointer,
    		class Distance>	bool operator> (
    	  const	reverse_iterator<RandomAccessIterator, T,
    				 Reference, Pointer,
    				 Distance>&,
    	  const	reverse_iterator<RandomAccessIterator, T,
    				 Reference, Pointer,
    				 Distance>&);

      template <class RandomAccessIterator,	class T,
    		class Reference, class Pointer,
    		class Distance>	bool operator<=	(
    	  const	reverse_iterator<RandomAccessIterator, T,
    				 Reference, Pointer,
    				 Distance>&,
    	  const	reverse_iterator<RandomAccessIterator, T,
    				 Reference, Pointer,
    				 Distance>&);

      template <class RandomAccessIterator,	class T,
    		class Reference, class Pointer,
    		class Distance>	bool operator>=	(
    	  const	reverse_iterator<RandomAccessIterator, T,
    				 Reference, Pointer,
    				 Distance>&,
    	  const	reverse_iterator<RandomAccessIterator, T,
    				 Reference, Pointer,
    				 Distance>&);

          template <class RandomAccessIterator, class T,
    		class Reference, class Pointer,
    		class Distance>	Distance operator- (
    	  const	reverse_iterator<RandomAccessIterator, T,
    				 Reference, Pointer,
    				 Distance>&,
    	  const	reverse_iterator<RandomAccessIterator, T,
    				 Reference, Pointer,
    				 Distance>&);

          template <class RandomAccessIterator, class T,
    		class Reference, class Pointer,
    		class Distance>
           reverse_iterator<RandomAccessIterator, T,
    			Reference, Pointer,
    			Distance> operator+ (
    	  Distance,
    	  const	reverse_iterator<RandomAccessIterator, T,
    				 Reference, Pointer,
    				 Distance>&);

    EXAMPLE

      //
      // rev_itr.cpp
      //
       #include <iterator>
       #include <vector>
       #include <iostream.h>

      int main()
       {
         //Initialize a vector using an array
        int	arr[4] = {3,4,7,8};
        vector<int>	v(arr,arr+4);
         //Output the original vector
        cout << "Traversing	vector with iterator: "	<< endl	<< "	 ";
        for(vector<int>::iterator i	= v.begin(); i != v.end(); i++)
          cout << *i << " ";
         //Declare the reverse_iterator
        vector<int>::reverse_iterator rev(v.end());
        vector<int>::reverse_iterator rev_end(v.begin());
         //Output the vector backwards
        cout << endl << endl;
        cout << "Same vector, same loop, reverse_itertor: "	<< endl
    	    << "     ";
        for(; rev != rev_end; rev++)
          cout << *rev << "	";
        return 0;
       }

      Output :
      Traversing vector with iterator:
          3	4 7 8
      Same vector, same loop, reverse_itertor:
          8	7 4 3

    WARNING

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

      vector<int, allocator<int> >

      instead of :

      vector<int>

    SEE ALSO

      Iterators

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

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

    NAME

      reverse_bidirectional_iterator, reverse_iterator  - An iterator that
      traverses a collection backwards.

    SYNOPSIS

      #include <iterator>

      template <class BidirectionalIterator,
    	   class T,
    	   class Reference = T&,
    	   class Pointer = T*
    	   class Distance = ptrdiff_t>
      class	reverse_bidirectional_iterator : public
           iterator<bidirectional_iterator_tag,T, Distance>	;

      template <class RandomAccessIterator,
    	   class T,
    	   class Reference = T&,
    	   class Pointer = T*,
    	   class Distance = ptrdiff_t>
      class	reverse_iterator : public
    	iterator<random_access_iterator_tag,T,Distance>;

    DESCRIPTION

      The iterators	reverse_iterator  and reverse_bidirectional_iterator
      correspond to	random_access_iterator and bidirectional_iterator,
      except they traverse	the collection they point to in	the opposite
      direction.	 The fundamental relationship between a reverse
      iterator and its corresponding iterator i is	established by the
      identity:

      &*(reverse_iterator(i)) == &*(i-1);

      This mapping is dictated by the fact that, while there is always a
      pointer past the end of a container, there might not be a valid
      pointer before its beginning.

      The following	are true for reverse_bidirectional_iterators :

      +	  These	iterators may be instantiated with the default
           constructor or by a single argument constructor	that
           initializes the new  reverse_bidirectional_iterator with a
           bidirectional_iterator.

      +	  operator* returns a reference	to the current value pointed
           to.

      +	  operator++ advances the iterator to the previous item
           (--current) and returns a reference to *this.

      +	  operator++(int) advances the iterator	to the	previous item
           (--current)	and returns the	old value of *this.

      +	  operator-- advances the iterator to the following item
           (++current) and returns a reference to *this.

      +	  operator--(int) Advances the iterator	to the following item
           (++current) and returns the old value of	*this.

      +	  operator== This non-member operator returns true if the
           iterators x and y point to the same item.

      The following	are true for reverse_iterators :

      +	  These	iterators may be instantiated with the default
           constructor or by a single argument constructor	which
           initializes the new reverse_iterator	with a
           random_access_iterator.

      +	  operator* returns a reference	to the current value pointed
           to.

      +	  operator++ advances the iterator to the previous item
           (--current) and returns a reference to *this.

      +	  operator++(int) advances the iterator	to the previous	item
           (--current)	and returns the	old value of *this.

      +	  operator-- advances the iterator to the  following  item
           (++current) and returns a reference to *this.

      +	  operator--(int) advances the iterator	to the following item
           (++current) and returns the old value of	*this.

      +	  operator== is	a non-member operator returns true if  the
           iterators x and y point to	the same item.

      +	  operator!= is	a non-member operator returns  !(x==y).

      +	  operator< is a non-member operator returns true if  the
           iterator x precedes	the iterator y.

      +	  operator> is a non-member operator returns y < x.

      +	  operator<= is	a non-member operator returns !(y < x).

      +	  operator>= is	a non-member operator returns !(x < y).

      +	  The remaining	operators (<, +, - , +=, -=) are redefined
           to behave exactly as they would in	a
           random_access_iterator, except with the sense of	 direction
           reversed.

    COMPLEXITY

      All iterator operations are required to take at most amortized
      constant time.

    INTERFACE

      template <class BidirectionalIterator,
    	   class T,
    	   class Reference = T&,
    	   class Pointer = T*,
    	   class Distance = ptrdiff_t>
      class	reverse_bidirectional_iterator
         : public iterator<bidirectional_iterator_tag,T, Distance> {
         typedef reverse_bidirectional_iterator<BidirectionalIterator, T,
    					    Reference,
    					    Pointer, Distance> self;
         friend bool operator== (const self&, const	self&);
       public:
         reverse_bidirectional_iterator ();
         explicit reverse_bidirectional_iterator
    	(BidirectionalIterator);
         BidirectionalIterator base	();
         Reference operator* ();
         self& operator++ ();
         self operator++ (int);
         self& operator-- ();
         self operator-- (int);
        };

      // Non-member	Operators

       template <class BidirectionalIterator,
    	     class T, class Reference,
    	     class Pointer, class Distance>
       bool	operator== (
          const reverse_bidirectional_iterator
    	  <BidirectionalIterator,T,Reference,Pointer,Distance>&,
           const reverse_bidirectional_iterator
    	  <BidirectionalIterator,T,Reference,Pointer,Distance>&);

      template <class BidirectionalIterator,
    	     class T, class Reference,
    	     class Pointer, class Distance>
       bool	operator!= (
          const reverse_bidirectional_iterator
    	  <BidirectionalIterator,T,Reference,Pointer,Distance>&,
           const reverse_bidirectional_iterator
    	  <BidirectionalIterator,T,Reference,Pointer,Distance>&);

      template <class RandomAccessIterator,
    	   class T,
    	   class Reference = T&,
    	   class Pointer = T*,
    	   class Distance = ptrdiff_t>
      class	reverse_iterator
         : public iterator<random_access_iterator_tag,T,Distance> {

         typedef reverse_iterator<RandomAccessIterator, T, Reference,
    			      Pointer, Distance> self;

         friend bool operator==    (const self&, const self&);
         friend bool operator<     (const self&, const self&);
         friend Distance operator- (const self&, const self&);
         friend self operator+     (Distance, const	self&);

      public:
         reverse_iterator ();
         explicit reverse_iterator (RandomAccessIterator);
         RandomAccessIterator base ();
         Reference operator* ();
         self& operator++ ();
         self operator++ (int);
         self& operator-- ();
         self operator-- (int);

         self  operator+ (Distance)	const;
         self& operator+= (Distance);
         self operator- (Distance) const;
         self& operator-= (Distance);
         Reference operator[] (Distance);
      };

      // Non-member	Operators

         template <class RandomAccessIterator, class T,
    	       class Reference,	class Pointer,
    	       class Distance> bool operator== (
    	 const reverse_iterator<RandomAccessIterator, T,
    				Reference, Pointer,
    				Distance>&,
    	 const reverse_iterator<RandomAccessIterator, T,
    				Reference, Pointer,
    				Distance>&);

      template <class RandomAccessIterator,	class T,
    	       class Reference,	class Pointer,
    	       class Distance> bool operator!= (
    	 const reverse_iterator<RandomAccessIterator, T,
    				Reference, Pointer,
    				Distance>&,
    	 const reverse_iterator<RandomAccessIterator, T,
    				Reference, Pointer,
    				Distance>&);

          template <class RandomAccessIterator, class T,
    		class Reference, class Pointer,
    		class Distance>	bool operator< (
    	  const	reverse_iterator<RandomAccessIterator, T,
    				 Reference, Pointer,
    				 Distance>&,
    	  const	reverse_iterator<RandomAccessIterator, T,
    				 Reference, Pointer,
    				 Distance>&);

      template <class RandomAccessIterator,	class T,
    		class Reference, class Pointer,
    		class Distance>	bool operator> (
    	  const	reverse_iterator<RandomAccessIterator, T,
    				 Reference, Pointer,
    				 Distance>&,
    	  const	reverse_iterator<RandomAccessIterator, T,
    				 Reference, Pointer,
    				 Distance>&);

      template <class RandomAccessIterator,	class T,
    		class Reference, class Pointer,
    		class Distance>	bool operator<=	(
    	  const	reverse_iterator<RandomAccessIterator, T,
    				 Reference, Pointer,
    				 Distance>&,
    	  const	reverse_iterator<RandomAccessIterator, T,
    				 Reference, Pointer,
    				 Distance>&);

      template <class RandomAccessIterator,	class T,
    		class Reference, class Pointer,
    		class Distance>	bool operator>=	(
    	  const	reverse_iterator<RandomAccessIterator, T,
    				 Reference, Pointer,
    				 Distance>&,
    	  const	reverse_iterator<RandomAccessIterator, T,
    				 Reference, Pointer,
    				 Distance>&);

          template <class RandomAccessIterator, class T,
    		class Reference, class Pointer,
    		class Distance>	Distance operator- (
    	  const	reverse_iterator<RandomAccessIterator, T,
    				 Reference, Pointer,
    				 Distance>&,
    	  const	reverse_iterator<RandomAccessIterator, T,
    				 Reference, Pointer,
    				 Distance>&);

          template <class RandomAccessIterator, class T,
    		class Reference, class Pointer,
    		class Distance>
           reverse_iterator<RandomAccessIterator, T,
    			Reference, Pointer,
    			Distance> operator+ (
    	  Distance,
    	  const	reverse_iterator<RandomAccessIterator, T,
    				 Reference, Pointer,
    				 Distance>&);

    EXAMPLE

      //
      // rev_itr.cpp
      //
       #include <iterator>
       #include <vector>
       #include <iostream.h>

      int main()
       {
         //Initialize a vector using an array
        int	arr[4] = {3,4,7,8};
        vector<int>	v(arr,arr+4);
         //Output the original vector
        cout << "Traversing	vector with iterator: "	<< endl	<< "	 ";
        for(vector<int>::iterator i	= v.begin(); i != v.end(); i++)
          cout << *i << " ";
         //Declare the reverse_iterator
        vector<int>::reverse_iterator rev(v.end());
        vector<int>::reverse_iterator rev_end(v.begin());
         //Output the vector backwards
        cout << endl << endl;
        cout << "Same vector, same loop, reverse_itertor: "	<< endl
    	    << "     ";
        for(; rev != rev_end; rev++)
          cout << *rev << "	";
        return 0;
       }

      Output :
      Traversing vector with iterator:
          3	4 7 8
      Same vector, same loop, reverse_itertor:
          8	7 4 3

    WARNING

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

      vector<int, allocator<int> >

      instead of :

      vector<int>

    SEE ALSO

      Iterators

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

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

    NAME

      Stream_Iterators  - Stream iterators provide iterator	capabilities
      for ostreams and istreams.  They allow generic algorithms	to be
      used directly on streams.

      See the sections istream_iterator and	ostream_iterator for a
      description of these	iterators.

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

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

    NAME

      value_type  -	Determine the type of value an iterator	points 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 T* value_type (const input_iterator<T,	Distance>&)

      template <class T, class Distance>
      inline T* value_type (const forward_iterator<T, Distance>&)

      template <class T, class Distance>
      inline T* value_type (const bidirectional_iterator<T,	Distance>&)

      template <class T, class Distance>
      inline T* value_type (const random_access_iterator<T,	Distance>&)

      template <class T>
      inline T* value_type (const T*)

    DESCRIPTION

      The value_type  function template returns a pointer to a default
      value of the type pointed to by an iterator.  Five overloaded
      versions	of this	function template	handle the four	basic
      iterator types and simple	arrays.	 Each of the first four take
      an iterator of	a specific type, and return the	value used to
      instantiate the iterator.  The fifth version takes and returns a T*
      in order to handle the case when an iterator is a simple pointer.

      This family of  function templates can be used to extract a value
      type from an iterator and subsequently use that	type to	create
      a local variable. Typically the	value_type functions are used
      like this:

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

      template <class Iterator, class T>
      void __foo(Iterator first, Iterator last, T*>
      {
       T temp = *first;
         _
      }

      The auxiliary	function __foo extracts	a usable value type from the
      iterator and then puts	the type to work.

    SEE ALSO

      Other	iterator primitives:  distance_type, iterator_category,
      distance, advance

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

|  | privacy statement and legal notices