Compaq C++ User Documentation

| United States

cxxlstd$help.HLP

##

##

##

    Overview
    Name
      cxxstdlib_intro - Introduction to the	Compaq C++ ANSI Standard
      Library

      This page describes the Compaq C++ ANSI Standard	Library.
      For an overview of the pre-ANSI C++ Class Library, type

           help cxxl

    DESCRIPTION

      The Compaq C++ ANSI Standard Library is an implementation of the
      C++ Standard Library.  It is comprised of a suite of header files
      and the run time code needed to implement the following clauses in
      the C++ Standard:

      ____________________________________________
      Clause   Description
      ____________________________________________
        18	   Run time support (new(),exceptions)
        21	   String Library
        22	   Localization	(locale) Library
        23	   Container Library
        24	   Iterator Library
        25	   Algorithms Library
        26	   Numerics Library
        27	   Input/Output	(iostream) Library

    See Also
      iostream_intro

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

    NAME

      complex - C++	complex	number library

      This page describes ANSI complex class. If you would like information
      on the pre-ANSI complex package,use the command:

           help cxxl

    SPECIALIZATIONS

      complex <float>
      complex <double>
      complex <long	double>

    SYNOPSIS

      #include <complex>

      template <class T>
      class	complex	;

      class	complex<float>;
      class	complex<double>;
      class	complex<long double>;

    DESCRIPTION

      complex<T> is	a class	that supports complex numbers. A complex number
      has a real part and	an imaginary part. The complex class supports
      equality,comparison and basic arithmetic operations. In addition,
      mathematical functions such as exponents, logarithms, powers, and
      square roots are also available.

    INTERFACE

      template <class T>
      class	complex	{

      public:
        typedef T value_type;

        complex (T = 0 , T = 0);
        template <class X> complex
          (const complex<X>&);

        T real () const;
        T imag () const;

        complex<T>&	operator= (const T&);
        complex<T>&	operator+=(const T&);
        complex<T>&	operator-=(const T&);
        complex<T>&	operator*=(const T&);
        complex<T>&	operator/=(const T&);

        template <class X>
         complex<T>& operator= (const complex<X>&);

        template <class X>
         complex<T>& operator+= (const complex<X>&);
        template <class X>
         complex<T>& operator-= (const complex<X>&);
        template <class X>
         complex<T>& operator*= (const complex<X>&);
        template <class X>
         complex<T>& operator/= (const complex<X>&);
      };

      // Non-member	Operators

      template<class T>
      complex<T> operator+ (const complex<T>&, const complex<T>&);
      template<class T>
      complex<T> operator+ (const complex<T>&, T);
      template<class T>
      complex<T> operator+ (T, const complex<T>&);

      template<class T>
      complex<T> operator- (const complex<T>&, const complex<T>&);
      template<class T>
      complex<T> operator- (const complex<T>&, T);
      template<classT>
      complex<T> operator- (T, const complex<T>&);

      template<class T>
      complex<T> operator* (const complex<T>&, const complex<T>&);
      template<class T>
      complex<T> operator* (const complex<T>&, T);
      template<class T>
      complex<T> operator* (T, const complex<T>&);

      template<class T>
      complex<T> operator/ (const complex<T>&, const complex<T>&);
      template<class T>
      complex<T> operator/ (const complex<T>&, T);
      template<class T>
      complex<T> operator/ (T, const complex<T>&);

      template<class T>
      complex<T> operator+ (const complex<T>&);
      template<class T>
      complex<T> operator- (const complex<T>&);

      template<class T>
      bool operator== (const complex<T>&, const complex<T>&);
      template<class T>
      bool operator== (const complex<T>&, T);
      template<class T>
      bool operator== (T, const complex<T>&);

      template<class T>
      bool operator!= (const complex<T>&, const complex<T>&);
      template<class T>
      bool operator!= (const complex<T>&, T);
      template<class T>
      bool operator!= (T, const complex<T>&);

      template <class X>
      istream& operator>> (istream&, complex<X>&);
      template <class X>
      ostream& operator<< (ostream&, const complex<X>&);

      // Values

      template<class T> T real (const complex<T>&);
      template<class T> T imag (const complex<T>&);

      template<class T> T abs (const complex<T>&);
      template<class T> T arg (const complex<T>&);
      template<class T> T norm (const complex<T>&);

      template<class T> complex<T> conj (const complex<T>&);
      template<class T> complex<T> polar (T, T);

      // Transcendentals

      template<class T> complex<T> cos (const complex<T>&);
      template<class T> complex<T> cosh (const complex<T>&);
      template<class T> complex<T> exp (const complex<T>&);
      template<class T> complex<T> log (const complex<T>&);

      template<class T> complex<T> log10 (const complex<T>&);

      template<class T> complex<T> pow (const complex<T>&, int);
      template<class T> complex<T> pow (const complex<T>&, T);
      template<class T> complex<T> pow (const complex<T>&,
    				   const complex<T>&);
      template<class T> complex<T> pow (T, const complex<T>&);

      template<class T> complex<T> sin (const complex<T>&);
      template<class T> complex<T> sinh (const complex<T>&);
      template<class T> complex<T> sqrt (const complex<T>&);
      template<class T> complex<T> tan (const complex<T>&);
      template<class T> complex<T> tanh (const complex<T>&);

    CONSTRUCTORS

      complex
      (const T& re_arg = 0,	const T& im_arg	= 0);
         Constructs	an object of class complex,  initializing re_arg to
         the real part and im_arg to the imaginary part.

    ASSIGNMENT OPERATORS
      template <class X> complex (const complex<X>&);
        Copy constructor. Constructs a complex number from another
        complex number.

      complex<T>& operator=(const T& v);
         Assigns v to the real part	of itself, setting the imaginary part
         to 0.

      complex<T>& operator+=(const T& v);
         Adds v to the real	part of	itself,	then returns the result.

      complex<T>& operator-=(const T& v);
         Subtracts v from the real part of itself, then returns the	result.

      complex<T>& operator*=(const T& v);
         Multiplies	v by the real part of itself, then returns the result.

      complex<T>& operator/=(const T& v);
         Divides v by the real part	of itself, then	returns	the result.

      template <class X>
      complex<T>
      operator=(const complex<X>& c);
         Assigns c to itself.

      template <class X>
      complex<T>
      operator+=(const complex<X>& c);
         Adds c to itself, then returns the	result.

      template <class X>
      complex<T>
      operator-=(const complex<X>& c);
         Subtracts c from itself, then returns the result.

      template <class X>
      complex<T>
      operator*=(const complex<X>& c);
         Multiplies	itself by c then returns the result.

      template <class X>
      complex<T>
      operator/=(const complex<X>& c);
         Divides itself by c, then returns the result.

    MEMBER FUNCTIONS

      T
      imag() const;
         Returns the imaginary part	of the complex number.

      T
      real() const;
         Returns the real part of the complex number.

    NON-MEMBER OPERATORS

      template<class T> complex<T>
      operator+(const complex<T>& lhs,const	complex<T>& rhs);
      template<class T> complex<T>
      operator+(const complex<T>& lhs, T rhs);

      template<class T> complex<T>
      operator+(T lhs, const complex<T>& rhs);
         Returns the sum of	lhs and	rhs.

      template<class T> complex<T>
      operator-(const complex<T>& lhs,const	complex<T>& rhs);
      template<class T> complex<T>
      operator-(const complex<T>& lhs, T rhs);
      operator-(T lhs, const complex<T>& rhs);
         Returns the difference of lhs and rhs.

      template<class T> complex<T>
      operator*(const complex<T>& lhs,const	complex<T>& rhs);
      template<class T> complex<T>
      operator*(const complex<T>& lhs, T rhs);
      template<class T> complex<T>
      operator* (T lhs, const complex<T>& rhs);
         Returns the product of lhs	and rhs.

      template<class T> complex<T>
      operator/(const complex<T>& lhs,const	complex<T>& rhs);
      template<class T> complex<T>
      operator/(const complex<T>& lhs, T rhs);
      template<class T> complex<T>
      operator/(T lhs, const complex<T>& rhs);
         Returns the quotient of lhs divided by rhs.

      template<class T> complex<T>
      operator+(const complex<T>& rhs);
         Returns rhs.

      template<class T> complex<T>
      operator-(const complex<T>& lhs);
         Returns complex<T>(-lhs.real(), -lhs.imag()).

      template<class T> bool
      operator==(const complex<T>& x, const	complex<T>& y);
         Returns true if the real and imaginary parts of x and y are equal.

      template<class T> bool
      operator==(const complex<T>& x, T y);
         Returns true if y is equal	to the real part of x and the imaginary
         part of x is equal to 0.

      template<class T> bool
      operator==(T x, const	complex<T>& y);
         Returns true if x is equal	to the real part of y and the imaginary
         part of	y is equal to 0.

      template<class T> bool
      operator!=(const complex<T>& x, const	complex<T>& y);
         Returns true if either the	real or	the imaginary part of x	and y
         are not equal.

      template<class T> bool
      operator!=(const complex<T>& x, T y);
         Returns true if y is not equal to the real	part of	x or the
         imaginary part of x is not equal to 0.

      template<class T> bool
      operator!=(T x, const	complex<T>& y);
         Returns true if x is not equal to the real	part of	y or the
         imaginary part of y is not equal to 0.

      template <class X> istream&
      operator>>(istream& is, complex<X>& x);
         Reads a complex number x into the input stream is.	 x may be of
         the form u,	(u), or	(u,v) where u is the real part and v is
         the  imaginary part. If	bad input is encountered, the
         ios::badbit flag is set.

      template <class X> ostream&
      operator<<(ostream& os, const	complex<X>& x);
         Returns os	<< "(" << x.real() << ","  << x.imag() << ")".

    NON-MEMBER FUNCTIONS

      template<class T> T
      abs(const complex<T>&	c);
         Returns the absolute value	or magnitude of	c (the square root
         of the norm).

      template<class T> complex<T>
      conj(const complex<T>& c);
         Returns the conjugate of c.

      template<class T> complex<T>
      cos(const complex<T>&	c);
         Returns the cosine	of c.

      template<class T> complex<T>
      cosh(const complex<T>& c);
         Returns the hyperbolic cosine of c.

      template<class T> complex<T>
      exp(const complex<T>&	x);
         Returns e raised to the x power.

      template<class T> T
      imag(const complex<T>& c) const;
         Returns the imaginary part	of c.

      template<class T> complex<T>
      log(const complex<T>&	x);
         Returns the natural logarithm of x. This function returns the
         complex value whose phase angle is	greater	than -pi and less
         than pi.

      template<class T> complex<T>
      log10(const complex<T>& x);
         Returns the logarithm base	10 of x.

      template<class T> T
      norm(const complex<T>& c);
         Returns the squared magnitude of c.  (The sum of the squares of
         the real and imaginary parts.)

      template<class T> complex<T>
      polar(const T& m, const T& a);
         Returns the complex value of a complex number whose magnitude
         is m and phase angle is a, measured in radians.

      template<class T> complex<T>
      pow(const complex<T>&	x, int y);
      template<class T> complex<T>
      pow(const complex<T>&	x, T y);
      template<class T> complex<T>
      pow(const complex<T>&	x, const complex<T>& y);
      template<class T> complex<T>
      pow(T	x, const complex<T>& y);
         Returns x raised to the y power.

      template<class T> T
      real(const complex<T>& c);
         Returns the real part of c.

      template<class T> complex<T>
      sin(const complex<T>&	c);
         Returns the sine of c.

      template<class T> complex<T>
      sinh(const complex<T>& c);
         Returns the hyperbolic sine of c.

      template<class T> complex<T>
      sqrt(const complex<T>& x);
         Returns the square	root of	x. This	function returns the complex
         value whose phase angle is greater than -pi/2 and less than or
         equal to

      template<class T> complex<T>
      tan(const complex<T>&	x);
         Returns the tangent of x.

      template<class T> complex<T>
      tanh(const complex<T>& x);
         Returns the hyperbolic tangent of x.

    EXAMPLE

      //
      // complex.cpp
      //
       #include <complex>
       #include <iostream.h>

      int main()
       {
        complex<double> a(1.2, 3.4);
        complex<double> b(-9.8, -7.6);

        a += b;
        a /= sin(b)	* cos(a);
        b *= log(a)	+ pow(b, a);

        cout << "a = " << a	<< ", b	= " << b << endl;

        return 0;
       }

      Output :
      a = (1.42804e-06,-0.0002873),	b = (58.2199,69.7354)

    WARNINGS

      On compilers that don't support member function templates, the
      arithmetic operators will not work on any arbitrary type.  (They
      will work only on float, double	and long doubles.)  You	also
      will only be able to perform binary arithmetic on types that are the
      same.

      Compilers that don't support non-converting constructors will	permit
      unsafe downcasts (i.e., long	double to double, double to float,
      long	double to float).

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

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

    NAME

      limits

      Refer	to the numeric_limits section of this reference	guide.

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee
- Additional Information on: numeric_limits

  ##

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

      NAME

        Containers  -	A standard template library (STL) collection.

      DESCRIPTION

        Within the standard template library,	collection classes are often
        described as containers.  A container	stores a collection of other
        objects and provides certain basic functionality that	supports the
        use of generic algorithms.  Containers come in two basic flavors:
        sequences, and associative containers.  They are further
        distinguished  by the type of iterator they support.

        A sequence supports a	linear arrangement of single elements. vector,
        list,deque, bitset, and string fall into this category.  Associative
        containers map values onto keys, which provides efficient retrieval
        of the values based on the keys.  The STL provides the map,
        multimap,  set and multiset associative containers. map and multimap
        store the  value and the key separately and allow for fast retrieval
        of the value, based upon fast retrieval of the key.	 set and
        multiset store	only keys  allowing fast retrieval of the key
        itself.

      CONTAINER REQUIREMENTS

        Containers within the	STL must meet the following requirements.
        Sequences and associative containers must also meet their own
        separate sets of requirements. The requirements for containers are:

        +	  A container allocates	all storage for	the objects it holds.

        +	  A container X	of objects of type T provides the following types:

             X::value_type    a T

             X::reference     lvalue of T

             X::const_reference const lvalue of T

             X::iterator    an iterator type pointing	to T.  X::iterator
                            cannot be an output iterator.

             X::const_iterator   an iterator type pointing to const T

             x::iterator cannot be an output iterator.

             X::difference_type    a signed integral type (must be the same as
                                   the distance type for X::iterator and
                                   X::const_iterator

             X::size_type    an unsigned integral type representing any non-
                             negative value of difference_type

             X::allocatr_type	  type of allocator used to obtain storage for
                                elements stored in the container

        +	  A container provides a default constructor, a	copy
                constructor, an assignment operator, and a full complement of
                comparison operators (==, !=,	<, >, <=, >=).

        +	  A container provides the following member functions:

                begin()  Returns an iterator or a const_iterator pointing
                         to the first element in  the collection.

                end()   Returns an iterator or a const_iterator pointing just
                        beyond the last element in the collection.

                swap(container) Swaps elements between this container and
                                the swap's argument.

                clear()  Deletes all the elements in the container.

                size()   Returns the number of elements in the collection
                         as a size_type.

                max_size()   Returns the largest possible number of elements
                             for this type of container as a size_type.

                empty()  Returns true if the container is empty, false
                         otherwise.

                get_allocator() Returns the allocator used by this container

      REVERSIBLE CONTAINERS

        A container may be reversible.  Essentially, a reversible container
        provides a reverse iterator that allows traversal of the collection
        in a direction opposite that of the default iterator.  A reversible
        container must meet the following requirements in addition to those
        listed above:

        +	  A reversible container provides the following	types:

                X::reverse_iterator    An iterator type pointing to T.

                X::const_reverse_iterator An iterator type pointing to
                                          const T

        +	  A reversible container provides the following	member functions:

                rbegin() Returns a reverse_iterator or a const_reverse_iterator
      		   pointing past the end of  the collection

                rend()   Returns a reverse_iterator or a const_reverse_iterator
                         pointing to the first element in the collection.

      SEQUENCES

        In addition to the requirements for containers, the following
        requirements hold for sequences:

        +	  iterator and const_iterator must be forward iterators,
                bidirectional iterators or random access iterators.

        +	  A sequence provides the following constructors:

             X(n, t)	 Constructs a container	with n copies of t.

             X(i, j)	 Constructs a container	with elements from the
                       range [i,j).

        +	  A sequence provides the following member functions:

             insert(p,t)   Inserts the element t in front of the position
                           identified	by the iterator	p.

             insert(p,n,t)   Inserts n copies	of  t in front of the position
                             identified by the iterator p.

             insert(p,i,j)   Inserts elements	from the range [i,j) in	front
                             of the position identified by the iterator p.

             erase(q)	  Erases the element pointed to	by the iterator	q.

             erase(q1,q2)   Erases the elements in the range [q1,q2).

        +	  A sequence may also provide the following member functions
                if they can be implemented with constant time complexity.

             front()	 Returns the element pointed to	by begin()

             back()	Returns	the element pointed to by end()

             push_front(x)   Inserts the element x at	begin()

             push_back(x)   Inserts the element x at end()

             pop_front()   Erases the	element	at begin()

             pop_back()   Erases the element at end()	-1

             operator[](n)   Returns the element at a.begin()	+ n

      ASSOCIATIVE CONTAINERS

        In addition to the requirements for a	container, the following
        requirements hold for associative containers:

        +	  For an associative container iterator	and const_iterator
                must be bidirectional iterators.  Associative containers
                are inherently sorted.  Their iterators proceed through
                the container in the nondescending order of keys (where
                non-descending order is defined by the comparison object
                that was used to construct the container).

        +	  An associative container provides the	following types:

             X::key_type    the type of the Key

             X::key_compare the type of the comparison to use to put
                            the keys in order

             X::value_compare	 the type of the comparison used on values

        +	  The default constructor and copy constructor for
                associative containers use the template parameter
                comparison class.

        +	  An associative container provides the	following
                additional constructors:

             X(c)   Construct	an empty container using c  as	the
                    comparison object

             X(i,j,c)	  Constructs a container with elements from the
                        range  [i,j) and the comparison object c.

             X(i, j)	 Constructs a container	with elements from the
                       range [i,j) using the template parameter comparison
                       object.

        +	  An associative container provides the	following member
                functions:

             key_comp()   Returns the	comparison object used in constructing
                          the associative container.

             value_comp() Returns the value	comparison object used in
                          constructing the associative container.

             insert(t)   Inserts t if	and only if there is no	element	in
                         the container with key equal to the	key of t.
                         Returns a pair<iterator,bool>.  The bool component
                         of the returned pair	indicates the success or
                         failure  of the operation and the iterator
                         component points  to the element with key equal
                         to key of t.

             insert(p,t) If the container does not support redundant key
                         values then this function only inserts t if	there
                         is no key present that is equal to the key of t.
                         If the container does support redundant keys then
                         this function always inserts the element t. The iterator
                         p serves as a hint of where to start searching, allowing
                         for some optimization of the insertion.  It does not
                         restrict the algorithm from inserting ahead of that
                         location if necessary.

             insert(i,j) Inserts elements from the range [i,j).

             erase(k)	   Erases all elements with key equal to k. Returns
                         number of erased elements.

             erase(q)	  Erases the element pointed to	by q.

             erase(q1,q2)   Erases the elements in the range [q1,q2).

             find(k)	 Returns an iterator pointing to an element with key
                       equal to k or end() if such an element is not found.

             count(k)	  Returns the number of	elements with key equal	to k.

             lower_bound(k)	Returns	an iterator pointing to	the first
                              element with a key greater than or equal to k.

             upper_bound(k)	Returns	an iterator pointing to	the first
                              element with a key less than or equal to k.

             equal_range(k)	Returns	a pair of iterators such that the
                              first element of the pair is equivalent to
                              lower_bound(k) and the second element equivalent
                              to upper_bound(k).

      SEE ALSO

        bitset, deque, list, map, multimap, multiset,	priority_queue,	queue,
        set, stack, vector

      STANDARDS CONFORMANCE
        ANSI X3J16/ISO WG21 Joint C++	Committee
- Additional Information on: Associative Containers Bitset deque list map multimap multiset priority_queue queue set Sequences stack vector

  ##

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

      NAME

        Algorithms  -	Generic	algorithms for performing various operations
        on	containers and sequences.

      SYNOPSIS

        #include <algorithm>

        The synopsis of each algorithm appears in its	entry in the reference
        guide.

      DESCRIPTION

        The Standard C++ Library provides a very flexible framework for
        applying generic algorithms to	containers.  The library also
        provides a rich set of these	algorithms for searching, sorting,
        merging, transforming, scanning, and much more.

        Each algorithm can be	applied	to a variety of	containers, including
        those defined by a user of the library.  The following design
        features make	algorithms generic:

        +	  Generic algorithms access the	collection through iterators

        +	  Algorithms are templatized on	iterator types

        +	  Each algorithm is designed to	require	the least number of
                services from the	iterators it uses

        In addition to requiring certain iterator capabilities, algorithms
        may require a container to be in a specific state.  For example,
        some algorithms can only work on previously sorted containers.

        Because most algorithms rely on iterators to gain access to data,
        they  can be grouped according to the type of iterator they require,
        as	is done	in the Algorithms by Iterator section below. They can
        also be grouped according to the type of operation they perform.

        ALGORITHMS BY	MUTATING/NON-MUTATING FUNCTION

        The broadest categorization groups algorithms	into two main types:
        mutating and non-mutating.	 Algorithms that alter (or mutate) the
        contents	of a container fall into the mutating group.  All
        others  are considered non-mutating.  For example, both fill and
        sort are  mutating algorithms, while find and for_each are
        non-mutating.

        Non-mutating operations

        accumulate	 find_end   max		   element
        adjacent_find	 find_first_of		   min
        binary_search	 find_if		   min_element
        count_min	 for_each		   mismatch
        count_if	 includes		   nth_element
        equal		 lexicographical_compare   search
        equal_range	 lower_bound		   search_n
        find		 max

        Mutating operations

        copy                 remove_if
        copy_backward        replace
        fill		       replace_copy
        fill_n               replace_copy_if
        generate             replace_if
        generate_n           reverse
        inplace_merge        reverse_copy
        iter_swap            rotate
        make_heap            rotate_copy
        merge                set_difference
        nth_element          set_symmetric_difference
        next_permutation     set_intersection
        partial_sort         set_union
        partial_sort_copy    sort
        partition            sort_heap
        prev_permutation     stable_partition
        push_heap            stable_sort
        pop_heap             swap
        random_shuffle       swap_ranges
        remove               transform
        remove_copy          unique
        remove_copy_if       unique_copy

        Note that the	library	provides both in place and copy	versions of
        many algorithms, such as replace and replace_copy.	 The library
        also provides versions of algorithms that allow the	use of default
        comparators and  comparators supplied by the user.  Often	these
        functions	are  overloaded,	but in some cases	(where
        overloading proved  impractical or impossible) the names	differ
        (e.g., replace, which will  use equality to determine replacement,
        and replace_if,	which  accesses a user provided compare
        function).

        ALGORITHMS BY	OPERATION

        We can further distinguish algorithms	by the kind of operations they
        perform.	 The following lists all algorithms by loosely
        grouping	them into similar operations.

        Initializing operations

        fill				 generate
        fill_n                         generate_n

        Search operations

        adjacent_find	       find_end		   search_n
        count		       find_if
        count_if             find_first_of
        find		       search

        Binary search	operations  (Elements must be sorted)

        binary_search			 lower_bound
        equal_range			 upper_bound

        Compare operations

        equal				 mismatch
        lexicographical_compare

        Copy operations

        copy				 copy_backward

        Transforming operations

        partition			 reverse
        random_shuffle		 reverse_copy
        replace			 rotate
        replace_copy                   rotate_copy
        replace_copy_if		 stable_partition
        replace_if			 transform

        Swap operations

        swap                           swap_ranges

        Scanning operations

        accumulate                     for_each

        Remove operations

        remove                         remove_if
        remove_copy                    unique
        remove_copy_if                 unique_copy

        Sorting operations

        nth_element			 sort
        partial_sort			 stable_sort
        partial_sort_copy

        Merge	operations  (Elements must be sorted)

        inplace_merge			 merge

        Set operations  (Elements must be sorted)

        includes                       set_symmetric_difference
        set_difference                 set_union
        set_intersection

        Heap operations

        make_heap                      push_heap
        pop_heap                       sort_heap

        Minimum and maximum

        max                            min
        max_element                    min_element

        Permutation generators

        next_permutation               prev_permutation

        ALGORITHMS BY	CATEGORY

        Each algorithm requires certain kinds	of iterators (for a
        description	of the iterators	and their capabilities see the
        Iterator	entry in this manual).  The	following set of lists
        groups the algorithms according to  the types	of iterators they
        require.

        Algorithms that use no iterators:

        max			 min		     swap

        Algorithms that require only input iterators:

        accumulate             find		     mismatch
        count                  find_if
        count_if               includes
        equal                  inner_product
        for_each               lexicographical_compare

        Algorithms that require only output iterators:

        fill_n		 generate_n

        Algorithms that read from input iterators and	write to output
        iterators:

        adjacent_difference	 replace_copy	     transform
        copy			 replace_copy_if     unique_copy
        merge			 set_difference
        partial_sum		 set_intersedtion
        remove_copy		 set_symmetric_difference
        remove_copy_if         set_union

        Algorithms that require forward iterators:

        adjacent_find	  iter_swap	replace_if
        binary_search	  lower_bound	rotate
        equal_range	  max_element	search
        fill		  min_element	search_n
        find_end	  remove	swap_ranges
        find_first_of	  remove_if	unique
        generate	  replace	upper_bound

        Algorithms that read from forward iterators and write	to output
        iterators:

        rotate_copy

        Algorithms that require bidirectional	iterators

        copy_backward		 partition
        inplace_merge		 prev_permutation
        next_permutation	 reverse
        stable_permutation

        Algorithms that read from bidirectional iterators and	write to output
        iterators:

        reverse_copy

        Algorithms that require random access	iterators:

        make_heap		 pop_heap	     sort
        nth_element		 push_heap	     sort_heap
        partial_sort		 random_shuffle	     stable_sort

        Algorithms that read from input iterators and	write to random	access
        iterators:

        partial_sort_copy

      COMPLEXITY

        The complexity for each of these algorithms is given in the manual
        page  for that algorithm.

      SEE ALSO

        Manual pages for each	of the algorithms named	in the lists above.

      STANDARDS CONFORMANCE
        ANSI X3J16/ISO WG21 Joint C++	Committee
- Additional Information on: accumulate adjacent_difference adjacent_find advance binary_search copy copy_backward count count_if compare distance distance_type equal equal_range equal_to fill fill_n find find_end find_first_of find_if for_each generate generate_n greater greater_equal Heap_Operations includes inner_product inplace_merge iter_swap lexicographical_compare lower_bound make_heap max max_element merge min min_element mismatch next_permutation nth_element partial_sort partial_sort_copy partial_sum partition permutation pop_heap prev_permutation push_heap random_shuffle remove remove_copy remove_copy_if remove_if replace replace_copy replace_copy_if replace_if reverse reverse_copy rotate rotate_copy search search_n set_difference set_intersection set_symmetric_difference set_union sort sort_heap stable_partition stable_sort swap swap_ranges transform uninitialized_copy uninitialized_fill uninitialized_fill_n unique unique_copy upper_bound

  ##

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

      NAME

        Iterators  - Pointer generalizations for traversal and modification
        of collections.

      DESCRIPTION

      	 Input Iterator		      Output Iterator
      	   read	only			write only
      	   forward moving		forward	moving
      	      |				     |
      	      |				     |
      	      --------------------------------
      			    |
      			    |
      		      Forward Iterator
      			read and write
      			forward	moving
      			    |
      			    |
      		      Bidirectional Iterator
      			read and write
      			moves forward or backward
      			    |
      			    |
      		      Random Access Iterator
      			read and write
      			random access

        Iterators are	a generalization of pointers that allow	a C++ program
        to uniformly interact with different data structures.  The
        illustration below displays the five iterator categories
        defined	by the standard	library, and shows	their
        hierarchical relationship.  Because standard library iterator
        categories are hierarchical, each category includes all the
        requirements of the categories above it.

        Because iterators are	used to	traverse and access containers,	the
        nature of the container	determines what	type of	iterator it
        generates.	And, because algorithms require specific iterator
        types as	arguments, it is iterators that,	for the	most
        part, determine which standard library algorithms can be used with
        which standard library containers.

        To conform to	the C++	standard, all container	and sequence classes
        must provide their	own iterators.	An instance of a container or
        sequence's iterator may be declared using either	of the
        following:

        class	name ::iterator
        class	name ::const_iterator

        Containers and sequences must	also provide const iterators to	the
        beginning and end of their collections.	 These may be accessed
        using the class members, begin() and end().

        The semantics	of iterators are a generalization of the semantics of
        C++ pointers.  Every template function that takes	iterators will
        work using C++ pointers for processing typed	contiguous memory
        sequences.

        Iterators may	be constant or mutable depending upon whether the
        result of the operator*	behaves	as a reference or  as a
        reference to a constant. Constant iterators cannot satisfy the
        requirements of	an output_iterator.

        Every	iterator type guarantees that there is an iterator value that
        points past the last	element	of a corresponding container. This
        value is called the past-the-end  value.  No guarantee is made that
        this value is dereferencable.

        Every	function provided by an	iterator is required to	be realized in
        amortized	constant time.

      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 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

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

        ++r	returns	X&

        r++	return value convertible to const X&

        *r++	 returns type T

        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.

      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.

      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.

      REQUIREMENTS FOR BIDIRECTIONAL ITERATORS

        A bidirectional iterator must	meet all the requirements for forward
        iterators.	 In addition, the following expressions	must be	valid:

        --r	returns	X&

        r--	return value convertible to const X&

        *r--	 returns T&

      REQUIREMENTS FOR RANDOM	ACCESS ITERATORS

        A random access iterator must	meet all the requirements for
        bidirectional iterators.  In addition, the following expressions
        must be valid:

        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)

        All relational operators return a value convertible to bool.

      STANDARDS CONFORMANCE
        ANSI X3J16/ISO WG21 Joint C++	Committee
- Additional Information on: iterator iterator_category iterator_traits back_inserter back_insert_iterator Bidirectional_Iterators Forward_Iterators front_inserter Input_Iterators inserter insert_iterator Insert_Iterators istream_iterator istreambuf_iterator ostream_iterator ostreambuf_iterator Output_Iterators Random_Access_Iterators raw_storage_iterator reverse_bidirectional_iterator reverse_iterator Stream_Iterators value_type

  ##

      Function_Objects
- Additional Information on: Function_Objects divides less less_equal logical_and logical_not logical_or minus modulus multiplies negate Negators not1 not2 not_equal_to plus Predicates times unary_function unary_negate binary_function binary_negate

  ##

      Adaptors
- Additional Information on: bind1st bind2nd binder1st binder2nd mem_fun mem_fun1 mem_fun_ref mem_fun_ref1

  ##

      Operators
- Additional Information on: Operators pair pointer_to_binary_function pointer_to_unary_function ptr_fun

  ##

  ##

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

      NAME

        allocator - The default allocator object for storage management in
        Standard Library containers.

      SYNOPSIS

        #include <memory>
        template <class T>
        class	allocator;

      DESCRIPTION

        Containers in	the Standard Library allow you control of storage
        management through the use of allocator objects.	 Each
        container	has an allocator template	parameter specifying
        the type of  allocator to be used.	Every constructor, except the
        copy constructor,  provides an allocator parameter, allowing you to
        pass in a specific  allocator.	 A container uses that
        allocator	for all	storage	management.

        The library provides a default allocator, called allocator.  This
        allocator uses the global new and delete operators.  By
        default,  all containers	use this allocator.  You can also
        design your own	allocator, but if you do so it must provide an
        appropriate  interface.  The standard interface is specified below.

      STANDARD INTERFACE

        template <class T>
        class	allocator {
         typedef size_t	     size_type;
         typedef ptrdiff_t	     difference_type;
         typedef T*		     pointer;
         typedef const T*	     const_pointer;
         typedef T&		     reference;
         typedef const T&	     const_reference;
         typedef T		     value_type;

         template <class U> struct rebind;
         allocator ()	throw();
         template <class U> allocator(const allocator<U>&) throw();
         template <class U>
           allocator&	operator=(const	allocator<U>&) throw();
          ~allocator () throw();
         pointer  address (reference)	const;
         const_pointer address (const_reference) const;
         pointer allocate (size_type,
            typename allocator<void> const_pointer = 0);
         void	deallocate(pointer);
         size_type max_size () const;
         void	construct (pointer, const T&);
         void	destroy	(pointer);
        };

        // specialize	for void:
         template <> class allocator<void> {
         public:
           typedef size_t	 size_type;
           typedef ptrdiff_t	 difference_type;
           typedef void*	 pointer;
           typedef const void* const_pointer;
            //  reference-to-void members are	impossible.
           typedef void  value_type;
           template <class U>
             struct rebind { typedef allocator<U> other; };

           allocator() throw();
           template <class U>
             allocator(const allocator<U>&) throw();
           template <class U>
             allocator operator=(const allocator<U>&)	throw();
           ~allocator() throw();

           pointer allocate(size_type, const void* hint);
           void deallocate(pointer p);
           size_type max_size() const	throw();
          };

        // globals
        template <class T>
         void* operator new(size_t N,	allocator<T>& a);
        template <class T, class U>
         bool	operator==(const allocator<T>&,
      		   const allocator<U>&)	throw();
        template <class T, class U>
         bool	operator!=(const allocator<T>&,
      		   const allocator<U>&)	throw();

      TYPES

        size_type
           Type used to hold the size	of an allocated	block of storage.

        difference_type
           Type used to hold values representing distances between storage
           addresses.

        pointer
           Type of pointer returned by allocator.

        const_pointer
           Const version of pointer.

        reference
           Type of reference to allocated objects.

        const_reference
           Const version of reference.

        value_type
           Type of allocated object.

        template <class U> struct rebind;
           Provides a	way to convert an allocator templated on one type to
           an	allocator templated on	another	type.  This struct contains a
           single type member:  typedef allocator<U> other.

      OPERATIONS

        allocator()
           Default constructor.

        template <class U>
        allocator(const allocator<U>&)
           Copy constructor.

        template <class U>
        allocator& operator=(const allocator<U>&) throw()>&)
           Assignment	operator.

        ~allocator()
           Destructor.

        pointer address(reference x) const;
           Returns the address of the	reference x as a pointer.

        const_pointer	address(const_reference	x) const;
           Returns the address of the	reference x as a const_pointer.

        pointer allocate(size_type n,
           typename allocator<void>::const_pointer p = 0)
           Allocates storage.  Returns a pointer to the first element in  a
           block of storage n*sizeof(T) bytes in	size.  The block  will
           be aligned appropriately for objects of type T.  Throws  the
           exception bad_alloc if the storage is unavailable.	This  function
           uses operator new(size_t).  The second parameter p  can be used
           by an allocator to localize memory	allocation,  but	the
           default allocator does not use it.

        void deallocate(pointer p)
           Deallocates the storage indicated by p.  The storage must have
           been obtained by a call	to allocate.

        size_type max_size ()	const;
           Returns the largest size for which	a call to allocate might
           succeed.

        void construct (pointer p, const T& val);
           Constructs	an object of type T2 with the initial value of val at
           the location specified	by p.  This function calls the
           placement new operator.

        void destroy (pointer	p)
           Calls the destructor on the object	pointed	to by p, but does not
           delete.

        See the container section of the Class Reference for a further
        description of how to use	the alternate allocator	within a
        user-defined container.

      SEE ALSO

        container

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

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

      NAME

        get_temporary_buffer	- Pointer based	primitive for handling memory

      SYNOPSIS

        #include <memory>

        template <class T>
        pair<T*, ptrdiff_t> get_temporary_buffer (ptrdiff_t, T*);

      DESCRIPTION

        The get_temporary_buffer templated function reserves from system
        memory the largest possible buffer that is less than or equal to
        the size requested (n*sizeof(T)), and returns a pair<T*,
        ptrdiff_t>  containing the address and size of that buffer.	The
        units used  to describe the capacity	are in sizeof(T).

      SEE ALSO

        allocate, construct, deallocate, pair, return_temporary_buffer.

      STANDARDS CONFORMANCE
        ANSI X3J16/ISO WG21 Joint C++	Committee
- Additional Information on: return_temporary_buffer

  ##

  ##

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

      NAME

        auto_ptr_  - A simple, smart pointer class.

      SYNOPSIS

        #include <memory>
        template <class X> class auto_ptr;

      DESCRIPTION

        The template class auto_ptr holds onto a pointer obtained via	new
        and deletes that object when the auto_ptr	object itself is
        destroyed (such  as when leaving block scope).  auto_ptr can be used
        to make calls to operator new exception-safe.  The auto_ptr class
        provides semantics  of	strict ownership:	 an object may
        be safely pointed to by only one	auto_ptr, so copying an
        auto_ptr copies the pointer and  transfers ownership to the
        destination if the source	had already had	ownership.

      INTERFACE

        template <class X> class auto_ptr {

          public:

             // constructor/copy/destroy

            explicit auto_ptr	(X* = 0) throw();
            template <class Y>
      	auto_ptr (const	auto_ptr<Y>&) throw();
            template <class Y>
      	void operator= (const auto_ptr<Y>&) throw();
             ~auto_ptr ();

             // members

            X& operator* () const throw();
            X* operator-> () const throw();
            X* get ()	const throw();
            X* release () throw();
         };

      CONSTRUCTORS AND DESTRUCTORS

        explicit
        auto_ptr (X* p = 0);
           Constructs	an object of class auto_ptr<X>,	initializing the  held
           pointer to	p, and acquiring ownership of that pointer.   Requires
           that p points to	an object of class X or	a class	derived	from X
           for which delete	p is defined and accessible, or	that p  is a
           null pointer.

        template <class Y> auto_ptr (const auto_ptr<Y>& a);
           Copy constructor. Constructs an object of class auto_ptr<X>, and
           copies the argument a to *this.  If a owned the underlying
           pointer  then *this becomes the new owner of that pointer.

        ~auto_ptr ();
           Deletes the underlying pointer.

      OPERATORS

        template <class Y>
        void operator= (const	auto_ptr<Y>& a);
           Assignment	operator.  Copies the argument a to *this.  If	*this
           becomes the new owner of the underlying pointer. If a owned the
           underlying pointer then *this	becomes	the new	owner of that
           pointer. If *this already owned a pointer, then that	pointer
           is deleted first.

        X&
        operator* () const;
           Returns a	reference to the object	to which the  underlying
           pointer points.

        X*
        operator-> ()	const;
           Returns the underlying pointer.

      MEMBER FUNCTIONS

        X*
        get () const;
           Returns the underlying pointer.

        X*
        release();
           Releases ownership	of the underlying pointer.  Returns that
           pointer.

      EXAMPLE

           //
           //	auto_ptr.cpp
           //
           #include <iostream.h>
           #include <memory>

           //
           //	A simple structure.
           //
          struct X
           {
      	X (int i = 0) :	m_i(i) { }
      	int get() const	{ return m_i; }
      	int m_i;
           };

          int	main ()
           {
      	//
      	// b will hold a pointer to an X.
      	//
             auto_ptr<X> b(new X(12345));
      	//
      	// a will now be the owner of the underlying pointer.
      	//
             auto_ptr<X> a = b;
      	//
      	// Output the value contained by the underlying	pointer.
      	//
             cout << a->get()	<< endl;
      	//
      	// The pointer will be deleted when a is destroyed on
      	// leaving scope.
      	//
             return 0;
           }

        Output :
        12345

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

      Runtime_Support
- Additional Information on: new new_handler delete bad_alloc type_info bad_cast bad_exception bad_typeid exception nothrow terminate_handler unexpected_handler

  ##

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

        NAME

        basic_string,string  - A templated class for handling	sequences of
        character-like entities.  string and wstring are specialized
        versions	of basic_string for chars and wchar_ts, respectively.

        This page describes the ANSI basic_string class.  If you would like
        information on the	pre-ANSI string	class, use the command:

             help cxxl

        typedef basic_string <char> string;
        typedef basic_string <wchar_t> wstring;

      SYNOPSIS

        #include <string>

        template <class charT,
      	   class traits	= char_traits<charT>,
      	   class Allocator = allocator<charT> >

        class	basic_string;

      DESCRIPTION

        basic_string<charT, traits, Allocator> is a homogeneous collection
        of character-like entities.  It provides	general	string
        functionality  such as compare, append, assign, insert, remove, and
        replace , along  with various searches.  basic_string also functions
        as an STL sequence  container, providing random	access
        iterators.  This	allows some of the generic algorithms to apply
        to strings.

        Any underlying character-like	type may be used as long as an
        appropriate string_char_traits class is provided or the default
        traits class is applicable.

      INTERFACE

        template <class charT,
      	   class traits	= char_traits<charT>,
      	   class Allocator = allocator<charT> >
        class	basic_string {

        public:

        // Types

        typedef traits			       traits_type;
        typedef typename traits::char_type	       value_type;
        typedef Allocator			       allocator_type;

        typename size_type;
        typename difference_type;
        typename reference;
        typename const_reference;
        typename pointer;
        typename const_pointer;
        typename iterator;
        typename const_iterator;
        typename const_reverse_iterator;
        typename reverse_iterator;

        static const size_type npos =	-1;

        // Constructors/Destructors

        explicit basic_string(const Allocator& = Allocator());
        basic_string (const basic_string<charT, traits, Allocator>&);
        basic_string(const basic_string&, size_type, size_type = npos);
        basic_string(const charT*, size_type,
      	      const Allocator& = Allocator());
        basic_string(const charT*, Allocator&	= Allocator());
        basic_string(size_type, charT,
      	      const Allocator& = Allocator());
        template <class InputIterator>
        basic_string(InputIterator, InputIterator,
      	      const Allocator& = Allocator());
        ~basic_string();

        // Assignment	operators
        basic_string&	operator=(const	basic_string&);
        basic_string&	operator=(const	charT*);
        basic_string&	operator=(charT);

        // Iterators

        iterator	 begin();
        const_iterator begin() const;
        iterator	 end();
        const_iterator end() const;

        reverse_iterator	 rbegin();
        const_reverse_iterator rbegin() const;
        reverse_iterator	 rend();
        const_reverse_iterator rend()	const;

        // Capacity

          size_type	    size() const;
          size_type	    length() const;
          size_type	    max_size() const;
          void	    resize(size_type, charT);
          void	    resize(size_type);
          size_type	    capacity() const;
          void	    reserve(size_type);
          bool	    empty() const;

        // Element access

          const_reference operator[](size_type) const;
          reference	    operator[](size_type);
          const_reference at(size_type) const;
          reference	    at(size_type);

        // Modifiers

          basic_string& operator+=(const basic_string&);
          basic_string& operator+=(const charT*);
          basic_string& operator+=(charT);

          basic_string& append(const basic_string&);
          basic_string& append(const basic_string&,
      			 size_type, size_type);
          basic_string& append(const charT*, size_type);
          basic_string& append(const charT*);
          basic_string& append(size_type, charT);
          template<class InputIterator>
           basic_string& append(InputIterator, InputIterator);

          basic_string& assign(const basic_string&);
          basic_string& assign(const basic_string&,
      			 size_type, size_type);
          basic_string& assign(const charT*, size_type);
          basic_string& assign(const charT*);
          basic_string& assign(size_type, charT);
          template<class InputIterator>
           basic_string& assign(InputIterator, InputIterator);

          basic_string& insert(size_type, const basic_string&);
          basic_string& insert(size_type, const basic_string&,
      			 size_type, size_type);
          basic_string& insert(size_type, const charT*, size_type);
          basic_string& insert(size_type, const charT*);
          basic_string& insert(size_type, size_type, charT);
          iterator insert(iterator, charT = charT());
          void insert(iterator, size_type, charT);
          template<class InputIterator>
           void insert(iterator, InputIterator,
      		InputIterator);

          basic_string& erase(size_type = 0, size_type= npos);
          iterator erase(iterator);
          iterator erase(iterator, iterator);

          basic_string& replace(size_type, size_type,
      			  const	basic_string&);
          basic_string& replace(size_type, size_type,
      			  const	basic_string&,
      			  size_type, size_type);
          basic_string& replace(size_type, size_type,
      			  const	charT*,	size_type);
          basic_string& replace(size_type, size_type,
      			  const	charT*);
          basic_string& replace(size_type, size_type,
      			  size_type, charT);
          basic_string& replace(iterator, iterator,
      			  const	basic_string&);
          basic_string& replace(iterator, iterator,
      			  const	charT*,	size_type);
          basic_string& replace(iterator, iterator,
      			  const	charT*);
          basic_string& replace(iterator, iterator,
      			  size_type, charT);
          template<class InputIterator>
           basic_string& replace(iterator, iterator,
      			  InputIterator, InputIterator);

          size_type copy(charT*, size_type, size_type	= 0);
          void swap(basic_string<charT, traits, Allocator>&);

        // String operations

          const charT* c_str() const;
          const charT* data()	const;
          const allocator_type& get_allocator() const;

          size_type find(const basic_string&,
      		   size_type = 0) const;
          size_type find(const charT*,
      		   size_type, size_type) const;
          size_type find(const charT*, size_type = 0)	const;
          size_type find(charT, size_type = 0) const;
          size_type rfind(const basic_string&,
      		    size_type =	npos) const;
          size_type rfind(const charT*,
      		    size_type, size_type) const;
          size_type rfind(const charT*,
      		    size_type =	npos) const;
          size_type rfind(charT, size_type = npos) const;

          size_type find_first_of(const basic_string&,
      			    size_type =	0) const;
          size_type find_first_of(const charT*,
      			    size_type, size_type) const;
          size_type find_first_of(const charT*,
      			    size_type =	0) const;
          size_type find_first_of(charT, size_type = 0) const;

          size_type find_last_of(const basic_string&,
      			   size_type = npos) const;
          size_type find_last_of(const charT*,
      			   size_type, size_type) const;
          size_type find_last_of(const charT*, size_type = npos) const;
          size_type find_last_of(charT, size_type = npos) const;

          size_type find_first_not_of(const basic_string&,
      				size_type = 0) const;
          size_type find_first_not_of(const charT*,
      				size_type, size_type) const;
          size_type find_first_not_of(const charT*, size_type	= 0) const;
          size_type find_first_not_of(charT, size_type = 0) const;

          size_type find_last_not_of(const basic_string&,
      			       size_type = npos) const;
          size_type find_last_not_of(const charT*,
      			       size_type, size_type) const;
          size_type find_last_not_of(const charT*,
      			       size_type = npos) const;
          size_type find_last_not_of(charT, size_type	= npos)	const;

          basic_string substr(size_type = 0, size_type = npos) const;
          int	compare(const basic_string&) const;
          int	compare(size_type, size_type, const basic_string&) const;
          int	compare(size_type, size_type, const basic_string&,
      		size_type, size_type) const;
          int	compare(size_type, size_type, charT*) const;
          int	compare(charT*)	const;
          int	compare(size_type, size_type, const charT*, size_type) const;
        };

        // Non-member	Operators

        template <class charT, class traits, class Allocator>
        basic_string operator+ (const	basic_string&,
      			  const	basic_string&);
        template <class charT, class traits, class Allocator>
        basic_string operator+ (const	charT*,	const basic_string&);
        template <class charT, class traits, class Allocator>
        basic_string operator+ (charT, const basic_string&);
        template <class charT, class traits, class Allocator>
        basic_string operator+ (const	basic_string&, const charT*);
        template <class charT, class traits, class Allocator>
        basic_string operator+ (const	basic_string&, charT);

        template <class charT, class traits, class Allocator>
        bool operator== (const basic_string&,	const basic_string&);
        template <class charT, class traits, class Allocator>
        bool operator== (const charT*, const basic_string&);
        template <class charT, class traits ,	class Allocator>
        bool operator== (const basic_string&,	const charT*);

        template <class charT, class traits, class Allocator>
        bool operator< (const	basic_string&, const basic_string&);
        template <class charT, class traits, class Allocator>
        bool operator< (const	charT*,	const basic_string&);
        template <class charT, class traits, class Allocator>
        bool operator< (const	basic_string&, const charT*);

        template <class charT, class traits, class Allocator>
        bool operator!= (const basic_string&,	const basic_string&);
        template <class charT, class traits, class Allocator>
        bool operator!= (const charT*, const basic_string&);
        template <class charT, class traits, class Allocator>
        bool operator!= (const basic_string&,	const charT*);

        template <class charT, class traits, class Allocator>
        bool operator> (const	basic_&, const basic_string&);
        template <class charT, class traits, class Allocator>
        bool operator> (const	charT*,	const basic_string&);
        template <class charT, class traits, class Allocator>
        bool operator> (const	basic_string&, const charT*);

        template <class charT, class traits, class Allocator>
        bool operator<= (const basic_string&,	const basic_string&);
        template <class charT, class traits, class Allocator>
        bool operator<= (const charT*, const basic_string&);
        template <class charT, class traits, class Allocator>
        bool operator<= (const basic_string&,	const charT*);

        template <class charT, class traits, class Allocator>
        bool operator>= (const basic_string&,	const basic_string&);
        template <class charT, class traits, class Allocator>
        bool operator>= (const charT*, const basic_string&);
        template <class charT, class traits, class Allocator>
        bool operator>= (const basic_string&,	const charT*);

        template <class charT, class traits, class Allocator>
        void swap(basic_string<charT,traits,Allocator>& a,
      	   basic_string<charT,traits,Allocator>& b);

        template<class charT,	class traits, class Allocator>
        istream& operator>> (istream&, basic_string&);
        template <class charT, class traits, class Allocator>
        ostream& operator<< (ostream&, const basic_string&);
        template <class Stream, class	charT,
      	   class traits, class Allocator>
        Stream& getline (Stream&, basic_string&, charT);

      CONSTRUCTORS AND DESTRUCTORS

        In all cases,	the Allocator parameter	will be	used for storage
        management.

        explicit
        basic_string (const Allocator& a = Allocator());
           The default constructor.  Creates a basic_string with the following
           effects:

           data()   a	non-null pointer that is copyable and can have 0 added
           to it

           size()   0

           capacity()	  an unspecified value

        basic_string (const basic_string<T, traits, Allocator>& str);
           Copy constructor. Creates a string	that is	a copy of str.

        basic_string (const basic_string &str, size_type pos,
      	       size_type n= npos);
      		  Creates a string if pos<=size() and determines length
                        rlen of initial string value as the smaller of n and
                        str.size() - pos. This has the following	effects:

      		  data()   points at the first element of an allocated
                                 copy of rlen elements of the string controlled
                                 by	str beginning at	position pos

      		  size()   rlen

      		  capacity()   a value at least	as large as size()

      		  get_allocator()   str.get_allocator()

      		  An out_of_range exception will be thrown if
                        pos>str.size().

        basic_string (const charT* s,	size_type n,
      	       const Allocator&	a = Allocator());
      		  Creates a string that	contains the first n characters
                        of s. s must not be	a NULL pointer.	 The effects of
                        this constructor are:

      		  data()   points at the first element of an allocated
                                 copy of the array	whose first element is
                                 pointed at by s

      		  size()   n

      		  capacity()   a value at least	as large as size()

      		  An out_of_range exception will be thrown if n	== npos.

        basic_string (const charT * s,
      	       const Allocator&	a = Allocator());
      		  Constructs a string containing all characters	in s up
                        to, but not including, a traits::eos() character.
                        s must not be a null pointer. The effects of this
                        constructor are:

      		  data()   points at the first element of an allocated
                                 copy of the array	whose first element is
                                 pointed at by s

      		  size()   traits::length(s)

      		  capacity()   a value at least	as large as size()

        basic_string (size_type n, charT c,
      	       const Allocator&	a  = Allocator());
      		  Constructs a string containing n repetitions of c.  A
      		  length_error exception is thrown if n	== npos.  The
                        effects of this constructor are:

      		  data()   points at the first element of an allocated
                                 array of n	elements, each storing the
                                 initial value c

      		  size()   n

      		  capacity()   a value at least	as large as size()

        template <class InputIterator>
        basic_string	(InputIterator first, InputIterator last,
      		const Allocator& a = Allocator());
      		   Creates a basic_string of length last - first,
                         filled with all values obtained by dereferencing
                         the InputIterators on the range [first, last).
                         The	effects	of this	constructor are:

      		   data()   points at the first	element	of an allocated
                                  copy of the elements in the range
                                  [first,last)

      		   size()   distance between first and last

      		   capacity()	a value	at least as large as size()

        ~basic_string	();
           Releases any allocated memory for this basic_string.

      OPERATORS

        basic_string&
        operator= (const basic_string& str);
           Assignment	operator. Sets the contents of this string to be the
           same as str.  The effects of operator= are:

           data()   points at	the first element of an	allocated copy of
                    the array whose first element is pointed at
                    by str.size()

           size()   str.size()

           capacity()	  a value at least as large as size()

        basic_string&
        operator= (const charT * s);
           Assignment	operator. Sets the contents of this string to be the
           same as s up to, but not including, the traits::eos() character.

        basic_string&
        operator= (charT c);
           Assignment	operator. Sets the contents of this string to be equal
           to the single charT c.

        const_reference
        operator[] (size_type	pos) const;
        reference
        operator[] (size_type	pos);
           If	pos < size(), returns the element at position pos in this
           string. If	pos == size(),	the const version returns traits::eos(),
           the behavior of	the non-const version is undefined.  The
           reference returned by either version is	invalidated by any
           call	to c_str(), data(), or any non-const member function
           for the object.

        basic_string&
        operator+= (const basic_string& s);
        basic_string&
        operator+= (const charT* s);
        basic_string&
        operator+= (charT c);
           Concatenates a string onto	the current contents of	this string.
           The second member operator uses traits::length() to determine the
           number of elements from s to	add.  The third	member operator
           adds the single	character c.  All return a reference to this
           string after completion.

      ITERATORS

        iterator begin ();
        const_iterator begin () const;
           Return an iterator	initialized to the first element of the	string.

        iterator end ();
        const_iterator end ()	const;
           Return an iterator	initialized to the position after the last
           element of the string.

        reverse_iterator rbegin ();
        const_reverse_iterator rbegin	() const;
           Returns an	iterator equivalent to reverse_iterator(end()).

        reverse_iterator rend	();
        const_reverse_iterator rend () const;
           Returns an	iterator equivalent to reverse_iterator(begin()).

      ALLOCATOR

        const	allocator_type get_allocator ()	const;
           Returns a copy of the allocator used by self for storage management.

      MEMBER FUNCTIONS

        basic_string&
        append (const	basic_string& s, size_type pos,	size_type npos);
        basic_string&
        append (const	basic_string& s);
        basic_string&
        append (const	charT* s, size_type n);
        basic_string&
        append (const	charT* s);
        basic_string&
        append (size_type n, charT c );
        template<class InputIterator>
        basic_string&
        append (InputIterator	first, InputIterator last);
           Append another string to the end of this string.  The first two
           functions append the lesser of n and s.size() - pos characters of s,
           beginning at position pos to this string.	 The second member will
           throw an	out_of_range exception if pos >	str.size().  The third
           member appends n characters of the array pointed to by s.	 The
           fourth variation appends elements from the array pointed to
           by s up	to, but	not including, a traits::eos() character.
           The fifth variation appends n repetitions of c.	 The final
           append function appends the elements	specified in the
           range [first, last).

           All functions will	throw a	length_error exception if the
           resulting length will exceed	max_size().  All return	a
           reference to this string after completion.

        basic_string&
        assign (const	basic_string& s);
        basic_string&
        assign (const	 basic_string& s,
      	size_type pos, size_type n);
        basic_string&
        assign (const	charT* s, size_type n);
        basic_string&
        assign (const	charT* s);
        basic_string&
        assign (size_type n, charT c );
        template<class InputIterator>
        basic_string&
        assign (InputIterator	first, InputIterator last);

           Replace the value of this string with the value of	another.

           All versions of the function assign values	to this	string.	 The
           first two variations assign the lesser of n and s.size()	- pos
           characters of s,	beginning at position pos.  The	second
           variation  throws	an out_of_range exception if pos > str.size().
           The third  version of the function assigns n	characters of
           the array	pointed	to by s.  The fourth version assigns elements
           from the array pointed  to	by s up	to, but	not including,	a
           traits::eos()	character.   The	fifth assigns one or n
           repetitions of c.	The last  variation assigns the members
           specified by the range [first, last).

           All functions will	throw a	length_error  exception	if the
           resulting length will exceed	max_size(). All	return a
           reference to this string after completion.

        const_reference
        at (size_type	pos) const;
        reference
        at (size_type	pos);
           If	pos < size(), returns the element at position pos in this
           string. Otherwise,	an out_of_range	exception is thrown.

        size_type
        capacity () const;
           Returns the current storage capacity of the string. This is
           guaranteed  to	be at least as large as	size().

        int
        compare (const basic_string& str);
           Returns the result	of a lexicographical comparison	between
           elements of this string and elements of str.  The return value
           is:

           <0	    if size() <	str.size()
           0	    if size() == str.size()
           >0	    if size() >	str.size()

        int
        compare (size_type pos1, size_type n1,
      	  const	basic_string& str) const;
        int
        compare (size_type pos1, size_type n1, const basic_string& str,
      	  size_type pos2, size_type n2)	const;
        int
        compare (charT* s) const;
        int
        compare (size_type pos, size_type n1,	charT* s) const;
        int
        compare (size_type pos, size_type n1,	charT* s,
      	  size_type n2)	const;
           Return the	result of a lexicographical comparison between
           elements of this string and a	given comparison string.  The
           members return, respectively:

      	  compare (str)
      	  compare (basic_string	(str, pos2, n2))
      	  compare (basic_string(s))
      	  compare (basic_string(s, npos))
      	  compare (basic_string	(s,n2))

        size_type
        copy (charT* s, size_type n,	size_type pos =	0) const;
           Replaces elements in memory with copies of	elements from this
           string. An	out_of_range exception will be thrown if pos > size().
           The lesser of n and size() - pos	 elements of this string,
           starting at position pos are copied	into the array pointed
           to by s.	 No terminating	null is appended to s.

        const	charT*
        c_str	() const;
        const	charT*
        data () const;
           Return a pointer to the initial element of	an array whose first
           size() elements are copies of the	elements in this string.
           A traits::eos() element is	appended to the	end.  The elements of
           the array	may not	be altered, and the returned pointer is only
           valid until a non-const member function of this string is	called.
           If size() is zero, the data() function returns a NULL pointer.

        bool empty ()	const;
           Returns size() == 0.

        basic_string&
        erase	(size_type pos = 0, size_type n	= npos);
        iterator
        erase	(iterator p);
        iterator
        erase	(iterator first, iterator last);
           This function removes elements from the string, collapsing
           the remaining elements, as necessary, to	remove any space
           left empty.  The first	version of the function removes the
           smaller of n and size() -	pos  starting at	position pos.
           An out_of_range exception will be thrown	if  pos	>
           size().  The  second version requires  that p is a	valid
           iterator on this string, and removes the character referred to
           by p. The last version of erase requires that both first and
           last are valid iterators on this string, and removes the
           characters defined by	the range [first,last).  The destructors
           for all removed characters	are called.   All versions of erase
           return a	reference to this string after completion.

        size_type
        find (const basic_string& str, size_type pos = 0) const;
           Searches for the first occurrence of the substring	specified by
           str in this string, starting at position pos.  If	found, it
           returns  the index of	the first character of the matching
           substring.	If not found, returns npos. Equality is defined by
           traits::eq().

        size_type
        find (const charT* s,	size_type pos, size_type n) const;
        size_type
        find (const charT* s,	size_type pos =	0) const;
        size_type
        find (charT c, size_type pos = 0) const;
           Search for	the first sequence of characters in this string	that
           match a specified string.	The variations of this function
           return,	respectively:

           find(basic_string(s,n), pos)
           find(basic_string(s), pos)
           find(basic_string(1, c), pos)

        size_type
        find_first_not_of (const basic_string& str,
      		    size_type pos = 0) const
           Searches	for the	first element of this string  at	or
           after position pos that is not  equal to any element of str.  If
           found, find_first_not_of returns the index of the non-matching
           character. If all of the  characters match, the function returns
           npos.   Equality is defined by traits::eq().

        size_type
        find_first_not_of  (const charT* s,
      		     size_type pos, size_type n) const;
        size_type
        find_first_not_of (const charT* s,
      		    size_type pos = 0) const;
        size_type
        find_first_not_of (charT c, size_type	pos = 0) const;
           Search for	the first element in this string at or after position
           pos that is not equal to any element of a given set of
           characters.  The members return, respectively:

           find_first_not_of(basic_string(s,n), pos)
           find_first_not_of(basic_string(s),	pos)
           find_first_not_of(basic_string(1, c), pos)

        size_type
        find_first_of(const basic_string& str,
      	       size_type pos = 0) const;
           Searches for the first occurrence at or after	position pos
           of any element of str	in this	string.	  If found, the index
           of this matching character is returned.  If not found, npos is
           returned.  Equality is defined by traits::eq().

        size_type
        find_first_of(const charT*  s,  size_type  pos,
      	       size_type n) const;
        size_type
        find_first_of(const charT* s,	size_type pos =	0) const;
        size_type
        find_first_of	(charT c, size_type pos	= 0) const;
           Search for	the first occurrence in	this  string of	any element in
           a specified string.	The find_first_of variations return,
           respectively:

           find_first_of(basic_string(s,n), pos)
           find_first_of(basic_string(s), pos)
           find_first_of(basic_string(1, c), pos)

        size_type
        find_last_not_of(const basic_string& str,
      		  size_type pos	= npos)	const;
           Searches for the last element of this string at or before
           position pos that is not equal to any  element of str.  If
           find_last_not_of finds a  non-matching element, it	returns	the
           index of  the character.  If	all the	elements match, the
           function returns npos.  Equality is defined by	traits::eq().

        size_type
        find_last_not_of(const charT*	s,
      		  size_type pos, size_type n) const;
        size_type
        find_last_not_of(const charT*	s, size_type pos = npos) const;
        size_type
        find_last_not_of(charT c, size_type pos = npos) const;
           Search for	the last element in this string	at or  before position
           pos that is not equal to any element of a given set of
           characters.  The members return, respectively:

           find_last_not_of(basic_string(s,n), pos)
           find_last_not_of(basic_string(s), pos)
           find_last_not_of(basic_string(1, c), pos)

        size_type
        find_last_of(const basic_string& str,
      	      size_type	pos = npos) const;
           Searches for the last occurrence of any element of  str	at or
           before	position pos in	this string.   If found,
           find_last_of returns the index of the  matching character.  If
           not found find_last_of returns  npos.  Equality is defined by
           traits::eq().

        size_type
        find_last_of(const charT* s, size_type pos,
      	      size_type	n) const;
        size_type
        find_last_of(const charT* s, size_type pos = npos) const;
        size_type
        find_last_of(charT c,	size_type pos =	npos) const;
           Search for	the last occurrence in this string of any element
           in a specified string.  The members return, respectively:

           find_last_of(basic_string(s,n), pos)
           find_last_of(basic_string(s), pos)
           find_last_of(basic_string(1, c), pos)

        basic_string&
        insert(size_type pos1, const basic_string& s);
        basic_string&
        insert(size_type pos,	const  basic_string& s,
      	size_type pos2 = 0, size_type n	= npos);
        basic_string&
        insert(size_type pos,	const charT* s,	size_type n);
        basic_string&
        insert(size_type pos,	const charT* s);
        basic_string&
        insert(size_type pos,	size_type n, charT c);
           Insert additional elements	at position pos	in this	string.	 All
           of	the variants of this function will throw an out_of_range
           exception if pos >  size().  All variants will	also throw a
           length_error if the resulting string will exceed	max_size().
           Elements of this string will be moved apart as necessary	to
           accommodate the inserted elements.  All return a reference to this
           string after completion.

           The second	variation of this function inserts the lesser of n and
           s.size() -	pos2 characters	of s, beginning	at position pos2 in
           this string.  This version will	throw an out_of_range
           exception	if   pos2  > s.size().	The third version inserts n
           characters of the  array pointed to	by s.  The fourth
           inserts elements from	the  array pointed to by	s up
           to, but not including,  a traits::eos()  character.
           Finally, the fifth variation inserts n repetitions of	c.

        iterator
        insert(iterator p, charT c = charT());
        void
        insert(iterator p, size_type n, charT	c);
        template<class InputIterator>
        void
        insert(iterator p, InputIterator first, InputIterator	last);
           Insert additional elements	in this	 string	 immediately before
           the	character referred to by p.  All of these versions of
           insert require that p is	a valid	iterator on this string.  The
           first version inserts a copy of c.	 The second version inserts n
           repetitions of c.	 The third version
           inserts characters	in the range [first, last).  The first version
           returns p.

        size_type
        length() const;
           Return the	number of elements contained in	this string.

        size_type
        max_size() const;
           Returns the maximum possible size of the string.

        size_type
        rfind	(const basic_string& str, size_type pos	 = npos) const;
           Searches for the last occurrence of the substring	specified by
           str in this string, starting at position pos. Note that only the
           first character of the	substring must be <= pos; the
           remaining	characters may extend beyond pos. If found, the index
           of	the first  character of that matches substring is returned.
           If	not  found, npos	is returned.  Equality is defined by
           traits::eq().

        size_type
        rfind(const charT* s,	size_type pos,	size_type n) const;
        size_type
        rfind(const charT* s,	size_type pos =	npos) const;
        size_type
        rfind(charT c, size_type pos = npos) const;
           Searches for the last sequence of characters in this string
           matching a specified string.	The rfind variations return,
           respectively:

           rfind(basic_string(s,n), pos)
           rfind(basic_string(s), pos)
           rfind(basic_string(1, c), pos)

        basic_string&
        replace(size_type pos, size_type n1, const basic_string& s);
        basic_string&
        replace(size_type pos1, size_type n1,	const basic_string& str,
      	 size_type pos2, size_type n2);
        basic_string&
        replace(size_type pos, size_type n1, const charT* s,
      	 size_type n2);
        basic_string&
        replace(size_type pos, size_type n1, const charT* s);
        basic_string&
        replace(size_type pos, size_type n1, size_type n2, charT c);
           The replace function replaces selected elements of	this string
           with an alternate set of elements.	 All of	these versions insert
           the new elements in place of n1 elements in this string, starting
           at position	pos.  They each throw an	out_of_range
           exception if pos1 > size()and a length_error exception if the
           resulting string size exceeds max_size().

        The second	version	replaces elements of the original string with
        n2 characters	from string s starting at position pos2.  It  will
        throw	the out_of_range exception if pos2 > s.size().	 The  third
        variation of	the function replaces elements	in the original	string
        with n2 elements	from the array pointed to by s.	 The fourth
        version replaces elements in the string with elements from  the
        array pointed to by s, up to, but not including,	a
        traits::eos()	character.  The	fifth replaces n elements with n2
        repetitions of character c.

        basic_string&
        replace(iterator i1, iterator	i2,
      	 const basic_string& str);
        basic_string&
        replace(iterator i1, iterator	i2, const charT* s,
      	 size_type n);
        basic_string&
        replace(iterator i1, iterator	i2, const charT* s);
        basic_string&
        replace(iterator i1, iterator	i2, size_type n,
      	 charT c);
        template<class InputIterator>
        basic_string&
        replace(iterator  i1,	 iterator  i2,
      	 InputIterator j1, InputIterator j2);
           Replace selected elements of this string with an  alternative set
           of elements.  All of these versions	of  replace require
           iterators i1 and i2 to be valid iterators on this string.  The
           elements specified by the range [i1,i2)  are	replaced by
           the	new elements.

           The	first version shown here replaces with all members in
           str. The	second version starts at position i1, and  replaces
           the next n characters with n	characters of  the array
           pointed	to by s.  The third variation replaces  string
           elements with elements from	the array pointed to by	s up
           to, but not including, a traits::eos() character.	The fourth
           version replaces string elements with n repetitions	of c.
           The last	variation shown	here replaces  string elements with
           the members specified	in the range  [j1, j2).

        void
        reserve(size_type res_arg);
           Assures that the storage capacity is at least res_arg.

        void
        resize(size_type n, charT c);
        void
        resize(size_type n);
           Changes the capacity of this string to n.	If the new capacity is
           smaller than the current size of the string, then it is
           truncated.	  If the capacity is larger, then the string is	padded
           with c  characters. The latter	resize member pads the string
           with  default characters specified by  traits::eos().

        size type
        size() const;
           Return the	number of elements contained in	this string.

        basic_string
        substr(size_type pos = 0, size_type n	= npos)	const;
           Returns a string composed of copies of the	lesser of n and	size()
           characters in this string starting at index pos.  Throws an
           out_of_range exception if pos <= size().

        void
        swap(basic_string& s);
           Swaps the contents	of this	string with the	contents of s.

      NON-MEMBER OPERATORS

        template<class charT,	class traits, class Allocator>
        basic_string
        operator+(const basic_string&	lhs, const basic_string& rhs);
           Returns a string of length	lhs.size()  +  rhs.size(), where
           the first lhs.size()	elements are copies of the  elements
           of	lhs, and the next rhs.size()	elements are copies of
           the elements of rhs.

        template<class charT,	class traits, class Allocator>
        basic_string
        operator+(const charT* lhs, const basic_string& rhs);
        template<class charT,	class traits, class Allocator>
        basic_string
        operator+(charT lhs, const basic_string& rhs);
        template<class charT,	class traits, class Allocator>
        basic_string
        operator+(const basic_string&	 lhs, const charT* rhs);
        template<class charT,	class traits, class Allocator>
        basic_string
        operator+(const basic_string&	lhs, charT rhs);
           Returns a string that represents the concatenation	of two
           string-like
           entities.	These functions	return,	respectively:

           basic_string(lhs) + rhs
           basic_string(1, lhs) + rhs
           lhs + basic_string(rhs)
           lhs + basic_string(1, rhs)

        template<class charT,	class traits, class Allocator>
        bool
        operator==(const basic_string& lhs, const basic_string& rhs);
           Returns a boolean value of	true if	lhs and	rhs are	equal,
           and false if they are not. Equality  is	defined	by the
           compare() member	function.

        template<class charT,	class traits, class Allocator>
        bool
        operator==(const charT* lhs, const basic_string& rhs);
        template<class charT,	class traits, class Allocator>
        bool
        operator==(const basic_string& lhs, const charT* rhs);
           Returns a boolean value indicating	whether	lhs and	rhs are	equal.
           Equality is defined by the	compare()  member function.  These
           functions return, respectively:

           basic_string(lhs) == rhs
           lhs == basic_string(rhs)

        template<class charT,	class traits, class Allocator>
        bool
        operator!=(const basic_string& lhs,
      	    const basic_string&	rhs);
      	       Returns a boolean value representing the	inequality of lhs
                     and rhs.  Inequality	is defined by the compare()
                     member function.

        template<class charT,	class traits, class Allocator>
        bool
        operator!=(const charT* lhs, const basic_string& rhs);
        template<class charT,	class traits, class Allocator>
        bool
        operator!=(const basic_string& lhs, const charT* rhs);
           Returns a boolean value representing the inequality of  lhs
           and rhs. Inequality	is defined by the compare()
           member function.  The functions return, respectively:

           basic_string(lhs) != rhs
           lhs != basic_string(rhs)

        template<class charT,	class traits, class Allocator>
        bool
        operator<(const basic_string&	lhs, const basic_string& rhs);
           Returns a boolean value representing the lexicographical
           less-than	relationship of lhs and rhs.  Less-than is defined
           by the compare() member.

        template<class charT,	class traits, class Allocator>
        bool
        operator<(const charT* lhs, const basic_string& rhs);
        template<class charT,	class traits, class Allocator>
        bool
        operator<(const basic_string&	lhs, const charT* rhs);
           Returns a boolean value representing the lexicographical
           less-than	relationship of lhs and rhs.  Less-than is defined
           by the compare() member
           function.	These functions	return,	respectively:

           basic_string(lhs) < rhs
           lhs < basic_string(rhs)

        template<class charT,	class traits, class Allocator>
        bool
        operator>(const basic_string&	lhs, const basic_string& rhs);
           Returns a boolean value representing the lexicographical
           greater-than relationship of lhs and rhs.  Greater-than
           is defined by the compare() member function.

        template<class charT,	class traits, class Allocator>
        bool
        operator>(const charT* lhs, const basic_string& rhs);
        template<class charT,	class traits, class Allocator>
        bool
        operator>(const basic_string&	lhs, const charT* rhs);
           Returns a boolean value representing the lexicographical
           greater-than relationship of lhs and rhs.  Greater-than
           is defined by the compare() member.  The functions return,
           respectively:

           basic_string(lhs) > rhs
           lhs > basic_string(rhs)

        template<class charT,	class traits, class Allocator>
        bool
        operator<=(const basic_string& lhs,
      	      const basic_string& rhs);
      		 Returns a boolean value representing the
                       lexicographical
      		 less-than-or-equal relationship of lhs	and rhs.
                       Less-than-or-equal is defined by	the compare()
                       member function.

        template<class charT,	class traits, class Allocator>
        bool
        operator<=(const charT* lhs, const basic_string& rhs);
        template<class charT,	class traits, class Allocator>
        bool
        operator<=(const basic_string& lhs, const charT* rhs);
           Returns a boolean value representing the lexicographical
           less-than-or-equal relationship	of lhs and rhs.
           Less-than-or-equal is defined by the compare() member function.
           These functions return, respectively:

           basic_string(lhs) <= rhs
           lhs <= basic_string(rhs)

        template<class charT,	class traits, class Allocator>
        bool
        operator>=(const basic_string& lhs, const basic_string& rhs);
           Returns a boolean value representing the lexicographical
           greater-than-or-equal relationship of lhs and rhs.
           Greater-than-or-equal is defined by	the compare() member
           function.

        template<class charT,	class traits, class Allocator>
        bool
        operator>=(const charT* lhs, const basic_string& rhs);
        template<class charT,	class traits, class Allocator>
        bool
        operator>=(const basic_string& lhs, const charT* rhs);
           Returns a boolean value representing the lexicographical
           greater-than-or-equal  relationship of lhs and rhs.
           Greater-than-or-equal is defined
           by	the compare() member.  The functions return, respectively:

           basic_string(lhs) >= rhs
           lhs >= basic_string(rhs)

        template <class charT, class traits, class Allocator>
        void swap(basic_string<charT,traits,Allocator>& a,
      	   basic_string<charT,traits,Allocator>& b);
      	      Swaps the	contents of a and b by calling a's swap	function on
      	      b.

        template<class charT,	class traits, class Allocator>
        istream&
        operator>>(istream& is, basic_string&	str);
           Reads str	from  is using traits::char_in until a
           traits::is_del()	element  is read.  All elements read,
           except the delimiter, are placed in
           str.  After the read, the function	returns	is.

        template<class charT,	class traits, class Allocator>
        ostream&
        operator<<(ostream& os, const	basic_string& str);
           Writes all	elements of str	to os in order from first to last, using
           traits::char_out().  After	the write, the function	returns	os.

      NON-MEMBER FUNCTION

        template <class Stream, class	charT, class traits,
      	   class Allocator>
        Stream&
        getline(Stream& is, basic_string& str, charT delim);
           An	unformatted input function that	extracts characters from is
           into str until npos	- 1 characters are read, the end of
           the	input sequence is reached, or the character read is
           delim.  The characters are read using traits::char_in().

      EXAMPLE

        //
        // string.cpp
        //
         #include<string>
         #include <iostream.h>

        int main()
         {
          string test;

           //Type in a string	over five characters long
          while(test.empty() ||  test.size() <= 5)
           {
            cout << "Type a string between 5 and 100 characters long.	"
      	    << endl;
            cin >> test;
           }

           //Test operator[] access
          cout << "Changing the third	character from " << test[2] <<
      	     " to * " << endl;
          test[2] = '*';
          cout << "now its: "	<< test	<< endl	<< endl;

           //Try the insertion member	function
          cout << "Identifying the middle: ";
          test.insert(test.size() / 2, "(the middle is here!)");
          cout << test << endl << endl;

           //Try replacement
          cout << "I didn't like the word 'middle',so	instead,I'll say:"
      		<< endl;
          test.replace(test.find("middle",0),	6, "center");
          cout << test << endl;

          return 0;
         }

        Output :
        Type a string	between	5 and 100 characters long.
        roguewave
        Changing the third character from g to *
        now its: ro*uewave
        Identifying the middle: ro*u(the middle is here!)ewave
        I didn't like	the word 'middle', so instead, I'll say:
        ro*u(the center is here!)ewave

      SEE ALSO

        Allocators, string, wstring

      STANDARDS CONFORMANCE
        ANSI X3J16/ISO WG21 Joint C++	Committee
- Additional Information on: string_char_traits basic_string basic_stringbuf

  ##

      IOStreams
- Additional Information on: iostream_intro basic_filebuf basic_fstream basic_ifstream basic_ios basic_iostream basic_istream basic_istringstream basic_ofstream basic_ostream basic_ostringstream basic_streambuf basic_stringstream cerr char_traits cin cout ctype filebuf fpos fstream ifstream ios iosfwd istream iostream ios_base istringstream istrstream ofstream ostream ostringstream ostrstream smanip smanip_fill streambuf stringbuf stringstream strstream strstreambuf wcerr wcin wclog wcout wstring

  ##

      locales
Additional Information on: locale codecvt_byname code_cvt collate collate_byname facets has_facet isalnum isalpha iscntrl isdigit isgraph islower isprint ispunct isspace isupper isxdigit messages messages_byname moneypunct moneypunct_byname money_get money_put numpunct numpunct_byname num_get num_put time_get time_get_byname time_put time_put_byname tolower toupper use_facet

|  | privacy statement and legal notices