# basic_string.h

Go to the documentation of this file.

    00001 // Components for manipulating sequences of characters -*- C++ -*-
    00002
    00003 // Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
    00004 // 2006, 2007, 2008
    00005 // Free Software Foundation, Inc.
    00006 //
    00007 // This file is part of the GNU ISO C++ Library.  This library is free
    00008 // software; you can redistribute it and/or modify it under the
    00009 // terms of the GNU General Public License as published by the
    00010 // Free Software Foundation; either version 2, or (at your option)
    00011 // any later version.
    00012
    00013 // This library is distributed in the hope that it will be useful,
    00014 // but WITHOUT ANY WARRANTY; without even the implied warranty of
    00015 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    00016 // GNU General Public License for more details.
    00017
    00018 // You should have received a copy of the GNU General Public License along
    00019 // with this library; see the file COPYING.  If not, write to the Free
    00020 // Software Foundation, 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
    00021 // USA.
    00022
    00023 // As a special exception, you may use this file as part of a free software
    00024 // library without restriction.  Specifically, if other files instantiate
    00025 // templates or use macros or inline functions from this file, or you compile
    00026 // this file and link it with other files to produce an executable, this
    00027 // file does not by itself cause the resulting executable to be covered by
    00028 // the GNU General Public License.  This exception does not however
    00029 // invalidate any other reasons why the executable file might be covered by
    00030 // the GNU General Public License.
    00031
    00032 /** @file basic_string.h
    00033  *  This is an internal header file, included by other library headers.
    00034  *  You should not attempt to use it directly.
    00035  */
    00036
    00037 //
    00038 // ISO C++ 14882: 21 Strings library
    00039 //
    00040
    00041 #ifndef _BASIC_STRING_H
    00042 #define _BASIC_STRING_H 1
    00043
    00044 #pragma GCC system_header
    00045
    00046 #include <ext/atomicity.h>
    00047 #include <debug/debug.h>
    00048
    00049 _GLIBCXX_BEGIN_NAMESPACE(std)
    00050
    00051   /**
    00052    *  @class basic_string basic_string.h <string>
    00053    *  @brief  Managing sequences of characters and character-like objects.
    00054    *
    00055    *  @ingroup Containers
    00056    *  @ingroup Sequences
    00057    *
    00058    *  Meets the requirements of a <a href="tables.html#65">container</a>, a
    00059    *  <a href="tables.html#66">reversible container</a>, and a
    00060    *  <a href="tables.html#67">sequence</a>.  Of the
    00061    *  <a href="tables.html#68">optional sequence requirements</a>, only
    00062    *  @c push_back, @c at, and array access are supported.
    00063    *
    00064    *  @doctodo
    00065    *
    00066    *
    00067    *  Documentation?  What's that?
    00068    *  Nathan Myers <ncm@cantrip.org>.
    00069    *
    00070    *  A string looks like this:
    00071    *
    00072    *  @code
    00073    *                                        [_Rep]
    00074    *                                        _M_length
    00075    *   [basic_string<char_type>]            _M_capacity
    00076    *   _M_dataplus                          _M_refcount
    00077    *   _M_p ---------------->               unnamed array of char_type
    00078    *  @endcode
    00079    *
    00080    *  Where the _M_p points to the first character in the string, and
    00081    *  you cast it to a pointer-to-_Rep and subtract 1 to get a
    00082    *  pointer to the header.
    00083    *
    00084    *  This approach has the enormous advantage that a string object
    00085    *  requires only one allocation.  All the ugliness is confined
    00086    *  within a single pair of inline functions, which each compile to
    00087    *  a single "add" instruction: _Rep::_M_data(), and
    00088    *  string::_M_rep(); and the allocation function which gets a
    00089    *  block of raw bytes and with room enough and constructs a _Rep
    00090    *  object at the front.
    00091    *
    00092    *  The reason you want _M_data pointing to the character array and
    00093    *  not the _Rep is so that the debugger can see the string
    00094    *  contents. (Probably we should add a non-inline member to get
    00095    *  the _Rep for the debugger to use, so users can check the actual
    00096    *  string length.)
    00097    *
    00098    *  Note that the _Rep object is a POD so that you can have a
    00099    *  static "empty string" _Rep object already "constructed" before
    00100    *  static constructors have run.  The reference-count encoding is
    00101    *  chosen so that a 0 indicates one reference, so you never try to
    00102    *  destroy the empty-string _Rep object.
    00103    *
    00104    *  All but the last paragraph is considered pretty conventional
    00105    *  for a C++ string implementation.
    00106   */
    00107   // 21.3  Template class basic_string
    00108   template<typename _CharT, typename _Traits, typename _Alloc>
    00109     class basic_string
    00110     {
    00111       typedef typename _Alloc::template rebind<_CharT>::other _CharT_alloc_type;
    00112
    00113       // Types:
    00114     public:
    00115       typedef _Traits                       traits_type;
    00116       typedef typename _Traits::char_type           value_type;
    00117       typedef _Alloc                        allocator_type;
    00118       typedef typename _CharT_alloc_type::size_type     size_type;
    00119       typedef typename _CharT_alloc_type::difference_type   difference_type;
    00120       typedef typename _CharT_alloc_type::reference     reference;
    00121       typedef typename _CharT_alloc_type::const_reference   const_reference;
    00122       typedef typename _CharT_alloc_type::pointer       pointer;
    00123       typedef typename _CharT_alloc_type::const_pointer     const_pointer;
    00124       typedef __gnu_cxx::__normal_iterator<pointer, basic_string>  iterator;
    00125       typedef __gnu_cxx::__normal_iterator<const_pointer, basic_string>
    00126                                                             const_iterator;
    00127       typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
    00128       typedef std::reverse_iterator<iterator>           reverse_iterator;
    00129
    00130     private:
    00131       // _Rep: string representation
    00132       //   Invariants:
    00133       //   1. String really contains _M_length + 1 characters: due to 21.3.4
    00134       //      must be kept null-terminated.
    00135       //   2. _M_capacity >= _M_length
    00136       //      Allocated memory is always (_M_capacity + 1) * sizeof(_CharT).
    00137       //   3. _M_refcount has three states:
    00138       //      -1: leaked, one reference, no ref-copies allowed, non-const.
    00139       //       0: one reference, non-const.
    00140       //     n>0: n + 1 references, operations require a lock, const.
    00141       //   4. All fields==0 is an empty string, given the extra storage
    00142       //      beyond-the-end for a null terminator; thus, the shared
    00143       //      empty string representation needs no constructor.
    00144
    00145       struct _Rep_base
    00146       {
    00147     size_type       _M_length;
    00148     size_type       _M_capacity;
    00149     _Atomic_word        _M_refcount;
    00150       };
    00151
    00152       struct _Rep : _Rep_base
    00153       {
    00154     // Types:
    00155     typedef typename _Alloc::template rebind<char>::other _Raw_bytes_alloc;
    00156
    00157     // (Public) Data members:
    00158
    00159     // The maximum number of individual char_type elements of an
    00160     // individual string is determined by _S_max_size. This is the
    00161     // value that will be returned by max_size().  (Whereas npos
    00162     // is the maximum number of bytes the allocator can allocate.)
    00163     // If one was to divvy up the theoretical largest size string,
    00164     // with a terminating character and m _CharT elements, it'd
    00165     // look like this:
    00166     // npos = sizeof(_Rep) + (m * sizeof(_CharT)) + sizeof(_CharT)
    00167     // Solving for m:
    00168     // m = ((npos - sizeof(_Rep))/sizeof(CharT)) - 1
    00169     // In addition, this implementation quarters this amount.
    00170     static const size_type  _S_max_size;
    00171     static const _CharT _S_terminal;
    00172
    00173     // The following storage is init'd to 0 by the linker, resulting
    00174         // (carefully) in an empty string with one reference.
    00175         static size_type _S_empty_rep_storage[];
    00176
    00177         static _Rep&
    00178         _S_empty_rep()
    00179         {
    00180       // NB: Mild hack to avoid strict-aliasing warnings.  Note that
    00181       // _S_empty_rep_storage is never modified and the punning should
    00182       // be reasonably safe in this case.
    00183       void* __p = reinterpret_cast<void*>(&_S_empty_rep_storage);
    00184       return *reinterpret_cast<_Rep*>(__p);
    00185     }
    00186
    00187         bool
    00188     _M_is_leaked() const
    00189         { return this->_M_refcount < 0; }
    00190
    00191         bool
    00192     _M_is_shared() const
    00193         { return this->_M_refcount > 0; }
    00194
    00195         void
    00196     _M_set_leaked()
    00197         { this->_M_refcount = -1; }
    00198
    00199         void
    00200     _M_set_sharable()
    00201         { this->_M_refcount = 0; }
    00202
    00203     void
    00204     _M_set_length_and_sharable(size_type __n)
    00205     {
    00206       this->_M_set_sharable();  // One reference.
    00207       this->_M_length = __n;
    00208       traits_type::assign(this->_M_refdata()[__n], _S_terminal);
    00209       // grrr. (per 21.3.4)
    00210       // You cannot leave those LWG people alone for a second.
    00211     }
    00212
    00213     _CharT*
    00214     _M_refdata() throw()
    00215     { return reinterpret_cast<_CharT*>(this + 1); }
    00216
    00217     _CharT*
    00218     _M_grab(const _Alloc& __alloc1, const _Alloc& __alloc2)
    00219     {
    00220       return (!_M_is_leaked() && __alloc1 == __alloc2)
    00221               ? _M_refcopy() : _M_clone(__alloc1);
    00222     }
    00223
    00224     // Create & Destroy
    00225     static _Rep*
    00226     _S_create(size_type, size_type, const _Alloc&);
    00227
    00228     void
    00229     _M_dispose(const _Alloc& __a)
    00230     {
    00231 #ifndef _GLIBCXX_FULLY_DYNAMIC_STRING
    00232       if (__builtin_expect(this != &_S_empty_rep(), false))
    00233 #endif
    00234         if (__gnu_cxx::__exchange_and_add_dispatch(&this->_M_refcount,
    00235                                -1) <= 0)
    00236           _M_destroy(__a);
    00237     }  // XXX MT
    00238
    00239     void
    00240     _M_destroy(const _Alloc&) throw();
    00241
    00242     _CharT*
    00243     _M_refcopy() throw()
    00244     {
    00245 #ifndef _GLIBCXX_FULLY_DYNAMIC_STRING
    00246       if (__builtin_expect(this != &_S_empty_rep(), false))
    00247 #endif
    00248             __gnu_cxx::__atomic_add_dispatch(&this->_M_refcount, 1);
    00249       return _M_refdata();
    00250     }  // XXX MT
    00251
    00252     _CharT*
    00253     _M_clone(const _Alloc&, size_type __res = 0);
    00254       };
    00255
    00256       // Use empty-base optimization: http://www.cantrip.org/emptyopt.html
    00257       struct _Alloc_hider : _Alloc
    00258       {
    00259     _Alloc_hider(_CharT* __dat, const _Alloc& __a)
    00260     : _Alloc(__a), _M_p(__dat) { }
    00261
    00262     _CharT* _M_p; // The actual data.
    00263       };
    00264
    00265     public:
    00266       // Data Members (public):
    00267       // NB: This is an unsigned type, and thus represents the maximum
    00268       // size that the allocator can hold.
    00269       ///  Value returned by various member functions when they fail.
    00270       static const size_type    npos = static_cast<size_type>(-1);
    00271
    00272     private:
    00273       // Data Members (private):
    00274       mutable _Alloc_hider  _M_dataplus;
    00275
    00276       _CharT*
    00277       _M_data() const
    00278       { return  _M_dataplus._M_p; }
    00279
    00280       _CharT*
    00281       _M_data(_CharT* __p)
    00282       { return (_M_dataplus._M_p = __p); }
    00283
    00284       _Rep*
    00285       _M_rep() const
    00286       { return &((reinterpret_cast<_Rep*> (_M_data()))[-1]); }
    00287
    00288       // For the internal use we have functions similar to `begin'/`end'
    00289       // but they do not call _M_leak.
    00290       iterator
    00291       _M_ibegin() const
    00292       { return iterator(_M_data()); }
    00293
    00294       iterator
    00295       _M_iend() const
    00296       { return iterator(_M_data() + this->size()); }
    00297
    00298       void
    00299       _M_leak()    // for use in begin() & non-const op[]
    00300       {
    00301     if (!_M_rep()->_M_is_leaked())
    00302       _M_leak_hard();
    00303       }
    00304
    00305       size_type
    00306       _M_check(size_type __pos, const char* __s) const
    00307       {
    00308     if (__pos > this->size())
    00309       __throw_out_of_range(__N(__s));
    00310     return __pos;
    00311       }
    00312
    00313       void
    00314       _M_check_length(size_type __n1, size_type __n2, const char* __s) const
    00315       {
    00316     if (this->max_size() - (this->size() - __n1) < __n2)
    00317       __throw_length_error(__N(__s));
    00318       }
    00319
    00320       // NB: _M_limit doesn't check for a bad __pos value.
    00321       size_type
    00322       _M_limit(size_type __pos, size_type __off) const
    00323       {
    00324     const bool __testoff =  __off < this->size() - __pos;
    00325     return __testoff ? __off : this->size() - __pos;
    00326       }
    00327
    00328       // True if _Rep and source do not overlap.
    00329       bool
    00330       _M_disjunct(const _CharT* __s) const
    00331       {
    00332     return (less<const _CharT*>()(__s, _M_data())
    00333         || less<const _CharT*>()(_M_data() + this->size(), __s));
    00334       }
    00335
    00336       // When __n = 1 way faster than the general multichar
    00337       // traits_type::copy/move/assign.
    00338       static void
    00339       _M_copy(_CharT* __d, const _CharT* __s, size_type __n)
    00340       {
    00341     if (__n == 1)
    00342       traits_type::assign(*__d, *__s);
    00343     else
    00344       traits_type::copy(__d, __s, __n);
    00345       }
    00346
    00347       static void
    00348       _M_move(_CharT* __d, const _CharT* __s, size_type __n)
    00349       {
    00350     if (__n == 1)
    00351       traits_type::assign(*__d, *__s);
    00352     else
    00353       traits_type::move(__d, __s, __n);
    00354       }
    00355
    00356       static void
    00357       _M_assign(_CharT* __d, size_type __n, _CharT __c)
    00358       {
    00359     if (__n == 1)
    00360       traits_type::assign(*__d, __c);
    00361     else
    00362       traits_type::assign(__d, __n, __c);
    00363       }
    00364
    00365       // _S_copy_chars is a separate template to permit specialization
    00366       // to optimize for the common case of pointers as iterators.
    00367       template<class _Iterator>
    00368         static void
    00369         _S_copy_chars(_CharT* __p, _Iterator __k1, _Iterator __k2)
    00370         {
    00371       for (; __k1 != __k2; ++__k1, ++__p)
    00372         traits_type::assign(*__p, *__k1); // These types are off.
    00373     }
    00374
    00375       static void
    00376       _S_copy_chars(_CharT* __p, iterator __k1, iterator __k2)
    00377       { _S_copy_chars(__p, __k1.base(), __k2.base()); }
    00378
    00379       static void
    00380       _S_copy_chars(_CharT* __p, const_iterator __k1, const_iterator __k2)
    00381       { _S_copy_chars(__p, __k1.base(), __k2.base()); }
    00382
    00383       static void
    00384       _S_copy_chars(_CharT* __p, _CharT* __k1, _CharT* __k2)
    00385       { _M_copy(__p, __k1, __k2 - __k1); }
    00386
    00387       static void
    00388       _S_copy_chars(_CharT* __p, const _CharT* __k1, const _CharT* __k2)
    00389       { _M_copy(__p, __k1, __k2 - __k1); }
    00390
    00391       static int
    00392       _S_compare(size_type __n1, size_type __n2)
    00393       {
    00394     const difference_type __d = difference_type(__n1 - __n2);
    00395
    00396     if (__d > __gnu_cxx::__numeric_traits<int>::__max)
    00397       return __gnu_cxx::__numeric_traits<int>::__max;
    00398     else if (__d < __gnu_cxx::__numeric_traits<int>::__min)
    00399       return __gnu_cxx::__numeric_traits<int>::__min;
    00400     else
    00401       return int(__d);
    00402       }
    00403
    00404       void
    00405       _M_mutate(size_type __pos, size_type __len1, size_type __len2);
    00406
    00407       void
    00408       _M_leak_hard();
    00409
    00410       static _Rep&
    00411       _S_empty_rep()
    00412       { return _Rep::_S_empty_rep(); }
    00413
    00414     public:
    00415       // Construct/copy/destroy:
    00416       // NB: We overload ctors in some cases instead of using default
    00417       // arguments, per 17.4.4.4 para. 2 item 2.
    00418
    00419       /**
    00420        *  @brief  Default constructor creates an empty string.
    00421        */
    00422       inline
    00423       basic_string();
    00424
    00425       /**
    00426        *  @brief  Construct an empty string using allocator @a a.
    00427        */
    00428       explicit
    00429       basic_string(const _Alloc& __a);
    00430
    00431       // NB: per LWG issue 42, semantics different from IS:
    00432       /**
    00433        *  @brief  Construct string with copy of value of @a str.
    00434        *  @param  str  Source string.
    00435        */
    00436       basic_string(const basic_string& __str);
    00437       /**
    00438        *  @brief  Construct string as copy of a substring.
    00439        *  @param  str  Source string.
    00440        *  @param  pos  Index of first character to copy from.
    00441        *  @param  n  Number of characters to copy (default remainder).
    00442        */
    00443       basic_string(const basic_string& __str, size_type __pos,
    00444            size_type __n = npos);
    00445       /**
    00446        *  @brief  Construct string as copy of a substring.
    00447        *  @param  str  Source string.
    00448        *  @param  pos  Index of first character to copy from.
    00449        *  @param  n  Number of characters to copy.
    00450        *  @param  a  Allocator to use.
    00451        */
    00452       basic_string(const basic_string& __str, size_type __pos,
    00453            size_type __n, const _Alloc& __a);
    00454
    00455       /**
    00456        *  @brief  Construct string initialized by a character array.
    00457        *  @param  s  Source character array.
    00458        *  @param  n  Number of characters to copy.
    00459        *  @param  a  Allocator to use (default is default allocator).
    00460        *
    00461        *  NB: @a s must have at least @a n characters, '\0' has no special
    00462        *  meaning.
    00463        */
    00464       basic_string(const _CharT* __s, size_type __n,
    00465            const _Alloc& __a = _Alloc());
    00466       /**
    00467        *  @brief  Construct string as copy of a C string.
    00468        *  @param  s  Source C string.
    00469        *  @param  a  Allocator to use (default is default allocator).
    00470        */
    00471       basic_string(const _CharT* __s, const _Alloc& __a = _Alloc());
    00472       /**
    00473        *  @brief  Construct string as multiple characters.
    00474        *  @param  n  Number of characters.
    00475        *  @param  c  Character to use.
    00476        *  @param  a  Allocator to use (default is default allocator).
    00477        */
    00478       basic_string(size_type __n, _CharT __c, const _Alloc& __a = _Alloc());
    00479
    00480       /**
    00481        *  @brief  Construct string as copy of a range.
    00482        *  @param  beg  Start of range.
    00483        *  @param  end  End of range.
    00484        *  @param  a  Allocator to use (default is default allocator).
    00485        */
    00486       template<class _InputIterator>
    00487         basic_string(_InputIterator __beg, _InputIterator __end,
    00488              const _Alloc& __a = _Alloc());
    00489
    00490       /**
    00491        *  @brief  Destroy the string instance.
    00492        */
    00493       ~basic_string()
    00494       { _M_rep()->_M_dispose(this->get_allocator()); }
    00495
    00496       /**
    00497        *  @brief  Assign the value of @a str to this string.
    00498        *  @param  str  Source string.
    00499        */
    00500       basic_string&
    00501       operator=(const basic_string& __str)
    00502       { return this->assign(__str); }
    00503
    00504       /**
    00505        *  @brief  Copy contents of @a s into this string.
    00506        *  @param  s  Source null-terminated string.
    00507        */
    00508       basic_string&
    00509       operator=(const _CharT* __s)
    00510       { return this->assign(__s); }
    00511
    00512       /**
    00513        *  @brief  Set value to string of length 1.
    00514        *  @param  c  Source character.
    00515        *
    00516        *  Assigning to a character makes this string length 1 and
    00517        *  (*this)[0] == @a c.
    00518        */
    00519       basic_string&
    00520       operator=(_CharT __c)
    00521       {
    00522     this->assign(1, __c);
    00523     return *this;
    00524       }
    00525
    00526       // Iterators:
    00527       /**
    00528        *  Returns a read/write iterator that points to the first character in
    00529        *  the %string.  Unshares the string.
    00530        */
    00531       iterator
    00532       begin()
    00533       {
    00534     _M_leak();
    00535     return iterator(_M_data());
    00536       }
    00537
    00538       /**
    00539        *  Returns a read-only (constant) iterator that points to the first
    00540        *  character in the %string.
    00541        */
    00542       const_iterator
    00543       begin() const
    00544       { return const_iterator(_M_data()); }
    00545
    00546       /**
    00547        *  Returns a read/write iterator that points one past the last
    00548        *  character in the %string.  Unshares the string.
    00549        */
    00550       iterator
    00551       end()
    00552       {
    00553     _M_leak();
    00554     return iterator(_M_data() + this->size());
    00555       }
    00556
    00557       /**
    00558        *  Returns a read-only (constant) iterator that points one past the
    00559        *  last character in the %string.
    00560        */
    00561       const_iterator
    00562       end() const
    00563       { return const_iterator(_M_data() + this->size()); }
    00564
    00565       /**
    00566        *  Returns a read/write reverse iterator that points to the last
    00567        *  character in the %string.  Iteration is done in reverse element
    00568        *  order.  Unshares the string.
    00569        */
    00570       reverse_iterator
    00571       rbegin()
    00572       { return reverse_iterator(this->end()); }
    00573
    00574       /**
    00575        *  Returns a read-only (constant) reverse iterator that points
    00576        *  to the last character in the %string.  Iteration is done in
    00577        *  reverse element order.
    00578        */
    00579       const_reverse_iterator
    00580       rbegin() const
    00581       { return const_reverse_iterator(this->end()); }
    00582
    00583       /**
    00584        *  Returns a read/write reverse iterator that points to one before the
    00585        *  first character in the %string.  Iteration is done in reverse
    00586        *  element order.  Unshares the string.
    00587        */
    00588       reverse_iterator
    00589       rend()
    00590       { return reverse_iterator(this->begin()); }
    00591
    00592       /**
    00593        *  Returns a read-only (constant) reverse iterator that points
    00594        *  to one before the first character in the %string.  Iteration
    00595        *  is done in reverse element order.
    00596        */
    00597       const_reverse_iterator
    00598       rend() const
    00599       { return const_reverse_iterator(this->begin()); }
    00600
    00601     public:
    00602       // Capacity:
    00603       ///  Returns the number of characters in the string, not including any
    00604       ///  null-termination.
    00605       size_type
    00606       size() const
    00607       { return _M_rep()->_M_length; }
    00608
    00609       ///  Returns the number of characters in the string, not including any
    00610       ///  null-termination.
    00611       size_type
    00612       length() const
    00613       { return _M_rep()->_M_length; }
    00614
    00615       /// Returns the size() of the largest possible %string.
    00616       size_type
    00617       max_size() const
    00618       { return _Rep::_S_max_size; }
    00619
    00620       /**
    00621        *  @brief  Resizes the %string to the specified number of characters.
    00622        *  @param  n  Number of characters the %string should contain.
    00623        *  @param  c  Character to fill any new elements.
    00624        *
    00625        *  This function will %resize the %string to the specified
    00626        *  number of characters.  If the number is smaller than the
    00627        *  %string's current size the %string is truncated, otherwise
    00628        *  the %string is extended and new elements are set to @a c.
    00629        */
    00630       void
    00631       resize(size_type __n, _CharT __c);
    00632
    00633       /**
    00634        *  @brief  Resizes the %string to the specified number of characters.
    00635        *  @param  n  Number of characters the %string should contain.
    00636        *
    00637        *  This function will resize the %string to the specified length.  If
    00638        *  the new size is smaller than the %string's current size the %string
    00639        *  is truncated, otherwise the %string is extended and new characters
    00640        *  are default-constructed.  For basic types such as char, this means
    00641        *  setting them to 0.
    00642        */
    00643       void
    00644       resize(size_type __n)
    00645       { this->resize(__n, _CharT()); }
    00646
    00647       /**
    00648        *  Returns the total number of characters that the %string can hold
    00649        *  before needing to allocate more memory.
    00650        */
    00651       size_type
    00652       capacity() const
    00653       { return _M_rep()->_M_capacity; }
    00654
    00655       /**
    00656        *  @brief  Attempt to preallocate enough memory for specified number of
    00657        *          characters.
    00658        *  @param  res_arg  Number of characters required.
    00659        *  @throw  std::length_error  If @a res_arg exceeds @c max_size().
    00660        *
    00661        *  This function attempts to reserve enough memory for the
    00662        *  %string to hold the specified number of characters.  If the
    00663        *  number requested is more than max_size(), length_error is
    00664        *  thrown.
    00665        *
    00666        *  The advantage of this function is that if optimal code is a
    00667        *  necessity and the user can determine the string length that will be
    00668        *  required, the user can reserve the memory in %advance, and thus
    00669        *  prevent a possible reallocation of memory and copying of %string
    00670        *  data.
    00671        */
    00672       void
    00673       reserve(size_type __res_arg = 0);
    00674
    00675       /**
    00676        *  Erases the string, making it empty.
    00677        */
    00678       void
    00679       clear()
    00680       { _M_mutate(0, this->size(), 0); }
    00681
    00682       /**
    00683        *  Returns true if the %string is empty.  Equivalent to *this == "".
    00684        */
    00685       bool
    00686       empty() const
    00687       { return this->size() == 0; }
    00688
    00689       // Element access:
    00690       /**
    00691        *  @brief  Subscript access to the data contained in the %string.
    00692        *  @param  pos  The index of the character to access.
    00693        *  @return  Read-only (constant) reference to the character.
    00694        *
    00695        *  This operator allows for easy, array-style, data access.
    00696        *  Note that data access with this operator is unchecked and
    00697        *  out_of_range lookups are not defined. (For checked lookups
    00698        *  see at().)
    00699        */
    00700       const_reference
    00701       operator[] (size_type __pos) const
    00702       {
    00703     _GLIBCXX_DEBUG_ASSERT(__pos <= size());
    00704     return _M_data()[__pos];
    00705       }
    00706
    00707       /**
    00708        *  @brief  Subscript access to the data contained in the %string.
    00709        *  @param  pos  The index of the character to access.
    00710        *  @return  Read/write reference to the character.
    00711        *
    00712        *  This operator allows for easy, array-style, data access.
    00713        *  Note that data access with this operator is unchecked and
    00714        *  out_of_range lookups are not defined. (For checked lookups
    00715        *  see at().)  Unshares the string.
    00716        */
    00717       reference
    00718       operator[](size_type __pos)
    00719       {
    00720         // allow pos == size() as v3 extension:
    00721     _GLIBCXX_DEBUG_ASSERT(__pos <= size());
    00722         // but be strict in pedantic mode:
    00723     _GLIBCXX_DEBUG_PEDASSERT(__pos < size());
    00724     _M_leak();
    00725     return _M_data()[__pos];
    00726       }
    00727
    00728       /**
    00729        *  @brief  Provides access to the data contained in the %string.
    00730        *  @param n The index of the character to access.
    00731        *  @return  Read-only (const) reference to the character.
    00732        *  @throw  std::out_of_range  If @a n is an invalid index.
    00733        *
    00734        *  This function provides for safer data access.  The parameter is
    00735        *  first checked that it is in the range of the string.  The function
    00736        *  throws out_of_range if the check fails.
    00737        */
    00738       const_reference
    00739       at(size_type __n) const
    00740       {
    00741     if (__n >= this->size())
    00742       __throw_out_of_range(__N("basic_string::at"));
    00743     return _M_data()[__n];
    00744       }
    00745
    00746       /**
    00747        *  @brief  Provides access to the data contained in the %string.
    00748        *  @param n The index of the character to access.
    00749        *  @return  Read/write reference to the character.
    00750        *  @throw  std::out_of_range  If @a n is an invalid index.
    00751        *
    00752        *  This function provides for safer data access.  The parameter is
    00753        *  first checked that it is in the range of the string.  The function
    00754        *  throws out_of_range if the check fails.  Success results in
    00755        *  unsharing the string.
    00756        */
    00757       reference
    00758       at(size_type __n)
    00759       {
    00760     if (__n >= size())
    00761       __throw_out_of_range(__N("basic_string::at"));
    00762     _M_leak();
    00763     return _M_data()[__n];
    00764       }
    00765
    00766       // Modifiers:
    00767       /**
    00768        *  @brief  Append a string to this string.
    00769        *  @param str  The string to append.
    00770        *  @return  Reference to this string.
    00771        */
    00772       basic_string&
    00773       operator+=(const basic_string& __str)
    00774       { return this->append(__str); }
    00775
    00776       /**
    00777        *  @brief  Append a C string.
    00778        *  @param s  The C string to append.
    00779        *  @return  Reference to this string.
    00780        */
    00781       basic_string&
    00782       operator+=(const _CharT* __s)
    00783       { return this->append(__s); }
    00784
    00785       /**
    00786        *  @brief  Append a character.
    00787        *  @param c  The character to append.
    00788        *  @return  Reference to this string.
    00789        */
    00790       basic_string&
    00791       operator+=(_CharT __c)
    00792       {
    00793     this->push_back(__c);
    00794     return *this;
    00795       }
    00796
    00797       /**
    00798        *  @brief  Append a string to this string.
    00799        *  @param str  The string to append.
    00800        *  @return  Reference to this string.
    00801        */
    00802       basic_string&
    00803       append(const basic_string& __str);
    00804
    00805       /**
    00806        *  @brief  Append a substring.
    00807        *  @param str  The string to append.
    00808        *  @param pos  Index of the first character of str to append.
    00809        *  @param n  The number of characters to append.
    00810        *  @return  Reference to this string.
    00811        *  @throw  std::out_of_range if @a pos is not a valid index.
    00812        *
    00813        *  This function appends @a n characters from @a str starting at @a pos
    00814        *  to this string.  If @a n is is larger than the number of available
    00815        *  characters in @a str, the remainder of @a str is appended.
    00816        */
    00817       basic_string&
    00818       append(const basic_string& __str, size_type __pos, size_type __n);
    00819
    00820       /**
    00821        *  @brief  Append a C substring.
    00822        *  @param s  The C string to append.
    00823        *  @param n  The number of characters to append.
    00824        *  @return  Reference to this string.
    00825        */
    00826       basic_string&
    00827       append(const _CharT* __s, size_type __n);
    00828
    00829       /**
    00830        *  @brief  Append a C string.
    00831        *  @param s  The C string to append.
    00832        *  @return  Reference to this string.
    00833        */
    00834       basic_string&
    00835       append(const _CharT* __s)
    00836       {
    00837     __glibcxx_requires_string(__s);
    00838     return this->append(__s, traits_type::length(__s));
    00839       }
    00840
    00841       /**
    00842        *  @brief  Append multiple characters.
    00843        *  @param n  The number of characters to append.
    00844        *  @param c  The character to use.
    00845        *  @return  Reference to this string.
    00846        *
    00847        *  Appends n copies of c to this string.
    00848        */
    00849       basic_string&
    00850       append(size_type __n, _CharT __c);
    00851
    00852       /**
    00853        *  @brief  Append a range of characters.
    00854        *  @param first  Iterator referencing the first character to append.
    00855        *  @param last  Iterator marking the end of the range.
    00856        *  @return  Reference to this string.
    00857        *
    00858        *  Appends characters in the range [first,last) to this string.
    00859        */
    00860       template<class _InputIterator>
    00861         basic_string&
    00862         append(_InputIterator __first, _InputIterator __last)
    00863         { return this->replace(_M_iend(), _M_iend(), __first, __last); }
    00864
    00865       /**
    00866        *  @brief  Append a single character.
    00867        *  @param c  Character to append.
    00868        */
    00869       void
    00870       push_back(_CharT __c)
    00871       {
    00872     const size_type __len = 1 + this->size();
    00873     if (__len > this->capacity() || _M_rep()->_M_is_shared())
    00874       this->reserve(__len);
    00875     traits_type::assign(_M_data()[this->size()], __c);
    00876     _M_rep()->_M_set_length_and_sharable(__len);
    00877       }
    00878
    00879       /**
    00880        *  @brief  Set value to contents of another string.
    00881        *  @param  str  Source string to use.
    00882        *  @return  Reference to this string.
    00883        */
    00884       basic_string&
    00885       assign(const basic_string& __str);
    00886
    00887       /**
    00888        *  @brief  Set value to a substring of a string.
    00889        *  @param str  The string to use.
    00890        *  @param pos  Index of the first character of str.
    00891        *  @param n  Number of characters to use.
    00892        *  @return  Reference to this string.
    00893        *  @throw  std::out_of_range if @a pos is not a valid index.
    00894        *
    00895        *  This function sets this string to the substring of @a str consisting
    00896        *  of @a n characters at @a pos.  If @a n is is larger than the number
    00897        *  of available characters in @a str, the remainder of @a str is used.
    00898        */
    00899       basic_string&
    00900       assign(const basic_string& __str, size_type __pos, size_type __n)
    00901       { return this->assign(__str._M_data()
    00902                 + __str._M_check(__pos, "basic_string::assign"),
    00903                 __str._M_limit(__pos, __n)); }
    00904
    00905       /**
    00906        *  @brief  Set value to a C substring.
    00907        *  @param s  The C string to use.
    00908        *  @param n  Number of characters to use.
    00909        *  @return  Reference to this string.
    00910        *
    00911        *  This function sets the value of this string to the first @a n
    00912        *  characters of @a s.  If @a n is is larger than the number of
    00913        *  available characters in @a s, the remainder of @a s is used.
    00914        */
    00915       basic_string&
    00916       assign(const _CharT* __s, size_type __n);
    00917
    00918       /**
    00919        *  @brief  Set value to contents of a C string.
    00920        *  @param s  The C string to use.
    00921        *  @return  Reference to this string.
    00922        *
    00923        *  This function sets the value of this string to the value of @a s.
    00924        *  The data is copied, so there is no dependence on @a s once the
    00925        *  function returns.
    00926        */
    00927       basic_string&
    00928       assign(const _CharT* __s)
    00929       {
    00930     __glibcxx_requires_string(__s);
    00931     return this->assign(__s, traits_type::length(__s));
    00932       }
    00933
    00934       /**
    00935        *  @brief  Set value to multiple characters.
    00936        *  @param n  Length of the resulting string.
    00937        *  @param c  The character to use.
    00938        *  @return  Reference to this string.
    00939        *
    00940        *  This function sets the value of this string to @a n copies of
    00941        *  character @a c.
    00942        */
    00943       basic_string&
    00944       assign(size_type __n, _CharT __c)
    00945       { return _M_replace_aux(size_type(0), this->size(), __n, __c); }
    00946
    00947       /**
    00948        *  @brief  Set value to a range of characters.
    00949        *  @param first  Iterator referencing the first character to append.
    00950        *  @param last  Iterator marking the end of the range.
    00951        *  @return  Reference to this string.
    00952        *
    00953        *  Sets value of string to characters in the range [first,last).
    00954       */
    00955       template<class _InputIterator>
    00956         basic_string&
    00957         assign(_InputIterator __first, _InputIterator __last)
    00958         { return this->replace(_M_ibegin(), _M_iend(), __first, __last); }
    00959
    00960       /**
    00961        *  @brief  Insert multiple characters.
    00962        *  @param p  Iterator referencing location in string to insert at.
    00963        *  @param n  Number of characters to insert
    00964        *  @param c  The character to insert.
    00965        *  @throw  std::length_error  If new length exceeds @c max_size().
    00966        *
    00967        *  Inserts @a n copies of character @a c starting at the position
    00968        *  referenced by iterator @a p.  If adding characters causes the length
    00969        *  to exceed max_size(), length_error is thrown.  The value of the
    00970        *  string doesn't change if an error is thrown.
    00971       */
    00972       void
    00973       insert(iterator __p, size_type __n, _CharT __c)
    00974       { this->replace(__p, __p, __n, __c);  }
    00975
    00976       /**
    00977        *  @brief  Insert a range of characters.
    00978        *  @param p  Iterator referencing location in string to insert at.
    00979        *  @param beg  Start of range.
    00980        *  @param end  End of range.
    00981        *  @throw  std::length_error  If new length exceeds @c max_size().
    00982        *
    00983        *  Inserts characters in range [beg,end).  If adding characters causes
    00984        *  the length to exceed max_size(), length_error is thrown.  The value
    00985        *  of the string doesn't change if an error is thrown.
    00986       */
    00987       template<class _InputIterator>
    00988         void
    00989         insert(iterator __p, _InputIterator __beg, _InputIterator __end)
    00990         { this->replace(__p, __p, __beg, __end); }
    00991
    00992       /**
    00993        *  @brief  Insert value of a string.
    00994        *  @param pos1  Iterator referencing location in string to insert at.
    00995        *  @param str  The string to insert.
    00996        *  @return  Reference to this string.
    00997        *  @throw  std::length_error  If new length exceeds @c max_size().
    00998        *
    00999        *  Inserts value of @a str starting at @a pos1.  If adding characters
    01000        *  causes the length to exceed max_size(), length_error is thrown.  The
    01001        *  value of the string doesn't change if an error is thrown.
    01002       */
    01003       basic_string&
    01004       insert(size_type __pos1, const basic_string& __str)
    01005       { return this->insert(__pos1, __str, size_type(0), __str.size()); }
    01006
    01007       /**
    01008        *  @brief  Insert a substring.
    01009        *  @param pos1  Iterator referencing location in string to insert at.
    01010        *  @param str  The string to insert.
    01011        *  @param pos2  Start of characters in str to insert.
    01012        *  @param n  Number of characters to insert.
    01013        *  @return  Reference to this string.
    01014        *  @throw  std::length_error  If new length exceeds @c max_size().
    01015        *  @throw  std::out_of_range  If @a pos1 > size() or
    01016        *  @a pos2 > @a str.size().
    01017        *
    01018        *  Starting at @a pos1, insert @a n character of @a str beginning with
    01019        *  @a pos2.  If adding characters causes the length to exceed
    01020        *  max_size(), length_error is thrown.  If @a pos1 is beyond the end of
    01021        *  this string or @a pos2 is beyond the end of @a str, out_of_range is
    01022        *  thrown.  The value of the string doesn't change if an error is
    01023        *  thrown.
    01024       */
    01025       basic_string&
    01026       insert(size_type __pos1, const basic_string& __str,
    01027          size_type __pos2, size_type __n)
    01028       { return this->insert(__pos1, __str._M_data()
    01029                 + __str._M_check(__pos2, "basic_string::insert"),
    01030                 __str._M_limit(__pos2, __n)); }
    01031
    01032       /**
    01033        *  @brief  Insert a C substring.
    01034        *  @param pos  Iterator referencing location in string to insert at.
    01035        *  @param s  The C string to insert.
    01036        *  @param n  The number of characters to insert.
    01037        *  @return  Reference to this string.
    01038        *  @throw  std::length_error  If new length exceeds @c max_size().
    01039        *  @throw  std::out_of_range  If @a pos is beyond the end of this
    01040        *  string.
    01041        *
    01042        *  Inserts the first @a n characters of @a s starting at @a pos.  If
    01043        *  adding characters causes the length to exceed max_size(),
    01044        *  length_error is thrown.  If @a pos is beyond end(), out_of_range is
    01045        *  thrown.  The value of the string doesn't change if an error is
    01046        *  thrown.
    01047       */
    01048       basic_string&
    01049       insert(size_type __pos, const _CharT* __s, size_type __n);
    01050
    01051       /**
    01052        *  @brief  Insert a C string.
    01053        *  @param pos  Iterator referencing location in string to insert at.
    01054        *  @param s  The C string to insert.
    01055        *  @return  Reference to this string.
    01056        *  @throw  std::length_error  If new length exceeds @c max_size().
    01057        *  @throw  std::out_of_range  If @a pos is beyond the end of this
    01058        *  string.
    01059        *
    01060        *  Inserts the first @a n characters of @a s starting at @a pos.  If
    01061        *  adding characters causes the length to exceed max_size(),
    01062        *  length_error is thrown.  If @a pos is beyond end(), out_of_range is
    01063        *  thrown.  The value of the string doesn't change if an error is
    01064        *  thrown.
    01065       */
    01066       basic_string&
    01067       insert(size_type __pos, const _CharT* __s)
    01068       {
    01069     __glibcxx_requires_string(__s);
    01070     return this->insert(__pos, __s, traits_type::length(__s));
    01071       }
    01072
    01073       /**
    01074        *  @brief  Insert multiple characters.
    01075        *  @param pos  Index in string to insert at.
    01076        *  @param n  Number of characters to insert
    01077        *  @param c  The character to insert.
    01078        *  @return  Reference to this string.
    01079        *  @throw  std::length_error  If new length exceeds @c max_size().
    01080        *  @throw  std::out_of_range  If @a pos is beyond the end of this
    01081        *  string.
    01082        *
    01083        *  Inserts @a n copies of character @a c starting at index @a pos.  If
    01084        *  adding characters causes the length to exceed max_size(),
    01085        *  length_error is thrown.  If @a pos > length(), out_of_range is
    01086        *  thrown.  The value of the string doesn't change if an error is
    01087        *  thrown.
    01088       */
    01089       basic_string&
    01090       insert(size_type __pos, size_type __n, _CharT __c)
    01091       { return _M_replace_aux(_M_check(__pos, "basic_string::insert"),
    01092                   size_type(0), __n, __c); }
    01093
    01094       /**
    01095        *  @brief  Insert one character.
    01096        *  @param p  Iterator referencing position in string to insert at.
    01097        *  @param c  The character to insert.
    01098        *  @return  Iterator referencing newly inserted char.
    01099        *  @throw  std::length_error  If new length exceeds @c max_size().
    01100        *
    01101        *  Inserts character @a c at position referenced by @a p.  If adding
    01102        *  character causes the length to exceed max_size(), length_error is
    01103        *  thrown.  If @a p is beyond end of string, out_of_range is thrown.
    01104        *  The value of the string doesn't change if an error is thrown.
    01105       */
    01106       iterator
    01107       insert(iterator __p, _CharT __c)
    01108       {
    01109     _GLIBCXX_DEBUG_PEDASSERT(__p >= _M_ibegin() && __p <= _M_iend());
    01110     const size_type __pos = __p - _M_ibegin();
    01111     _M_replace_aux(__pos, size_type(0), size_type(1), __c);
    01112     _M_rep()->_M_set_leaked();
    01113     return iterator(_M_data() + __pos);
    01114       }
    01115
    01116       /**
    01117        *  @brief  Remove characters.
    01118        *  @param pos  Index of first character to remove (default 0).
    01119        *  @param n  Number of characters to remove (default remainder).
    01120        *  @return  Reference to this string.
    01121        *  @throw  std::out_of_range  If @a pos is beyond the end of this
    01122        *  string.
    01123        *
    01124        *  Removes @a n characters from this string starting at @a pos.  The
    01125        *  length of the string is reduced by @a n.  If there are < @a n
    01126        *  characters to remove, the remainder of the string is truncated.  If
    01127        *  @a p is beyond end of string, out_of_range is thrown.  The value of
    01128        *  the string doesn't change if an error is thrown.
    01129       */
    01130       basic_string&
    01131       erase(size_type __pos = 0, size_type __n = npos)
    01132       {
    01133     _M_mutate(_M_check(__pos, "basic_string::erase"),
    01134           _M_limit(__pos, __n), size_type(0));
    01135     return *this;
    01136       }
    01137
    01138       /**
    01139        *  @brief  Remove one character.
    01140        *  @param position  Iterator referencing the character to remove.
    01141        *  @return  iterator referencing same location after removal.
    01142        *
    01143        *  Removes the character at @a position from this string. The value
    01144        *  of the string doesn't change if an error is thrown.
    01145       */
    01146       iterator
    01147       erase(iterator __position)
    01148       {
    01149     _GLIBCXX_DEBUG_PEDASSERT(__position >= _M_ibegin()
    01150                  && __position < _M_iend());
    01151     const size_type __pos = __position - _M_ibegin();
    01152     _M_mutate(__pos, size_type(1), size_type(0));
    01153     _M_rep()->_M_set_leaked();
    01154     return iterator(_M_data() + __pos);
    01155       }
    01156
    01157       /**
    01158        *  @brief  Remove a range of characters.
    01159        *  @param first  Iterator referencing the first character to remove.
    01160        *  @param last  Iterator referencing the end of the range.
    01161        *  @return  Iterator referencing location of first after removal.
    01162        *
    01163        *  Removes the characters in the range [first,last) from this string.
    01164        *  The value of the string doesn't change if an error is thrown.
    01165       */
    01166       iterator
    01167       erase(iterator __first, iterator __last)
    01168       {
    01169     _GLIBCXX_DEBUG_PEDASSERT(__first >= _M_ibegin() && __first <= __last
    01170                  && __last <= _M_iend());
    01171         const size_type __pos = __first - _M_ibegin();
    01172     _M_mutate(__pos, __last - __first, size_type(0));
    01173     _M_rep()->_M_set_leaked();
    01174     return iterator(_M_data() + __pos);
    01175       }
    01176
    01177       /**
    01178        *  @brief  Replace characters with value from another string.
    01179        *  @param pos  Index of first character to replace.
    01180        *  @param n  Number of characters to be replaced.
    01181        *  @param str  String to insert.
    01182        *  @return  Reference to this string.
    01183        *  @throw  std::out_of_range  If @a pos is beyond the end of this
    01184        *  string.
    01185        *  @throw  std::length_error  If new length exceeds @c max_size().
    01186        *
    01187        *  Removes the characters in the range [pos,pos+n) from this string.
    01188        *  In place, the value of @a str is inserted.  If @a pos is beyond end
    01189        *  of string, out_of_range is thrown.  If the length of the result
    01190        *  exceeds max_size(), length_error is thrown.  The value of the string
    01191        *  doesn't change if an error is thrown.
    01192       */
    01193       basic_string&
    01194       replace(size_type __pos, size_type __n, const basic_string& __str)
    01195       { return this->replace(__pos, __n, __str._M_data(), __str.size()); }
    01196
    01197       /**
    01198        *  @brief  Replace characters with value from another string.
    01199        *  @param pos1  Index of first character to replace.
    01200        *  @param n1  Number of characters to be replaced.
    01201        *  @param str  String to insert.
    01202        *  @param pos2  Index of first character of str to use.
    01203        *  @param n2  Number of characters from str to use.
    01204        *  @return  Reference to this string.
    01205        *  @throw  std::out_of_range  If @a pos1 > size() or @a pos2 >
    01206        *  str.size().
    01207        *  @throw  std::length_error  If new length exceeds @c max_size().
    01208        *
    01209        *  Removes the characters in the range [pos1,pos1 + n) from this
    01210        *  string.  In place, the value of @a str is inserted.  If @a pos is
    01211        *  beyond end of string, out_of_range is thrown.  If the length of the
    01212        *  result exceeds max_size(), length_error is thrown.  The value of the
    01213        *  string doesn't change if an error is thrown.
    01214       */
    01215       basic_string&
    01216       replace(size_type __pos1, size_type __n1, const basic_string& __str,
    01217           size_type __pos2, size_type __n2)
    01218       { return this->replace(__pos1, __n1, __str._M_data()
    01219                  + __str._M_check(__pos2, "basic_string::replace"),
    01220                  __str._M_limit(__pos2, __n2)); }
    01221
    01222       /**
    01223        *  @brief  Replace characters with value of a C substring.
    01224        *  @param pos  Index of first character to replace.
    01225        *  @param n1  Number of characters to be replaced.
    01226        *  @param s  C string to insert.
    01227        *  @param n2  Number of characters from @a s to use.
    01228        *  @return  Reference to this string.
    01229        *  @throw  std::out_of_range  If @a pos1 > size().
    01230        *  @throw  std::length_error  If new length exceeds @c max_size().
    01231        *
    01232        *  Removes the characters in the range [pos,pos + n1) from this string.
    01233        *  In place, the first @a n2 characters of @a s are inserted, or all
    01234        *  of @a s if @a n2 is too large.  If @a pos is beyond end of string,
    01235        *  out_of_range is thrown.  If the length of result exceeds max_size(),
    01236        *  length_error is thrown.  The value of the string doesn't change if
    01237        *  an error is thrown.
    01238       */
    01239       basic_string&
    01240       replace(size_type __pos, size_type __n1, const _CharT* __s,
    01241           size_type __n2);
    01242
    01243       /**
    01244        *  @brief  Replace characters with value of a C string.
    01245        *  @param pos  Index of first character to replace.
    01246        *  @param n1  Number of characters to be replaced.
    01247        *  @param s  C string to insert.
    01248        *  @return  Reference to this string.
    01249        *  @throw  std::out_of_range  If @a pos > size().
    01250        *  @throw  std::length_error  If new length exceeds @c max_size().
    01251        *
    01252        *  Removes the characters in the range [pos,pos + n1) from this string.
    01253        *  In place, the first @a n characters of @a s are inserted.  If @a
    01254        *  pos is beyond end of string, out_of_range is thrown.  If the length
    01255        *  of result exceeds max_size(), length_error is thrown.  The value of
    01256        *  the string doesn't change if an error is thrown.
    01257       */
    01258       basic_string&
    01259       replace(size_type __pos, size_type __n1, const _CharT* __s)
    01260       {
    01261     __glibcxx_requires_string(__s);
    01262     return this->replace(__pos, __n1, __s, traits_type::length(__s));
    01263       }
    01264
    01265       /**
    01266        *  @brief  Replace characters with multiple characters.
    01267        *  @param pos  Index of first character to replace.
    01268        *  @param n1  Number of characters to be replaced.
    01269        *  @param n2  Number of characters to insert.
    01270        *  @param c  Character to insert.
    01271        *  @return  Reference to this string.
    01272        *  @throw  std::out_of_range  If @a pos > size().
    01273        *  @throw  std::length_error  If new length exceeds @c max_size().
    01274        *
    01275        *  Removes the characters in the range [pos,pos + n1) from this string.
    01276        *  In place, @a n2 copies of @a c are inserted.  If @a pos is beyond
    01277        *  end of string, out_of_range is thrown.  If the length of result
    01278        *  exceeds max_size(), length_error is thrown.  The value of the string
    01279        *  doesn't change if an error is thrown.
    01280       */
    01281       basic_string&
    01282       replace(size_type __pos, size_type __n1, size_type __n2, _CharT __c)
    01283       { return _M_replace_aux(_M_check(__pos, "basic_string::replace"),
    01284                   _M_limit(__pos, __n1), __n2, __c); }
    01285
    01286       /**
    01287        *  @brief  Replace range of characters with string.
    01288        *  @param i1  Iterator referencing start of range to replace.
    01289        *  @param i2  Iterator referencing end of range to replace.
    01290        *  @param str  String value to insert.
    01291        *  @return  Reference to this string.
    01292        *  @throw  std::length_error  If new length exceeds @c max_size().
    01293        *
    01294        *  Removes the characters in the range [i1,i2).  In place, the value of
    01295        *  @a str is inserted.  If the length of result exceeds max_size(),
    01296        *  length_error is thrown.  The value of the string doesn't change if
    01297        *  an error is thrown.
    01298       */
    01299       basic_string&
    01300       replace(iterator __i1, iterator __i2, const basic_string& __str)
    01301       { return this->replace(__i1, __i2, __str._M_data(), __str.size()); }
    01302
    01303       /**
    01304        *  @brief  Replace range of characters with C substring.
    01305        *  @param i1  Iterator referencing start of range to replace.
    01306        *  @param i2  Iterator referencing end of range to replace.
    01307        *  @param s  C string value to insert.
    01308        *  @param n  Number of characters from s to insert.
    01309        *  @return  Reference to this string.
    01310        *  @throw  std::length_error  If new length exceeds @c max_size().
    01311        *
    01312        *  Removes the characters in the range [i1,i2).  In place, the first @a
    01313        *  n characters of @a s are inserted.  If the length of result exceeds
    01314        *  max_size(), length_error is thrown.  The value of the string doesn't
    01315        *  change if an error is thrown.
    01316       */
    01317       basic_string&
    01318       replace(iterator __i1, iterator __i2, const _CharT* __s, size_type __n)
    01319       {
    01320     _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1 && __i1 <= __i2
    01321                  && __i2 <= _M_iend());
    01322     return this->replace(__i1 - _M_ibegin(), __i2 - __i1, __s, __n);
    01323       }
    01324
    01325       /**
    01326        *  @brief  Replace range of characters with C string.
    01327        *  @param i1  Iterator referencing start of range to replace.
    01328        *  @param i2  Iterator referencing end of range to replace.
    01329        *  @param s  C string value to insert.
    01330        *  @return  Reference to this string.
    01331        *  @throw  std::length_error  If new length exceeds @c max_size().
    01332        *
    01333        *  Removes the characters in the range [i1,i2).  In place, the
    01334        *  characters of @a s are inserted.  If the length of result exceeds
    01335        *  max_size(), length_error is thrown.  The value of the string doesn't
    01336        *  change if an error is thrown.
    01337       */
    01338       basic_string&
    01339       replace(iterator __i1, iterator __i2, const _CharT* __s)
    01340       {
    01341     __glibcxx_requires_string(__s);
    01342     return this->replace(__i1, __i2, __s, traits_type::length(__s));
    01343       }
    01344
    01345       /**
    01346        *  @brief  Replace range of characters with multiple characters
    01347        *  @param i1  Iterator referencing start of range to replace.
    01348        *  @param i2  Iterator referencing end of range to replace.
    01349        *  @param n  Number of characters to insert.
    01350        *  @param c  Character to insert.
    01351        *  @return  Reference to this string.
    01352        *  @throw  std::length_error  If new length exceeds @c max_size().
    01353        *
    01354        *  Removes the characters in the range [i1,i2).  In place, @a n copies
    01355        *  of @a c are inserted.  If the length of result exceeds max_size(),
    01356        *  length_error is thrown.  The value of the string doesn't change if
    01357        *  an error is thrown.
    01358       */
    01359       basic_string&
    01360       replace(iterator __i1, iterator __i2, size_type __n, _CharT __c)
    01361       {
    01362     _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1 && __i1 <= __i2
    01363                  && __i2 <= _M_iend());
    01364     return _M_replace_aux(__i1 - _M_ibegin(), __i2 - __i1, __n, __c);
    01365       }
    01366
    01367       /**
    01368        *  @brief  Replace range of characters with range.
    01369        *  @param i1  Iterator referencing start of range to replace.
    01370        *  @param i2  Iterator referencing end of range to replace.
    01371        *  @param k1  Iterator referencing start of range to insert.
    01372        *  @param k2  Iterator referencing end of range to insert.
    01373        *  @return  Reference to this string.
    01374        *  @throw  std::length_error  If new length exceeds @c max_size().
    01375        *
    01376        *  Removes the characters in the range [i1,i2).  In place, characters
    01377        *  in the range [k1,k2) are inserted.  If the length of result exceeds
    01378        *  max_size(), length_error is thrown.  The value of the string doesn't
    01379        *  change if an error is thrown.
    01380       */
    01381       template<class _InputIterator>
    01382         basic_string&
    01383         replace(iterator __i1, iterator __i2,
    01384         _InputIterator __k1, _InputIterator __k2)
    01385         {
    01386       _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1 && __i1 <= __i2
    01387                    && __i2 <= _M_iend());
    01388       __glibcxx_requires_valid_range(__k1, __k2);
    01389       typedef typename std::__is_integer<_InputIterator>::__type _Integral;
    01390       return _M_replace_dispatch(__i1, __i2, __k1, __k2, _Integral());
    01391     }
    01392
    01393       // Specializations for the common case of pointer and iterator:
    01394       // useful to avoid the overhead of temporary buffering in _M_replace.
    01395       basic_string&
    01396       replace(iterator __i1, iterator __i2, _CharT* __k1, _CharT* __k2)
    01397       {
    01398     _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1 && __i1 <= __i2
    01399                  && __i2 <= _M_iend());
    01400     __glibcxx_requires_valid_range(__k1, __k2);
    01401     return this->replace(__i1 - _M_ibegin(), __i2 - __i1,
    01402                  __k1, __k2 - __k1);
    01403       }
    01404
    01405       basic_string&
    01406       replace(iterator __i1, iterator __i2,
    01407           const _CharT* __k1, const _CharT* __k2)
    01408       {
    01409     _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1 && __i1 <= __i2
    01410                  && __i2 <= _M_iend());
    01411     __glibcxx_requires_valid_range(__k1, __k2);
    01412     return this->replace(__i1 - _M_ibegin(), __i2 - __i1,
    01413                  __k1, __k2 - __k1);
    01414       }
    01415
    01416       basic_string&
    01417       replace(iterator __i1, iterator __i2, iterator __k1, iterator __k2)
    01418       {
    01419     _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1 && __i1 <= __i2
    01420                  && __i2 <= _M_iend());
    01421     __glibcxx_requires_valid_range(__k1, __k2);
    01422     return this->replace(__i1 - _M_ibegin(), __i2 - __i1,
    01423                  __k1.base(), __k2 - __k1);
    01424       }
    01425
    01426       basic_string&
    01427       replace(iterator __i1, iterator __i2,
    01428           const_iterator __k1, const_iterator __k2)
    01429       {
    01430     _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1 && __i1 <= __i2
    01431                  && __i2 <= _M_iend());
    01432     __glibcxx_requires_valid_range(__k1, __k2);
    01433     return this->replace(__i1 - _M_ibegin(), __i2 - __i1,
    01434                  __k1.base(), __k2 - __k1);
    01435       }
    01436
    01437     private:
    01438       template<class _Integer>
    01439     basic_string&
    01440     _M_replace_dispatch(iterator __i1, iterator __i2, _Integer __n,
    01441                 _Integer __val, __true_type)
    01442         { return _M_replace_aux(__i1 - _M_ibegin(), __i2 - __i1, __n, __val); }
    01443
    01444       template<class _InputIterator>
    01445     basic_string&
    01446     _M_replace_dispatch(iterator __i1, iterator __i2, _InputIterator __k1,
    01447                 _InputIterator __k2, __false_type);
    01448
    01449       basic_string&
    01450       _M_replace_aux(size_type __pos1, size_type __n1, size_type __n2,
    01451              _CharT __c);
    01452
    01453       basic_string&
    01454       _M_replace_safe(size_type __pos1, size_type __n1, const _CharT* __s,
    01455               size_type __n2);
    01456
    01457       // _S_construct_aux is used to implement the 21.3.1 para 15 which
    01458       // requires special behaviour if _InIter is an integral type
    01459       template<class _InIterator>
    01460         static _CharT*
    01461         _S_construct_aux(_InIterator __beg, _InIterator __end,
    01462              const _Alloc& __a, __false_type)
    01463     {
    01464           typedef typename iterator_traits<_InIterator>::iterator_category _Tag;
    01465           return _S_construct(__beg, __end, __a, _Tag());
    01466     }
    01467
    01468       // _GLIBCXX_RESOLVE_LIB_DEFECTS
    01469       // 438. Ambiguity in the "do the right thing" clause
    01470       template<class _Integer>
    01471         static _CharT*
    01472         _S_construct_aux(_Integer __beg, _Integer __end,
    01473              const _Alloc& __a, __true_type)
    01474         { return _S_construct(static_cast<size_type>(__beg), __end, __a); }
    01475
    01476       template<class _InIterator>
    01477         static _CharT*
    01478         _S_construct(_InIterator __beg, _InIterator __end, const _Alloc& __a)
    01479     {
    01480       typedef typename std::__is_integer<_InIterator>::__type _Integral;
    01481       return _S_construct_aux(__beg, __end, __a, _Integral());
    01482         }
    01483
    01484       // For Input Iterators, used in istreambuf_iterators, etc.
    01485       template<class _InIterator>
    01486         static _CharT*
    01487          _S_construct(_InIterator __beg, _InIterator __end, const _Alloc& __a,
    01488               input_iterator_tag);
    01489
    01490       // For forward_iterators up to random_access_iterators, used for
    01491       // string::iterator, _CharT*, etc.
    01492       template<class _FwdIterator>
    01493         static _CharT*
    01494         _S_construct(_FwdIterator __beg, _FwdIterator __end, const _Alloc& __a,
    01495              forward_iterator_tag);
    01496
    01497       static _CharT*
    01498       _S_construct(size_type __req, _CharT __c, const _Alloc& __a);
    01499
    01500     public:
    01501
    01502       /**
    01503        *  @brief  Copy substring into C string.
    01504        *  @param s  C string to copy value into.
    01505        *  @param n  Number of characters to copy.
    01506        *  @param pos  Index of first character to copy.
    01507        *  @return  Number of characters actually copied
    01508        *  @throw  std::out_of_range  If pos > size().
    01509        *
    01510        *  Copies up to @a n characters starting at @a pos into the C string @a
    01511        *  s.  If @a pos is greater than size(), out_of_range is thrown.
    01512       */
    01513       size_type
    01514       copy(_CharT* __s, size_type __n, size_type __pos = 0) const;
    01515
    01516       /**
    01517        *  @brief  Swap contents with another string.
    01518        *  @param s  String to swap with.
    01519        *
    01520        *  Exchanges the contents of this string with that of @a s in constant
    01521        *  time.
    01522       */
    01523       void
    01524       swap(basic_string& __s);
    01525
    01526       // String operations:
    01527       /**
    01528        *  @brief  Return const pointer to null-terminated contents.
    01529        *
    01530        *  This is a handle to internal data.  Do not modify or dire things may
    01531        *  happen.
    01532       */
    01533       const _CharT*
    01534       c_str() const
    01535       { return _M_data(); }
    01536
    01537       /**
    01538        *  @brief  Return const pointer to contents.
    01539        *
    01540        *  This is a handle to internal data.  Do not modify or dire things may
    01541        *  happen.
    01542       */
    01543       const _CharT*
    01544       data() const
    01545       { return _M_data(); }
    01546
    01547       /**
    01548        *  @brief  Return copy of allocator used to construct this string.
    01549       */
    01550       allocator_type
    01551       get_allocator() const
    01552       { return _M_dataplus; }
    01553
    01554       /**
    01555        *  @brief  Find position of a C substring.
    01556        *  @param s  C string to locate.
    01557        *  @param pos  Index of character to search from.
    01558        *  @param n  Number of characters from @a s to search for.
    01559        *  @return  Index of start of first occurrence.
    01560        *
    01561        *  Starting from @a pos, searches forward for the first @a n characters
    01562        *  in @a s within this string.  If found, returns the index where it
    01563        *  begins.  If not found, returns npos.
    01564       */
    01565       size_type
    01566       find(const _CharT* __s, size_type __pos, size_type __n) const;
    01567
    01568       /**
    01569        *  @brief  Find position of a string.
    01570        *  @param str  String to locate.
    01571        *  @param pos  Index of character to search from (default 0).
    01572        *  @return  Index of start of first occurrence.
    01573        *
    01574        *  Starting from @a pos, searches forward for value of @a str within
    01575        *  this string.  If found, returns the index where it begins.  If not
    01576        *  found, returns npos.
    01577       */
    01578       size_type
    01579       find(const basic_string& __str, size_type __pos = 0) const
    01580       { return this->find(__str.data(), __pos, __str.size()); }
    01581
    01582       /**
    01583        *  @brief  Find position of a C string.
    01584        *  @param s  C string to locate.
    01585        *  @param pos  Index of character to search from (default 0).
    01586        *  @return  Index of start of first occurrence.
    01587        *
    01588        *  Starting from @a pos, searches forward for the value of @a s within
    01589        *  this string.  If found, returns the index where it begins.  If not
    01590        *  found, returns npos.
    01591       */
    01592       size_type
    01593       find(const _CharT* __s, size_type __pos = 0) const
    01594       {
    01595     __glibcxx_requires_string(__s);
    01596     return this->find(__s, __pos, traits_type::length(__s));
    01597       }
    01598
    01599       /**
    01600        *  @brief  Find position of a character.
    01601        *  @param c  Character to locate.
    01602        *  @param pos  Index of character to search from (default 0).
    01603        *  @return  Index of first occurrence.
    01604        *
    01605        *  Starting from @a pos, searches forward for @a c within this string.
    01606        *  If found, returns the index where it was found.  If not found,
    01607        *  returns npos.
    01608       */
    01609       size_type
    01610       find(_CharT __c, size_type __pos = 0) const;
    01611
    01612       /**
    01613        *  @brief  Find last position of a string.
    01614        *  @param str  String to locate.
    01615        *  @param pos  Index of character to search back from (default end).
    01616        *  @return  Index of start of last occurrence.
    01617        *
    01618        *  Starting from @a pos, searches backward for value of @a str within
    01619        *  this string.  If found, returns the index where it begins.  If not
    01620        *  found, returns npos.
    01621       */
    01622       size_type
    01623       rfind(const basic_string& __str, size_type __pos = npos) const
    01624       { return this->rfind(__str.data(), __pos, __str.size()); }
    01625
    01626       /**
    01627        *  @brief  Find last position of a C substring.
    01628        *  @param s  C string to locate.
    01629        *  @param pos  Index of character to search back from.
    01630        *  @param n  Number of characters from s to search for.
    01631        *  @return  Index of start of last occurrence.
    01632        *
    01633        *  Starting from @a pos, searches backward for the first @a n
    01634        *  characters in @a s within this string.  If found, returns the index
    01635        *  where it begins.  If not found, returns npos.
    01636       */
    01637       size_type
    01638       rfind(const _CharT* __s, size_type __pos, size_type __n) const;
    01639
    01640       /**
    01641        *  @brief  Find last position of a C string.
    01642        *  @param s  C string to locate.
    01643        *  @param pos  Index of character to start search at (default end).
    01644        *  @return  Index of start of  last occurrence.
    01645        *
    01646        *  Starting from @a pos, searches backward for the value of @a s within
    01647        *  this string.  If found, returns the index where it begins.  If not
    01648        *  found, returns npos.
    01649       */
    01650       size_type
    01651       rfind(const _CharT* __s, size_type __pos = npos) const
    01652       {
    01653     __glibcxx_requires_string(__s);
    01654     return this->rfind(__s, __pos, traits_type::length(__s));
    01655       }
    01656
    01657       /**
    01658        *  @brief  Find last position of a character.
    01659        *  @param c  Character to locate.
    01660        *  @param pos  Index of character to search back from (default end).
    01661        *  @return  Index of last occurrence.
    01662        *
    01663        *  Starting from @a pos, searches backward for @a c within this string.
    01664        *  If found, returns the index where it was found.  If not found,
    01665        *  returns npos.
    01666       */
    01667       size_type
    01668       rfind(_CharT __c, size_type __pos = npos) const;
    01669
    01670       /**
    01671        *  @brief  Find position of a character of string.
    01672        *  @param str  String containing characters to locate.
    01673        *  @param pos  Index of character to search from (default 0).
    01674        *  @return  Index of first occurrence.
    01675        *
    01676        *  Starting from @a pos, searches forward for one of the characters of
    01677        *  @a str within this string.  If found, returns the index where it was
    01678        *  found.  If not found, returns npos.
    01679       */
    01680       size_type
    01681       find_first_of(const basic_string& __str, size_type __pos = 0) const
    01682       { return this->find_first_of(__str.data(), __pos, __str.size()); }
    01683
    01684       /**
    01685        *  @brief  Find position of a character of C substring.
    01686        *  @param s  String containing characters to locate.
    01687        *  @param pos  Index of character to search from.
    01688        *  @param n  Number of characters from s to search for.
    01689        *  @return  Index of first occurrence.
    01690        *
    01691        *  Starting from @a pos, searches forward for one of the first @a n
    01692        *  characters of @a s within this string.  If found, returns the index
    01693        *  where it was found.  If not found, returns npos.
    01694       */
    01695       size_type
    01696       find_first_of(const _CharT* __s, size_type __pos, size_type __n) const;
    01697
    01698       /**
    01699        *  @brief  Find position of a character of C string.
    01700        *  @param s  String containing characters to locate.
    01701        *  @param pos  Index of character to search from (default 0).
    01702        *  @return  Index of first occurrence.
    01703        *
    01704        *  Starting from @a pos, searches forward for one of the characters of
    01705        *  @a s within this string.  If found, returns the index where it was
    01706        *  found.  If not found, returns npos.
    01707       */
    01708       size_type
    01709       find_first_of(const _CharT* __s, size_type __pos = 0) const
    01710       {
    01711     __glibcxx_requires_string(__s);
    01712     return this->find_first_of(__s, __pos, traits_type::length(__s));
    01713       }
    01714
    01715       /**
    01716        *  @brief  Find position of a character.
    01717        *  @param c  Character to locate.
    01718        *  @param pos  Index of character to search from (default 0).
    01719        *  @return  Index of first occurrence.
    01720        *
    01721        *  Starting from @a pos, searches forward for the character @a c within
    01722        *  this string.  If found, returns the index where it was found.  If
    01723        *  not found, returns npos.
    01724        *
    01725        *  Note: equivalent to find(c, pos).
    01726       */
    01727       size_type
    01728       find_first_of(_CharT __c, size_type __pos = 0) const
    01729       { return this->find(__c, __pos); }
    01730
    01731       /**
    01732        *  @brief  Find last position of a character of string.
    01733        *  @param str  String containing characters to locate.
    01734        *  @param pos  Index of character to search back from (default end).
    01735        *  @return  Index of last occurrence.
    01736        *
    01737        *  Starting from @a pos, searches backward for one of the characters of
    01738        *  @a str within this string.  If found, returns the index where it was
    01739        *  found.  If not found, returns npos.
    01740       */
    01741       size_type
    01742       find_last_of(const basic_string& __str, size_type __pos = npos) const
    01743       { return this->find_last_of(__str.data(), __pos, __str.size()); }
    01744
    01745       /**
    01746        *  @brief  Find last position of a character of C substring.
    01747        *  @param s  C string containing characters to locate.
    01748        *  @param pos  Index of character to search back from.
    01749        *  @param n  Number of characters from s to search for.
    01750        *  @return  Index of last occurrence.
    01751        *
    01752        *  Starting from @a pos, searches backward for one of the first @a n
    01753        *  characters of @a s within this string.  If found, returns the index
    01754        *  where it was found.  If not found, returns npos.
    01755       */
    01756       size_type
    01757       find_last_of(const _CharT* __s, size_type __pos, size_type __n) const;
    01758
    01759       /**
    01760        *  @brief  Find last position of a character of C string.
    01761        *  @param s  C string containing characters to locate.
    01762        *  @param pos  Index of character to search back from (default end).
    01763        *  @return  Index of last occurrence.
    01764        *
    01765        *  Starting from @a pos, searches backward for one of the characters of
    01766        *  @a s within this string.  If found, returns the index where it was
    01767        *  found.  If not found, returns npos.
    01768       */
    01769       size_type
    01770       find_last_of(const _CharT* __s, size_type __pos = npos) const
    01771       {
    01772     __glibcxx_requires_string(__s);
    01773     return this->find_last_of(__s, __pos, traits_type::length(__s));
    01774       }
    01775
    01776       /**
    01777        *  @brief  Find last position of a character.
    01778        *  @param c  Character to locate.
    01779        *  @param pos  Index of character to search back from (default end).
    01780        *  @return  Index of last occurrence.
    01781        *
    01782        *  Starting from @a pos, searches backward for @a c within this string.
    01783        *  If found, returns the index where it was found.  If not found,
    01784        *  returns npos.
    01785        *
    01786        *  Note: equivalent to rfind(c, pos).
    01787       */
    01788       size_type
    01789       find_last_of(_CharT __c, size_type __pos = npos) const
    01790       { return this->rfind(__c, __pos); }
    01791
    01792       /**
    01793        *  @brief  Find position of a character not in string.
    01794        *  @param str  String containing characters to avoid.
    01795        *  @param pos  Index of character to search from (default 0).
    01796        *  @return  Index of first occurrence.
    01797        *
    01798        *  Starting from @a pos, searches forward for a character not contained
    01799        *  in @a str within this string.  If found, returns the index where it
    01800        *  was found.  If not found, returns npos.
    01801       */
    01802       size_type
    01803       find_first_not_of(const basic_string& __str, size_type __pos = 0) const
    01804       { return this->find_first_not_of(__str.data(), __pos, __str.size()); }
    01805
    01806       /**
    01807        *  @brief  Find position of a character not in C substring.
    01808        *  @param s  C string containing characters to avoid.
    01809        *  @param pos  Index of character to search from.
    01810        *  @param n  Number of characters from s to consider.
    01811        *  @return  Index of first occurrence.
    01812        *
    01813        *  Starting from @a pos, searches forward for a character not contained
    01814        *  in the first @a n characters of @a s within this string.  If found,
    01815        *  returns the index where it was found.  If not found, returns npos.
    01816       */
    01817       size_type
    01818       find_first_not_of(const _CharT* __s, size_type __pos,
    01819             size_type __n) const;
    01820
    01821       /**
    01822        *  @brief  Find position of a character not in C string.
    01823        *  @param s  C string containing characters to avoid.
    01824        *  @param pos  Index of character to search from (default 0).
    01825        *  @return  Index of first occurrence.
    01826        *
    01827        *  Starting from @a pos, searches forward for a character not contained
    01828        *  in @a s within this string.  If found, returns the index where it
    01829        *  was found.  If not found, returns npos.
    01830       */
    01831       size_type
    01832       find_first_not_of(const _CharT* __s, size_type __pos = 0) const
    01833       {
    01834     __glibcxx_requires_string(__s);
    01835     return this->find_first_not_of(__s, __pos, traits_type::length(__s));
    01836       }
    01837
    01838       /**
    01839        *  @brief  Find position of a different character.
    01840        *  @param c  Character to avoid.
    01841        *  @param pos  Index of character to search from (default 0).
    01842        *  @return  Index of first occurrence.
    01843        *
    01844        *  Starting from @a pos, searches forward for a character other than @a c
    01845        *  within this string.  If found, returns the index where it was found.
    01846        *  If not found, returns npos.
    01847       */
    01848       size_type
    01849       find_first_not_of(_CharT __c, size_type __pos = 0) const;
    01850
    01851       /**
    01852        *  @brief  Find last position of a character not in string.
    01853        *  @param str  String containing characters to avoid.
    01854        *  @param pos  Index of character to search back from (default end).
    01855        *  @return  Index of last occurrence.
    01856        *
    01857        *  Starting from @a pos, searches backward for a character not
    01858        *  contained in @a str within this string.  If found, returns the index
    01859        *  where it was found.  If not found, returns npos.
    01860       */
    01861       size_type
    01862       find_last_not_of(const basic_string& __str, size_type __pos = npos) const
    01863       { return this->find_last_not_of(__str.data(), __pos, __str.size()); }
    01864
    01865       /**
    01866        *  @brief  Find last position of a character not in C substring.
    01867        *  @param s  C string containing characters to avoid.
    01868        *  @param pos  Index of character to search back from.
    01869        *  @param n  Number of characters from s to consider.
    01870        *  @return  Index of last occurrence.
    01871        *
    01872        *  Starting from @a pos, searches backward for a character not
    01873        *  contained in the first @a n characters of @a s within this string.
    01874        *  If found, returns the index where it was found.  If not found,
    01875        *  returns npos.
    01876       */
    01877       size_type
    01878       find_last_not_of(const _CharT* __s, size_type __pos,
    01879                size_type __n) const;
    01880       /**
    01881        *  @brief  Find last position of a character not in C string.
    01882        *  @param s  C string containing characters to avoid.
    01883        *  @param pos  Index of character to search back from (default end).
    01884        *  @return  Index of last occurrence.
    01885        *
    01886        *  Starting from @a pos, searches backward for a character not
    01887        *  contained in @a s within this string.  If found, returns the index
    01888        *  where it was found.  If not found, returns npos.
    01889       */
    01890       size_type
    01891       find_last_not_of(const _CharT* __s, size_type __pos = npos) const
    01892       {
    01893     __glibcxx_requires_string(__s);
    01894     return this->find_last_not_of(__s, __pos, traits_type::length(__s));
    01895       }
    01896
    01897       /**
    01898        *  @brief  Find last position of a different character.
    01899        *  @param c  Character to avoid.
    01900        *  @param pos  Index of character to search back from (default end).
    01901        *  @return  Index of last occurrence.
    01902        *
    01903        *  Starting from @a pos, searches backward for a character other than
    01904        *  @a c within this string.  If found, returns the index where it was
    01905        *  found.  If not found, returns npos.
    01906       */
    01907       size_type
    01908       find_last_not_of(_CharT __c, size_type __pos = npos) const;
    01909
    01910       /**
    01911        *  @brief  Get a substring.
    01912        *  @param pos  Index of first character (default 0).
    01913        *  @param n  Number of characters in substring (default remainder).
    01914        *  @return  The new string.
    01915        *  @throw  std::out_of_range  If pos > size().
    01916        *
    01917        *  Construct and return a new string using the @a n characters starting
    01918        *  at @a pos.  If the string is too short, use the remainder of the
    01919        *  characters.  If @a pos is beyond the end of the string, out_of_range
    01920        *  is thrown.
    01921       */
    01922       basic_string
    01923       substr(size_type __pos = 0, size_type __n = npos) const
    01924       { return basic_string(*this,
    01925                 _M_check(__pos, "basic_string::substr"), __n); }
    01926
    01927       /**
    01928        *  @brief  Compare to a string.
    01929        *  @param str  String to compare against.
    01930        *  @return  Integer < 0, 0, or > 0.
    01931        *
    01932        *  Returns an integer < 0 if this string is ordered before @a str, 0 if
    01933        *  their values are equivalent, or > 0 if this string is ordered after
    01934        *  @a str.  Determines the effective length rlen of the strings to
    01935        *  compare as the smallest of size() and str.size().  The function
    01936        *  then compares the two strings by calling traits::compare(data(),
    01937        *  str.data(),rlen).  If the result of the comparison is nonzero returns
    01938        *  it, otherwise the shorter one is ordered first.
    01939       */
    01940       int
    01941       compare(const basic_string& __str) const
    01942       {
    01943     const size_type __size = this->size();
    01944     const size_type __osize = __str.size();
    01945     const size_type __len = std::min(__size, __osize);
    01946
    01947     int __r = traits_type::compare(_M_data(), __str.data(), __len);
    01948     if (!__r)
    01949       __r = _S_compare(__size, __osize);
    01950     return __r;
    01951       }
    01952
    01953       /**
    01954        *  @brief  Compare substring to a string.
    01955        *  @param pos  Index of first character of substring.
    01956        *  @param n  Number of characters in substring.
    01957        *  @param str  String to compare against.
    01958        *  @return  Integer < 0, 0, or > 0.
    01959        *
    01960        *  Form the substring of this string from the @a n characters starting
    01961        *  at @a pos.  Returns an integer < 0 if the substring is ordered
    01962        *  before @a str, 0 if their values are equivalent, or > 0 if the
    01963        *  substring is ordered after @a str.  Determines the effective length
    01964        *  rlen of the strings to compare as the smallest of the length of the
    01965        *  substring and @a str.size().  The function then compares the two
    01966        *  strings by calling traits::compare(substring.data(),str.data(),rlen).
    01967        *  If the result of the comparison is nonzero returns it, otherwise the
    01968        *  shorter one is ordered first.
    01969       */
    01970       int
    01971       compare(size_type __pos, size_type __n, const basic_string& __str) const;
    01972
    01973       /**
    01974        *  @brief  Compare substring to a substring.
    01975        *  @param pos1  Index of first character of substring.
    01976        *  @param n1  Number of characters in substring.
    01977        *  @param str  String to compare against.
    01978        *  @param pos2  Index of first character of substring of str.
    01979        *  @param n2  Number of characters in substring of str.
    01980        *  @return  Integer < 0, 0, or > 0.
    01981        *
    01982        *  Form the substring of this string from the @a n1 characters starting
    01983        *  at @a pos1.  Form the substring of @a str from the @a n2 characters
    01984        *  starting at @a pos2.  Returns an integer < 0 if this substring is
    01985        *  ordered before the substring of @a str, 0 if their values are
    01986        *  equivalent, or > 0 if this substring is ordered after the substring
    01987        *  of @a str.  Determines the effective length rlen of the strings
    01988        *  to compare as the smallest of the lengths of the substrings.  The
    01989        *  function then compares the two strings by calling
    01990        *  traits::compare(substring.data(),str.substr(pos2,n2).data(),rlen).
    01991        *  If the result of the comparison is nonzero returns it, otherwise the
    01992        *  shorter one is ordered first.
    01993       */
    01994       int
    01995       compare(size_type __pos1, size_type __n1, const basic_string& __str,
    01996           size_type __pos2, size_type __n2) const;
    01997
    01998       /**
    01999        *  @brief  Compare to a C string.
    02000        *  @param s  C string to compare against.
    02001        *  @return  Integer < 0, 0, or > 0.
    02002        *
    02003        *  Returns an integer < 0 if this string is ordered before @a s, 0 if
    02004        *  their values are equivalent, or > 0 if this string is ordered after
    02005        *  @a s.  Determines the effective length rlen of the strings to
    02006        *  compare as the smallest of size() and the length of a string
    02007        *  constructed from @a s.  The function then compares the two strings
    02008        *  by calling traits::compare(data(),s,rlen).  If the result of the
    02009        *  comparison is nonzero returns it, otherwise the shorter one is
    02010        *  ordered first.
    02011       */
    02012       int
    02013       compare(const _CharT* __s) const;
    02014
    02015       // _GLIBCXX_RESOLVE_LIB_DEFECTS
    02016       // 5 String::compare specification questionable
    02017       /**
    02018        *  @brief  Compare substring to a C string.
    02019        *  @param pos  Index of first character of substring.
    02020        *  @param n1  Number of characters in substring.
    02021        *  @param s  C string to compare against.
    02022        *  @return  Integer < 0, 0, or > 0.
    02023        *
    02024        *  Form the substring of this string from the @a n1 characters starting
    02025        *  at @a pos.  Returns an integer < 0 if the substring is ordered
    02026        *  before @a s, 0 if their values are equivalent, or > 0 if the
    02027        *  substring is ordered after @a s.  Determines the effective length
    02028        *  rlen of the strings to compare as the smallest of the length of the
    02029        *  substring and the length of a string constructed from @a s.  The
    02030        *  function then compares the two string by calling
    02031        *  traits::compare(substring.data(),s,rlen).  If the result of the
    02032        *  comparison is nonzero returns it, otherwise the shorter one is
    02033        *  ordered first.
    02034       */
    02035       int
    02036       compare(size_type __pos, size_type __n1, const _CharT* __s) const;
    02037
    02038       /**
    02039        *  @brief  Compare substring against a character array.
    02040        *  @param pos1  Index of first character of substring.
    02041        *  @param n1  Number of characters in substring.
    02042        *  @param s  character array to compare against.
    02043        *  @param n2  Number of characters of s.
    02044        *  @return  Integer < 0, 0, or > 0.
    02045        *
    02046        *  Form the substring of this string from the @a n1 characters starting
    02047        *  at @a pos1.  Form a string from the first @a n2 characters of @a s.
    02048        *  Returns an integer < 0 if this substring is ordered before the string
    02049        *  from @a s, 0 if their values are equivalent, or > 0 if this substring
    02050        *  is ordered after the string from @a s.   Determines the effective
    02051        *  length rlen of the strings to compare as the smallest of the length
    02052        *  of the substring and @a n2.  The function then compares the two
    02053        *  strings by calling traits::compare(substring.data(),s,rlen).  If the
    02054        *  result of the comparison is nonzero returns it, otherwise the shorter
    02055        *  one is ordered first.
    02056        *
    02057        *  NB: s must have at least n2 characters, '\0' has no special
    02058        *  meaning.
    02059       */
    02060       int
    02061       compare(size_type __pos, size_type __n1, const _CharT* __s,
    02062           size_type __n2) const;
    02063   };
    02064
    02065   template<typename _CharT, typename _Traits, typename _Alloc>
    02066     inline basic_string<_CharT, _Traits, _Alloc>::
    02067     basic_string()
    02068 #ifndef _GLIBCXX_FULLY_DYNAMIC_STRING
    02069     : _M_dataplus(_S_empty_rep()._M_refdata(), _Alloc()) { }
    02070 #else
    02071     : _M_dataplus(_S_construct(size_type(), _CharT(), _Alloc()), _Alloc()) { }
    02072 #endif
    02073
    02074   // operator+
    02075   /**
    02076    *  @brief  Concatenate two strings.
    02077    *  @param lhs  First string.
    02078    *  @param rhs  Last string.
    02079    *  @return  New string with value of @a lhs followed by @a rhs.
    02080    */
    02081   template<typename _CharT, typename _Traits, typename _Alloc>
    02082     basic_string<_CharT, _Traits, _Alloc>
    02083     operator+(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
    02084           const basic_string<_CharT, _Traits, _Alloc>& __rhs)
    02085     {
    02086       basic_string<_CharT, _Traits, _Alloc> __str(__lhs);
    02087       __str.append(__rhs);
    02088       return __str;
    02089     }
    02090
    02091   /**
    02092    *  @brief  Concatenate C string and string.
    02093    *  @param lhs  First string.
    02094    *  @param rhs  Last string.
    02095    *  @return  New string with value of @a lhs followed by @a rhs.
    02096    */
    02097   template<typename _CharT, typename _Traits, typename _Alloc>
    02098     basic_string<_CharT,_Traits,_Alloc>
    02099     operator+(const _CharT* __lhs,
    02100           const basic_string<_CharT,_Traits,_Alloc>& __rhs);
    02101
    02102   /**
    02103    *  @brief  Concatenate character and string.
    02104    *  @param lhs  First string.
    02105    *  @param rhs  Last string.
    02106    *  @return  New string with @a lhs followed by @a rhs.
    02107    */
    02108   template<typename _CharT, typename _Traits, typename _Alloc>
    02109     basic_string<_CharT,_Traits,_Alloc>
    02110     operator+(_CharT __lhs, const basic_string<_CharT,_Traits,_Alloc>& __rhs);
    02111
    02112   /**
    02113    *  @brief  Concatenate string and C string.
    02114    *  @param lhs  First string.
    02115    *  @param rhs  Last string.
    02116    *  @return  New string with @a lhs followed by @a rhs.
    02117    */
    02118   template<typename _CharT, typename _Traits, typename _Alloc>
    02119     inline basic_string<_CharT, _Traits, _Alloc>
    02120     operator+(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
    02121          const _CharT* __rhs)
    02122     {
    02123       basic_string<_CharT, _Traits, _Alloc> __str(__lhs);
    02124       __str.append(__rhs);
    02125       return __str;
    02126     }
    02127
    02128   /**
    02129    *  @brief  Concatenate string and character.
    02130    *  @param lhs  First string.
    02131    *  @param rhs  Last string.
    02132    *  @return  New string with @a lhs followed by @a rhs.
    02133    */
    02134   template<typename _CharT, typename _Traits, typename _Alloc>
    02135     inline basic_string<_CharT, _Traits, _Alloc>
    02136     operator+(const basic_string<_CharT, _Traits, _Alloc>& __lhs, _CharT __rhs)
    02137     {
    02138       typedef basic_string<_CharT, _Traits, _Alloc> __string_type;
    02139       typedef typename __string_type::size_type     __size_type;
    02140       __string_type __str(__lhs);
    02141       __str.append(__size_type(1), __rhs);
    02142       return __str;
    02143     }
    02144
    02145   // operator ==
    02146   /**
    02147    *  @brief  Test equivalence of two strings.
    02148    *  @param lhs  First string.
    02149    *  @param rhs  Second string.
    02150    *  @return  True if @a lhs.compare(@a rhs) == 0.  False otherwise.
    02151    */
    02152   template<typename _CharT, typename _Traits, typename _Alloc>
    02153     inline bool
    02154     operator==(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
    02155            const basic_string<_CharT, _Traits, _Alloc>& __rhs)
    02156     { return __lhs.compare(__rhs) == 0; }
    02157
    02158   template<typename _CharT>
    02159     inline
    02160     typename __gnu_cxx::__enable_if<__is_char<_CharT>::__value, bool>::__type
    02161     operator==(const basic_string<_CharT>& __lhs,
    02162            const basic_string<_CharT>& __rhs)
    02163     { return (__lhs.size() == __rhs.size()
    02164           && !std::char_traits<_CharT>::compare(__lhs.data(), __rhs.data(),
    02165                             __lhs.size())); }
    02166
    02167   /**
    02168    *  @brief  Test equivalence of C string and string.
    02169    *  @param lhs  C string.
    02170    *  @param rhs  String.
    02171    *  @return  True if @a rhs.compare(@a lhs) == 0.  False otherwise.
    02172    */
    02173   template<typename _CharT, typename _Traits, typename _Alloc>
    02174     inline bool
    02175     operator==(const _CharT* __lhs,
    02176            const basic_string<_CharT, _Traits, _Alloc>& __rhs)
    02177     { return __rhs.compare(__lhs) == 0; }
    02178
    02179   /**
    02180    *  @brief  Test equivalence of string and C string.
    02181    *  @param lhs  String.
    02182    *  @param rhs  C string.
    02183    *  @return  True if @a lhs.compare(@a rhs) == 0.  False otherwise.
    02184    */
    02185   template<typename _CharT, typename _Traits, typename _Alloc>
    02186     inline bool
    02187     operator==(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
    02188            const _CharT* __rhs)
    02189     { return __lhs.compare(__rhs) == 0; }
    02190
    02191   // operator !=
    02192   /**
    02193    *  @brief  Test difference of two strings.
    02194    *  @param lhs  First string.
    02195    *  @param rhs  Second string.
    02196    *  @return  True if @a lhs.compare(@a rhs) != 0.  False otherwise.
    02197    */
    02198   template<typename _CharT, typename _Traits, typename _Alloc>
    02199     inline bool
    02200     operator!=(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
    02201            const basic_string<_CharT, _Traits, _Alloc>& __rhs)
    02202     { return !(__lhs == __rhs); }
    02203
    02204   /**
    02205    *  @brief  Test difference of C string and string.
    02206    *  @param lhs  C string.
    02207    *  @param rhs  String.
    02208    *  @return  True if @a rhs.compare(@a lhs) != 0.  False otherwise.
    02209    */
    02210   template<typename _CharT, typename _Traits, typename _Alloc>
    02211     inline bool
    02212     operator!=(const _CharT* __lhs,
    02213            const basic_string<_CharT, _Traits, _Alloc>& __rhs)
    02214     { return !(__lhs == __rhs); }
    02215
    02216   /**
    02217    *  @brief  Test difference of string and C string.
    02218    *  @param lhs  String.
    02219    *  @param rhs  C string.
    02220    *  @return  True if @a lhs.compare(@a rhs) != 0.  False otherwise.
    02221    */
    02222   template<typename _CharT, typename _Traits, typename _Alloc>
    02223     inline bool
    02224     operator!=(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
    02225            const _CharT* __rhs)
    02226     { return !(__lhs == __rhs); }
    02227
    02228   // operator <
    02229   /**
    02230    *  @brief  Test if string precedes string.
    02231    *  @param lhs  First string.
    02232    *  @param rhs  Second string.
    02233    *  @return  True if @a lhs precedes @a rhs.  False otherwise.
    02234    */
    02235   template<typename _CharT, typename _Traits, typename _Alloc>
    02236     inline bool
    02237     operator<(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
    02238           const basic_string<_CharT, _Traits, _Alloc>& __rhs)
    02239     { return __lhs.compare(__rhs) < 0; }
    02240
    02241   /**
    02242    *  @brief  Test if string precedes C string.
    02243    *  @param lhs  String.
    02244    *  @param rhs  C string.
    02245    *  @return  True if @a lhs precedes @a rhs.  False otherwise.
    02246    */
    02247   template<typename _CharT, typename _Traits, typename _Alloc>
    02248     inline bool
    02249     operator<(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
    02250           const _CharT* __rhs)
    02251     { return __lhs.compare(__rhs) < 0; }
    02252
    02253   /**
    02254    *  @brief  Test if C string precedes string.
    02255    *  @param lhs  C string.
    02256    *  @param rhs  String.
    02257    *  @return  True if @a lhs precedes @a rhs.  False otherwise.
    02258    */
    02259   template<typename _CharT, typename _Traits, typename _Alloc>
    02260     inline bool
    02261     operator<(const _CharT* __lhs,
    02262           const basic_string<_CharT, _Traits, _Alloc>& __rhs)
    02263     { return __rhs.compare(__lhs) > 0; }
    02264
    02265   // operator >
    02266   /**
    02267    *  @brief  Test if string follows string.
    02268    *  @param lhs  First string.
    02269    *  @param rhs  Second string.
    02270    *  @return  True if @a lhs follows @a rhs.  False otherwise.
    02271    */
    02272   template<typename _CharT, typename _Traits, typename _Alloc>
    02273     inline bool
    02274     operator>(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
    02275           const basic_string<_CharT, _Traits, _Alloc>& __rhs)
    02276     { return __lhs.compare(__rhs) > 0; }
    02277
    02278   /**
    02279    *  @brief  Test if string follows C string.
    02280    *  @param lhs  String.
    02281    *  @param rhs  C string.
    02282    *  @return  True if @a lhs follows @a rhs.  False otherwise.
    02283    */
    02284   template<typename _CharT, typename _Traits, typename _Alloc>
    02285     inline bool
    02286     operator>(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
    02287           const _CharT* __rhs)
    02288     { return __lhs.compare(__rhs) > 0; }
    02289
    02290   /**
    02291    *  @brief  Test if C string follows string.
    02292    *  @param lhs  C string.
    02293    *  @param rhs  String.
    02294    *  @return  True if @a lhs follows @a rhs.  False otherwise.
    02295    */
    02296   template<typename _CharT, typename _Traits, typename _Alloc>
    02297     inline bool
    02298     operator>(const _CharT* __lhs,
    02299           const basic_string<_CharT, _Traits, _Alloc>& __rhs)
    02300     { return __rhs.compare(__lhs) < 0; }
    02301
    02302   // operator <=
    02303   /**
    02304    *  @brief  Test if string doesn't follow string.
    02305    *  @param lhs  First string.
    02306    *  @param rhs  Second string.
    02307    *  @return  True if @a lhs doesn't follow @a rhs.  False otherwise.
    02308    */
    02309   template<typename _CharT, typename _Traits, typename _Alloc>
    02310     inline bool
    02311     operator<=(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
    02312            const basic_string<_CharT, _Traits, _Alloc>& __rhs)
    02313     { return __lhs.compare(__rhs) <= 0; }
    02314
    02315   /**
    02316    *  @brief  Test if string doesn't follow C string.
    02317    *  @param lhs  String.
    02318    *  @param rhs  C string.
    02319    *  @return  True if @a lhs doesn't follow @a rhs.  False otherwise.
    02320    */
    02321   template<typename _CharT, typename _Traits, typename _Alloc>
    02322     inline bool
    02323     operator<=(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
    02324            const _CharT* __rhs)
    02325     { return __lhs.compare(__rhs) <= 0; }
    02326
    02327   /**
    02328    *  @brief  Test if C string doesn't follow string.
    02329    *  @param lhs  C string.
    02330    *  @param rhs  String.
    02331    *  @return  True if @a lhs doesn't follow @a rhs.  False otherwise.
    02332    */
    02333   template<typename _CharT, typename _Traits, typename _Alloc>
    02334     inline bool
    02335     operator<=(const _CharT* __lhs,
    02336            const basic_string<_CharT, _Traits, _Alloc>& __rhs)
    02337     { return __rhs.compare(__lhs) >= 0; }
    02338
    02339   // operator >=
    02340   /**
    02341    *  @brief  Test if string doesn't precede string.
    02342    *  @param lhs  First string.
    02343    *  @param rhs  Second string.
    02344    *  @return  True if @a lhs doesn't precede @a rhs.  False otherwise.
    02345    */
    02346   template<typename _CharT, typename _Traits, typename _Alloc>
    02347     inline bool
    02348     operator>=(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
    02349            const basic_string<_CharT, _Traits, _Alloc>& __rhs)
    02350     { return __lhs.compare(__rhs) >= 0; }
    02351
    02352   /**
    02353    *  @brief  Test if string doesn't precede C string.
    02354    *  @param lhs  String.
    02355    *  @param rhs  C string.
    02356    *  @return  True if @a lhs doesn't precede @a rhs.  False otherwise.
    02357    */
    02358   template<typename _CharT, typename _Traits, typename _Alloc>
    02359     inline bool
    02360     operator>=(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
    02361            const _CharT* __rhs)
    02362     { return __lhs.compare(__rhs) >= 0; }
    02363
    02364   /**
    02365    *  @brief  Test if C string doesn't precede string.
    02366    *  @param lhs  C string.
    02367    *  @param rhs  String.
    02368    *  @return  True if @a lhs doesn't precede @a rhs.  False otherwise.
    02369    */
    02370   template<typename _CharT, typename _Traits, typename _Alloc>
    02371     inline bool
    02372     operator>=(const _CharT* __lhs,
    02373          const basic_string<_CharT, _Traits, _Alloc>& __rhs)
    02374     { return __rhs.compare(__lhs) <= 0; }
    02375
    02376   /**
    02377    *  @brief  Swap contents of two strings.
    02378    *  @param lhs  First string.
    02379    *  @param rhs  Second string.
    02380    *
    02381    *  Exchanges the contents of @a lhs and @a rhs in constant time.
    02382    */
    02383   template<typename _CharT, typename _Traits, typename _Alloc>
    02384     inline void
    02385     swap(basic_string<_CharT, _Traits, _Alloc>& __lhs,
    02386      basic_string<_CharT, _Traits, _Alloc>& __rhs)
    02387     { __lhs.swap(__rhs); }
    02388
    02389   /**
    02390    *  @brief  Read stream into a string.
    02391    *  @param is  Input stream.
    02392    *  @param str  Buffer to store into.
    02393    *  @return  Reference to the input stream.
    02394    *
    02395    *  Stores characters from @a is into @a str until whitespace is found, the
    02396    *  end of the stream is encountered, or str.max_size() is reached.  If
    02397    *  is.width() is non-zero, that is the limit on the number of characters
    02398    *  stored into @a str.  Any previous contents of @a str are erased.
    02399    */
    02400   template<typename _CharT, typename _Traits, typename _Alloc>
    02401     basic_istream<_CharT, _Traits>&
    02402     operator>>(basic_istream<_CharT, _Traits>& __is,
    02403            basic_string<_CharT, _Traits, _Alloc>& __str);
    02404
    02405   template<>
    02406     basic_istream<char>&
    02407     operator>>(basic_istream<char>& __is, basic_string<char>& __str);
    02408
    02409   /**
    02410    *  @brief  Write string to a stream.
    02411    *  @param os  Output stream.
    02412    *  @param str  String to write out.
    02413    *  @return  Reference to the output stream.
    02414    *
    02415    *  Output characters of @a str into os following the same rules as for
    02416    *  writing a C string.
    02417    */
    02418   template<typename _CharT, typename _Traits, typename _Alloc>
    02419     inline basic_ostream<_CharT, _Traits>&
    02420     operator<<(basic_ostream<_CharT, _Traits>& __os,
    02421            const basic_string<_CharT, _Traits, _Alloc>& __str)
    02422     {
    02423       // _GLIBCXX_RESOLVE_LIB_DEFECTS
    02424       // 586. string inserter not a formatted function
    02425       return __ostream_insert(__os, __str.data(), __str.size());
    02426     }
    02427
    02428   /**
    02429    *  @brief  Read a line from stream into a string.
    02430    *  @param is  Input stream.
    02431    *  @param str  Buffer to store into.
    02432    *  @param delim  Character marking end of line.
    02433    *  @return  Reference to the input stream.
    02434    *
    02435    *  Stores characters from @a is into @a str until @a delim is found, the
    02436    *  end of the stream is encountered, or str.max_size() is reached.  If
    02437    *  is.width() is non-zero, that is the limit on the number of characters
    02438    *  stored into @a str.  Any previous contents of @a str are erased.  If @a
    02439    *  delim was encountered, it is extracted but not stored into @a str.
    02440    */
    02441   template<typename _CharT, typename _Traits, typename _Alloc>
    02442     basic_istream<_CharT, _Traits>&
    02443     getline(basic_istream<_CharT, _Traits>& __is,
    02444         basic_string<_CharT, _Traits, _Alloc>& __str, _CharT __delim);
    02445
    02446   /**
    02447    *  @brief  Read a line from stream into a string.
    02448    *  @param is  Input stream.
    02449    *  @param str  Buffer to store into.
    02450    *  @return  Reference to the input stream.
    02451    *
    02452    *  Stores characters from is into @a str until '\n' is found, the end of
    02453    *  the stream is encountered, or str.max_size() is reached.  If is.width()
    02454    *  is non-zero, that is the limit on the number of characters stored into
    02455    *  @a str.  Any previous contents of @a str are erased.  If end of line was
    02456    *  encountered, it is extracted but not stored into @a str.
    02457    */
    02458   template<typename _CharT, typename _Traits, typename _Alloc>
    02459     inline basic_istream<_CharT, _Traits>&
    02460     getline(basic_istream<_CharT, _Traits>& __is,
    02461         basic_string<_CharT, _Traits, _Alloc>& __str)
    02462     { return getline(__is, __str, __is.widen('\n')); }
    02463
    02464   template<>
    02465     basic_istream<char>&
    02466     getline(basic_istream<char>& __in, basic_string<char>& __str,
    02467         char __delim);
    02468
    02469 #ifdef _GLIBCXX_USE_WCHAR_T
    02470   template<>
    02471     basic_istream<wchar_t>&
    02472     getline(basic_istream<wchar_t>& __in, basic_string<wchar_t>& __str,
    02473         wchar_t __delim);
    02474 #endif
    02475
    02476 _GLIBCXX_END_NAMESPACE
    02477
    02478 #endif /* _BASIC_STRING_H */