basic_string.h

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

Generated on Sun Jul 25 00:12:32 2004 for libstdc++ source by doxygen 1.3.7