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