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