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

source code of include/c++/11/bits/basic_string.h