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

Generated on 11 Jan 2010 for libstdc++ by  doxygen 1.6.1