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