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 #ifdef __GXX_EXPERIMENTAL_CXX0X__
00855       /**
00856        *  Returns a read/write reference to the data at the first
00857        *  element of the %string.
00858        */
00859       reference
00860       front()
00861       { return operator[](0); }
00862 
00863       /**
00864        *  Returns a read-only (constant) reference to the data at the first
00865        *  element of the %string.
00866        */
00867       const_reference
00868       front() const
00869       { return operator[](0); }
00870 
00871       /**
00872        *  Returns a read/write reference to the data at the last
00873        *  element of the %string.
00874        */
00875       reference
00876       back()
00877       { return operator[](this->size() - 1); }
00878 
00879       /**
00880        *  Returns a read-only (constant) reference to the data at the
00881        *  last element of the %string.
00882        */
00883       const_reference
00884       back() const
00885       { return operator[](this->size() - 1); }
00886 #endif
00887 
00888       /**
00889        *  @brief  Provides access to the data contained in the %string.
00890        *  @param n The index of the character to access.
00891        *  @return  Read/write reference to the character.
00892        *  @throw  std::out_of_range  If @a n is an invalid index.
00893        *
00894        *  This function provides for safer data access.  The parameter is
00895        *  first checked that it is in the range of the string.  The function
00896        *  throws out_of_range if the check fails.  Success results in
00897        *  unsharing the string.
00898        */
00899       reference
00900       at(size_type __n)
00901       {
00902     if (__n >= size())
00903       __throw_out_of_range(__N("basic_string::at"));
00904     _M_leak();
00905     return _M_data()[__n];
00906       }
00907 
00908       // Modifiers:
00909       /**
00910        *  @brief  Append a string to this string.
00911        *  @param str  The string to append.
00912        *  @return  Reference to this string.
00913        */
00914       basic_string&
00915       operator+=(const basic_string& __str)
00916       { return this->append(__str); }
00917 
00918       /**
00919        *  @brief  Append a C string.
00920        *  @param s  The C string to append.
00921        *  @return  Reference to this string.
00922        */
00923       basic_string&
00924       operator+=(const _CharT* __s)
00925       { return this->append(__s); }
00926 
00927       /**
00928        *  @brief  Append a character.
00929        *  @param c  The character to append.
00930        *  @return  Reference to this string.
00931        */
00932       basic_string&
00933       operator+=(_CharT __c)
00934       { 
00935     this->push_back(__c);
00936     return *this;
00937       }
00938 
00939 #ifdef __GXX_EXPERIMENTAL_CXX0X__
00940       /**
00941        *  @brief  Append an initializer_list of characters.
00942        *  @param l  The initializer_list of characters to be appended.
00943        *  @return  Reference to this string.
00944        */
00945       basic_string&
00946       operator+=(initializer_list<_CharT> __l)
00947       { return this->append(__l.begin(), __l.size()); }
00948 #endif // __GXX_EXPERIMENTAL_CXX0X__
00949 
00950       /**
00951        *  @brief  Append a string to this string.
00952        *  @param str  The string to append.
00953        *  @return  Reference to this string.
00954        */
00955       basic_string&
00956       append(const basic_string& __str);
00957 
00958       /**
00959        *  @brief  Append a substring.
00960        *  @param str  The string to append.
00961        *  @param pos  Index of the first character of str to append.
00962        *  @param n  The number of characters to append.
00963        *  @return  Reference to this string.
00964        *  @throw  std::out_of_range if @a pos is not a valid index.
00965        *
00966        *  This function appends @a n characters from @a str starting at @a pos
00967        *  to this string.  If @a n is is larger than the number of available
00968        *  characters in @a str, the remainder of @a str is appended.
00969        */
00970       basic_string&
00971       append(const basic_string& __str, size_type __pos, size_type __n);
00972 
00973       /**
00974        *  @brief  Append a C substring.
00975        *  @param s  The C string to append.
00976        *  @param n  The number of characters to append.
00977        *  @return  Reference to this string.
00978        */
00979       basic_string&
00980       append(const _CharT* __s, size_type __n);
00981 
00982       /**
00983        *  @brief  Append a C string.
00984        *  @param s  The C string to append.
00985        *  @return  Reference to this string.
00986        */
00987       basic_string&
00988       append(const _CharT* __s)
00989       {
00990     __glibcxx_requires_string(__s);
00991     return this->append(__s, traits_type::length(__s));
00992       }
00993 
00994       /**
00995        *  @brief  Append multiple characters.
00996        *  @param n  The number of characters to append.
00997        *  @param c  The character to use.
00998        *  @return  Reference to this string.
00999        *
01000        *  Appends n copies of c to this string.
01001        */
01002       basic_string&
01003       append(size_type __n, _CharT __c);
01004 
01005 #ifdef __GXX_EXPERIMENTAL_CXX0X__
01006       /**
01007        *  @brief  Append an initializer_list of characters.
01008        *  @param l  The initializer_list of characters to append.
01009        *  @return  Reference to this string.
01010        */
01011       basic_string&
01012       append(initializer_list<_CharT> __l)
01013       { return this->append(__l.begin(), __l.size()); }
01014 #endif // __GXX_EXPERIMENTAL_CXX0X__
01015 
01016       /**
01017        *  @brief  Append a range of characters.
01018        *  @param first  Iterator referencing the first character to append.
01019        *  @param last  Iterator marking the end of the range.
01020        *  @return  Reference to this string.
01021        *
01022        *  Appends characters in the range [first,last) to this string.
01023        */
01024       template<class _InputIterator>
01025         basic_string&
01026         append(_InputIterator __first, _InputIterator __last)
01027         { return this->replace(_M_iend(), _M_iend(), __first, __last); }
01028 
01029       /**
01030        *  @brief  Append a single character.
01031        *  @param c  Character to append.
01032        */
01033       void
01034       push_back(_CharT __c)
01035       { 
01036     const size_type __len = 1 + this->size();
01037     if (__len > this->capacity() || _M_rep()->_M_is_shared())
01038       this->reserve(__len);
01039     traits_type::assign(_M_data()[this->size()], __c);
01040     _M_rep()->_M_set_length_and_sharable(__len);
01041       }
01042 
01043       /**
01044        *  @brief  Set value to contents of another string.
01045        *  @param  str  Source string to use.
01046        *  @return  Reference to this string.
01047        */
01048       basic_string&
01049       assign(const basic_string& __str);
01050 
01051 #ifdef __GXX_EXPERIMENTAL_CXX0X__
01052       /**
01053        *  @brief  Set value to contents of another string.
01054        *  @param  str  Source string to use.
01055        *  @return  Reference to this string.
01056        *
01057        *  This function sets this string to the exact contents of @a str.
01058        *  @a str is a valid, but unspecified string.
01059        */
01060       basic_string&
01061       assign(basic_string&& __str)
01062       {
01063     this->swap(__str);
01064     return *this;
01065       }
01066 #endif // __GXX_EXPERIMENTAL_CXX0X__
01067 
01068       /**
01069        *  @brief  Set value to a substring of a string.
01070        *  @param str  The string to use.
01071        *  @param pos  Index of the first character of str.
01072        *  @param n  Number of characters to use.
01073        *  @return  Reference to this string.
01074        *  @throw  std::out_of_range if @a pos is not a valid index.
01075        *
01076        *  This function sets this string to the substring of @a str consisting
01077        *  of @a n characters at @a pos.  If @a n is is larger than the number
01078        *  of available characters in @a str, the remainder of @a str is used.
01079        */
01080       basic_string&
01081       assign(const basic_string& __str, size_type __pos, size_type __n)
01082       { return this->assign(__str._M_data()
01083                 + __str._M_check(__pos, "basic_string::assign"),
01084                 __str._M_limit(__pos, __n)); }
01085 
01086       /**
01087        *  @brief  Set value to a C substring.
01088        *  @param s  The C string to use.
01089        *  @param n  Number of characters to use.
01090        *  @return  Reference to this string.
01091        *
01092        *  This function sets the value of this string to the first @a n
01093        *  characters of @a s.  If @a n is is larger than the number of
01094        *  available characters in @a s, the remainder of @a s is used.
01095        */
01096       basic_string&
01097       assign(const _CharT* __s, size_type __n);
01098 
01099       /**
01100        *  @brief  Set value to contents of a C string.
01101        *  @param s  The C string to use.
01102        *  @return  Reference to this string.
01103        *
01104        *  This function sets the value of this string to the value of @a s.
01105        *  The data is copied, so there is no dependence on @a s once the
01106        *  function returns.
01107        */
01108       basic_string&
01109       assign(const _CharT* __s)
01110       {
01111     __glibcxx_requires_string(__s);
01112     return this->assign(__s, traits_type::length(__s));
01113       }
01114 
01115       /**
01116        *  @brief  Set value to multiple characters.
01117        *  @param n  Length of the resulting string.
01118        *  @param c  The character to use.
01119        *  @return  Reference to this string.
01120        *
01121        *  This function sets the value of this string to @a n copies of
01122        *  character @a c.
01123        */
01124       basic_string&
01125       assign(size_type __n, _CharT __c)
01126       { return _M_replace_aux(size_type(0), this->size(), __n, __c); }
01127 
01128       /**
01129        *  @brief  Set value to a range of characters.
01130        *  @param first  Iterator referencing the first character to append.
01131        *  @param last  Iterator marking the end of the range.
01132        *  @return  Reference to this string.
01133        *
01134        *  Sets value of string to characters in the range [first,last).
01135       */
01136       template<class _InputIterator>
01137         basic_string&
01138         assign(_InputIterator __first, _InputIterator __last)
01139         { return this->replace(_M_ibegin(), _M_iend(), __first, __last); }
01140 
01141 #ifdef __GXX_EXPERIMENTAL_CXX0X__
01142       /**
01143        *  @brief  Set value to an initializer_list of characters.
01144        *  @param l  The initializer_list of characters to assign.
01145        *  @return  Reference to this string.
01146        */
01147       basic_string&
01148       assign(initializer_list<_CharT> __l)
01149       { return this->assign(__l.begin(), __l.size()); }
01150 #endif // __GXX_EXPERIMENTAL_CXX0X__
01151 
01152       /**
01153        *  @brief  Insert multiple characters.
01154        *  @param p  Iterator referencing location in string to insert at.
01155        *  @param n  Number of characters to insert
01156        *  @param c  The character to insert.
01157        *  @throw  std::length_error  If new length exceeds @c max_size().
01158        *
01159        *  Inserts @a n copies of character @a c starting at the position
01160        *  referenced by iterator @a p.  If adding characters causes the length
01161        *  to exceed max_size(), length_error is thrown.  The value of the
01162        *  string doesn't change if an error is thrown.
01163       */
01164       void
01165       insert(iterator __p, size_type __n, _CharT __c)
01166       { this->replace(__p, __p, __n, __c);  }
01167 
01168       /**
01169        *  @brief  Insert a range of characters.
01170        *  @param p  Iterator referencing location in string to insert at.
01171        *  @param beg  Start of range.
01172        *  @param end  End of range.
01173        *  @throw  std::length_error  If new length exceeds @c max_size().
01174        *
01175        *  Inserts characters in range [beg,end).  If adding characters causes
01176        *  the length to exceed max_size(), length_error is thrown.  The value
01177        *  of the string doesn't change if an error is thrown.
01178       */
01179       template<class _InputIterator>
01180         void
01181         insert(iterator __p, _InputIterator __beg, _InputIterator __end)
01182         { this->replace(__p, __p, __beg, __end); }
01183 
01184 #ifdef __GXX_EXPERIMENTAL_CXX0X__
01185       /**
01186        *  @brief  Insert an initializer_list of characters.
01187        *  @param p  Iterator referencing location in string to insert at.
01188        *  @param l  The initializer_list of characters to insert.
01189        *  @throw  std::length_error  If new length exceeds @c max_size().
01190        */
01191       void
01192       insert(iterator __p, initializer_list<_CharT> __l)
01193       {
01194     _GLIBCXX_DEBUG_PEDASSERT(__p >= _M_ibegin() && __p <= _M_iend());
01195     this->insert(__p - _M_ibegin(), __l.begin(), __l.size());
01196       }
01197 #endif // __GXX_EXPERIMENTAL_CXX0X__
01198 
01199       /**
01200        *  @brief  Insert value of a string.
01201        *  @param pos1  Iterator referencing location in string to insert at.
01202        *  @param str  The string to insert.
01203        *  @return  Reference to this string.
01204        *  @throw  std::length_error  If new length exceeds @c max_size().
01205        *
01206        *  Inserts value of @a str starting at @a pos1.  If adding characters
01207        *  causes the length to exceed max_size(), length_error is thrown.  The
01208        *  value of the string doesn't change if an error is thrown.
01209       */
01210       basic_string&
01211       insert(size_type __pos1, const basic_string& __str)
01212       { return this->insert(__pos1, __str, size_type(0), __str.size()); }
01213 
01214       /**
01215        *  @brief  Insert a substring.
01216        *  @param pos1  Iterator referencing location in string to insert at.
01217        *  @param str  The string to insert.
01218        *  @param pos2  Start of characters in str to insert.
01219        *  @param n  Number of characters to insert.
01220        *  @return  Reference to this string.
01221        *  @throw  std::length_error  If new length exceeds @c max_size().
01222        *  @throw  std::out_of_range  If @a pos1 > size() or
01223        *  @a pos2 > @a str.size().
01224        *
01225        *  Starting at @a pos1, insert @a n character of @a str beginning with
01226        *  @a pos2.  If adding characters causes the length to exceed
01227        *  max_size(), length_error is thrown.  If @a pos1 is beyond the end of
01228        *  this string or @a pos2 is beyond the end of @a str, out_of_range is
01229        *  thrown.  The value of the string doesn't change if an error is
01230        *  thrown.
01231       */
01232       basic_string&
01233       insert(size_type __pos1, const basic_string& __str,
01234          size_type __pos2, size_type __n)
01235       { return this->insert(__pos1, __str._M_data()
01236                 + __str._M_check(__pos2, "basic_string::insert"),
01237                 __str._M_limit(__pos2, __n)); }
01238 
01239       /**
01240        *  @brief  Insert a C substring.
01241        *  @param pos  Iterator referencing location in string to insert at.
01242        *  @param s  The C string to insert.
01243        *  @param n  The number of characters to insert.
01244        *  @return  Reference to this string.
01245        *  @throw  std::length_error  If new length exceeds @c max_size().
01246        *  @throw  std::out_of_range  If @a pos is beyond the end of this
01247        *  string.
01248        *
01249        *  Inserts the first @a n characters of @a s starting at @a pos.  If
01250        *  adding characters causes the length to exceed max_size(),
01251        *  length_error is thrown.  If @a pos is beyond end(), out_of_range is
01252        *  thrown.  The value of the string doesn't change if an error is
01253        *  thrown.
01254       */
01255       basic_string&
01256       insert(size_type __pos, const _CharT* __s, size_type __n);
01257 
01258       /**
01259        *  @brief  Insert a C string.
01260        *  @param pos  Iterator referencing location in string to insert at.
01261        *  @param s  The C string to insert.
01262        *  @return  Reference to this string.
01263        *  @throw  std::length_error  If new length exceeds @c max_size().
01264        *  @throw  std::out_of_range  If @a pos is beyond the end of this
01265        *  string.
01266        *
01267        *  Inserts the first @a n characters of @a s starting at @a pos.  If
01268        *  adding characters causes the length to exceed max_size(),
01269        *  length_error is thrown.  If @a pos is beyond end(), out_of_range is
01270        *  thrown.  The value of the string doesn't change if an error is
01271        *  thrown.
01272       */
01273       basic_string&
01274       insert(size_type __pos, const _CharT* __s)
01275       {
01276     __glibcxx_requires_string(__s);
01277     return this->insert(__pos, __s, traits_type::length(__s));
01278       }
01279 
01280       /**
01281        *  @brief  Insert multiple characters.
01282        *  @param pos  Index in string to insert at.
01283        *  @param n  Number of characters to insert
01284        *  @param c  The character to insert.
01285        *  @return  Reference to this string.
01286        *  @throw  std::length_error  If new length exceeds @c max_size().
01287        *  @throw  std::out_of_range  If @a pos is beyond the end of this
01288        *  string.
01289        *
01290        *  Inserts @a n copies of character @a c starting at index @a pos.  If
01291        *  adding characters causes the length to exceed max_size(),
01292        *  length_error is thrown.  If @a pos > length(), out_of_range is
01293        *  thrown.  The value of the string doesn't change if an error is
01294        *  thrown.
01295       */
01296       basic_string&
01297       insert(size_type __pos, size_type __n, _CharT __c)
01298       { return _M_replace_aux(_M_check(__pos, "basic_string::insert"),
01299                   size_type(0), __n, __c); }
01300 
01301       /**
01302        *  @brief  Insert one character.
01303        *  @param p  Iterator referencing position in string to insert at.
01304        *  @param c  The character to insert.
01305        *  @return  Iterator referencing newly inserted char.
01306        *  @throw  std::length_error  If new length exceeds @c max_size().
01307        *
01308        *  Inserts character @a c at position referenced by @a p.  If adding
01309        *  character causes the length to exceed max_size(), length_error is
01310        *  thrown.  If @a p is beyond end of string, out_of_range is thrown.
01311        *  The value of the string doesn't change if an error is thrown.
01312       */
01313       iterator
01314       insert(iterator __p, _CharT __c)
01315       {
01316     _GLIBCXX_DEBUG_PEDASSERT(__p >= _M_ibegin() && __p <= _M_iend());
01317     const size_type __pos = __p - _M_ibegin();
01318     _M_replace_aux(__pos, size_type(0), size_type(1), __c);
01319     _M_rep()->_M_set_leaked();
01320     return iterator(_M_data() + __pos);
01321       }
01322 
01323       /**
01324        *  @brief  Remove characters.
01325        *  @param pos  Index of first character to remove (default 0).
01326        *  @param n  Number of characters to remove (default remainder).
01327        *  @return  Reference to this string.
01328        *  @throw  std::out_of_range  If @a pos is beyond the end of this
01329        *  string.
01330        *
01331        *  Removes @a n characters from this string starting at @a pos.  The
01332        *  length of the string is reduced by @a n.  If there are < @a n
01333        *  characters to remove, the remainder of the string is truncated.  If
01334        *  @a p is beyond end of string, out_of_range is thrown.  The value of
01335        *  the string doesn't change if an error is thrown.
01336       */
01337       basic_string&
01338       erase(size_type __pos = 0, size_type __n = npos)
01339       { 
01340     _M_mutate(_M_check(__pos, "basic_string::erase"),
01341           _M_limit(__pos, __n), size_type(0));
01342     return *this;
01343       }
01344 
01345       /**
01346        *  @brief  Remove one character.
01347        *  @param position  Iterator referencing the character to remove.
01348        *  @return  iterator referencing same location after removal.
01349        *
01350        *  Removes the character at @a position from this string. The value
01351        *  of the string doesn't change if an error is thrown.
01352       */
01353       iterator
01354       erase(iterator __position)
01355       {
01356     _GLIBCXX_DEBUG_PEDASSERT(__position >= _M_ibegin()
01357                  && __position < _M_iend());
01358     const size_type __pos = __position - _M_ibegin();
01359     _M_mutate(__pos, size_type(1), size_type(0));
01360     _M_rep()->_M_set_leaked();
01361     return iterator(_M_data() + __pos);
01362       }
01363 
01364       /**
01365        *  @brief  Remove a range of characters.
01366        *  @param first  Iterator referencing the first character to remove.
01367        *  @param last  Iterator referencing the end of the range.
01368        *  @return  Iterator referencing location of first after removal.
01369        *
01370        *  Removes the characters in the range [first,last) from this string.
01371        *  The value of the string doesn't change if an error is thrown.
01372       */
01373       iterator
01374       erase(iterator __first, iterator __last);
01375  
01376       /**
01377        *  @brief  Replace characters with value from another string.
01378        *  @param pos  Index of first character to replace.
01379        *  @param n  Number of characters to be replaced.
01380        *  @param str  String to insert.
01381        *  @return  Reference to this string.
01382        *  @throw  std::out_of_range  If @a pos is beyond the end of this
01383        *  string.
01384        *  @throw  std::length_error  If new length exceeds @c max_size().
01385        *
01386        *  Removes the characters in the range [pos,pos+n) from this string.
01387        *  In place, the value of @a str is inserted.  If @a pos is beyond end
01388        *  of string, out_of_range is thrown.  If the length of the result
01389        *  exceeds max_size(), length_error is thrown.  The value of the string
01390        *  doesn't change if an error is thrown.
01391       */
01392       basic_string&
01393       replace(size_type __pos, size_type __n, const basic_string& __str)
01394       { return this->replace(__pos, __n, __str._M_data(), __str.size()); }
01395 
01396       /**
01397        *  @brief  Replace characters with value from another string.
01398        *  @param pos1  Index of first character to replace.
01399        *  @param n1  Number of characters to be replaced.
01400        *  @param str  String to insert.
01401        *  @param pos2  Index of first character of str to use.
01402        *  @param n2  Number of characters from str to use.
01403        *  @return  Reference to this string.
01404        *  @throw  std::out_of_range  If @a pos1 > size() or @a pos2 >
01405        *  str.size().
01406        *  @throw  std::length_error  If new length exceeds @c max_size().
01407        *
01408        *  Removes the characters in the range [pos1,pos1 + n) from this
01409        *  string.  In place, the value of @a str is inserted.  If @a pos is
01410        *  beyond end of string, out_of_range is thrown.  If the length of the
01411        *  result exceeds max_size(), length_error is thrown.  The value of the
01412        *  string doesn't change if an error is thrown.
01413       */
01414       basic_string&
01415       replace(size_type __pos1, size_type __n1, const basic_string& __str,
01416           size_type __pos2, size_type __n2)
01417       { return this->replace(__pos1, __n1, __str._M_data()
01418                  + __str._M_check(__pos2, "basic_string::replace"),
01419                  __str._M_limit(__pos2, __n2)); }
01420 
01421       /**
01422        *  @brief  Replace characters with value of a C substring.
01423        *  @param pos  Index of first character to replace.
01424        *  @param n1  Number of characters to be replaced.
01425        *  @param s  C string to insert.
01426        *  @param n2  Number of characters from @a s to use.
01427        *  @return  Reference to this string.
01428        *  @throw  std::out_of_range  If @a pos1 > size().
01429        *  @throw  std::length_error  If new length exceeds @c max_size().
01430        *
01431        *  Removes the characters in the range [pos,pos + n1) from this string.
01432        *  In place, the first @a n2 characters of @a s are inserted, or all
01433        *  of @a s if @a n2 is too large.  If @a pos is beyond end of string,
01434        *  out_of_range is thrown.  If the length of result exceeds max_size(),
01435        *  length_error is thrown.  The value of the string doesn't change if
01436        *  an error is thrown.
01437       */
01438       basic_string&
01439       replace(size_type __pos, size_type __n1, const _CharT* __s,
01440           size_type __n2);
01441 
01442       /**
01443        *  @brief  Replace characters with value of a C string.
01444        *  @param pos  Index of first character to replace.
01445        *  @param n1  Number of characters to be replaced.
01446        *  @param s  C string to insert.
01447        *  @return  Reference to this string.
01448        *  @throw  std::out_of_range  If @a pos > size().
01449        *  @throw  std::length_error  If new length exceeds @c max_size().
01450        *
01451        *  Removes the characters in the range [pos,pos + n1) from this string.
01452        *  In place, the characters of @a s are inserted.  If @a pos is beyond
01453        *  end of string, out_of_range is thrown.  If the length of result
01454        *  exceeds max_size(), length_error is thrown.  The value of the string
01455        *  doesn't change if an error is thrown.
01456       */
01457       basic_string&
01458       replace(size_type __pos, size_type __n1, const _CharT* __s)
01459       {
01460     __glibcxx_requires_string(__s);
01461     return this->replace(__pos, __n1, __s, traits_type::length(__s));
01462       }
01463 
01464       /**
01465        *  @brief  Replace characters with multiple characters.
01466        *  @param pos  Index of first character to replace.
01467        *  @param n1  Number of characters to be replaced.
01468        *  @param n2  Number of characters to insert.
01469        *  @param c  Character to insert.
01470        *  @return  Reference to this string.
01471        *  @throw  std::out_of_range  If @a pos > size().
01472        *  @throw  std::length_error  If new length exceeds @c max_size().
01473        *
01474        *  Removes the characters in the range [pos,pos + n1) from this string.
01475        *  In place, @a n2 copies of @a c are inserted.  If @a pos is beyond
01476        *  end of string, out_of_range is thrown.  If the length of result
01477        *  exceeds max_size(), length_error is thrown.  The value of the string
01478        *  doesn't change if an error is thrown.
01479       */
01480       basic_string&
01481       replace(size_type __pos, size_type __n1, size_type __n2, _CharT __c)
01482       { return _M_replace_aux(_M_check(__pos, "basic_string::replace"),
01483                   _M_limit(__pos, __n1), __n2, __c); }
01484 
01485       /**
01486        *  @brief  Replace range of characters with string.
01487        *  @param i1  Iterator referencing start of range to replace.
01488        *  @param i2  Iterator referencing end of range to replace.
01489        *  @param str  String value to insert.
01490        *  @return  Reference to this string.
01491        *  @throw  std::length_error  If new length exceeds @c max_size().
01492        *
01493        *  Removes the characters in the range [i1,i2).  In place, the value of
01494        *  @a str is inserted.  If the length of result exceeds max_size(),
01495        *  length_error is thrown.  The value of the string doesn't change if
01496        *  an error is thrown.
01497       */
01498       basic_string&
01499       replace(iterator __i1, iterator __i2, const basic_string& __str)
01500       { return this->replace(__i1, __i2, __str._M_data(), __str.size()); }
01501 
01502       /**
01503        *  @brief  Replace range of characters with C substring.
01504        *  @param i1  Iterator referencing start of range to replace.
01505        *  @param i2  Iterator referencing end of range to replace.
01506        *  @param s  C string value to insert.
01507        *  @param n  Number of characters from s to insert.
01508        *  @return  Reference to this string.
01509        *  @throw  std::length_error  If new length exceeds @c max_size().
01510        *
01511        *  Removes the characters in the range [i1,i2).  In place, the first @a
01512        *  n characters of @a s are inserted.  If the length of result exceeds
01513        *  max_size(), length_error is thrown.  The value of the string doesn't
01514        *  change if an error is thrown.
01515       */
01516       basic_string&
01517       replace(iterator __i1, iterator __i2, const _CharT* __s, size_type __n)
01518       {
01519     _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1 && __i1 <= __i2
01520                  && __i2 <= _M_iend());
01521     return this->replace(__i1 - _M_ibegin(), __i2 - __i1, __s, __n);
01522       }
01523 
01524       /**
01525        *  @brief  Replace range of characters with C string.
01526        *  @param i1  Iterator referencing start of range to replace.
01527        *  @param i2  Iterator referencing end of range to replace.
01528        *  @param s  C string value to insert.
01529        *  @return  Reference to this string.
01530        *  @throw  std::length_error  If new length exceeds @c max_size().
01531        *
01532        *  Removes the characters in the range [i1,i2).  In place, the
01533        *  characters of @a s are inserted.  If the length of result exceeds
01534        *  max_size(), length_error is thrown.  The value of the string doesn't
01535        *  change if an error is thrown.
01536       */
01537       basic_string&
01538       replace(iterator __i1, iterator __i2, const _CharT* __s)
01539       {
01540     __glibcxx_requires_string(__s);
01541     return this->replace(__i1, __i2, __s, traits_type::length(__s));
01542       }
01543 
01544       /**
01545        *  @brief  Replace range of characters with multiple characters
01546        *  @param i1  Iterator referencing start of range to replace.
01547        *  @param i2  Iterator referencing end of range to replace.
01548        *  @param n  Number of characters to insert.
01549        *  @param c  Character to insert.
01550        *  @return  Reference to this string.
01551        *  @throw  std::length_error  If new length exceeds @c max_size().
01552        *
01553        *  Removes the characters in the range [i1,i2).  In place, @a n copies
01554        *  of @a c are inserted.  If the length of result exceeds max_size(),
01555        *  length_error is thrown.  The value of the string doesn't change if
01556        *  an error is thrown.
01557       */
01558       basic_string&
01559       replace(iterator __i1, iterator __i2, size_type __n, _CharT __c)
01560       {
01561     _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1 && __i1 <= __i2
01562                  && __i2 <= _M_iend());
01563     return _M_replace_aux(__i1 - _M_ibegin(), __i2 - __i1, __n, __c);
01564       }
01565 
01566       /**
01567        *  @brief  Replace range of characters with range.
01568        *  @param i1  Iterator referencing start of range to replace.
01569        *  @param i2  Iterator referencing end of range to replace.
01570        *  @param k1  Iterator referencing start of range to insert.
01571        *  @param k2  Iterator referencing end of range to insert.
01572        *  @return  Reference to this string.
01573        *  @throw  std::length_error  If new length exceeds @c max_size().
01574        *
01575        *  Removes the characters in the range [i1,i2).  In place, characters
01576        *  in the range [k1,k2) are inserted.  If the length of result exceeds
01577        *  max_size(), length_error is thrown.  The value of the string doesn't
01578        *  change if an error is thrown.
01579       */
01580       template<class _InputIterator>
01581         basic_string&
01582         replace(iterator __i1, iterator __i2,
01583         _InputIterator __k1, _InputIterator __k2)
01584         {
01585       _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1 && __i1 <= __i2
01586                    && __i2 <= _M_iend());
01587       __glibcxx_requires_valid_range(__k1, __k2);
01588       typedef typename std::__is_integer<_InputIterator>::__type _Integral;
01589       return _M_replace_dispatch(__i1, __i2, __k1, __k2, _Integral());
01590     }
01591 
01592       // Specializations for the common case of pointer and iterator:
01593       // useful to avoid the overhead of temporary buffering in _M_replace.
01594       basic_string&
01595       replace(iterator __i1, iterator __i2, _CharT* __k1, _CharT* __k2)
01596       {
01597     _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1 && __i1 <= __i2
01598                  && __i2 <= _M_iend());
01599     __glibcxx_requires_valid_range(__k1, __k2);
01600     return this->replace(__i1 - _M_ibegin(), __i2 - __i1,
01601                  __k1, __k2 - __k1);
01602       }
01603 
01604       basic_string&
01605       replace(iterator __i1, iterator __i2,
01606           const _CharT* __k1, const _CharT* __k2)
01607       {
01608     _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1 && __i1 <= __i2
01609                  && __i2 <= _M_iend());
01610     __glibcxx_requires_valid_range(__k1, __k2);
01611     return this->replace(__i1 - _M_ibegin(), __i2 - __i1,
01612                  __k1, __k2 - __k1);
01613       }
01614 
01615       basic_string&
01616       replace(iterator __i1, iterator __i2, iterator __k1, iterator __k2)
01617       {
01618     _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1 && __i1 <= __i2
01619                  && __i2 <= _M_iend());
01620     __glibcxx_requires_valid_range(__k1, __k2);
01621     return this->replace(__i1 - _M_ibegin(), __i2 - __i1,
01622                  __k1.base(), __k2 - __k1);
01623       }
01624 
01625       basic_string&
01626       replace(iterator __i1, iterator __i2,
01627           const_iterator __k1, const_iterator __k2)
01628       {
01629     _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1 && __i1 <= __i2
01630                  && __i2 <= _M_iend());
01631     __glibcxx_requires_valid_range(__k1, __k2);
01632     return this->replace(__i1 - _M_ibegin(), __i2 - __i1,
01633                  __k1.base(), __k2 - __k1);
01634       }
01635       
01636 #ifdef __GXX_EXPERIMENTAL_CXX0X__
01637       /**
01638        *  @brief  Replace range of characters with initializer_list.
01639        *  @param i1  Iterator referencing start of range to replace.
01640        *  @param i2  Iterator referencing end of range to replace.
01641        *  @param l  The initializer_list of characters to insert.
01642        *  @return  Reference to this string.
01643        *  @throw  std::length_error  If new length exceeds @c max_size().
01644        *
01645        *  Removes the characters in the range [i1,i2).  In place, characters
01646        *  in the range [k1,k2) are inserted.  If the length of result exceeds
01647        *  max_size(), length_error is thrown.  The value of the string doesn't
01648        *  change if an error is thrown.
01649       */
01650       basic_string& replace(iterator __i1, iterator __i2,
01651                 initializer_list<_CharT> __l)
01652       { return this->replace(__i1, __i2, __l.begin(), __l.end()); }
01653 #endif // __GXX_EXPERIMENTAL_CXX0X__
01654 
01655     private:
01656       template<class _Integer>
01657     basic_string&
01658     _M_replace_dispatch(iterator __i1, iterator __i2, _Integer __n,
01659                 _Integer __val, __true_type)
01660         { return _M_replace_aux(__i1 - _M_ibegin(), __i2 - __i1, __n, __val); }
01661 
01662       template<class _InputIterator>
01663     basic_string&
01664     _M_replace_dispatch(iterator __i1, iterator __i2, _InputIterator __k1,
01665                 _InputIterator __k2, __false_type);
01666 
01667       basic_string&
01668       _M_replace_aux(size_type __pos1, size_type __n1, size_type __n2,
01669              _CharT __c);
01670 
01671       basic_string&
01672       _M_replace_safe(size_type __pos1, size_type __n1, const _CharT* __s,
01673               size_type __n2);
01674 
01675       // _S_construct_aux is used to implement the 21.3.1 para 15 which
01676       // requires special behaviour if _InIter is an integral type
01677       template<class _InIterator>
01678         static _CharT*
01679         _S_construct_aux(_InIterator __beg, _InIterator __end,
01680              const _Alloc& __a, __false_type)
01681     {
01682           typedef typename iterator_traits<_InIterator>::iterator_category _Tag;
01683           return _S_construct(__beg, __end, __a, _Tag());
01684     }
01685 
01686       // _GLIBCXX_RESOLVE_LIB_DEFECTS
01687       // 438. Ambiguity in the "do the right thing" clause
01688       template<class _Integer>
01689         static _CharT*
01690         _S_construct_aux(_Integer __beg, _Integer __end,
01691              const _Alloc& __a, __true_type)
01692         { return _S_construct_aux_2(static_cast<size_type>(__beg),
01693                     __end, __a); }
01694 
01695       static _CharT*
01696       _S_construct_aux_2(size_type __req, _CharT __c, const _Alloc& __a)
01697       { return _S_construct(__req, __c, __a); }
01698 
01699       template<class _InIterator>
01700         static _CharT*
01701         _S_construct(_InIterator __beg, _InIterator __end, const _Alloc& __a)
01702     {
01703       typedef typename std::__is_integer<_InIterator>::__type _Integral;
01704       return _S_construct_aux(__beg, __end, __a, _Integral());
01705         }
01706 
01707       // For Input Iterators, used in istreambuf_iterators, etc.
01708       template<class _InIterator>
01709         static _CharT*
01710          _S_construct(_InIterator __beg, _InIterator __end, const _Alloc& __a,
01711               input_iterator_tag);
01712 
01713       // For forward_iterators up to random_access_iterators, used for
01714       // string::iterator, _CharT*, etc.
01715       template<class _FwdIterator>
01716         static _CharT*
01717         _S_construct(_FwdIterator __beg, _FwdIterator __end, const _Alloc& __a,
01718              forward_iterator_tag);
01719 
01720       static _CharT*
01721       _S_construct(size_type __req, _CharT __c, const _Alloc& __a);
01722 
01723     public:
01724 
01725       /**
01726        *  @brief  Copy substring into C string.
01727        *  @param s  C string to copy value into.
01728        *  @param n  Number of characters to copy.
01729        *  @param pos  Index of first character to copy.
01730        *  @return  Number of characters actually copied
01731        *  @throw  std::out_of_range  If pos > size().
01732        *
01733        *  Copies up to @a n characters starting at @a pos into the C string @a
01734        *  s.  If @a pos is %greater than size(), out_of_range is thrown.
01735       */
01736       size_type
01737       copy(_CharT* __s, size_type __n, size_type __pos = 0) const;
01738 
01739       /**
01740        *  @brief  Swap contents with another string.
01741        *  @param s  String to swap with.
01742        *
01743        *  Exchanges the contents of this string with that of @a s in constant
01744        *  time.
01745       */
01746       void
01747       swap(basic_string& __s);
01748 
01749       // String operations:
01750       /**
01751        *  @brief  Return const pointer to null-terminated contents.
01752        *
01753        *  This is a handle to internal data.  Do not modify or dire things may
01754        *  happen.
01755       */
01756       const _CharT*
01757       c_str() const
01758       { return _M_data(); }
01759 
01760       /**
01761        *  @brief  Return const pointer to contents.
01762        *
01763        *  This is a handle to internal data.  Do not modify or dire things may
01764        *  happen.
01765       */
01766       const _CharT*
01767       data() const
01768       { return _M_data(); }
01769 
01770       /**
01771        *  @brief  Return copy of allocator used to construct this string.
01772       */
01773       allocator_type
01774       get_allocator() const
01775       { return _M_dataplus; }
01776 
01777       /**
01778        *  @brief  Find position of a C substring.
01779        *  @param s  C string to locate.
01780        *  @param pos  Index of character to search from.
01781        *  @param n  Number of characters from @a s to search for.
01782        *  @return  Index of start of first occurrence.
01783        *
01784        *  Starting from @a pos, searches forward for the first @a n characters
01785        *  in @a s within this string.  If found, returns the index where it
01786        *  begins.  If not found, returns npos.
01787       */
01788       size_type
01789       find(const _CharT* __s, size_type __pos, size_type __n) const;
01790 
01791       /**
01792        *  @brief  Find position of a string.
01793        *  @param str  String to locate.
01794        *  @param pos  Index of character to search from (default 0).
01795        *  @return  Index of start of first occurrence.
01796        *
01797        *  Starting from @a pos, searches forward for value of @a str within
01798        *  this string.  If found, returns the index where it begins.  If not
01799        *  found, returns npos.
01800       */
01801       size_type
01802       find(const basic_string& __str, size_type __pos = 0) const
01803       { return this->find(__str.data(), __pos, __str.size()); }
01804 
01805       /**
01806        *  @brief  Find position of a C string.
01807        *  @param s  C string to locate.
01808        *  @param pos  Index of character to search from (default 0).
01809        *  @return  Index of start of first occurrence.
01810        *
01811        *  Starting from @a pos, searches forward for the value of @a s within
01812        *  this string.  If found, returns the index where it begins.  If not
01813        *  found, returns npos.
01814       */
01815       size_type
01816       find(const _CharT* __s, size_type __pos = 0) const
01817       {
01818     __glibcxx_requires_string(__s);
01819     return this->find(__s, __pos, traits_type::length(__s));
01820       }
01821 
01822       /**
01823        *  @brief  Find position of a character.
01824        *  @param c  Character to locate.
01825        *  @param pos  Index of character to search from (default 0).
01826        *  @return  Index of first occurrence.
01827        *
01828        *  Starting from @a pos, searches forward for @a c within this string.
01829        *  If found, returns the index where it was found.  If not found,
01830        *  returns npos.
01831       */
01832       size_type
01833       find(_CharT __c, size_type __pos = 0) const;
01834 
01835       /**
01836        *  @brief  Find last position of a string.
01837        *  @param str  String to locate.
01838        *  @param pos  Index of character to search back from (default end).
01839        *  @return  Index of start of last occurrence.
01840        *
01841        *  Starting from @a pos, searches backward for value of @a str within
01842        *  this string.  If found, returns the index where it begins.  If not
01843        *  found, returns npos.
01844       */
01845       size_type
01846       rfind(const basic_string& __str, size_type __pos = npos) const
01847       { return this->rfind(__str.data(), __pos, __str.size()); }
01848 
01849       /**
01850        *  @brief  Find last position of a C substring.
01851        *  @param s  C string to locate.
01852        *  @param pos  Index of character to search back from.
01853        *  @param n  Number of characters from s to search for.
01854        *  @return  Index of start of last occurrence.
01855        *
01856        *  Starting from @a pos, searches backward for the first @a n
01857        *  characters in @a s within this string.  If found, returns the index
01858        *  where it begins.  If not found, returns npos.
01859       */
01860       size_type
01861       rfind(const _CharT* __s, size_type __pos, size_type __n) const;
01862 
01863       /**
01864        *  @brief  Find last position of a C string.
01865        *  @param s  C string to locate.
01866        *  @param pos  Index of character to start search at (default end).
01867        *  @return  Index of start of  last occurrence.
01868        *
01869        *  Starting from @a pos, searches backward for the value of @a s within
01870        *  this string.  If found, returns the index where it begins.  If not
01871        *  found, returns npos.
01872       */
01873       size_type
01874       rfind(const _CharT* __s, size_type __pos = npos) const
01875       {
01876     __glibcxx_requires_string(__s);
01877     return this->rfind(__s, __pos, traits_type::length(__s));
01878       }
01879 
01880       /**
01881        *  @brief  Find last position of a character.
01882        *  @param c  Character to locate.
01883        *  @param pos  Index of character to search back from (default end).
01884        *  @return  Index of last occurrence.
01885        *
01886        *  Starting from @a pos, searches backward for @a c within this string.
01887        *  If found, returns the index where it was found.  If not found,
01888        *  returns npos.
01889       */
01890       size_type
01891       rfind(_CharT __c, size_type __pos = npos) const;
01892 
01893       /**
01894        *  @brief  Find position of a character of string.
01895        *  @param str  String containing characters to locate.
01896        *  @param pos  Index of character to search from (default 0).
01897        *  @return  Index of first occurrence.
01898        *
01899        *  Starting from @a pos, searches forward for one of the characters of
01900        *  @a str within this string.  If found, returns the index where it was
01901        *  found.  If not found, returns npos.
01902       */
01903       size_type
01904       find_first_of(const basic_string& __str, size_type __pos = 0) const
01905       { return this->find_first_of(__str.data(), __pos, __str.size()); }
01906 
01907       /**
01908        *  @brief  Find position of a character of C substring.
01909        *  @param s  String containing characters to locate.
01910        *  @param pos  Index of character to search from.
01911        *  @param n  Number of characters from s to search for.
01912        *  @return  Index of first occurrence.
01913        *
01914        *  Starting from @a pos, searches forward for one of the first @a n
01915        *  characters of @a s within this string.  If found, returns the index
01916        *  where it was found.  If not found, returns npos.
01917       */
01918       size_type
01919       find_first_of(const _CharT* __s, size_type __pos, size_type __n) const;
01920 
01921       /**
01922        *  @brief  Find position of a character of C string.
01923        *  @param s  String containing characters to locate.
01924        *  @param pos  Index of character to search from (default 0).
01925        *  @return  Index of first occurrence.
01926        *
01927        *  Starting from @a pos, searches forward for one of the characters of
01928        *  @a s within this string.  If found, returns the index where it was
01929        *  found.  If not found, returns npos.
01930       */
01931       size_type
01932       find_first_of(const _CharT* __s, size_type __pos = 0) const
01933       {
01934     __glibcxx_requires_string(__s);
01935     return this->find_first_of(__s, __pos, traits_type::length(__s));
01936       }
01937 
01938       /**
01939        *  @brief  Find position of a character.
01940        *  @param c  Character to locate.
01941        *  @param pos  Index of character to search from (default 0).
01942        *  @return  Index of first occurrence.
01943        *
01944        *  Starting from @a pos, searches forward for the character @a c within
01945        *  this string.  If found, returns the index where it was found.  If
01946        *  not found, returns npos.
01947        *
01948        *  Note: equivalent to find(c, pos).
01949       */
01950       size_type
01951       find_first_of(_CharT __c, size_type __pos = 0) const
01952       { return this->find(__c, __pos); }
01953 
01954       /**
01955        *  @brief  Find last position of a character of string.
01956        *  @param str  String containing characters to locate.
01957        *  @param pos  Index of character to search back from (default end).
01958        *  @return  Index of last occurrence.
01959        *
01960        *  Starting from @a pos, searches backward for one of the characters of
01961        *  @a str within this string.  If found, returns the index where it was
01962        *  found.  If not found, returns npos.
01963       */
01964       size_type
01965       find_last_of(const basic_string& __str, size_type __pos = npos) const
01966       { return this->find_last_of(__str.data(), __pos, __str.size()); }
01967 
01968       /**
01969        *  @brief  Find last position of a character of C substring.
01970        *  @param s  C string containing characters to locate.
01971        *  @param pos  Index of character to search back from.
01972        *  @param n  Number of characters from s to search for.
01973        *  @return  Index of last occurrence.
01974        *
01975        *  Starting from @a pos, searches backward for one of the first @a n
01976        *  characters of @a s within this string.  If found, returns the index
01977        *  where it was found.  If not found, returns npos.
01978       */
01979       size_type
01980       find_last_of(const _CharT* __s, size_type __pos, size_type __n) const;
01981 
01982       /**
01983        *  @brief  Find last position of a character of C string.
01984        *  @param s  C string containing characters to locate.
01985        *  @param pos  Index of character to search back from (default end).
01986        *  @return  Index of last occurrence.
01987        *
01988        *  Starting from @a pos, searches backward for one of the characters of
01989        *  @a s within this string.  If found, returns the index where it was
01990        *  found.  If not found, returns npos.
01991       */
01992       size_type
01993       find_last_of(const _CharT* __s, size_type __pos = npos) const
01994       {
01995     __glibcxx_requires_string(__s);
01996     return this->find_last_of(__s, __pos, traits_type::length(__s));
01997       }
01998 
01999       /**
02000        *  @brief  Find last position of a character.
02001        *  @param c  Character to locate.
02002        *  @param pos  Index of character to search back from (default end).
02003        *  @return  Index of last occurrence.
02004        *
02005        *  Starting from @a pos, searches backward for @a c within this string.
02006        *  If found, returns the index where it was found.  If not found,
02007        *  returns npos.
02008        *
02009        *  Note: equivalent to rfind(c, pos).
02010       */
02011       size_type
02012       find_last_of(_CharT __c, size_type __pos = npos) const
02013       { return this->rfind(__c, __pos); }
02014 
02015       /**
02016        *  @brief  Find position of a character not in string.
02017        *  @param str  String containing characters to avoid.
02018        *  @param pos  Index of character to search from (default 0).
02019        *  @return  Index of first occurrence.
02020        *
02021        *  Starting from @a pos, searches forward for a character not contained
02022        *  in @a str within this string.  If found, returns the index where it
02023        *  was found.  If not found, returns npos.
02024       */
02025       size_type
02026       find_first_not_of(const basic_string& __str, size_type __pos = 0) const
02027       { return this->find_first_not_of(__str.data(), __pos, __str.size()); }
02028 
02029       /**
02030        *  @brief  Find position of a character not in C substring.
02031        *  @param s  C string containing characters to avoid.
02032        *  @param pos  Index of character to search from.
02033        *  @param n  Number of characters from s to consider.
02034        *  @return  Index of first occurrence.
02035        *
02036        *  Starting from @a pos, searches forward for a character not contained
02037        *  in the first @a n characters of @a s within this string.  If found,
02038        *  returns the index where it was found.  If not found, returns npos.
02039       */
02040       size_type
02041       find_first_not_of(const _CharT* __s, size_type __pos,
02042             size_type __n) const;
02043 
02044       /**
02045        *  @brief  Find position of a character not in C string.
02046        *  @param s  C string containing characters to avoid.
02047        *  @param pos  Index of character to search from (default 0).
02048        *  @return  Index of first occurrence.
02049        *
02050        *  Starting from @a pos, searches forward for a character not contained
02051        *  in @a s within this string.  If found, returns the index where it
02052        *  was found.  If not found, returns npos.
02053       */
02054       size_type
02055       find_first_not_of(const _CharT* __s, size_type __pos = 0) const
02056       {
02057     __glibcxx_requires_string(__s);
02058     return this->find_first_not_of(__s, __pos, traits_type::length(__s));
02059       }
02060 
02061       /**
02062        *  @brief  Find position of a different character.
02063        *  @param c  Character to avoid.
02064        *  @param pos  Index of character to search from (default 0).
02065        *  @return  Index of first occurrence.
02066        *
02067        *  Starting from @a pos, searches forward for a character other than @a c
02068        *  within this string.  If found, returns the index where it was found.
02069        *  If not found, returns npos.
02070       */
02071       size_type
02072       find_first_not_of(_CharT __c, size_type __pos = 0) const;
02073 
02074       /**
02075        *  @brief  Find last position of a character not in string.
02076        *  @param str  String containing characters to avoid.
02077        *  @param pos  Index of character to search back from (default end).
02078        *  @return  Index of last occurrence.
02079        *
02080        *  Starting from @a pos, searches backward for a character not
02081        *  contained in @a str within this string.  If found, returns the index
02082        *  where it was found.  If not found, returns npos.
02083       */
02084       size_type
02085       find_last_not_of(const basic_string& __str, size_type __pos = npos) const
02086       { return this->find_last_not_of(__str.data(), __pos, __str.size()); }
02087 
02088       /**
02089        *  @brief  Find last position of a character not in C substring.
02090        *  @param s  C string containing characters to avoid.
02091        *  @param pos  Index of character to search back from.
02092        *  @param n  Number of characters from s to consider.
02093        *  @return  Index of last occurrence.
02094        *
02095        *  Starting from @a pos, searches backward for a character not
02096        *  contained in the first @a n characters of @a s within this string.
02097        *  If found, returns the index where it was found.  If not found,
02098        *  returns npos.
02099       */
02100       size_type
02101       find_last_not_of(const _CharT* __s, size_type __pos,
02102                size_type __n) const;
02103       /**
02104        *  @brief  Find last position of a character not in C string.
02105        *  @param s  C string containing characters to avoid.
02106        *  @param pos  Index of character to search back from (default end).
02107        *  @return  Index of last occurrence.
02108        *
02109        *  Starting from @a pos, searches backward for a character not
02110        *  contained in @a s within this string.  If found, returns the index
02111        *  where it was found.  If not found, returns npos.
02112       */
02113       size_type
02114       find_last_not_of(const _CharT* __s, size_type __pos = npos) const
02115       {
02116     __glibcxx_requires_string(__s);
02117     return this->find_last_not_of(__s, __pos, traits_type::length(__s));
02118       }
02119 
02120       /**
02121        *  @brief  Find last position of a different character.
02122        *  @param c  Character to avoid.
02123        *  @param pos  Index of character to search back from (default end).
02124        *  @return  Index of last occurrence.
02125        *
02126        *  Starting from @a pos, searches backward for a character other than
02127        *  @a c within this string.  If found, returns the index where it was
02128        *  found.  If not found, returns npos.
02129       */
02130       size_type
02131       find_last_not_of(_CharT __c, size_type __pos = npos) const;
02132 
02133       /**
02134        *  @brief  Get a substring.
02135        *  @param pos  Index of first character (default 0).
02136        *  @param n  Number of characters in substring (default remainder).
02137        *  @return  The new string.
02138        *  @throw  std::out_of_range  If pos > size().
02139        *
02140        *  Construct and return a new string using the @a n characters starting
02141        *  at @a pos.  If the string is too short, use the remainder of the
02142        *  characters.  If @a pos is beyond the end of the string, out_of_range
02143        *  is thrown.
02144       */
02145       basic_string
02146       substr(size_type __pos = 0, size_type __n = npos) const
02147       { return basic_string(*this,
02148                 _M_check(__pos, "basic_string::substr"), __n); }
02149 
02150       /**
02151        *  @brief  Compare to a string.
02152        *  @param str  String to compare against.
02153        *  @return  Integer < 0, 0, or > 0.
02154        *
02155        *  Returns an integer < 0 if this string is ordered before @a str, 0 if
02156        *  their values are equivalent, or > 0 if this string is ordered after
02157        *  @a str.  Determines the effective length rlen of the strings to
02158        *  compare as the smallest of size() and str.size().  The function
02159        *  then compares the two strings by calling traits::compare(data(),
02160        *  str.data(),rlen).  If the result of the comparison is nonzero returns
02161        *  it, otherwise the shorter one is ordered first.
02162       */
02163       int
02164       compare(const basic_string& __str) const
02165       {
02166     const size_type __size = this->size();
02167     const size_type __osize = __str.size();
02168     const size_type __len = std::min(__size, __osize);
02169 
02170     int __r = traits_type::compare(_M_data(), __str.data(), __len);
02171     if (!__r)
02172       __r = _S_compare(__size, __osize);
02173     return __r;
02174       }
02175 
02176       /**
02177        *  @brief  Compare substring to a string.
02178        *  @param pos  Index of first character of substring.
02179        *  @param n  Number of characters in substring.
02180        *  @param str  String to compare against.
02181        *  @return  Integer < 0, 0, or > 0.
02182        *
02183        *  Form the substring of this string from the @a n characters starting
02184        *  at @a pos.  Returns an integer < 0 if the substring is ordered
02185        *  before @a str, 0 if their values are equivalent, or > 0 if the
02186        *  substring is ordered after @a str.  Determines the effective length
02187        *  rlen of the strings to compare as the smallest of the length of the
02188        *  substring and @a str.size().  The function then compares the two
02189        *  strings by calling traits::compare(substring.data(),str.data(),rlen).
02190        *  If the result of the comparison is nonzero returns it, otherwise the
02191        *  shorter one is ordered first.
02192       */
02193       int
02194       compare(size_type __pos, size_type __n, const basic_string& __str) const;
02195 
02196       /**
02197        *  @brief  Compare substring to a substring.
02198        *  @param pos1  Index of first character of substring.
02199        *  @param n1  Number of characters in substring.
02200        *  @param str  String to compare against.
02201        *  @param pos2  Index of first character of substring of str.
02202        *  @param n2  Number of characters in substring of str.
02203        *  @return  Integer < 0, 0, or > 0.
02204        *
02205        *  Form the substring of this string from the @a n1 characters starting
02206        *  at @a pos1.  Form the substring of @a str from the @a n2 characters
02207        *  starting at @a pos2.  Returns an integer < 0 if this substring is
02208        *  ordered before the substring of @a str, 0 if their values are
02209        *  equivalent, or > 0 if this substring is ordered after the substring
02210        *  of @a str.  Determines the effective length rlen of the strings
02211        *  to compare as the smallest of the lengths of the substrings.  The
02212        *  function then compares the two strings by calling
02213        *  traits::compare(substring.data(),str.substr(pos2,n2).data(),rlen).
02214        *  If the result of the comparison is nonzero returns it, otherwise the
02215        *  shorter one is ordered first.
02216       */
02217       int
02218       compare(size_type __pos1, size_type __n1, const basic_string& __str,
02219           size_type __pos2, size_type __n2) const;
02220 
02221       /**
02222        *  @brief  Compare to a C string.
02223        *  @param s  C string to compare against.
02224        *  @return  Integer < 0, 0, or > 0.
02225        *
02226        *  Returns an integer < 0 if this string is ordered before @a s, 0 if
02227        *  their values are equivalent, or > 0 if this string is ordered after
02228        *  @a s.  Determines the effective length rlen of the strings to
02229        *  compare as the smallest of size() and the length of a string
02230        *  constructed from @a s.  The function then compares the two strings
02231        *  by calling traits::compare(data(),s,rlen).  If the result of the
02232        *  comparison is nonzero returns it, otherwise the shorter one is
02233        *  ordered first.
02234       */
02235       int
02236       compare(const _CharT* __s) const;
02237 
02238       // _GLIBCXX_RESOLVE_LIB_DEFECTS
02239       // 5 String::compare specification questionable
02240       /**
02241        *  @brief  Compare substring to a C string.
02242        *  @param pos  Index of first character of substring.
02243        *  @param n1  Number of characters in substring.
02244        *  @param s  C string to compare against.
02245        *  @return  Integer < 0, 0, or > 0.
02246        *
02247        *  Form the substring of this string from the @a n1 characters starting
02248        *  at @a pos.  Returns an integer < 0 if the substring is ordered
02249        *  before @a s, 0 if their values are equivalent, or > 0 if the
02250        *  substring is ordered after @a s.  Determines the effective length
02251        *  rlen of the strings to compare as the smallest of the length of the 
02252        *  substring and the length of a string constructed from @a s.  The
02253        *  function then compares the two string by calling
02254        *  traits::compare(substring.data(),s,rlen).  If the result of the
02255        *  comparison is nonzero returns it, otherwise the shorter one is
02256        *  ordered first.
02257       */
02258       int
02259       compare(size_type __pos, size_type __n1, const _CharT* __s) const;
02260 
02261       /**
02262        *  @brief  Compare substring against a character %array.
02263        *  @param pos1  Index of first character of substring.
02264        *  @param n1  Number of characters in substring.
02265        *  @param s  character %array to compare against.
02266        *  @param n2  Number of characters of s.
02267        *  @return  Integer < 0, 0, or > 0.
02268        *
02269        *  Form the substring of this string from the @a n1 characters starting
02270        *  at @a pos1.  Form a string from the first @a n2 characters of @a s.
02271        *  Returns an integer < 0 if this substring is ordered before the string
02272        *  from @a s, 0 if their values are equivalent, or > 0 if this substring
02273        *  is ordered after the string from @a s.   Determines the effective
02274        *  length rlen of the strings to compare as the smallest of the length
02275        *  of the substring and @a n2.  The function then compares the two
02276        *  strings by calling traits::compare(substring.data(),s,rlen).  If the
02277        *  result of the comparison is nonzero returns it, otherwise the shorter
02278        *  one is ordered first.
02279        *
02280        *  NB: s must have at least n2 characters, &apos;\\0&apos; has
02281        *  no special meaning.
02282       */
02283       int
02284       compare(size_type __pos, size_type __n1, const _CharT* __s,
02285           size_type __n2) const;
02286   };
02287 
02288   // operator+
02289   /**
02290    *  @brief  Concatenate two strings.
02291    *  @param lhs  First string.
02292    *  @param rhs  Last string.
02293    *  @return  New string with value of @a lhs followed by @a rhs.
02294    */
02295   template<typename _CharT, typename _Traits, typename _Alloc>
02296     basic_string<_CharT, _Traits, _Alloc>
02297     operator+(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
02298           const basic_string<_CharT, _Traits, _Alloc>& __rhs)
02299     {
02300       basic_string<_CharT, _Traits, _Alloc> __str(__lhs);
02301       __str.append(__rhs);
02302       return __str;
02303     }
02304 
02305   /**
02306    *  @brief  Concatenate C string and string.
02307    *  @param lhs  First string.
02308    *  @param rhs  Last string.
02309    *  @return  New string with value of @a lhs followed by @a rhs.
02310    */
02311   template<typename _CharT, typename _Traits, typename _Alloc>
02312     basic_string<_CharT,_Traits,_Alloc>
02313     operator+(const _CharT* __lhs,
02314           const basic_string<_CharT,_Traits,_Alloc>& __rhs);
02315 
02316   /**
02317    *  @brief  Concatenate character and string.
02318    *  @param lhs  First string.
02319    *  @param rhs  Last string.
02320    *  @return  New string with @a lhs followed by @a rhs.
02321    */
02322   template<typename _CharT, typename _Traits, typename _Alloc>
02323     basic_string<_CharT,_Traits,_Alloc>
02324     operator+(_CharT __lhs, const basic_string<_CharT,_Traits,_Alloc>& __rhs);
02325 
02326   /**
02327    *  @brief  Concatenate string and C string.
02328    *  @param lhs  First string.
02329    *  @param rhs  Last string.
02330    *  @return  New string with @a lhs followed by @a rhs.
02331    */
02332   template<typename _CharT, typename _Traits, typename _Alloc>
02333     inline basic_string<_CharT, _Traits, _Alloc>
02334     operator+(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
02335          const _CharT* __rhs)
02336     {
02337       basic_string<_CharT, _Traits, _Alloc> __str(__lhs);
02338       __str.append(__rhs);
02339       return __str;
02340     }
02341 
02342   /**
02343    *  @brief  Concatenate string and character.
02344    *  @param lhs  First string.
02345    *  @param rhs  Last string.
02346    *  @return  New string with @a lhs followed by @a rhs.
02347    */
02348   template<typename _CharT, typename _Traits, typename _Alloc>
02349     inline basic_string<_CharT, _Traits, _Alloc>
02350     operator+(const basic_string<_CharT, _Traits, _Alloc>& __lhs, _CharT __rhs)
02351     {
02352       typedef basic_string<_CharT, _Traits, _Alloc> __string_type;
02353       typedef typename __string_type::size_type     __size_type;
02354       __string_type __str(__lhs);
02355       __str.append(__size_type(1), __rhs);
02356       return __str;
02357     }
02358 
02359   // operator ==
02360   /**
02361    *  @brief  Test equivalence of two strings.
02362    *  @param lhs  First string.
02363    *  @param rhs  Second string.
02364    *  @return  True if @a lhs.compare(@a rhs) == 0.  False otherwise.
02365    */
02366   template<typename _CharT, typename _Traits, typename _Alloc>
02367     inline bool
02368     operator==(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
02369            const basic_string<_CharT, _Traits, _Alloc>& __rhs)
02370     { return __lhs.compare(__rhs) == 0; }
02371 
02372   template<typename _CharT>
02373     inline
02374     typename __gnu_cxx::__enable_if<__is_char<_CharT>::__value, bool>::__type
02375     operator==(const basic_string<_CharT>& __lhs,
02376            const basic_string<_CharT>& __rhs)
02377     { return (__lhs.size() == __rhs.size()
02378           && !std::char_traits<_CharT>::compare(__lhs.data(), __rhs.data(),
02379                             __lhs.size())); }
02380 
02381   /**
02382    *  @brief  Test equivalence of C string and string.
02383    *  @param lhs  C string.
02384    *  @param rhs  String.
02385    *  @return  True if @a rhs.compare(@a lhs) == 0.  False otherwise.
02386    */
02387   template<typename _CharT, typename _Traits, typename _Alloc>
02388     inline bool
02389     operator==(const _CharT* __lhs,
02390            const basic_string<_CharT, _Traits, _Alloc>& __rhs)
02391     { return __rhs.compare(__lhs) == 0; }
02392 
02393   /**
02394    *  @brief  Test equivalence of string and C string.
02395    *  @param lhs  String.
02396    *  @param rhs  C string.
02397    *  @return  True if @a lhs.compare(@a rhs) == 0.  False otherwise.
02398    */
02399   template<typename _CharT, typename _Traits, typename _Alloc>
02400     inline bool
02401     operator==(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
02402            const _CharT* __rhs)
02403     { return __lhs.compare(__rhs) == 0; }
02404 
02405   // operator !=
02406   /**
02407    *  @brief  Test difference of two strings.
02408    *  @param lhs  First string.
02409    *  @param rhs  Second string.
02410    *  @return  True if @a lhs.compare(@a rhs) != 0.  False otherwise.
02411    */
02412   template<typename _CharT, typename _Traits, typename _Alloc>
02413     inline bool
02414     operator!=(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
02415            const basic_string<_CharT, _Traits, _Alloc>& __rhs)
02416     { return !(__lhs == __rhs); }
02417 
02418   /**
02419    *  @brief  Test difference of C string and string.
02420    *  @param lhs  C string.
02421    *  @param rhs  String.
02422    *  @return  True if @a rhs.compare(@a lhs) != 0.  False otherwise.
02423    */
02424   template<typename _CharT, typename _Traits, typename _Alloc>
02425     inline bool
02426     operator!=(const _CharT* __lhs,
02427            const basic_string<_CharT, _Traits, _Alloc>& __rhs)
02428     { return !(__lhs == __rhs); }
02429 
02430   /**
02431    *  @brief  Test difference of string and C string.
02432    *  @param lhs  String.
02433    *  @param rhs  C string.
02434    *  @return  True if @a lhs.compare(@a rhs) != 0.  False otherwise.
02435    */
02436   template<typename _CharT, typename _Traits, typename _Alloc>
02437     inline bool
02438     operator!=(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
02439            const _CharT* __rhs)
02440     { return !(__lhs == __rhs); }
02441 
02442   // operator <
02443   /**
02444    *  @brief  Test if string precedes string.
02445    *  @param lhs  First string.
02446    *  @param rhs  Second string.
02447    *  @return  True if @a lhs precedes @a rhs.  False otherwise.
02448    */
02449   template<typename _CharT, typename _Traits, typename _Alloc>
02450     inline bool
02451     operator<(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
02452           const basic_string<_CharT, _Traits, _Alloc>& __rhs)
02453     { return __lhs.compare(__rhs) < 0; }
02454 
02455   /**
02456    *  @brief  Test if string precedes C string.
02457    *  @param lhs  String.
02458    *  @param rhs  C string.
02459    *  @return  True if @a lhs precedes @a rhs.  False otherwise.
02460    */
02461   template<typename _CharT, typename _Traits, typename _Alloc>
02462     inline bool
02463     operator<(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
02464           const _CharT* __rhs)
02465     { return __lhs.compare(__rhs) < 0; }
02466 
02467   /**
02468    *  @brief  Test if C string precedes string.
02469    *  @param lhs  C string.
02470    *  @param rhs  String.
02471    *  @return  True if @a lhs precedes @a rhs.  False otherwise.
02472    */
02473   template<typename _CharT, typename _Traits, typename _Alloc>
02474     inline bool
02475     operator<(const _CharT* __lhs,
02476           const basic_string<_CharT, _Traits, _Alloc>& __rhs)
02477     { return __rhs.compare(__lhs) > 0; }
02478 
02479   // operator >
02480   /**
02481    *  @brief  Test if string follows string.
02482    *  @param lhs  First string.
02483    *  @param rhs  Second string.
02484    *  @return  True if @a lhs follows @a rhs.  False otherwise.
02485    */
02486   template<typename _CharT, typename _Traits, typename _Alloc>
02487     inline bool
02488     operator>(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
02489           const basic_string<_CharT, _Traits, _Alloc>& __rhs)
02490     { return __lhs.compare(__rhs) > 0; }
02491 
02492   /**
02493    *  @brief  Test if string follows C string.
02494    *  @param lhs  String.
02495    *  @param rhs  C string.
02496    *  @return  True if @a lhs follows @a rhs.  False otherwise.
02497    */
02498   template<typename _CharT, typename _Traits, typename _Alloc>
02499     inline bool
02500     operator>(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
02501           const _CharT* __rhs)
02502     { return __lhs.compare(__rhs) > 0; }
02503 
02504   /**
02505    *  @brief  Test if C string follows string.
02506    *  @param lhs  C string.
02507    *  @param rhs  String.
02508    *  @return  True if @a lhs follows @a rhs.  False otherwise.
02509    */
02510   template<typename _CharT, typename _Traits, typename _Alloc>
02511     inline bool
02512     operator>(const _CharT* __lhs,
02513           const basic_string<_CharT, _Traits, _Alloc>& __rhs)
02514     { return __rhs.compare(__lhs) < 0; }
02515 
02516   // operator <=
02517   /**
02518    *  @brief  Test if string doesn't follow string.
02519    *  @param lhs  First string.
02520    *  @param rhs  Second string.
02521    *  @return  True if @a lhs doesn't follow @a rhs.  False otherwise.
02522    */
02523   template<typename _CharT, typename _Traits, typename _Alloc>
02524     inline bool
02525     operator<=(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
02526            const basic_string<_CharT, _Traits, _Alloc>& __rhs)
02527     { return __lhs.compare(__rhs) <= 0; }
02528 
02529   /**
02530    *  @brief  Test if string doesn't follow C string.
02531    *  @param lhs  String.
02532    *  @param rhs  C string.
02533    *  @return  True if @a lhs doesn't follow @a rhs.  False otherwise.
02534    */
02535   template<typename _CharT, typename _Traits, typename _Alloc>
02536     inline bool
02537     operator<=(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
02538            const _CharT* __rhs)
02539     { return __lhs.compare(__rhs) <= 0; }
02540 
02541   /**
02542    *  @brief  Test if C string doesn't follow string.
02543    *  @param lhs  C string.
02544    *  @param rhs  String.
02545    *  @return  True if @a lhs doesn't follow @a rhs.  False otherwise.
02546    */
02547   template<typename _CharT, typename _Traits, typename _Alloc>
02548     inline bool
02549     operator<=(const _CharT* __lhs,
02550            const basic_string<_CharT, _Traits, _Alloc>& __rhs)
02551     { return __rhs.compare(__lhs) >= 0; }
02552 
02553   // operator >=
02554   /**
02555    *  @brief  Test if string doesn't precede string.
02556    *  @param lhs  First string.
02557    *  @param rhs  Second string.
02558    *  @return  True if @a lhs doesn't precede @a rhs.  False otherwise.
02559    */
02560   template<typename _CharT, typename _Traits, typename _Alloc>
02561     inline bool
02562     operator>=(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
02563            const basic_string<_CharT, _Traits, _Alloc>& __rhs)
02564     { return __lhs.compare(__rhs) >= 0; }
02565 
02566   /**
02567    *  @brief  Test if string doesn't precede C string.
02568    *  @param lhs  String.
02569    *  @param rhs  C string.
02570    *  @return  True if @a lhs doesn't precede @a rhs.  False otherwise.
02571    */
02572   template<typename _CharT, typename _Traits, typename _Alloc>
02573     inline bool
02574     operator>=(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
02575            const _CharT* __rhs)
02576     { return __lhs.compare(__rhs) >= 0; }
02577 
02578   /**
02579    *  @brief  Test if C string doesn't precede string.
02580    *  @param lhs  C string.
02581    *  @param rhs  String.
02582    *  @return  True if @a lhs doesn't precede @a rhs.  False otherwise.
02583    */
02584   template<typename _CharT, typename _Traits, typename _Alloc>
02585     inline bool
02586     operator>=(const _CharT* __lhs,
02587          const basic_string<_CharT, _Traits, _Alloc>& __rhs)
02588     { return __rhs.compare(__lhs) <= 0; }
02589 
02590   /**
02591    *  @brief  Swap contents of two strings.
02592    *  @param lhs  First string.
02593    *  @param rhs  Second string.
02594    *
02595    *  Exchanges the contents of @a lhs and @a rhs in constant time.
02596    */
02597   template<typename _CharT, typename _Traits, typename _Alloc>
02598     inline void
02599     swap(basic_string<_CharT, _Traits, _Alloc>& __lhs,
02600      basic_string<_CharT, _Traits, _Alloc>& __rhs)
02601     { __lhs.swap(__rhs); }
02602 
02603   /**
02604    *  @brief  Read stream into a string.
02605    *  @param is  Input stream.
02606    *  @param str  Buffer to store into.
02607    *  @return  Reference to the input stream.
02608    *
02609    *  Stores characters from @a is into @a str until whitespace is found, the
02610    *  end of the stream is encountered, or str.max_size() is reached.  If
02611    *  is.width() is non-zero, that is the limit on the number of characters
02612    *  stored into @a str.  Any previous contents of @a str are erased.
02613    */
02614   template<typename _CharT, typename _Traits, typename _Alloc>
02615     basic_istream<_CharT, _Traits>&
02616     operator>>(basic_istream<_CharT, _Traits>& __is,
02617            basic_string<_CharT, _Traits, _Alloc>& __str);
02618 
02619   template<>
02620     basic_istream<char>&
02621     operator>>(basic_istream<char>& __is, basic_string<char>& __str);
02622 
02623   /**
02624    *  @brief  Write string to a stream.
02625    *  @param os  Output stream.
02626    *  @param str  String to write out.
02627    *  @return  Reference to the output stream.
02628    *
02629    *  Output characters of @a str into os following the same rules as for
02630    *  writing a C string.
02631    */
02632   template<typename _CharT, typename _Traits, typename _Alloc>
02633     inline basic_ostream<_CharT, _Traits>&
02634     operator<<(basic_ostream<_CharT, _Traits>& __os,
02635            const basic_string<_CharT, _Traits, _Alloc>& __str)
02636     {
02637       // _GLIBCXX_RESOLVE_LIB_DEFECTS
02638       // 586. string inserter not a formatted function
02639       return __ostream_insert(__os, __str.data(), __str.size());
02640     }
02641 
02642   /**
02643    *  @brief  Read a line from stream into a string.
02644    *  @param is  Input stream.
02645    *  @param str  Buffer to store into.
02646    *  @param delim  Character marking end of line.
02647    *  @return  Reference to the input stream.
02648    *
02649    *  Stores characters from @a is into @a str until @a delim is found, the
02650    *  end of the stream is encountered, or str.max_size() is reached.  If
02651    *  is.width() is non-zero, that is the limit on the number of characters
02652    *  stored into @a str.  Any previous contents of @a str are erased.  If @a
02653    *  delim was encountered, it is extracted but not stored into @a str.
02654    */
02655   template<typename _CharT, typename _Traits, typename _Alloc>
02656     basic_istream<_CharT, _Traits>&
02657     getline(basic_istream<_CharT, _Traits>& __is,
02658         basic_string<_CharT, _Traits, _Alloc>& __str, _CharT __delim);
02659 
02660   /**
02661    *  @brief  Read a line from stream into a string.
02662    *  @param is  Input stream.
02663    *  @param str  Buffer to store into.
02664    *  @return  Reference to the input stream.
02665    *
02666    *  Stores characters from is into @a str until &apos;\n&apos; is
02667    *  found, the end of the stream is encountered, or str.max_size()
02668    *  is reached.  If is.width() is non-zero, that is the limit on the
02669    *  number of characters stored into @a str.  Any previous contents
02670    *  of @a str are erased.  If end of line was encountered, it is
02671    *  extracted but not stored into @a str.
02672    */
02673   template<typename _CharT, typename _Traits, typename _Alloc>
02674     inline basic_istream<_CharT, _Traits>&
02675     getline(basic_istream<_CharT, _Traits>& __is,
02676         basic_string<_CharT, _Traits, _Alloc>& __str)
02677     { return getline(__is, __str, __is.widen('\n')); }
02678 
02679   template<>
02680     basic_istream<char>&
02681     getline(basic_istream<char>& __in, basic_string<char>& __str,
02682         char __delim);
02683 
02684 #ifdef _GLIBCXX_USE_WCHAR_T
02685   template<>
02686     basic_istream<wchar_t>&
02687     getline(basic_istream<wchar_t>& __in, basic_string<wchar_t>& __str,
02688         wchar_t __delim);
02689 #endif  
02690 
02691 _GLIBCXX_END_NAMESPACE
02692 
02693 #if (defined(__GXX_EXPERIMENTAL_CXX0X__) && defined(_GLIBCXX_USE_C99) \
02694      && !defined(_GLIBCXX_HAVE_BROKEN_VSWPRINTF))
02695 
02696 #include <ext/string_conversions.h>
02697 
02698 _GLIBCXX_BEGIN_NAMESPACE(std)
02699 
02700   // 21.4 Numeric Conversions [string.conversions].
02701   inline int
02702   stoi(const string& __str, size_t* __idx = 0, int __base = 10)
02703   { return __gnu_cxx::__stoa<long, int>(&std::strtol, "stoi", __str.c_str(),
02704                     __idx, __base); }
02705 
02706   inline long
02707   stol(const string& __str, size_t* __idx = 0, int __base = 10)
02708   { return __gnu_cxx::__stoa(&std::strtol, "stol", __str.c_str(),
02709                  __idx, __base); }
02710 
02711   inline unsigned long
02712   stoul(const string& __str, size_t* __idx = 0, int __base = 10)
02713   { return __gnu_cxx::__stoa(&std::strtoul, "stoul", __str.c_str(),
02714                  __idx, __base); }
02715 
02716   inline long long
02717   stoll(const string& __str, size_t* __idx = 0, int __base = 10)
02718   { return __gnu_cxx::__stoa(&std::strtoll, "stoll", __str.c_str(),
02719                  __idx, __base); }
02720 
02721   inline unsigned long long
02722   stoull(const string& __str, size_t* __idx = 0, int __base = 10)
02723   { return __gnu_cxx::__stoa(&std::strtoull, "stoull", __str.c_str(),
02724                  __idx, __base); }
02725 
02726   // NB: strtof vs strtod.
02727   inline float
02728   stof(const string& __str, size_t* __idx = 0)
02729   { return __gnu_cxx::__stoa(&std::strtof, "stof", __str.c_str(), __idx); }
02730 
02731   inline double
02732   stod(const string& __str, size_t* __idx = 0)
02733   { return __gnu_cxx::__stoa(&std::strtod, "stod", __str.c_str(), __idx); }
02734 
02735   inline long double
02736   stold(const string& __str, size_t* __idx = 0)
02737   { return __gnu_cxx::__stoa(&std::strtold, "stold", __str.c_str(), __idx); }
02738 
02739   // NB: (v)snprintf vs sprintf.
02740 
02741   // DR 1261.
02742   inline string
02743   to_string(int __val)
02744   { return __gnu_cxx::__to_xstring<string>(&std::vsnprintf, 4 * sizeof(int),
02745                        "%d", __val); }
02746 
02747   inline string
02748   to_string(unsigned __val)
02749   { return __gnu_cxx::__to_xstring<string>(&std::vsnprintf,
02750                        4 * sizeof(unsigned),
02751                        "%u", __val); }
02752 
02753   inline string
02754   to_string(long __val)
02755   { return __gnu_cxx::__to_xstring<string>(&std::vsnprintf, 4 * sizeof(long),
02756                        "%ld", __val); }
02757 
02758   inline string
02759   to_string(unsigned long __val)
02760   { return __gnu_cxx::__to_xstring<string>(&std::vsnprintf,
02761                        4 * sizeof(unsigned long),
02762                        "%lu", __val); }
02763 
02764   inline string
02765   to_string(long long __val)
02766   { return __gnu_cxx::__to_xstring<string>(&std::vsnprintf,
02767                        4 * sizeof(long long),
02768                        "%lld", __val); }
02769 
02770   inline string
02771   to_string(unsigned long long __val)
02772   { return __gnu_cxx::__to_xstring<string>(&std::vsnprintf,
02773                        4 * sizeof(unsigned long long),
02774                        "%llu", __val); }
02775 
02776   inline string
02777   to_string(float __val)
02778   {
02779     const int __n = 
02780       __gnu_cxx::__numeric_traits<float>::__max_exponent10 + 20;
02781     return __gnu_cxx::__to_xstring<string>(&std::vsnprintf, __n,
02782                        "%f", __val);
02783   }
02784 
02785   inline string
02786   to_string(double __val)
02787   {
02788     const int __n = 
02789       __gnu_cxx::__numeric_traits<double>::__max_exponent10 + 20;
02790     return __gnu_cxx::__to_xstring<string>(&std::vsnprintf, __n,
02791                        "%f", __val);
02792   }
02793 
02794   inline string
02795   to_string(long double __val)
02796   {
02797     const int __n = 
02798       __gnu_cxx::__numeric_traits<long double>::__max_exponent10 + 20;
02799     return __gnu_cxx::__to_xstring<string>(&std::vsnprintf, __n,
02800                        "%Lf", __val);
02801   }
02802 
02803 #ifdef _GLIBCXX_USE_WCHAR_T
02804   inline int 
02805   stoi(const wstring& __str, size_t* __idx = 0, int __base = 10)
02806   { return __gnu_cxx::__stoa<long, int>(&std::wcstol, "stoi", __str.c_str(),
02807                     __idx, __base); }
02808 
02809   inline long 
02810   stol(const wstring& __str, size_t* __idx = 0, int __base = 10)
02811   { return __gnu_cxx::__stoa(&std::wcstol, "stol", __str.c_str(),
02812                  __idx, __base); }
02813 
02814   inline unsigned long
02815   stoul(const wstring& __str, size_t* __idx = 0, int __base = 10)
02816   { return __gnu_cxx::__stoa(&std::wcstoul, "stoul", __str.c_str(),
02817                  __idx, __base); }
02818 
02819   inline long long
02820   stoll(const wstring& __str, size_t* __idx = 0, int __base = 10)
02821   { return __gnu_cxx::__stoa(&std::wcstoll, "stoll", __str.c_str(),
02822                  __idx, __base); }
02823 
02824   inline unsigned long long
02825   stoull(const wstring& __str, size_t* __idx = 0, int __base = 10)
02826   { return __gnu_cxx::__stoa(&std::wcstoull, "stoull", __str.c_str(),
02827                  __idx, __base); }
02828 
02829   // NB: wcstof vs wcstod.
02830   inline float
02831   stof(const wstring& __str, size_t* __idx = 0)
02832   { return __gnu_cxx::__stoa(&std::wcstof, "stof", __str.c_str(), __idx); }
02833 
02834   inline double
02835   stod(const wstring& __str, size_t* __idx = 0)
02836   { return __gnu_cxx::__stoa(&std::wcstod, "stod", __str.c_str(), __idx); }
02837 
02838   inline long double
02839   stold(const wstring& __str, size_t* __idx = 0)
02840   { return __gnu_cxx::__stoa(&std::wcstold, "stold", __str.c_str(), __idx); }
02841 
02842   // DR 1261.
02843   inline wstring
02844   to_wstring(int __val)
02845   { return __gnu_cxx::__to_xstring<wstring>(&std::vswprintf, 4 * sizeof(int),
02846                         L"%d", __val); }
02847 
02848   inline wstring
02849   to_wstring(unsigned __val)
02850   { return __gnu_cxx::__to_xstring<wstring>(&std::vswprintf,
02851                         4 * sizeof(unsigned),
02852                         L"%u", __val); }
02853 
02854   inline wstring
02855   to_wstring(long __val)
02856   { return __gnu_cxx::__to_xstring<wstring>(&std::vswprintf, 4 * sizeof(long),
02857                         L"%ld", __val); }
02858 
02859   inline wstring
02860   to_wstring(unsigned long __val)
02861   { return __gnu_cxx::__to_xstring<wstring>(&std::vswprintf,
02862                         4 * sizeof(unsigned long),
02863                         L"%lu", __val); }
02864 
02865   inline wstring
02866   to_wstring(long long __val)
02867   { return __gnu_cxx::__to_xstring<wstring>(&std::vswprintf,
02868                         4 * sizeof(long long),
02869                         L"%lld", __val); }
02870 
02871   inline wstring
02872   to_wstring(unsigned long long __val)
02873   { return __gnu_cxx::__to_xstring<wstring>(&std::vswprintf,
02874                         4 * sizeof(unsigned long long),
02875                         L"%llu", __val); }
02876 
02877   inline wstring
02878   to_wstring(float __val)
02879   {
02880     const int __n =
02881       __gnu_cxx::__numeric_traits<float>::__max_exponent10 + 20;
02882     return __gnu_cxx::__to_xstring<wstring>(&std::vswprintf, __n,
02883                         L"%f", __val);
02884   }
02885 
02886   inline wstring
02887   to_wstring(double __val)
02888   {
02889     const int __n =
02890       __gnu_cxx::__numeric_traits<double>::__max_exponent10 + 20;
02891     return __gnu_cxx::__to_xstring<wstring>(&std::vswprintf, __n,
02892                         L"%f", __val);
02893   }
02894 
02895   inline wstring
02896   to_wstring(long double __val)
02897   {
02898     const int __n =
02899       __gnu_cxx::__numeric_traits<long double>::__max_exponent10 + 20;
02900     return __gnu_cxx::__to_xstring<wstring>(&std::vswprintf, __n,
02901                         L"%Lf", __val);
02902   }
02903 #endif
02904 
02905 _GLIBCXX_END_NAMESPACE
02906 
02907 #endif /* __GXX_EXPERIMENTAL_CXX0X__ && _GLIBCXX_USE_C99 ... */
02908 
02909 #ifdef __GXX_EXPERIMENTAL_CXX0X__
02910 
02911 #include <bits/functional_hash.h>
02912 
02913 _GLIBCXX_BEGIN_NAMESPACE(std)
02914 
02915   // DR 1182.
02916 
02917 #ifndef _GLIBCXX_COMPATIBILITY_CXX0X
02918   /// std::hash specialization for string.
02919   template<>
02920     struct hash<string>
02921     : public std::unary_function<string, size_t>
02922     {
02923       size_t
02924       operator()(const string& __s) const
02925       { return std::_Fnv_hash::hash(__s.data(), __s.length()); }
02926     };
02927 
02928 #ifdef _GLIBCXX_USE_WCHAR_T
02929   /// std::hash specialization for wstring.
02930   template<>
02931     struct hash<wstring>
02932     : public std::unary_function<wstring, size_t>
02933     {
02934       size_t
02935       operator()(const wstring& __s) const
02936       { return std::_Fnv_hash::hash(__s.data(),
02937                     __s.length() * sizeof(wchar_t)); }
02938     };
02939 #endif
02940 #endif /* _GLIBCXX_COMPATIBILITY_CXX0X */
02941 
02942 #ifdef _GLIBCXX_USE_C99_STDINT_TR1
02943   /// std::hash specialization for u16string.
02944   template<>
02945     struct hash<u16string>
02946     : public std::unary_function<u16string, size_t>
02947     {
02948       size_t
02949       operator()(const u16string& __s) const
02950       { return std::_Fnv_hash::hash(__s.data(),
02951                     __s.length() * sizeof(char16_t)); }
02952     };
02953 
02954   /// std::hash specialization for u32string.
02955   template<>
02956     struct hash<u32string>
02957     : public std::unary_function<u32string, size_t>
02958     {
02959       size_t
02960       operator()(const u32string& __s) const
02961       { return std::_Fnv_hash::hash(__s.data(),
02962                     __s.length() * sizeof(char32_t)); }
02963     };
02964 #endif
02965 
02966 _GLIBCXX_END_NAMESPACE
02967 
02968 #endif /* __GXX_EXPERIMENTAL_CXX0X__ */
02969 
02970 #endif /* _BASIC_STRING_H */