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