1 // Components for manipulating sequences of characters -*- C++ -*-
3 // Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004
4 // Free Software Foundation, Inc.
6 // This file is part of the GNU ISO C++ Library. This library is free
7 // software; you can redistribute it and/or modify it under the
8 // terms of the GNU General Public License as published by the
9 // Free Software Foundation; either version 2, or (at your option)
12 // This library is distributed in the hope that it will be useful,
13 // but WITHOUT ANY WARRANTY; without even the implied warranty of
14 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 // GNU General Public License for more details.
17 // You should have received a copy of the GNU General Public License along
18 // with this library; see the file COPYING. If not, write to the Free
19 // Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307,
22 // As a special exception, you may use this file as part of a free software
23 // library without restriction. Specifically, if other files instantiate
24 // templates or use macros or inline functions from this file, or you compile
25 // this file and link it with other files to produce an executable, this
26 // file does not by itself cause the resulting executable to be covered by
27 // the GNU General Public License. This exception does not however
28 // invalidate any other reasons why the executable file might be covered by
29 // the GNU General Public License.
32 // ISO C++ 14882: 21 Strings library
35 /** @file basic_string.h
36 * This is an internal header file, included by other library headers.
37 * You should not attempt to use it directly.
40 #ifndef _BASIC_STRING_H
41 #define _BASIC_STRING_H 1
43 #pragma GCC system_header
45 #include <bits/atomicity.h>
46 #include <debug/debug.h>
51 * @class basic_string basic_string.h <string>
52 * @brief Managing sequences of characters and character-like objects.
57 * Meets the requirements of a <a href="tables.html#65">container</a>, a
58 * <a href="tables.html#66">reversible container</a>, and a
59 * <a href="tables.html#67">sequence</a>. Of the
60 * <a href="tables.html#68">optional sequence requirements</a>, only
61 * @c push_back, @c at, and array access are supported.
67 * Documentation? What's that?
68 * Nathan Myers <ncm@cantrip.org>.
70 * A string looks like this:
75 * [basic_string<char_type>] _M_capacity
76 * _M_dataplus _M_refcount
77 * _M_p ----------------> unnamed array of char_type
80 * Where the _M_p points to the first character in the string, and
81 * you cast it to a pointer-to-_Rep and subtract 1 to get a
82 * pointer to the header.
84 * This approach has the enormous advantage that a string object
85 * requires only one allocation. All the ugliness is confined
86 * within a single pair of inline functions, which each compile to
87 * a single "add" instruction: _Rep::_M_data(), and
88 * string::_M_rep(); and the allocation function which gets a
89 * block of raw bytes and with room enough and constructs a _Rep
90 * object at the front.
92 * The reason you want _M_data pointing to the character array and
93 * not the _Rep is so that the debugger can see the string
94 * contents. (Probably we should add a non-inline member to get
95 * the _Rep for the debugger to use, so users can check the actual
98 * Note that the _Rep object is a POD so that you can have a
99 * static "empty string" _Rep object already "constructed" before
100 * static constructors have run. The reference-count encoding is
101 * chosen so that a 0 indicates one reference, so you never try to
102 * destroy the empty-string _Rep object.
104 * All but the last paragraph is considered pretty conventional
105 * for a C++ string implementation.
108 // 21.3 Template class basic_string
109 template<typename _CharT
, typename _Traits
, typename _Alloc
>
114 typedef _Traits traits_type
;
115 typedef typename
_Traits::char_type value_type
;
116 typedef _Alloc allocator_type
;
117 typedef typename
_Alloc::size_type size_type
;
118 typedef typename
_Alloc::difference_type difference_type
;
119 typedef typename
_Alloc::reference reference
;
120 typedef typename
_Alloc::const_reference const_reference
;
121 typedef typename
_Alloc::pointer pointer
;
122 typedef typename
_Alloc::const_pointer const_pointer
;
123 typedef __gnu_cxx::__normal_iterator
<pointer
, basic_string
> iterator
;
124 typedef __gnu_cxx::__normal_iterator
<const_pointer
, basic_string
>
126 typedef std::reverse_iterator
<const_iterator
> const_reverse_iterator
;
127 typedef std::reverse_iterator
<iterator
> reverse_iterator
;
130 // _Rep: string representation
132 // 1. String really contains _M_length + 1 characters: due to 21.3.4
133 // must be kept null-terminated.
134 // 2. _M_capacity >= _M_length
135 // Allocated memory is always (_M_capacity + 1) * sizeof(_CharT).
136 // 3. _M_refcount has three states:
137 // -1: leaked, one reference, no ref-copies allowed, non-const.
138 // 0: one reference, non-const.
139 // n>0: n + 1 references, operations require a lock, const.
140 // 4. All fields==0 is an empty string, given the extra storage
141 // beyond-the-end for a null terminator; thus, the shared
142 // empty string representation needs no constructor.
147 size_type _M_capacity
;
148 _Atomic_word _M_refcount
;
151 struct _Rep
: _Rep_base
154 typedef typename
_Alloc::template rebind
<char>::other _Raw_bytes_alloc
;
156 // (Public) Data members:
158 // The maximum number of individual char_type elements of an
159 // individual string is determined by _S_max_size. This is the
160 // value that will be returned by max_size(). (Whereas npos
161 // is the maximum number of bytes the allocator can allocate.)
162 // If one was to divvy up the theoretical largest size string,
163 // with a terminating character and m _CharT elements, it'd
165 // npos = sizeof(_Rep) + (m * sizeof(_CharT)) + sizeof(_CharT)
167 // m = ((npos - sizeof(_Rep))/sizeof(CharT)) - 1
168 // In addition, this implementation quarters this amount.
169 static const size_type _S_max_size
;
170 static const _CharT _S_terminal
;
172 // The following storage is init'd to 0 by the linker, resulting
173 // (carefully) in an empty string with one reference.
174 static size_type _S_empty_rep_storage
[];
178 { return *reinterpret_cast<_Rep
*>(&_S_empty_rep_storage
); }
182 { return this->_M_refcount
< 0; }
186 { return this->_M_refcount
> 0; }
190 { this->_M_refcount
= -1; }
194 { this->_M_refcount
= 0; }
198 { return reinterpret_cast<_CharT
*>(this + 1); }
201 _M_grab(const _Alloc
& __alloc1
, const _Alloc
& __alloc2
)
203 return (!_M_is_leaked() && __alloc1
== __alloc2
)
204 ? _M_refcopy() : _M_clone(__alloc1
);
209 _S_create(size_type
, size_type
, const _Alloc
&);
212 _M_dispose(const _Alloc
& __a
)
214 #ifndef _GLIBCXX_FULLY_DYNAMIC_STRING
215 if (__builtin_expect(this != &_S_empty_rep(), false))
217 if (__gnu_cxx::__exchange_and_add(&this->_M_refcount
, -1) <= 0)
222 _M_destroy(const _Alloc
&) throw();
227 #ifndef _GLIBCXX_FULLY_DYNAMIC_STRING
228 if (__builtin_expect(this != &_S_empty_rep(), false))
230 __gnu_cxx::__atomic_add(&this->_M_refcount
, 1);
235 _M_clone(const _Alloc
&, size_type __res
= 0);
238 // Use empty-base optimization: http://www.cantrip.org/emptyopt.html
239 struct _Alloc_hider
: _Alloc
241 _Alloc_hider(_CharT
* __dat
, const _Alloc
& __a
)
242 : _Alloc(__a
), _M_p(__dat
) { }
244 _CharT
* _M_p
; // The actual data.
248 // Data Members (public):
249 // NB: This is an unsigned type, and thus represents the maximum
250 // size that the allocator can hold.
252 /// Value returned by various member functions when they fail.
253 static const size_type npos
= static_cast<size_type
>(-1);
256 // Data Members (private):
257 mutable _Alloc_hider _M_dataplus
;
261 { return _M_dataplus
._M_p
; }
265 { return (_M_dataplus
._M_p
= __p
); }
269 { return &((reinterpret_cast<_Rep
*> (_M_data()))[-1]); }
271 // For the internal use we have functions similar to `begin'/`end'
272 // but they do not call _M_leak.
274 _M_ibegin() const { return iterator(_M_data()); }
277 _M_iend() const { return iterator(_M_data() + this->size()); }
280 _M_leak() // for use in begin() & non-const op[]
282 if (!_M_rep()->_M_is_leaked())
287 _M_check(size_type __pos
, const char* __s
) const
289 if (__pos
> this->size())
290 __throw_out_of_range(__N(__s
));
294 // NB: _M_limit doesn't check for a bad __pos value.
296 _M_limit(size_type __pos
, size_type __off
) const
298 const bool __testoff
= __off
< this->size() - __pos
;
299 return __testoff
? __off
: this->size() - __pos
;
302 // _S_copy_chars is a separate template to permit specialization
303 // to optimize for the common case of pointers as iterators.
304 template<class _Iterator
>
306 _S_copy_chars(_CharT
* __p
, _Iterator __k1
, _Iterator __k2
)
308 for (; __k1
!= __k2
; ++__k1
, ++__p
)
309 traits_type::assign(*__p
, *__k1
); // These types are off.
313 _S_copy_chars(_CharT
* __p
, iterator __k1
, iterator __k2
)
314 { _S_copy_chars(__p
, __k1
.base(), __k2
.base()); }
317 _S_copy_chars(_CharT
* __p
, const_iterator __k1
, const_iterator __k2
)
318 { _S_copy_chars(__p
, __k1
.base(), __k2
.base()); }
321 _S_copy_chars(_CharT
* __p
, _CharT
* __k1
, _CharT
* __k2
)
322 { traits_type::copy(__p
, __k1
, __k2
- __k1
); }
325 _S_copy_chars(_CharT
* __p
, const _CharT
* __k1
, const _CharT
* __k2
)
326 { traits_type::copy(__p
, __k1
, __k2
- __k1
); }
329 _M_mutate(size_type __pos
, size_type __len1
, size_type __len2
);
336 { return _Rep::_S_empty_rep(); }
339 // Construct/copy/destroy:
340 // NB: We overload ctors in some cases instead of using default
341 // arguments, per 17.4.4.4 para. 2 item 2.
344 * @brief Default constructor creates an empty string.
350 * @brief Construct an empty string using allocator a.
353 basic_string(const _Alloc
& __a
);
355 // NB: per LWG issue 42, semantics different from IS:
357 * @brief Construct string with copy of value of @a str.
358 * @param str Source string.
360 basic_string(const basic_string
& __str
);
362 * @brief Construct string as copy of a substring.
363 * @param str Source string.
364 * @param pos Index of first character to copy from.
365 * @param n Number of characters to copy (default remainder).
367 basic_string(const basic_string
& __str
, size_type __pos
,
368 size_type __n
= npos
);
370 * @brief Construct string as copy of a substring.
371 * @param str Source string.
372 * @param pos Index of first character to copy from.
373 * @param n Number of characters to copy.
374 * @param a Allocator to use.
376 basic_string(const basic_string
& __str
, size_type __pos
,
377 size_type __n
, const _Alloc
& __a
);
380 * @brief Construct string initialized by a character array.
381 * @param s Source character array.
382 * @param n Number of characters to copy.
383 * @param a Allocator to use (default is default allocator).
385 * NB: s must have at least n characters, '\0' has no special
388 basic_string(const _CharT
* __s
, size_type __n
,
389 const _Alloc
& __a
= _Alloc());
391 * @brief Construct string as copy of a C string.
392 * @param s Source C string.
393 * @param a Allocator to use (default is default allocator).
395 basic_string(const _CharT
* __s
, const _Alloc
& __a
= _Alloc());
397 * @brief Construct string as multiple characters.
398 * @param n Number of characters.
399 * @param c Character to use.
400 * @param a Allocator to use (default is default allocator).
402 basic_string(size_type __n
, _CharT __c
, const _Alloc
& __a
= _Alloc());
405 * @brief Construct string as copy of a range.
406 * @param beg Start of range.
407 * @param end End of range.
408 * @param a Allocator to use (default is default allocator).
410 template<class _InputIterator
>
411 basic_string(_InputIterator __beg
, _InputIterator __end
,
412 const _Alloc
& __a
= _Alloc());
415 * @brief Destroy the string instance.
418 { _M_rep()->_M_dispose(this->get_allocator()); }
421 * @brief Assign the value of @a str to this string.
422 * @param str Source string.
425 operator=(const basic_string
& __str
)
426 { return this->assign(__str
); }
429 * @brief Copy contents of @a s into this string.
430 * @param s Source null-terminated string.
433 operator=(const _CharT
* __s
)
434 { return this->assign(__s
); }
437 * @brief Set value to string of length 1.
438 * @param c Source character.
440 * Assigning to a character makes this string length 1 and
441 * (*this)[0] == @a c.
444 operator=(_CharT __c
)
446 this->assign(1, __c
);
452 * Returns a read/write iterator that points to the first character in
453 * the %string. Unshares the string.
459 return iterator(_M_data());
463 * Returns a read-only (constant) iterator that points to the first
464 * character in the %string.
468 { return const_iterator(_M_data()); }
471 * Returns a read/write iterator that points one past the last
472 * character in the %string. Unshares the string.
478 return iterator(_M_data() + this->size());
482 * Returns a read-only (constant) iterator that points one past the
483 * last character in the %string.
487 { return const_iterator(_M_data() + this->size()); }
490 * Returns a read/write reverse iterator that points to the last
491 * character in the %string. Iteration is done in reverse element
492 * order. Unshares the string.
496 { return reverse_iterator(this->end()); }
499 * Returns a read-only (constant) reverse iterator that points
500 * to the last character in the %string. Iteration is done in
501 * reverse element order.
503 const_reverse_iterator
505 { return const_reverse_iterator(this->end()); }
508 * Returns a read/write reverse iterator that points to one before the
509 * first character in the %string. Iteration is done in reverse
510 * element order. Unshares the string.
514 { return reverse_iterator(this->begin()); }
517 * Returns a read-only (constant) reverse iterator that points
518 * to one before the first character in the %string. Iteration
519 * is done in reverse element order.
521 const_reverse_iterator
523 { return const_reverse_iterator(this->begin()); }
527 /// Returns the number of characters in the string, not including any
528 /// null-termination.
530 size() const { return _M_rep()->_M_length
; }
532 /// Returns the number of characters in the string, not including any
533 /// null-termination.
535 length() const { return _M_rep()->_M_length
; }
537 /// Returns the size() of the largest possible %string.
539 max_size() const { return _Rep::_S_max_size
; }
542 * @brief Resizes the %string to the specified number of characters.
543 * @param n Number of characters the %string should contain.
544 * @param c Character to fill any new elements.
546 * This function will %resize the %string to the specified
547 * number of characters. If the number is smaller than the
548 * %string's current size the %string is truncated, otherwise
549 * the %string is extended and new elements are set to @a c.
552 resize(size_type __n
, _CharT __c
);
555 * @brief Resizes the %string to the specified number of characters.
556 * @param n Number of characters the %string should contain.
558 * This function will resize the %string to the specified length. If
559 * the new size is smaller than the %string's current size the %string
560 * is truncated, otherwise the %string is extended and new characters
561 * are default-constructed. For basic types such as char, this means
565 resize(size_type __n
) { this->resize(__n
, _CharT()); }
568 * Returns the total number of characters that the %string can hold
569 * before needing to allocate more memory.
572 capacity() const { return _M_rep()->_M_capacity
; }
575 * @brief Attempt to preallocate enough memory for specified number of
577 * @param n Number of characters required.
578 * @throw std::length_error If @a n exceeds @c max_size().
580 * This function attempts to reserve enough memory for the
581 * %string to hold the specified number of characters. If the
582 * number requested is more than max_size(), length_error is
585 * The advantage of this function is that if optimal code is a
586 * necessity and the user can determine the string length that will be
587 * required, the user can reserve the memory in %advance, and thus
588 * prevent a possible reallocation of memory and copying of %string
592 reserve(size_type __res_arg
= 0);
595 * Erases the string, making it empty.
598 clear() { _M_mutate(0, this->size(), 0); }
601 * Returns true if the %string is empty. Equivalent to *this == "".
604 empty() const { return this->size() == 0; }
608 * @brief Subscript access to the data contained in the %string.
609 * @param n The index of the character to access.
610 * @return Read-only (constant) reference to the character.
612 * This operator allows for easy, array-style, data access.
613 * Note that data access with this operator is unchecked and
614 * out_of_range lookups are not defined. (For checked lookups
618 operator[] (size_type __pos
) const
620 _GLIBCXX_DEBUG_ASSERT(__pos
<= size());
621 return _M_data()[__pos
];
625 * @brief Subscript access to the data contained in the %string.
626 * @param n The index of the character to access.
627 * @return Read/write reference to the character.
629 * This operator allows for easy, array-style, data access.
630 * Note that data access with this operator is unchecked and
631 * out_of_range lookups are not defined. (For checked lookups
632 * see at().) Unshares the string.
635 operator[](size_type __pos
)
637 _GLIBCXX_DEBUG_ASSERT(__pos
< size());
639 return _M_data()[__pos
];
643 * @brief Provides access to the data contained in the %string.
644 * @param n The index of the character to access.
645 * @return Read-only (const) reference to the character.
646 * @throw std::out_of_range If @a n is an invalid index.
648 * This function provides for safer data access. The parameter is
649 * first checked that it is in the range of the string. The function
650 * throws out_of_range if the check fails.
653 at(size_type __n
) const
655 if (__n
>= this->size())
656 __throw_out_of_range(__N("basic_string::at"));
657 return _M_data()[__n
];
661 * @brief Provides access to the data contained in the %string.
662 * @param n The index of the character to access.
663 * @return Read/write reference to the character.
664 * @throw std::out_of_range If @a n is an invalid index.
666 * This function provides for safer data access. The parameter is
667 * first checked that it is in the range of the string. The function
668 * throws out_of_range if the check fails. Success results in
669 * unsharing the string.
675 __throw_out_of_range(__N("basic_string::at"));
677 return _M_data()[__n
];
682 * @brief Append a string to this string.
683 * @param str The string to append.
684 * @return Reference to this string.
687 operator+=(const basic_string
& __str
) { return this->append(__str
); }
690 * @brief Append a C string.
691 * @param s The C string to append.
692 * @return Reference to this string.
695 operator+=(const _CharT
* __s
) { return this->append(__s
); }
698 * @brief Append a character.
699 * @param s The character to append.
700 * @return Reference to this string.
703 operator+=(_CharT __c
) { return this->append(size_type(1), __c
); }
706 * @brief Append a string to this string.
707 * @param str The string to append.
708 * @return Reference to this string.
711 append(const basic_string
& __str
);
714 * @brief Append a substring.
715 * @param str The string to append.
716 * @param pos Index of the first character of str to append.
717 * @param n The number of characters to append.
718 * @return Reference to this string.
719 * @throw std::out_of_range if @a pos is not a valid index.
721 * This function appends @a n characters from @a str starting at @a pos
722 * to this string. If @a n is is larger than the number of available
723 * characters in @a str, the remainder of @a str is appended.
726 append(const basic_string
& __str
, size_type __pos
, size_type __n
);
729 * @brief Append a C substring.
730 * @param s The C string to append.
731 * @param n The number of characters to append.
732 * @return Reference to this string.
735 append(const _CharT
* __s
, size_type __n
);
738 * @brief Append a C string.
739 * @param s The C string to append.
740 * @return Reference to this string.
743 append(const _CharT
* __s
)
745 __glibcxx_requires_string(__s
);
746 return this->append(__s
, traits_type::length(__s
));
750 * @brief Append multiple characters.
751 * @param n The number of characters to append.
752 * @param c The character to use.
753 * @return Reference to this string.
755 * Appends n copies of c to this string.
758 append(size_type __n
, _CharT __c
)
759 { return _M_replace_aux(this->size(), size_type(0), __n
, __c
); }
762 * @brief Append a range of characters.
763 * @param first Iterator referencing the first character to append.
764 * @param last Iterator marking the end of the range.
765 * @return Reference to this string.
767 * Appends characters in the range [first,last) to this string.
769 template<class _InputIterator
>
771 append(_InputIterator __first
, _InputIterator __last
)
772 { return this->replace(_M_iend(), _M_iend(), __first
, __last
); }
775 * @brief Append a single character.
776 * @param c Character to append.
779 push_back(_CharT __c
)
780 { _M_replace_aux(this->size(), size_type(0), size_type(1), __c
); }
783 * @brief Set value to contents of another string.
784 * @param str Source string to use.
785 * @return Reference to this string.
788 assign(const basic_string
& __str
);
791 * @brief Set value to a substring of a string.
792 * @param str The string to use.
793 * @param pos Index of the first character of str.
794 * @param n Number of characters to use.
795 * @return Reference to this string.
796 * @throw std::out_of_range if @a pos is not a valid index.
798 * This function sets this string to the substring of @a str consisting
799 * of @a n characters at @a pos. If @a n is is larger than the number
800 * of available characters in @a str, the remainder of @a str is used.
803 assign(const basic_string
& __str
, size_type __pos
, size_type __n
)
804 { return this->assign(__str
._M_data()
805 + __str
._M_check(__pos
, "basic_string::assign"),
806 __str
._M_limit(__pos
, __n
)); }
809 * @brief Set value to a C substring.
810 * @param s The C string to use.
811 * @param n Number of characters to use.
812 * @return Reference to this string.
814 * This function sets the value of this string to the first @a n
815 * characters of @a s. If @a n is is larger than the number of
816 * available characters in @a s, the remainder of @a s is used.
819 assign(const _CharT
* __s
, size_type __n
);
822 * @brief Set value to contents of a C string.
823 * @param s The C string to use.
824 * @return Reference to this string.
826 * This function sets the value of this string to the value of @a s.
827 * The data is copied, so there is no dependence on @a s once the
831 assign(const _CharT
* __s
)
833 __glibcxx_requires_string(__s
);
834 return this->assign(__s
, traits_type::length(__s
));
838 * @brief Set value to multiple characters.
839 * @param n Length of the resulting string.
840 * @param c The character to use.
841 * @return Reference to this string.
843 * This function sets the value of this string to @a n copies of
847 assign(size_type __n
, _CharT __c
)
848 { return _M_replace_aux(size_type(0), this->size(), __n
, __c
); }
851 * @brief Set value to a range of characters.
852 * @param first Iterator referencing the first character to append.
853 * @param last Iterator marking the end of the range.
854 * @return Reference to this string.
856 * Sets value of string to characters in the range [first,last).
858 template<class _InputIterator
>
860 assign(_InputIterator __first
, _InputIterator __last
)
861 { return this->replace(_M_ibegin(), _M_iend(), __first
, __last
); }
864 * @brief Insert multiple characters.
865 * @param p Iterator referencing location in string to insert at.
866 * @param n Number of characters to insert
867 * @param c The character to insert.
868 * @throw std::length_error If new length exceeds @c max_size().
870 * Inserts @a n copies of character @a c starting at the position
871 * referenced by iterator @a p. If adding characters causes the length
872 * to exceed max_size(), length_error is thrown. The value of the
873 * string doesn't change if an error is thrown.
876 insert(iterator __p
, size_type __n
, _CharT __c
)
877 { this->replace(__p
, __p
, __n
, __c
); }
880 * @brief Insert a range of characters.
881 * @param p Iterator referencing location in string to insert at.
882 * @param beg Start of range.
883 * @param end End of range.
884 * @throw std::length_error If new length exceeds @c max_size().
886 * Inserts characters in range [beg,end). If adding characters causes
887 * the length to exceed max_size(), length_error is thrown. The value
888 * of the string doesn't change if an error is thrown.
890 template<class _InputIterator
>
891 void insert(iterator __p
, _InputIterator __beg
, _InputIterator __end
)
892 { this->replace(__p
, __p
, __beg
, __end
); }
895 * @brief Insert value of a string.
896 * @param pos1 Iterator referencing location in string to insert at.
897 * @param str The string to insert.
898 * @return Reference to this string.
899 * @throw std::length_error If new length exceeds @c max_size().
901 * Inserts value of @a str starting at @a pos1. If adding characters
902 * causes the length to exceed max_size(), length_error is thrown. The
903 * value of the string doesn't change if an error is thrown.
906 insert(size_type __pos1
, const basic_string
& __str
)
907 { return this->insert(__pos1
, __str
, size_type(0), __str
.size()); }
910 * @brief Insert a substring.
911 * @param pos1 Iterator referencing location in string to insert at.
912 * @param str The string to insert.
913 * @param pos2 Start of characters in str to insert.
914 * @param n Number of characters to insert.
915 * @return Reference to this string.
916 * @throw std::length_error If new length exceeds @c max_size().
917 * @throw std::out_of_range If @a pos1 > size() or
918 * @a pos2 > @a str.size().
920 * Starting at @a pos1, insert @a n character of @a str beginning with
921 * @a pos2. If adding characters causes the length to exceed
922 * max_size(), length_error is thrown. If @a pos1 is beyond the end of
923 * this string or @a pos2 is beyond the end of @a str, out_of_range is
924 * thrown. The value of the string doesn't change if an error is
928 insert(size_type __pos1
, const basic_string
& __str
,
929 size_type __pos2
, size_type __n
)
930 { return this->insert(__pos1
, __str
._M_data()
931 + __str
._M_check(__pos2
, "basic_string::insert"),
932 __str
._M_limit(__pos2
, __n
)); }
935 * @brief Insert a C substring.
936 * @param pos Iterator referencing location in string to insert at.
937 * @param s The C string to insert.
938 * @param n The number of characters to insert.
939 * @return Reference to this string.
940 * @throw std::length_error If new length exceeds @c max_size().
941 * @throw std::out_of_range If @a pos is beyond the end of this
944 * Inserts the first @a n characters of @a s starting at @a pos. If
945 * adding characters causes the length to exceed max_size(),
946 * length_error is thrown. If @a pos is beyond end(), out_of_range is
947 * thrown. The value of the string doesn't change if an error is
951 insert(size_type __pos
, const _CharT
* __s
, size_type __n
);
954 * @brief Insert a C string.
955 * @param pos Iterator referencing location in string to insert at.
956 * @param s The C string to insert.
957 * @return Reference to this string.
958 * @throw std::length_error If new length exceeds @c max_size().
959 * @throw std::out_of_range If @a pos is beyond the end of this
962 * Inserts the first @a n characters of @a s starting at @a pos. If
963 * adding characters causes the length to exceed max_size(),
964 * length_error is thrown. If @a pos is beyond end(), out_of_range is
965 * thrown. The value of the string doesn't change if an error is
969 insert(size_type __pos
, const _CharT
* __s
)
971 __glibcxx_requires_string(__s
);
972 return this->insert(__pos
, __s
, traits_type::length(__s
));
976 * @brief Insert multiple characters.
977 * @param pos Index in string to insert at.
978 * @param n Number of characters to insert
979 * @param c The character to insert.
980 * @return Reference to this string.
981 * @throw std::length_error If new length exceeds @c max_size().
982 * @throw std::out_of_range If @a pos is beyond the end of this
985 * Inserts @a n copies of character @a c starting at index @a pos. If
986 * adding characters causes the length to exceed max_size(),
987 * length_error is thrown. If @a pos > length(), out_of_range is
988 * thrown. The value of the string doesn't change if an error is
992 insert(size_type __pos
, size_type __n
, _CharT __c
)
993 { return _M_replace_aux(_M_check(__pos
, "basic_string::insert"),
994 size_type(0), __n
, __c
); }
997 * @brief Insert one character.
998 * @param p Iterator referencing position in string to insert at.
999 * @param c The character to insert.
1000 * @return Iterator referencing newly inserted char.
1001 * @throw std::length_error If new length exceeds @c max_size().
1003 * Inserts character @a c at position referenced by @a p. If adding
1004 * character causes the length to exceed max_size(), length_error is
1005 * thrown. If @a p is beyond end of string, out_of_range is thrown.
1006 * The value of the string doesn't change if an error is thrown.
1009 insert(iterator __p
, _CharT __c
)
1011 _GLIBCXX_DEBUG_PEDASSERT(__p
>= _M_ibegin() && __p
<= _M_iend());
1012 const size_type __pos
= __p
- _M_ibegin();
1013 _M_replace_aux(__pos
, size_type(0), size_type(1), __c
);
1014 _M_rep()->_M_set_leaked();
1015 return this->_M_ibegin() + __pos
;
1019 * @brief Remove characters.
1020 * @param pos Index of first character to remove (default 0).
1021 * @param n Number of characters to remove (default remainder).
1022 * @return Reference to this string.
1023 * @throw std::out_of_range If @a pos is beyond the end of this
1026 * Removes @a n characters from this string starting at @a pos. The
1027 * length of the string is reduced by @a n. If there are < @a n
1028 * characters to remove, the remainder of the string is truncated. If
1029 * @a p is beyond end of string, out_of_range is thrown. The value of
1030 * the string doesn't change if an error is thrown.
1033 erase(size_type __pos
= 0, size_type __n
= npos
)
1034 { return _M_replace_safe(_M_check(__pos
, "basic_string::erase"),
1035 _M_limit(__pos
, __n
), NULL
, size_type(0)); }
1038 * @brief Remove one character.
1039 * @param position Iterator referencing the character to remove.
1040 * @return iterator referencing same location after removal.
1042 * Removes the character at @a position from this string. The value
1043 * of the string doesn't change if an error is thrown.
1046 erase(iterator __position
)
1048 _GLIBCXX_DEBUG_PEDASSERT(__position
>= _M_ibegin()
1049 && __position
< _M_iend());
1050 const size_type __pos
= __position
- _M_ibegin();
1051 _M_replace_safe(__pos
, size_type(1), NULL
, size_type(0));
1052 _M_rep()->_M_set_leaked();
1053 return _M_ibegin() + __pos
;
1057 * @brief Remove a range of characters.
1058 * @param first Iterator referencing the first character to remove.
1059 * @param last Iterator referencing the end of the range.
1060 * @return Iterator referencing location of first after removal.
1062 * Removes the characters in the range [first,last) from this string.
1063 * The value of the string doesn't change if an error is thrown.
1066 erase(iterator __first
, iterator __last
)
1068 _GLIBCXX_DEBUG_PEDASSERT(__first
>= _M_ibegin() && __first
<= __last
1069 && __last
<= _M_iend());
1070 const size_type __pos
= __first
- _M_ibegin();
1071 _M_replace_safe(__pos
, __last
- __first
, NULL
, size_type(0));
1072 _M_rep()->_M_set_leaked();
1073 return _M_ibegin() + __pos
;
1077 * @brief Replace characters with value from another string.
1078 * @param pos Index of first character to replace.
1079 * @param n Number of characters to be replaced.
1080 * @param str String to insert.
1081 * @return Reference to this string.
1082 * @throw std::out_of_range If @a pos is beyond the end of this
1084 * @throw std::length_error If new length exceeds @c max_size().
1086 * Removes the characters in the range [pos,pos+n) from this string.
1087 * In place, the value of @a str is inserted. If @a pos is beyond end
1088 * of string, out_of_range is thrown. If the length of the result
1089 * exceeds max_size(), length_error is thrown. The value of the string
1090 * doesn't change if an error is thrown.
1093 replace(size_type __pos
, size_type __n
, const basic_string
& __str
)
1094 { return this->replace(__pos
, __n
, __str
._M_data(), __str
.size()); }
1097 * @brief Replace characters with value from another string.
1098 * @param pos1 Index of first character to replace.
1099 * @param n1 Number of characters to be replaced.
1100 * @param str String to insert.
1101 * @param pos2 Index of first character of str to use.
1102 * @param n2 Number of characters from str to use.
1103 * @return Reference to this string.
1104 * @throw std::out_of_range If @a pos1 > size() or @a pos2 >
1106 * @throw std::length_error If new length exceeds @c max_size().
1108 * Removes the characters in the range [pos1,pos1 + n) from this
1109 * string. In place, the value of @a str is inserted. If @a pos is
1110 * beyond end of string, out_of_range is thrown. If the length of the
1111 * result exceeds max_size(), length_error is thrown. The value of the
1112 * string doesn't change if an error is thrown.
1115 replace(size_type __pos1
, size_type __n1
, const basic_string
& __str
,
1116 size_type __pos2
, size_type __n2
)
1117 { return this->replace(__pos1
, __n1
, __str
._M_data()
1118 + __str
._M_check(__pos2
, "basic_string::replace"),
1119 __str
._M_limit(__pos2
, __n2
)); }
1122 * @brief Replace characters with value of a C substring.
1123 * @param pos Index of first character to replace.
1124 * @param n1 Number of characters to be replaced.
1125 * @param str C string to insert.
1126 * @param n2 Number of characters from str to use.
1127 * @return Reference to this string.
1128 * @throw std::out_of_range If @a pos1 > size().
1129 * @throw std::length_error If new length exceeds @c max_size().
1131 * Removes the characters in the range [pos,pos + n1) from this string.
1132 * In place, the first @a n2 characters of @a str are inserted, or all
1133 * of @a str if @a n2 is too large. If @a pos is beyond end of string,
1134 * out_of_range is thrown. If the length of result exceeds max_size(),
1135 * length_error is thrown. The value of the string doesn't change if
1136 * an error is thrown.
1139 replace(size_type __pos
, size_type __n1
, const _CharT
* __s
,
1143 * @brief Replace characters with value of a C string.
1144 * @param pos Index of first character to replace.
1145 * @param n1 Number of characters to be replaced.
1146 * @param str C string to insert.
1147 * @return Reference to this string.
1148 * @throw std::out_of_range If @a pos > size().
1149 * @throw std::length_error If new length exceeds @c max_size().
1151 * Removes the characters in the range [pos,pos + n1) from this string.
1152 * In place, the first @a n characters of @a str are inserted. If @a
1153 * pos is beyond end of string, out_of_range is thrown. If the length
1154 * of result exceeds max_size(), length_error is thrown. The value of
1155 * the string doesn't change if an error is thrown.
1158 replace(size_type __pos
, size_type __n1
, const _CharT
* __s
)
1160 __glibcxx_requires_string(__s
);
1161 return this->replace(__pos
, __n1
, __s
, traits_type::length(__s
));
1165 * @brief Replace characters with multiple characters.
1166 * @param pos Index of first character to replace.
1167 * @param n1 Number of characters to be replaced.
1168 * @param n2 Number of characters to insert.
1169 * @param c Character to insert.
1170 * @return Reference to this string.
1171 * @throw std::out_of_range If @a pos > size().
1172 * @throw std::length_error If new length exceeds @c max_size().
1174 * Removes the characters in the range [pos,pos + n1) from this string.
1175 * In place, @a n2 copies of @a c are inserted. If @a pos is beyond
1176 * end of string, out_of_range is thrown. If the length of result
1177 * exceeds max_size(), length_error is thrown. The value of the string
1178 * doesn't change if an error is thrown.
1181 replace(size_type __pos
, size_type __n1
, size_type __n2
, _CharT __c
)
1182 { return _M_replace_aux(_M_check(__pos
, "basic_string::replace"),
1183 _M_limit(__pos
, __n1
), __n2
, __c
); }
1186 * @brief Replace range of characters with string.
1187 * @param i1 Iterator referencing start of range to replace.
1188 * @param i2 Iterator referencing end of range to replace.
1189 * @param str String value to insert.
1190 * @return Reference to this string.
1191 * @throw std::length_error If new length exceeds @c max_size().
1193 * Removes the characters in the range [i1,i2). In place, the value of
1194 * @a str is inserted. If the length of result exceeds max_size(),
1195 * length_error is thrown. The value of the string doesn't change if
1196 * an error is thrown.
1199 replace(iterator __i1
, iterator __i2
, const basic_string
& __str
)
1200 { return this->replace(__i1
, __i2
, __str
._M_data(), __str
.size()); }
1203 * @brief Replace range of characters with C substring.
1204 * @param i1 Iterator referencing start of range to replace.
1205 * @param i2 Iterator referencing end of range to replace.
1206 * @param s C string value to insert.
1207 * @param n Number of characters from s to insert.
1208 * @return Reference to this string.
1209 * @throw std::length_error If new length exceeds @c max_size().
1211 * Removes the characters in the range [i1,i2). In place, the first @a
1212 * n characters of @a s are inserted. If the length of result exceeds
1213 * max_size(), length_error is thrown. The value of the string doesn't
1214 * change if an error is thrown.
1217 replace(iterator __i1
, iterator __i2
, const _CharT
* __s
, size_type __n
)
1219 _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1
&& __i1
<= __i2
1220 && __i2
<= _M_iend());
1221 return this->replace(__i1
- _M_ibegin(), __i2
- __i1
, __s
, __n
);
1225 * @brief Replace range of characters with C string.
1226 * @param i1 Iterator referencing start of range to replace.
1227 * @param i2 Iterator referencing end of range to replace.
1228 * @param s C string value to insert.
1229 * @return Reference to this string.
1230 * @throw std::length_error If new length exceeds @c max_size().
1232 * Removes the characters in the range [i1,i2). In place, the
1233 * characters of @a s are inserted. If the length of result exceeds
1234 * max_size(), length_error is thrown. The value of the string doesn't
1235 * change if an error is thrown.
1238 replace(iterator __i1
, iterator __i2
, const _CharT
* __s
)
1240 __glibcxx_requires_string(__s
);
1241 return this->replace(__i1
, __i2
, __s
, traits_type::length(__s
));
1245 * @brief Replace range of characters with multiple characters
1246 * @param i1 Iterator referencing start of range to replace.
1247 * @param i2 Iterator referencing end of range to replace.
1248 * @param n Number of characters to insert.
1249 * @param c Character to insert.
1250 * @return Reference to this string.
1251 * @throw std::length_error If new length exceeds @c max_size().
1253 * Removes the characters in the range [i1,i2). In place, @a n copies
1254 * of @a c are inserted. If the length of result exceeds max_size(),
1255 * length_error is thrown. The value of the string doesn't change if
1256 * an error is thrown.
1259 replace(iterator __i1
, iterator __i2
, size_type __n
, _CharT __c
)
1261 _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1
&& __i1
<= __i2
1262 && __i2
<= _M_iend());
1263 return _M_replace_aux(__i1
- _M_ibegin(), __i2
- __i1
, __n
, __c
);
1267 * @brief Replace range of characters with range.
1268 * @param i1 Iterator referencing start of range to replace.
1269 * @param i2 Iterator referencing end of range to replace.
1270 * @param k1 Iterator referencing start of range to insert.
1271 * @param k2 Iterator referencing end of range to insert.
1272 * @return Reference to this string.
1273 * @throw std::length_error If new length exceeds @c max_size().
1275 * Removes the characters in the range [i1,i2). In place, characters
1276 * in the range [k1,k2) are inserted. If the length of result exceeds
1277 * max_size(), length_error is thrown. The value of the string doesn't
1278 * change if an error is thrown.
1280 template<class _InputIterator
>
1282 replace(iterator __i1
, iterator __i2
,
1283 _InputIterator __k1
, _InputIterator __k2
)
1285 _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1
&& __i1
<= __i2
1286 && __i2
<= _M_iend());
1287 __glibcxx_requires_valid_range(__k1
, __k2
);
1288 typedef typename _Is_integer
<_InputIterator
>::_Integral _Integral
;
1289 return _M_replace_dispatch(__i1
, __i2
, __k1
, __k2
, _Integral());
1292 // Specializations for the common case of pointer and iterator:
1293 // useful to avoid the overhead of temporary buffering in _M_replace.
1295 replace(iterator __i1
, iterator __i2
, _CharT
* __k1
, _CharT
* __k2
)
1297 _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1
&& __i1
<= __i2
1298 && __i2
<= _M_iend());
1299 __glibcxx_requires_valid_range(__k1
, __k2
);
1300 return this->replace(__i1
- _M_ibegin(), __i2
- __i1
,
1305 replace(iterator __i1
, iterator __i2
,
1306 const _CharT
* __k1
, const _CharT
* __k2
)
1308 _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1
&& __i1
<= __i2
1309 && __i2
<= _M_iend());
1310 __glibcxx_requires_valid_range(__k1
, __k2
);
1311 return this->replace(__i1
- _M_ibegin(), __i2
- __i1
,
1316 replace(iterator __i1
, iterator __i2
, iterator __k1
, iterator __k2
)
1318 _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1
&& __i1
<= __i2
1319 && __i2
<= _M_iend());
1320 __glibcxx_requires_valid_range(__k1
, __k2
);
1321 return this->replace(__i1
- _M_ibegin(), __i2
- __i1
,
1322 __k1
.base(), __k2
- __k1
);
1326 replace(iterator __i1
, iterator __i2
,
1327 const_iterator __k1
, const_iterator __k2
)
1329 _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1
&& __i1
<= __i2
1330 && __i2
<= _M_iend());
1331 __glibcxx_requires_valid_range(__k1
, __k2
);
1332 return this->replace(__i1
- _M_ibegin(), __i2
- __i1
,
1333 __k1
.base(), __k2
- __k1
);
1337 template<class _Integer
>
1339 _M_replace_dispatch(iterator __i1
, iterator __i2
, _Integer __n
,
1340 _Integer __val
, __true_type
)
1341 { return _M_replace_aux(__i1
- _M_ibegin(), __i2
- __i1
, __n
, __val
); }
1343 template<class _InputIterator
>
1345 _M_replace_dispatch(iterator __i1
, iterator __i2
, _InputIterator __k1
,
1346 _InputIterator __k2
, __false_type
);
1349 _M_replace_aux(size_type __pos1
, size_type __n1
, size_type __n2
,
1352 if (this->max_size() - (this->size() - __n1
) < __n2
)
1353 __throw_length_error(__N("basic_string::_M_replace_aux"));
1354 _M_mutate(__pos1
, __n1
, __n2
);
1356 _M_data()[__pos1
] = __c
;
1358 traits_type::assign(_M_data() + __pos1
, __n2
, __c
);
1363 _M_replace_safe(size_type __pos1
, size_type __n1
, const _CharT
* __s
,
1366 _M_mutate(__pos1
, __n1
, __n2
);
1368 _M_data()[__pos1
] = *__s
;
1370 traits_type::copy(_M_data() + __pos1
, __s
, __n2
);
1374 // _S_construct_aux is used to implement the 21.3.1 para 15 which
1375 // requires special behaviour if _InIter is an integral type
1376 template<class _InIterator
>
1378 _S_construct_aux(_InIterator __beg
, _InIterator __end
,
1379 const _Alloc
& __a
, __false_type
)
1381 typedef typename iterator_traits
<_InIterator
>::iterator_category _Tag
;
1382 return _S_construct(__beg
, __end
, __a
, _Tag());
1385 template<class _InIterator
>
1387 _S_construct_aux(_InIterator __beg
, _InIterator __end
,
1388 const _Alloc
& __a
, __true_type
)
1389 { return _S_construct(static_cast<size_type
>(__beg
),
1390 static_cast<value_type
>(__end
), __a
); }
1392 template<class _InIterator
>
1394 _S_construct(_InIterator __beg
, _InIterator __end
, const _Alloc
& __a
)
1396 typedef typename _Is_integer
<_InIterator
>::_Integral _Integral
;
1397 return _S_construct_aux(__beg
, __end
, __a
, _Integral());
1400 // For Input Iterators, used in istreambuf_iterators, etc.
1401 template<class _InIterator
>
1403 _S_construct(_InIterator __beg
, _InIterator __end
, const _Alloc
& __a
,
1404 input_iterator_tag
);
1406 // For forward_iterators up to random_access_iterators, used for
1407 // string::iterator, _CharT*, etc.
1408 template<class _FwdIterator
>
1410 _S_construct(_FwdIterator __beg
, _FwdIterator __end
, const _Alloc
& __a
,
1411 forward_iterator_tag
);
1414 _S_construct(size_type __req
, _CharT __c
, const _Alloc
& __a
);
1419 * @brief Copy substring into C string.
1420 * @param s C string to copy value into.
1421 * @param n Number of characters to copy.
1422 * @param pos Index of first character to copy.
1423 * @return Number of characters actually copied
1424 * @throw std::out_of_range If pos > size().
1426 * Copies up to @a n characters starting at @a pos into the C string @a
1427 * s. If @a pos is greater than size(), out_of_range is thrown.
1430 copy(_CharT
* __s
, size_type __n
, size_type __pos
= 0) const;
1433 * @brief Swap contents with another string.
1434 * @param s String to swap with.
1436 * Exchanges the contents of this string with that of @a s in constant
1440 swap(basic_string
& __s
);
1442 // String operations:
1444 * @brief Return const pointer to null-terminated contents.
1446 * This is a handle to internal data. Do not modify or dire things may
1450 c_str() const { return _M_data(); }
1453 * @brief Return const pointer to contents.
1455 * This is a handle to internal data. Do not modify or dire things may
1459 data() const { return _M_data(); }
1462 * @brief Return copy of allocator used to construct this string.
1465 get_allocator() const { return _M_dataplus
; }
1468 * @brief Find position of a C substring.
1469 * @param s C string to locate.
1470 * @param pos Index of character to search from.
1471 * @param n Number of characters from @a s to search for.
1472 * @return Index of start of first occurrence.
1474 * Starting from @a pos, searches forward for the first @a n characters
1475 * in @a s within this string. If found, returns the index where it
1476 * begins. If not found, returns npos.
1479 find(const _CharT
* __s
, size_type __pos
, size_type __n
) const;
1482 * @brief Find position of a string.
1483 * @param str String to locate.
1484 * @param pos Index of character to search from (default 0).
1485 * @return Index of start of first occurrence.
1487 * Starting from @a pos, searches forward for value of @a str within
1488 * this string. If found, returns the index where it begins. If not
1489 * found, returns npos.
1492 find(const basic_string
& __str
, size_type __pos
= 0) const
1493 { return this->find(__str
.data(), __pos
, __str
.size()); }
1496 * @brief Find position of a C string.
1497 * @param s C string to locate.
1498 * @param pos Index of character to search from (default 0).
1499 * @return Index of start of first occurrence.
1501 * Starting from @a pos, searches forward for the value of @a s within
1502 * this string. If found, returns the index where it begins. If not
1503 * found, returns npos.
1506 find(const _CharT
* __s
, size_type __pos
= 0) const
1508 __glibcxx_requires_string(__s
);
1509 return this->find(__s
, __pos
, traits_type::length(__s
));
1513 * @brief Find position of a character.
1514 * @param c Character to locate.
1515 * @param pos Index of character to search from (default 0).
1516 * @return Index of first occurrence.
1518 * Starting from @a pos, searches forward for @a c within this string.
1519 * If found, returns the index where it was found. If not found,
1523 find(_CharT __c
, size_type __pos
= 0) const;
1526 * @brief Find last position of a string.
1527 * @param str String to locate.
1528 * @param pos Index of character to search back from (default end).
1529 * @return Index of start of last occurrence.
1531 * Starting from @a pos, searches backward for value of @a str within
1532 * this string. If found, returns the index where it begins. If not
1533 * found, returns npos.
1536 rfind(const basic_string
& __str
, size_type __pos
= npos
) const
1537 { return this->rfind(__str
.data(), __pos
, __str
.size()); }
1540 * @brief Find last position of a C substring.
1541 * @param s C string to locate.
1542 * @param pos Index of character to search back from.
1543 * @param n Number of characters from s to search for.
1544 * @return Index of start of last occurrence.
1546 * Starting from @a pos, searches backward for the first @a n
1547 * characters in @a s within this string. If found, returns the index
1548 * where it begins. If not found, returns npos.
1551 rfind(const _CharT
* __s
, size_type __pos
, size_type __n
) const;
1554 * @brief Find last position of a C string.
1555 * @param s C string to locate.
1556 * @param pos Index of character to start search at (default 0).
1557 * @return Index of start of last occurrence.
1559 * Starting from @a pos, searches backward for the value of @a s within
1560 * this string. If found, returns the index where it begins. If not
1561 * found, returns npos.
1564 rfind(const _CharT
* __s
, size_type __pos
= npos
) const
1566 __glibcxx_requires_string(__s
);
1567 return this->rfind(__s
, __pos
, traits_type::length(__s
));
1571 * @brief Find last position of a character.
1572 * @param c Character to locate.
1573 * @param pos Index of character to search back from (default 0).
1574 * @return Index of last occurrence.
1576 * Starting from @a pos, searches backward for @a c within this string.
1577 * If found, returns the index where it was found. If not found,
1581 rfind(_CharT __c
, size_type __pos
= npos
) const;
1584 * @brief Find position of a character of string.
1585 * @param str String containing characters to locate.
1586 * @param pos Index of character to search from (default 0).
1587 * @return Index of first occurrence.
1589 * Starting from @a pos, searches forward for one of the characters of
1590 * @a str within this string. If found, returns the index where it was
1591 * found. If not found, returns npos.
1594 find_first_of(const basic_string
& __str
, size_type __pos
= 0) const
1595 { return this->find_first_of(__str
.data(), __pos
, __str
.size()); }
1598 * @brief Find position of a character of C substring.
1599 * @param s String containing characters to locate.
1600 * @param pos Index of character to search from (default 0).
1601 * @param n Number of characters from s to search for.
1602 * @return Index of first occurrence.
1604 * Starting from @a pos, searches forward for one of the first @a n
1605 * characters of @a s within this string. If found, returns the index
1606 * where it was found. If not found, returns npos.
1609 find_first_of(const _CharT
* __s
, size_type __pos
, size_type __n
) const;
1612 * @brief Find position of a character of C string.
1613 * @param s String containing characters to locate.
1614 * @param pos Index of character to search from (default 0).
1615 * @return Index of first occurrence.
1617 * Starting from @a pos, searches forward for one of the characters of
1618 * @a s within this string. If found, returns the index where it was
1619 * found. If not found, returns npos.
1622 find_first_of(const _CharT
* __s
, size_type __pos
= 0) const
1624 __glibcxx_requires_string(__s
);
1625 return this->find_first_of(__s
, __pos
, traits_type::length(__s
));
1629 * @brief Find position of a character.
1630 * @param c Character to locate.
1631 * @param pos Index of character to search from (default 0).
1632 * @return Index of first occurrence.
1634 * Starting from @a pos, searches forward for the character @a c within
1635 * this string. If found, returns the index where it was found. If
1636 * not found, returns npos.
1638 * Note: equivalent to find(c, pos).
1641 find_first_of(_CharT __c
, size_type __pos
= 0) const
1642 { return this->find(__c
, __pos
); }
1645 * @brief Find last position of a character of string.
1646 * @param str String containing characters to locate.
1647 * @param pos Index of character to search back from (default end).
1648 * @return Index of last occurrence.
1650 * Starting from @a pos, searches backward for one of the characters of
1651 * @a str within this string. If found, returns the index where it was
1652 * found. If not found, returns npos.
1655 find_last_of(const basic_string
& __str
, size_type __pos
= npos
) const
1656 { return this->find_last_of(__str
.data(), __pos
, __str
.size()); }
1659 * @brief Find last position of a character of C substring.
1660 * @param s C string containing characters to locate.
1661 * @param pos Index of character to search back from (default end).
1662 * @param n Number of characters from s to search for.
1663 * @return Index of last occurrence.
1665 * Starting from @a pos, searches backward for one of the first @a n
1666 * characters of @a s within this string. If found, returns the index
1667 * where it was found. If not found, returns npos.
1670 find_last_of(const _CharT
* __s
, size_type __pos
, size_type __n
) const;
1673 * @brief Find last position of a character of C string.
1674 * @param s C string containing characters to locate.
1675 * @param pos Index of character to search back from (default end).
1676 * @return Index of last occurrence.
1678 * Starting from @a pos, searches backward for one of the characters of
1679 * @a s within this string. If found, returns the index where it was
1680 * found. If not found, returns npos.
1683 find_last_of(const _CharT
* __s
, size_type __pos
= npos
) const
1685 __glibcxx_requires_string(__s
);
1686 return this->find_last_of(__s
, __pos
, traits_type::length(__s
));
1690 * @brief Find last position of a character.
1691 * @param c Character to locate.
1692 * @param pos Index of character to search back from (default 0).
1693 * @return Index of last occurrence.
1695 * Starting from @a pos, searches backward for @a c within this string.
1696 * If found, returns the index where it was found. If not found,
1699 * Note: equivalent to rfind(c, pos).
1702 find_last_of(_CharT __c
, size_type __pos
= npos
) const
1703 { return this->rfind(__c
, __pos
); }
1706 * @brief Find position of a character not in string.
1707 * @param str String containing characters to avoid.
1708 * @param pos Index of character to search from (default 0).
1709 * @return Index of first occurrence.
1711 * Starting from @a pos, searches forward for a character not contained
1712 * in @a str within this string. If found, returns the index where it
1713 * was found. If not found, returns npos.
1716 find_first_not_of(const basic_string
& __str
, size_type __pos
= 0) const
1717 { return this->find_first_not_of(__str
.data(), __pos
, __str
.size()); }
1720 * @brief Find position of a character not in C substring.
1721 * @param s C string containing characters to avoid.
1722 * @param pos Index of character to search from (default 0).
1723 * @param n Number of characters from s to consider.
1724 * @return Index of first occurrence.
1726 * Starting from @a pos, searches forward for a character not contained
1727 * in the first @a n characters of @a s within this string. If found,
1728 * returns the index where it was found. If not found, returns npos.
1731 find_first_not_of(const _CharT
* __s
, size_type __pos
,
1732 size_type __n
) const;
1735 * @brief Find position of a character not in C string.
1736 * @param s C string containing characters to avoid.
1737 * @param pos Index of character to search from (default 0).
1738 * @return Index of first occurrence.
1740 * Starting from @a pos, searches forward for a character not contained
1741 * in @a s within this string. If found, returns the index where it
1742 * was found. If not found, returns npos.
1745 find_first_not_of(const _CharT
* __s
, size_type __pos
= 0) const
1747 __glibcxx_requires_string(__s
);
1748 return this->find_first_not_of(__s
, __pos
, traits_type::length(__s
));
1752 * @brief Find position of a different character.
1753 * @param c Character to avoid.
1754 * @param pos Index of character to search from (default 0).
1755 * @return Index of first occurrence.
1757 * Starting from @a pos, searches forward for a character other than @a c
1758 * within this string. If found, returns the index where it was found.
1759 * If not found, returns npos.
1762 find_first_not_of(_CharT __c
, size_type __pos
= 0) const;
1765 * @brief Find last position of a character not in string.
1766 * @param str String containing characters to avoid.
1767 * @param pos Index of character to search from (default 0).
1768 * @return Index of first occurrence.
1770 * Starting from @a pos, searches backward for a character not
1771 * contained in @a str within this string. If found, returns the index
1772 * where it was found. If not found, returns npos.
1775 find_last_not_of(const basic_string
& __str
, size_type __pos
= npos
) const
1776 { return this->find_last_not_of(__str
.data(), __pos
, __str
.size()); }
1779 * @brief Find last position of a character not in C substring.
1780 * @param s C string containing characters to avoid.
1781 * @param pos Index of character to search from (default 0).
1782 * @param n Number of characters from s to consider.
1783 * @return Index of first occurrence.
1785 * Starting from @a pos, searches backward for a character not
1786 * contained in the first @a n characters of @a s within this string.
1787 * If found, returns the index where it was found. If not found,
1791 find_last_not_of(const _CharT
* __s
, size_type __pos
,
1792 size_type __n
) const;
1794 * @brief Find position of a character not in C string.
1795 * @param s C string containing characters to avoid.
1796 * @param pos Index of character to search from (default 0).
1797 * @return Index of first occurrence.
1799 * Starting from @a pos, searches backward for a character not
1800 * contained in @a s within this string. If found, returns the index
1801 * where it was found. If not found, returns npos.
1804 find_last_not_of(const _CharT
* __s
, size_type __pos
= npos
) const
1806 __glibcxx_requires_string(__s
);
1807 return this->find_last_not_of(__s
, __pos
, traits_type::length(__s
));
1811 * @brief Find last position of a different character.
1812 * @param c Character to avoid.
1813 * @param pos Index of character to search from (default 0).
1814 * @return Index of first occurrence.
1816 * Starting from @a pos, searches backward for a character other than
1817 * @a c within this string. If found, returns the index where it was
1818 * found. If not found, returns npos.
1821 find_last_not_of(_CharT __c
, size_type __pos
= npos
) const;
1824 * @brief Get a substring.
1825 * @param pos Index of first character (default 0).
1826 * @param n Number of characters in substring (default remainder).
1827 * @return The new string.
1828 * @throw std::out_of_range If pos > size().
1830 * Construct and return a new string using the @a n characters starting
1831 * at @a pos. If the string is too short, use the remainder of the
1832 * characters. If @a pos is beyond the end of the string, out_of_range
1836 substr(size_type __pos
= 0, size_type __n
= npos
) const
1837 { return basic_string(*this,
1838 _M_check(__pos
, "basic_string::substr"), __n
); }
1841 * @brief Compare to a string.
1842 * @param str String to compare against.
1843 * @return Integer < 0, 0, or > 0.
1845 * Returns an integer < 0 if this string is ordered before @a str, 0 if
1846 * their values are equivalent, or > 0 if this string is ordered after
1847 * @a str. If the lengths of @a str and this string are different, the
1848 * shorter one is ordered first. If they are the same, returns the
1849 * result of traits::compare(data(),str.data(),size());
1852 compare(const basic_string
& __str
) const
1854 const size_type __size
= this->size();
1855 const size_type __osize
= __str
.size();
1856 const size_type __len
= std::min(__size
, __osize
);
1858 int __r
= traits_type::compare(_M_data(), __str
.data(), __len
);
1860 __r
= __size
- __osize
;
1865 * @brief Compare substring to a string.
1866 * @param pos Index of first character of substring.
1867 * @param n Number of characters in substring.
1868 * @param str String to compare against.
1869 * @return Integer < 0, 0, or > 0.
1871 * Form the substring of this string from the @a n characters starting
1872 * at @a pos. Returns an integer < 0 if the substring is ordered
1873 * before @a str, 0 if their values are equivalent, or > 0 if the
1874 * substring is ordered after @a str. If the lengths @a of str and the
1875 * substring are different, the shorter one is ordered first. If they
1876 * are the same, returns the result of
1877 * traits::compare(substring.data(),str.data(),size());
1880 compare(size_type __pos
, size_type __n
, const basic_string
& __str
) const;
1883 * @brief Compare substring to a substring.
1884 * @param pos1 Index of first character of substring.
1885 * @param n1 Number of characters in substring.
1886 * @param str String to compare against.
1887 * @param pos2 Index of first character of substring of str.
1888 * @param n2 Number of characters in substring of str.
1889 * @return Integer < 0, 0, or > 0.
1891 * Form the substring of this string from the @a n1 characters starting
1892 * at @a pos1. Form the substring of @a str from the @a n2 characters
1893 * starting at @a pos2. Returns an integer < 0 if this substring is
1894 * ordered before the substring of @a str, 0 if their values are
1895 * equivalent, or > 0 if this substring is ordered after the substring
1896 * of @a str. If the lengths of the substring of @a str and this
1897 * substring are different, the shorter one is ordered first. If they
1898 * are the same, returns the result of
1899 * traits::compare(substring.data(),str.substr(pos2,n2).data(),size());
1902 compare(size_type __pos1
, size_type __n1
, const basic_string
& __str
,
1903 size_type __pos2
, size_type __n2
) const;
1906 * @brief Compare to a C string.
1907 * @param s C string to compare against.
1908 * @return Integer < 0, 0, or > 0.
1910 * Returns an integer < 0 if this string is ordered before @a s, 0 if
1911 * their values are equivalent, or > 0 if this string is ordered after
1912 * @a s. If the lengths of @a s and this string are different, the
1913 * shorter one is ordered first. If they are the same, returns the
1914 * result of traits::compare(data(),s,size());
1917 compare(const _CharT
* __s
) const;
1919 // _GLIBCXX_RESOLVE_LIB_DEFECTS
1920 // 5 String::compare specification questionable
1922 * @brief Compare substring to a C string.
1923 * @param pos Index of first character of substring.
1924 * @param n1 Number of characters in substring.
1925 * @param s C string to compare against.
1926 * @return Integer < 0, 0, or > 0.
1928 * Form the substring of this string from the @a n1 characters starting
1929 * at @a pos. Returns an integer < 0 if the substring is ordered
1930 * before @a s, 0 if their values are equivalent, or > 0 if the
1931 * substring is ordered after @a s. If the lengths of @a s and the
1932 * substring are different, the shorter one is ordered first. If they
1933 * are the same, returns the result of
1934 * traits::compare(substring.data(),s,size());
1937 compare(size_type __pos
, size_type __n1
, const _CharT
* __s
) const;
1940 * @brief Compare substring against a character array.
1941 * @param pos1 Index of first character of substring.
1942 * @param n1 Number of characters in substring.
1943 * @param s character array to compare against.
1944 * @param n2 Number of characters of s.
1945 * @return Integer < 0, 0, or > 0.
1947 * Form the substring of this string from the @a n1 characters starting
1948 * at @a pos1. Form a string from the first @a n2 characters of @a s.
1949 * Returns an integer < 0 if this substring is ordered before the string
1950 * from @a s, 0 if their values are equivalent, or > 0 if this substring
1951 * is ordered after the string from @a s. If the lengths of this
1952 * substring and @a n2 are different, the shorter one is ordered first.
1953 * If they are the same, returns the result of
1954 * traits::compare(substring.data(),s,size());
1956 * NB: s must have at least n2 characters, '\0' has no special
1960 compare(size_type __pos
, size_type __n1
, const _CharT
* __s
,
1961 size_type __n2
) const;
1964 template<typename _CharT
, typename _Traits
, typename _Alloc
>
1965 inline basic_string
<_CharT
, _Traits
, _Alloc
>::
1967 #ifndef _GLIBCXX_FULLY_DYNAMIC_STRING
1968 : _M_dataplus(_S_empty_rep()._M_refdata(), _Alloc()) { }
1970 : _M_dataplus(_S_construct(size_type(), _CharT(), _Alloc()), _Alloc()) { }
1975 * @brief Concatenate two strings.
1976 * @param lhs First string.
1977 * @param rhs Last string.
1978 * @return New string with value of @a lhs followed by @a rhs.
1980 template<typename _CharT
, typename _Traits
, typename _Alloc
>
1981 basic_string
<_CharT
, _Traits
, _Alloc
>
1982 operator+(const basic_string
<_CharT
, _Traits
, _Alloc
>& __lhs
,
1983 const basic_string
<_CharT
, _Traits
, _Alloc
>& __rhs
)
1985 basic_string
<_CharT
, _Traits
, _Alloc
> __str(__lhs
);
1986 __str
.append(__rhs
);
1991 * @brief Concatenate C string and string.
1992 * @param lhs First string.
1993 * @param rhs Last string.
1994 * @return New string with value of @a lhs followed by @a rhs.
1996 template<typename _CharT
, typename _Traits
, typename _Alloc
>
1997 basic_string
<_CharT
,_Traits
,_Alloc
>
1998 operator+(const _CharT
* __lhs
,
1999 const basic_string
<_CharT
,_Traits
,_Alloc
>& __rhs
);
2002 * @brief Concatenate character and string.
2003 * @param lhs First string.
2004 * @param rhs Last string.
2005 * @return New string with @a lhs followed by @a rhs.
2007 template<typename _CharT
, typename _Traits
, typename _Alloc
>
2008 basic_string
<_CharT
,_Traits
,_Alloc
>
2009 operator+(_CharT __lhs
, const basic_string
<_CharT
,_Traits
,_Alloc
>& __rhs
);
2012 * @brief Concatenate string and C string.
2013 * @param lhs First string.
2014 * @param rhs Last string.
2015 * @return New string with @a lhs followed by @a rhs.
2017 template<typename _CharT
, typename _Traits
, typename _Alloc
>
2018 inline basic_string
<_CharT
, _Traits
, _Alloc
>
2019 operator+(const basic_string
<_CharT
, _Traits
, _Alloc
>& __lhs
,
2020 const _CharT
* __rhs
)
2022 basic_string
<_CharT
, _Traits
, _Alloc
> __str(__lhs
);
2023 __str
.append(__rhs
);
2028 * @brief Concatenate string and character.
2029 * @param lhs First string.
2030 * @param rhs Last string.
2031 * @return New string with @a lhs followed by @a rhs.
2033 template<typename _CharT
, typename _Traits
, typename _Alloc
>
2034 inline basic_string
<_CharT
, _Traits
, _Alloc
>
2035 operator+(const basic_string
<_CharT
, _Traits
, _Alloc
>& __lhs
, _CharT __rhs
)
2037 typedef basic_string
<_CharT
, _Traits
, _Alloc
> __string_type
;
2038 typedef typename
__string_type::size_type __size_type
;
2039 __string_type
__str(__lhs
);
2040 __str
.append(__size_type(1), __rhs
);
2046 * @brief Test equivalence of two strings.
2047 * @param lhs First string.
2048 * @param rhs Second string.
2049 * @return True if @a lhs.compare(@a rhs) == 0. False otherwise.
2051 template<typename _CharT
, typename _Traits
, typename _Alloc
>
2053 operator==(const basic_string
<_CharT
, _Traits
, _Alloc
>& __lhs
,
2054 const basic_string
<_CharT
, _Traits
, _Alloc
>& __rhs
)
2055 { return __lhs
.compare(__rhs
) == 0; }
2058 * @brief Test equivalence of C string and string.
2059 * @param lhs C string.
2060 * @param rhs String.
2061 * @return True if @a rhs.compare(@a lhs) == 0. False otherwise.
2063 template<typename _CharT
, typename _Traits
, typename _Alloc
>
2065 operator==(const _CharT
* __lhs
,
2066 const basic_string
<_CharT
, _Traits
, _Alloc
>& __rhs
)
2067 { return __rhs
.compare(__lhs
) == 0; }
2070 * @brief Test equivalence of string and C string.
2071 * @param lhs String.
2072 * @param rhs C string.
2073 * @return True if @a lhs.compare(@a rhs) == 0. False otherwise.
2075 template<typename _CharT
, typename _Traits
, typename _Alloc
>
2077 operator==(const basic_string
<_CharT
, _Traits
, _Alloc
>& __lhs
,
2078 const _CharT
* __rhs
)
2079 { return __lhs
.compare(__rhs
) == 0; }
2083 * @brief Test difference of two strings.
2084 * @param lhs First string.
2085 * @param rhs Second string.
2086 * @return True if @a lhs.compare(@a rhs) != 0. False otherwise.
2088 template<typename _CharT
, typename _Traits
, typename _Alloc
>
2090 operator!=(const basic_string
<_CharT
, _Traits
, _Alloc
>& __lhs
,
2091 const basic_string
<_CharT
, _Traits
, _Alloc
>& __rhs
)
2092 { return __rhs
.compare(__lhs
) != 0; }
2095 * @brief Test difference of C string and string.
2096 * @param lhs C string.
2097 * @param rhs String.
2098 * @return True if @a rhs.compare(@a lhs) != 0. False otherwise.
2100 template<typename _CharT
, typename _Traits
, typename _Alloc
>
2102 operator!=(const _CharT
* __lhs
,
2103 const basic_string
<_CharT
, _Traits
, _Alloc
>& __rhs
)
2104 { return __rhs
.compare(__lhs
) != 0; }
2107 * @brief Test difference of string and C string.
2108 * @param lhs String.
2109 * @param rhs C string.
2110 * @return True if @a lhs.compare(@a rhs) != 0. False otherwise.
2112 template<typename _CharT
, typename _Traits
, typename _Alloc
>
2114 operator!=(const basic_string
<_CharT
, _Traits
, _Alloc
>& __lhs
,
2115 const _CharT
* __rhs
)
2116 { return __lhs
.compare(__rhs
) != 0; }
2120 * @brief Test if string precedes string.
2121 * @param lhs First string.
2122 * @param rhs Second string.
2123 * @return True if @a lhs precedes @a rhs. False otherwise.
2125 template<typename _CharT
, typename _Traits
, typename _Alloc
>
2127 operator<(const basic_string
<_CharT
, _Traits
, _Alloc
>& __lhs
,
2128 const basic_string
<_CharT
, _Traits
, _Alloc
>& __rhs
)
2129 { return __lhs
.compare(__rhs
) < 0; }
2132 * @brief Test if string precedes C string.
2133 * @param lhs String.
2134 * @param rhs C string.
2135 * @return True if @a lhs precedes @a rhs. False otherwise.
2137 template<typename _CharT
, typename _Traits
, typename _Alloc
>
2139 operator<(const basic_string
<_CharT
, _Traits
, _Alloc
>& __lhs
,
2140 const _CharT
* __rhs
)
2141 { return __lhs
.compare(__rhs
) < 0; }
2144 * @brief Test if C string precedes string.
2145 * @param lhs C string.
2146 * @param rhs String.
2147 * @return True if @a lhs precedes @a rhs. False otherwise.
2149 template<typename _CharT
, typename _Traits
, typename _Alloc
>
2151 operator<(const _CharT
* __lhs
,
2152 const basic_string
<_CharT
, _Traits
, _Alloc
>& __rhs
)
2153 { return __rhs
.compare(__lhs
) > 0; }
2157 * @brief Test if string follows string.
2158 * @param lhs First string.
2159 * @param rhs Second string.
2160 * @return True if @a lhs follows @a rhs. False otherwise.
2162 template<typename _CharT
, typename _Traits
, typename _Alloc
>
2164 operator>(const basic_string
<_CharT
, _Traits
, _Alloc
>& __lhs
,
2165 const basic_string
<_CharT
, _Traits
, _Alloc
>& __rhs
)
2166 { return __lhs
.compare(__rhs
) > 0; }
2169 * @brief Test if string follows C string.
2170 * @param lhs String.
2171 * @param rhs C string.
2172 * @return True if @a lhs follows @a rhs. False otherwise.
2174 template<typename _CharT
, typename _Traits
, typename _Alloc
>
2176 operator>(const basic_string
<_CharT
, _Traits
, _Alloc
>& __lhs
,
2177 const _CharT
* __rhs
)
2178 { return __lhs
.compare(__rhs
) > 0; }
2181 * @brief Test if C string follows string.
2182 * @param lhs C string.
2183 * @param rhs String.
2184 * @return True if @a lhs follows @a rhs. False otherwise.
2186 template<typename _CharT
, typename _Traits
, typename _Alloc
>
2188 operator>(const _CharT
* __lhs
,
2189 const basic_string
<_CharT
, _Traits
, _Alloc
>& __rhs
)
2190 { return __rhs
.compare(__lhs
) < 0; }
2194 * @brief Test if string doesn't follow string.
2195 * @param lhs First string.
2196 * @param rhs Second string.
2197 * @return True if @a lhs doesn't follow @a rhs. False otherwise.
2199 template<typename _CharT
, typename _Traits
, typename _Alloc
>
2201 operator<=(const basic_string
<_CharT
, _Traits
, _Alloc
>& __lhs
,
2202 const basic_string
<_CharT
, _Traits
, _Alloc
>& __rhs
)
2203 { return __lhs
.compare(__rhs
) <= 0; }
2206 * @brief Test if string doesn't follow C string.
2207 * @param lhs String.
2208 * @param rhs C string.
2209 * @return True if @a lhs doesn't follow @a rhs. False otherwise.
2211 template<typename _CharT
, typename _Traits
, typename _Alloc
>
2213 operator<=(const basic_string
<_CharT
, _Traits
, _Alloc
>& __lhs
,
2214 const _CharT
* __rhs
)
2215 { return __lhs
.compare(__rhs
) <= 0; }
2218 * @brief Test if C string doesn't follow string.
2219 * @param lhs C string.
2220 * @param rhs String.
2221 * @return True if @a lhs doesn't follow @a rhs. False otherwise.
2223 template<typename _CharT
, typename _Traits
, typename _Alloc
>
2225 operator<=(const _CharT
* __lhs
,
2226 const basic_string
<_CharT
, _Traits
, _Alloc
>& __rhs
)
2227 { return __rhs
.compare(__lhs
) >= 0; }
2231 * @brief Test if string doesn't precede string.
2232 * @param lhs First string.
2233 * @param rhs Second string.
2234 * @return True if @a lhs doesn't precede @a rhs. False otherwise.
2236 template<typename _CharT
, typename _Traits
, typename _Alloc
>
2238 operator>=(const basic_string
<_CharT
, _Traits
, _Alloc
>& __lhs
,
2239 const basic_string
<_CharT
, _Traits
, _Alloc
>& __rhs
)
2240 { return __lhs
.compare(__rhs
) >= 0; }
2243 * @brief Test if string doesn't precede C string.
2244 * @param lhs String.
2245 * @param rhs C string.
2246 * @return True if @a lhs doesn't precede @a rhs. False otherwise.
2248 template<typename _CharT
, typename _Traits
, typename _Alloc
>
2250 operator>=(const basic_string
<_CharT
, _Traits
, _Alloc
>& __lhs
,
2251 const _CharT
* __rhs
)
2252 { return __lhs
.compare(__rhs
) >= 0; }
2255 * @brief Test if C string doesn't precede string.
2256 * @param lhs C string.
2257 * @param rhs String.
2258 * @return True if @a lhs doesn't precede @a rhs. False otherwise.
2260 template<typename _CharT
, typename _Traits
, typename _Alloc
>
2262 operator>=(const _CharT
* __lhs
,
2263 const basic_string
<_CharT
, _Traits
, _Alloc
>& __rhs
)
2264 { return __rhs
.compare(__lhs
) <= 0; }
2267 * @brief Swap contents of two strings.
2268 * @param lhs First string.
2269 * @param rhs Second string.
2271 * Exchanges the contents of @a lhs and @a rhs in constant time.
2273 template<typename _CharT
, typename _Traits
, typename _Alloc
>
2275 swap(basic_string
<_CharT
, _Traits
, _Alloc
>& __lhs
,
2276 basic_string
<_CharT
, _Traits
, _Alloc
>& __rhs
)
2277 { __lhs
.swap(__rhs
); }
2280 * @brief Read stream into a string.
2281 * @param is Input stream.
2282 * @param str Buffer to store into.
2283 * @return Reference to the input stream.
2285 * Stores characters from @a is into @a str until whitespace is found, the
2286 * end of the stream is encountered, or str.max_size() is reached. If
2287 * is.width() is non-zero, that is the limit on the number of characters
2288 * stored into @a str. Any previous contents of @a str are erased.
2290 template<typename _CharT
, typename _Traits
, typename _Alloc
>
2291 basic_istream
<_CharT
, _Traits
>&
2292 operator>>(basic_istream
<_CharT
, _Traits
>& __is
,
2293 basic_string
<_CharT
, _Traits
, _Alloc
>& __str
);
2296 * @brief Write string to a stream.
2297 * @param os Output stream.
2298 * @param str String to write out.
2299 * @return Reference to the output stream.
2301 * Output characters of @a str into os following the same rules as for
2302 * writing a C string.
2304 template<typename _CharT
, typename _Traits
, typename _Alloc
>
2305 basic_ostream
<_CharT
, _Traits
>&
2306 operator<<(basic_ostream
<_CharT
, _Traits
>& __os
,
2307 const basic_string
<_CharT
, _Traits
, _Alloc
>& __str
);
2310 * @brief Read a line from stream into a string.
2311 * @param is Input stream.
2312 * @param str Buffer to store into.
2313 * @param delim Character marking end of line.
2314 * @return Reference to the input stream.
2316 * Stores characters from @a is into @a str until @a delim is found, the
2317 * end of the stream is encountered, or str.max_size() is reached. If
2318 * is.width() is non-zero, that is the limit on the number of characters
2319 * stored into @a str. Any previous contents of @a str are erased. If @a
2320 * delim was encountered, it is extracted but not stored into @a str.
2322 template<typename _CharT
, typename _Traits
, typename _Alloc
>
2323 basic_istream
<_CharT
,_Traits
>&
2324 getline(basic_istream
<_CharT
, _Traits
>& __is
,
2325 basic_string
<_CharT
, _Traits
, _Alloc
>& __str
, _CharT __delim
);
2328 * @brief Read a line from stream into a string.
2329 * @param is Input stream.
2330 * @param str Buffer to store into.
2331 * @return Reference to the input stream.
2333 * Stores characters from is into @a str until '\n' is found, the end of
2334 * the stream is encountered, or str.max_size() is reached. If is.width()
2335 * is non-zero, that is the limit on the number of characters stored into
2336 * @a str. Any previous contents of @a str are erased. If end of line was
2337 * encountered, it is extracted but not stored into @a str.
2339 template<typename _CharT
, typename _Traits
, typename _Alloc
>
2340 inline basic_istream
<_CharT
,_Traits
>&
2341 getline(basic_istream
<_CharT
, _Traits
>& __is
,
2342 basic_string
<_CharT
, _Traits
, _Alloc
>& __str
);
2345 #endif /* _BASIC_STRING_H */