# vstring.h

Go to the documentation of this file.

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