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

Generated on 19 Jun 2018 for libstdc++ by  doxygen 1.6.1