1// Components for manipulating sequences of characters -*- C++ -*-
2
3// Copyright (C) 1997-2018 Free Software Foundation, Inc.
4//
5// This file is part of the GNU ISO C++ Library. This library is free
6// software; you can redistribute it and/or modify it under the
7// terms of the GNU General Public License as published by the
8// Free Software Foundation; either version 3, or (at your option)
9// any later version.
10
11// This library is distributed in the hope that it will be useful,
12// but WITHOUT ANY WARRANTY; without even the implied warranty of
13// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14// GNU General Public License for more details.
15
16// Under Section 7 of GPL version 3, you are granted additional
17// permissions described in the GCC Runtime Library Exception, version
18// 3.1, as published by the Free Software Foundation.
19
20// You should have received a copy of the GNU General Public License and
21// a copy of the GCC Runtime Library Exception along with this program;
22// see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
23// <http://www.gnu.org/licenses/>.
24
25/** @file bits/basic_string.h
26 * This is an internal header file, included by other library headers.
27 * Do not attempt to use it directly. @headername{string}
28 */
29
30//
31// ISO C++ 14882: 21 Strings library
32//
33
34#ifndef _BASIC_STRING_H
35#define _BASIC_STRING_H 1
36
37#pragma GCC system_header
38
39#include <ext/atomicity.h>
40#include <ext/alloc_traits.h>
41#include <debug/debug.h>
42
43#if __cplusplus >= 201103L
44#include <initializer_list>
45#endif
46
47#if __cplusplus > 201402L
48# include <string_view>
49#endif
50
51
52namespace std _GLIBCXX_VISIBILITY(default)
53{
54_GLIBCXX_BEGIN_NAMESPACE_VERSION
55
56#if _GLIBCXX_USE_CXX11_ABI
57_GLIBCXX_BEGIN_NAMESPACE_CXX11
58 /**
59 * @class basic_string basic_string.h <string>
60 * @brief Managing sequences of characters and character-like objects.
61 *
62 * @ingroup strings
63 * @ingroup sequences
64 *
65 * @tparam _CharT Type of character
66 * @tparam _Traits Traits for character type, defaults to
67 * char_traits<_CharT>.
68 * @tparam _Alloc Allocator type, defaults to allocator<_CharT>.
69 *
70 * Meets the requirements of a <a href="tables.html#65">container</a>, a
71 * <a href="tables.html#66">reversible container</a>, and a
72 * <a href="tables.html#67">sequence</a>. Of the
73 * <a href="tables.html#68">optional sequence requirements</a>, only
74 * @c push_back, @c at, and @c %array access are supported.
75 */
76 template<typename _CharT, typename _Traits, typename _Alloc>
77 class basic_string
78 {
79 typedef typename __gnu_cxx::__alloc_traits<_Alloc>::template
80 rebind<_CharT>::other _Char_alloc_type;
81 typedef __gnu_cxx::__alloc_traits<_Char_alloc_type> _Alloc_traits;
82
83 // Types:
84 public:
85 typedef _Traits traits_type;
86 typedef typename _Traits::char_type value_type;
87 typedef _Char_alloc_type allocator_type;
88 typedef typename _Alloc_traits::size_type size_type;
89 typedef typename _Alloc_traits::difference_type difference_type;
90 typedef typename _Alloc_traits::reference reference;
91 typedef typename _Alloc_traits::const_reference const_reference;
92 typedef typename _Alloc_traits::pointer pointer;
93 typedef typename _Alloc_traits::const_pointer const_pointer;
94 typedef __gnu_cxx::__normal_iterator<pointer, basic_string> iterator;
95 typedef __gnu_cxx::__normal_iterator<const_pointer, basic_string>
96 const_iterator;
97 typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
98 typedef std::reverse_iterator<iterator> reverse_iterator;
99
100 /// Value returned by various member functions when they fail.
101 static const size_type npos = static_cast<size_type>(-1);
102
103 private:
104 // type used for positions in insert, erase etc.
105#if __cplusplus < 201103L
106 typedef iterator __const_iterator;
107#else
108 typedef const_iterator __const_iterator;
109#endif
110
111#if __cplusplus > 201402L
112 // A helper type for avoiding boiler-plate.
113 typedef basic_string_view<_CharT, _Traits> __sv_type;
114
115 template<typename _Tp, typename _Res>
116 using _If_sv = enable_if_t<
117 __and_<is_convertible<const _Tp&, __sv_type>,
118 __not_<is_convertible<const _Tp*, const basic_string*>>,
119 __not_<is_convertible<const _Tp&, const _CharT*>>>::value,
120 _Res>;
121
122 // Allows an implicit conversion to __sv_type.
123 static __sv_type
124 _S_to_string_view(__sv_type __svt) noexcept
125 { return __svt; }
126
127 // Wraps a string_view by explicit conversion and thus
128 // allows to add an internal constructor that does not
129 // participate in overload resolution when a string_view
130 // is provided.
131 struct __sv_wrapper
132 {
133 explicit __sv_wrapper(__sv_type __sv) noexcept : _M_sv(__sv) { }
134 __sv_type _M_sv;
135 };
136#endif
137
138 // Use empty-base optimization: http://www.cantrip.org/emptyopt.html
139 struct _Alloc_hider : allocator_type // TODO check __is_final
140 {
141#if __cplusplus < 201103L
142 _Alloc_hider(pointer __dat, const _Alloc& __a = _Alloc())
143 : allocator_type(__a), _M_p(__dat) { }
144#else
145 _Alloc_hider(pointer __dat, const _Alloc& __a)
146 : allocator_type(__a), _M_p(__dat) { }
147
148 _Alloc_hider(pointer __dat, _Alloc&& __a = _Alloc())
149 : allocator_type(std::move(__a)), _M_p(__dat) { }
150#endif
151
152 pointer _M_p; // The actual data.
153 };
154
155 _Alloc_hider _M_dataplus;
156 size_type _M_string_length;
157
158 enum { _S_local_capacity = 15 / sizeof(_CharT) };
159
160 union
161 {
162 _CharT _M_local_buf[_S_local_capacity + 1];
163 size_type _M_allocated_capacity;
164 };
165
166 void
167 _M_data(pointer __p)
168 { _M_dataplus._M_p = __p; }
169
170 void
171 _M_length(size_type __length)
172 { _M_string_length = __length; }
173
174 pointer
175 _M_data() const
176 { return _M_dataplus._M_p; }
177
178 pointer
179 _M_local_data()
180 {
181#if __cplusplus >= 201103L
182 return std::pointer_traits<pointer>::pointer_to(*_M_local_buf);
183#else
184 return pointer(_M_local_buf);
185#endif
186 }
187
188 const_pointer
189 _M_local_data() const
190 {
191#if __cplusplus >= 201103L
192 return std::pointer_traits<const_pointer>::pointer_to(*_M_local_buf);
193#else
194 return const_pointer(_M_local_buf);
195#endif
196 }
197
198 void
199 _M_capacity(size_type __capacity)
200 { _M_allocated_capacity = __capacity; }
201
202 void
203 _M_set_length(size_type __n)
204 {
205 _M_length(__n);
206 traits_type::assign(_M_data()[__n], _CharT());
207 }
208
209 bool
210 _M_is_local() const
211 { return _M_data() == _M_local_data(); }
212
213 // Create & Destroy
214 pointer
215 _M_create(size_type&, size_type);
216
217 void
218 _M_dispose()
219 {
220 if (!_M_is_local())
221 _M_destroy(_M_allocated_capacity);
222 }
223
224 void
225 _M_destroy(size_type __size) throw()
226 { _Alloc_traits::deallocate(_M_get_allocator(), _M_data(), __size + 1); }
227
228 // _M_construct_aux is used to implement the 21.3.1 para 15 which
229 // requires special behaviour if _InIterator is an integral type
230 template<typename _InIterator>
231 void
232 _M_construct_aux(_InIterator __beg, _InIterator __end,
233 std::__false_type)
234 {
235 typedef typename iterator_traits<_InIterator>::iterator_category _Tag;
236 _M_construct(__beg, __end, _Tag());
237 }
238
239 // _GLIBCXX_RESOLVE_LIB_DEFECTS
240 // 438. Ambiguity in the "do the right thing" clause
241 template<typename _Integer>
242 void
243 _M_construct_aux(_Integer __beg, _Integer __end, std::__true_type)
244 { _M_construct_aux_2(static_cast<size_type>(__beg), __end); }
245
246 void
247 _M_construct_aux_2(size_type __req, _CharT __c)
248 { _M_construct(__req, __c); }
249
250 template<typename _InIterator>
251 void
252 _M_construct(_InIterator __beg, _InIterator __end)
253 {
254 typedef typename std::__is_integer<_InIterator>::__type _Integral;
255 _M_construct_aux(__beg, __end, _Integral());
256 }
257
258 // For Input Iterators, used in istreambuf_iterators, etc.
259 template<typename _InIterator>
260 void
261 _M_construct(_InIterator __beg, _InIterator __end,
262 std::input_iterator_tag);
263
264 // For forward_iterators up to random_access_iterators, used for
265 // string::iterator, _CharT*, etc.
266 template<typename _FwdIterator>
267 void
268 _M_construct(_FwdIterator __beg, _FwdIterator __end,
269 std::forward_iterator_tag);
270
271 void
272 _M_construct(size_type __req, _CharT __c);
273
274 allocator_type&
275 _M_get_allocator()
276 { return _M_dataplus; }
277
278 const allocator_type&
279 _M_get_allocator() const
280 { return _M_dataplus; }
281
282 private:
283
284#ifdef _GLIBCXX_DISAMBIGUATE_REPLACE_INST
285 // The explicit instantiations in misc-inst.cc require this due to
286 // https://gcc.gnu.org/bugzilla/show_bug.cgi?id=64063
287 template<typename _Tp, bool _Requires =
288 !__are_same<_Tp, _CharT*>::__value
289 && !__are_same<_Tp, const _CharT*>::__value
290 && !__are_same<_Tp, iterator>::__value
291 && !__are_same<_Tp, const_iterator>::__value>
292 struct __enable_if_not_native_iterator
293 { typedef basic_string& __type; };
294 template<typename _Tp>
295 struct __enable_if_not_native_iterator<_Tp, false> { };
296#endif
297
298 size_type
299 _M_check(size_type __pos, const char* __s) const
300 {
301 if (__pos > this->size())
302 __throw_out_of_range_fmt(__N("%s: __pos (which is %zu) > "
303 "this->size() (which is %zu)"),
304 __s, __pos, this->size());
305 return __pos;
306 }
307
308 void
309 _M_check_length(size_type __n1, size_type __n2, const char* __s) const
310 {
311 if (this->max_size() - (this->size() - __n1) < __n2)
312 __throw_length_error(__N(__s));
313 }
314
315
316 // NB: _M_limit doesn't check for a bad __pos value.
317 size_type
318 _M_limit(size_type __pos, size_type __off) const _GLIBCXX_NOEXCEPT
319 {
320 const bool __testoff = __off < this->size() - __pos;
321 return __testoff ? __off : this->size() - __pos;
322 }
323
324 // True if _Rep and source do not overlap.
325 bool
326 _M_disjunct(const _CharT* __s) const _GLIBCXX_NOEXCEPT
327 {
328 return (less<const _CharT*>()(__s, _M_data())
329 || less<const _CharT*>()(_M_data() + this->size(), __s));
330 }
331
332 // When __n = 1 way faster than the general multichar
333 // traits_type::copy/move/assign.
334 static void
335 _S_copy(_CharT* __d, const _CharT* __s, size_type __n)
336 {
337 if (__n == 1)
338 traits_type::assign(*__d, *__s);
339 else
340 traits_type::copy(__d, __s, __n);
341 }
342
343 static void
344 _S_move(_CharT* __d, const _CharT* __s, size_type __n)
345 {
346 if (__n == 1)
347 traits_type::assign(*__d, *__s);
348 else
349 traits_type::move(__d, __s, __n);
350 }
351
352 static void
353 _S_assign(_CharT* __d, size_type __n, _CharT __c)
354 {
355 if (__n == 1)
356 traits_type::assign(*__d, __c);
357 else
358 traits_type::assign(__d, __n, __c);
359 }
360
361 // _S_copy_chars is a separate template to permit specialization
362 // to optimize for the common case of pointers as iterators.
363 template<class _Iterator>
364 static void
365 _S_copy_chars(_CharT* __p, _Iterator __k1, _Iterator __k2)
366 {
367 for (; __k1 != __k2; ++__k1, (void)++__p)
368 traits_type::assign(*__p, *__k1); // These types are off.
369 }
370
371 static void
372 _S_copy_chars(_CharT* __p, iterator __k1, iterator __k2) _GLIBCXX_NOEXCEPT
373 { _S_copy_chars(__p, __k1.base(), __k2.base()); }
374
375 static void
376 _S_copy_chars(_CharT* __p, const_iterator __k1, const_iterator __k2)
377 _GLIBCXX_NOEXCEPT
378 { _S_copy_chars(__p, __k1.base(), __k2.base()); }
379
380 static void
381 _S_copy_chars(_CharT* __p, _CharT* __k1, _CharT* __k2) _GLIBCXX_NOEXCEPT
382 { _S_copy(__p, __k1, __k2 - __k1); }
383
384 static void
385 _S_copy_chars(_CharT* __p, const _CharT* __k1, const _CharT* __k2)
386 _GLIBCXX_NOEXCEPT
387 { _S_copy(__p, __k1, __k2 - __k1); }
388
389 static int
390 _S_compare(size_type __n1, size_type __n2) _GLIBCXX_NOEXCEPT
391 {
392 const difference_type __d = difference_type(__n1 - __n2);
393
394 if (__d > __gnu_cxx::__numeric_traits<int>::__max)
395 return __gnu_cxx::__numeric_traits<int>::__max;
396 else if (__d < __gnu_cxx::__numeric_traits<int>::__min)
397 return __gnu_cxx::__numeric_traits<int>::__min;
398 else
399 return int(__d);
400 }
401
402 void
403 _M_assign(const basic_string&);
404
405 void
406 _M_mutate(size_type __pos, size_type __len1, const _CharT* __s,
407 size_type __len2);
408
409 void
410 _M_erase(size_type __pos, size_type __n);
411
412 public:
413 // Construct/copy/destroy:
414 // NB: We overload ctors in some cases instead of using default
415 // arguments, per 17.4.4.4 para. 2 item 2.
416
417 /**
418 * @brief Default constructor creates an empty string.
419 */
420 basic_string()
421 _GLIBCXX_NOEXCEPT_IF(is_nothrow_default_constructible<_Alloc>::value)
422 : _M_dataplus(_M_local_data())
423 { _M_set_length(0); }
424
425 /**
426 * @brief Construct an empty string using allocator @a a.
427 */
428 explicit
429 basic_string(const _Alloc& __a) _GLIBCXX_NOEXCEPT
430 : _M_dataplus(_M_local_data(), __a)
431 { _M_set_length(0); }
432
433 /**
434 * @brief Construct string with copy of value of @a __str.
435 * @param __str Source string.
436 */
437 basic_string(const basic_string& __str)
438 : _M_dataplus(_M_local_data(),
439 _Alloc_traits::_S_select_on_copy(__str._M_get_allocator()))
440 { _M_construct(__str._M_data(), __str._M_data() + __str.length()); }
441
442 // _GLIBCXX_RESOLVE_LIB_DEFECTS
443 // 2583. no way to supply an allocator for basic_string(str, pos)
444 /**
445 * @brief Construct string as copy of a substring.
446 * @param __str Source string.
447 * @param __pos Index of first character to copy from.
448 * @param __a Allocator to use.
449 */
450 basic_string(const basic_string& __str, size_type __pos,
451 const _Alloc& __a = _Alloc())
452 : _M_dataplus(_M_local_data(), __a)
453 {
454 const _CharT* __start = __str._M_data()
455 + __str._M_check(__pos, "basic_string::basic_string");
456 _M_construct(__start, __start + __str._M_limit(__pos, npos));
457 }
458
459 /**
460 * @brief Construct string as copy of a substring.
461 * @param __str Source string.
462 * @param __pos Index of first character to copy from.
463 * @param __n Number of characters to copy.
464 */
465 basic_string(const basic_string& __str, size_type __pos,
466 size_type __n)
467 : _M_dataplus(_M_local_data())
468 {
469 const _CharT* __start = __str._M_data()
470 + __str._M_check(__pos, "basic_string::basic_string");
471 _M_construct(__start, __start + __str._M_limit(__pos, __n));
472 }
473
474 /**
475 * @brief Construct string as copy of a substring.
476 * @param __str Source string.
477 * @param __pos Index of first character to copy from.
478 * @param __n Number of characters to copy.
479 * @param __a Allocator to use.
480 */
481 basic_string(const basic_string& __str, size_type __pos,
482 size_type __n, const _Alloc& __a)
483 : _M_dataplus(_M_local_data(), __a)
484 {
485 const _CharT* __start
486 = __str._M_data() + __str._M_check(__pos, "string::string");
487 _M_construct(__start, __start + __str._M_limit(__pos, __n));
488 }
489
490 /**
491 * @brief Construct string initialized by a character %array.
492 * @param __s Source character %array.
493 * @param __n Number of characters to copy.
494 * @param __a Allocator to use (default is default allocator).
495 *
496 * NB: @a __s must have at least @a __n characters, &apos;\\0&apos;
497 * has no special meaning.
498 */
499 basic_string(const _CharT* __s, size_type __n,
500 const _Alloc& __a = _Alloc())
501 : _M_dataplus(_M_local_data(), __a)
502 { _M_construct(__s, __s + __n); }
503
504 /**
505 * @brief Construct string as copy of a C string.
506 * @param __s Source C string.
507 * @param __a Allocator to use (default is default allocator).
508 */
509#if __cpp_deduction_guides && ! defined _GLIBCXX_DEFINING_STRING_INSTANTIATIONS
510 // _GLIBCXX_RESOLVE_LIB_DEFECTS
511 // 3076. basic_string CTAD ambiguity
512 template<typename = _RequireAllocator<_Alloc>>
513#endif
514 basic_string(const _CharT* __s, const _Alloc& __a = _Alloc())
515 : _M_dataplus(_M_local_data(), __a)
516 { _M_construct(__s, __s ? __s + traits_type::length(__s) : __s+npos); }
517
518 /**
519 * @brief Construct string as multiple characters.
520 * @param __n Number of characters.
521 * @param __c Character to use.
522 * @param __a Allocator to use (default is default allocator).
523 */
524#if __cpp_deduction_guides && ! defined _GLIBCXX_DEFINING_STRING_INSTANTIATIONS
525 // _GLIBCXX_RESOLVE_LIB_DEFECTS
526 // 3076. basic_string CTAD ambiguity
527 template<typename = _RequireAllocator<_Alloc>>
528#endif
529 basic_string(size_type __n, _CharT __c, const _Alloc& __a = _Alloc())
530 : _M_dataplus(_M_local_data(), __a)
531 { _M_construct(__n, __c); }
532
533#if __cplusplus >= 201103L
534 /**
535 * @brief Move construct string.
536 * @param __str Source string.
537 *
538 * The newly-created string contains the exact contents of @a __str.
539 * @a __str is a valid, but unspecified string.
540 **/
541 basic_string(basic_string&& __str) noexcept
542 : _M_dataplus(_M_local_data(), std::move(__str._M_get_allocator()))
543 {
544 if (__str._M_is_local())
545 {
546 traits_type::copy(_M_local_buf, __str._M_local_buf,
547 _S_local_capacity + 1);
548 }
549 else
550 {
551 _M_data(__str._M_data());
552 _M_capacity(__str._M_allocated_capacity);
553 }
554
555 // Must use _M_length() here not _M_set_length() because
556 // basic_stringbuf relies on writing into unallocated capacity so
557 // we mess up the contents if we put a '\0' in the string.
558 _M_length(__str.length());
559 __str._M_data(__str._M_local_data());
560 __str._M_set_length(0);
561 }
562
563 /**
564 * @brief Construct string from an initializer %list.
565 * @param __l std::initializer_list of characters.
566 * @param __a Allocator to use (default is default allocator).
567 */
568 basic_string(initializer_list<_CharT> __l, const _Alloc& __a = _Alloc())
569 : _M_dataplus(_M_local_data(), __a)
570 { _M_construct(__l.begin(), __l.end()); }
571
572 basic_string(const basic_string& __str, const _Alloc& __a)
573 : _M_dataplus(_M_local_data(), __a)
574 { _M_construct(__str.begin(), __str.end()); }
575
576 basic_string(basic_string&& __str, const _Alloc& __a)
577 noexcept(_Alloc_traits::_S_always_equal())
578 : _M_dataplus(_M_local_data(), __a)
579 {
580 if (__str._M_is_local())
581 {
582 traits_type::copy(_M_local_buf, __str._M_local_buf,
583 _S_local_capacity + 1);
584 _M_length(__str.length());
585 __str._M_set_length(0);
586 }
587 else if (_Alloc_traits::_S_always_equal()
588 || __str.get_allocator() == __a)
589 {
590 _M_data(__str._M_data());
591 _M_length(__str.length());
592 _M_capacity(__str._M_allocated_capacity);
593 __str._M_data(__str._M_local_buf);
594 __str._M_set_length(0);
595 }
596 else
597 _M_construct(__str.begin(), __str.end());
598 }
599
600#endif // C++11
601
602 /**
603 * @brief Construct string as copy of a range.
604 * @param __beg Start of range.
605 * @param __end End of range.
606 * @param __a Allocator to use (default is default allocator).
607 */
608#if __cplusplus >= 201103L
609 template<typename _InputIterator,
610 typename = std::_RequireInputIter<_InputIterator>>
611#else
612 template<typename _InputIterator>
613#endif
614 basic_string(_InputIterator __beg, _InputIterator __end,
615 const _Alloc& __a = _Alloc())
616 : _M_dataplus(_M_local_data(), __a)
617 { _M_construct(__beg, __end); }
618
619#if __cplusplus > 201402L
620 /**
621 * @brief Construct string from a substring of a string_view.
622 * @param __t Source object convertible to string view.
623 * @param __pos The index of the first character to copy from __t.
624 * @param __n The number of characters to copy from __t.
625 * @param __a Allocator to use.
626 */
627 template<typename _Tp, typename = _If_sv<_Tp, void>>
628 basic_string(const _Tp& __t, size_type __pos, size_type __n,
629 const _Alloc& __a = _Alloc())
630 : basic_string(_S_to_string_view(__t).substr(__pos, __n), __a) { }
631
632 /**
633 * @brief Construct string from a string_view.
634 * @param __t Source object convertible to string view.
635 * @param __a Allocator to use (default is default allocator).
636 */
637 template<typename _Tp, typename = _If_sv<_Tp, void>>
638 explicit
639 basic_string(const _Tp& __t, const _Alloc& __a = _Alloc())
640 : basic_string(__sv_wrapper(_S_to_string_view(__t)), __a) { }
641
642 /**
643 * @brief Only internally used: Construct string from a string view
644 * wrapper.
645 * @param __svw string view wrapper.
646 * @param __a Allocator to use.
647 */
648 explicit
649 basic_string(__sv_wrapper __svw, const _Alloc& __a)
650 : basic_string(__svw._M_sv.data(), __svw._M_sv.size(), __a) { }
651#endif // C++17
652
653 /**
654 * @brief Destroy the string instance.
655 */
656 ~basic_string()
657 { _M_dispose(); }
658
659 /**
660 * @brief Assign the value of @a str to this string.
661 * @param __str Source string.
662 */
663 basic_string&
664 operator=(const basic_string& __str)
665 {
666#if __cplusplus >= 201103L
667 if (_Alloc_traits::_S_propagate_on_copy_assign())
668 {
669 if (!_Alloc_traits::_S_always_equal() && !_M_is_local()
670 && _M_get_allocator() != __str._M_get_allocator())
671 {
672 // Propagating allocator cannot free existing storage so must
673 // deallocate it before replacing current allocator.
674 if (__str.size() <= _S_local_capacity)
675 {
676 _M_destroy(_M_allocated_capacity);
677 _M_data(_M_local_data());
678 _M_set_length(0);
679 }
680 else
681 {
682 const auto __len = __str.size();
683 auto __alloc = __str._M_get_allocator();
684 // If this allocation throws there are no effects:
685 auto __ptr = _Alloc_traits::allocate(__alloc, __len + 1);
686 _M_destroy(_M_allocated_capacity);
687 _M_data(__ptr);
688 _M_capacity(__len);
689 _M_set_length(__len);
690 }
691 }
692 std::__alloc_on_copy(_M_get_allocator(), __str._M_get_allocator());
693 }
694#endif
695 return this->assign(__str);
696 }
697
698 /**
699 * @brief Copy contents of @a s into this string.
700 * @param __s Source null-terminated string.
701 */
702 basic_string&
703 operator=(const _CharT* __s)
704 { return this->assign(__s); }
705
706 /**
707 * @brief Set value to string of length 1.
708 * @param __c Source character.
709 *
710 * Assigning to a character makes this string length 1 and
711 * (*this)[0] == @a c.
712 */
713 basic_string&
714 operator=(_CharT __c)
715 {
716 this->assign(1, __c);
717 return *this;
718 }
719
720#if __cplusplus >= 201103L
721 /**
722 * @brief Move assign the value of @a str to this string.
723 * @param __str Source string.
724 *
725 * The contents of @a str are moved into this string (without copying).
726 * @a str is a valid, but unspecified string.
727 **/
728 // PR 58265, this should be noexcept.
729 // _GLIBCXX_RESOLVE_LIB_DEFECTS
730 // 2063. Contradictory requirements for string move assignment
731 basic_string&
732 operator=(basic_string&& __str)
733 noexcept(_Alloc_traits::_S_nothrow_move())
734 {
735 if (!_M_is_local() && _Alloc_traits::_S_propagate_on_move_assign()
736 && !_Alloc_traits::_S_always_equal()
737 && _M_get_allocator() != __str._M_get_allocator())
738 {
739 // Destroy existing storage before replacing allocator.
740 _M_destroy(_M_allocated_capacity);
741 _M_data(_M_local_data());
742 _M_set_length(0);
743 }
744 // Replace allocator if POCMA is true.
745 std::__alloc_on_move(_M_get_allocator(), __str._M_get_allocator());
746
747 if (!__str._M_is_local()
748 && (_Alloc_traits::_S_propagate_on_move_assign()
749 || _Alloc_traits::_S_always_equal()))
750 {
751 pointer __data = nullptr;
752 size_type __capacity;
753 if (!_M_is_local())
754 {
755 if (_Alloc_traits::_S_always_equal())
756 {
757 __data = _M_data();
758 __capacity = _M_allocated_capacity;
759 }
760 else
761 _M_destroy(_M_allocated_capacity);
762 }
763
764 _M_data(__str._M_data());
765 _M_length(__str.length());
766 _M_capacity(__str._M_allocated_capacity);
767 if (__data)
768 {
769 __str._M_data(__data);
770 __str._M_capacity(__capacity);
771 }
772 else
773 __str._M_data(__str._M_local_buf);
774 }
775 else
776 assign(__str);
777 __str.clear();
778 return *this;
779 }
780
781 /**
782 * @brief Set value to string constructed from initializer %list.
783 * @param __l std::initializer_list.
784 */
785 basic_string&
786 operator=(initializer_list<_CharT> __l)
787 {
788 this->assign(__l.begin(), __l.size());
789 return *this;
790 }
791#endif // C++11
792
793#if __cplusplus > 201402L
794 /**
795 * @brief Set value to string constructed from a string_view.
796 * @param __svt An object convertible to string_view.
797 */
798 template<typename _Tp>
799 _If_sv<_Tp, basic_string&>
800 operator=(const _Tp& __svt)
801 { return this->assign(__svt); }
802
803 /**
804 * @brief Convert to a string_view.
805 * @return A string_view.
806 */
807 operator __sv_type() const noexcept
808 { return __sv_type(data(), size()); }
809#endif // C++17
810
811 // Iterators:
812 /**
813 * Returns a read/write iterator that points to the first character in
814 * the %string.
815 */
816 iterator
817 begin() _GLIBCXX_NOEXCEPT
818 { return iterator(_M_data()); }
819
820 /**
821 * Returns a read-only (constant) iterator that points to the first
822 * character in the %string.
823 */
824 const_iterator
825 begin() const _GLIBCXX_NOEXCEPT
826 { return const_iterator(_M_data()); }
827
828 /**
829 * Returns a read/write iterator that points one past the last
830 * character in the %string.
831 */
832 iterator
833 end() _GLIBCXX_NOEXCEPT
834 { return iterator(_M_data() + this->size()); }
835
836 /**
837 * Returns a read-only (constant) iterator that points one past the
838 * last character in the %string.
839 */
840 const_iterator
841 end() const _GLIBCXX_NOEXCEPT
842 { return const_iterator(_M_data() + this->size()); }
843
844 /**
845 * Returns a read/write reverse iterator that points to the last
846 * character in the %string. Iteration is done in reverse element
847 * order.
848 */
849 reverse_iterator
850 rbegin() _GLIBCXX_NOEXCEPT
851 { return reverse_iterator(this->end()); }
852
853 /**
854 * Returns a read-only (constant) reverse iterator that points
855 * to the last character in the %string. Iteration is done in
856 * reverse element order.
857 */
858 const_reverse_iterator
859 rbegin() const _GLIBCXX_NOEXCEPT
860 { return const_reverse_iterator(this->end()); }
861
862 /**
863 * Returns a read/write reverse iterator that points to one before the
864 * first character in the %string. Iteration is done in reverse
865 * element order.
866 */
867 reverse_iterator
868 rend() _GLIBCXX_NOEXCEPT
869 { return reverse_iterator(this->begin()); }
870
871 /**
872 * Returns a read-only (constant) reverse iterator that points
873 * to one before the first character in the %string. Iteration
874 * is done in reverse element order.
875 */
876 const_reverse_iterator
877 rend() const _GLIBCXX_NOEXCEPT
878 { return const_reverse_iterator(this->begin()); }
879
880#if __cplusplus >= 201103L
881 /**
882 * Returns a read-only (constant) iterator that points to the first
883 * character in the %string.
884 */
885 const_iterator
886 cbegin() const noexcept
887 { return const_iterator(this->_M_data()); }
888
889 /**
890 * Returns a read-only (constant) iterator that points one past the
891 * last character in the %string.
892 */
893 const_iterator
894 cend() const noexcept
895 { return const_iterator(this->_M_data() + this->size()); }
896
897 /**
898 * Returns a read-only (constant) reverse iterator that points
899 * to the last character in the %string. Iteration is done in
900 * reverse element order.
901 */
902 const_reverse_iterator
903 crbegin() const noexcept
904 { return const_reverse_iterator(this->end()); }
905
906 /**
907 * Returns a read-only (constant) reverse iterator that points
908 * to one before the first character in the %string. Iteration
909 * is done in reverse element order.
910 */
911 const_reverse_iterator
912 crend() const noexcept
913 { return const_reverse_iterator(this->begin()); }
914#endif
915
916 public:
917 // Capacity:
918 /// Returns the number of characters in the string, not including any
919 /// null-termination.
920 size_type
921 size() const _GLIBCXX_NOEXCEPT
922 { return _M_string_length; }
923
924 /// Returns the number of characters in the string, not including any
925 /// null-termination.
926 size_type
927 length() const _GLIBCXX_NOEXCEPT
928 { return _M_string_length; }
929
930 /// Returns the size() of the largest possible %string.
931 size_type
932 max_size() const _GLIBCXX_NOEXCEPT
933 { return (_Alloc_traits::max_size(_M_get_allocator()) - 1) / 2; }
934
935 /**
936 * @brief Resizes the %string to the specified number of characters.
937 * @param __n Number of characters the %string should contain.
938 * @param __c Character to fill any new elements.
939 *
940 * This function will %resize the %string to the specified
941 * number of characters. If the number is smaller than the
942 * %string's current size the %string is truncated, otherwise
943 * the %string is extended and new elements are %set to @a __c.
944 */
945 void
946 resize(size_type __n, _CharT __c);
947
948 /**
949 * @brief Resizes the %string to the specified number of characters.
950 * @param __n Number of characters the %string should contain.
951 *
952 * This function will resize the %string to the specified length. If
953 * the new size is smaller than the %string's current size the %string
954 * is truncated, otherwise the %string is extended and new characters
955 * are default-constructed. For basic types such as char, this means
956 * setting them to 0.
957 */
958 void
959 resize(size_type __n)
960 { this->resize(__n, _CharT()); }
961
962#if __cplusplus >= 201103L
963 /// A non-binding request to reduce capacity() to size().
964 void
965 shrink_to_fit() noexcept
966 {
967#if __cpp_exceptions
968 if (capacity() > size())
969 {
970 try
971 { reserve(0); }
972 catch(...)
973 { }
974 }
975#endif
976 }
977#endif
978
979 /**
980 * Returns the total number of characters that the %string can hold
981 * before needing to allocate more memory.
982 */
983 size_type
984 capacity() const _GLIBCXX_NOEXCEPT
985 {
986 return _M_is_local() ? size_type(_S_local_capacity)
987 : _M_allocated_capacity;
988 }
989
990 /**
991 * @brief Attempt to preallocate enough memory for specified number of
992 * characters.
993 * @param __res_arg Number of characters required.
994 * @throw std::length_error If @a __res_arg exceeds @c max_size().
995 *
996 * This function attempts to reserve enough memory for the
997 * %string to hold the specified number of characters. If the
998 * number requested is more than max_size(), length_error is
999 * thrown.
1000 *
1001 * The advantage of this function is that if optimal code is a
1002 * necessity and the user can determine the string length that will be
1003 * required, the user can reserve the memory in %advance, and thus
1004 * prevent a possible reallocation of memory and copying of %string
1005 * data.
1006 */
1007 void
1008 reserve(size_type __res_arg = 0);
1009
1010 /**
1011 * Erases the string, making it empty.
1012 */
1013 void
1014 clear() _GLIBCXX_NOEXCEPT
1015 { _M_set_length(0); }
1016
1017 /**
1018 * Returns true if the %string is empty. Equivalent to
1019 * <code>*this == ""</code>.
1020 */
1021 bool
1022 empty() const _GLIBCXX_NOEXCEPT
1023 { return this->size() == 0; }
1024
1025 // Element access:
1026 /**
1027 * @brief Subscript access to the data contained in the %string.
1028 * @param __pos The index of the character to access.
1029 * @return Read-only (constant) reference to the character.
1030 *
1031 * This operator allows for easy, array-style, data access.
1032 * Note that data access with this operator is unchecked and
1033 * out_of_range lookups are not defined. (For checked lookups
1034 * see at().)
1035 */
1036 const_reference
1037 operator[] (size_type __pos) const _GLIBCXX_NOEXCEPT
1038 {
1039 __glibcxx_assert(__pos <= size());
1040 return _M_data()[__pos];
1041 }
1042
1043 /**
1044 * @brief Subscript access to the data contained in the %string.
1045 * @param __pos The index of the character to access.
1046 * @return Read/write reference to the character.
1047 *
1048 * This operator allows for easy, array-style, data access.
1049 * Note that data access with this operator is unchecked and
1050 * out_of_range lookups are not defined. (For checked lookups
1051 * see at().)
1052 */
1053 reference
1054 operator[](size_type __pos)
1055 {
1056 // Allow pos == size() both in C++98 mode, as v3 extension,
1057 // and in C++11 mode.
1058 __glibcxx_assert(__pos <= size());
1059 // In pedantic mode be strict in C++98 mode.
1060 _GLIBCXX_DEBUG_PEDASSERT(__cplusplus >= 201103L || __pos < size());
1061 return _M_data()[__pos];
1062 }
1063
1064 /**
1065 * @brief Provides access to the data contained in the %string.
1066 * @param __n The index of the character to access.
1067 * @return Read-only (const) reference to the character.
1068 * @throw std::out_of_range If @a n is an invalid index.
1069 *
1070 * This function provides for safer data access. The parameter is
1071 * first checked that it is in the range of the string. The function
1072 * throws out_of_range if the check fails.
1073 */
1074 const_reference
1075 at(size_type __n) const
1076 {
1077 if (__n >= this->size())
1078 __throw_out_of_range_fmt(__N("basic_string::at: __n "
1079 "(which is %zu) >= this->size() "
1080 "(which is %zu)"),
1081 __n, this->size());
1082 return _M_data()[__n];
1083 }
1084
1085 /**
1086 * @brief Provides access to the data contained in the %string.
1087 * @param __n The index of the character to access.
1088 * @return Read/write reference to the character.
1089 * @throw std::out_of_range If @a n is an invalid index.
1090 *
1091 * This function provides for safer data access. The parameter is
1092 * first checked that it is in the range of the string. The function
1093 * throws out_of_range if the check fails.
1094 */
1095 reference
1096 at(size_type __n)
1097 {
1098 if (__n >= size())
1099 __throw_out_of_range_fmt(__N("basic_string::at: __n "
1100 "(which is %zu) >= this->size() "
1101 "(which is %zu)"),
1102 __n, this->size());
1103 return _M_data()[__n];
1104 }
1105
1106#if __cplusplus >= 201103L
1107 /**
1108 * Returns a read/write reference to the data at the first
1109 * element of the %string.
1110 */
1111 reference
1112 front() noexcept
1113 {
1114 __glibcxx_assert(!empty());
1115 return operator[](0);
1116 }
1117
1118 /**
1119 * Returns a read-only (constant) reference to the data at the first
1120 * element of the %string.
1121 */
1122 const_reference
1123 front() const noexcept
1124 {
1125 __glibcxx_assert(!empty());
1126 return operator[](0);
1127 }
1128
1129 /**
1130 * Returns a read/write reference to the data at the last
1131 * element of the %string.
1132 */
1133 reference
1134 back() noexcept
1135 {
1136 __glibcxx_assert(!empty());
1137 return operator[](this->size() - 1);
1138 }
1139
1140 /**
1141 * Returns a read-only (constant) reference to the data at the
1142 * last element of the %string.
1143 */
1144 const_reference
1145 back() const noexcept
1146 {
1147 __glibcxx_assert(!empty());
1148 return operator[](this->size() - 1);
1149 }
1150#endif
1151
1152 // Modifiers:
1153 /**
1154 * @brief Append a string to this string.
1155 * @param __str The string to append.
1156 * @return Reference to this string.
1157 */
1158 basic_string&
1159 operator+=(const basic_string& __str)
1160 { return this->append(__str); }
1161
1162 /**
1163 * @brief Append a C string.
1164 * @param __s The C string to append.
1165 * @return Reference to this string.
1166 */
1167 basic_string&
1168 operator+=(const _CharT* __s)
1169 { return this->append(__s); }
1170
1171 /**
1172 * @brief Append a character.
1173 * @param __c The character to append.
1174 * @return Reference to this string.
1175 */
1176 basic_string&
1177 operator+=(_CharT __c)
1178 {
1179 this->push_back(__c);
1180 return *this;
1181 }
1182
1183#if __cplusplus >= 201103L
1184 /**
1185 * @brief Append an initializer_list of characters.
1186 * @param __l The initializer_list of characters to be appended.
1187 * @return Reference to this string.
1188 */
1189 basic_string&
1190 operator+=(initializer_list<_CharT> __l)
1191 { return this->append(__l.begin(), __l.size()); }
1192#endif // C++11
1193
1194#if __cplusplus > 201402L
1195 /**
1196 * @brief Append a string_view.
1197 * @param __svt An object convertible to string_view to be appended.
1198 * @return Reference to this string.
1199 */
1200 template<typename _Tp>
1201 _If_sv<_Tp, basic_string&>
1202 operator+=(const _Tp& __svt)
1203 { return this->append(__svt); }
1204#endif // C++17
1205
1206 /**
1207 * @brief Append a string to this string.
1208 * @param __str The string to append.
1209 * @return Reference to this string.
1210 */
1211 basic_string&
1212 append(const basic_string& __str)
1213 { return _M_append(__str._M_data(), __str.size()); }
1214
1215 /**
1216 * @brief Append a substring.
1217 * @param __str The string to append.
1218 * @param __pos Index of the first character of str to append.
1219 * @param __n The number of characters to append.
1220 * @return Reference to this string.
1221 * @throw std::out_of_range if @a __pos is not a valid index.
1222 *
1223 * This function appends @a __n characters from @a __str
1224 * starting at @a __pos to this string. If @a __n is is larger
1225 * than the number of available characters in @a __str, the
1226 * remainder of @a __str is appended.
1227 */
1228 basic_string&
1229 append(const basic_string& __str, size_type __pos, size_type __n = npos)
1230 { return _M_append(__str._M_data()
1231 + __str._M_check(__pos, "basic_string::append"),
1232 __str._M_limit(__pos, __n)); }
1233
1234 /**
1235 * @brief Append a C substring.
1236 * @param __s The C string to append.
1237 * @param __n The number of characters to append.
1238 * @return Reference to this string.
1239 */
1240 basic_string&
1241 append(const _CharT* __s, size_type __n)
1242 {
1243 __glibcxx_requires_string_len(__s, __n);
1244 _M_check_length(size_type(0), __n, "basic_string::append");
1245 return _M_append(__s, __n);
1246 }
1247
1248 /**
1249 * @brief Append a C string.
1250 * @param __s The C string to append.
1251 * @return Reference to this string.
1252 */
1253 basic_string&
1254 append(const _CharT* __s)
1255 {
1256 __glibcxx_requires_string(__s);
1257 const size_type __n = traits_type::length(__s);
1258 _M_check_length(size_type(0), __n, "basic_string::append");
1259 return _M_append(__s, __n);
1260 }
1261
1262 /**
1263 * @brief Append multiple characters.
1264 * @param __n The number of characters to append.
1265 * @param __c The character to use.
1266 * @return Reference to this string.
1267 *
1268 * Appends __n copies of __c to this string.
1269 */
1270 basic_string&
1271 append(size_type __n, _CharT __c)
1272 { return _M_replace_aux(this->size(), size_type(0), __n, __c); }
1273
1274#if __cplusplus >= 201103L
1275 /**
1276 * @brief Append an initializer_list of characters.
1277 * @param __l The initializer_list of characters to append.
1278 * @return Reference to this string.
1279 */
1280 basic_string&
1281 append(initializer_list<_CharT> __l)
1282 { return this->append(__l.begin(), __l.size()); }
1283#endif // C++11
1284
1285 /**
1286 * @brief Append a range of characters.
1287 * @param __first Iterator referencing the first character to append.
1288 * @param __last Iterator marking the end of the range.
1289 * @return Reference to this string.
1290 *
1291 * Appends characters in the range [__first,__last) to this string.
1292 */
1293#if __cplusplus >= 201103L
1294 template<class _InputIterator,
1295 typename = std::_RequireInputIter<_InputIterator>>
1296#else
1297 template<class _InputIterator>
1298#endif
1299 basic_string&
1300 append(_InputIterator __first, _InputIterator __last)
1301 { return this->replace(end(), end(), __first, __last); }
1302
1303#if __cplusplus > 201402L
1304 /**
1305 * @brief Append a string_view.
1306 * @param __svt An object convertible to string_view to be appended.
1307 * @return Reference to this string.
1308 */
1309 template<typename _Tp>
1310 _If_sv<_Tp, basic_string&>
1311 append(const _Tp& __svt)
1312 {
1313 __sv_type __sv = __svt;
1314 return this->append(__sv.data(), __sv.size());
1315 }
1316
1317 /**
1318 * @brief Append a range of characters from a string_view.
1319 * @param __svt An object convertible to string_view to be appended from.
1320 * @param __pos The position in the string_view to append from.
1321 * @param __n The number of characters to append from the string_view.
1322 * @return Reference to this string.
1323 */
1324 template<typename _Tp>
1325 _If_sv<_Tp, basic_string&>
1326 append(const _Tp& __svt, size_type __pos, size_type __n = npos)
1327 {
1328 __sv_type __sv = __svt;
1329 return _M_append(__sv.data()
1330 + __sv._M_check(__pos, "basic_string::append"),
1331 __sv._M_limit(__pos, __n));
1332 }
1333#endif // C++17
1334
1335 /**
1336 * @brief Append a single character.
1337 * @param __c Character to append.
1338 */
1339 void
1340 push_back(_CharT __c)
1341 {
1342 const size_type __size = this->size();
1343 if (__size + 1 > this->capacity())
1344 this->_M_mutate(__size, size_type(0), 0, size_type(1));
1345 traits_type::assign(this->_M_data()[__size], __c);
1346 this->_M_set_length(__size + 1);
1347 }
1348
1349 /**
1350 * @brief Set value to contents of another string.
1351 * @param __str Source string to use.
1352 * @return Reference to this string.
1353 */
1354 basic_string&
1355 assign(const basic_string& __str)
1356 {
1357 this->_M_assign(__str);
1358 return *this;
1359 }
1360
1361#if __cplusplus >= 201103L
1362 /**
1363 * @brief Set value to contents of another string.
1364 * @param __str Source string to use.
1365 * @return Reference to this string.
1366 *
1367 * This function sets this string to the exact contents of @a __str.
1368 * @a __str is a valid, but unspecified string.
1369 */
1370 basic_string&
1371 assign(basic_string&& __str)
1372 noexcept(_Alloc_traits::_S_nothrow_move())
1373 {
1374 // _GLIBCXX_RESOLVE_LIB_DEFECTS
1375 // 2063. Contradictory requirements for string move assignment
1376 return *this = std::move(__str);
1377 }
1378#endif // C++11
1379
1380 /**
1381 * @brief Set value to a substring of a string.
1382 * @param __str The string to use.
1383 * @param __pos Index of the first character of str.
1384 * @param __n Number of characters to use.
1385 * @return Reference to this string.
1386 * @throw std::out_of_range if @a pos is not a valid index.
1387 *
1388 * This function sets this string to the substring of @a __str
1389 * consisting of @a __n characters at @a __pos. If @a __n is
1390 * is larger than the number of available characters in @a
1391 * __str, the remainder of @a __str is used.
1392 */
1393 basic_string&
1394 assign(const basic_string& __str, size_type __pos, size_type __n = npos)
1395 { return _M_replace(size_type(0), this->size(), __str._M_data()
1396 + __str._M_check(__pos, "basic_string::assign"),
1397 __str._M_limit(__pos, __n)); }
1398
1399 /**
1400 * @brief Set value to a C substring.
1401 * @param __s The C string to use.
1402 * @param __n Number of characters to use.
1403 * @return Reference to this string.
1404 *
1405 * This function sets the value of this string to the first @a __n
1406 * characters of @a __s. If @a __n is is larger than the number of
1407 * available characters in @a __s, the remainder of @a __s is used.
1408 */
1409 basic_string&
1410 assign(const _CharT* __s, size_type __n)
1411 {
1412 __glibcxx_requires_string_len(__s, __n);
1413 return _M_replace(size_type(0), this->size(), __s, __n);
1414 }
1415
1416 /**
1417 * @brief Set value to contents of a C string.
1418 * @param __s The C string to use.
1419 * @return Reference to this string.
1420 *
1421 * This function sets the value of this string to the value of @a __s.
1422 * The data is copied, so there is no dependence on @a __s once the
1423 * function returns.
1424 */
1425 basic_string&
1426 assign(const _CharT* __s)
1427 {
1428 __glibcxx_requires_string(__s);
1429 return _M_replace(size_type(0), this->size(), __s,
1430 traits_type::length(__s));
1431 }
1432
1433 /**
1434 * @brief Set value to multiple characters.
1435 * @param __n Length of the resulting string.
1436 * @param __c The character to use.
1437 * @return Reference to this string.
1438 *
1439 * This function sets the value of this string to @a __n copies of
1440 * character @a __c.
1441 */
1442 basic_string&
1443 assign(size_type __n, _CharT __c)
1444 { return _M_replace_aux(size_type(0), this->size(), __n, __c); }
1445
1446 /**
1447 * @brief Set value to a range of characters.
1448 * @param __first Iterator referencing the first character to append.
1449 * @param __last Iterator marking the end of the range.
1450 * @return Reference to this string.
1451 *
1452 * Sets value of string to characters in the range [__first,__last).
1453 */
1454#if __cplusplus >= 201103L
1455 template<class _InputIterator,
1456 typename = std::_RequireInputIter<_InputIterator>>
1457#else
1458 template<class _InputIterator>
1459#endif
1460 basic_string&
1461 assign(_InputIterator __first, _InputIterator __last)
1462 { return this->replace(begin(), end(), __first, __last); }
1463
1464#if __cplusplus >= 201103L
1465 /**
1466 * @brief Set value to an initializer_list of characters.
1467 * @param __l The initializer_list of characters to assign.
1468 * @return Reference to this string.
1469 */
1470 basic_string&
1471 assign(initializer_list<_CharT> __l)
1472 { return this->assign(__l.begin(), __l.size()); }
1473#endif // C++11
1474
1475#if __cplusplus > 201402L
1476 /**
1477 * @brief Set value from a string_view.
1478 * @param __svt The source object convertible to string_view.
1479 * @return Reference to this string.
1480 */
1481 template<typename _Tp>
1482 _If_sv<_Tp, basic_string&>
1483 assign(const _Tp& __svt)
1484 {
1485 __sv_type __sv = __svt;
1486 return this->assign(__sv.data(), __sv.size());
1487 }
1488
1489 /**
1490 * @brief Set value from a range of characters in a string_view.
1491 * @param __svt The source object convertible to string_view.
1492 * @param __pos The position in the string_view to assign from.
1493 * @param __n The number of characters to assign.
1494 * @return Reference to this string.
1495 */
1496 template<typename _Tp>
1497 _If_sv<_Tp, basic_string&>
1498 assign(const _Tp& __svt, size_type __pos, size_type __n = npos)
1499 {
1500 __sv_type __sv = __svt;
1501 return _M_replace(size_type(0), this->size(), __sv.data()
1502 + __sv._M_check(__pos, "basic_string::assign"),
1503 __sv._M_limit(__pos, __n));
1504 }
1505#endif // C++17
1506
1507#if __cplusplus >= 201103L
1508 /**
1509 * @brief Insert multiple characters.
1510 * @param __p Const_iterator referencing location in string to
1511 * insert at.
1512 * @param __n Number of characters to insert
1513 * @param __c The character to insert.
1514 * @return Iterator referencing the first inserted char.
1515 * @throw std::length_error If new length exceeds @c max_size().
1516 *
1517 * Inserts @a __n copies of character @a __c starting at the
1518 * position referenced by iterator @a __p. If adding
1519 * characters causes the length to exceed max_size(),
1520 * length_error is thrown. The value of the string doesn't
1521 * change if an error is thrown.
1522 */
1523 iterator
1524 insert(const_iterator __p, size_type __n, _CharT __c)
1525 {
1526 _GLIBCXX_DEBUG_PEDASSERT(__p >= begin() && __p <= end());
1527 const size_type __pos = __p - begin();
1528 this->replace(__p, __p, __n, __c);
1529 return iterator(this->_M_data() + __pos);
1530 }
1531#else
1532 /**
1533 * @brief Insert multiple characters.
1534 * @param __p Iterator referencing location in string to insert at.
1535 * @param __n Number of characters to insert
1536 * @param __c The character to insert.
1537 * @throw std::length_error If new length exceeds @c max_size().
1538 *
1539 * Inserts @a __n copies of character @a __c starting at the
1540 * position referenced by iterator @a __p. If adding
1541 * characters causes the length to exceed max_size(),
1542 * length_error is thrown. The value of the string doesn't
1543 * change if an error is thrown.
1544 */
1545 void
1546 insert(iterator __p, size_type __n, _CharT __c)
1547 { this->replace(__p, __p, __n, __c); }
1548#endif
1549
1550#if __cplusplus >= 201103L
1551 /**
1552 * @brief Insert a range of characters.
1553 * @param __p Const_iterator referencing location in string to
1554 * insert at.
1555 * @param __beg Start of range.
1556 * @param __end End of range.
1557 * @return Iterator referencing the first inserted char.
1558 * @throw std::length_error If new length exceeds @c max_size().
1559 *
1560 * Inserts characters in range [beg,end). If adding characters
1561 * causes the length to exceed max_size(), length_error is
1562 * thrown. The value of the string doesn't change if an error
1563 * is thrown.
1564 */
1565 template<class _InputIterator,
1566 typename = std::_RequireInputIter<_InputIterator>>
1567 iterator
1568 insert(const_iterator __p, _InputIterator __beg, _InputIterator __end)
1569 {
1570 _GLIBCXX_DEBUG_PEDASSERT(__p >= begin() && __p <= end());
1571 const size_type __pos = __p - begin();
1572 this->replace(__p, __p, __beg, __end);
1573 return iterator(this->_M_data() + __pos);
1574 }
1575#else
1576 /**
1577 * @brief Insert a range of characters.
1578 * @param __p Iterator referencing location in string to insert at.
1579 * @param __beg Start of range.
1580 * @param __end End of range.
1581 * @throw std::length_error If new length exceeds @c max_size().
1582 *
1583 * Inserts characters in range [__beg,__end). If adding
1584 * characters causes the length to exceed max_size(),
1585 * length_error is thrown. The value of the string doesn't
1586 * change if an error is thrown.
1587 */
1588 template<class _InputIterator>
1589 void
1590 insert(iterator __p, _InputIterator __beg, _InputIterator __end)
1591 { this->replace(__p, __p, __beg, __end); }
1592#endif
1593
1594#if __cplusplus >= 201103L
1595 /**
1596 * @brief Insert an initializer_list of characters.
1597 * @param __p Iterator referencing location in string to insert at.
1598 * @param __l The initializer_list of characters to insert.
1599 * @throw std::length_error If new length exceeds @c max_size().
1600 */
1601 void
1602 insert(iterator __p, initializer_list<_CharT> __l)
1603 {
1604 _GLIBCXX_DEBUG_PEDASSERT(__p >= begin() && __p <= end());
1605 this->insert(__p - begin(), __l.begin(), __l.size());
1606 }
1607#endif // C++11
1608
1609 /**
1610 * @brief Insert value of a string.
1611 * @param __pos1 Iterator referencing location in string to insert at.
1612 * @param __str The string to insert.
1613 * @return Reference to this string.
1614 * @throw std::length_error If new length exceeds @c max_size().
1615 *
1616 * Inserts value of @a __str starting at @a __pos1. If adding
1617 * characters causes the length to exceed max_size(),
1618 * length_error is thrown. The value of the string doesn't
1619 * change if an error is thrown.
1620 */
1621 basic_string&
1622 insert(size_type __pos1, const basic_string& __str)
1623 { return this->replace(__pos1, size_type(0),
1624 __str._M_data(), __str.size()); }
1625
1626 /**
1627 * @brief Insert a substring.
1628 * @param __pos1 Iterator referencing location in string to insert at.
1629 * @param __str The string to insert.
1630 * @param __pos2 Start of characters in str to insert.
1631 * @param __n Number of characters to insert.
1632 * @return Reference to this string.
1633 * @throw std::length_error If new length exceeds @c max_size().
1634 * @throw std::out_of_range If @a pos1 > size() or
1635 * @a __pos2 > @a str.size().
1636 *
1637 * Starting at @a pos1, insert @a __n character of @a __str
1638 * beginning with @a __pos2. If adding characters causes the
1639 * length to exceed max_size(), length_error is thrown. If @a
1640 * __pos1 is beyond the end of this string or @a __pos2 is
1641 * beyond the end of @a __str, out_of_range is thrown. The
1642 * value of the string doesn't change if an error is thrown.
1643 */
1644 basic_string&
1645 insert(size_type __pos1, const basic_string& __str,
1646 size_type __pos2, size_type __n = npos)
1647 { return this->replace(__pos1, size_type(0), __str._M_data()
1648 + __str._M_check(__pos2, "basic_string::insert"),
1649 __str._M_limit(__pos2, __n)); }
1650
1651 /**
1652 * @brief Insert a C substring.
1653 * @param __pos Iterator referencing location in string to insert at.
1654 * @param __s The C string to insert.
1655 * @param __n The number of characters to insert.
1656 * @return Reference to this string.
1657 * @throw std::length_error If new length exceeds @c max_size().
1658 * @throw std::out_of_range If @a __pos is beyond the end of this
1659 * string.
1660 *
1661 * Inserts the first @a __n characters of @a __s starting at @a
1662 * __pos. If adding characters causes the length to exceed
1663 * max_size(), length_error is thrown. If @a __pos is beyond
1664 * end(), out_of_range is thrown. The value of the string
1665 * doesn't change if an error is thrown.
1666 */
1667 basic_string&
1668 insert(size_type __pos, const _CharT* __s, size_type __n)
1669 { return this->replace(__pos, size_type(0), __s, __n); }
1670
1671 /**
1672 * @brief Insert a C string.
1673 * @param __pos Iterator referencing location in string to insert at.
1674 * @param __s The C string to insert.
1675 * @return Reference to this string.
1676 * @throw std::length_error If new length exceeds @c max_size().
1677 * @throw std::out_of_range If @a pos is beyond the end of this
1678 * string.
1679 *
1680 * Inserts the first @a n characters of @a __s starting at @a __pos. If
1681 * adding characters causes the length to exceed max_size(),
1682 * length_error is thrown. If @a __pos is beyond end(), out_of_range is
1683 * thrown. The value of the string doesn't change if an error is
1684 * thrown.
1685 */
1686 basic_string&
1687 insert(size_type __pos, const _CharT* __s)
1688 {
1689 __glibcxx_requires_string(__s);
1690 return this->replace(__pos, size_type(0), __s,
1691 traits_type::length(__s));
1692 }
1693
1694 /**
1695 * @brief Insert multiple characters.
1696 * @param __pos Index in string to insert at.
1697 * @param __n Number of characters to insert
1698 * @param __c The character to insert.
1699 * @return Reference to this string.
1700 * @throw std::length_error If new length exceeds @c max_size().
1701 * @throw std::out_of_range If @a __pos is beyond the end of this
1702 * string.
1703 *
1704 * Inserts @a __n copies of character @a __c starting at index
1705 * @a __pos. If adding characters causes the length to exceed
1706 * max_size(), length_error is thrown. If @a __pos > length(),
1707 * out_of_range is thrown. The value of the string doesn't
1708 * change if an error is thrown.
1709 */
1710 basic_string&
1711 insert(size_type __pos, size_type __n, _CharT __c)
1712 { return _M_replace_aux(_M_check(__pos, "basic_string::insert"),
1713 size_type(0), __n, __c); }
1714
1715 /**
1716 * @brief Insert one character.
1717 * @param __p Iterator referencing position in string to insert at.
1718 * @param __c The character to insert.
1719 * @return Iterator referencing newly inserted char.
1720 * @throw std::length_error If new length exceeds @c max_size().
1721 *
1722 * Inserts character @a __c at position referenced by @a __p.
1723 * If adding character causes the length to exceed max_size(),
1724 * length_error is thrown. If @a __p is beyond end of string,
1725 * out_of_range is thrown. The value of the string doesn't
1726 * change if an error is thrown.
1727 */
1728 iterator
1729 insert(__const_iterator __p, _CharT __c)
1730 {
1731 _GLIBCXX_DEBUG_PEDASSERT(__p >= begin() && __p <= end());
1732 const size_type __pos = __p - begin();
1733 _M_replace_aux(__pos, size_type(0), size_type(1), __c);
1734 return iterator(_M_data() + __pos);
1735 }
1736
1737#if __cplusplus > 201402L
1738 /**
1739 * @brief Insert a string_view.
1740 * @param __pos Iterator referencing position in string to insert at.
1741 * @param __svt The object convertible to string_view to insert.
1742 * @return Reference to this string.
1743 */
1744 template<typename _Tp>
1745 _If_sv<_Tp, basic_string&>
1746 insert(size_type __pos, const _Tp& __svt)
1747 {
1748 __sv_type __sv = __svt;
1749 return this->insert(__pos, __sv.data(), __sv.size());
1750 }
1751
1752 /**
1753 * @brief Insert a string_view.
1754 * @param __pos Iterator referencing position in string to insert at.
1755 * @param __svt The object convertible to string_view to insert from.
1756 * @param __pos Iterator referencing position in string_view to insert
1757 * from.
1758 * @param __n The number of characters to insert.
1759 * @return Reference to this string.
1760 */
1761 template<typename _Tp>
1762 _If_sv<_Tp, basic_string&>
1763 insert(size_type __pos1, const _Tp& __svt,
1764 size_type __pos2, size_type __n = npos)
1765 {
1766 __sv_type __sv = __svt;
1767 return this->replace(__pos1, size_type(0), __sv.data()
1768 + __sv._M_check(__pos2, "basic_string::insert"),
1769 __sv._M_limit(__pos2, __n));
1770 }
1771#endif // C++17
1772
1773 /**
1774 * @brief Remove characters.
1775 * @param __pos Index of first character to remove (default 0).
1776 * @param __n Number of characters to remove (default remainder).
1777 * @return Reference to this string.
1778 * @throw std::out_of_range If @a pos is beyond the end of this
1779 * string.
1780 *
1781 * Removes @a __n characters from this string starting at @a
1782 * __pos. The length of the string is reduced by @a __n. If
1783 * there are < @a __n characters to remove, the remainder of
1784 * the string is truncated. If @a __p is beyond end of string,
1785 * out_of_range is thrown. The value of the string doesn't
1786 * change if an error is thrown.
1787 */
1788 basic_string&
1789 erase(size_type __pos = 0, size_type __n = npos)
1790 {
1791 _M_check(__pos, "basic_string::erase");
1792 if (__n == npos)
1793 this->_M_set_length(__pos);
1794 else if (__n != 0)
1795 this->_M_erase(__pos, _M_limit(__pos, __n));
1796 return *this;
1797 }
1798
1799 /**
1800 * @brief Remove one character.
1801 * @param __position Iterator referencing the character to remove.
1802 * @return iterator referencing same location after removal.
1803 *
1804 * Removes the character at @a __position from this string. The value
1805 * of the string doesn't change if an error is thrown.
1806 */
1807 iterator
1808 erase(__const_iterator __position)
1809 {
1810 _GLIBCXX_DEBUG_PEDASSERT(__position >= begin()
1811 && __position < end());
1812 const size_type __pos = __position - begin();
1813 this->_M_erase(__pos, size_type(1));
1814 return iterator(_M_data() + __pos);
1815 }
1816
1817 /**
1818 * @brief Remove a range of characters.
1819 * @param __first Iterator referencing the first character to remove.
1820 * @param __last Iterator referencing the end of the range.
1821 * @return Iterator referencing location of first after removal.
1822 *
1823 * Removes the characters in the range [first,last) from this string.
1824 * The value of the string doesn't change if an error is thrown.
1825 */
1826 iterator
1827 erase(__const_iterator __first, __const_iterator __last)
1828 {
1829 _GLIBCXX_DEBUG_PEDASSERT(__first >= begin() && __first <= __last
1830 && __last <= end());
1831 const size_type __pos = __first - begin();
1832 if (__last == end())
1833 this->_M_set_length(__pos);
1834 else
1835 this->_M_erase(__pos, __last - __first);
1836 return iterator(this->_M_data() + __pos);
1837 }
1838
1839#if __cplusplus >= 201103L
1840 /**
1841 * @brief Remove the last character.
1842 *
1843 * The string must be non-empty.
1844 */
1845 void
1846 pop_back() noexcept
1847 {
1848 __glibcxx_assert(!empty());
1849 _M_erase(size() - 1, 1);
1850 }
1851#endif // C++11
1852
1853 /**
1854 * @brief Replace characters with value from another string.
1855 * @param __pos Index of first character to replace.
1856 * @param __n Number of characters to be replaced.
1857 * @param __str String to insert.
1858 * @return Reference to this string.
1859 * @throw std::out_of_range If @a pos is beyond the end of this
1860 * string.
1861 * @throw std::length_error If new length exceeds @c max_size().
1862 *
1863 * Removes the characters in the range [__pos,__pos+__n) from
1864 * this string. In place, the value of @a __str is inserted.
1865 * If @a __pos is beyond end of string, out_of_range is thrown.
1866 * If the length of the result exceeds max_size(), length_error
1867 * is thrown. The value of the string doesn't change if an
1868 * error is thrown.
1869 */
1870 basic_string&
1871 replace(size_type __pos, size_type __n, const basic_string& __str)
1872 { return this->replace(__pos, __n, __str._M_data(), __str.size()); }
1873
1874 /**
1875 * @brief Replace characters with value from another string.
1876 * @param __pos1 Index of first character to replace.
1877 * @param __n1 Number of characters to be replaced.
1878 * @param __str String to insert.
1879 * @param __pos2 Index of first character of str to use.
1880 * @param __n2 Number of characters from str to use.
1881 * @return Reference to this string.
1882 * @throw std::out_of_range If @a __pos1 > size() or @a __pos2 >
1883 * __str.size().
1884 * @throw std::length_error If new length exceeds @c max_size().
1885 *
1886 * Removes the characters in the range [__pos1,__pos1 + n) from this
1887 * string. In place, the value of @a __str is inserted. If @a __pos is
1888 * beyond end of string, out_of_range is thrown. If the length of the
1889 * result exceeds max_size(), length_error is thrown. The value of the
1890 * string doesn't change if an error is thrown.
1891 */
1892 basic_string&
1893 replace(size_type __pos1, size_type __n1, const basic_string& __str,
1894 size_type __pos2, size_type __n2 = npos)
1895 { return this->replace(__pos1, __n1, __str._M_data()
1896 + __str._M_check(__pos2, "basic_string::replace"),
1897 __str._M_limit(__pos2, __n2)); }
1898
1899 /**
1900 * @brief Replace characters with value of a C substring.
1901 * @param __pos Index of first character to replace.
1902 * @param __n1 Number of characters to be replaced.
1903 * @param __s C string to insert.
1904 * @param __n2 Number of characters from @a s to use.
1905 * @return Reference to this string.
1906 * @throw std::out_of_range If @a pos1 > size().
1907 * @throw std::length_error If new length exceeds @c max_size().
1908 *
1909 * Removes the characters in the range [__pos,__pos + __n1)
1910 * from this string. In place, the first @a __n2 characters of
1911 * @a __s are inserted, or all of @a __s if @a __n2 is too large. If
1912 * @a __pos is beyond end of string, out_of_range is thrown. If
1913 * the length of result exceeds max_size(), length_error is
1914 * thrown. The value of the string doesn't change if an error
1915 * is thrown.
1916 */
1917 basic_string&
1918 replace(size_type __pos, size_type __n1, const _CharT* __s,
1919 size_type __n2)
1920 {
1921 __glibcxx_requires_string_len(__s, __n2);
1922 return _M_replace(_M_check(__pos, "basic_string::replace"),
1923 _M_limit(__pos, __n1), __s, __n2);
1924 }
1925
1926 /**
1927 * @brief Replace characters with value of a C string.
1928 * @param __pos Index of first character to replace.
1929 * @param __n1 Number of characters to be replaced.
1930 * @param __s C string to insert.
1931 * @return Reference to this string.
1932 * @throw std::out_of_range If @a pos > size().
1933 * @throw std::length_error If new length exceeds @c max_size().
1934 *
1935 * Removes the characters in the range [__pos,__pos + __n1)
1936 * from this string. In place, the characters of @a __s are
1937 * inserted. If @a __pos is beyond end of string, out_of_range
1938 * is thrown. If the length of result exceeds max_size(),
1939 * length_error is thrown. The value of the string doesn't
1940 * change if an error is thrown.
1941 */
1942 basic_string&
1943 replace(size_type __pos, size_type __n1, const _CharT* __s)
1944 {
1945 __glibcxx_requires_string(__s);
1946 return this->replace(__pos, __n1, __s, traits_type::length(__s));
1947 }
1948
1949 /**
1950 * @brief Replace characters with multiple characters.
1951 * @param __pos Index of first character to replace.
1952 * @param __n1 Number of characters to be replaced.
1953 * @param __n2 Number of characters to insert.
1954 * @param __c Character to insert.
1955 * @return Reference to this string.
1956 * @throw std::out_of_range If @a __pos > size().
1957 * @throw std::length_error If new length exceeds @c max_size().
1958 *
1959 * Removes the characters in the range [pos,pos + n1) from this
1960 * string. In place, @a __n2 copies of @a __c are inserted.
1961 * If @a __pos is beyond end of string, out_of_range is thrown.
1962 * If the length of result exceeds max_size(), length_error is
1963 * thrown. The value of the string doesn't change if an error
1964 * is thrown.
1965 */
1966 basic_string&
1967 replace(size_type __pos, size_type __n1, size_type __n2, _CharT __c)
1968 { return _M_replace_aux(_M_check(__pos, "basic_string::replace"),
1969 _M_limit(__pos, __n1), __n2, __c); }
1970
1971 /**
1972 * @brief Replace range of characters with string.
1973 * @param __i1 Iterator referencing start of range to replace.
1974 * @param __i2 Iterator referencing end of range to replace.
1975 * @param __str String value to insert.
1976 * @return Reference to this string.
1977 * @throw std::length_error If new length exceeds @c max_size().
1978 *
1979 * Removes the characters in the range [__i1,__i2). In place,
1980 * the value of @a __str is inserted. If the length of result
1981 * exceeds max_size(), length_error is thrown. The value of
1982 * the string doesn't change if an error is thrown.
1983 */
1984 basic_string&
1985 replace(__const_iterator __i1, __const_iterator __i2,
1986 const basic_string& __str)
1987 { return this->replace(__i1, __i2, __str._M_data(), __str.size()); }
1988
1989 /**
1990 * @brief Replace range of characters with C substring.
1991 * @param __i1 Iterator referencing start of range to replace.
1992 * @param __i2 Iterator referencing end of range to replace.
1993 * @param __s C string value to insert.
1994 * @param __n Number of characters from s to insert.
1995 * @return Reference to this string.
1996 * @throw std::length_error If new length exceeds @c max_size().
1997 *
1998 * Removes the characters in the range [__i1,__i2). In place,
1999 * the first @a __n characters of @a __s are inserted. If the
2000 * length of result exceeds max_size(), length_error is thrown.
2001 * The value of the string doesn't change if an error is
2002 * thrown.
2003 */
2004 basic_string&
2005 replace(__const_iterator __i1, __const_iterator __i2,
2006 const _CharT* __s, size_type __n)
2007 {
2008 _GLIBCXX_DEBUG_PEDASSERT(begin() <= __i1 && __i1 <= __i2
2009 && __i2 <= end());
2010 return this->replace(__i1 - begin(), __i2 - __i1, __s, __n);
2011 }
2012
2013 /**
2014 * @brief Replace range of characters with C string.
2015 * @param __i1 Iterator referencing start of range to replace.
2016 * @param __i2 Iterator referencing end of range to replace.
2017 * @param __s C string value to insert.
2018 * @return Reference to this string.
2019 * @throw std::length_error If new length exceeds @c max_size().
2020 *
2021 * Removes the characters in the range [__i1,__i2). In place,
2022 * the characters of @a __s are inserted. If the length of
2023 * result exceeds max_size(), length_error is thrown. The
2024 * value of the string doesn't change if an error is thrown.
2025 */
2026 basic_string&
2027 replace(__const_iterator __i1, __const_iterator __i2, const _CharT* __s)
2028 {
2029 __glibcxx_requires_string(__s);
2030 return this->replace(__i1, __i2, __s, traits_type::length(__s));
2031 }
2032
2033 /**
2034 * @brief Replace range of characters with multiple characters
2035 * @param __i1 Iterator referencing start of range to replace.
2036 * @param __i2 Iterator referencing end of range to replace.
2037 * @param __n Number of characters to insert.
2038 * @param __c Character to insert.
2039 * @return Reference to this string.
2040 * @throw std::length_error If new length exceeds @c max_size().
2041 *
2042 * Removes the characters in the range [__i1,__i2). In place,
2043 * @a __n copies of @a __c are inserted. If the length of
2044 * result exceeds max_size(), length_error is thrown. The
2045 * value of the string doesn't change if an error is thrown.
2046 */
2047 basic_string&
2048 replace(__const_iterator __i1, __const_iterator __i2, size_type __n,
2049 _CharT __c)
2050 {
2051 _GLIBCXX_DEBUG_PEDASSERT(begin() <= __i1 && __i1 <= __i2
2052 && __i2 <= end());
2053 return _M_replace_aux(__i1 - begin(), __i2 - __i1, __n, __c);
2054 }
2055
2056 /**
2057 * @brief Replace range of characters with range.
2058 * @param __i1 Iterator referencing start of range to replace.
2059 * @param __i2 Iterator referencing end of range to replace.
2060 * @param __k1 Iterator referencing start of range to insert.
2061 * @param __k2 Iterator referencing end of range to insert.
2062 * @return Reference to this string.
2063 * @throw std::length_error If new length exceeds @c max_size().
2064 *
2065 * Removes the characters in the range [__i1,__i2). In place,
2066 * characters in the range [__k1,__k2) are inserted. If the
2067 * length of result exceeds max_size(), length_error is thrown.
2068 * The value of the string doesn't change if an error is
2069 * thrown.
2070 */
2071#if __cplusplus >= 201103L
2072 template<class _InputIterator,
2073 typename = std::_RequireInputIter<_InputIterator>>
2074 basic_string&
2075 replace(const_iterator __i1, const_iterator __i2,
2076 _InputIterator __k1, _InputIterator __k2)
2077 {
2078 _GLIBCXX_DEBUG_PEDASSERT(begin() <= __i1 && __i1 <= __i2
2079 && __i2 <= end());
2080 __glibcxx_requires_valid_range(__k1, __k2);
2081 return this->_M_replace_dispatch(__i1, __i2, __k1, __k2,
2082 std::__false_type());
2083 }
2084#else
2085 template<class _InputIterator>
2086#ifdef _GLIBCXX_DISAMBIGUATE_REPLACE_INST
2087 typename __enable_if_not_native_iterator<_InputIterator>::__type
2088#else
2089 basic_string&
2090#endif
2091 replace(iterator __i1, iterator __i2,
2092 _InputIterator __k1, _InputIterator __k2)
2093 {
2094 _GLIBCXX_DEBUG_PEDASSERT(begin() <= __i1 && __i1 <= __i2
2095 && __i2 <= end());
2096 __glibcxx_requires_valid_range(__k1, __k2);
2097 typedef typename std::__is_integer<_InputIterator>::__type _Integral;
2098 return _M_replace_dispatch(__i1, __i2, __k1, __k2, _Integral());
2099 }
2100#endif
2101
2102 // Specializations for the common case of pointer and iterator:
2103 // useful to avoid the overhead of temporary buffering in _M_replace.
2104 basic_string&
2105 replace(__const_iterator __i1, __const_iterator __i2,
2106 _CharT* __k1, _CharT* __k2)
2107 {
2108 _GLIBCXX_DEBUG_PEDASSERT(begin() <= __i1 && __i1 <= __i2
2109 && __i2 <= end());
2110 __glibcxx_requires_valid_range(__k1, __k2);
2111 return this->replace(__i1 - begin(), __i2 - __i1,
2112 __k1, __k2 - __k1);
2113 }
2114
2115 basic_string&
2116 replace(__const_iterator __i1, __const_iterator __i2,
2117 const _CharT* __k1, const _CharT* __k2)
2118 {
2119 _GLIBCXX_DEBUG_PEDASSERT(begin() <= __i1 && __i1 <= __i2
2120 && __i2 <= end());
2121 __glibcxx_requires_valid_range(__k1, __k2);
2122 return this->replace(__i1 - begin(), __i2 - __i1,
2123 __k1, __k2 - __k1);
2124 }
2125
2126 basic_string&
2127 replace(__const_iterator __i1, __const_iterator __i2,
2128 iterator __k1, iterator __k2)
2129 {
2130 _GLIBCXX_DEBUG_PEDASSERT(begin() <= __i1 && __i1 <= __i2
2131 && __i2 <= end());
2132 __glibcxx_requires_valid_range(__k1, __k2);
2133 return this->replace(__i1 - begin(), __i2 - __i1,
2134 __k1.base(), __k2 - __k1);
2135 }
2136
2137 basic_string&
2138 replace(__const_iterator __i1, __const_iterator __i2,
2139 const_iterator __k1, const_iterator __k2)
2140 {
2141 _GLIBCXX_DEBUG_PEDASSERT(begin() <= __i1 && __i1 <= __i2
2142 && __i2 <= end());
2143 __glibcxx_requires_valid_range(__k1, __k2);
2144 return this->replace(__i1 - begin(), __i2 - __i1,
2145 __k1.base(), __k2 - __k1);
2146 }
2147
2148#if __cplusplus >= 201103L
2149 /**
2150 * @brief Replace range of characters with initializer_list.
2151 * @param __i1 Iterator referencing start of range to replace.
2152 * @param __i2 Iterator referencing end of range to replace.
2153 * @param __l The initializer_list of characters to insert.
2154 * @return Reference to this string.
2155 * @throw std::length_error If new length exceeds @c max_size().
2156 *
2157 * Removes the characters in the range [__i1,__i2). In place,
2158 * characters in the range [__k1,__k2) are inserted. If the
2159 * length of result exceeds max_size(), length_error is thrown.
2160 * The value of the string doesn't change if an error is
2161 * thrown.
2162 */
2163 basic_string& replace(const_iterator __i1, const_iterator __i2,
2164 initializer_list<_CharT> __l)
2165 { return this->replace(__i1, __i2, __l.begin(), __l.size()); }
2166#endif // C++11
2167
2168#if __cplusplus > 201402L
2169 /**
2170 * @brief Replace range of characters with string_view.
2171 * @param __pos The position to replace at.
2172 * @param __n The number of characters to replace.
2173 * @param __svt The object convertible to string_view to insert.
2174 * @return Reference to this string.
2175 */
2176 template<typename _Tp>
2177 _If_sv<_Tp, basic_string&>
2178 replace(size_type __pos, size_type __n, const _Tp& __svt)
2179 {
2180 __sv_type __sv = __svt;
2181 return this->replace(__pos, __n, __sv.data(), __sv.size());
2182 }
2183
2184 /**
2185 * @brief Replace range of characters with string_view.
2186 * @param __pos1 The position to replace at.
2187 * @param __n1 The number of characters to replace.
2188 * @param __svt The object convertible to string_view to insert from.
2189 * @param __pos2 The position in the string_view to insert from.
2190 * @param __n2 The number of characters to insert.
2191 * @return Reference to this string.
2192 */
2193 template<typename _Tp>
2194 _If_sv<_Tp, basic_string&>
2195 replace(size_type __pos1, size_type __n1, const _Tp& __svt,
2196 size_type __pos2, size_type __n2 = npos)
2197 {
2198 __sv_type __sv = __svt;
2199 return this->replace(__pos1, __n1, __sv.data()
2200 + __sv._M_check(__pos2, "basic_string::replace"),
2201 __sv._M_limit(__pos2, __n2));
2202 }
2203
2204 /**
2205 * @brief Replace range of characters with string_view.
2206 * @param __i1 An iterator referencing the start position
2207 to replace at.
2208 * @param __i2 An iterator referencing the end position
2209 for the replace.
2210 * @param __svt The object convertible to string_view to insert from.
2211 * @return Reference to this string.
2212 */
2213 template<typename _Tp>
2214 _If_sv<_Tp, basic_string&>
2215 replace(const_iterator __i1, const_iterator __i2, const _Tp& __svt)
2216 {
2217 __sv_type __sv = __svt;
2218 return this->replace(__i1 - begin(), __i2 - __i1, __sv);
2219 }
2220#endif // C++17
2221
2222 private:
2223 template<class _Integer>
2224 basic_string&
2225 _M_replace_dispatch(const_iterator __i1, const_iterator __i2,
2226 _Integer __n, _Integer __val, __true_type)
2227 { return _M_replace_aux(__i1 - begin(), __i2 - __i1, __n, __val); }
2228
2229 template<class _InputIterator>
2230 basic_string&
2231 _M_replace_dispatch(const_iterator __i1, const_iterator __i2,
2232 _InputIterator __k1, _InputIterator __k2,
2233 __false_type);
2234
2235 basic_string&
2236 _M_replace_aux(size_type __pos1, size_type __n1, size_type __n2,
2237 _CharT __c);
2238
2239 basic_string&
2240 _M_replace(size_type __pos, size_type __len1, const _CharT* __s,
2241 const size_type __len2);
2242
2243 basic_string&
2244 _M_append(const _CharT* __s, size_type __n);
2245
2246 public:
2247
2248 /**
2249 * @brief Copy substring into C string.
2250 * @param __s C string to copy value into.
2251 * @param __n Number of characters to copy.
2252 * @param __pos Index of first character to copy.
2253 * @return Number of characters actually copied
2254 * @throw std::out_of_range If __pos > size().
2255 *
2256 * Copies up to @a __n characters starting at @a __pos into the
2257 * C string @a __s. If @a __pos is %greater than size(),
2258 * out_of_range is thrown.
2259 */
2260 size_type
2261 copy(_CharT* __s, size_type __n, size_type __pos = 0) const;
2262
2263 /**
2264 * @brief Swap contents with another string.
2265 * @param __s String to swap with.
2266 *
2267 * Exchanges the contents of this string with that of @a __s in constant
2268 * time.
2269 */
2270 void
2271 swap(basic_string& __s) _GLIBCXX_NOEXCEPT;
2272
2273 // String operations:
2274 /**
2275 * @brief Return const pointer to null-terminated contents.
2276 *
2277 * This is a handle to internal data. Do not modify or dire things may
2278 * happen.
2279 */
2280 const _CharT*
2281 c_str() const _GLIBCXX_NOEXCEPT
2282 { return _M_data(); }
2283
2284 /**
2285 * @brief Return const pointer to contents.
2286 *
2287 * This is a pointer to internal data. It is undefined to modify
2288 * the contents through the returned pointer. To get a pointer that
2289 * allows modifying the contents use @c &str[0] instead,
2290 * (or in C++17 the non-const @c str.data() overload).
2291 */
2292 const _CharT*
2293 data() const _GLIBCXX_NOEXCEPT
2294 { return _M_data(); }
2295
2296#if __cplusplus > 201402L
2297 /**
2298 * @brief Return non-const pointer to contents.
2299 *
2300 * This is a pointer to the character sequence held by the string.
2301 * Modifying the characters in the sequence is allowed.
2302 */
2303 _CharT*
2304 data() noexcept
2305 { return _M_data(); }
2306#endif
2307
2308 /**
2309 * @brief Return copy of allocator used to construct this string.
2310 */
2311 allocator_type
2312 get_allocator() const _GLIBCXX_NOEXCEPT
2313 { return _M_get_allocator(); }
2314
2315 /**
2316 * @brief Find position of a C substring.
2317 * @param __s C string to locate.
2318 * @param __pos Index of character to search from.
2319 * @param __n Number of characters from @a s to search for.
2320 * @return Index of start of first occurrence.
2321 *
2322 * Starting from @a __pos, searches forward for the first @a
2323 * __n characters in @a __s within this string. If found,
2324 * returns the index where it begins. If not found, returns
2325 * npos.
2326 */
2327 size_type
2328 find(const _CharT* __s, size_type __pos, size_type __n) const
2329 _GLIBCXX_NOEXCEPT;
2330
2331 /**
2332 * @brief Find position of a string.
2333 * @param __str String to locate.
2334 * @param __pos Index of character to search from (default 0).
2335 * @return Index of start of first occurrence.
2336 *
2337 * Starting from @a __pos, searches forward for value of @a __str within
2338 * this string. If found, returns the index where it begins. If not
2339 * found, returns npos.
2340 */
2341 size_type
2342 find(const basic_string& __str, size_type __pos = 0) const
2343 _GLIBCXX_NOEXCEPT
2344 { return this->find(__str.data(), __pos, __str.size()); }
2345
2346#if __cplusplus > 201402L
2347 /**
2348 * @brief Find position of a string_view.
2349 * @param __svt The object convertible to string_view to locate.
2350 * @param __pos Index of character to search from (default 0).
2351 * @return Index of start of first occurrence.
2352 */
2353 template<typename _Tp>
2354 _If_sv<_Tp, size_type>
2355 find(const _Tp& __svt, size_type __pos = 0) const
2356 noexcept(is_same<_Tp, __sv_type>::value)
2357 {
2358 __sv_type __sv = __svt;
2359 return this->find(__sv.data(), __pos, __sv.size());
2360 }
2361#endif // C++17
2362
2363 /**
2364 * @brief Find position of a C string.
2365 * @param __s C string to locate.
2366 * @param __pos Index of character to search from (default 0).
2367 * @return Index of start of first occurrence.
2368 *
2369 * Starting from @a __pos, searches forward for the value of @a
2370 * __s within this string. If found, returns the index where
2371 * it begins. If not found, returns npos.
2372 */
2373 size_type
2374 find(const _CharT* __s, size_type __pos = 0) const _GLIBCXX_NOEXCEPT
2375 {
2376 __glibcxx_requires_string(__s);
2377 return this->find(__s, __pos, traits_type::length(__s));
2378 }
2379
2380 /**
2381 * @brief Find position of a character.
2382 * @param __c Character to locate.
2383 * @param __pos Index of character to search from (default 0).
2384 * @return Index of first occurrence.
2385 *
2386 * Starting from @a __pos, searches forward for @a __c within
2387 * this string. If found, returns the index where it was
2388 * found. If not found, returns npos.
2389 */
2390 size_type
2391 find(_CharT __c, size_type __pos = 0) const _GLIBCXX_NOEXCEPT;
2392
2393 /**
2394 * @brief Find last position of a string.
2395 * @param __str String to locate.
2396 * @param __pos Index of character to search back from (default end).
2397 * @return Index of start of last occurrence.
2398 *
2399 * Starting from @a __pos, searches backward for value of @a
2400 * __str within this string. If found, returns the index where
2401 * it begins. If not found, returns npos.
2402 */
2403 size_type
2404 rfind(const basic_string& __str, size_type __pos = npos) const
2405 _GLIBCXX_NOEXCEPT
2406 { return this->rfind(__str.data(), __pos, __str.size()); }
2407
2408#if __cplusplus > 201402L
2409 /**
2410 * @brief Find last position of a string_view.
2411 * @param __svt The object convertible to string_view to locate.
2412 * @param __pos Index of character to search back from (default end).
2413 * @return Index of start of last occurrence.
2414 */
2415 template<typename _Tp>
2416 _If_sv<_Tp, size_type>
2417 rfind(const _Tp& __svt, size_type __pos = npos) const
2418 noexcept(is_same<_Tp, __sv_type>::value)
2419 {
2420 __sv_type __sv = __svt;
2421 return this->rfind(__sv.data(), __pos, __sv.size());
2422 }
2423#endif // C++17
2424
2425 /**
2426 * @brief Find last position of a C substring.
2427 * @param __s C string to locate.
2428 * @param __pos Index of character to search back from.
2429 * @param __n Number of characters from s to search for.
2430 * @return Index of start of last occurrence.
2431 *
2432 * Starting from @a __pos, searches backward for the first @a
2433 * __n characters in @a __s within this string. If found,
2434 * returns the index where it begins. If not found, returns
2435 * npos.
2436 */
2437 size_type
2438 rfind(const _CharT* __s, size_type __pos, size_type __n) const
2439 _GLIBCXX_NOEXCEPT;
2440
2441 /**
2442 * @brief Find last position of a C string.
2443 * @param __s C string to locate.
2444 * @param __pos Index of character to start search at (default end).
2445 * @return Index of start of last occurrence.
2446 *
2447 * Starting from @a __pos, searches backward for the value of
2448 * @a __s within this string. If found, returns the index
2449 * where it begins. If not found, returns npos.
2450 */
2451 size_type
2452 rfind(const _CharT* __s, size_type __pos = npos) const
2453 {
2454 __glibcxx_requires_string(__s);
2455 return this->rfind(__s, __pos, traits_type::length(__s));
2456 }
2457
2458 /**
2459 * @brief Find last position of a character.
2460 * @param __c Character to locate.
2461 * @param __pos Index of character to search back from (default end).
2462 * @return Index of last occurrence.
2463 *
2464 * Starting from @a __pos, searches backward for @a __c within
2465 * this string. If found, returns the index where it was
2466 * found. If not found, returns npos.
2467 */
2468 size_type
2469 rfind(_CharT __c, size_type __pos = npos) const _GLIBCXX_NOEXCEPT;
2470
2471 /**
2472 * @brief Find position of a character of string.
2473 * @param __str String containing characters to locate.
2474 * @param __pos Index of character to search from (default 0).
2475 * @return Index of first occurrence.
2476 *
2477 * Starting from @a __pos, searches forward for one of the
2478 * characters of @a __str within this string. If found,
2479 * returns the index where it was found. If not found, returns
2480 * npos.
2481 */
2482 size_type
2483 find_first_of(const basic_string& __str, size_type __pos = 0) const
2484 _GLIBCXX_NOEXCEPT
2485 { return this->find_first_of(__str.data(), __pos, __str.size()); }
2486
2487#if __cplusplus > 201402L
2488 /**
2489 * @brief Find position of a character of a string_view.
2490 * @param __svt An object convertible to string_view containing
2491 * characters to locate.
2492 * @param __pos Index of character to search from (default 0).
2493 * @return Index of first occurrence.
2494 */
2495 template<typename _Tp>
2496 _If_sv<_Tp, size_type>
2497 find_first_of(const _Tp& __svt, size_type __pos = 0) const
2498 noexcept(is_same<_Tp, __sv_type>::value)
2499 {
2500 __sv_type __sv = __svt;
2501 return this->find_first_of(__sv.data(), __pos, __sv.size());
2502 }
2503#endif // C++17
2504
2505 /**
2506 * @brief Find position of a character of C substring.
2507 * @param __s String containing characters to locate.
2508 * @param __pos Index of character to search from.
2509 * @param __n Number of characters from s to search for.
2510 * @return Index of first occurrence.
2511 *
2512 * Starting from @a __pos, searches forward for one of the
2513 * first @a __n characters of @a __s within this string. If
2514 * found, returns the index where it was found. If not found,
2515 * returns npos.
2516 */
2517 size_type
2518 find_first_of(const _CharT* __s, size_type __pos, size_type __n) const
2519 _GLIBCXX_NOEXCEPT;
2520
2521 /**
2522 * @brief Find position of a character of C string.
2523 * @param __s String containing characters to locate.
2524 * @param __pos Index of character to search from (default 0).
2525 * @return Index of first occurrence.
2526 *
2527 * Starting from @a __pos, searches forward for one of the
2528 * characters of @a __s within this string. If found, returns
2529 * the index where it was found. If not found, returns npos.
2530 */
2531 size_type
2532 find_first_of(const _CharT* __s, size_type __pos = 0) const
2533 _GLIBCXX_NOEXCEPT
2534 {
2535 __glibcxx_requires_string(__s);
2536 return this->find_first_of(__s, __pos, traits_type::length(__s));
2537 }
2538
2539 /**
2540 * @brief Find position of a character.
2541 * @param __c Character to locate.
2542 * @param __pos Index of character to search from (default 0).
2543 * @return Index of first occurrence.
2544 *
2545 * Starting from @a __pos, searches forward for the character
2546 * @a __c within this string. If found, returns the index
2547 * where it was found. If not found, returns npos.
2548 *
2549 * Note: equivalent to find(__c, __pos).
2550 */
2551 size_type
2552 find_first_of(_CharT __c, size_type __pos = 0) const _GLIBCXX_NOEXCEPT
2553 { return this->find(__c, __pos); }
2554
2555 /**
2556 * @brief Find last position of a character of string.
2557 * @param __str String containing characters to locate.
2558 * @param __pos Index of character to search back from (default end).
2559 * @return Index of last occurrence.
2560 *
2561 * Starting from @a __pos, searches backward for one of the
2562 * characters of @a __str within this string. If found,
2563 * returns the index where it was found. If not found, returns
2564 * npos.
2565 */
2566 size_type
2567 find_last_of(const basic_string& __str, size_type __pos = npos) const
2568 _GLIBCXX_NOEXCEPT
2569 { return this->find_last_of(__str.data(), __pos, __str.size()); }
2570
2571#if __cplusplus > 201402L
2572 /**
2573 * @brief Find last position of a character of string.
2574 * @param __svt An object convertible to string_view containing
2575 * characters to locate.
2576 * @param __pos Index of character to search back from (default end).
2577 * @return Index of last occurrence.
2578 */
2579 template<typename _Tp>
2580 _If_sv<_Tp, size_type>
2581 find_last_of(const _Tp& __svt, size_type __pos = npos) const
2582 noexcept(is_same<_Tp, __sv_type>::value)
2583 {
2584 __sv_type __sv = __svt;
2585 return this->find_last_of(__sv.data(), __pos, __sv.size());
2586 }
2587#endif // C++17
2588
2589 /**
2590 * @brief Find last position of a character of C substring.
2591 * @param __s C string containing characters to locate.
2592 * @param __pos Index of character to search back from.
2593 * @param __n Number of characters from s to search for.
2594 * @return Index of last occurrence.
2595 *
2596 * Starting from @a __pos, searches backward for one of the
2597 * first @a __n characters of @a __s within this string. If
2598 * found, returns the index where it was found. If not found,
2599 * returns npos.
2600 */
2601 size_type
2602 find_last_of(const _CharT* __s, size_type __pos, size_type __n) const
2603 _GLIBCXX_NOEXCEPT;
2604
2605 /**
2606 * @brief Find last position of a character of C string.
2607 * @param __s C string containing characters to locate.
2608 * @param __pos Index of character to search back from (default end).
2609 * @return Index of last occurrence.
2610 *
2611 * Starting from @a __pos, searches backward for one of the
2612 * characters of @a __s within this string. If found, returns
2613 * the index where it was found. If not found, returns npos.
2614 */
2615 size_type
2616 find_last_of(const _CharT* __s, size_type __pos = npos) const
2617 _GLIBCXX_NOEXCEPT
2618 {
2619 __glibcxx_requires_string(__s);
2620 return this->find_last_of(__s, __pos, traits_type::length(__s));
2621 }
2622
2623 /**
2624 * @brief Find last position of a character.
2625 * @param __c Character to locate.
2626 * @param __pos Index of character to search back from (default end).
2627 * @return Index of last occurrence.
2628 *
2629 * Starting from @a __pos, searches backward for @a __c within
2630 * this string. If found, returns the index where it was
2631 * found. If not found, returns npos.
2632 *
2633 * Note: equivalent to rfind(__c, __pos).
2634 */
2635 size_type
2636 find_last_of(_CharT __c, size_type __pos = npos) const _GLIBCXX_NOEXCEPT
2637 { return this->rfind(__c, __pos); }
2638
2639 /**
2640 * @brief Find position of a character not in string.
2641 * @param __str String containing characters to avoid.
2642 * @param __pos Index of character to search from (default 0).
2643 * @return Index of first occurrence.
2644 *
2645 * Starting from @a __pos, searches forward for a character not contained
2646 * in @a __str within this string. If found, returns the index where it
2647 * was found. If not found, returns npos.
2648 */
2649 size_type
2650 find_first_not_of(const basic_string& __str, size_type __pos = 0) const
2651 _GLIBCXX_NOEXCEPT
2652 { return this->find_first_not_of(__str.data(), __pos, __str.size()); }
2653
2654#if __cplusplus > 201402L
2655 /**
2656 * @brief Find position of a character not in a string_view.
2657 * @param __svt A object convertible to string_view containing
2658 * characters to avoid.
2659 * @param __pos Index of character to search from (default 0).
2660 * @return Index of first occurrence.
2661 */
2662 template<typename _Tp>
2663 _If_sv<_Tp, size_type>
2664 find_first_not_of(const _Tp& __svt, size_type __pos = 0) const
2665 noexcept(is_same<_Tp, __sv_type>::value)
2666 {
2667 __sv_type __sv = __svt;
2668 return this->find_first_not_of(__sv.data(), __pos, __sv.size());
2669 }
2670#endif // C++17
2671
2672 /**
2673 * @brief Find position of a character not in C substring.
2674 * @param __s C string containing characters to avoid.
2675 * @param __pos Index of character to search from.
2676 * @param __n Number of characters from __s to consider.
2677 * @return Index of first occurrence.
2678 *
2679 * Starting from @a __pos, searches forward for a character not
2680 * contained in the first @a __n characters of @a __s within
2681 * this string. If found, returns the index where it was
2682 * found. If not found, returns npos.
2683 */
2684 size_type
2685 find_first_not_of(const _CharT* __s, size_type __pos,
2686 size_type __n) const _GLIBCXX_NOEXCEPT;
2687
2688 /**
2689 * @brief Find position of a character not in C string.
2690 * @param __s C string containing characters to avoid.
2691 * @param __pos Index of character to search from (default 0).
2692 * @return Index of first occurrence.
2693 *
2694 * Starting from @a __pos, searches forward for a character not
2695 * contained in @a __s within this string. If found, returns
2696 * the index where it was found. If not found, returns npos.
2697 */
2698 size_type
2699 find_first_not_of(const _CharT* __s, size_type __pos = 0) const
2700 _GLIBCXX_NOEXCEPT
2701 {
2702 __glibcxx_requires_string(__s);
2703 return this->find_first_not_of(__s, __pos, traits_type::length(__s));
2704 }
2705
2706 /**
2707 * @brief Find position of a different character.
2708 * @param __c Character to avoid.
2709 * @param __pos Index of character to search from (default 0).
2710 * @return Index of first occurrence.
2711 *
2712 * Starting from @a __pos, searches forward for a character
2713 * other than @a __c within this string. If found, returns the
2714 * index where it was found. If not found, returns npos.
2715 */
2716 size_type
2717 find_first_not_of(_CharT __c, size_type __pos = 0) const
2718 _GLIBCXX_NOEXCEPT;
2719
2720 /**
2721 * @brief Find last position of a character not in string.
2722 * @param __str String containing characters to avoid.
2723 * @param __pos Index of character to search back from (default end).
2724 * @return Index of last occurrence.
2725 *
2726 * Starting from @a __pos, searches backward for a character
2727 * not contained in @a __str within this string. If found,
2728 * returns the index where it was found. If not found, returns
2729 * npos.
2730 */
2731 size_type
2732 find_last_not_of(const basic_string& __str, size_type __pos = npos) const
2733 _GLIBCXX_NOEXCEPT
2734 { return this->find_last_not_of(__str.data(), __pos, __str.size()); }
2735
2736#if __cplusplus > 201402L
2737 /**
2738 * @brief Find last position of a character not in a string_view.
2739 * @param __svt An object convertible to string_view containing
2740 * characters to avoid.
2741 * @param __pos Index of character to search back from (default end).
2742 * @return Index of last occurrence.
2743 */
2744 template<typename _Tp>
2745 _If_sv<_Tp, size_type>
2746 find_last_not_of(const _Tp& __svt, size_type __pos = npos) const
2747 noexcept(is_same<_Tp, __sv_type>::value)
2748 {
2749 __sv_type __sv = __svt;
2750 return this->find_last_not_of(__sv.data(), __pos, __sv.size());
2751 }
2752#endif // C++17
2753
2754 /**
2755 * @brief Find last position of a character not in C substring.
2756 * @param __s C string containing characters to avoid.
2757 * @param __pos Index of character to search back from.
2758 * @param __n Number of characters from s to consider.
2759 * @return Index of last occurrence.
2760 *
2761 * Starting from @a __pos, searches backward for a character not
2762 * contained in the first @a __n characters of @a __s within this string.
2763 * If found, returns the index where it was found. If not found,
2764 * returns npos.
2765 */
2766 size_type
2767 find_last_not_of(const _CharT* __s, size_type __pos,
2768 size_type __n) const _GLIBCXX_NOEXCEPT;
2769 /**
2770 * @brief Find last position of a character not in C string.
2771 * @param __s C string containing characters to avoid.
2772 * @param __pos Index of character to search back from (default end).
2773 * @return Index of last occurrence.
2774 *
2775 * Starting from @a __pos, searches backward for a character
2776 * not contained in @a __s within this string. If found,
2777 * returns the index where it was found. If not found, returns
2778 * npos.
2779 */
2780 size_type
2781 find_last_not_of(const _CharT* __s, size_type __pos = npos) const
2782 _GLIBCXX_NOEXCEPT
2783 {
2784 __glibcxx_requires_string(__s);
2785 return this->find_last_not_of(__s, __pos, traits_type::length(__s));
2786 }
2787
2788 /**
2789 * @brief Find last position of a different character.
2790 * @param __c Character to avoid.
2791 * @param __pos Index of character to search back from (default end).
2792 * @return Index of last occurrence.
2793 *
2794 * Starting from @a __pos, searches backward for a character other than
2795 * @a __c within this string. If found, returns the index where it was
2796 * found. If not found, returns npos.
2797 */
2798 size_type
2799 find_last_not_of(_CharT __c, size_type __pos = npos) const
2800 _GLIBCXX_NOEXCEPT;
2801
2802 /**
2803 * @brief Get a substring.
2804 * @param __pos Index of first character (default 0).
2805 * @param __n Number of characters in substring (default remainder).
2806 * @return The new string.
2807 * @throw std::out_of_range If __pos > size().
2808 *
2809 * Construct and return a new string using the @a __n
2810 * characters starting at @a __pos. If the string is too
2811 * short, use the remainder of the characters. If @a __pos is
2812 * beyond the end of the string, out_of_range is thrown.
2813 */
2814 basic_string
2815 substr(size_type __pos = 0, size_type __n = npos) const
2816 { return basic_string(*this,
2817 _M_check(__pos, "basic_string::substr"), __n); }
2818
2819 /**
2820 * @brief Compare to a string.
2821 * @param __str String to compare against.
2822 * @return Integer < 0, 0, or > 0.
2823 *
2824 * Returns an integer < 0 if this string is ordered before @a
2825 * __str, 0 if their values are equivalent, or > 0 if this
2826 * string is ordered after @a __str. Determines the effective
2827 * length rlen of the strings to compare as the smallest of
2828 * size() and str.size(). The function then compares the two
2829 * strings by calling traits::compare(data(), str.data(),rlen).
2830 * If the result of the comparison is nonzero returns it,
2831 * otherwise the shorter one is ordered first.
2832 */
2833 int
2834 compare(const basic_string& __str) const
2835 {
2836 const size_type __size = this->size();
2837 const size_type __osize = __str.size();
2838 const size_type __len = std::min(__size, __osize);
2839
2840 int __r = traits_type::compare(_M_data(), __str.data(), __len);
2841 if (!__r)
2842 __r = _S_compare(__size, __osize);
2843 return __r;
2844 }
2845
2846#if __cplusplus > 201402L
2847 /**
2848 * @brief Compare to a string_view.
2849 * @param __svt An object convertible to string_view to compare against.
2850 * @return Integer < 0, 0, or > 0.
2851 */
2852 template<typename _Tp>
2853 _If_sv<_Tp, int>
2854 compare(const _Tp& __svt) const
2855 noexcept(is_same<_Tp, __sv_type>::value)
2856 {
2857 __sv_type __sv = __svt;
2858 const size_type __size = this->size();
2859 const size_type __osize = __sv.size();
2860 const size_type __len = std::min(__size, __osize);
2861
2862 int __r = traits_type::compare(_M_data(), __sv.data(), __len);
2863 if (!__r)
2864 __r = _S_compare(__size, __osize);
2865 return __r;
2866 }
2867
2868 /**
2869 * @brief Compare to a string_view.
2870 * @param __pos A position in the string to start comparing from.
2871 * @param __n The number of characters to compare.
2872 * @param __svt An object convertible to string_view to compare
2873 * against.
2874 * @return Integer < 0, 0, or > 0.
2875 */
2876 template<typename _Tp>
2877 _If_sv<_Tp, int>
2878 compare(size_type __pos, size_type __n, const _Tp& __svt) const
2879 noexcept(is_same<_Tp, __sv_type>::value)
2880 {
2881 __sv_type __sv = __svt;
2882 return __sv_type(*this).substr(__pos, __n).compare(__sv);
2883 }
2884
2885 /**
2886 * @brief Compare to a string_view.
2887 * @param __pos1 A position in the string to start comparing from.
2888 * @param __n1 The number of characters to compare.
2889 * @param __svt An object convertible to string_view to compare
2890 * against.
2891 * @param __pos2 A position in the string_view to start comparing from.
2892 * @param __n2 The number of characters to compare.
2893 * @return Integer < 0, 0, or > 0.
2894 */
2895 template<typename _Tp>
2896 _If_sv<_Tp, int>
2897 compare(size_type __pos1, size_type __n1, const _Tp& __svt,
2898 size_type __pos2, size_type __n2 = npos) const
2899 noexcept(is_same<_Tp, __sv_type>::value)
2900 {
2901 __sv_type __sv = __svt;
2902 return __sv_type(*this)
2903 .substr(__pos1, __n1).compare(__sv.substr(__pos2, __n2));
2904 }
2905#endif // C++17
2906
2907 /**
2908 * @brief Compare substring to a string.
2909 * @param __pos Index of first character of substring.
2910 * @param __n Number of characters in substring.
2911 * @param __str String to compare against.
2912 * @return Integer < 0, 0, or > 0.
2913 *
2914 * Form the substring of this string from the @a __n characters
2915 * starting at @a __pos. Returns an integer < 0 if the
2916 * substring is ordered before @a __str, 0 if their values are
2917 * equivalent, or > 0 if the substring is ordered after @a
2918 * __str. Determines the effective length rlen of the strings
2919 * to compare as the smallest of the length of the substring
2920 * and @a __str.size(). The function then compares the two
2921 * strings by calling
2922 * traits::compare(substring.data(),str.data(),rlen). If the
2923 * result of the comparison is nonzero returns it, otherwise
2924 * the shorter one is ordered first.
2925 */
2926 int
2927 compare(size_type __pos, size_type __n, const basic_string& __str) const;
2928
2929 /**
2930 * @brief Compare substring to a substring.
2931 * @param __pos1 Index of first character of substring.
2932 * @param __n1 Number of characters in substring.
2933 * @param __str String to compare against.
2934 * @param __pos2 Index of first character of substring of str.
2935 * @param __n2 Number of characters in substring of str.
2936 * @return Integer < 0, 0, or > 0.
2937 *
2938 * Form the substring of this string from the @a __n1
2939 * characters starting at @a __pos1. Form the substring of @a
2940 * __str from the @a __n2 characters starting at @a __pos2.
2941 * Returns an integer < 0 if this substring is ordered before
2942 * the substring of @a __str, 0 if their values are equivalent,
2943 * or > 0 if this substring is ordered after the substring of
2944 * @a __str. Determines the effective length rlen of the
2945 * strings to compare as the smallest of the lengths of the
2946 * substrings. The function then compares the two strings by
2947 * calling
2948 * traits::compare(substring.data(),str.substr(pos2,n2).data(),rlen).
2949 * If the result of the comparison is nonzero returns it,
2950 * otherwise the shorter one is ordered first.
2951 */
2952 int
2953 compare(size_type __pos1, size_type __n1, const basic_string& __str,
2954 size_type __pos2, size_type __n2 = npos) const;
2955
2956 /**
2957 * @brief Compare to a C string.
2958 * @param __s C string to compare against.
2959 * @return Integer < 0, 0, or > 0.
2960 *
2961 * Returns an integer < 0 if this string is ordered before @a __s, 0 if
2962 * their values are equivalent, or > 0 if this string is ordered after
2963 * @a __s. Determines the effective length rlen of the strings to
2964 * compare as the smallest of size() and the length of a string
2965 * constructed from @a __s. The function then compares the two strings
2966 * by calling traits::compare(data(),s,rlen). If the result of the
2967 * comparison is nonzero returns it, otherwise the shorter one is
2968 * ordered first.
2969 */
2970 int
2971 compare(const _CharT* __s) const _GLIBCXX_NOEXCEPT;
2972
2973 // _GLIBCXX_RESOLVE_LIB_DEFECTS
2974 // 5 String::compare specification questionable
2975 /**
2976 * @brief Compare substring to a C string.
2977 * @param __pos Index of first character of substring.
2978 * @param __n1 Number of characters in substring.
2979 * @param __s C string to compare against.
2980 * @return Integer < 0, 0, or > 0.
2981 *
2982 * Form the substring of this string from the @a __n1
2983 * characters starting at @a pos. Returns an integer < 0 if
2984 * the substring is ordered before @a __s, 0 if their values
2985 * are equivalent, or > 0 if the substring is ordered after @a
2986 * __s. Determines the effective length rlen of the strings to
2987 * compare as the smallest of the length of the substring and
2988 * the length of a string constructed from @a __s. The
2989 * function then compares the two string by calling
2990 * traits::compare(substring.data(),__s,rlen). If the result of
2991 * the comparison is nonzero returns it, otherwise the shorter
2992 * one is ordered first.
2993 */
2994 int
2995 compare(size_type __pos, size_type __n1, const _CharT* __s) const;
2996
2997 /**
2998 * @brief Compare substring against a character %array.
2999 * @param __pos Index of first character of substring.
3000 * @param __n1 Number of characters in substring.
3001 * @param __s character %array to compare against.
3002 * @param __n2 Number of characters of s.
3003 * @return Integer < 0, 0, or > 0.
3004 *
3005 * Form the substring of this string from the @a __n1
3006 * characters starting at @a __pos. Form a string from the
3007 * first @a __n2 characters of @a __s. Returns an integer < 0
3008 * if this substring is ordered before the string from @a __s,
3009 * 0 if their values are equivalent, or > 0 if this substring
3010 * is ordered after the string from @a __s. Determines the
3011 * effective length rlen of the strings to compare as the
3012 * smallest of the length of the substring and @a __n2. The
3013 * function then compares the two strings by calling
3014 * traits::compare(substring.data(),s,rlen). If the result of
3015 * the comparison is nonzero returns it, otherwise the shorter
3016 * one is ordered first.
3017 *
3018 * NB: s must have at least n2 characters, &apos;\\0&apos; has
3019 * no special meaning.
3020 */
3021 int
3022 compare(size_type __pos, size_type __n1, const _CharT* __s,
3023 size_type __n2) const;
3024
3025 // Allow basic_stringbuf::__xfer_bufptrs to call _M_length:
3026 template<typename, typename, typename> friend class basic_stringbuf;
3027 };
3028_GLIBCXX_END_NAMESPACE_CXX11
3029#else // !_GLIBCXX_USE_CXX11_ABI
3030 // Reference-counted COW string implentation
3031
3032 /**
3033 * @class basic_string basic_string.h <string>
3034 * @brief Managing sequences of characters and character-like objects.
3035 *
3036 * @ingroup strings
3037 * @ingroup sequences
3038 *
3039 * @tparam _CharT Type of character
3040 * @tparam _Traits Traits for character type, defaults to
3041 * char_traits<_CharT>.
3042 * @tparam _Alloc Allocator type, defaults to allocator<_CharT>.
3043 *
3044 * Meets the requirements of a <a href="tables.html#65">container</a>, a
3045 * <a href="tables.html#66">reversible container</a>, and a
3046 * <a href="tables.html#67">sequence</a>. Of the
3047 * <a href="tables.html#68">optional sequence requirements</a>, only
3048 * @c push_back, @c at, and @c %array access are supported.
3049 *
3050 * @doctodo
3051 *
3052 *
3053 * Documentation? What's that?
3054 * Nathan Myers <ncm@cantrip.org>.
3055 *
3056 * A string looks like this:
3057 *
3058 * @code
3059 * [_Rep]
3060 * _M_length
3061 * [basic_string<char_type>] _M_capacity
3062 * _M_dataplus _M_refcount
3063 * _M_p ----------------> unnamed array of char_type
3064 * @endcode
3065 *
3066 * Where the _M_p points to the first character in the string, and
3067 * you cast it to a pointer-to-_Rep and subtract 1 to get a
3068 * pointer to the header.
3069 *
3070 * This approach has the enormous advantage that a string object
3071 * requires only one allocation. All the ugliness is confined
3072 * within a single %pair of inline functions, which each compile to
3073 * a single @a add instruction: _Rep::_M_data(), and
3074 * string::_M_rep(); and the allocation function which gets a
3075 * block of raw bytes and with room enough and constructs a _Rep
3076 * object at the front.
3077 *
3078 * The reason you want _M_data pointing to the character %array and
3079 * not the _Rep is so that the debugger can see the string
3080 * contents. (Probably we should add a non-inline member to get
3081 * the _Rep for the debugger to use, so users can check the actual
3082 * string length.)
3083 *
3084 * Note that the _Rep object is a POD so that you can have a
3085 * static <em>empty string</em> _Rep object already @a constructed before
3086 * static constructors have run. The reference-count encoding is
3087 * chosen so that a 0 indicates one reference, so you never try to
3088 * destroy the empty-string _Rep object.
3089 *
3090 * All but the last paragraph is considered pretty conventional
3091 * for a C++ string implementation.
3092 */
3093 // 21.3 Template class basic_string
3094 template<typename _CharT, typename _Traits, typename _Alloc>
3095 class basic_string
3096 {
3097 typedef typename _Alloc::template rebind<_CharT>::other _CharT_alloc_type;
3098
3099 // Types:
3100 public:
3101 typedef _Traits traits_type;
3102 typedef typename _Traits::char_type value_type;
3103 typedef _Alloc allocator_type;
3104 typedef typename _CharT_alloc_type::size_type size_type;
3105 typedef typename _CharT_alloc_type::difference_type difference_type;
3106 typedef typename _CharT_alloc_type::reference reference;
3107 typedef typename _CharT_alloc_type::const_reference const_reference;
3108 typedef typename _CharT_alloc_type::pointer pointer;
3109 typedef typename _CharT_alloc_type::const_pointer const_pointer;
3110 typedef __gnu_cxx::__normal_iterator<pointer, basic_string> iterator;
3111 typedef __gnu_cxx::__normal_iterator<const_pointer, basic_string>
3112 const_iterator;
3113 typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
3114 typedef std::reverse_iterator<iterator> reverse_iterator;
3115
3116 private:
3117 // _Rep: string representation
3118 // Invariants:
3119 // 1. String really contains _M_length + 1 characters: due to 21.3.4
3120 // must be kept null-terminated.
3121 // 2. _M_capacity >= _M_length
3122 // Allocated memory is always (_M_capacity + 1) * sizeof(_CharT).
3123 // 3. _M_refcount has three states:
3124 // -1: leaked, one reference, no ref-copies allowed, non-const.
3125 // 0: one reference, non-const.
3126 // n>0: n + 1 references, operations require a lock, const.
3127 // 4. All fields==0 is an empty string, given the extra storage
3128 // beyond-the-end for a null terminator; thus, the shared
3129 // empty string representation needs no constructor.
3130
3131 struct _Rep_base
3132 {
3133 size_type _M_length;
3134 size_type _M_capacity;
3135 _Atomic_word _M_refcount;
3136 };
3137
3138 struct _Rep : _Rep_base
3139 {
3140 // Types:
3141 typedef typename _Alloc::template rebind<char>::other _Raw_bytes_alloc;
3142
3143 // (Public) Data members:
3144
3145 // The maximum number of individual char_type elements of an
3146 // individual string is determined by _S_max_size. This is the
3147 // value that will be returned by max_size(). (Whereas npos
3148 // is the maximum number of bytes the allocator can allocate.)
3149 // If one was to divvy up the theoretical largest size string,
3150 // with a terminating character and m _CharT elements, it'd
3151 // look like this:
3152 // npos = sizeof(_Rep) + (m * sizeof(_CharT)) + sizeof(_CharT)
3153 // Solving for m:
3154 // m = ((npos - sizeof(_Rep))/sizeof(CharT)) - 1
3155 // In addition, this implementation quarters this amount.
3156 static const size_type _S_max_size;
3157 static const _CharT _S_terminal;
3158
3159 // The following storage is init'd to 0 by the linker, resulting
3160 // (carefully) in an empty string with one reference.
3161 static size_type _S_empty_rep_storage[];
3162
3163 static _Rep&
3164 _S_empty_rep() _GLIBCXX_NOEXCEPT
3165 {
3166 // NB: Mild hack to avoid strict-aliasing warnings. Note that
3167 // _S_empty_rep_storage is never modified and the punning should
3168 // be reasonably safe in this case.
3169 void* __p = reinterpret_cast<void*>(&_S_empty_rep_storage);
3170 return *reinterpret_cast<_Rep*>(__p);
3171 }
3172
3173 bool
3174 _M_is_leaked() const _GLIBCXX_NOEXCEPT
3175 {
3176#if defined(__GTHREADS)
3177 // _M_refcount is mutated concurrently by _M_refcopy/_M_dispose,
3178 // so we need to use an atomic load. However, _M_is_leaked
3179 // predicate does not change concurrently (i.e. the string is either
3180 // leaked or not), so a relaxed load is enough.
3181 return __atomic_load_n(&this->_M_refcount, __ATOMIC_RELAXED) < 0;
3182#else
3183 return this->_M_refcount < 0;
3184#endif
3185 }
3186
3187 bool
3188 _M_is_shared() const _GLIBCXX_NOEXCEPT
3189 {
3190#if defined(__GTHREADS)
3191 // _M_refcount is mutated concurrently by _M_refcopy/_M_dispose,
3192 // so we need to use an atomic load. Another thread can drop last
3193 // but one reference concurrently with this check, so we need this
3194 // load to be acquire to synchronize with release fetch_and_add in
3195 // _M_dispose.
3196 return __atomic_load_n(&this->_M_refcount, __ATOMIC_ACQUIRE) > 0;
3197#else
3198 return this->_M_refcount > 0;
3199#endif
3200 }
3201
3202 void
3203 _M_set_leaked() _GLIBCXX_NOEXCEPT
3204 { this->_M_refcount = -1; }
3205
3206 void
3207 _M_set_sharable() _GLIBCXX_NOEXCEPT
3208 { this->_M_refcount = 0; }
3209
3210 void
3211 _M_set_length_and_sharable(size_type __n) _GLIBCXX_NOEXCEPT
3212 {
3213#if _GLIBCXX_FULLY_DYNAMIC_STRING == 0
3214 if (__builtin_expect(this != &_S_empty_rep(), false))
3215#endif
3216 {
3217 this->_M_set_sharable(); // One reference.
3218 this->_M_length = __n;
3219 traits_type::assign(this->_M_refdata()[__n], _S_terminal);
3220 // grrr. (per 21.3.4)
3221 // You cannot leave those LWG people alone for a second.
3222 }
3223 }
3224
3225 _CharT*
3226 _M_refdata() throw()
3227 { return reinterpret_cast<_CharT*>(this + 1); }
3228
3229 _CharT*
3230 _M_grab(const _Alloc& __alloc1, const _Alloc& __alloc2)
3231 {
3232 return (!_M_is_leaked() && __alloc1 == __alloc2)
3233 ? _M_refcopy() : _M_clone(__alloc1);
3234 }
3235
3236 // Create & Destroy
3237 static _Rep*
3238 _S_create(size_type, size_type, const _Alloc&);
3239
3240 void
3241 _M_dispose(const _Alloc& __a) _GLIBCXX_NOEXCEPT
3242 {
3243#if _GLIBCXX_FULLY_DYNAMIC_STRING == 0
3244 if (__builtin_expect(this != &_S_empty_rep(), false))
3245#endif
3246 {
3247 // Be race-detector-friendly. For more info see bits/c++config.
3248 _GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE(&this->_M_refcount);
3249 // Decrement of _M_refcount is acq_rel, because:
3250 // - all but last decrements need to release to synchronize with
3251 // the last decrement that will delete the object.
3252 // - the last decrement needs to acquire to synchronize with
3253 // all the previous decrements.
3254 // - last but one decrement needs to release to synchronize with
3255 // the acquire load in _M_is_shared that will conclude that
3256 // the object is not shared anymore.
3257 if (__gnu_cxx::__exchange_and_add_dispatch(&this->_M_refcount,
3258 -1) <= 0)
3259 {
3260 _GLIBCXX_SYNCHRONIZATION_HAPPENS_AFTER(&this->_M_refcount);
3261 _M_destroy(__a);
3262 }
3263 }
3264 } // XXX MT
3265
3266 void
3267 _M_destroy(const _Alloc&) throw();
3268
3269 _CharT*
3270 _M_refcopy() throw()
3271 {
3272#if _GLIBCXX_FULLY_DYNAMIC_STRING == 0
3273 if (__builtin_expect(this != &_S_empty_rep(), false))
3274#endif
3275 __gnu_cxx::__atomic_add_dispatch(&this->_M_refcount, 1);
3276 return _M_refdata();
3277 } // XXX MT
3278
3279 _CharT*
3280 _M_clone(const _Alloc&, size_type __res = 0);
3281 };
3282
3283 // Use empty-base optimization: http://www.cantrip.org/emptyopt.html
3284 struct _Alloc_hider : _Alloc
3285 {
3286 _Alloc_hider(_CharT* __dat, const _Alloc& __a) _GLIBCXX_NOEXCEPT
3287 : _Alloc(__a), _M_p(__dat) { }
3288
3289 _CharT* _M_p; // The actual data.
3290 };
3291
3292 public:
3293 // Data Members (public):
3294 // NB: This is an unsigned type, and thus represents the maximum
3295 // size that the allocator can hold.
3296 /// Value returned by various member functions when they fail.
3297 static const size_type npos = static_cast<size_type>(-1);
3298
3299 private:
3300 // Data Members (private):
3301 mutable _Alloc_hider _M_dataplus;
3302
3303 _CharT*
3304 _M_data() const _GLIBCXX_NOEXCEPT
3305 { return _M_dataplus._M_p; }
3306
3307 _CharT*
3308 _M_data(_CharT* __p) _GLIBCXX_NOEXCEPT
3309 { return (_M_dataplus._M_p = __p); }
3310
3311 _Rep*
3312 _M_rep() const _GLIBCXX_NOEXCEPT
3313 { return &((reinterpret_cast<_Rep*> (_M_data()))[-1]); }
3314
3315 // For the internal use we have functions similar to `begin'/`end'
3316 // but they do not call _M_leak.
3317 iterator
3318 _M_ibegin() const _GLIBCXX_NOEXCEPT
3319 { return iterator(_M_data()); }
3320
3321 iterator
3322 _M_iend() const _GLIBCXX_NOEXCEPT
3323 { return iterator(_M_data() + this->size()); }
3324
3325 void
3326 _M_leak() // for use in begin() & non-const op[]
3327 {
3328 if (!_M_rep()->_M_is_leaked())
3329 _M_leak_hard();
3330 }
3331
3332 size_type
3333 _M_check(size_type __pos, const char* __s) const
3334 {
3335 if (__pos > this->size())
3336 __throw_out_of_range_fmt(__N("%s: __pos (which is %zu) > "
3337 "this->size() (which is %zu)"),
3338 __s, __pos, this->size());
3339 return __pos;
3340 }
3341
3342 void
3343 _M_check_length(size_type __n1, size_type __n2, const char* __s) const
3344 {
3345 if (this->max_size() - (this->size() - __n1) < __n2)
3346 __throw_length_error(__N(__s));
3347 }
3348
3349 // NB: _M_limit doesn't check for a bad __pos value.
3350 size_type
3351 _M_limit(size_type __pos, size_type __off) const _GLIBCXX_NOEXCEPT
3352 {
3353 const bool __testoff = __off < this->size() - __pos;
3354 return __testoff ? __off : this->size() - __pos;
3355 }
3356
3357 // True if _Rep and source do not overlap.
3358 bool
3359 _M_disjunct(const _CharT* __s) const _GLIBCXX_NOEXCEPT
3360 {
3361 return (less<const _CharT*>()(__s, _M_data())
3362 || less<const _CharT*>()(_M_data() + this->size(), __s));
3363 }
3364
3365 // When __n = 1 way faster than the general multichar
3366 // traits_type::copy/move/assign.
3367 static void
3368 _M_copy(_CharT* __d, const _CharT* __s, size_type __n) _GLIBCXX_NOEXCEPT
3369 {
3370 if (__n == 1)
3371 traits_type::assign(*__d, *__s);
3372 else
3373 traits_type::copy(__d, __s, __n);
3374 }
3375
3376 static void
3377 _M_move(_CharT* __d, const _CharT* __s, size_type __n) _GLIBCXX_NOEXCEPT
3378 {
3379 if (__n == 1)
3380 traits_type::assign(*__d, *__s);
3381 else
3382 traits_type::move(__d, __s, __n);
3383 }
3384
3385 static void
3386 _M_assign(_CharT* __d, size_type __n, _CharT __c) _GLIBCXX_NOEXCEPT
3387 {
3388 if (__n == 1)
3389 traits_type::assign(*__d, __c);
3390 else
3391 traits_type::assign(__d, __n, __c);
3392 }
3393
3394 // _S_copy_chars is a separate template to permit specialization
3395 // to optimize for the common case of pointers as iterators.
3396 template<class _Iterator>
3397 static void
3398 _S_copy_chars(_CharT* __p, _Iterator __k1, _Iterator __k2)
3399 {
3400 for (; __k1 != __k2; ++__k1, (void)++__p)
3401 traits_type::assign(*__p, *__k1); // These types are off.
3402 }
3403
3404 static void
3405 _S_copy_chars(_CharT* __p, iterator __k1, iterator __k2) _GLIBCXX_NOEXCEPT
3406 { _S_copy_chars(__p, __k1.base(), __k2.base()); }
3407
3408 static void
3409 _S_copy_chars(_CharT* __p, const_iterator __k1, const_iterator __k2)
3410 _GLIBCXX_NOEXCEPT
3411 { _S_copy_chars(__p, __k1.base(), __k2.base()); }
3412
3413 static void
3414 _S_copy_chars(_CharT* __p, _CharT* __k1, _CharT* __k2) _GLIBCXX_NOEXCEPT
3415 { _M_copy(__p, __k1, __k2 - __k1); }
3416
3417 static void
3418 _S_copy_chars(_CharT* __p, const _CharT* __k1, const _CharT* __k2)
3419 _GLIBCXX_NOEXCEPT
3420 { _M_copy(__p, __k1, __k2 - __k1); }
3421
3422 static int
3423 _S_compare(size_type __n1, size_type __n2) _GLIBCXX_NOEXCEPT
3424 {
3425 const difference_type __d = difference_type(__n1 - __n2);
3426
3427 if (__d > __gnu_cxx::__numeric_traits<int>::__max)
3428 return __gnu_cxx::__numeric_traits<int>::__max;
3429 else if (__d < __gnu_cxx::__numeric_traits<int>::__min)
3430 return __gnu_cxx::__numeric_traits<int>::__min;
3431 else
3432 return int(__d);
3433 }
3434
3435 void
3436 _M_mutate(size_type __pos, size_type __len1, size_type __len2);
3437
3438 void
3439 _M_leak_hard();
3440
3441 static _Rep&
3442 _S_empty_rep() _GLIBCXX_NOEXCEPT
3443 { return _Rep::_S_empty_rep(); }
3444
3445#if __cplusplus > 201402L
3446 // A helper type for avoiding boiler-plate.
3447 typedef basic_string_view<_CharT, _Traits> __sv_type;
3448
3449 template<typename _Tp, typename _Res>
3450 using _If_sv = enable_if_t<
3451 __and_<is_convertible<const _Tp&, __sv_type>,
3452 __not_<is_convertible<const _Tp*, const basic_string*>>,
3453 __not_<is_convertible<const _Tp&, const _CharT*>>>::value,
3454 _Res>;
3455
3456 // Allows an implicit conversion to __sv_type.
3457 static __sv_type
3458 _S_to_string_view(__sv_type __svt) noexcept
3459 { return __svt; }
3460
3461 // Wraps a string_view by explicit conversion and thus
3462 // allows to add an internal constructor that does not
3463 // participate in overload resolution when a string_view
3464 // is provided.
3465 struct __sv_wrapper
3466 {
3467 explicit __sv_wrapper(__sv_type __sv) noexcept : _M_sv(__sv) { }
3468 __sv_type _M_sv;
3469 };
3470#endif
3471
3472 public:
3473 // Construct/copy/destroy:
3474 // NB: We overload ctors in some cases instead of using default
3475 // arguments, per 17.4.4.4 para. 2 item 2.
3476
3477 /**
3478 * @brief Default constructor creates an empty string.
3479 */
3480 basic_string()
3481#if _GLIBCXX_FULLY_DYNAMIC_STRING == 0
3482 : _M_dataplus(_S_empty_rep()._M_refdata(), _Alloc()) { }
3483#else
3484 : _M_dataplus(_S_construct(size_type(), _CharT(), _Alloc()), _Alloc()){ }
3485#endif
3486
3487 /**
3488 * @brief Construct an empty string using allocator @a a.
3489 */
3490 explicit
3491 basic_string(const _Alloc& __a);
3492
3493 // NB: per LWG issue 42, semantics different from IS:
3494 /**
3495 * @brief Construct string with copy of value of @a str.
3496 * @param __str Source string.
3497 */
3498 basic_string(const basic_string& __str);
3499
3500 // _GLIBCXX_RESOLVE_LIB_DEFECTS
3501 // 2583. no way to supply an allocator for basic_string(str, pos)
3502 /**
3503 * @brief Construct string as copy of a substring.
3504 * @param __str Source string.
3505 * @param __pos Index of first character to copy from.
3506 * @param __a Allocator to use.
3507 */
3508 basic_string(const basic_string& __str, size_type __pos,
3509 const _Alloc& __a = _Alloc());
3510
3511 /**
3512 * @brief Construct string as copy of a substring.
3513 * @param __str Source string.
3514 * @param __pos Index of first character to copy from.
3515 * @param __n Number of characters to copy.
3516 */
3517 basic_string(const basic_string& __str, size_type __pos,
3518 size_type __n);
3519 /**
3520 * @brief Construct string as copy of a substring.
3521 * @param __str Source string.
3522 * @param __pos Index of first character to copy from.
3523 * @param __n Number of characters to copy.
3524 * @param __a Allocator to use.
3525 */
3526 basic_string(const basic_string& __str, size_type __pos,
3527 size_type __n, const _Alloc& __a);
3528
3529 /**
3530 * @brief Construct string initialized by a character %array.
3531 * @param __s Source character %array.
3532 * @param __n Number of characters to copy.
3533 * @param __a Allocator to use (default is default allocator).
3534 *
3535 * NB: @a __s must have at least @a __n characters, &apos;\\0&apos;
3536 * has no special meaning.
3537 */
3538 basic_string(const _CharT* __s, size_type __n,
3539 const _Alloc& __a = _Alloc());
3540 /**
3541 * @brief Construct string as copy of a C string.
3542 * @param __s Source C string.
3543 * @param __a Allocator to use (default is default allocator).
3544 */
3545 basic_string(const _CharT* __s, const _Alloc& __a = _Alloc());
3546 /**
3547 * @brief Construct string as multiple characters.
3548 * @param __n Number of characters.
3549 * @param __c Character to use.
3550 * @param __a Allocator to use (default is default allocator).
3551 */
3552 basic_string(size_type __n, _CharT __c, const _Alloc& __a = _Alloc());
3553
3554#if __cplusplus >= 201103L
3555 /**
3556 * @brief Move construct string.
3557 * @param __str Source string.
3558 *
3559 * The newly-created string contains the exact contents of @a __str.
3560 * @a __str is a valid, but unspecified string.
3561 **/
3562 basic_string(basic_string&& __str)
3563#if _GLIBCXX_FULLY_DYNAMIC_STRING == 0
3564 noexcept // FIXME C++11: should always be noexcept.
3565#endif
3566 : _M_dataplus(__str._M_dataplus)
3567 {
3568#if _GLIBCXX_FULLY_DYNAMIC_STRING == 0
3569 __str._M_data(_S_empty_rep()._M_refdata());
3570#else
3571 __str._M_data(_S_construct(size_type(), _CharT(), get_allocator()));
3572#endif
3573 }
3574
3575 /**
3576 * @brief Construct string from an initializer %list.
3577 * @param __l std::initializer_list of characters.
3578 * @param __a Allocator to use (default is default allocator).
3579 */
3580 basic_string(initializer_list<_CharT> __l, const _Alloc& __a = _Alloc());
3581#endif // C++11
3582
3583 /**
3584 * @brief Construct string as copy of a range.
3585 * @param __beg Start of range.
3586 * @param __end End of range.
3587 * @param __a Allocator to use (default is default allocator).
3588 */
3589 template<class _InputIterator>
3590 basic_string(_InputIterator __beg, _InputIterator __end,
3591 const _Alloc& __a = _Alloc());
3592
3593#if __cplusplus > 201402L
3594 /**
3595 * @brief Construct string from a substring of a string_view.
3596 * @param __t Source object convertible to string view.
3597 * @param __pos The index of the first character to copy from __t.
3598 * @param __n The number of characters to copy from __t.
3599 * @param __a Allocator to use.
3600 */
3601 template<typename _Tp, typename = _If_sv<_Tp, void>>
3602 basic_string(const _Tp& __t, size_type __pos, size_type __n,
3603 const _Alloc& __a = _Alloc())
3604 : basic_string(_S_to_string_view(__t).substr(__pos, __n), __a) { }
3605
3606 /**
3607 * @brief Construct string from a string_view.
3608 * @param __t Source object convertible to string view.
3609 * @param __a Allocator to use (default is default allocator).
3610 */
3611 template<typename _Tp, typename = _If_sv<_Tp, void>>
3612 explicit
3613 basic_string(const _Tp& __t, const _Alloc& __a = _Alloc())
3614 : basic_string(__sv_wrapper(_S_to_string_view(__t)), __a) { }
3615
3616 /**
3617 * @brief Only internally used: Construct string from a string view
3618 * wrapper.
3619 * @param __svw string view wrapper.
3620 * @param __a Allocator to use.
3621 */
3622 explicit
3623 basic_string(__sv_wrapper __svw, const _Alloc& __a)
3624 : basic_string(__svw._M_sv.data(), __svw._M_sv.size(), __a) { }
3625#endif // C++17
3626
3627 /**
3628 * @brief Destroy the string instance.
3629 */
3630 ~basic_string() _GLIBCXX_NOEXCEPT
3631 { _M_rep()->_M_dispose(this->get_allocator()); }
3632
3633 /**
3634 * @brief Assign the value of @a str to this string.
3635 * @param __str Source string.
3636 */
3637 basic_string&
3638 operator=(const basic_string& __str)
3639 { return this->assign(__str); }
3640
3641 /**
3642 * @brief Copy contents of @a s into this string.
3643 * @param __s Source null-terminated string.
3644 */
3645 basic_string&
3646 operator=(const _CharT* __s)
3647 { return this->assign(__s); }
3648
3649 /**
3650 * @brief Set value to string of length 1.
3651 * @param __c Source character.
3652 *
3653 * Assigning to a character makes this string length 1 and
3654 * (*this)[0] == @a c.
3655 */
3656 basic_string&
3657 operator=(_CharT __c)
3658 {
3659 this->assign(1, __c);
3660 return *this;
3661 }
3662
3663#if __cplusplus >= 201103L
3664 /**
3665 * @brief Move assign the value of @a str to this string.
3666 * @param __str Source string.
3667 *
3668 * The contents of @a str are moved into this string (without copying).
3669 * @a str is a valid, but unspecified string.
3670 **/
3671 // PR 58265, this should be noexcept.
3672 basic_string&
3673 operator=(basic_string&& __str)
3674 {
3675 // NB: DR 1204.
3676 this->swap(__str);
3677 return *this;
3678 }
3679
3680 /**
3681 * @brief Set value to string constructed from initializer %list.
3682 * @param __l std::initializer_list.
3683 */
3684 basic_string&
3685 operator=(initializer_list<_CharT> __l)
3686 {
3687 this->assign(__l.begin(), __l.size());
3688 return *this;
3689 }
3690#endif // C++11
3691
3692#if __cplusplus > 201402L
3693 /**
3694 * @brief Set value to string constructed from a string_view.
3695 * @param __svt An object convertible to string_view.
3696 */
3697 template<typename _Tp>
3698 _If_sv<_Tp, basic_string&>
3699 operator=(const _Tp& __svt)
3700 { return this->assign(__svt); }
3701
3702 /**
3703 * @brief Convert to a string_view.
3704 * @return A string_view.
3705 */
3706 operator __sv_type() const noexcept
3707 { return __sv_type(data(), size()); }
3708#endif // C++17
3709
3710 // Iterators:
3711 /**
3712 * Returns a read/write iterator that points to the first character in
3713 * the %string. Unshares the string.
3714 */
3715 iterator
3716 begin() // FIXME C++11: should be noexcept.
3717 {
3718 _M_leak();
3719 return iterator(_M_data());
3720 }
3721
3722 /**
3723 * Returns a read-only (constant) iterator that points to the first
3724 * character in the %string.
3725 */
3726 const_iterator
3727 begin() const _GLIBCXX_NOEXCEPT
3728 { return const_iterator(_M_data()); }
3729
3730 /**
3731 * Returns a read/write iterator that points one past the last
3732 * character in the %string. Unshares the string.
3733 */
3734 iterator
3735 end() // FIXME C++11: should be noexcept.
3736 {
3737 _M_leak();
3738 return iterator(_M_data() + this->size());
3739 }
3740
3741 /**
3742 * Returns a read-only (constant) iterator that points one past the
3743 * last character in the %string.
3744 */
3745 const_iterator
3746 end() const _GLIBCXX_NOEXCEPT
3747 { return const_iterator(_M_data() + this->size()); }
3748
3749 /**
3750 * Returns a read/write reverse iterator that points to the last
3751 * character in the %string. Iteration is done in reverse element
3752 * order. Unshares the string.
3753 */
3754 reverse_iterator
3755 rbegin() // FIXME C++11: should be noexcept.
3756 { return reverse_iterator(this->end()); }
3757
3758 /**
3759 * Returns a read-only (constant) reverse iterator that points
3760 * to the last character in the %string. Iteration is done in
3761 * reverse element order.
3762 */
3763 const_reverse_iterator
3764 rbegin() const _GLIBCXX_NOEXCEPT
3765 { return const_reverse_iterator(this->end()); }
3766
3767 /**
3768 * Returns a read/write reverse iterator that points to one before the
3769 * first character in the %string. Iteration is done in reverse
3770 * element order. Unshares the string.
3771 */
3772 reverse_iterator
3773 rend() // FIXME C++11: should be noexcept.
3774 { return reverse_iterator(this->begin()); }
3775
3776 /**
3777 * Returns a read-only (constant) reverse iterator that points
3778 * to one before the first character in the %string. Iteration
3779 * is done in reverse element order.
3780 */
3781 const_reverse_iterator
3782 rend() const _GLIBCXX_NOEXCEPT
3783 { return const_reverse_iterator(this->begin()); }
3784
3785#if __cplusplus >= 201103L
3786 /**
3787 * Returns a read-only (constant) iterator that points to the first
3788 * character in the %string.
3789 */
3790 const_iterator
3791 cbegin() const noexcept
3792 { return const_iterator(this->_M_data()); }
3793
3794 /**
3795 * Returns a read-only (constant) iterator that points one past the
3796 * last character in the %string.
3797 */
3798 const_iterator
3799 cend() const noexcept
3800 { return const_iterator(this->_M_data() + this->size()); }
3801
3802 /**
3803 * Returns a read-only (constant) reverse iterator that points
3804 * to the last character in the %string. Iteration is done in
3805 * reverse element order.
3806 */
3807 const_reverse_iterator
3808 crbegin() const noexcept
3809 { return const_reverse_iterator(this->end()); }
3810
3811 /**
3812 * Returns a read-only (constant) reverse iterator that points
3813 * to one before the first character in the %string. Iteration
3814 * is done in reverse element order.
3815 */
3816 const_reverse_iterator
3817 crend() const noexcept
3818 { return const_reverse_iterator(this->begin()); }
3819#endif
3820
3821 public:
3822 // Capacity:
3823 /// Returns the number of characters in the string, not including any
3824 /// null-termination.
3825 size_type
3826 size() const _GLIBCXX_NOEXCEPT
3827 { return _M_rep()->_M_length; }
3828
3829 /// Returns the number of characters in the string, not including any
3830 /// null-termination.
3831 size_type
3832 length() const _GLIBCXX_NOEXCEPT
3833 { return _M_rep()->_M_length; }
3834
3835 /// Returns the size() of the largest possible %string.
3836 size_type
3837 max_size() const _GLIBCXX_NOEXCEPT
3838 { return _Rep::_S_max_size; }
3839
3840 /**
3841 * @brief Resizes the %string to the specified number of characters.
3842 * @param __n Number of characters the %string should contain.
3843 * @param __c Character to fill any new elements.
3844 *
3845 * This function will %resize the %string to the specified
3846 * number of characters. If the number is smaller than the
3847 * %string's current size the %string is truncated, otherwise
3848 * the %string is extended and new elements are %set to @a __c.
3849 */
3850 void
3851 resize(size_type __n, _CharT __c);
3852
3853 /**
3854 * @brief Resizes the %string to the specified number of characters.
3855 * @param __n Number of characters the %string should contain.
3856 *
3857 * This function will resize the %string to the specified length. If
3858 * the new size is smaller than the %string's current size the %string
3859 * is truncated, otherwise the %string is extended and new characters
3860 * are default-constructed. For basic types such as char, this means
3861 * setting them to 0.
3862 */
3863 void
3864 resize(size_type __n)
3865 { this->resize(__n, _CharT()); }
3866
3867#if __cplusplus >= 201103L
3868 /// A non-binding request to reduce capacity() to size().
3869 void
3870 shrink_to_fit() _GLIBCXX_NOEXCEPT
3871 {
3872#if __cpp_exceptions
3873 if (capacity() > size())
3874 {
3875 try
3876 { reserve(0); }
3877 catch(...)
3878 { }
3879 }
3880#endif
3881 }
3882#endif
3883
3884 /**
3885 * Returns the total number of characters that the %string can hold
3886 * before needing to allocate more memory.
3887 */
3888 size_type
3889 capacity() const _GLIBCXX_NOEXCEPT
3890 { return _M_rep()->_M_capacity; }
3891
3892 /**
3893 * @brief Attempt to preallocate enough memory for specified number of
3894 * characters.
3895 * @param __res_arg Number of characters required.
3896 * @throw std::length_error If @a __res_arg exceeds @c max_size().
3897 *
3898 * This function attempts to reserve enough memory for the
3899 * %string to hold the specified number of characters. If the
3900 * number requested is more than max_size(), length_error is
3901 * thrown.
3902 *
3903 * The advantage of this function is that if optimal code is a
3904 * necessity and the user can determine the string length that will be
3905 * required, the user can reserve the memory in %advance, and thus
3906 * prevent a possible reallocation of memory and copying of %string
3907 * data.
3908 */
3909 void
3910 reserve(size_type __res_arg = 0);
3911
3912 /**
3913 * Erases the string, making it empty.
3914 */
3915#if _GLIBCXX_FULLY_DYNAMIC_STRING == 0
3916 void
3917 clear() _GLIBCXX_NOEXCEPT
3918 {
3919 if (_M_rep()->_M_is_shared())
3920 {
3921 _M_rep()->_M_dispose(this->get_allocator());
3922 _M_data(_S_empty_rep()._M_refdata());
3923 }
3924 else
3925 _M_rep()->_M_set_length_and_sharable(0);
3926 }
3927#else
3928 // PR 56166: this should not throw.
3929 void
3930 clear()
3931 { _M_mutate(0, this->size(), 0); }
3932#endif
3933
3934 /**
3935 * Returns true if the %string is empty. Equivalent to
3936 * <code>*this == ""</code>.
3937 */
3938 bool
3939 empty() const _GLIBCXX_NOEXCEPT
3940 { return this->size() == 0; }
3941
3942 // Element access:
3943 /**
3944 * @brief Subscript access to the data contained in the %string.
3945 * @param __pos The index of the character to access.
3946 * @return Read-only (constant) reference to the character.
3947 *
3948 * This operator allows for easy, array-style, data access.
3949 * Note that data access with this operator is unchecked and
3950 * out_of_range lookups are not defined. (For checked lookups
3951 * see at().)
3952 */
3953 const_reference
3954 operator[] (size_type __pos) const _GLIBCXX_NOEXCEPT
3955 {
3956 __glibcxx_assert(__pos <= size());
3957 return _M_data()[__pos];
3958 }
3959
3960 /**
3961 * @brief Subscript access to the data contained in the %string.
3962 * @param __pos The index of the character to access.
3963 * @return Read/write reference to the character.
3964 *
3965 * This operator allows for easy, array-style, data access.
3966 * Note that data access with this operator is unchecked and
3967 * out_of_range lookups are not defined. (For checked lookups
3968 * see at().) Unshares the string.
3969 */
3970 reference
3971 operator[](size_type __pos)
3972 {
3973 // Allow pos == size() both in C++98 mode, as v3 extension,
3974 // and in C++11 mode.
3975 __glibcxx_assert(__pos <= size());
3976 // In pedantic mode be strict in C++98 mode.
3977 _GLIBCXX_DEBUG_PEDASSERT(__cplusplus >= 201103L || __pos < size());
3978 _M_leak();
3979 return _M_data()[__pos];
3980 }
3981
3982 /**
3983 * @brief Provides access to the data contained in the %string.
3984 * @param __n The index of the character to access.
3985 * @return Read-only (const) reference to the character.
3986 * @throw std::out_of_range If @a n is an invalid index.
3987 *
3988 * This function provides for safer data access. The parameter is
3989 * first checked that it is in the range of the string. The function
3990 * throws out_of_range if the check fails.
3991 */
3992 const_reference
3993 at(size_type __n) const
3994 {
3995 if (__n >= this->size())
3996 __throw_out_of_range_fmt(__N("basic_string::at: __n "
3997 "(which is %zu) >= this->size() "
3998 "(which is %zu)"),
3999 __n, this->size());
4000 return _M_data()[__n];
4001 }
4002
4003 /**
4004 * @brief Provides access to the data contained in the %string.
4005 * @param __n The index of the character to access.
4006 * @return Read/write reference to the character.
4007 * @throw std::out_of_range If @a n is an invalid index.
4008 *
4009 * This function provides for safer data access. The parameter is
4010 * first checked that it is in the range of the string. The function
4011 * throws out_of_range if the check fails. Success results in
4012 * unsharing the string.
4013 */
4014 reference
4015 at(size_type __n)
4016 {
4017 if (__n >= size())
4018 __throw_out_of_range_fmt(__N("basic_string::at: __n "
4019 "(which is %zu) >= this->size() "
4020 "(which is %zu)"),
4021 __n, this->size());
4022 _M_leak();
4023 return _M_data()[__n];
4024 }
4025
4026#if __cplusplus >= 201103L
4027 /**
4028 * Returns a read/write reference to the data at the first
4029 * element of the %string.
4030 */
4031 reference
4032 front()
4033 {
4034 __glibcxx_assert(!empty());
4035 return operator[](0);
4036 }
4037
4038 /**
4039 * Returns a read-only (constant) reference to the data at the first
4040 * element of the %string.
4041 */
4042 const_reference
4043 front() const noexcept
4044 {
4045 __glibcxx_assert(!empty());
4046 return operator[](0);
4047 }
4048
4049 /**
4050 * Returns a read/write reference to the data at the last
4051 * element of the %string.
4052 */
4053 reference
4054 back()
4055 {
4056 __glibcxx_assert(!empty());
4057 return operator[](this->size() - 1);
4058 }
4059
4060 /**
4061 * Returns a read-only (constant) reference to the data at the
4062 * last element of the %string.
4063 */
4064 const_reference
4065 back() const noexcept
4066 {
4067 __glibcxx_assert(!empty());
4068 return operator[](this->size() - 1);
4069 }
4070#endif
4071
4072 // Modifiers:
4073 /**
4074 * @brief Append a string to this string.
4075 * @param __str The string to append.
4076 * @return Reference to this string.
4077 */
4078 basic_string&
4079 operator+=(const basic_string& __str)
4080 { return this->append(__str); }
4081
4082 /**
4083 * @brief Append a C string.
4084 * @param __s The C string to append.
4085 * @return Reference to this string.
4086 */
4087 basic_string&
4088 operator+=(const _CharT* __s)
4089 { return this->append(__s); }
4090
4091 /**
4092 * @brief Append a character.
4093 * @param __c The character to append.
4094 * @return Reference to this string.
4095 */
4096 basic_string&
4097 operator+=(_CharT __c)
4098 {
4099 this->push_back(__c);
4100 return *this;
4101 }
4102
4103#if __cplusplus >= 201103L
4104 /**
4105 * @brief Append an initializer_list of characters.
4106 * @param __l The initializer_list of characters to be appended.
4107 * @return Reference to this string.
4108 */
4109 basic_string&
4110 operator+=(initializer_list<_CharT> __l)
4111 { return this->append(__l.begin(), __l.size()); }
4112#endif // C++11
4113
4114#if __cplusplus > 201402L
4115 /**
4116 * @brief Append a string_view.
4117 * @param __svt The object convertible to string_view to be appended.
4118 * @return Reference to this string.
4119 */
4120 template<typename _Tp>
4121 _If_sv<_Tp, basic_string&>
4122 operator+=(const _Tp& __svt)
4123 { return this->append(__svt); }
4124#endif // C++17
4125
4126 /**
4127 * @brief Append a string to this string.
4128 * @param __str The string to append.
4129 * @return Reference to this string.
4130 */
4131 basic_string&
4132 append(const basic_string& __str);
4133
4134 /**
4135 * @brief Append a substring.
4136 * @param __str The string to append.
4137 * @param __pos Index of the first character of str to append.
4138 * @param __n The number of characters to append.
4139 * @return Reference to this string.
4140 * @throw std::out_of_range if @a __pos is not a valid index.
4141 *
4142 * This function appends @a __n characters from @a __str
4143 * starting at @a __pos to this string. If @a __n is is larger
4144 * than the number of available characters in @a __str, the
4145 * remainder of @a __str is appended.
4146 */
4147 basic_string&
4148 append(const basic_string& __str, size_type __pos, size_type __n = npos);
4149
4150 /**
4151 * @brief Append a C substring.
4152 * @param __s The C string to append.
4153 * @param __n The number of characters to append.
4154 * @return Reference to this string.
4155 */
4156 basic_string&
4157 append(const _CharT* __s, size_type __n);
4158
4159 /**
4160 * @brief Append a C string.
4161 * @param __s The C string to append.
4162 * @return Reference to this string.
4163 */
4164 basic_string&
4165 append(const _CharT* __s)
4166 {
4167 __glibcxx_requires_string(__s);
4168 return this->append(__s, traits_type::length(__s));
4169 }
4170
4171 /**
4172 * @brief Append multiple characters.
4173 * @param __n The number of characters to append.
4174 * @param __c The character to use.
4175 * @return Reference to this string.
4176 *
4177 * Appends __n copies of __c to this string.
4178 */
4179 basic_string&
4180 append(size_type __n, _CharT __c);
4181
4182#if __cplusplus >= 201103L
4183 /**
4184 * @brief Append an initializer_list of characters.
4185 * @param __l The initializer_list of characters to append.
4186 * @return Reference to this string.
4187 */
4188 basic_string&
4189 append(initializer_list<_CharT> __l)
4190 { return this->append(__l.begin(), __l.size()); }
4191#endif // C++11
4192
4193 /**
4194 * @brief Append a range of characters.
4195 * @param __first Iterator referencing the first character to append.
4196 * @param __last Iterator marking the end of the range.
4197 * @return Reference to this string.
4198 *
4199 * Appends characters in the range [__first,__last) to this string.
4200 */
4201 template<class _InputIterator>
4202 basic_string&
4203 append(_InputIterator __first, _InputIterator __last)
4204 { return this->replace(_M_iend(), _M_iend(), __first, __last); }
4205
4206#if __cplusplus > 201402L
4207 /**
4208 * @brief Append a string_view.
4209 * @param __svt The object convertible to string_view to be appended.
4210 * @return Reference to this string.
4211 */
4212 template<typename _Tp>
4213 _If_sv<_Tp, basic_string&>
4214 append(const _Tp& __svt)
4215 {
4216 __sv_type __sv = __svt;
4217 return this->append(__sv.data(), __sv.size());
4218 }
4219
4220 /**
4221 * @brief Append a range of characters from a string_view.
4222 * @param __svt The object convertible to string_view to be appended
4223 * from.
4224 * @param __pos The position in the string_view to append from.
4225 * @param __n The number of characters to append from the string_view.
4226 * @return Reference to this string.
4227 */
4228 template<typename _Tp>
4229 _If_sv<_Tp, basic_string&>
4230 append(const _Tp& __svt, size_type __pos, size_type __n = npos)
4231 {
4232 __sv_type __sv = __svt;
4233 return append(__sv.data()
4234 + __sv._M_check(__pos, "basic_string::append"),
4235 __sv._M_limit(__pos, __n));
4236 }
4237#endif // C++17
4238
4239 /**
4240 * @brief Append a single character.
4241 * @param __c Character to append.
4242 */
4243 void
4244 push_back(_CharT __c)
4245 {
4246 const size_type __len = 1 + this->size();
4247 if (__len > this->capacity() || _M_rep()->_M_is_shared())
4248 this->reserve(__len);
4249 traits_type::assign(_M_data()[this->size()], __c);
4250 _M_rep()->_M_set_length_and_sharable(__len);
4251 }
4252
4253 /**
4254 * @brief Set value to contents of another string.
4255 * @param __str Source string to use.
4256 * @return Reference to this string.
4257 */
4258 basic_string&
4259 assign(const basic_string& __str);
4260
4261#if __cplusplus >= 201103L
4262 /**
4263 * @brief Set value to contents of another string.
4264 * @param __str Source string to use.
4265 * @return Reference to this string.
4266 *
4267 * This function sets this string to the exact contents of @a __str.
4268 * @a __str is a valid, but unspecified string.
4269 */
4270 // PR 58265, this should be noexcept.
4271 basic_string&
4272 assign(basic_string&& __str)
4273 {
4274 this->swap(__str);
4275 return *this;
4276 }
4277#endif // C++11
4278
4279 /**
4280 * @brief Set value to a substring of a string.
4281 * @param __str The string to use.
4282 * @param __pos Index of the first character of str.
4283 * @param __n Number of characters to use.
4284 * @return Reference to this string.
4285 * @throw std::out_of_range if @a pos is not a valid index.
4286 *
4287 * This function sets this string to the substring of @a __str
4288 * consisting of @a __n characters at @a __pos. If @a __n is
4289 * is larger than the number of available characters in @a
4290 * __str, the remainder of @a __str is used.
4291 */
4292 basic_string&
4293 assign(const basic_string& __str, size_type __pos, size_type __n = npos)
4294 { return this->assign(__str._M_data()
4295 + __str._M_check(__pos, "basic_string::assign"),
4296 __str._M_limit(__pos, __n)); }
4297
4298 /**
4299 * @brief Set value to a C substring.
4300 * @param __s The C string to use.
4301 * @param __n Number of characters to use.
4302 * @return Reference to this string.
4303 *
4304 * This function sets the value of this string to the first @a __n
4305 * characters of @a __s. If @a __n is is larger than the number of
4306 * available characters in @a __s, the remainder of @a __s is used.
4307 */
4308 basic_string&
4309 assign(const _CharT* __s, size_type __n);
4310
4311 /**
4312 * @brief Set value to contents of a C string.
4313 * @param __s The C string to use.
4314 * @return Reference to this string.
4315 *
4316 * This function sets the value of this string to the value of @a __s.
4317 * The data is copied, so there is no dependence on @a __s once the
4318 * function returns.
4319 */
4320 basic_string&
4321 assign(const _CharT* __s)
4322 {
4323 __glibcxx_requires_string(__s);
4324 return this->assign(__s, traits_type::length(__s));
4325 }
4326
4327 /**
4328 * @brief Set value to multiple characters.
4329 * @param __n Length of the resulting string.
4330 * @param __c The character to use.
4331 * @return Reference to this string.
4332 *
4333 * This function sets the value of this string to @a __n copies of
4334 * character @a __c.
4335 */
4336 basic_string&
4337 assign(size_type __n, _CharT __c)
4338 { return _M_replace_aux(size_type(0), this->size(), __n, __c); }
4339
4340 /**
4341 * @brief Set value to a range of characters.
4342 * @param __first Iterator referencing the first character to append.
4343 * @param __last Iterator marking the end of the range.
4344 * @return Reference to this string.
4345 *
4346 * Sets value of string to characters in the range [__first,__last).
4347 */
4348 template<class _InputIterator>
4349 basic_string&
4350 assign(_InputIterator __first, _InputIterator __last)
4351 { return this->replace(_M_ibegin(), _M_iend(), __first, __last); }
4352
4353#if __cplusplus >= 201103L
4354 /**
4355 * @brief Set value to an initializer_list of characters.
4356 * @param __l The initializer_list of characters to assign.
4357 * @return Reference to this string.
4358 */
4359 basic_string&
4360 assign(initializer_list<_CharT> __l)
4361 { return this->assign(__l.begin(), __l.size()); }
4362#endif // C++11
4363
4364#if __cplusplus > 201402L
4365 /**
4366 * @brief Set value from a string_view.
4367 * @param __svt The source object convertible to string_view.
4368 * @return Reference to this string.
4369 */
4370 template<typename _Tp>
4371 _If_sv<_Tp, basic_string&>
4372 assign(const _Tp& __svt)
4373 {
4374 __sv_type __sv = __svt;
4375 return this->assign(__sv.data(), __sv.size());
4376 }
4377
4378 /**
4379 * @brief Set value from a range of characters in a string_view.
4380 * @param __svt The source object convertible to string_view.
4381 * @param __pos The position in the string_view to assign from.
4382 * @param __n The number of characters to assign.
4383 * @return Reference to this string.
4384 */
4385 template<typename _Tp>
4386 _If_sv<_Tp, basic_string&>
4387 assign(const _Tp& __svt, size_type __pos, size_type __n = npos)
4388 {
4389 __sv_type __sv = __svt;
4390 return assign(__sv.data()
4391 + __sv._M_check(__pos, "basic_string::assign"),
4392 __sv._M_limit(__pos, __n));
4393 }
4394#endif // C++17
4395
4396 /**
4397 * @brief Insert multiple characters.
4398 * @param __p Iterator referencing location in string to insert at.
4399 * @param __n Number of characters to insert
4400 * @param __c The character to insert.
4401 * @throw std::length_error If new length exceeds @c max_size().
4402 *
4403 * Inserts @a __n copies of character @a __c starting at the
4404 * position referenced by iterator @a __p. If adding
4405 * characters causes the length to exceed max_size(),
4406 * length_error is thrown. The value of the string doesn't
4407 * change if an error is thrown.
4408 */
4409 void
4410 insert(iterator __p, size_type __n, _CharT __c)
4411 { this->replace(__p, __p, __n, __c); }
4412
4413 /**
4414 * @brief Insert a range of characters.
4415 * @param __p Iterator referencing location in string to insert at.
4416 * @param __beg Start of range.
4417 * @param __end End of range.
4418 * @throw std::length_error If new length exceeds @c max_size().
4419 *
4420 * Inserts characters in range [__beg,__end). If adding
4421 * characters causes the length to exceed max_size(),
4422 * length_error is thrown. The value of the string doesn't
4423 * change if an error is thrown.
4424 */
4425 template<class _InputIterator>
4426 void
4427 insert(iterator __p, _InputIterator __beg, _InputIterator __end)
4428 { this->replace(__p, __p, __beg, __end); }
4429
4430#if __cplusplus >= 201103L
4431 /**
4432 * @brief Insert an initializer_list of characters.
4433 * @param __p Iterator referencing location in string to insert at.
4434 * @param __l The initializer_list of characters to insert.
4435 * @throw std::length_error If new length exceeds @c max_size().
4436 */
4437 void
4438 insert(iterator __p, initializer_list<_CharT> __l)
4439 {
4440 _GLIBCXX_DEBUG_PEDASSERT(__p >= _M_ibegin() && __p <= _M_iend());
4441 this->insert(__p - _M_ibegin(), __l.begin(), __l.size());
4442 }
4443#endif // C++11
4444
4445 /**
4446 * @brief Insert value of a string.
4447 * @param __pos1 Iterator referencing location in string to insert at.
4448 * @param __str The string to insert.
4449 * @return Reference to this string.
4450 * @throw std::length_error If new length exceeds @c max_size().
4451 *
4452 * Inserts value of @a __str starting at @a __pos1. If adding
4453 * characters causes the length to exceed max_size(),
4454 * length_error is thrown. The value of the string doesn't
4455 * change if an error is thrown.
4456 */
4457 basic_string&
4458 insert(size_type __pos1, const basic_string& __str)
4459 { return this->insert(__pos1, __str, size_type(0), __str.size()); }
4460
4461 /**
4462 * @brief Insert a substring.
4463 * @param __pos1 Iterator referencing location in string to insert at.
4464 * @param __str The string to insert.
4465 * @param __pos2 Start of characters in str to insert.
4466 * @param __n Number of characters to insert.
4467 * @return Reference to this string.
4468 * @throw std::length_error If new length exceeds @c max_size().
4469 * @throw std::out_of_range If @a pos1 > size() or
4470 * @a __pos2 > @a str.size().
4471 *
4472 * Starting at @a pos1, insert @a __n character of @a __str
4473 * beginning with @a __pos2. If adding characters causes the
4474 * length to exceed max_size(), length_error is thrown. If @a
4475 * __pos1 is beyond the end of this string or @a __pos2 is
4476 * beyond the end of @a __str, out_of_range is thrown. The
4477 * value of the string doesn't change if an error is thrown.
4478 */
4479 basic_string&
4480 insert(size_type __pos1, const basic_string& __str,
4481 size_type __pos2, size_type __n = npos)
4482 { return this->insert(__pos1, __str._M_data()
4483 + __str._M_check(__pos2, "basic_string::insert"),
4484 __str._M_limit(__pos2, __n)); }
4485
4486 /**
4487 * @brief Insert a C substring.
4488 * @param __pos Iterator referencing location in string to insert at.
4489 * @param __s The C string to insert.
4490 * @param __n The number of characters to insert.
4491 * @return Reference to this string.
4492 * @throw std::length_error If new length exceeds @c max_size().
4493 * @throw std::out_of_range If @a __pos is beyond the end of this
4494 * string.
4495 *
4496 * Inserts the first @a __n characters of @a __s starting at @a
4497 * __pos. If adding characters causes the length to exceed
4498 * max_size(), length_error is thrown. If @a __pos is beyond
4499 * end(), out_of_range is thrown. The value of the string
4500 * doesn't change if an error is thrown.
4501 */
4502 basic_string&
4503 insert(size_type __pos, const _CharT* __s, size_type __n);
4504
4505 /**
4506 * @brief Insert a C string.
4507 * @param __pos Iterator referencing location in string to insert at.
4508 * @param __s The C string to insert.
4509 * @return Reference to this string.
4510 * @throw std::length_error If new length exceeds @c max_size().
4511 * @throw std::out_of_range If @a pos is beyond the end of this
4512 * string.
4513 *
4514 * Inserts the first @a n characters of @a __s starting at @a __pos. If
4515 * adding characters causes the length to exceed max_size(),
4516 * length_error is thrown. If @a __pos is beyond end(), out_of_range is
4517 * thrown. The value of the string doesn't change if an error is
4518 * thrown.
4519 */
4520 basic_string&
4521 insert(size_type __pos, const _CharT* __s)
4522 {
4523 __glibcxx_requires_string(__s);
4524 return this->insert(__pos, __s, traits_type::length(__s));
4525 }
4526
4527 /**
4528 * @brief Insert multiple characters.
4529 * @param __pos Index in string to insert at.
4530 * @param __n Number of characters to insert
4531 * @param __c The character to insert.
4532 * @return Reference to this string.
4533 * @throw std::length_error If new length exceeds @c max_size().
4534 * @throw std::out_of_range If @a __pos is beyond the end of this
4535 * string.
4536 *
4537 * Inserts @a __n copies of character @a __c starting at index
4538 * @a __pos. If adding characters causes the length to exceed
4539 * max_size(), length_error is thrown. If @a __pos > length(),
4540 * out_of_range is thrown. The value of the string doesn't
4541 * change if an error is thrown.
4542 */
4543 basic_string&
4544 insert(size_type __pos, size_type __n, _CharT __c)
4545 { return _M_replace_aux(_M_check(__pos, "basic_string::insert"),
4546 size_type(0), __n, __c); }
4547
4548 /**
4549 * @brief Insert one character.
4550 * @param __p Iterator referencing position in string to insert at.
4551 * @param __c The character to insert.
4552 * @return Iterator referencing newly inserted char.
4553 * @throw std::length_error If new length exceeds @c max_size().
4554 *
4555 * Inserts character @a __c at position referenced by @a __p.
4556 * If adding character causes the length to exceed max_size(),
4557 * length_error is thrown. If @a __p is beyond end of string,
4558 * out_of_range is thrown. The value of the string doesn't
4559 * change if an error is thrown.
4560 */
4561 iterator
4562 insert(iterator __p, _CharT __c)
4563 {
4564 _GLIBCXX_DEBUG_PEDASSERT(__p >= _M_ibegin() && __p <= _M_iend());
4565 const size_type __pos = __p - _M_ibegin();
4566 _M_replace_aux(__pos, size_type(0), size_type(1), __c);
4567 _M_rep()->_M_set_leaked();
4568 return iterator(_M_data() + __pos);
4569 }
4570
4571#if __cplusplus > 201402L
4572 /**
4573 * @brief Insert a string_view.
4574 * @param __pos Iterator referencing position in string to insert at.
4575 * @param __svt The object convertible to string_view to insert.
4576 * @return Reference to this string.
4577 */
4578 template<typename _Tp>
4579 _If_sv<_Tp, basic_string&>
4580 insert(size_type __pos, const _Tp& __svt)
4581 {
4582 __sv_type __sv = __svt;
4583 return this->insert(__pos, __sv.data(), __sv.size());
4584 }
4585
4586 /**
4587 * @brief Insert a string_view.
4588 * @param __pos Iterator referencing position in string to insert at.
4589 * @param __svt The object convertible to string_view to insert from.
4590 * @param __pos Iterator referencing position in string_view to insert
4591 * from.
4592 * @param __n The number of characters to insert.
4593 * @return Reference to this string.
4594 */
4595 template<typename _Tp>
4596 _If_sv<_Tp, basic_string&>
4597 insert(size_type __pos1, const _Tp& __svt,
4598 size_type __pos2, size_type __n = npos)
4599 {
4600 __sv_type __sv = __svt;
4601 return this->replace(__pos1, size_type(0), __sv.data()
4602 + __sv._M_check(__pos2, "basic_string::insert"),
4603 __sv._M_limit(__pos2, __n));
4604 }
4605#endif // C++17
4606
4607 /**
4608 * @brief Remove characters.
4609 * @param __pos Index of first character to remove (default 0).
4610 * @param __n Number of characters to remove (default remainder).
4611 * @return Reference to this string.
4612 * @throw std::out_of_range If @a pos is beyond the end of this
4613 * string.
4614 *
4615 * Removes @a __n characters from this string starting at @a
4616 * __pos. The length of the string is reduced by @a __n. If
4617 * there are < @a __n characters to remove, the remainder of
4618 * the string is truncated. If @a __p is beyond end of string,
4619 * out_of_range is thrown. The value of the string doesn't
4620 * change if an error is thrown.
4621 */
4622 basic_string&
4623 erase(size_type __pos = 0, size_type __n = npos)
4624 {
4625 _M_mutate(_M_check(__pos, "basic_string::erase"),
4626 _M_limit(__pos, __n), size_type(0));
4627 return *this;
4628 }
4629
4630 /**
4631 * @brief Remove one character.
4632 * @param __position Iterator referencing the character to remove.
4633 * @return iterator referencing same location after removal.
4634 *
4635 * Removes the character at @a __position from this string. The value
4636 * of the string doesn't change if an error is thrown.
4637 */
4638 iterator
4639 erase(iterator __position)
4640 {
4641 _GLIBCXX_DEBUG_PEDASSERT(__position >= _M_ibegin()
4642 && __position < _M_iend());
4643 const size_type __pos = __position - _M_ibegin();
4644 _M_mutate(__pos, size_type(1), size_type(0));
4645 _M_rep()->_M_set_leaked();
4646 return iterator(_M_data() + __pos);
4647 }
4648
4649 /**
4650 * @brief Remove a range of characters.
4651 * @param __first Iterator referencing the first character to remove.
4652 * @param __last Iterator referencing the end of the range.
4653 * @return Iterator referencing location of first after removal.
4654 *
4655 * Removes the characters in the range [first,last) from this string.
4656 * The value of the string doesn't change if an error is thrown.
4657 */
4658 iterator
4659 erase(iterator __first, iterator __last);
4660
4661#if __cplusplus >= 201103L
4662 /**
4663 * @brief Remove the last character.
4664 *
4665 * The string must be non-empty.
4666 */
4667 void
4668 pop_back() // FIXME C++11: should be noexcept.
4669 {
4670 __glibcxx_assert(!empty());
4671 erase(size() - 1, 1);
4672 }
4673#endif // C++11
4674
4675 /**
4676 * @brief Replace characters with value from another string.
4677 * @param __pos Index of first character to replace.
4678 * @param __n Number of characters to be replaced.
4679 * @param __str String to insert.
4680 * @return Reference to this string.
4681 * @throw std::out_of_range If @a pos is beyond the end of this
4682 * string.
4683 * @throw std::length_error If new length exceeds @c max_size().
4684 *
4685 * Removes the characters in the range [__pos,__pos+__n) from
4686 * this string. In place, the value of @a __str is inserted.
4687 * If @a __pos is beyond end of string, out_of_range is thrown.
4688 * If the length of the result exceeds max_size(), length_error
4689 * is thrown. The value of the string doesn't change if an
4690 * error is thrown.
4691 */
4692 basic_string&
4693 replace(size_type __pos, size_type __n, const basic_string& __str)
4694 { return this->replace(__pos, __n, __str._M_data(), __str.size()); }
4695
4696 /**
4697 * @brief Replace characters with value from another string.
4698 * @param __pos1 Index of first character to replace.
4699 * @param __n1 Number of characters to be replaced.
4700 * @param __str String to insert.
4701 * @param __pos2 Index of first character of str to use.
4702 * @param __n2 Number of characters from str to use.
4703 * @return Reference to this string.
4704 * @throw std::out_of_range If @a __pos1 > size() or @a __pos2 >
4705 * __str.size().
4706 * @throw std::length_error If new length exceeds @c max_size().
4707 *
4708 * Removes the characters in the range [__pos1,__pos1 + n) from this
4709 * string. In place, the value of @a __str is inserted. If @a __pos is
4710 * beyond end of string, out_of_range is thrown. If the length of the
4711 * result exceeds max_size(), length_error is thrown. The value of the
4712 * string doesn't change if an error is thrown.
4713 */
4714 basic_string&
4715 replace(size_type __pos1, size_type __n1, const basic_string& __str,
4716 size_type __pos2, size_type __n2 = npos)
4717 { return this->replace(__pos1, __n1, __str._M_data()
4718 + __str._M_check(__pos2, "basic_string::replace"),
4719 __str._M_limit(__pos2, __n2)); }
4720
4721 /**
4722 * @brief Replace characters with value of a C substring.
4723 * @param __pos Index of first character to replace.
4724 * @param __n1 Number of characters to be replaced.
4725 * @param __s C string to insert.
4726 * @param __n2 Number of characters from @a s to use.
4727 * @return Reference to this string.
4728 * @throw std::out_of_range If @a pos1 > size().
4729 * @throw std::length_error If new length exceeds @c max_size().
4730 *
4731 * Removes the characters in the range [__pos,__pos + __n1)
4732 * from this string. In place, the first @a __n2 characters of
4733 * @a __s are inserted, or all of @a __s if @a __n2 is too large. If
4734 * @a __pos is beyond end of string, out_of_range is thrown. If
4735 * the length of result exceeds max_size(), length_error is
4736 * thrown. The value of the string doesn't change if an error
4737 * is thrown.
4738 */
4739 basic_string&
4740 replace(size_type __pos, size_type __n1, const _CharT* __s,
4741 size_type __n2);
4742
4743 /**
4744 * @brief Replace characters with value of a C string.
4745 * @param __pos Index of first character to replace.
4746 * @param __n1 Number of characters to be replaced.
4747 * @param __s C string to insert.
4748 * @return Reference to this string.
4749 * @throw std::out_of_range If @a pos > size().
4750 * @throw std::length_error If new length exceeds @c max_size().
4751 *
4752 * Removes the characters in the range [__pos,__pos + __n1)
4753 * from this string. In place, the characters of @a __s are
4754 * inserted. If @a __pos is beyond end of string, out_of_range
4755 * is thrown. If the length of result exceeds max_size(),
4756 * length_error is thrown. The value of the string doesn't
4757 * change if an error is thrown.
4758 */
4759 basic_string&
4760 replace(size_type __pos, size_type __n1, const _CharT* __s)
4761 {
4762 __glibcxx_requires_string(__s);
4763 return this->replace(__pos, __n1, __s, traits_type::length(__s));
4764 }
4765
4766 /**
4767 * @brief Replace characters with multiple characters.
4768 * @param __pos Index of first character to replace.
4769 * @param __n1 Number of characters to be replaced.
4770 * @param __n2 Number of characters to insert.
4771 * @param __c Character to insert.
4772 * @return Reference to this string.
4773 * @throw std::out_of_range If @a __pos > size().
4774 * @throw std::length_error If new length exceeds @c max_size().
4775 *
4776 * Removes the characters in the range [pos,pos + n1) from this
4777 * string. In place, @a __n2 copies of @a __c are inserted.
4778 * If @a __pos is beyond end of string, out_of_range is thrown.
4779 * If the length of result exceeds max_size(), length_error is
4780 * thrown. The value of the string doesn't change if an error
4781 * is thrown.
4782 */
4783 basic_string&
4784 replace(size_type __pos, size_type __n1, size_type __n2, _CharT __c)
4785 { return _M_replace_aux(_M_check(__pos, "basic_string::replace"),
4786 _M_limit(__pos, __n1), __n2, __c); }
4787
4788 /**
4789 * @brief Replace range of characters with string.
4790 * @param __i1 Iterator referencing start of range to replace.
4791 * @param __i2 Iterator referencing end of range to replace.
4792 * @param __str String value to insert.
4793 * @return Reference to this string.
4794 * @throw std::length_error If new length exceeds @c max_size().
4795 *
4796 * Removes the characters in the range [__i1,__i2). In place,
4797 * the value of @a __str is inserted. If the length of result
4798 * exceeds max_size(), length_error is thrown. The value of
4799 * the string doesn't change if an error is thrown.
4800 */
4801 basic_string&
4802 replace(iterator __i1, iterator __i2, const basic_string& __str)
4803 { return this->replace(__i1, __i2, __str._M_data(), __str.size()); }
4804
4805 /**
4806 * @brief Replace range of characters with C substring.
4807 * @param __i1 Iterator referencing start of range to replace.
4808 * @param __i2 Iterator referencing end of range to replace.
4809 * @param __s C string value to insert.
4810 * @param __n Number of characters from s to insert.
4811 * @return Reference to this string.
4812 * @throw std::length_error If new length exceeds @c max_size().
4813 *
4814 * Removes the characters in the range [__i1,__i2). In place,
4815 * the first @a __n characters of @a __s are inserted. If the
4816 * length of result exceeds max_size(), length_error is thrown.
4817 * The value of the string doesn't change if an error is
4818 * thrown.
4819 */
4820 basic_string&
4821 replace(iterator __i1, iterator __i2, const _CharT* __s, size_type __n)
4822 {
4823 _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1 && __i1 <= __i2
4824 && __i2 <= _M_iend());
4825 return this->replace(__i1 - _M_ibegin(), __i2 - __i1, __s, __n);
4826 }
4827
4828 /**
4829 * @brief Replace range of characters with C string.
4830 * @param __i1 Iterator referencing start of range to replace.
4831 * @param __i2 Iterator referencing end of range to replace.
4832 * @param __s C string value to insert.
4833 * @return Reference to this string.
4834 * @throw std::length_error If new length exceeds @c max_size().
4835 *
4836 * Removes the characters in the range [__i1,__i2). In place,
4837 * the characters of @a __s are inserted. If the length of
4838 * result exceeds max_size(), length_error is thrown. The
4839 * value of the string doesn't change if an error is thrown.
4840 */
4841 basic_string&
4842 replace(iterator __i1, iterator __i2, const _CharT* __s)
4843 {
4844 __glibcxx_requires_string(__s);
4845 return this->replace(__i1, __i2, __s, traits_type::length(__s));
4846 }
4847
4848 /**
4849 * @brief Replace range of characters with multiple characters
4850 * @param __i1 Iterator referencing start of range to replace.
4851 * @param __i2 Iterator referencing end of range to replace.
4852 * @param __n Number of characters to insert.
4853 * @param __c Character to insert.
4854 * @return Reference to this string.
4855 * @throw std::length_error If new length exceeds @c max_size().
4856 *
4857 * Removes the characters in the range [__i1,__i2). In place,
4858 * @a __n copies of @a __c are inserted. If the length of
4859 * result exceeds max_size(), length_error is thrown. The
4860 * value of the string doesn't change if an error is thrown.
4861 */
4862 basic_string&
4863 replace(iterator __i1, iterator __i2, size_type __n, _CharT __c)
4864 {
4865 _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1 && __i1 <= __i2
4866 && __i2 <= _M_iend());
4867 return _M_replace_aux(__i1 - _M_ibegin(), __i2 - __i1, __n, __c);
4868 }
4869
4870 /**
4871 * @brief Replace range of characters with range.
4872 * @param __i1 Iterator referencing start of range to replace.
4873 * @param __i2 Iterator referencing end of range to replace.
4874 * @param __k1 Iterator referencing start of range to insert.
4875 * @param __k2 Iterator referencing end of range to insert.
4876 * @return Reference to this string.
4877 * @throw std::length_error If new length exceeds @c max_size().
4878 *
4879 * Removes the characters in the range [__i1,__i2). In place,
4880 * characters in the range [__k1,__k2) are inserted. If the
4881 * length of result exceeds max_size(), length_error is thrown.
4882 * The value of the string doesn't change if an error is
4883 * thrown.
4884 */
4885 template<class _InputIterator>
4886 basic_string&
4887 replace(iterator __i1, iterator __i2,
4888 _InputIterator __k1, _InputIterator __k2)
4889 {
4890 _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1 && __i1 <= __i2
4891 && __i2 <= _M_iend());
4892 __glibcxx_requires_valid_range(__k1, __k2);
4893 typedef typename std::__is_integer<_InputIterator>::__type _Integral;
4894 return _M_replace_dispatch(__i1, __i2, __k1, __k2, _Integral());
4895 }
4896
4897 // Specializations for the common case of pointer and iterator:
4898 // useful to avoid the overhead of temporary buffering in _M_replace.
4899 basic_string&
4900 replace(iterator __i1, iterator __i2, _CharT* __k1, _CharT* __k2)
4901 {
4902 _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1 && __i1 <= __i2
4903 && __i2 <= _M_iend());
4904 __glibcxx_requires_valid_range(__k1, __k2);
4905 return this->replace(__i1 - _M_ibegin(), __i2 - __i1,
4906 __k1, __k2 - __k1);
4907 }
4908
4909 basic_string&
4910 replace(iterator __i1, iterator __i2,
4911 const _CharT* __k1, const _CharT* __k2)
4912 {
4913 _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1 && __i1 <= __i2
4914 && __i2 <= _M_iend());
4915 __glibcxx_requires_valid_range(__k1, __k2);
4916 return this->replace(__i1 - _M_ibegin(), __i2 - __i1,
4917 __k1, __k2 - __k1);
4918 }
4919
4920 basic_string&
4921 replace(iterator __i1, iterator __i2, iterator __k1, iterator __k2)
4922 {
4923 _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1 && __i1 <= __i2
4924 && __i2 <= _M_iend());
4925 __glibcxx_requires_valid_range(__k1, __k2);
4926 return this->replace(__i1 - _M_ibegin(), __i2 - __i1,
4927 __k1.base(), __k2 - __k1);
4928 }
4929
4930 basic_string&
4931 replace(iterator __i1, iterator __i2,
4932 const_iterator __k1, const_iterator __k2)
4933 {
4934 _GLIBCXX_DEBUG_PEDASSERT(_M_ibegin() <= __i1 && __i1 <= __i2
4935 && __i2 <= _M_iend());
4936 __glibcxx_requires_valid_range(__k1, __k2);
4937 return this->replace(__i1 - _M_ibegin(), __i2 - __i1,
4938 __k1.base(), __k2 - __k1);
4939 }
4940
4941#if __cplusplus >= 201103L
4942 /**
4943 * @brief Replace range of characters with initializer_list.
4944 * @param __i1 Iterator referencing start of range to replace.
4945 * @param __i2 Iterator referencing end of range to replace.
4946 * @param __l The initializer_list of characters to insert.
4947 * @return Reference to this string.
4948 * @throw std::length_error If new length exceeds @c max_size().
4949 *
4950 * Removes the characters in the range [__i1,__i2). In place,
4951 * characters in the range [__k1,__k2) are inserted. If the
4952 * length of result exceeds max_size(), length_error is thrown.
4953 * The value of the string doesn't change if an error is
4954 * thrown.
4955 */
4956 basic_string& replace(iterator __i1, iterator __i2,
4957 initializer_list<_CharT> __l)
4958 { return this->replace(__i1, __i2, __l.begin(), __l.end()); }
4959#endif // C++11
4960
4961#if __cplusplus > 201402L
4962 /**
4963 * @brief Replace range of characters with string_view.
4964 * @param __pos The position to replace at.
4965 * @param __n The number of characters to replace.
4966 * @param __svt The object convertible to string_view to insert.
4967 * @return Reference to this string.
4968 */
4969 template<typename _Tp>
4970 _If_sv<_Tp, basic_string&>
4971 replace(size_type __pos, size_type __n, const _Tp& __svt)
4972 {
4973 __sv_type __sv = __svt;
4974 return this->replace(__pos, __n, __sv.data(), __sv.size());
4975 }
4976
4977 /**
4978 * @brief Replace range of characters with string_view.
4979 * @param __pos1 The position to replace at.
4980 * @param __n1 The number of characters to replace.
4981 * @param __svt The object convertible to string_view to insert from.
4982 * @param __pos2 The position in the string_view to insert from.
4983 * @param __n2 The number of characters to insert.
4984 * @return Reference to this string.
4985 */
4986 template<typename _Tp>
4987 _If_sv<_Tp, basic_string&>
4988 replace(size_type __pos1, size_type __n1, const _Tp& __svt,
4989 size_type __pos2, size_type __n2 = npos)
4990 {
4991 __sv_type __sv = __svt;
4992 return this->replace(__pos1, __n1,
4993 __sv.data() + __sv._M_check(__pos2, "basic_string::replace"),
4994 __sv._M_limit(__pos2, __n2));
4995 }
4996
4997 /**
4998 * @brief Replace range of characters with string_view.
4999 * @param __i1 An iterator referencing the start position
5000 to replace at.
5001 * @param __i2 An iterator referencing the end position
5002 for the replace.
5003 * @param __svt The object convertible to string_view to insert from.
5004 * @return Reference to this string.
5005 */
5006 template<typename _Tp>
5007 _If_sv<_Tp, basic_string&>
5008 replace(const_iterator __i1, const_iterator __i2, const _Tp& __svt)
5009 {
5010 __sv_type __sv = __svt;
5011 return this->replace(__i1 - begin(), __i2 - __i1, __sv);
5012 }
5013#endif // C++17
5014
5015 private:
5016 template<class _Integer>
5017 basic_string&
5018 _M_replace_dispatch(iterator __i1, iterator __i2, _Integer __n,
5019 _Integer __val, __true_type)
5020 { return _M_replace_aux(__i1 - _M_ibegin(), __i2 - __i1, __n, __val); }
5021
5022 template<class _InputIterator>
5023 basic_string&
5024 _M_replace_dispatch(iterator __i1, iterator __i2, _InputIterator __k1,
5025 _InputIterator __k2, __false_type);
5026
5027 basic_string&
5028 _M_replace_aux(size_type __pos1, size_type __n1, size_type __n2,
5029 _CharT __c);
5030
5031 basic_string&
5032 _M_replace_safe(size_type __pos1, size_type __n1, const _CharT* __s,
5033 size_type __n2);
5034
5035 // _S_construct_aux is used to implement the 21.3.1 para 15 which
5036 // requires special behaviour if _InIter is an integral type
5037 template<class _InIterator>
5038 static _CharT*
5039 _S_construct_aux(_InIterator __beg, _InIterator __end,
5040 const _Alloc& __a, __false_type)
5041 {
5042 typedef typename iterator_traits<_InIterator>::iterator_category _Tag;
5043 return _S_construct(__beg, __end, __a, _Tag());
5044 }
5045
5046 // _GLIBCXX_RESOLVE_LIB_DEFECTS
5047 // 438. Ambiguity in the "do the right thing" clause
5048 template<class _Integer>
5049 static _CharT*
5050 _S_construct_aux(_Integer __beg, _Integer __end,
5051 const _Alloc& __a, __true_type)
5052 { return _S_construct_aux_2(static_cast<size_type>(__beg),
5053 __end, __a); }
5054
5055 static _CharT*
5056 _S_construct_aux_2(size_type __req, _CharT __c, const _Alloc& __a)
5057 { return _S_construct(__req, __c, __a); }
5058
5059 template<class _InIterator>
5060 static _CharT*
5061 _S_construct(_InIterator __beg, _InIterator __end, const _Alloc& __a)
5062 {
5063 typedef typename std::__is_integer<_InIterator>::__type _Integral;
5064 return _S_construct_aux(__beg, __end, __a, _Integral());
5065 }
5066
5067 // For Input Iterators, used in istreambuf_iterators, etc.
5068 template<class _InIterator>
5069 static _CharT*
5070 _S_construct(_InIterator __beg, _InIterator __end, const _Alloc& __a,
5071 input_iterator_tag);
5072
5073 // For forward_iterators up to random_access_iterators, used for
5074 // string::iterator, _CharT*, etc.
5075 template<class _FwdIterator>
5076 static _CharT*
5077 _S_construct(_FwdIterator __beg, _FwdIterator __end, const _Alloc& __a,
5078 forward_iterator_tag);
5079
5080 static _CharT*
5081 _S_construct(size_type __req, _CharT __c, const _Alloc& __a);
5082
5083 public:
5084
5085 /**
5086 * @brief Copy substring into C string.
5087 * @param __s C string to copy value into.
5088 * @param __n Number of characters to copy.
5089 * @param __pos Index of first character to copy.
5090 * @return Number of characters actually copied
5091 * @throw std::out_of_range If __pos > size().
5092 *
5093 * Copies up to @a __n characters starting at @a __pos into the
5094 * C string @a __s. If @a __pos is %greater than size(),
5095 * out_of_range is thrown.
5096 */
5097 size_type
5098 copy(_CharT* __s, size_type __n, size_type __pos = 0) const;
5099
5100 /**
5101 * @brief Swap contents with another string.
5102 * @param __s String to swap with.
5103 *
5104 * Exchanges the contents of this string with that of @a __s in constant
5105 * time.
5106 */
5107 // PR 58265, this should be noexcept.
5108 void
5109 swap(basic_string& __s);
5110
5111 // String operations:
5112 /**
5113 * @brief Return const pointer to null-terminated contents.
5114 *
5115 * This is a handle to internal data. Do not modify or dire things may
5116 * happen.
5117 */
5118 const _CharT*
5119 c_str() const _GLIBCXX_NOEXCEPT
5120 { return _M_data(); }
5121
5122 /**
5123 * @brief Return const pointer to contents.
5124 *
5125 * This is a pointer to internal data. It is undefined to modify
5126 * the contents through the returned pointer. To get a pointer that
5127 * allows modifying the contents use @c &str[0] instead,
5128 * (or in C++17 the non-const @c str.data() overload).
5129 */
5130 const _CharT*
5131 data() const _GLIBCXX_NOEXCEPT
5132 { return _M_data(); }
5133
5134#if __cplusplus > 201402L
5135 /**
5136 * @brief Return non-const pointer to contents.
5137 *
5138 * This is a pointer to the character sequence held by the string.
5139 * Modifying the characters in the sequence is allowed.
5140 */
5141 _CharT*
5142 data() noexcept
5143 {
5144 _M_leak();
5145 return _M_data();
5146 }
5147#endif
5148
5149 /**
5150 * @brief Return copy of allocator used to construct this string.
5151 */
5152 allocator_type
5153 get_allocator() const _GLIBCXX_NOEXCEPT
5154 { return _M_dataplus; }
5155
5156 /**
5157 * @brief Find position of a C substring.
5158 * @param __s C string to locate.
5159 * @param __pos Index of character to search from.
5160 * @param __n Number of characters from @a s to search for.
5161 * @return Index of start of first occurrence.
5162 *
5163 * Starting from @a __pos, searches forward for the first @a
5164 * __n characters in @a __s within this string. If found,
5165 * returns the index where it begins. If not found, returns
5166 * npos.
5167 */
5168 size_type
5169 find(const _CharT* __s, size_type __pos, size_type __n) const
5170 _GLIBCXX_NOEXCEPT;
5171
5172 /**
5173 * @brief Find position of a string.
5174 * @param __str String to locate.
5175 * @param __pos Index of character to search from (default 0).
5176 * @return Index of start of first occurrence.
5177 *
5178 * Starting from @a __pos, searches forward for value of @a __str within
5179 * this string. If found, returns the index where it begins. If not
5180 * found, returns npos.
5181 */
5182 size_type
5183 find(const basic_string& __str, size_type __pos = 0) const
5184 _GLIBCXX_NOEXCEPT
5185 { return this->find(__str.data(), __pos, __str.size()); }
5186
5187 /**
5188 * @brief Find position of a C string.
5189 * @param __s C string to locate.
5190 * @param __pos Index of character to search from (default 0).
5191 * @return Index of start of first occurrence.
5192 *
5193 * Starting from @a __pos, searches forward for the value of @a
5194 * __s within this string. If found, returns the index where
5195 * it begins. If not found, returns npos.
5196 */
5197 size_type
5198 find(const _CharT* __s, size_type __pos = 0) const _GLIBCXX_NOEXCEPT
5199 {
5200 __glibcxx_requires_string(__s);
5201 return this->find(__s, __pos, traits_type::length(__s));
5202 }
5203
5204 /**
5205 * @brief Find position of a character.
5206 * @param __c Character to locate.
5207 * @param __pos Index of character to search from (default 0).
5208 * @return Index of first occurrence.
5209 *
5210 * Starting from @a __pos, searches forward for @a __c within
5211 * this string. If found, returns the index where it was
5212 * found. If not found, returns npos.
5213 */
5214 size_type
5215 find(_CharT __c, size_type __pos = 0) const _GLIBCXX_NOEXCEPT;
5216
5217#if __cplusplus > 201402L
5218 /**
5219 * @brief Find position of a string_view.
5220 * @param __svt The object convertible to string_view to locate.
5221 * @param __pos Index of character to search from (default 0).
5222 * @return Index of start of first occurrence.
5223 */
5224 template<typename _Tp>
5225 _If_sv<_Tp, size_type>
5226 find(const _Tp& __svt, size_type __pos = 0) const
5227 noexcept(is_same<_Tp, __sv_type>::value)
5228 {
5229 __sv_type __sv = __svt;
5230 return this->find(__sv.data(), __pos, __sv.size());
5231 }
5232#endif // C++17
5233
5234 /**
5235 * @brief Find last position of a string.
5236 * @param __str String to locate.
5237 * @param __pos Index of character to search back from (default end).
5238 * @return Index of start of last occurrence.
5239 *
5240 * Starting from @a __pos, searches backward for value of @a
5241 * __str within this string. If found, returns the index where
5242 * it begins. If not found, returns npos.
5243 */
5244 size_type
5245 rfind(const basic_string& __str, size_type __pos = npos) const
5246 _GLIBCXX_NOEXCEPT
5247 { return this->rfind(__str.data(), __pos, __str.size()); }
5248
5249 /**
5250 * @brief Find last position of a C substring.
5251 * @param __s C string to locate.
5252 * @param __pos Index of character to search back from.
5253 * @param __n Number of characters from s to search for.
5254 * @return Index of start of last occurrence.
5255 *
5256 * Starting from @a __pos, searches backward for the first @a
5257 * __n characters in @a __s within this string. If found,
5258 * returns the index where it begins. If not found, returns
5259 * npos.
5260 */
5261 size_type
5262 rfind(const _CharT* __s, size_type __pos, size_type __n) const
5263 _GLIBCXX_NOEXCEPT;
5264
5265 /**
5266 * @brief Find last position of a C string.
5267 * @param __s C string to locate.
5268 * @param __pos Index of character to start search at (default end).
5269 * @return Index of start of last occurrence.
5270 *
5271 * Starting from @a __pos, searches backward for the value of
5272 * @a __s within this string. If found, returns the index
5273 * where it begins. If not found, returns npos.
5274 */
5275 size_type
5276 rfind(const _CharT* __s, size_type __pos = npos) const _GLIBCXX_NOEXCEPT
5277 {
5278 __glibcxx_requires_string(__s);
5279 return this->rfind(__s, __pos, traits_type::length(__s));
5280 }
5281
5282 /**
5283 * @brief Find last position of a character.
5284 * @param __c Character to locate.
5285 * @param __pos Index of character to search back from (default end).
5286 * @return Index of last occurrence.
5287 *
5288 * Starting from @a __pos, searches backward for @a __c within
5289 * this string. If found, returns the index where it was
5290 * found. If not found, returns npos.
5291 */
5292 size_type
5293 rfind(_CharT __c, size_type __pos = npos) const _GLIBCXX_NOEXCEPT;
5294
5295#if __cplusplus > 201402L
5296 /**
5297 * @brief Find last position of a string_view.
5298 * @param __svt The object convertible to string_view to locate.
5299 * @param __pos Index of character to search back from (default end).
5300 * @return Index of start of last occurrence.
5301 */
5302 template<typename _Tp>
5303 _If_sv<_Tp, size_type>
5304 rfind(const _Tp& __svt, size_type __pos = npos) const
5305 noexcept(is_same<_Tp, __sv_type>::value)
5306 {
5307 __sv_type __sv = __svt;
5308 return this->rfind(__sv.data(), __pos, __sv.size());
5309 }
5310#endif // C++17
5311
5312 /**
5313 * @brief Find position of a character of string.
5314 * @param __str String containing characters to locate.
5315 * @param __pos Index of character to search from (default 0).
5316 * @return Index of first occurrence.
5317 *
5318 * Starting from @a __pos, searches forward for one of the
5319 * characters of @a __str within this string. If found,
5320 * returns the index where it was found. If not found, returns
5321 * npos.
5322 */
5323 size_type
5324 find_first_of(const basic_string& __str, size_type __pos = 0) const
5325 _GLIBCXX_NOEXCEPT
5326 { return this->find_first_of(__str.data(), __pos, __str.size()); }
5327
5328 /**
5329 * @brief Find position of a character of C substring.
5330 * @param __s String containing characters to locate.
5331 * @param __pos Index of character to search from.
5332 * @param __n Number of characters from s to search for.
5333 * @return Index of first occurrence.
5334 *
5335 * Starting from @a __pos, searches forward for one of the
5336 * first @a __n characters of @a __s within this string. If
5337 * found, returns the index where it was found. If not found,
5338 * returns npos.
5339 */
5340 size_type
5341 find_first_of(const _CharT* __s, size_type __pos, size_type __n) const
5342 _GLIBCXX_NOEXCEPT;
5343
5344 /**
5345 * @brief Find position of a character of C string.
5346 * @param __s String containing characters to locate.
5347 * @param __pos Index of character to search from (default 0).
5348 * @return Index of first occurrence.
5349 *
5350 * Starting from @a __pos, searches forward for one of the
5351 * characters of @a __s within this string. If found, returns
5352 * the index where it was found. If not found, returns npos.
5353 */
5354 size_type
5355 find_first_of(const _CharT* __s, size_type __pos = 0) const
5356 _GLIBCXX_NOEXCEPT
5357 {
5358 __glibcxx_requires_string(__s);
5359 return this->find_first_of(__s, __pos, traits_type::length(__s));
5360 }
5361
5362 /**
5363 * @brief Find position of a character.
5364 * @param __c Character to locate.
5365 * @param __pos Index of character to search from (default 0).
5366 * @return Index of first occurrence.
5367 *
5368 * Starting from @a __pos, searches forward for the character
5369 * @a __c within this string. If found, returns the index
5370 * where it was found. If not found, returns npos.
5371 *
5372 * Note: equivalent to find(__c, __pos).
5373 */
5374 size_type
5375 find_first_of(_CharT __c, size_type __pos = 0) const _GLIBCXX_NOEXCEPT
5376 { return this->find(__c, __pos); }
5377
5378#if __cplusplus > 201402L
5379 /**
5380 * @brief Find position of a character of a string_view.
5381 * @param __svt An object convertible to string_view containing
5382 * characters to locate.
5383 * @param __pos Index of character to search from (default 0).
5384 * @return Index of first occurrence.
5385 */
5386 template<typename _Tp>
5387 _If_sv<_Tp, size_type>
5388 find_first_of(const _Tp& __svt, size_type __pos = 0) const
5389 noexcept(is_same<_Tp, __sv_type>::value)
5390 {
5391 __sv_type __sv = __svt;
5392 return this->find_first_of(__sv.data(), __pos, __sv.size());
5393 }
5394#endif // C++17
5395
5396 /**
5397 * @brief Find last position of a character of string.
5398 * @param __str String containing characters to locate.
5399 * @param __pos Index of character to search back from (default end).
5400 * @return Index of last occurrence.
5401 *
5402 * Starting from @a __pos, searches backward for one of the
5403 * characters of @a __str within this string. If found,
5404 * returns the index where it was found. If not found, returns
5405 * npos.
5406 */
5407 size_type
5408 find_last_of(const basic_string& __str, size_type __pos = npos) const
5409 _GLIBCXX_NOEXCEPT
5410 { return this->find_last_of(__str.data(), __pos, __str.size()); }
5411
5412 /**
5413 * @brief Find last position of a character of C substring.
5414 * @param __s C string containing characters to locate.
5415 * @param __pos Index of character to search back from.
5416 * @param __n Number of characters from s to search for.
5417 * @return Index of last occurrence.
5418 *
5419 * Starting from @a __pos, searches backward for one of the
5420 * first @a __n characters of @a __s within this string. If
5421 * found, returns the index where it was found. If not found,
5422 * returns npos.
5423 */
5424 size_type
5425 find_last_of(const _CharT* __s, size_type __pos, size_type __n) const
5426 _GLIBCXX_NOEXCEPT;
5427
5428 /**
5429 * @brief Find last position of a character of C string.
5430 * @param __s C string containing characters to locate.
5431 * @param __pos Index of character to search back from (default end).
5432 * @return Index of last occurrence.
5433 *
5434 * Starting from @a __pos, searches backward for one of the
5435 * characters of @a __s within this string. If found, returns
5436 * the index where it was found. If not found, returns npos.
5437 */
5438 size_type
5439 find_last_of(const _CharT* __s, size_type __pos = npos) const
5440 _GLIBCXX_NOEXCEPT
5441 {
5442 __glibcxx_requires_string(__s);
5443 return this->find_last_of(__s, __pos, traits_type::length(__s));
5444 }
5445
5446 /**
5447 * @brief Find last position of a character.
5448 * @param __c Character to locate.
5449 * @param __pos Index of character to search back from (default end).
5450 * @return Index of last occurrence.
5451 *
5452 * Starting from @a __pos, searches backward for @a __c within
5453 * this string. If found, returns the index where it was
5454 * found. If not found, returns npos.
5455 *
5456 * Note: equivalent to rfind(__c, __pos).
5457 */
5458 size_type
5459 find_last_of(_CharT __c, size_type __pos = npos) const _GLIBCXX_NOEXCEPT
5460 { return this->rfind(__c, __pos); }
5461
5462#if __cplusplus > 201402L
5463 /**
5464 * @brief Find last position of a character of string.
5465 * @param __svt An object convertible to string_view containing
5466 * characters to locate.
5467 * @param __pos Index of character to search back from (default end).
5468 * @return Index of last occurrence.
5469 */
5470 template<typename _Tp>
5471 _If_sv<_Tp, size_type>
5472 find_last_of(const _Tp& __svt, size_type __pos = npos) const
5473 noexcept(is_same<_Tp, __sv_type>::value)
5474 {
5475 __sv_type __sv = __svt;
5476 return this->find_last_of(__sv.data(), __pos, __sv.size());
5477 }
5478#endif // C++17
5479
5480 /**
5481 * @brief Find position of a character not in string.
5482 * @param __str String containing characters to avoid.
5483 * @param __pos Index of character to search from (default 0).
5484 * @return Index of first occurrence.
5485 *
5486 * Starting from @a __pos, searches forward for a character not contained
5487 * in @a __str within this string. If found, returns the index where it
5488 * was found. If not found, returns npos.
5489 */
5490 size_type
5491 find_first_not_of(const basic_string& __str, size_type __pos = 0) const
5492 _GLIBCXX_NOEXCEPT
5493 { return this->find_first_not_of(__str.data(), __pos, __str.size()); }
5494
5495 /**
5496 * @brief Find position of a character not in C substring.
5497 * @param __s C string containing characters to avoid.
5498 * @param __pos Index of character to search from.
5499 * @param __n Number of characters from __s to consider.
5500 * @return Index of first occurrence.
5501 *
5502 * Starting from @a __pos, searches forward for a character not
5503 * contained in the first @a __n characters of @a __s within
5504 * this string. If found, returns the index where it was
5505 * found. If not found, returns npos.
5506 */
5507 size_type
5508 find_first_not_of(const _CharT* __s, size_type __pos,
5509 size_type __n) const _GLIBCXX_NOEXCEPT;
5510
5511 /**
5512 * @brief Find position of a character not in C string.
5513 * @param __s C string containing characters to avoid.
5514 * @param __pos Index of character to search from (default 0).
5515 * @return Index of first occurrence.
5516 *
5517 * Starting from @a __pos, searches forward for a character not
5518 * contained in @a __s within this string. If found, returns
5519 * the index where it was found. If not found, returns npos.
5520 */
5521 size_type
5522 find_first_not_of(const _CharT* __s, size_type __pos = 0) const
5523 _GLIBCXX_NOEXCEPT
5524 {
5525 __glibcxx_requires_string(__s);
5526 return this->find_first_not_of(__s, __pos, traits_type::length(__s));
5527 }
5528
5529 /**
5530 * @brief Find position of a different character.
5531 * @param __c Character to avoid.
5532 * @param __pos Index of character to search from (default 0).
5533 * @return Index of first occurrence.
5534 *
5535 * Starting from @a __pos, searches forward for a character
5536 * other than @a __c within this string. If found, returns the
5537 * index where it was found. If not found, returns npos.
5538 */
5539 size_type
5540 find_first_not_of(_CharT __c, size_type __pos = 0) const
5541 _GLIBCXX_NOEXCEPT;
5542
5543#if __cplusplus > 201402L
5544 /**
5545 * @brief Find position of a character not in a string_view.
5546 * @param __svt An object convertible to string_view containing
5547 * characters to avoid.
5548 * @param __pos Index of character to search from (default 0).
5549 * @return Index of first occurrence.
5550 */
5551 template<typename _Tp>
5552 _If_sv<_Tp, size_type>
5553 find_first_not_of(const _Tp& __svt, size_type __pos = 0) const
5554 noexcept(is_same<_Tp, __sv_type>::value)
5555 {
5556 __sv_type __sv = __svt;
5557 return this->find_first_not_of(__sv.data(), __pos, __sv.size());
5558 }
5559#endif // C++17
5560
5561 /**
5562 * @brief Find last position of a character not in string.
5563 * @param __str String containing characters to avoid.
5564 * @param __pos Index of character to search back from (default end).
5565 * @return Index of last occurrence.
5566 *
5567 * Starting from @a __pos, searches backward for a character
5568 * not contained in @a __str within this string. If found,
5569 * returns the index where it was found. If not found, returns
5570 * npos.
5571 */
5572 size_type
5573 find_last_not_of(const basic_string& __str, size_type __pos = npos) const
5574 _GLIBCXX_NOEXCEPT
5575 { return this->find_last_not_of(__str.data(), __pos, __str.size()); }
5576
5577 /**
5578 * @brief Find last position of a character not in C substring.
5579 * @param __s C string containing characters to avoid.
5580 * @param __pos Index of character to search back from.
5581 * @param __n Number of characters from s to consider.
5582 * @return Index of last occurrence.
5583 *
5584 * Starting from @a __pos, searches backward for a character not
5585 * contained in the first @a __n characters of @a __s within this string.
5586 * If found, returns the index where it was found. If not found,
5587 * returns npos.
5588 */
5589 size_type
5590 find_last_not_of(const _CharT* __s, size_type __pos,
5591 size_type __n) const _GLIBCXX_NOEXCEPT;
5592 /**
5593 * @brief Find last position of a character not in C string.
5594 * @param __s C string containing characters to avoid.
5595 * @param __pos Index of character to search back from (default end).
5596 * @return Index of last occurrence.
5597 *
5598 * Starting from @a __pos, searches backward for a character
5599 * not contained in @a __s within this string. If found,
5600 * returns the index where it was found. If not found, returns
5601 * npos.
5602 */
5603 size_type
5604 find_last_not_of(const _CharT* __s, size_type __pos = npos) const
5605 _GLIBCXX_NOEXCEPT
5606 {
5607 __glibcxx_requires_string(__s);
5608 return this->find_last_not_of(__s, __pos, traits_type::length(__s));
5609 }
5610
5611 /**
5612 * @brief Find last position of a different character.
5613 * @param __c Character to avoid.
5614 * @param __pos Index of character to search back from (default end).
5615 * @return Index of last occurrence.
5616 *
5617 * Starting from @a __pos, searches backward for a character other than
5618 * @a __c within this string. If found, returns the index where it was
5619 * found. If not found, returns npos.
5620 */
5621 size_type
5622 find_last_not_of(_CharT __c, size_type __pos = npos) const
5623 _GLIBCXX_NOEXCEPT;
5624
5625#if __cplusplus > 201402L
5626 /**
5627 * @brief Find last position of a character not in a string_view.
5628 * @param __svt An object convertible to string_view containing
5629 * characters to avoid.
5630 * @param __pos Index of character to search back from (default end).
5631 * @return Index of last occurrence.
5632 */
5633 template<typename _Tp>
5634 _If_sv<_Tp, size_type>
5635 find_last_not_of(const _Tp& __svt, size_type __pos = npos) const
5636 noexcept(is_same<_Tp, __sv_type>::value)
5637 {
5638 __sv_type __sv = __svt;
5639 return this->find_last_not_of(__sv.data(), __pos, __sv.size());
5640 }
5641#endif // C++17
5642
5643 /**
5644 * @brief Get a substring.
5645 * @param __pos Index of first character (default 0).
5646 * @param __n Number of characters in substring (default remainder).
5647 * @return The new string.
5648 * @throw std::out_of_range If __pos > size().
5649 *
5650 * Construct and return a new string using the @a __n
5651 * characters starting at @a __pos. If the string is too
5652 * short, use the remainder of the characters. If @a __pos is
5653 * beyond the end of the string, out_of_range is thrown.
5654 */
5655 basic_string
5656 substr(size_type __pos = 0, size_type __n = npos) const
5657 { return basic_string(*this,
5658 _M_check(__pos, "basic_string::substr"), __n); }
5659
5660 /**
5661 * @brief Compare to a string.
5662 * @param __str String to compare against.
5663 * @return Integer < 0, 0, or > 0.
5664 *
5665 * Returns an integer < 0 if this string is ordered before @a
5666 * __str, 0 if their values are equivalent, or > 0 if this
5667 * string is ordered after @a __str. Determines the effective
5668 * length rlen of the strings to compare as the smallest of
5669 * size() and str.size(). The function then compares the two
5670 * strings by calling traits::compare(data(), str.data(),rlen).
5671 * If the result of the comparison is nonzero returns it,
5672 * otherwise the shorter one is ordered first.
5673 */
5674 int
5675 compare(const basic_string& __str) const
5676 {
5677 const size_type __size = this->size();
5678 const size_type __osize = __str.size();
5679 const size_type __len = std::min(__size, __osize);
5680
5681 int __r = traits_type::compare(_M_data(), __str.data(), __len);
5682 if (!__r)
5683 __r = _S_compare(__size, __osize);
5684 return __r;
5685 }
5686
5687#if __cplusplus > 201402L
5688 /**
5689 * @brief Compare to a string_view.
5690 * @param __svt An object convertible to string_view to compare against.
5691 * @return Integer < 0, 0, or > 0.
5692 */
5693 template<typename _Tp>
5694 _If_sv<_Tp, int>
5695 compare(const _Tp& __svt) const
5696 noexcept(is_same<_Tp, __sv_type>::value)
5697 {
5698 __sv_type __sv = __svt;
5699 const size_type __size = this->size();
5700 const size_type __osize = __sv.size();
5701 const size_type __len = std::min(__size, __osize);
5702
5703 int __r = traits_type::compare(_M_data(), __sv.data(), __len);
5704 if (!__r)
5705 __r = _S_compare(__size, __osize);
5706 return __r;
5707 }
5708
5709 /**
5710 * @brief Compare to a string_view.
5711 * @param __pos A position in the string to start comparing from.
5712 * @param __n The number of characters to compare.
5713 * @param __svt An object convertible to string_view to compare
5714 * against.
5715 * @return Integer < 0, 0, or > 0.
5716 */
5717 template<typename _Tp>
5718 _If_sv<_Tp, int>
5719 compare(size_type __pos, size_type __n, const _Tp& __svt) const
5720 noexcept(is_same<_Tp, __sv_type>::value)
5721 {
5722 __sv_type __sv = __svt;
5723 return __sv_type(*this).substr(__pos, __n).compare(__sv);
5724 }
5725
5726 /**
5727 * @brief Compare to a string_view.
5728 * @param __pos1 A position in the string to start comparing from.
5729 * @param __n1 The number of characters to compare.
5730 * @param __svt An object convertible to string_view to compare
5731 * against.
5732 * @param __pos2 A position in the string_view to start comparing from.
5733 * @param __n2 The number of characters to compare.
5734 * @return Integer < 0, 0, or > 0.
5735 */
5736 template<typename _Tp>
5737 _If_sv<_Tp, int>
5738 compare(size_type __pos1, size_type __n1, const _Tp& __svt,
5739 size_type __pos2, size_type __n2 = npos) const
5740 noexcept(is_same<_Tp, __sv_type>::value)
5741 {
5742 __sv_type __sv = __svt;
5743 return __sv_type(*this)
5744 .substr(__pos1, __n1).compare(__sv.substr(__pos2, __n2));
5745 }
5746#endif // C++17
5747
5748 /**
5749 * @brief Compare substring to a string.
5750 * @param __pos Index of first character of substring.
5751 * @param __n Number of characters in substring.
5752 * @param __str String to compare against.
5753 * @return Integer < 0, 0, or > 0.
5754 *
5755 * Form the substring of this string from the @a __n characters
5756 * starting at @a __pos. Returns an integer < 0 if the
5757 * substring is ordered before @a __str, 0 if their values are
5758 * equivalent, or > 0 if the substring is ordered after @a
5759 * __str. Determines the effective length rlen of the strings
5760 * to compare as the smallest of the length of the substring
5761 * and @a __str.size(). The function then compares the two
5762 * strings by calling
5763 * traits::compare(substring.data(),str.data(),rlen). If the
5764 * result of the comparison is nonzero returns it, otherwise
5765 * the shorter one is ordered first.
5766 */
5767 int
5768 compare(size_type __pos, size_type __n, const basic_string& __str) const;
5769
5770 /**
5771 * @brief Compare substring to a substring.
5772 * @param __pos1 Index of first character of substring.
5773 * @param __n1 Number of characters in substring.
5774 * @param __str String to compare against.
5775 * @param __pos2 Index of first character of substring of str.
5776 * @param __n2 Number of characters in substring of str.
5777 * @return Integer < 0, 0, or > 0.
5778 *
5779 * Form the substring of this string from the @a __n1
5780 * characters starting at @a __pos1. Form the substring of @a
5781 * __str from the @a __n2 characters starting at @a __pos2.
5782 * Returns an integer < 0 if this substring is ordered before
5783 * the substring of @a __str, 0 if their values are equivalent,
5784 * or > 0 if this substring is ordered after the substring of
5785 * @a __str. Determines the effective length rlen of the
5786 * strings to compare as the smallest of the lengths of the
5787 * substrings. The function then compares the two strings by
5788 * calling
5789 * traits::compare(substring.data(),str.substr(pos2,n2).data(),rlen).
5790 * If the result of the comparison is nonzero returns it,
5791 * otherwise the shorter one is ordered first.
5792 */
5793 int
5794 compare(size_type __pos1, size_type __n1, const basic_string& __str,
5795 size_type __pos2, size_type __n2 = npos) const;
5796
5797 /**
5798 * @brief Compare to a C string.
5799 * @param __s C string to compare against.
5800 * @return Integer < 0, 0, or > 0.
5801 *
5802 * Returns an integer < 0 if this string is ordered before @a __s, 0 if
5803 * their values are equivalent, or > 0 if this string is ordered after
5804 * @a __s. Determines the effective length rlen of the strings to
5805 * compare as the smallest of size() and the length of a string
5806 * constructed from @a __s. The function then compares the two strings
5807 * by calling traits::compare(data(),s,rlen). If the result of the
5808 * comparison is nonzero returns it, otherwise the shorter one is
5809 * ordered first.
5810 */
5811 int
5812 compare(const _CharT* __s) const _GLIBCXX_NOEXCEPT;
5813
5814 // _GLIBCXX_RESOLVE_LIB_DEFECTS
5815 // 5 String::compare specification questionable
5816 /**
5817 * @brief Compare substring to a C string.
5818 * @param __pos Index of first character of substring.
5819 * @param __n1 Number of characters in substring.
5820 * @param __s C string to compare against.
5821 * @return Integer < 0, 0, or > 0.
5822 *
5823 * Form the substring of this string from the @a __n1
5824 * characters starting at @a pos. Returns an integer < 0 if
5825 * the substring is ordered before @a __s, 0 if their values
5826 * are equivalent, or > 0 if the substring is ordered after @a
5827 * __s. Determines the effective length rlen of the strings to
5828 * compare as the smallest of the length of the substring and
5829 * the length of a string constructed from @a __s. The
5830 * function then compares the two string by calling
5831 * traits::compare(substring.data(),__s,rlen). If the result of
5832 * the comparison is nonzero returns it, otherwise the shorter
5833 * one is ordered first.
5834 */
5835 int
5836 compare(size_type __pos, size_type __n1, const _CharT* __s) const;
5837
5838 /**
5839 * @brief Compare substring against a character %array.
5840 * @param __pos Index of first character of substring.
5841 * @param __n1 Number of characters in substring.
5842 * @param __s character %array to compare against.
5843 * @param __n2 Number of characters of s.
5844 * @return Integer < 0, 0, or > 0.
5845 *
5846 * Form the substring of this string from the @a __n1
5847 * characters starting at @a __pos. Form a string from the
5848 * first @a __n2 characters of @a __s. Returns an integer < 0
5849 * if this substring is ordered before the string from @a __s,
5850 * 0 if their values are equivalent, or > 0 if this substring
5851 * is ordered after the string from @a __s. Determines the
5852 * effective length rlen of the strings to compare as the
5853 * smallest of the length of the substring and @a __n2. The
5854 * function then compares the two strings by calling
5855 * traits::compare(substring.data(),s,rlen). If the result of
5856 * the comparison is nonzero returns it, otherwise the shorter
5857 * one is ordered first.
5858 *
5859 * NB: s must have at least n2 characters, &apos;\\0&apos; has
5860 * no special meaning.
5861 */
5862 int
5863 compare(size_type __pos, size_type __n1, const _CharT* __s,
5864 size_type __n2) const;
5865
5866# ifdef _GLIBCXX_TM_TS_INTERNAL
5867 friend void
5868 ::_txnal_cow_string_C1_for_exceptions(void* that, const char* s,
5869 void* exc);
5870 friend const char*
5871 ::_txnal_cow_string_c_str(const void *that);
5872 friend void
5873 ::_txnal_cow_string_D1(void *that);
5874 friend void
5875 ::_txnal_cow_string_D1_commit(void *that);
5876# endif
5877 };
5878#endif // !_GLIBCXX_USE_CXX11_ABI
5879
5880#if __cpp_deduction_guides >= 201606
5881_GLIBCXX_BEGIN_NAMESPACE_CXX11
5882 template<typename _InputIterator, typename _CharT
5883 = typename iterator_traits<_InputIterator>::value_type,
5884 typename _Allocator = allocator<_CharT>,
5885 typename = _RequireInputIter<_InputIterator>,
5886 typename = _RequireAllocator<_Allocator>>
5887 basic_string(_InputIterator, _InputIterator, _Allocator = _Allocator())
5888 -> basic_string<_CharT, char_traits<_CharT>, _Allocator>;
5889
5890 // _GLIBCXX_RESOLVE_LIB_DEFECTS
5891 // 3075. basic_string needs deduction guides from basic_string_view
5892 template<typename _CharT, typename _Traits,
5893 typename _Allocator = allocator<_CharT>,
5894 typename = _RequireAllocator<_Allocator>>
5895 basic_string(basic_string_view<_CharT, _Traits>, const _Allocator& = _Allocator())
5896 -> basic_string<_CharT, _Traits, _Allocator>;
5897
5898 template<typename _CharT, typename _Traits,
5899 typename _Allocator = allocator<_CharT>,
5900 typename = _RequireAllocator<_Allocator>>
5901 basic_string(basic_string_view<_CharT, _Traits>,
5902 typename basic_string<_CharT, _Traits, _Allocator>::size_type,
5903 typename basic_string<_CharT, _Traits, _Allocator>::size_type,
5904 const _Allocator& = _Allocator())
5905 -> basic_string<_CharT, _Traits, _Allocator>;
5906_GLIBCXX_END_NAMESPACE_CXX11
5907#endif
5908
5909 // operator+
5910 /**
5911 * @brief Concatenate two strings.
5912 * @param __lhs First string.
5913 * @param __rhs Last string.
5914 * @return New string with value of @a __lhs followed by @a __rhs.
5915 */
5916 template<typename _CharT, typename _Traits, typename _Alloc>
5917 basic_string<_CharT, _Traits, _Alloc>
5918 operator+(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
5919 const basic_string<_CharT, _Traits, _Alloc>& __rhs)
5920 {
5921 basic_string<_CharT, _Traits, _Alloc> __str(__lhs);
5922 __str.append(__rhs);
5923 return __str;
5924 }
5925
5926 /**
5927 * @brief Concatenate C string and string.
5928 * @param __lhs First string.
5929 * @param __rhs Last string.
5930 * @return New string with value of @a __lhs followed by @a __rhs.
5931 */
5932 template<typename _CharT, typename _Traits, typename _Alloc>
5933 basic_string<_CharT,_Traits,_Alloc>
5934 operator+(const _CharT* __lhs,
5935 const basic_string<_CharT,_Traits,_Alloc>& __rhs);
5936
5937 /**
5938 * @brief Concatenate character and string.
5939 * @param __lhs First string.
5940 * @param __rhs Last string.
5941 * @return New string with @a __lhs followed by @a __rhs.
5942 */
5943 template<typename _CharT, typename _Traits, typename _Alloc>
5944 basic_string<_CharT,_Traits,_Alloc>
5945 operator+(_CharT __lhs, const basic_string<_CharT,_Traits,_Alloc>& __rhs);
5946
5947 /**
5948 * @brief Concatenate string and C string.
5949 * @param __lhs First string.
5950 * @param __rhs Last string.
5951 * @return New string with @a __lhs followed by @a __rhs.
5952 */
5953 template<typename _CharT, typename _Traits, typename _Alloc>
5954 inline basic_string<_CharT, _Traits, _Alloc>
5955 operator+(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
5956 const _CharT* __rhs)
5957 {
5958 basic_string<_CharT, _Traits, _Alloc> __str(__lhs);
5959 __str.append(__rhs);
5960 return __str;
5961 }
5962
5963 /**
5964 * @brief Concatenate string and character.
5965 * @param __lhs First string.
5966 * @param __rhs Last string.
5967 * @return New string with @a __lhs followed by @a __rhs.
5968 */
5969 template<typename _CharT, typename _Traits, typename _Alloc>
5970 inline basic_string<_CharT, _Traits, _Alloc>
5971 operator+(const basic_string<_CharT, _Traits, _Alloc>& __lhs, _CharT __rhs)
5972 {
5973 typedef basic_string<_CharT, _Traits, _Alloc> __string_type;
5974 typedef typename __string_type::size_type __size_type;
5975 __string_type __str(__lhs);
5976 __str.append(__size_type(1), __rhs);
5977 return __str;
5978 }
5979
5980#if __cplusplus >= 201103L
5981 template<typename _CharT, typename _Traits, typename _Alloc>
5982 inline basic_string<_CharT, _Traits, _Alloc>
5983 operator+(basic_string<_CharT, _Traits, _Alloc>&& __lhs,
5984 const basic_string<_CharT, _Traits, _Alloc>& __rhs)
5985 { return std::move(__lhs.append(__rhs)); }
5986
5987 template<typename _CharT, typename _Traits, typename _Alloc>
5988 inline basic_string<_CharT, _Traits, _Alloc>
5989 operator+(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
5990 basic_string<_CharT, _Traits, _Alloc>&& __rhs)
5991 { return std::move(__rhs.insert(0, __lhs)); }
5992
5993 template<typename _CharT, typename _Traits, typename _Alloc>
5994 inline basic_string<_CharT, _Traits, _Alloc>
5995 operator+(basic_string<_CharT, _Traits, _Alloc>&& __lhs,
5996 basic_string<_CharT, _Traits, _Alloc>&& __rhs)
5997 {
5998 const auto __size = __lhs.size() + __rhs.size();
5999 const bool __cond = (__size > __lhs.capacity()
6000 && __size <= __rhs.capacity());
6001 return __cond ? std::move(__rhs.insert(0, __lhs))
6002 : std::move(__lhs.append(__rhs));
6003 }
6004
6005 template<typename _CharT, typename _Traits, typename _Alloc>
6006 inline basic_string<_CharT, _Traits, _Alloc>
6007 operator+(const _CharT* __lhs,
6008 basic_string<_CharT, _Traits, _Alloc>&& __rhs)
6009 { return std::move(__rhs.insert(0, __lhs)); }
6010
6011 template<typename _CharT, typename _Traits, typename _Alloc>
6012 inline basic_string<_CharT, _Traits, _Alloc>
6013 operator+(_CharT __lhs,
6014 basic_string<_CharT, _Traits, _Alloc>&& __rhs)
6015 { return std::move(__rhs.insert(0, 1, __lhs)); }
6016
6017 template<typename _CharT, typename _Traits, typename _Alloc>
6018 inline basic_string<_CharT, _Traits, _Alloc>
6019 operator+(basic_string<_CharT, _Traits, _Alloc>&& __lhs,
6020 const _CharT* __rhs)
6021 { return std::move(__lhs.append(__rhs)); }
6022
6023 template<typename _CharT, typename _Traits, typename _Alloc>
6024 inline basic_string<_CharT, _Traits, _Alloc>
6025 operator+(basic_string<_CharT, _Traits, _Alloc>&& __lhs,
6026 _CharT __rhs)
6027 { return std::move(__lhs.append(1, __rhs)); }
6028#endif
6029
6030 // operator ==
6031 /**
6032 * @brief Test equivalence of two strings.
6033 * @param __lhs First string.
6034 * @param __rhs Second string.
6035 * @return True if @a __lhs.compare(@a __rhs) == 0. False otherwise.
6036 */
6037 template<typename _CharT, typename _Traits, typename _Alloc>
6038 inline bool
6039 operator==(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
6040 const basic_string<_CharT, _Traits, _Alloc>& __rhs)
6041 _GLIBCXX_NOEXCEPT
6042 { return __lhs.compare(__rhs) == 0; }
6043
6044 template<typename _CharT>
6045 inline
6046 typename __gnu_cxx::__enable_if<__is_char<_CharT>::__value, bool>::__type
6047 operator==(const basic_string<_CharT>& __lhs,
6048 const basic_string<_CharT>& __rhs) _GLIBCXX_NOEXCEPT
6049 { return (__lhs.size() == __rhs.size()
6050 && !std::char_traits<_CharT>::compare(__lhs.data(), __rhs.data(),
6051 __lhs.size())); }
6052
6053 /**
6054 * @brief Test equivalence of C string and string.
6055 * @param __lhs C string.
6056 * @param __rhs String.
6057 * @return True if @a __rhs.compare(@a __lhs) == 0. False otherwise.
6058 */
6059 template<typename _CharT, typename _Traits, typename _Alloc>
6060 inline bool
6061 operator==(const _CharT* __lhs,
6062 const basic_string<_CharT, _Traits, _Alloc>& __rhs)
6063 { return __rhs.compare(__lhs) == 0; }
6064
6065 /**
6066 * @brief Test equivalence of string and C string.
6067 * @param __lhs String.
6068 * @param __rhs C string.
6069 * @return True if @a __lhs.compare(@a __rhs) == 0. False otherwise.
6070 */
6071 template<typename _CharT, typename _Traits, typename _Alloc>
6072 inline bool
6073 operator==(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
6074 const _CharT* __rhs)
6075 { return __lhs.compare(__rhs) == 0; }
6076
6077 // operator !=
6078 /**
6079 * @brief Test difference of two strings.
6080 * @param __lhs First string.
6081 * @param __rhs Second string.
6082 * @return True if @a __lhs.compare(@a __rhs) != 0. False otherwise.
6083 */
6084 template<typename _CharT, typename _Traits, typename _Alloc>
6085 inline bool
6086 operator!=(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
6087 const basic_string<_CharT, _Traits, _Alloc>& __rhs)
6088 _GLIBCXX_NOEXCEPT
6089 { return !(__lhs == __rhs); }
6090
6091 /**
6092 * @brief Test difference of C string and string.
6093 * @param __lhs C string.
6094 * @param __rhs String.
6095 * @return True if @a __rhs.compare(@a __lhs) != 0. False otherwise.
6096 */
6097 template<typename _CharT, typename _Traits, typename _Alloc>
6098 inline bool
6099 operator!=(const _CharT* __lhs,
6100 const basic_string<_CharT, _Traits, _Alloc>& __rhs)
6101 { return !(__lhs == __rhs); }
6102
6103 /**
6104 * @brief Test difference of string and C string.
6105 * @param __lhs String.
6106 * @param __rhs C string.
6107 * @return True if @a __lhs.compare(@a __rhs) != 0. False otherwise.
6108 */
6109 template<typename _CharT, typename _Traits, typename _Alloc>
6110 inline bool
6111 operator!=(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
6112 const _CharT* __rhs)
6113 { return !(__lhs == __rhs); }
6114
6115 // operator <
6116 /**
6117 * @brief Test if string precedes string.
6118 * @param __lhs First string.
6119 * @param __rhs Second string.
6120 * @return True if @a __lhs precedes @a __rhs. False otherwise.
6121 */
6122 template<typename _CharT, typename _Traits, typename _Alloc>
6123 inline bool
6124 operator<(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
6125 const basic_string<_CharT, _Traits, _Alloc>& __rhs)
6126 _GLIBCXX_NOEXCEPT
6127 { return __lhs.compare(__rhs) < 0; }
6128
6129 /**
6130 * @brief Test if string precedes C string.
6131 * @param __lhs String.
6132 * @param __rhs C string.
6133 * @return True if @a __lhs precedes @a __rhs. False otherwise.
6134 */
6135 template<typename _CharT, typename _Traits, typename _Alloc>
6136 inline bool
6137 operator<(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
6138 const _CharT* __rhs)
6139 { return __lhs.compare(__rhs) < 0; }
6140
6141 /**
6142 * @brief Test if C string precedes string.
6143 * @param __lhs C string.
6144 * @param __rhs String.
6145 * @return True if @a __lhs precedes @a __rhs. False otherwise.
6146 */
6147 template<typename _CharT, typename _Traits, typename _Alloc>
6148 inline bool
6149 operator<(const _CharT* __lhs,
6150 const basic_string<_CharT, _Traits, _Alloc>& __rhs)
6151 { return __rhs.compare(__lhs) > 0; }
6152
6153 // operator >
6154 /**
6155 * @brief Test if string follows string.
6156 * @param __lhs First string.
6157 * @param __rhs Second string.
6158 * @return True if @a __lhs follows @a __rhs. False otherwise.
6159 */
6160 template<typename _CharT, typename _Traits, typename _Alloc>
6161 inline bool
6162 operator>(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
6163 const basic_string<_CharT, _Traits, _Alloc>& __rhs)
6164 _GLIBCXX_NOEXCEPT
6165 { return __lhs.compare(__rhs) > 0; }
6166
6167 /**
6168 * @brief Test if string follows C string.
6169 * @param __lhs String.
6170 * @param __rhs C string.
6171 * @return True if @a __lhs follows @a __rhs. False otherwise.
6172 */
6173 template<typename _CharT, typename _Traits, typename _Alloc>
6174 inline bool
6175 operator>(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
6176 const _CharT* __rhs)
6177 { return __lhs.compare(__rhs) > 0; }
6178
6179 /**
6180 * @brief Test if C string follows string.
6181 * @param __lhs C string.
6182 * @param __rhs String.
6183 * @return True if @a __lhs follows @a __rhs. False otherwise.
6184 */
6185 template<typename _CharT, typename _Traits, typename _Alloc>
6186 inline bool
6187 operator>(const _CharT* __lhs,
6188 const basic_string<_CharT, _Traits, _Alloc>& __rhs)
6189 { return __rhs.compare(__lhs) < 0; }
6190
6191 // operator <=
6192 /**
6193 * @brief Test if string doesn't follow string.
6194 * @param __lhs First string.
6195 * @param __rhs Second string.
6196 * @return True if @a __lhs doesn't follow @a __rhs. False otherwise.
6197 */
6198 template<typename _CharT, typename _Traits, typename _Alloc>
6199 inline bool
6200 operator<=(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
6201 const basic_string<_CharT, _Traits, _Alloc>& __rhs)
6202 _GLIBCXX_NOEXCEPT
6203 { return __lhs.compare(__rhs) <= 0; }
6204
6205 /**
6206 * @brief Test if string doesn't follow C string.
6207 * @param __lhs String.
6208 * @param __rhs C string.
6209 * @return True if @a __lhs doesn't follow @a __rhs. False otherwise.
6210 */
6211 template<typename _CharT, typename _Traits, typename _Alloc>
6212 inline bool
6213 operator<=(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
6214 const _CharT* __rhs)
6215 { return __lhs.compare(__rhs) <= 0; }
6216
6217 /**
6218 * @brief Test if C string doesn't follow string.
6219 * @param __lhs C string.
6220 * @param __rhs String.
6221 * @return True if @a __lhs doesn't follow @a __rhs. False otherwise.
6222 */
6223 template<typename _CharT, typename _Traits, typename _Alloc>
6224 inline bool
6225 operator<=(const _CharT* __lhs,
6226 const basic_string<_CharT, _Traits, _Alloc>& __rhs)
6227 { return __rhs.compare(__lhs) >= 0; }
6228
6229 // operator >=
6230 /**
6231 * @brief Test if string doesn't precede string.
6232 * @param __lhs First string.
6233 * @param __rhs Second string.
6234 * @return True if @a __lhs doesn't precede @a __rhs. False otherwise.
6235 */
6236 template<typename _CharT, typename _Traits, typename _Alloc>
6237 inline bool
6238 operator>=(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
6239 const basic_string<_CharT, _Traits, _Alloc>& __rhs)
6240 _GLIBCXX_NOEXCEPT
6241 { return __lhs.compare(__rhs) >= 0; }
6242
6243 /**
6244 * @brief Test if string doesn't precede C string.
6245 * @param __lhs String.
6246 * @param __rhs C string.
6247 * @return True if @a __lhs doesn't precede @a __rhs. False otherwise.
6248 */
6249 template<typename _CharT, typename _Traits, typename _Alloc>
6250 inline bool
6251 operator>=(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
6252 const _CharT* __rhs)
6253 { return __lhs.compare(__rhs) >= 0; }
6254
6255 /**
6256 * @brief Test if C string doesn't precede string.
6257 * @param __lhs C string.
6258 * @param __rhs String.
6259 * @return True if @a __lhs doesn't precede @a __rhs. False otherwise.
6260 */
6261 template<typename _CharT, typename _Traits, typename _Alloc>
6262 inline bool
6263 operator>=(const _CharT* __lhs,
6264 const basic_string<_CharT, _Traits, _Alloc>& __rhs)
6265 { return __rhs.compare(__lhs) <= 0; }
6266
6267 /**
6268 * @brief Swap contents of two strings.
6269 * @param __lhs First string.
6270 * @param __rhs Second string.
6271 *
6272 * Exchanges the contents of @a __lhs and @a __rhs in constant time.
6273 */
6274 template<typename _CharT, typename _Traits, typename _Alloc>
6275 inline void
6276 swap(basic_string<_CharT, _Traits, _Alloc>& __lhs,
6277 basic_string<_CharT, _Traits, _Alloc>& __rhs)
6278 _GLIBCXX_NOEXCEPT_IF(noexcept(__lhs.swap(__rhs)))
6279 { __lhs.swap(__rhs); }
6280
6281
6282 /**
6283 * @brief Read stream into a string.
6284 * @param __is Input stream.
6285 * @param __str Buffer to store into.
6286 * @return Reference to the input stream.
6287 *
6288 * Stores characters from @a __is into @a __str until whitespace is
6289 * found, the end of the stream is encountered, or str.max_size()
6290 * is reached. If is.width() is non-zero, that is the limit on the
6291 * number of characters stored into @a __str. Any previous
6292 * contents of @a __str are erased.
6293 */
6294 template<typename _CharT, typename _Traits, typename _Alloc>
6295 basic_istream<_CharT, _Traits>&
6296 operator>>(basic_istream<_CharT, _Traits>& __is,
6297 basic_st