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