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