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