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