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

Generated on Tue May 23 12:55:24 2006 for libstdc++ source by  doxygen 1.4.4