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