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

Generated on Thu Jul 23 21:15:58 2009 for libstdc++ by  doxygen 1.5.8