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

Generated on 12 Mar 2010 for libstdc++ by  doxygen 1.6.1