home *** CD-ROM | disk | FTP | other *** search
/ Beginning C++ Through Gam…rogramming (2nd Edition) / BCGP2E.ISO / bloodshed / devcpp-4.9.9.2_setup.exe / basic_string.h < prev    next >
C/C++ Source or Header  |  2005-01-29  |  88KB  |  2,345 lines

  1. // Components for manipulating sequences of characters -*- C++ -*-
  2.  
  3. // Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004
  4. // Free Software Foundation, Inc.
  5. //
  6. // This file is part of the GNU ISO C++ Library.  This library is free
  7. // software; you can redistribute it and/or modify it under the
  8. // terms of the GNU General Public License as published by the
  9. // Free Software Foundation; either version 2, or (at your option)
  10. // any later version.
  11.  
  12. // This library is distributed in the hope that it will be useful,
  13. // but WITHOUT ANY WARRANTY; without even the implied warranty of
  14. // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15. // GNU General Public License for more details.
  16.  
  17. // You should have received a copy of the GNU General Public License along
  18. // with this library; see the file COPYING.  If not, write to the Free
  19. // Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  20. // USA.
  21.  
  22. // As a special exception, you may use this file as part of a free software
  23. // library without restriction.  Specifically, if other files instantiate
  24. // templates or use macros or inline functions from this file, or you compile
  25. // this file and link it with other files to produce an executable, this
  26. // file does not by itself cause the resulting executable to be covered by
  27. // the GNU General Public License.  This exception does not however
  28. // invalidate any other reasons why the executable file might be covered by
  29. // the GNU General Public License.
  30.  
  31. //
  32. // ISO C++ 14882: 21 Strings library
  33. //
  34.  
  35. /** @file basic_string.h
  36.  *  This is an internal header file, included by other library headers.
  37.  *  You should not attempt to use it directly.
  38.  */
  39.  
  40. #ifndef _BASIC_STRING_H
  41. #define _BASIC_STRING_H 1
  42.  
  43. #pragma GCC system_header
  44.  
  45. #include <bits/atomicity.h>
  46. #include <debug/debug.h>
  47.  
  48. namespace std
  49. {
  50.   /**
  51.    *  @class basic_string basic_string.h <string>
  52.    *  @brief  Managing sequences of characters and character-like objects.
  53.    *
  54.    *  @ingroup Containers
  55.    *  @ingroup Sequences
  56.    *
  57.    *  Meets the requirements of a <a href="tables.html#65">container</a>, a
  58.    *  <a href="tables.html#66">reversible container</a>, and a
  59.    *  <a href="tables.html#67">sequence</a>.  Of the
  60.    *  <a href="tables.html#68">optional sequence requirements</a>, only
  61.    *  @c push_back, @c at, and array access are supported.
  62.    *
  63.    *  @doctodo
  64.    *
  65.    *
  66.    *  @if maint
  67.    *  Documentation?  What's that?
  68.    *  Nathan Myers <ncm@cantrip.org>.
  69.    *
  70.    *  A string looks like this:
  71.    *
  72.    *  @code
  73.    *                                        [_Rep]
  74.    *                                        _M_length
  75.    *   [basic_string<char_type>]            _M_capacity
  76.    *   _M_dataplus                          _M_refcount
  77.    *   _M_p ---------------->               unnamed array of char_type
  78.    *  @endcode
  79.    *
  80.    *  Where the _M_p points to the first character in the string, and
  81.    *  you cast it to a pointer-to-_Rep and subtract 1 to get a
  82.    *  pointer to the header.
  83.    *
  84.    *  This approach has the enormous advantage that a string object
  85.    *  requires only one allocation.  All the ugliness is confined
  86.    *  within a single pair of inline functions, which each compile to
  87.    *  a single "add" instruction: _Rep::_M_data(), and
  88.    *  string::_M_rep(); and the allocation function which gets a
  89.    *  block of raw bytes and with room enough and constructs a _Rep
  90.    *  object at the front.
  91.    *
  92.    *  The reason you want _M_data pointing to the character array and
  93.    *  not the _Rep is so that the debugger can see the string
  94.    *  contents. (Probably we should add a non-inline member to get
  95.    *  the _Rep for the debugger to use, so users can check the actual
  96.    *  string length.)
  97.    *
  98.    *  Note that the _Rep object is a POD so that you can have a
  99.    *  static "empty string" _Rep object already "constructed" before
  100.    *  static constructors have run.  The reference-count encoding is
  101.    *  chosen so that a 0 indicates one reference, so you never try to
  102.    *  destroy the empty-string _Rep object.
  103.    *
  104.    *  All but the last paragraph is considered pretty conventional
  105.    *  for a C++ string implementation.
  106.    *  @endif
  107.   */
  108.   // 21.3  Template class basic_string
  109.   template<typename _CharT, typename _Traits, typename _Alloc>
  110.     class basic_string
  111.     {
  112.       // Types:
  113.     public:
  114.       typedef _Traits                        traits_type;
  115.       typedef typename _Traits::char_type            value_type;
  116.       typedef _Alloc                        allocator_type;
  117.       typedef typename _Alloc::size_type            size_type;
  118.       typedef typename _Alloc::difference_type            difference_type;
  119.       typedef typename _Alloc::reference            reference;
  120.       typedef typename _Alloc::const_reference            const_reference;
  121.       typedef typename _Alloc::pointer                pointer;
  122.       typedef typename _Alloc::const_pointer            const_pointer;
  123.       typedef __gnu_cxx::__normal_iterator<pointer, basic_string>  iterator;
  124.       typedef __gnu_cxx::__normal_iterator<const_pointer, basic_string>
  125.                                                             const_iterator;
  126.       typedef std::reverse_iterator<const_iterator>    const_reverse_iterator;
  127.       typedef std::reverse_iterator<iterator>            reverse_iterator;
  128.  
  129.     private:
  130.       // _Rep: string representation
  131.       //   Invariants:
  132.       //   1. String really contains _M_length + 1 characters: due to 21.3.4
  133.       //      must be kept null-terminated.
  134.       //   2. _M_capacity >= _M_length
  135.       //      Allocated memory is always (_M_capacity + 1) * sizeof(_CharT).
  136.       //   3. _M_refcount has three states:
  137.       //      -1: leaked, one reference, no ref-copies allowed, non-const.
  138.       //       0: one reference, non-const.
  139.       //     n>0: n + 1 references, operations require a lock, const.
  140.       //   4. All fields==0 is an empty string, given the extra storage
  141.       //      beyond-the-end for a null terminator; thus, the shared
  142.       //      empty string representation needs no constructor.
  143.  
  144.       struct _Rep_base
  145.       {
  146.     size_type        _M_length;
  147.     size_type        _M_capacity;
  148.     _Atomic_word        _M_refcount;
  149.       };
  150.  
  151.       struct _Rep : _Rep_base
  152.       {
  153.     // Types:
  154.     typedef typename _Alloc::template rebind<char>::other _Raw_bytes_alloc;
  155.  
  156.     // (Public) Data members:
  157.  
  158.     // The maximum number of individual char_type elements of an
  159.     // individual string is determined by _S_max_size. This is the
  160.     // value that will be returned by max_size().  (Whereas npos
  161.     // is the maximum number of bytes the allocator can allocate.)
  162.     // If one was to divvy up the theoretical largest size string,
  163.     // with a terminating character and m _CharT elements, it'd
  164.     // look like this:
  165.     // npos = sizeof(_Rep) + (m * sizeof(_CharT)) + sizeof(_CharT)
  166.     // Solving for m:
  167.     // m = ((npos - sizeof(_Rep))/sizeof(CharT)) - 1
  168.     // In addition, this implementation quarters this amount.
  169.     static const size_type    _S_max_size;
  170.     static const _CharT    _S_terminal;
  171.  
  172.     // The following storage is init'd to 0 by the linker, resulting
  173.         // (carefully) in an empty string with one reference.
  174.         static size_type _S_empty_rep_storage[];
  175.  
  176.         static _Rep&
  177.         _S_empty_rep()
  178.         { return *reinterpret_cast<_Rep*>(&_S_empty_rep_storage); }
  179.  
  180.         bool
  181.     _M_is_leaked() const
  182.         { return this->_M_refcount < 0; }
  183.  
  184.         bool
  185.     _M_is_shared() const
  186.         { return this->_M_refcount > 0; }
  187.  
  188.         void
  189.     _M_set_leaked()
  190.         { this->_M_refcount = -1; }
  191.  
  192.         void
  193.     _M_set_sharable()
  194.         { this->_M_refcount = 0; }
  195.  
  196.     _CharT*
  197.     _M_refdata() throw()
  198.     { return reinterpret_cast<_CharT*>(this + 1); }
  199.  
  200.     _CharT*
  201.     _M_grab(const _Alloc& __alloc1, const _Alloc& __alloc2)
  202.     {
  203.       return (!_M_is_leaked() && __alloc1 == __alloc2)
  204.               ? _M_refcopy() : _M_clone(__alloc1);
  205.     }
  206.  
  207.     // Create & Destroy
  208.     static _Rep*
  209.     _S_create(size_type, size_type, const _Alloc&);
  210.  
  211.     void
  212.     _M_dispose(const _Alloc& __a)
  213.     {
  214.       if (__builtin_expect(this != &_S_empty_rep(), false))
  215.         if (__gnu_cxx::__exchange_and_add(&this->_M_refcount, -1) <= 0)
  216.           _M_destroy(__a);
  217.     }  // XXX MT
  218.  
  219.     void
  220.     _M_destroy(const _Alloc&) throw();
  221.  
  222.     _CharT*
  223.     _M_refcopy() throw()
  224.     {
  225.       if (__builtin_expect(this != &_S_empty_rep(), false))
  226.             __gnu_cxx::__atomic_add(&this->_M_refcount, 1);
  227.       return _M_refdata();
  228.     }  // XXX MT
  229.  
  230.     _CharT*
  231.     _M_clone(const _Alloc&, size_type __res = 0);
  232.       };
  233.  
  234.       // Use empty-base optimization: http://www.cantrip.org/emptyopt.html
  235.       struct _Alloc_hider : _Alloc
  236.       {
  237.     _Alloc_hider(_CharT* __dat, const _Alloc& __a)
  238.     : _Alloc(__a), _M_p(__dat) { }
  239.  
  240.     _CharT* _M_p; // The actual data.
  241.       };
  242.  
  243.     public:
  244.       // Data Members (public):
  245.       // NB: This is an unsigned type, and thus represents the maximum
  246.       // size that the allocator can hold.
  247.       /// @var
  248.       /// Value returned by various member functions when they fail.
  249.       static const size_type    npos = static_cast<size_type>(-1);
  250.  
  251.     private:
  252.       // Data Members (private):
  253.       mutable _Alloc_hider    _M_dataplus;
  254.  
  255.       _CharT*
  256.       _M_data() const
  257.       { return  _M_dataplus._M_p; }
  258.  
  259.       _CharT*
  260.       _M_data(_CharT* __p)
  261.       { return (_M_dataplus._M_p = __p); }
  262.  
  263.       _Rep*
  264.       _M_rep() const
  265.       { return &((reinterpret_cast<_Rep*> (_M_data()))[-1]); }
  266.  
  267.       // For the internal use we have functions similar to `begin'/`end'
  268.       // but they do not call _M_leak.
  269.       iterator
  270.       _M_ibegin() const { return iterator(_M_data()); }
  271.  
  272.       iterator
  273.       _M_iend() const { return iterator(_M_data() + this->size()); }
  274.  
  275.       void
  276.       _M_leak()    // for use in begin() & non-const op[]
  277.       {
  278.     if (!_M_rep()->_M_is_leaked())
  279.       _M_leak_hard();
  280.       }
  281.  
  282.       size_type
  283.       _M_check(size_type __pos, const char* __s) const
  284.       {
  285.     if (__pos > this->size())
  286.       __throw_out_of_range(__N(__s));
  287.     return __pos;
  288.       }
  289.  
  290.       // NB: _M_limit doesn't check for a bad __pos value.
  291.       size_type
  292.       _M_limit(size_type __pos, size_type __off) const
  293.       {
  294.     const bool __testoff =  __off < this->size() - __pos;
  295.     return __testoff ? __off : this->size() - __pos;
  296.       }
  297.  
  298.       // _S_copy_chars is a separate template to permit specialization
  299.       // to optimize for the common case of pointers as iterators.
  300.       template<class _Iterator>
  301.         static void
  302.         _S_copy_chars(_CharT* __p, _Iterator __k1, _Iterator __k2)
  303.         {
  304.       for (; __k1 != __k2; ++__k1, ++__p)
  305.         traits_type::assign(*__p, *__k1); // These types are off.
  306.     }
  307.  
  308.       static void
  309.       _S_copy_chars(_CharT* __p, iterator __k1, iterator __k2)
  310.       { _S_copy_chars(__p, __k1.base(), __k2.base()); }
  311.  
  312.       static void
  313.       _S_copy_chars(_CharT* __p, const_iterator __k1, const_iterator __k2)
  314.       { _S_copy_chars(__p, __k1.base(), __k2.base()); }
  315.  
  316.       static void
  317.       _S_copy_chars(_CharT* __p, _CharT* __k1, _CharT* __k2)
  318.       { traits_type::copy(__p, __k1, __k2 - __k1); }
  319.  
  320.       static void
  321.       _S_copy_chars(_CharT* __p, const _CharT* __k1, const _CharT* __k2)
  322.       { traits_type::copy(__p, __k1, __k2 - __k1); }
  323.  
  324.       void
  325.       _M_mutate(size_type __pos, size_type __len1, size_type __len2);
  326.  
  327.       void
  328.       _M_leak_hard();
  329.  
  330.       static _Rep&
  331.       _S_empty_rep()
  332.       { return _Rep::_S_empty_rep(); }
  333.  
  334.     public:
  335.       // Construct/copy/destroy:
  336.       // NB: We overload ctors in some cases instead of using default
  337.       // arguments, per 17.4.4.4 para. 2 item 2.
  338.  
  339.       /**
  340.        *  @brief  Default constructor creates an empty string.
  341.        */
  342.       inline
  343.       basic_string();
  344.  
  345.       /**
  346.        *  @brief  Construct an empty string using allocator a.
  347.        */
  348.       explicit
  349.       basic_string(const _Alloc& __a);
  350.  
  351.       // NB: per LWG issue 42, semantics different from IS:
  352.       /**
  353.        *  @brief  Construct string with copy of value of @a str.
  354.        *  @param  str  Source string.
  355.        */
  356.       basic_string(const basic_string& __str);
  357.       /**
  358.        *  @brief  Construct string as copy of a substring.
  359.        *  @param  str  Source string.
  360.        *  @param  pos  Index of first character to copy from.
  361.        *  @param  n  Number of characters to copy (default remainder).
  362.        */
  363.       basic_string(const basic_string& __str, size_type __pos,
  364.            size_type __n = npos);
  365.       /**
  366.        *  @brief  Construct string as copy of a substring.
  367.        *  @param  str  Source string.
  368.        *  @param  pos  Index of first character to copy from.
  369.        *  @param  n  Number of characters to copy.
  370.        *  @param  a  Allocator to use.
  371.        */
  372.       basic_string(const basic_string& __str, size_type __pos,
  373.            size_type __n, const _Alloc& __a);
  374.  
  375.       /**
  376.        *  @brief  Construct string initialized by a character array.
  377.        *  @param  s  Source character array.
  378.        *  @param  n  Number of characters to copy.
  379.        *  @param  a  Allocator to use (default is default allocator).
  380.        *
  381.        *  NB: s must have at least n characters, '\0' has no special
  382.        *  meaning.
  383.        */
  384.       basic_string(const _CharT* __s, size_type __n,
  385.            const _Alloc& __a = _Alloc());
  386.       /**
  387.        *  @brief  Construct string as copy of a C string.
  388.        *  @param  s  Source C string.
  389.        *  @param  a  Allocator to use (default is default allocator).
  390.        */
  391.       basic_string(const _CharT* __s, const _Alloc& __a = _Alloc());
  392.       /**
  393.        *  @brief  Construct string as multiple characters.
  394.        *  @param  n  Number of characters.
  395.        *  @param  c  Character to use.
  396.        *  @param  a  Allocator to use (default is default allocator).
  397.        */
  398.       basic_string(size_type __n, _CharT __c, const _Alloc& __a = _Alloc());
  399.  
  400.       /**
  401.        *  @brief  Construct string as copy of a range.
  402.        *  @param  beg  Start of range.
  403.        *  @param  end  End of range.
  404.        *  @param  a  Allocator to use (default is default allocator).
  405.        */
  406.       template<class _InputIterator>
  407.         basic_string(_InputIterator __beg, _InputIterator __end,
  408.              const _Alloc& __a = _Alloc());
  409.  
  410.       /**
  411.        *  @brief  Destroy the string instance.
  412.        */
  413.       ~basic_string()
  414.       { _M_rep()->_M_dispose(this->get_allocator()); }
  415.  
  416.       /**
  417.        *  @brief  Assign the value of @a str to this string.
  418.        *  @param  str  Source string.
  419.        */
  420.       basic_string&
  421.       operator=(const basic_string& __str) 
  422.       { 
  423.     this->assign(__str); 
  424.     return *this;
  425.       }
  426.  
  427.       /**
  428.        *  @brief  Copy contents of @a s into this string.
  429.        *  @param  s  Source null-terminated string.
  430.        */
  431.       basic_string&
  432.       operator=(const _CharT* __s) 
  433.       { 
  434.     this->assign(__s); 
  435.     return *this;
  436.       }
  437.  
  438.       /**
  439.        *  @brief  Set value to string of length 1.
  440.        *  @param  c  Source character.
  441.        *
  442.        *  Assigning to a character makes this string length 1 and
  443.        *  (*this)[0] == @a c.
  444.        */
  445.       basic_string&
  446.       operator=(_CharT __c) 
  447.       { 
  448.     this->assign(1, __c); 
  449.     return *this;
  450.       }
  451.  
  452.       // Iterators:
  453.       /**
  454.        *  Returns a read/write iterator that points to the first character in
  455.        *  the %string.  Unshares the string.
  456.        */
  457.       iterator
  458.       begin()
  459.       {
  460.     _M_leak();
  461.     return iterator(_M_data());
  462.       }
  463.  
  464.       /**
  465.        *  Returns a read-only (constant) iterator that points to the first
  466.        *  character in the %string.
  467.        */
  468.       const_iterator
  469.       begin() const
  470.       { return const_iterator(_M_data()); }
  471.  
  472.       /**
  473.        *  Returns a read/write iterator that points one past the last
  474.        *  character in the %string.  Unshares the string.
  475.        */
  476.       iterator
  477.       end()
  478.       {
  479.     _M_leak();
  480.     return iterator(_M_data() + this->size());
  481.       }
  482.  
  483.       /**
  484.        *  Returns a read-only (constant) iterator that points one past the
  485.        *  last character in the %string.
  486.        */
  487.       const_iterator
  488.       end() const
  489.       { return const_iterator(_M_data() + this->size()); }
  490.  
  491.       /**
  492.        *  Returns a read/write reverse iterator that points to the last
  493.        *  character in the %string.  Iteration is done in reverse element
  494.        *  order.  Unshares the string.
  495.        */
  496.       reverse_iterator
  497.       rbegin()
  498.       { return reverse_iterator(this->end()); }
  499.  
  500.       /**
  501.        *  Returns a read-only (constant) reverse iterator that points
  502.        *  to the last character in the %string.  Iteration is done in
  503.        *  reverse element order.
  504.        */
  505.       const_reverse_iterator
  506.       rbegin() const
  507.       { return const_reverse_iterator(this->end()); }
  508.  
  509.       /**
  510.        *  Returns a read/write reverse iterator that points to one before the
  511.        *  first character in the %string.  Iteration is done in reverse
  512.        *  element order.  Unshares the string.
  513.        */
  514.       reverse_iterator
  515.       rend()
  516.       { return reverse_iterator(this->begin()); }
  517.  
  518.       /**
  519.        *  Returns a read-only (constant) reverse iterator that points
  520.        *  to one before the first character in the %string.  Iteration
  521.        *  is done in reverse element order.
  522.        */
  523.       const_reverse_iterator
  524.       rend() const
  525.       { return const_reverse_iterator(this->begin()); }
  526.  
  527.     public:
  528.       // Capacity:
  529.       ///  Returns the number of characters in the string, not including any
  530.       ///  null-termination.
  531.       size_type
  532.       size() const { return _M_rep()->_M_length; }
  533.  
  534.       ///  Returns the number of characters in the string, not including any
  535.       ///  null-termination.
  536.       size_type
  537.       length() const { return _M_rep()->_M_length; }
  538.  
  539.       /// Returns the size() of the largest possible %string.
  540.       size_type
  541.       max_size() const { return _Rep::_S_max_size; }
  542.  
  543.       /**
  544.        *  @brief  Resizes the %string to the specified number of characters.
  545.        *  @param  n  Number of characters the %string should contain.
  546.        *  @param  c  Character to fill any new elements.
  547.        *
  548.        *  This function will %resize the %string to the specified
  549.        *  number of characters.  If the number is smaller than the
  550.        *  %string's current size the %string is truncated, otherwise
  551.        *  the %string is extended and new elements are set to @a c.
  552.        */
  553.       void
  554.       resize(size_type __n, _CharT __c);
  555.  
  556.       /**
  557.        *  @brief  Resizes the %string to the specified number of characters.
  558.        *  @param  n  Number of characters the %string should contain.
  559.        *
  560.        *  This function will resize the %string to the specified length.  If
  561.        *  the new size is smaller than the %string's current size the %string
  562.        *  is truncated, otherwise the %string is extended and new characters
  563.        *  are default-constructed.  For basic types such as char, this means
  564.        *  setting them to 0.
  565.        */
  566.       void
  567.       resize(size_type __n) { this->resize(__n, _CharT()); }
  568.  
  569.       /**
  570.        *  Returns the total number of characters that the %string can hold
  571.        *  before needing to allocate more memory.
  572.        */
  573.       size_type
  574.       capacity() const { return _M_rep()->_M_capacity; }
  575.  
  576.       /**
  577.        *  @brief  Attempt to preallocate enough memory for specified number of
  578.        *          characters.
  579.        *  @param  n  Number of characters required.
  580.        *  @throw  std::length_error  If @a n exceeds @c max_size().
  581.        *
  582.        *  This function attempts to reserve enough memory for the
  583.        *  %string to hold the specified number of characters.  If the
  584.        *  number requested is more than max_size(), length_error is
  585.        *  thrown.
  586.        *
  587.        *  The advantage of this function is that if optimal code is a
  588.        *  necessity and the user can determine the string length that will be
  589.        *  required, the user can reserve the memory in %advance, and thus
  590.        *  prevent a possible reallocation of memory and copying of %string
  591.        *  data.
  592.        */
  593.       void
  594.       reserve(size_type __res_arg = 0);
  595.  
  596.       /**
  597.        *  Erases the string, making it empty.
  598.        */
  599.       void
  600.       clear() { _M_mutate(0, this->size(), 0); }
  601.  
  602.       /**
  603.        *  Returns true if the %string is empty.  Equivalent to *this == "".
  604.        */
  605.       bool
  606.       empty() const { return this->size() == 0; }
  607.  
  608.       // Element access:
  609.       /**
  610.        *  @brief  Subscript access to the data contained in the %string.
  611.        *  @param  n  The index of the character to access.
  612.        *  @return  Read-only (constant) reference to the character.
  613.        *
  614.        *  This operator allows for easy, array-style, data access.
  615.        *  Note that data access with this operator is unchecked and
  616.        *  out_of_range lookups are not defined. (For checked lookups
  617.        *  see at().)
  618.        */
  619.       const_reference
  620.       operator[] (size_type __pos) const
  621.       {
  622.     _GLIBCXX_DEBUG_ASSERT(__pos <= size());
  623.     return _M_data()[__pos];
  624.       }
  625.  
  626.       /**
  627.        *  @brief  Subscript access to the data contained in the %string.
  628.        *  @param  n  The index of the character to access.
  629.        *  @return  Read/write reference to the character.
  630.        *
  631.        *  This operator allows for easy, array-style, data access.
  632.        *  Note that data access with this operator is unchecked and
  633.        *  out_of_range lookups are not defined. (For checked lookups
  634.        *  see at().)  Unshares the string.
  635.        */
  636.       reference
  637.       operator[](size_type __pos)
  638.       {
  639.     _GLIBCXX_DEBUG_ASSERT(__pos < size());
  640.     _M_leak();
  641.     return _M_data()[__pos];
  642.       }
  643.  
  644.       /**
  645.        *  @brief  Provides access to the data contained in the %string.
  646.        *  @param n The index of the character to access.
  647.        *  @return  Read-only (const) reference to the character.
  648.        *  @throw  std::out_of_range  If @a n is an invalid index.
  649.        *
  650.        *  This function provides for safer data access.  The parameter is
  651.        *  first checked that it is in the range of the string.  The function
  652.        *  throws out_of_range if the check fails.
  653.        */
  654.       const_reference
  655.       at(size_type __n) const
  656.       {
  657.     if (__n >= this->size())
  658.       __throw_out_of_range(__N("basic_string::at"));
  659.     return _M_data()[__n];
  660.       }
  661.  
  662.       /**
  663.        *  @brief  Provides access to the data contained in the %string.
  664.        *  @param n The index of the character to access.
  665.        *  @return  Read/write reference to the character.
  666.        *  @throw  std::out_of_range  If @a n is an invalid index.
  667.        *
  668.        *  This function provides for safer data access.  The parameter is
  669.        *  first checked that it is in the range of the string.  The function
  670.        *  throws out_of_range if the check fails.  Success results in
  671.        *  unsharing the string.
  672.        */
  673.       reference
  674.       at(size_type __n)
  675.       {
  676.     if (__n >= size())
  677.       __throw_out_of_range(__N("basic_string::at"));
  678.     _M_leak();
  679.     return _M_data()[__n];
  680.       }
  681.  
  682.       // Modifiers:
  683.       /**
  684.        *  @brief  Append a string to this string.
  685.        *  @param str  The string to append.
  686.        *  @return  Reference to this string.
  687.        */
  688.       basic_string&
  689.       operator+=(const basic_string& __str) { return this->append(__str); }
  690.  
  691.       /**
  692.        *  @brief  Append a C string.
  693.        *  @param s  The C string to append.
  694.        *  @return  Reference to this string.
  695.        */
  696.       basic_string&
  697.       operator+=(const _CharT* __s) { return this->append(__s); }
  698.  
  699.       /**
  700.        *  @brief  Append a character.
  701.        *  @param s  The character to append.
  702.        *  @return  Reference to this string.
  703.        */
  704.       basic_string&
  705.       operator+=(_CharT __c) { return this->append(size_type(1), __c); }
  706.  
  707.       /**
  708.        *  @brief  Append a string to this string.
  709.        *  @param str  The string to append.
  710.        *  @return  Reference to this string.
  711.        */
  712.       basic_string&
  713.       append(const basic_string& __str);
  714.  
  715.       /**
  716.        *  @brief  Append a substring.
  717.        *  @param str  The string to append.
  718.        *  @param pos  Index of the first character of str to append.
  719.        *  @param n  The number of characters to append.
  720.        *  @return  Reference to this string.
  721.        *  @throw  std::out_of_range if @a pos is not a valid index.
  722.        *
  723.        *  This function appends @a n characters from @a str starting at @a pos
  724.        *  to this string.  If @a n is is larger than the number of available
  725.        *  characters in @a str, the remainder of @a str is appended.
  726.        */
  727.       basic_string&
  728.       append(const basic_string& __str, size_type __pos, size_type __n);
  729.  
  730.       /**
  731.        *  @brief  Append a C substring.
  732.        *  @param s  The C string to append.
  733.        *  @param n  The number of characters to append.
  734.        *  @return  Reference to this string.
  735.        */
  736.       basic_string&
  737.       append(const _CharT* __s, size_type __n);
  738.  
  739.       /**
  740.        *  @brief  Append a C string.
  741.        *  @param s  The C string to append.
  742.        *  @return  Reference to this string.
  743.        */
  744.       basic_string&
  745.       append(const _CharT* __s)
  746.       {
  747.     __glibcxx_requires_string(__s);
  748.     return this->append(__s, traits_type::length(__s));
  749.       }
  750.  
  751.       /**
  752.        *  @brief  Append multiple characters.
  753.        *  @param n  The number of characters to append.
  754.        *  @param c  The character to use.
  755.        *  @return  Reference to this string.
  756.        *
  757.        *  Appends n copies of c to this string.
  758.        */
  759.       basic_string&
  760.       append(size_type __n, _CharT __c)
  761.       { return _M_replace_aux(this->size(), size_type(0), __n, __c); }
  762.  
  763.       /**
  764.        *  @brief  Append a range of characters.
  765.        *  @param first  Iterator referencing the first character to append.
  766.        *  @param last  Iterator marking the end of the range.
  767.        *  @return  Reference to this string.
  768.        *
  769.        *  Appends characters in the range [first,last) to this string.
  770.        */
  771.       template<class _InputIterator>
  772.         basic_string&
  773.         append(_InputIterator __first, _InputIterator __last)
  774.         { return this->replace(_M_iend(), _M_iend(), __first, __last); }
  775.  
  776.       /**
  777.        *  @brief  Append a single character.
  778.        *  @param c  Character to append.
  779.        */
  780.       void
  781.       push_back(_CharT __c)
  782.       { _M_replace_aux(this->size(), size_type(0), size_type(1), __c); }
  783.  
  784.       /**
  785.        *  @brief  Set value to contents of another string.
  786.        *  @param  str  Source string to use.
  787.        *  @return  Reference to this string.
  788.        */
  789.       basic_string&
  790.       assign(const basic_string& __str);
  791.  
  792.       /**
  793.        *  @brief  Set value to a substring of a string.
  794.        *  @param str  The string to use.
  795.        *  @param pos  Index of the first character of str.
  796.        *  @param n  Number of characters to use.
  797.        *  @return  Reference to this string.
  798.        *  @throw  std::out_of_range if @a pos is not a valid index.
  799.        *
  800.        *  This function sets this string to the substring of @a str consisting
  801.        *  of @a n characters at @a pos.  If @a n is is larger than the number
  802.        *  of available characters in @a str, the remainder of @a str is used.
  803.        */
  804.       basic_string&
  805.       assign(const basic_string& __str, size_type __pos, size_type __n)
  806.       { return this->assign(__str._M_data()
  807.                 + __str._M_check(__pos, "basic_string::assign"),
  808.                 __str._M_limit(__pos, __n)); }
  809.  
  810.       /**
  811.        *  @brief  Set value to a C substring.
  812.        *  @param s  The C string to use.
  813.        *  @param n  Number of characters to use.
  814.        *  @return  Reference to this string.
  815.        *
  816.        *  This function sets the value of this string to the first @a n
  817.        *  characters of @a s.  If @a n is is larger than the number of
  818.        *  available characters in @a s, the remainder of @a s is used.
  819.        */
  820.       basic_string&
  821.       assign(const _CharT* __s, size_type __n);
  822.  
  823.       /**
  824.        *  @brief  Set value to contents of a C string.
  825.        *  @param s  The C string to use.
  826.        *  @return  Reference to this string.
  827.        *
  828.        *  This function sets the value of this string to the value of @a s.
  829.        *  The data is copied, so there is no dependence on @a s once the
  830.        *  function returns.
  831.        */
  832.       basic_string&
  833.       assign(const _CharT* __s)
  834.       {
  835.     __glibcxx_requires_string(__s);
  836.     return this->assign(__s, traits_type::length(__s));
  837.       }
  838.  
  839.       /**
  840.        *  @brief  Set value to multiple characters.
  841.        *  @param n  Length of the resulting string.
  842.        *  @param c  The character to use.
  843.        *  @return  Reference to this string.
  844.        *
  845.        *  This function sets the value of this string to @a n copies of
  846.        *  character @a c.
  847.        */
  848.       basic_string&
  849.       assign(size_type __n, _CharT __c)
  850.       { return _M_replace_aux(size_type(0), this->size(), __n, __c); }
  851.  
  852.       /**
  853.        *  @brief  Set value to a range of characters.
  854.        *  @param first  Iterator referencing the first character to append.
  855.        *  @param last  Iterator marking the end of the range.
  856.        *  @return  Reference to this string.
  857.        *
  858.        *  Sets value of string to characters in the range [first,last).
  859.       */
  860.       template<class _InputIterator>
  861.         basic_string&
  862.         assign(_InputIterator __first, _InputIterator __last)
  863.         { return this->replace(_M_ibegin(), _M_iend(), __first, __last); }
  864.  
  865.       /**
  866.        *  @brief  Insert multiple characters.
  867.        *  @param p  Iterator referencing location in string to insert at.
  868.        *  @param n  Number of characters to insert
  869.        *  @param c  The character to insert.
  870.        *  @throw  std::length_error  If new length exceeds @c max_size().
  871.        *
  872.        *  Inserts @a n copies of character @a c starting at the position
  873.        *  referenced by iterator @a p.  If adding characters causes the length
  874.        *  to exceed max_size(), length_error is thrown.  The value of the
  875.        *  string doesn't change if an error is thrown.
  876.       */
  877.       void
  878.       insert(iterator __p, size_type __n, _CharT __c)
  879.       {    this->replace(__p, __p, __n, __c);  }
  880.  
  881.       /**
  882.        *  @brief  Insert a range of characters.
  883.        *  @param p  Iterator referencing location in string to insert at.
  884.        *  @param beg  Start of range.
  885.        *  @param end  End of range.
  886.        *  @throw  std::length_error  If new length exceeds @c max_size().
  887.        *
  888.        *  Inserts characters in range [beg,end).  If adding characters causes
  889.        *  the length to exceed max_size(), length_error is thrown.  The value
  890.        *  of the string doesn't change if an error is thrown.
  891.       */
  892.       template<class _InputIterator>
  893.         void insert(iterator __p, _InputIterator __beg, _InputIterator __end)
  894.         { this->replace(__p, __p, __beg, __end); }
  895.  
  896.       /**
  897.        *  @brief  Insert value of a string.
  898.        *  @param pos1  Iterator referencing location in string to insert at.
  899.        *  @param str  The string to insert.
  900.        *  @return  Reference to this string.
  901.        *  @throw  std::length_error  If new length exceeds @c max_size().
  902.        *
  903.        *  Inserts value of @a str starting at @a pos1.  If adding characters
  904.        *  causes the length to exceed max_size(), length_error is thrown.  The
  905.        *  value of the string doesn't change if an error is thrown.
  906.       */
  907.       basic_string&
  908.       insert(size_type __pos1, const basic_string& __str)
  909.       { return this->insert(__pos1, __str, size_type(0), __str.size()); }
  910.  
  911.       /**
  912.        *  @brief  Insert a substring.
  913.        *  @param pos1  Iterator referencing location in string to insert at.
  914.        *  @param str  The string to insert.
  915.        *  @param pos2  Start of characters in str to insert.
  916.        *  @param n  Number of characters to insert.
  917.        *  @return  Reference to this string.
  918.        *  @throw  std::length_error  If new length exceeds @c max_size().
  919.        *  @throw  std::out_of_range  If @a pos1 > size() or
  920.        *  @a pos2 > @a str.size().
  921.        *
  922.        *  Starting at @a pos1, insert @a n character of @a str beginning with
  923.        *  @a pos2.  If adding characters causes the length to exceed
  924.        *  max_size(), length_error is thrown.  If @a pos1 is beyond the end of
  925.        *  this string or @a pos2 is beyond the end of @a str, out_of_range is
  926.        *  thrown.  The value of the string doesn't change if an error is
  927.        *  thrown.
  928.       */
  929.       basic_string&
  930.       insert(size_type __pos1, const basic_string& __str,
  931.          size_type __pos2, size_type __n)
  932.       { return this->insert(__pos1, __str._M_data()
  933.                 + __str._M_check(__pos2, "basic_string::insert"),
  934.                 __str._M_limit(__pos2, __n)); }
  935.  
  936.       /**
  937.        *  @brief  Insert a C substring.
  938.        *  @param pos  Iterator referencing location in string to insert at.
  939.        *  @param s  The C string to insert.
  940.        *  @param n  The number of characters to insert.
  941.        *  @return  Reference to this string.
  942.        *  @throw  std::length_error  If new length exceeds @c max_size().
  943.        *  @throw  std::out_of_range  If @a pos is beyond the end of this
  944.        *  string.
  945.        *
  946.        *  Inserts the first @a n characters of @a s starting at @a pos.  If
  947.        *  adding characters causes the length to exceed max_size(),
  948.        *  length_error is thrown.  If @a pos is beyond end(), out_of_range is
  949.        *  thrown.  The value of the string doesn't change if an error is
  950.        *  thrown.
  951.       */
  952.       basic_string&
  953.       insert(size_type __pos, const _CharT* __s, size_type __n);
  954.  
  955.       /**
  956.        *  @brief  Insert a C string.
  957.        *  @param pos  Iterator referencing location in string to insert at.
  958.        *  @param s  The C string to insert.
  959.        *  @return  Reference to this string.
  960.        *  @throw  std::length_error  If new length exceeds @c max_size().
  961.        *  @throw  std::out_of_range  If @a pos is beyond the end of this
  962.        *  string.
  963.        *
  964.        *  Inserts the first @a n characters of @a s starting at @a pos.  If
  965.        *  adding characters causes the length to exceed max_size(),
  966.        *  length_error is thrown.  If @a pos is beyond end(), out_of_range is
  967.        *  thrown.  The value of the string doesn't change if an error is
  968.        *  thrown.
  969.       */
  970.       basic_string&
  971.       insert(size_type __pos, const _CharT* __s)
  972.       {
  973.     __glibcxx_requires_string(__s);
  974.     return this->insert(__pos, __s, traits_type::length(__s));
  975.       }
  976.  
  977.       /**
  978.        *  @brief  Insert multiple characters.
  979.        *  @param pos  Index in string to insert at.
  980.        *  @param n  Number of characters to insert
  981.        *  @param c  The character to insert.
  982.        *  @return  Reference to this string.
  983.        *  @throw  std::length_error  If new length exceeds @c max_size().
  984.        *  @throw  std::out_of_range  If @a pos is beyond the end of this
  985.        *  string.
  986.        *
  987.        *  Inserts @a n copies of character @a c starting at index @a pos.  If
  988.        *  adding characters causes the length to exceed max_size(),
  989.        *  length_error is thrown.  If @a pos > length(), out_of_range is
  990.        *  thrown.  The value of the string doesn't change if an error is
  991.        *  thrown.
  992.       */
  993.       basic_string&
  994.       insert(size_type __pos, size_type __n, _CharT __c)
  995.       { return _M_replace_aux(_M_check(__pos, "basic_string::insert"),
  996.                   size_type(0), __n, __c); }
  997.  
  998.       /**
  999.        *  @brief  Insert one character.
  1000.        *  @param p  Iterator referencing position in string to insert at.
  1001.        *  @param c  The character to insert.
  1002.        *  @return  Iterator referencing newly inserted char.
  1003.        *  @throw  std::length_error  If new length exceeds @c max_size().
  1004.        *
  1005.        *  Inserts character @a c at position referenced by @a p.  If adding
  1006.        *  character causes the length to exceed max_size(), length_error is
  1007.        *  thrown.  If @a p is beyond end of string, out_of_range is thrown.
  1008.        *  The value of the string doesn't change if an error is thrown.
  1009.       */
  1010.       iterator
  1011.       insert(iterator __p, _CharT __c)
  1012.       {
  1013.     _GLIBCXX_DEBUG_PEDASSERT(__p >= _M_ibegin() && __p <= _M_iend());
  1014.     const size_type __pos = __p - _M_ibegin();
  1015.     _M_replace_aux(__pos, size_type(0), size_type(1), __c);
  1016.     _M_rep()->_M_set_leaked();
  1017.     return this->_M_ibegin() + __pos;
  1018.       }
  1019.  
  1020.       /**
  1021.        *  @brief  Remove characters.
  1022.        *  @param pos  Index of first character to remove (default 0).
  1023.        *  @param n  Number of characters to remove (default remainder).
  1024.        *  @return  Reference to this string.
  1025.        *  @throw  std::out_of_range  If @a pos is beyond the end of this
  1026.        *  string.
  1027.        *
  1028.        *  Removes @a n characters from this string starting at @a pos.  The
  1029.        *  length of the string is reduced by @a n.  If there are < @a n
  1030.        *  characters to remove, the remainder of the string is truncated.  If
  1031.        *  @a p is beyond end of string, out_of_range is thrown.  The value of
  1032.        *  the string doesn't change if an error is thrown.
  1033.       */
  1034.       basic_string&
  1035.       erase(size_type __pos = 0, size_type __n = npos)
  1036.       { return _M_replace_safe(_M_check(__pos, "basic_string::erase"),
  1037.                    _M_limit(__pos, __n), NULL, size_type(0)); }
  1038.  
  1039.       /**
  1040.        *  @brief  Remove one character.
  1041.        *  @param position  Iterator referencing the character to remove.
  1042.        *  @return  iterator referencing same location after removal.
  1043.        *
  1044.        *  Removes the character at @a position from this string. The value
  1045.        *  of the string doesn't change if an error is thrown.
  1046.       */
  1047.       iterator
  1048.       erase(iterator __position)
  1049.       {
  1050.     _GLIBCXX_DEBUG_PEDASSERT(__position >= _M_ibegin()
  1051.                  && __position < _M_iend());
  1052.     const size_type __pos = __position - _M_ibegin();
  1053.     _M_replace_safe(__pos, size_type(1), NULL, size_type(0));
  1054.     _M_rep()->_M_set_leaked();
  1055.     return _M_ibegin() + __pos;
  1056.       }
  1057.  
  1058.       /**
  1059.        *  @brief  Remove a range of characters.
  1060.        *  @param first  Iterator referencing the first character to remove.
  1061.        *  @param last  Iterator referencing the end of the range.
  1062.        *  @return  Iterator referencing location of first after removal.
  1063.        *
  1064.        *  Removes the characters in the range [first,last) from this string.
  1065.        *  The value of the string doesn't change if an error is thrown.
  1066.       */
  1067.       iterator
  1068.       erase(iterator __first, iterator __last)
  1069.       {
  1070.     _GLIBCXX_DEBUG_PEDASSERT(__first >= _M_ibegin() && __first <= __last
  1071.                  && __last <= _M_iend());
  1072.         const size_type __pos = __first - _M_ibegin();
  1073.     _M_replace_safe(__pos, __last - __first, NULL, size_type(0));
  1074.     _M_rep()->_M_set_leaked();
  1075.     return _M_ibegin() + __pos;
  1076.       }
  1077.  
  1078.       /**
  1079.        *  @brief  Replace characters with value from another string.
  1080.        *  @param pos  Index of first character to replace.
  1081.        *  @param n  Number of characters to be replaced.
  1082.        *  @param str  String to insert.
  1083.        *  @return  Reference to this string.
  1084.        *  @throw  std::out_of_range  If @a pos is beyond the end of this
  1085.        *  string.
  1086.        *  @throw  std::length_error  If new length exceeds @c max_size().
  1087.        *
  1088.        *  Removes the characters in the range [pos,pos+n) from this string.
  1089.        *  In place, the value of @a str is inserted.  If @a pos is beyond end
  1090.        *  of string, out_of_range is thrown.  If the length of the result
  1091.        *  exceeds max_size(), length_error is thrown.  The value of the string
  1092.        *  doesn't change if an error is thrown.
  1093.       */
  1094.       basic_string&
  1095.       replace(size_type __pos, size_type __n, const basic_string& __str)
  1096.       { return this->replace(__pos, __n, __str._M_data(), __str.size()); }
  1097.  
  1098.       /**
  1099.        *  @brief  Replace characters with value from another string.
  1100.        *  @param pos1  Index of first character to replace.
  1101.        *  @param n1  Number of characters to be replaced.
  1102.        *  @param str  String to insert.
  1103.        *  @param pos2  Index of first character of str to use.
  1104.        *  @param n2  Number of characters from str to use.
  1105.        *  @return  Reference to this string.
  1106.        *  @throw  std::out_of_range  If @a pos1 > size() or @a pos2 >
  1107.        *  str.size().
  1108.        *  @throw  std::length_error  If new length exceeds @c max_size().
  1109.        *
  1110.        *  Removes the characters in the range [pos1,pos1 + n) from this
  1111.        *  string.  In place, the value of @a str is inserted.  If @a pos is
  1112.        *  beyond end of string, out_of_range is thrown.  If the length of the
  1113.        *  result exceeds max_size(), length_error is thrown.  The value of the
  1114.        *  string doesn't change if an error is thrown.
  1115.       */
  1116.       basic_string&
  1117.       replace(size_type __pos1, size_type __n1, const basic_string& __str,
  1118.           size_type __pos2, size_type __n2)
  1119.       { return this->replace(__pos1, __n1, __str._M_data()
  1120.                  + __str._M_check(__pos2, "basic_string::replace"),
  1121.                  __str._M_limit(__pos2, __n2)); }
  1122.  
  1123.       /**
  1124.        *  @brief  Replace characters with value of a C substring.
  1125.        *  @param pos  Index of first character to replace.
  1126.        *  @param n1  Number of characters to be replaced.
  1127.        *  @param str  C string to insert.
  1128.        *  @param n2  Number of characters from str to use.
  1129.        *  @return  Reference to this string.
  1130.        *  @throw  std::out_of_range  If @a pos1 > size().
  1131.        *  @throw  std::length_error  If new length exceeds @c max_size().
  1132.        *
  1133.        *  Removes the characters in the range [pos,pos + n1) from this string.
  1134.        *  In place, the first @a n2 characters of @a str are inserted, or all
  1135.        *  of @a str if @a n2 is too large.  If @a pos is beyond end of string,
  1136.        *  out_of_range is thrown.  If the length of result exceeds max_size(),
  1137.        *  length_error is thrown.  The value of the string doesn't change if
  1138.        *  an error is thrown.
  1139.       */
  1140.       basic_string&
  1141.       replace(size_type __pos, size_type __n1, const _CharT* __s,
  1142.           size_type __n2);
  1143.  
  1144.       /**
  1145.        *  @brief  Replace characters with value of a C string.
  1146.        *  @param pos  Index of first character to replace.
  1147.        *  @param n1  Number of characters to be replaced.
  1148.        *  @param str  C string to insert.
  1149.        *  @return  Reference to this string.
  1150.        *  @throw  std::out_of_range  If @a pos > size().
  1151.        *  @throw  std::length_error  If new length exceeds @c max_size().
  1152.        *
  1153.        *  Removes the characters in the range [pos,pos + n1) from this string.
  1154.        *  In place, the first @a n characters of @a str are inserted.  If @a
  1155.        *  pos is beyond end of string, out_of_range is thrown.  If the length
  1156.        *  of result exceeds max_size(), length_error is thrown.  The value of
  1157.        *  the string doesn't change if an error is thrown.
  1158.       */
  1159.       basic_string&
  1160.       replace(size_type __pos, size_type __n1, const _CharT* __s)
  1161.       {
  1162.     __glibcxx_requires_string(__s);
  1163.     return this->replace(__pos, __n1, __s, traits_type::length(__s));
  1164.       }
  1165.  
  1166.       /**
  1167.        *  @brief  Replace characters with multiple characters.
  1168.        *  @param pos  Index of first character to replace.
  1169.        *  @param n1  Number of characters to be replaced.
  1170.        *  @param n2  Number of characters to insert.
  1171.        *  @param c  Character to insert.
  1172.        *  @return  Reference to this string.
  1173.        *  @throw  std::out_of_range  If @a pos > size().
  1174.        *  @throw  std::length_error  If new length exceeds @c max_size().
  1175.        *
  1176.        *  Removes the characters in the range [pos,pos + n1) from this string.
  1177.        *  In place, @a n2 copies of @a c are inserted.  If @a pos is beyond
  1178.        *  end of string, out_of_range is thrown.  If the length of result
  1179.        *  exceeds max_size(), length_error is thrown.  The value of the string
  1180.        *  doesn't change if an error is thrown.
  1181.       */
  1182.       basic_string&
  1183.       replace(size_type __pos, size_type __n1, size_type __n2, _CharT __c)
  1184.       { return _M_replace_aux(_M_check(__pos, "basic_string::replace"),
  1185.                   _M_limit(__pos, __n1), __n2, __c); }
  1186.  
  1187.       /**
  1188.        *  @brief  Replace range of characters with string.
  1189.        *  @param i1  Iterator referencing start of range to replace.
  1190.        *  @param i2  Iterator referencing end of range to replace.
  1191.        *  @param str  String value to insert.
  1192.        *  @return  Reference to this string.
  1193.        *  @throw  std::length_error  If new length exceeds @c max_size().
  1194.        *
  1195.        *  Removes the characters in the range [i1,i2).  In place, the value of
  1196.        *  @a str is inserted.  If the length of result exceeds max_size(),
  1197.        *  length_error is thrown.  The value of the string doesn't change if
  1198.        *  an error is thrown.
  1199.       */
  1200.       basic_string&
  1201.       replace(iterator __i1, iterator __i2, const basic_string& __str)
  1202.       { return this->replace(__i1, __i2, __str._M_data(), __str.size()); }
  1203.  
  1204.       /**
  1205.        *  @brief  Replace range of characters with C substring.
  1206.        *  @param i1  Iterator referencing start of range to replace.
  1207.        *  @param i2  Iterator referencing end of range to replace.
  1208.        *  @param s  C string value to insert.
  1209.        *  @param n  Number of characters from s to insert.
  1210.        *  @return  Reference to this string.
  1211.        *  @throw  std::length_error  If new length exceeds @c max_size().
  1212.        *
  1213.        *  Removes the characters in the range [i1,i2).  In place, the first @a
  1214.        *  n characters of @a s are inserted.  If the length of result exceeds
  1215.        *  max_size(), length_error is thrown.  The value of the string doesn't
  1216.        *  change if an error is thrown.
  1217.       */
  1218.       basic_string&
  1219.       replace(iterator __i1, iterator __i2, const _CharT* __s, size_type __n)
  1220.       {
  1221.     _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1 && __i1 <= __i2
  1222.                  && __i2 <= _M_iend());
  1223.     return this->replace(__i1 - _M_ibegin(), __i2 - __i1, __s, __n);
  1224.       }
  1225.  
  1226.       /**
  1227.        *  @brief  Replace range of characters with C string.
  1228.        *  @param i1  Iterator referencing start of range to replace.
  1229.        *  @param i2  Iterator referencing end of range to replace.
  1230.        *  @param s  C string value to insert.
  1231.        *  @return  Reference to this string.
  1232.        *  @throw  std::length_error  If new length exceeds @c max_size().
  1233.        *
  1234.        *  Removes the characters in the range [i1,i2).  In place, the
  1235.        *  characters of @a s are inserted.  If the length of result exceeds
  1236.        *  max_size(), length_error is thrown.  The value of the string doesn't
  1237.        *  change if an error is thrown.
  1238.       */
  1239.       basic_string&
  1240.       replace(iterator __i1, iterator __i2, const _CharT* __s)
  1241.       {
  1242.     __glibcxx_requires_string(__s);
  1243.     return this->replace(__i1, __i2, __s, traits_type::length(__s));
  1244.       }
  1245.  
  1246.       /**
  1247.        *  @brief  Replace range of characters with multiple characters
  1248.        *  @param i1  Iterator referencing start of range to replace.
  1249.        *  @param i2  Iterator referencing end of range to replace.
  1250.        *  @param n  Number of characters to insert.
  1251.        *  @param c  Character to insert.
  1252.        *  @return  Reference to this string.
  1253.        *  @throw  std::length_error  If new length exceeds @c max_size().
  1254.        *
  1255.        *  Removes the characters in the range [i1,i2).  In place, @a n copies
  1256.        *  of @a c are inserted.  If the length of result exceeds max_size(),
  1257.        *  length_error is thrown.  The value of the string doesn't change if
  1258.        *  an error is thrown.
  1259.       */
  1260.       basic_string&
  1261.       replace(iterator __i1, iterator __i2, size_type __n, _CharT __c)
  1262.       {
  1263.     _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1 && __i1 <= __i2
  1264.                  && __i2 <= _M_iend());
  1265.     return _M_replace_aux(__i1 - _M_ibegin(), __i2 - __i1, __n, __c);
  1266.       }
  1267.  
  1268.       /**
  1269.        *  @brief  Replace range of characters with range.
  1270.        *  @param i1  Iterator referencing start of range to replace.
  1271.        *  @param i2  Iterator referencing end of range to replace.
  1272.        *  @param k1  Iterator referencing start of range to insert.
  1273.        *  @param k2  Iterator referencing end of range to insert.
  1274.        *  @return  Reference to this string.
  1275.        *  @throw  std::length_error  If new length exceeds @c max_size().
  1276.        *
  1277.        *  Removes the characters in the range [i1,i2).  In place, characters
  1278.        *  in the range [k1,k2) are inserted.  If the length of result exceeds
  1279.        *  max_size(), length_error is thrown.  The value of the string doesn't
  1280.        *  change if an error is thrown.
  1281.       */
  1282.       template<class _InputIterator>
  1283.         basic_string&
  1284.         replace(iterator __i1, iterator __i2,
  1285.         _InputIterator __k1, _InputIterator __k2)
  1286.         {
  1287.       _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1 && __i1 <= __i2
  1288.                    && __i2 <= _M_iend());
  1289.       __glibcxx_requires_valid_range(__k1, __k2);
  1290.       typedef typename _Is_integer<_InputIterator>::_Integral _Integral;
  1291.       return _M_replace_dispatch(__i1, __i2, __k1, __k2, _Integral());
  1292.     }
  1293.  
  1294.       // Specializations for the common case of pointer and iterator:
  1295.       // useful to avoid the overhead of temporary buffering in _M_replace.
  1296.       basic_string&
  1297.         replace(iterator __i1, iterator __i2, _CharT* __k1, _CharT* __k2)
  1298.         {
  1299.       _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1 && __i1 <= __i2
  1300.                    && __i2 <= _M_iend());
  1301.       __glibcxx_requires_valid_range(__k1, __k2);
  1302.       return this->replace(__i1 - _M_ibegin(), __i2 - __i1,
  1303.                    __k1, __k2 - __k1);
  1304.     }
  1305.  
  1306.       basic_string&
  1307.         replace(iterator __i1, iterator __i2,
  1308.         const _CharT* __k1, const _CharT* __k2)
  1309.         {
  1310.       _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1 && __i1 <= __i2
  1311.                    && __i2 <= _M_iend());
  1312.       __glibcxx_requires_valid_range(__k1, __k2);
  1313.       return this->replace(__i1 - _M_ibegin(), __i2 - __i1,
  1314.                    __k1, __k2 - __k1);
  1315.     }
  1316.  
  1317.       basic_string&
  1318.         replace(iterator __i1, iterator __i2, iterator __k1, iterator __k2)
  1319.         {
  1320.       _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1 && __i1 <= __i2
  1321.                    && __i2 <= _M_iend());
  1322.       __glibcxx_requires_valid_range(__k1, __k2);
  1323.       return this->replace(__i1 - _M_ibegin(), __i2 - __i1,
  1324.                    __k1.base(), __k2 - __k1);
  1325.     }
  1326.  
  1327.       basic_string&
  1328.         replace(iterator __i1, iterator __i2,
  1329.         const_iterator __k1, const_iterator __k2)
  1330.         {
  1331.       _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1 && __i1 <= __i2
  1332.                    && __i2 <= _M_iend());
  1333.       __glibcxx_requires_valid_range(__k1, __k2);
  1334.       return this->replace(__i1 - _M_ibegin(), __i2 - __i1,
  1335.                    __k1.base(), __k2 - __k1);
  1336.     }
  1337.  
  1338.     private:
  1339.       template<class _Integer>
  1340.     basic_string&
  1341.     _M_replace_dispatch(iterator __i1, iterator __i2, _Integer __n,
  1342.                 _Integer __val, __true_type)
  1343.         { return _M_replace_aux(__i1 - _M_ibegin(), __i2 - __i1, __n, __val); }
  1344.  
  1345.       template<class _InputIterator>
  1346.     basic_string&
  1347.     _M_replace_dispatch(iterator __i1, iterator __i2, _InputIterator __k1,
  1348.                 _InputIterator __k2, __false_type);
  1349.  
  1350.       basic_string&
  1351.       _M_replace_aux(size_type __pos1, size_type __n1, size_type __n2,
  1352.              _CharT __c)
  1353.       {
  1354.     if (this->max_size() - (this->size() - __n1) < __n2)
  1355.       __throw_length_error(__N("basic_string::_M_replace_aux"));
  1356.     _M_mutate(__pos1, __n1, __n2);
  1357.     if (__n2 == 1)
  1358.       _M_data()[__pos1] = __c;
  1359.     else if (__n2)
  1360.       traits_type::assign(_M_data() + __pos1, __n2, __c);
  1361.     return *this;
  1362.       }
  1363.  
  1364.       basic_string&
  1365.       _M_replace_safe(size_type __pos1, size_type __n1, const _CharT* __s,
  1366.               size_type __n2)
  1367.       {
  1368.     _M_mutate(__pos1, __n1, __n2);
  1369.     if (__n2 == 1)
  1370.       _M_data()[__pos1] = *__s;
  1371.     else if (__n2)
  1372.       traits_type::copy(_M_data() + __pos1, __s, __n2);
  1373.     return *this;
  1374.       }
  1375.  
  1376.       // _S_construct_aux is used to implement the 21.3.1 para 15 which
  1377.       // requires special behaviour if _InIter is an integral type
  1378.       template<class _InIterator>
  1379.         static _CharT*
  1380.         _S_construct_aux(_InIterator __beg, _InIterator __end,
  1381.              const _Alloc& __a, __false_type)
  1382.     {
  1383.           typedef typename iterator_traits<_InIterator>::iterator_category _Tag;
  1384.           return _S_construct(__beg, __end, __a, _Tag());
  1385.     }
  1386.  
  1387.       template<class _InIterator>
  1388.         static _CharT*
  1389.         _S_construct_aux(_InIterator __beg, _InIterator __end,
  1390.              const _Alloc& __a, __true_type)
  1391.     { return _S_construct(static_cast<size_type>(__beg),
  1392.                   static_cast<value_type>(__end), __a); }
  1393.  
  1394.       template<class _InIterator>
  1395.         static _CharT*
  1396.         _S_construct(_InIterator __beg, _InIterator __end, const _Alloc& __a)
  1397.     {
  1398.       typedef typename _Is_integer<_InIterator>::_Integral _Integral;
  1399.       return _S_construct_aux(__beg, __end, __a, _Integral());
  1400.         }
  1401.  
  1402.       // For Input Iterators, used in istreambuf_iterators, etc.
  1403.       template<class _InIterator>
  1404.         static _CharT*
  1405.          _S_construct(_InIterator __beg, _InIterator __end, const _Alloc& __a,
  1406.               input_iterator_tag);
  1407.  
  1408.       // For forward_iterators up to random_access_iterators, used for
  1409.       // string::iterator, _CharT*, etc.
  1410.       template<class _FwdIterator>
  1411.         static _CharT*
  1412.         _S_construct(_FwdIterator __beg, _FwdIterator __end, const _Alloc& __a,
  1413.              forward_iterator_tag);
  1414.  
  1415.       static _CharT*
  1416.       _S_construct(size_type __req, _CharT __c, const _Alloc& __a);
  1417.  
  1418.     public:
  1419.  
  1420.       /**
  1421.        *  @brief  Copy substring into C string.
  1422.        *  @param s  C string to copy value into.
  1423.        *  @param n  Number of characters to copy.
  1424.        *  @param pos  Index of first character to copy.
  1425.        *  @return  Number of characters actually copied
  1426.        *  @throw  std::out_of_range  If pos > size().
  1427.        *
  1428.        *  Copies up to @a n characters starting at @a pos into the C string @a
  1429.        *  s.  If @a pos is greater than size(), out_of_range is thrown.
  1430.       */
  1431.       size_type
  1432.       copy(_CharT* __s, size_type __n, size_type __pos = 0) const;
  1433.  
  1434.       /**
  1435.        *  @brief  Swap contents with another string.
  1436.        *  @param s  String to swap with.
  1437.        *
  1438.        *  Exchanges the contents of this string with that of @a s in constant
  1439.        *  time.
  1440.       */
  1441.       void
  1442.       swap(basic_string& __s);
  1443.  
  1444.       // String operations:
  1445.       /**
  1446.        *  @brief  Return const pointer to null-terminated contents.
  1447.        *
  1448.        *  This is a handle to internal data.  Do not modify or dire things may
  1449.        *  happen.
  1450.       */
  1451.       const _CharT*
  1452.       c_str() const { return _M_data(); }
  1453.  
  1454.       /**
  1455.        *  @brief  Return const pointer to contents.
  1456.        *
  1457.        *  This is a handle to internal data.  Do not modify or dire things may
  1458.        *  happen.
  1459.       */
  1460.       const _CharT*
  1461.       data() const { return _M_data(); }
  1462.  
  1463.       /**
  1464.        *  @brief  Return copy of allocator used to construct this string.
  1465.       */
  1466.       allocator_type
  1467.       get_allocator() const { return _M_dataplus; }
  1468.  
  1469.       /**
  1470.        *  @brief  Find position of a C substring.
  1471.        *  @param s  C string to locate.
  1472.        *  @param pos  Index of character to search from.
  1473.        *  @param n  Number of characters from @a s to search for.
  1474.        *  @return  Index of start of first occurrence.
  1475.        *
  1476.        *  Starting from @a pos, searches forward for the first @a n characters
  1477.        *  in @a s within this string.  If found, returns the index where it
  1478.        *  begins.  If not found, returns npos.
  1479.       */
  1480.       size_type
  1481.       find(const _CharT* __s, size_type __pos, size_type __n) const;
  1482.  
  1483.       /**
  1484.        *  @brief  Find position of a string.
  1485.        *  @param str  String to locate.
  1486.        *  @param pos  Index of character to search from (default 0).
  1487.        *  @return  Index of start of first occurrence.
  1488.        *
  1489.        *  Starting from @a pos, searches forward for value of @a str within
  1490.        *  this string.  If found, returns the index where it begins.  If not
  1491.        *  found, returns npos.
  1492.       */
  1493.       size_type
  1494.       find(const basic_string& __str, size_type __pos = 0) const
  1495.       { return this->find(__str.data(), __pos, __str.size()); }
  1496.  
  1497.       /**
  1498.        *  @brief  Find position of a C string.
  1499.        *  @param s  C string to locate.
  1500.        *  @param pos  Index of character to search from (default 0).
  1501.        *  @return  Index of start of first occurrence.
  1502.        *
  1503.        *  Starting from @a pos, searches forward for the value of @a s within
  1504.        *  this string.  If found, returns the index where it begins.  If not
  1505.        *  found, returns npos.
  1506.       */
  1507.       size_type
  1508.       find(const _CharT* __s, size_type __pos = 0) const
  1509.       {
  1510.     __glibcxx_requires_string(__s);
  1511.     return this->find(__s, __pos, traits_type::length(__s));
  1512.       }
  1513.  
  1514.       /**
  1515.        *  @brief  Find position of a character.
  1516.        *  @param c  Character to locate.
  1517.        *  @param pos  Index of character to search from (default 0).
  1518.        *  @return  Index of first occurrence.
  1519.        *
  1520.        *  Starting from @a pos, searches forward for @a c within this string.
  1521.        *  If found, returns the index where it was found.  If not found,
  1522.        *  returns npos.
  1523.       */
  1524.       size_type
  1525.       find(_CharT __c, size_type __pos = 0) const;
  1526.  
  1527.       /**
  1528.        *  @brief  Find last position of a string.
  1529.        *  @param str  String to locate.
  1530.        *  @param pos  Index of character to search back from (default end).
  1531.        *  @return  Index of start of last occurrence.
  1532.        *
  1533.        *  Starting from @a pos, searches backward for value of @a str within
  1534.        *  this string.  If found, returns the index where it begins.  If not
  1535.        *  found, returns npos.
  1536.       */
  1537.       size_type
  1538.       rfind(const basic_string& __str, size_type __pos = npos) const
  1539.       { return this->rfind(__str.data(), __pos, __str.size()); }
  1540.  
  1541.       /**
  1542.        *  @brief  Find last position of a C substring.
  1543.        *  @param s  C string to locate.
  1544.        *  @param pos  Index of character to search back from.
  1545.        *  @param n  Number of characters from s to search for.
  1546.        *  @return  Index of start of last occurrence.
  1547.        *
  1548.        *  Starting from @a pos, searches backward for the first @a n
  1549.        *  characters in @a s within this string.  If found, returns the index
  1550.        *  where it begins.  If not found, returns npos.
  1551.       */
  1552.       size_type
  1553.       rfind(const _CharT* __s, size_type __pos, size_type __n) const;
  1554.  
  1555.       /**
  1556.        *  @brief  Find last position of a C string.
  1557.        *  @param s  C string to locate.
  1558.        *  @param pos  Index of character to start search at (default 0).
  1559.        *  @return  Index of start of  last occurrence.
  1560.        *
  1561.        *  Starting from @a pos, searches backward for the value of @a s within
  1562.        *  this string.  If found, returns the index where it begins.  If not
  1563.        *  found, returns npos.
  1564.       */
  1565.       size_type
  1566.       rfind(const _CharT* __s, size_type __pos = npos) const
  1567.       {
  1568.     __glibcxx_requires_string(__s);
  1569.     return this->rfind(__s, __pos, traits_type::length(__s));
  1570.       }
  1571.  
  1572.       /**
  1573.        *  @brief  Find last position of a character.
  1574.        *  @param c  Character to locate.
  1575.        *  @param pos  Index of character to search back from (default 0).
  1576.        *  @return  Index of last occurrence.
  1577.        *
  1578.        *  Starting from @a pos, searches backward for @a c within this string.
  1579.        *  If found, returns the index where it was found.  If not found,
  1580.        *  returns npos.
  1581.       */
  1582.       size_type
  1583.       rfind(_CharT __c, size_type __pos = npos) const;
  1584.  
  1585.       /**
  1586.        *  @brief  Find position of a character of string.
  1587.        *  @param str  String containing characters to locate.
  1588.        *  @param pos  Index of character to search from (default 0).
  1589.        *  @return  Index of first occurrence.
  1590.        *
  1591.        *  Starting from @a pos, searches forward for one of the characters of
  1592.        *  @a str within this string.  If found, returns the index where it was
  1593.        *  found.  If not found, returns npos.
  1594.       */
  1595.       size_type
  1596.       find_first_of(const basic_string& __str, size_type __pos = 0) const
  1597.       { return this->find_first_of(__str.data(), __pos, __str.size()); }
  1598.  
  1599.       /**
  1600.        *  @brief  Find position of a character of C substring.
  1601.        *  @param s  String containing characters to locate.
  1602.        *  @param pos  Index of character to search from (default 0).
  1603.        *  @param n  Number of characters from s to search for.
  1604.        *  @return  Index of first occurrence.
  1605.        *
  1606.        *  Starting from @a pos, searches forward for one of the first @a n
  1607.        *  characters of @a s within this string.  If found, returns the index
  1608.        *  where it was found.  If not found, returns npos.
  1609.       */
  1610.       size_type
  1611.       find_first_of(const _CharT* __s, size_type __pos, size_type __n) const;
  1612.  
  1613.       /**
  1614.        *  @brief  Find position of a character of C string.
  1615.        *  @param s  String containing characters to locate.
  1616.        *  @param pos  Index of character to search from (default 0).
  1617.        *  @return  Index of first occurrence.
  1618.        *
  1619.        *  Starting from @a pos, searches forward for one of the characters of
  1620.        *  @a s within this string.  If found, returns the index where it was
  1621.        *  found.  If not found, returns npos.
  1622.       */
  1623.       size_type
  1624.       find_first_of(const _CharT* __s, size_type __pos = 0) const
  1625.       {
  1626.     __glibcxx_requires_string(__s);
  1627.     return this->find_first_of(__s, __pos, traits_type::length(__s));
  1628.       }
  1629.  
  1630.       /**
  1631.        *  @brief  Find position of a character.
  1632.        *  @param c  Character to locate.
  1633.        *  @param pos  Index of character to search from (default 0).
  1634.        *  @return  Index of first occurrence.
  1635.        *
  1636.        *  Starting from @a pos, searches forward for the character @a c within
  1637.        *  this string.  If found, returns the index where it was found.  If
  1638.        *  not found, returns npos.
  1639.        *
  1640.        *  Note: equivalent to find(c, pos).
  1641.       */
  1642.       size_type
  1643.       find_first_of(_CharT __c, size_type __pos = 0) const
  1644.       { return this->find(__c, __pos); }
  1645.  
  1646.       /**
  1647.        *  @brief  Find last position of a character of string.
  1648.        *  @param str  String containing characters to locate.
  1649.        *  @param pos  Index of character to search back from (default end).
  1650.        *  @return  Index of last occurrence.
  1651.        *
  1652.        *  Starting from @a pos, searches backward for one of the characters of
  1653.        *  @a str within this string.  If found, returns the index where it was
  1654.        *  found.  If not found, returns npos.
  1655.       */
  1656.       size_type
  1657.       find_last_of(const basic_string& __str, size_type __pos = npos) const
  1658.       { return this->find_last_of(__str.data(), __pos, __str.size()); }
  1659.  
  1660.       /**
  1661.        *  @brief  Find last position of a character of C substring.
  1662.        *  @param s  C string containing characters to locate.
  1663.        *  @param pos  Index of character to search back from (default end).
  1664.        *  @param n  Number of characters from s to search for.
  1665.        *  @return  Index of last occurrence.
  1666.        *
  1667.        *  Starting from @a pos, searches backward for one of the first @a n
  1668.        *  characters of @a s within this string.  If found, returns the index
  1669.        *  where it was found.  If not found, returns npos.
  1670.       */
  1671.       size_type
  1672.       find_last_of(const _CharT* __s, size_type __pos, size_type __n) const;
  1673.  
  1674.       /**
  1675.        *  @brief  Find last position of a character of C string.
  1676.        *  @param s  C string containing characters to locate.
  1677.        *  @param pos  Index of character to search back from (default end).
  1678.        *  @return  Index of last occurrence.
  1679.        *
  1680.        *  Starting from @a pos, searches backward for one of the characters of
  1681.        *  @a s within this string.  If found, returns the index where it was
  1682.        *  found.  If not found, returns npos.
  1683.       */
  1684.       size_type
  1685.       find_last_of(const _CharT* __s, size_type __pos = npos) const
  1686.       {
  1687.     __glibcxx_requires_string(__s);
  1688.     return this->find_last_of(__s, __pos, traits_type::length(__s));
  1689.       }
  1690.  
  1691.       /**
  1692.        *  @brief  Find last position of a character.
  1693.        *  @param c  Character to locate.
  1694.        *  @param pos  Index of character to search back from (default 0).
  1695.        *  @return  Index of last occurrence.
  1696.        *
  1697.        *  Starting from @a pos, searches backward for @a c within this string.
  1698.        *  If found, returns the index where it was found.  If not found,
  1699.        *  returns npos.
  1700.        *
  1701.        *  Note: equivalent to rfind(c, pos).
  1702.       */
  1703.       size_type
  1704.       find_last_of(_CharT __c, size_type __pos = npos) const
  1705.       { return this->rfind(__c, __pos); }
  1706.  
  1707.       /**
  1708.        *  @brief  Find position of a character not in string.
  1709.        *  @param str  String containing characters to avoid.
  1710.        *  @param pos  Index of character to search from (default 0).
  1711.        *  @return  Index of first occurrence.
  1712.        *
  1713.        *  Starting from @a pos, searches forward for a character not contained
  1714.        *  in @a str within this string.  If found, returns the index where it
  1715.        *  was found.  If not found, returns npos.
  1716.       */
  1717.       size_type
  1718.       find_first_not_of(const basic_string& __str, size_type __pos = 0) const
  1719.       { return this->find_first_not_of(__str.data(), __pos, __str.size()); }
  1720.  
  1721.       /**
  1722.        *  @brief  Find position of a character not in C substring.
  1723.        *  @param s  C string containing characters to avoid.
  1724.        *  @param pos  Index of character to search from (default 0).
  1725.        *  @param n  Number of characters from s to consider.
  1726.        *  @return  Index of first occurrence.
  1727.        *
  1728.        *  Starting from @a pos, searches forward for a character not contained
  1729.        *  in the first @a n characters of @a s within this string.  If found,
  1730.        *  returns the index where it was found.  If not found, returns npos.
  1731.       */
  1732.       size_type
  1733.       find_first_not_of(const _CharT* __s, size_type __pos,
  1734.             size_type __n) const;
  1735.  
  1736.       /**
  1737.        *  @brief  Find position of a character not in C string.
  1738.        *  @param s  C string containing characters to avoid.
  1739.        *  @param pos  Index of character to search from (default 0).
  1740.        *  @return  Index of first occurrence.
  1741.        *
  1742.        *  Starting from @a pos, searches forward for a character not contained
  1743.        *  in @a s within this string.  If found, returns the index where it
  1744.        *  was found.  If not found, returns npos.
  1745.       */
  1746.       size_type
  1747.       find_first_not_of(const _CharT* __s, size_type __pos = 0) const
  1748.       {
  1749.     __glibcxx_requires_string(__s);
  1750.     return this->find_first_not_of(__s, __pos, traits_type::length(__s));
  1751.       }
  1752.  
  1753.       /**
  1754.        *  @brief  Find position of a different character.
  1755.        *  @param c  Character to avoid.
  1756.        *  @param pos  Index of character to search from (default 0).
  1757.        *  @return  Index of first occurrence.
  1758.        *
  1759.        *  Starting from @a pos, searches forward for a character other than @a c
  1760.        *  within this string.  If found, returns the index where it was found.
  1761.        *  If not found, returns npos.
  1762.       */
  1763.       size_type
  1764.       find_first_not_of(_CharT __c, size_type __pos = 0) const;
  1765.  
  1766.       /**
  1767.        *  @brief  Find last position of a character not in string.
  1768.        *  @param str  String containing characters to avoid.
  1769.        *  @param pos  Index of character to search from (default 0).
  1770.        *  @return  Index of first occurrence.
  1771.        *
  1772.        *  Starting from @a pos, searches backward for a character not
  1773.        *  contained in @a str within this string.  If found, returns the index
  1774.        *  where it was found.  If not found, returns npos.
  1775.       */
  1776.       size_type
  1777.       find_last_not_of(const basic_string& __str, size_type __pos = npos) const
  1778.       { return this->find_last_not_of(__str.data(), __pos, __str.size()); }
  1779.  
  1780.       /**
  1781.        *  @brief  Find last position of a character not in C substring.
  1782.        *  @param s  C string containing characters to avoid.
  1783.        *  @param pos  Index of character to search from (default 0).
  1784.        *  @param n  Number of characters from s to consider.
  1785.        *  @return  Index of first occurrence.
  1786.        *
  1787.        *  Starting from @a pos, searches backward for a character not
  1788.        *  contained in the first @a n characters of @a s within this string.
  1789.        *  If found, returns the index where it was found.  If not found,
  1790.        *  returns npos.
  1791.       */
  1792.       size_type
  1793.       find_last_not_of(const _CharT* __s, size_type __pos,
  1794.                size_type __n) const;
  1795.       /**
  1796.        *  @brief  Find position of a character not in C string.
  1797.        *  @param s  C string containing characters to avoid.
  1798.        *  @param pos  Index of character to search from (default 0).
  1799.        *  @return  Index of first occurrence.
  1800.        *
  1801.        *  Starting from @a pos, searches backward for a character not
  1802.        *  contained in @a s within this string.  If found, returns the index
  1803.        *  where it was found.  If not found, returns npos.
  1804.       */
  1805.       size_type
  1806.       find_last_not_of(const _CharT* __s, size_type __pos = npos) const
  1807.       {
  1808.     __glibcxx_requires_string(__s);
  1809.     return this->find_last_not_of(__s, __pos, traits_type::length(__s));
  1810.       }
  1811.  
  1812.       /**
  1813.        *  @brief  Find last position of a different character.
  1814.        *  @param c  Character to avoid.
  1815.        *  @param pos  Index of character to search from (default 0).
  1816.        *  @return  Index of first occurrence.
  1817.        *
  1818.        *  Starting from @a pos, searches backward for a character other than
  1819.        *  @a c within this string.  If found, returns the index where it was
  1820.        *  found.  If not found, returns npos.
  1821.       */
  1822.       size_type
  1823.       find_last_not_of(_CharT __c, size_type __pos = npos) const;
  1824.  
  1825.       /**
  1826.        *  @brief  Get a substring.
  1827.        *  @param pos  Index of first character (default 0).
  1828.        *  @param n  Number of characters in substring (default remainder).
  1829.        *  @return  The new string.
  1830.        *  @throw  std::out_of_range  If pos > size().
  1831.        *
  1832.        *  Construct and return a new string using the @a n characters starting
  1833.        *  at @a pos.  If the string is too short, use the remainder of the
  1834.        *  characters.  If @a pos is beyond the end of the string, out_of_range
  1835.        *  is thrown.
  1836.       */
  1837.       basic_string
  1838.       substr(size_type __pos = 0, size_type __n = npos) const
  1839.       { return basic_string(*this,
  1840.                 _M_check(__pos, "basic_string::substr"), __n); }
  1841.  
  1842.       /**
  1843.        *  @brief  Compare to a string.
  1844.        *  @param str  String to compare against.
  1845.        *  @return  Integer < 0, 0, or > 0.
  1846.        *
  1847.        *  Returns an integer < 0 if this string is ordered before @a str, 0 if
  1848.        *  their values are equivalent, or > 0 if this string is ordered after
  1849.        *  @a str.  If the lengths of @a str and this string are different, the
  1850.        *  shorter one is ordered first.  If they are the same, returns the
  1851.        *  result of traits::compare(data(),str.data(),size());
  1852.       */
  1853.       int
  1854.       compare(const basic_string& __str) const
  1855.       {
  1856.     const size_type __size = this->size();
  1857.     const size_type __osize = __str.size();
  1858.     const size_type __len = std::min(__size, __osize);
  1859.  
  1860.     int __r = traits_type::compare(_M_data(), __str.data(), __len);
  1861.     if (!__r)
  1862.       __r =  __size - __osize;
  1863.     return __r;
  1864.       }
  1865.  
  1866.       /**
  1867.        *  @brief  Compare substring to a string.
  1868.        *  @param pos  Index of first character of substring.
  1869.        *  @param n  Number of characters in substring.
  1870.        *  @param str  String to compare against.
  1871.        *  @return  Integer < 0, 0, or > 0.
  1872.        *
  1873.        *  Form the substring of this string from the @a n characters starting
  1874.        *  at @a pos.  Returns an integer < 0 if the substring is ordered
  1875.        *  before @a str, 0 if their values are equivalent, or > 0 if the
  1876.        *  substring is ordered after @a str.  If the lengths @a of str and the
  1877.        *  substring are different, the shorter one is ordered first.  If they
  1878.        *  are the same, returns the result of
  1879.        *  traits::compare(substring.data(),str.data(),size());
  1880.       */
  1881.       int
  1882.       compare(size_type __pos, size_type __n, const basic_string& __str) const;
  1883.  
  1884.       /**
  1885.        *  @brief  Compare substring to a substring.
  1886.        *  @param pos1  Index of first character of substring.
  1887.        *  @param n1  Number of characters in substring.
  1888.        *  @param str  String to compare against.
  1889.        *  @param pos2  Index of first character of substring of str.
  1890.        *  @param n2  Number of characters in substring of str.
  1891.        *  @return  Integer < 0, 0, or > 0.
  1892.        *
  1893.        *  Form the substring of this string from the @a n1 characters starting
  1894.        *  at @a pos1.  Form the substring of @a str from the @a n2 characters
  1895.        *  starting at @a pos2.  Returns an integer < 0 if this substring is
  1896.        *  ordered before the substring of @a str, 0 if their values are
  1897.        *  equivalent, or > 0 if this substring is ordered after the substring
  1898.        *  of @a str.  If the lengths of the substring of @a str and this
  1899.        *  substring are different, the shorter one is ordered first.  If they
  1900.        *  are the same, returns the result of
  1901.        *  traits::compare(substring.data(),str.substr(pos2,n2).data(),size());
  1902.       */
  1903.       int
  1904.       compare(size_type __pos1, size_type __n1, const basic_string& __str,
  1905.           size_type __pos2, size_type __n2) const;
  1906.  
  1907.       /**
  1908.        *  @brief  Compare to a C string.
  1909.        *  @param s  C string to compare against.
  1910.        *  @return  Integer < 0, 0, or > 0.
  1911.        *
  1912.        *  Returns an integer < 0 if this string is ordered before @a s, 0 if
  1913.        *  their values are equivalent, or > 0 if this string is ordered after
  1914.        *  @a s.  If the lengths of @a s and this string are different, the
  1915.        *  shorter one is ordered first.  If they are the same, returns the
  1916.        *  result of traits::compare(data(),s,size());
  1917.       */
  1918.       int
  1919.       compare(const _CharT* __s) const;
  1920.  
  1921.       // _GLIBCXX_RESOLVE_LIB_DEFECTS
  1922.       // 5 String::compare specification questionable
  1923.       /**
  1924.        *  @brief  Compare substring to a C string.
  1925.        *  @param pos  Index of first character of substring.
  1926.        *  @param n1  Number of characters in substring.
  1927.        *  @param s  C string to compare against.
  1928.        *  @return  Integer < 0, 0, or > 0.
  1929.        *
  1930.        *  Form the substring of this string from the @a n1 characters starting
  1931.        *  at @a pos.  Returns an integer < 0 if the substring is ordered
  1932.        *  before @a s, 0 if their values are equivalent, or > 0 if the
  1933.        *  substring is ordered after @a s.  If the lengths of @a s and the
  1934.        *  substring are different, the shorter one is ordered first.  If they
  1935.        *  are the same, returns the result of
  1936.        *  traits::compare(substring.data(),s,size());
  1937.       */
  1938.       int
  1939.       compare(size_type __pos, size_type __n1, const _CharT* __s) const;
  1940.  
  1941.       /**
  1942.        *  @brief  Compare substring against a character array.
  1943.        *  @param pos1  Index of first character of substring.
  1944.        *  @param n1  Number of characters in substring.
  1945.        *  @param s  character array to compare against.
  1946.        *  @param n2  Number of characters of s.
  1947.        *  @return  Integer < 0, 0, or > 0.
  1948.        *
  1949.        *  Form the substring of this string from the @a n1 characters starting
  1950.        *  at @a pos1.  Form a string from the first @a n2 characters of @a s.
  1951.        *  Returns an integer < 0 if this substring is ordered before the string
  1952.        *  from @a s, 0 if their values are equivalent, or > 0 if this substring
  1953.        *  is ordered after the string from @a s. If the lengths of this
  1954.        *  substring and @a n2 are different, the shorter one is ordered first.
  1955.        *  If they are the same, returns the result of
  1956.        *  traits::compare(substring.data(),s,size());
  1957.        *
  1958.        *  NB: s must have at least n2 characters, '\0' has no special
  1959.        *  meaning.
  1960.       */
  1961.       int
  1962.       compare(size_type __pos, size_type __n1, const _CharT* __s,
  1963.           size_type __n2) const;
  1964.   };
  1965.  
  1966.  
  1967.   template<typename _CharT, typename _Traits, typename _Alloc>
  1968.     inline basic_string<_CharT, _Traits, _Alloc>::
  1969.     basic_string()
  1970.     : _M_dataplus(_S_empty_rep()._M_refdata(), _Alloc()) { }
  1971.  
  1972.   // operator+
  1973.   /**
  1974.    *  @brief  Concatenate two strings.
  1975.    *  @param lhs  First string.
  1976.    *  @param rhs  Last string.
  1977.    *  @return  New string with value of @a lhs followed by @a rhs.
  1978.    */
  1979.   template<typename _CharT, typename _Traits, typename _Alloc>
  1980.     basic_string<_CharT, _Traits, _Alloc>
  1981.     operator+(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
  1982.           const basic_string<_CharT, _Traits, _Alloc>& __rhs)
  1983.     {
  1984.       basic_string<_CharT, _Traits, _Alloc> __str(__lhs);
  1985.       __str.append(__rhs);
  1986.       return __str;
  1987.     }
  1988.  
  1989.   /**
  1990.    *  @brief  Concatenate C string and string.
  1991.    *  @param lhs  First string.
  1992.    *  @param rhs  Last string.
  1993.    *  @return  New string with value of @a lhs followed by @a rhs.
  1994.    */
  1995.   template<typename _CharT, typename _Traits, typename _Alloc>
  1996.     basic_string<_CharT,_Traits,_Alloc>
  1997.     operator+(const _CharT* __lhs,
  1998.           const basic_string<_CharT,_Traits,_Alloc>& __rhs);
  1999.  
  2000.   /**
  2001.    *  @brief  Concatenate character and string.
  2002.    *  @param lhs  First string.
  2003.    *  @param rhs  Last string.
  2004.    *  @return  New string with @a lhs followed by @a rhs.
  2005.    */
  2006.   template<typename _CharT, typename _Traits, typename _Alloc>
  2007.     basic_string<_CharT,_Traits,_Alloc>
  2008.     operator+(_CharT __lhs, const basic_string<_CharT,_Traits,_Alloc>& __rhs);
  2009.  
  2010.   /**
  2011.    *  @brief  Concatenate string and C string.
  2012.    *  @param lhs  First string.
  2013.    *  @param rhs  Last string.
  2014.    *  @return  New string with @a lhs followed by @a rhs.
  2015.    */
  2016.   template<typename _CharT, typename _Traits, typename _Alloc>
  2017.     inline basic_string<_CharT, _Traits, _Alloc>
  2018.     operator+(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
  2019.          const _CharT* __rhs)
  2020.     {
  2021.       basic_string<_CharT, _Traits, _Alloc> __str(__lhs);
  2022.       __str.append(__rhs);
  2023.       return __str;
  2024.     }
  2025.  
  2026.   /**
  2027.    *  @brief  Concatenate string and character.
  2028.    *  @param lhs  First string.
  2029.    *  @param rhs  Last string.
  2030.    *  @return  New string with @a lhs followed by @a rhs.
  2031.    */
  2032.   template<typename _CharT, typename _Traits, typename _Alloc>
  2033.     inline basic_string<_CharT, _Traits, _Alloc>
  2034.     operator+(const basic_string<_CharT, _Traits, _Alloc>& __lhs, _CharT __rhs)
  2035.     {
  2036.       typedef basic_string<_CharT, _Traits, _Alloc>    __string_type;
  2037.       typedef typename __string_type::size_type        __size_type;
  2038.       __string_type __str(__lhs);
  2039.       __str.append(__size_type(1), __rhs);
  2040.       return __str;
  2041.     }
  2042.  
  2043.   // operator ==
  2044.   /**
  2045.    *  @brief  Test equivalence of two strings.
  2046.    *  @param lhs  First string.
  2047.    *  @param rhs  Second string.
  2048.    *  @return  True if @a lhs.compare(@a rhs) == 0.  False otherwise.
  2049.    */
  2050.   template<typename _CharT, typename _Traits, typename _Alloc>
  2051.     inline bool
  2052.     operator==(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
  2053.            const basic_string<_CharT, _Traits, _Alloc>& __rhs)
  2054.     { return __lhs.compare(__rhs) == 0; }
  2055.  
  2056.   /**
  2057.    *  @brief  Test equivalence of C string and string.
  2058.    *  @param lhs  C string.
  2059.    *  @param rhs  String.
  2060.    *  @return  True if @a rhs.compare(@a lhs) == 0.  False otherwise.
  2061.    */
  2062.   template<typename _CharT, typename _Traits, typename _Alloc>
  2063.     inline bool
  2064.     operator==(const _CharT* __lhs,
  2065.            const basic_string<_CharT, _Traits, _Alloc>& __rhs)
  2066.     { return __rhs.compare(__lhs) == 0; }
  2067.  
  2068.   /**
  2069.    *  @brief  Test equivalence of string and C string.
  2070.    *  @param lhs  String.
  2071.    *  @param rhs  C string.
  2072.    *  @return  True if @a lhs.compare(@a rhs) == 0.  False otherwise.
  2073.    */
  2074.   template<typename _CharT, typename _Traits, typename _Alloc>
  2075.     inline bool
  2076.     operator==(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
  2077.            const _CharT* __rhs)
  2078.     { return __lhs.compare(__rhs) == 0; }
  2079.  
  2080.   // operator !=
  2081.   /**
  2082.    *  @brief  Test difference of two strings.
  2083.    *  @param lhs  First string.
  2084.    *  @param rhs  Second string.
  2085.    *  @return  True if @a lhs.compare(@a rhs) != 0.  False otherwise.
  2086.    */
  2087.   template<typename _CharT, typename _Traits, typename _Alloc>
  2088.     inline bool
  2089.     operator!=(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
  2090.            const basic_string<_CharT, _Traits, _Alloc>& __rhs)
  2091.     { return __rhs.compare(__lhs) != 0; }
  2092.  
  2093.   /**
  2094.    *  @brief  Test difference of C string and string.
  2095.    *  @param lhs  C string.
  2096.    *  @param rhs  String.
  2097.    *  @return  True if @a rhs.compare(@a lhs) != 0.  False otherwise.
  2098.    */
  2099.   template<typename _CharT, typename _Traits, typename _Alloc>
  2100.     inline bool
  2101.     operator!=(const _CharT* __lhs,
  2102.            const basic_string<_CharT, _Traits, _Alloc>& __rhs)
  2103.     { return __rhs.compare(__lhs) != 0; }
  2104.  
  2105.   /**
  2106.    *  @brief  Test difference of string and C string.
  2107.    *  @param lhs  String.
  2108.    *  @param rhs  C string.
  2109.    *  @return  True if @a lhs.compare(@a rhs) != 0.  False otherwise.
  2110.    */
  2111.   template<typename _CharT, typename _Traits, typename _Alloc>
  2112.     inline bool
  2113.     operator!=(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
  2114.            const _CharT* __rhs)
  2115.     { return __lhs.compare(__rhs) != 0; }
  2116.  
  2117.   // operator <
  2118.   /**
  2119.    *  @brief  Test if string precedes string.
  2120.    *  @param lhs  First string.
  2121.    *  @param rhs  Second string.
  2122.    *  @return  True if @a lhs precedes @a rhs.  False otherwise.
  2123.    */
  2124.   template<typename _CharT, typename _Traits, typename _Alloc>
  2125.     inline bool
  2126.     operator<(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
  2127.           const basic_string<_CharT, _Traits, _Alloc>& __rhs)
  2128.     { return __lhs.compare(__rhs) < 0; }
  2129.  
  2130.   /**
  2131.    *  @brief  Test if string precedes C string.
  2132.    *  @param lhs  String.
  2133.    *  @param rhs  C string.
  2134.    *  @return  True if @a lhs precedes @a rhs.  False otherwise.
  2135.    */
  2136.   template<typename _CharT, typename _Traits, typename _Alloc>
  2137.     inline bool
  2138.     operator<(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
  2139.           const _CharT* __rhs)
  2140.     { return __lhs.compare(__rhs) < 0; }
  2141.  
  2142.   /**
  2143.    *  @brief  Test if C string precedes string.
  2144.    *  @param lhs  C string.
  2145.    *  @param rhs  String.
  2146.    *  @return  True if @a lhs precedes @a rhs.  False otherwise.
  2147.    */
  2148.   template<typename _CharT, typename _Traits, typename _Alloc>
  2149.     inline bool
  2150.     operator<(const _CharT* __lhs,
  2151.           const basic_string<_CharT, _Traits, _Alloc>& __rhs)
  2152.     { return __rhs.compare(__lhs) > 0; }
  2153.  
  2154.   // operator >
  2155.   /**
  2156.    *  @brief  Test if string follows string.
  2157.    *  @param lhs  First string.
  2158.    *  @param rhs  Second string.
  2159.    *  @return  True if @a lhs follows @a rhs.  False otherwise.
  2160.    */
  2161.   template<typename _CharT, typename _Traits, typename _Alloc>
  2162.     inline bool
  2163.     operator>(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
  2164.           const basic_string<_CharT, _Traits, _Alloc>& __rhs)
  2165.     { return __lhs.compare(__rhs) > 0; }
  2166.  
  2167.   /**
  2168.    *  @brief  Test if string follows C string.
  2169.    *  @param lhs  String.
  2170.    *  @param rhs  C string.
  2171.    *  @return  True if @a lhs follows @a rhs.  False otherwise.
  2172.    */
  2173.   template<typename _CharT, typename _Traits, typename _Alloc>
  2174.     inline bool
  2175.     operator>(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
  2176.           const _CharT* __rhs)
  2177.     { return __lhs.compare(__rhs) > 0; }
  2178.  
  2179.   /**
  2180.    *  @brief  Test if C string follows string.
  2181.    *  @param lhs  C string.
  2182.    *  @param rhs  String.
  2183.    *  @return  True if @a lhs follows @a rhs.  False otherwise.
  2184.    */
  2185.   template<typename _CharT, typename _Traits, typename _Alloc>
  2186.     inline bool
  2187.     operator>(const _CharT* __lhs,
  2188.           const basic_string<_CharT, _Traits, _Alloc>& __rhs)
  2189.     { return __rhs.compare(__lhs) < 0; }
  2190.  
  2191.   // operator <=
  2192.   /**
  2193.    *  @brief  Test if string doesn't follow string.
  2194.    *  @param lhs  First string.
  2195.    *  @param rhs  Second string.
  2196.    *  @return  True if @a lhs doesn't follow @a rhs.  False otherwise.
  2197.    */
  2198.   template<typename _CharT, typename _Traits, typename _Alloc>
  2199.     inline bool
  2200.     operator<=(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
  2201.            const basic_string<_CharT, _Traits, _Alloc>& __rhs)
  2202.     { return __lhs.compare(__rhs) <= 0; }
  2203.  
  2204.   /**
  2205.    *  @brief  Test if string doesn't follow C string.
  2206.    *  @param lhs  String.
  2207.    *  @param rhs  C string.
  2208.    *  @return  True if @a lhs doesn't follow @a rhs.  False otherwise.
  2209.    */
  2210.   template<typename _CharT, typename _Traits, typename _Alloc>
  2211.     inline bool
  2212.     operator<=(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
  2213.            const _CharT* __rhs)
  2214.     { return __lhs.compare(__rhs) <= 0; }
  2215.  
  2216.   /**
  2217.    *  @brief  Test if C string doesn't follow string.
  2218.    *  @param lhs  C string.
  2219.    *  @param rhs  String.
  2220.    *  @return  True if @a lhs doesn't follow @a rhs.  False otherwise.
  2221.    */
  2222.   template<typename _CharT, typename _Traits, typename _Alloc>
  2223.     inline bool
  2224.     operator<=(const _CharT* __lhs,
  2225.            const basic_string<_CharT, _Traits, _Alloc>& __rhs)
  2226.   { return __rhs.compare(__lhs) >= 0; }
  2227.  
  2228.   // operator >=
  2229.   /**
  2230.    *  @brief  Test if string doesn't precede string.
  2231.    *  @param lhs  First string.
  2232.    *  @param rhs  Second string.
  2233.    *  @return  True if @a lhs doesn't precede @a rhs.  False otherwise.
  2234.    */
  2235.   template<typename _CharT, typename _Traits, typename _Alloc>
  2236.     inline bool
  2237.     operator>=(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
  2238.            const basic_string<_CharT, _Traits, _Alloc>& __rhs)
  2239.     { return __lhs.compare(__rhs) >= 0; }
  2240.  
  2241.   /**
  2242.    *  @brief  Test if string doesn't precede C string.
  2243.    *  @param lhs  String.
  2244.    *  @param rhs  C string.
  2245.    *  @return  True if @a lhs doesn't precede @a rhs.  False otherwise.
  2246.    */
  2247.   template<typename _CharT, typename _Traits, typename _Alloc>
  2248.     inline bool
  2249.     operator>=(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
  2250.            const _CharT* __rhs)
  2251.     { return __lhs.compare(__rhs) >= 0; }
  2252.  
  2253.   /**
  2254.    *  @brief  Test if C string doesn't precede string.
  2255.    *  @param lhs  C string.
  2256.    *  @param rhs  String.
  2257.    *  @return  True if @a lhs doesn't precede @a rhs.  False otherwise.
  2258.    */
  2259.   template<typename _CharT, typename _Traits, typename _Alloc>
  2260.     inline bool
  2261.     operator>=(const _CharT* __lhs,
  2262.          const basic_string<_CharT, _Traits, _Alloc>& __rhs)
  2263.     { return __rhs.compare(__lhs) <= 0; }
  2264.  
  2265.   /**
  2266.    *  @brief  Swap contents of two strings.
  2267.    *  @param lhs  First string.
  2268.    *  @param rhs  Second string.
  2269.    *
  2270.    *  Exchanges the contents of @a lhs and @a rhs in constant time.
  2271.    */
  2272.   template<typename _CharT, typename _Traits, typename _Alloc>
  2273.     inline void
  2274.     swap(basic_string<_CharT, _Traits, _Alloc>& __lhs,
  2275.      basic_string<_CharT, _Traits, _Alloc>& __rhs)
  2276.     { __lhs.swap(__rhs); }
  2277.  
  2278.   /**
  2279.    *  @brief  Read stream into a string.
  2280.    *  @param is  Input stream.
  2281.    *  @param str  Buffer to store into.
  2282.    *  @return  Reference to the input stream.
  2283.    *
  2284.    *  Stores characters from @a is into @a str until whitespace is found, the
  2285.    *  end of the stream is encountered, or str.max_size() is reached.  If
  2286.    *  is.width() is non-zero, that is the limit on the number of characters
  2287.    *  stored into @a str.  Any previous contents of @a str are erased.
  2288.    */
  2289.   template<typename _CharT, typename _Traits, typename _Alloc>
  2290.     basic_istream<_CharT, _Traits>&
  2291.     operator>>(basic_istream<_CharT, _Traits>& __is,
  2292.            basic_string<_CharT, _Traits, _Alloc>& __str);
  2293.  
  2294.   /**
  2295.    *  @brief  Write string to a stream.
  2296.    *  @param os  Output stream.
  2297.    *  @param str  String to write out.
  2298.    *  @return  Reference to the output stream.
  2299.    *
  2300.    *  Output characters of @a str into os following the same rules as for
  2301.    *  writing a C string.
  2302.    */
  2303.   template<typename _CharT, typename _Traits, typename _Alloc>
  2304.     basic_ostream<_CharT, _Traits>&
  2305.     operator<<(basic_ostream<_CharT, _Traits>& __os,
  2306.            const basic_string<_CharT, _Traits, _Alloc>& __str);
  2307.  
  2308.   /**
  2309.    *  @brief  Read a line from stream into a string.
  2310.    *  @param is  Input stream.
  2311.    *  @param str  Buffer to store into.
  2312.    *  @param delim  Character marking end of line.
  2313.    *  @return  Reference to the input stream.
  2314.    *
  2315.    *  Stores characters from @a is into @a str until @a delim is found, the
  2316.    *  end of the stream is encountered, or str.max_size() is reached.  If
  2317.    *  is.width() is non-zero, that is the limit on the number of characters
  2318.    *  stored into @a str.  Any previous contents of @a str are erased.  If @a
  2319.    *  delim was encountered, it is extracted but not stored into @a str.
  2320.    */
  2321.   template<typename _CharT, typename _Traits, typename _Alloc>
  2322.     basic_istream<_CharT,_Traits>&
  2323.     getline(basic_istream<_CharT, _Traits>& __is,
  2324.         basic_string<_CharT, _Traits, _Alloc>& __str, _CharT __delim);
  2325.  
  2326.   /**
  2327.    *  @brief  Read a line from stream into a string.
  2328.    *  @param is  Input stream.
  2329.    *  @param str  Buffer to store into.
  2330.    *  @return  Reference to the input stream.
  2331.    *
  2332.    *  Stores characters from is into @a str until '\n' is found, the end of
  2333.    *  the stream is encountered, or str.max_size() is reached.  If is.width()
  2334.    *  is non-zero, that is the limit on the number of characters stored into
  2335.    *  @a str.  Any previous contents of @a str are erased.  If end of line was
  2336.    *  encountered, it is extracted but not stored into @a str.
  2337.    */
  2338.   template<typename _CharT, typename _Traits, typename _Alloc>
  2339.     inline basic_istream<_CharT,_Traits>&
  2340.     getline(basic_istream<_CharT, _Traits>& __is,
  2341.         basic_string<_CharT, _Traits, _Alloc>& __str);
  2342. } // namespace std
  2343.  
  2344. #endif /* _BASIC_STRING_H */
  2345.