basic_string.h

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

Generated on Sat Apr 2 13:54:41 2005 for libstdc++ source by  doxygen 1.4.0