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
_GLIBCXX_VISIBILITY(default)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
59 // Support P0426R1 changes to char_traits in C++17.
60 # define __cpp_lib_constexpr_string 201611L
61 #elif __cplusplus > 201703L
62 #endif
63
64 #if _GLIBCXX_USE_CXX11_ABI
65 _GLIBCXX_BEGIN_NAMESPACE_CXX11
66 /**
67 * @class basic_string basic_string.h <string>
68 * @brief Managing sequences of characters and character-like objects.
69 *
70 * @ingroup strings
71 * @ingroup sequences
72 *
73 * @tparam _CharT Type of character
74 * @tparam _Traits Traits for character type, defaults to
75 * char_traits<_CharT>.
76 * @tparam _Alloc Allocator type, defaults to allocator<_CharT>.
77 *
78 * Meets the requirements of a <a href="tables.html#65">container</a>, a
79 * <a href="tables.html#66">reversible container</a>, and a
80 * <a href="tables.html#67">sequence</a>. Of the
81 * <a href="tables.html#68">optional sequence requirements</a>, only
82 * @c push_back, @c at, and @c %array access are supported.
83 */
84 template<typename _CharT, typename _Traits, typename _Alloc>
85 class basic_string
86 {
87 typedef typename __gnu_cxx::__alloc_traits<_Alloc>::template
88 rebind<_CharT>::other _Char_alloc_type;
89 typedef __gnu_cxx::__alloc_traits<_Char_alloc_type> _Alloc_traits;
90
91 // Types:
92 public:
93 typedef _Traits traits_type;
94 typedef typename _Traits::char_type value_type;
95 typedef _Char_alloc_type allocator_type;
96 typedef typename _Alloc_traits::size_type size_type;
97 typedef typename _Alloc_traits::difference_type difference_type;
98 typedef typename _Alloc_traits::reference reference;
99 typedef typename _Alloc_traits::const_reference const_reference;
100 typedef typename _Alloc_traits::pointer pointer;
101 typedef typename _Alloc_traits::const_pointer const_pointer;
102 typedef __gnu_cxx::__normal_iterator<pointer, basic_string> iterator;
103 typedef __gnu_cxx::__normal_iterator<const_pointer, basic_string>
104 const_iterator;
105 typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
106 typedef std::reverse_iterator<iterator> reverse_iterator;
107
108 /// Value returned by various member functions when they fail.
109 static const size_type npos = static_cast<size_type>(-1);
110
111 protected:
112 // type used for positions in insert, erase etc.
113 #if __cplusplus < 201103L
114 typedef iterator __const_iterator;
115 #else
116 typedef const_iterator __const_iterator;
117 #endif
118
119 private:
120 #if __cplusplus >= 201703L
121 // A helper type for avoiding boiler-plate.
122 typedef basic_string_view<_CharT, _Traits> __sv_type;
123
124 template<typename _Tp, typename _Res>
125 using _If_sv = enable_if_t<
126 __and_<is_convertible<const _Tp&, __sv_type>,
127 __not_<is_convertible<const _Tp*, const basic_string*>>,
128 __not_<is_convertible<const _Tp&, const _CharT*>>>::value,
129 _Res>;
130
131 // Allows an implicit conversion to __sv_type.
132 static __sv_type
133 _S_to_string_view(__sv_type __svt) noexcept
134 { return __svt; }
135
136 // Wraps a string_view by explicit conversion and thus
137 // allows to add an internal constructor that does not
138 // participate in overload resolution when a string_view
139 // is provided.
140 struct __sv_wrapper
141 {
142 explicit __sv_wrapper(__sv_type __sv) noexcept : _M_sv(__sv) { }
143 __sv_type _M_sv;
144 };
145
146 /**
147 * @brief Only internally used: Construct string from a string view
148 * wrapper.
149 * @param __svw string view wrapper.
150 * @param __a Allocator to use.
151 */
152 explicit
153 basic_string(__sv_wrapper __svw, const _Alloc& __a)
154 : basic_string(__svw._M_sv.data(), __svw._M_sv.size(), __a) { }
155 #endif
156
157 // Use empty-base optimization: http://www.cantrip.org/emptyopt.html
158 struct _Alloc_hider : allocator_type // TODO check __is_final
159 {
160 #if __cplusplus < 201103L
161 _Alloc_hider(pointer __dat, const _Alloc& __a = _Alloc())
162 : allocator_type(__a), _M_p(__dat) { }
163 #else
164 _Alloc_hider(pointer __dat, const _Alloc& __a)
165 : allocator_type(__a), _M_p(__dat) { }
166
167 _Alloc_hider(pointer __dat, _Alloc&& __a = _Alloc())
168 : allocator_type(std::move(__a)), _M_p(__dat) { }
169 #endif
170
171 pointer _M_p; // The actual data.
172 };
173
174 _Alloc_hider _M_dataplus;
175 size_type _M_string_length;
176
177 enum { _S_local_capacity = 15 / sizeof(_CharT) };
178
179 union
180 {
181 _CharT _M_local_buf[_S_local_capacity + 1];
182 size_type _M_allocated_capacity;
183 };
184
185 void
186 _M_data(pointer __p)
187 { _M_dataplus._M_p = __p; }
188
189 void
190 _M_length(size_type __length)
191 { _M_string_length = __length; }
192
193 pointer
194 _M_data() const
195 { return _M_dataplus._M_p; }
196
197 pointer
198 _M_local_data()
199 {
200 #if __cplusplus >= 201103L
201 return std::pointer_traits<pointer>::pointer_to(*_M_local_buf);
202 #else
203 return pointer(_M_local_buf);
204 #endif
205 }
206
207 const_pointer
208 _M_local_data() const
209 {
210 #if __cplusplus >= 201103L
211 return std::pointer_traits<const_pointer>::pointer_to(*_M_local_buf);
212 #else
213 return const_pointer(_M_local_buf);
214 #endif
215 }
216
217 void
218 _M_capacity(size_type __capacity)
219 { _M_allocated_capacity = __capacity; }
220
221 void
222 _M_set_length(size_type __n)
223 {
224 _M_length(__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,
281 std::input_iterator_tag);
282
283 // For forward_iterators up to random_access_iterators, used for
284 // string::iterator, _CharT*, etc.
285 template<typename _FwdIterator>
286 void
287 _M_construct(_FwdIterator __beg, _FwdIterator __end,
288 std::forward_iterator_tag);
289
290 void
291 _M_construct(size_type __req, _CharT __c);
292
293 allocator_type&
294 _M_get_allocator()
295 { return _M_dataplus; }
296
297 const allocator_type&
298 _M_get_allocator() const
299 { return _M_dataplus; }
300
301 private:
302
303 #ifdef _GLIBCXX_DISAMBIGUATE_REPLACE_INST
304 // The explicit instantiations in misc-inst.cc require this due to
305 // https://gcc.gnu.org/bugzilla/show_bug.cgi?id=64063
306 template<typename _Tp, bool _Requires =
307 !__are_same<_Tp, _CharT*>::__value
308 && !__are_same<_Tp, const _CharT*>::__value
309 && !__are_same<_Tp, iterator>::__value
310 && !__are_same<_Tp, const_iterator>::__value>
311 struct __enable_if_not_native_iterator
312 { typedef basic_string& __type; };
313 template<typename _Tp>
314 struct __enable_if_not_native_iterator<_Tp, false> { };
315 #endif
316
317 size_type
318 _M_check(size_type __pos, const char* __s) const
319 {
320 if (__pos > this->size())
321 __throw_out_of_range_fmt(__N("%s: __pos (which is %zu) > "
322 "this->size() (which is %zu)"),
323 __s, __pos, this->size());
324 return __pos;
325 }
326
327 void
328 _M_check_length(size_type __n1, size_type __n2, const char* __s) const
329 {
330 if (this->max_size() - (this->size() - __n1) < __n2)
331 __throw_length_error(__N(__s));
332 }
333
334
335 // NB: _M_limit doesn't check for a bad __pos value.
336 size_type
337 _M_limit(size_type __pos, size_type __off) const _GLIBCXX_NOEXCEPT
338 {
339 const bool __testoff = __off < this->size() - __pos;
340 return __testoff ? __off : this->size() - __pos;
341 }
342
343 // True if _Rep and source do not overlap.
344 bool
345 _M_disjunct(const _CharT* __s) const _GLIBCXX_NOEXCEPT
346 {
347 return (less<const _CharT*>()(__s, _M_data())
348 || less<const _CharT*>()(_M_data() + this->size(), __s));
349 }
350
351 // When __n = 1 way faster than the general multichar
352 // traits_type::copy/move/assign.
353 static void
354 _S_copy(_CharT* __d, const _CharT* __s, size_type __n)
355 {
356 if (__n == 1)
357 traits_type::assign(*__d, *__s);
358 else
359 traits_type::copy(__d, __s, __n);
360 }
361
362 static void
363 _S_move(_CharT* __d, const _CharT* __s, size_type __n)
364 {
365 if (__n == 1)
366 traits_type::assign(*__d, *__s);
367 else
368 traits_type::move(__d, __s, __n);
369 }
370
371 static void
372 _S_assign(_CharT* __d, size_type __n, _CharT __c)
373 {
374 if (__n == 1)
375 traits_type::assign(*__d, __c);
376 else
377 traits_type::assign(__d, __n, __c);
378 }
379
380 // _S_copy_chars is a separate template to permit specialization
381 // to optimize for the common case of pointers as iterators.
382 template<class _Iterator>
383 static void
384 _S_copy_chars(_CharT* __p, _Iterator __k1, _Iterator __k2)
385 {
386 for (; __k1 != __k2; ++__k1, (void)++__p)
387 traits_type::assign(*__p, *__k1); // These types are off.
388 }
389
390 static void
391 _S_copy_chars(_CharT* __p, iterator __k1, iterator __k2) _GLIBCXX_NOEXCEPT
392 { _S_copy_chars(__p, __k1.base(), __k2.base()); }
393
394 static void
395 _S_copy_chars(_CharT* __p, const_iterator __k1, const_iterator __k2)
396 _GLIBCXX_NOEXCEPT
397 { _S_copy_chars(__p, __k1.base(), __k2.base()); }
398
399 static void
400 _S_copy_chars(_CharT* __p, _CharT* __k1, _CharT* __k2) _GLIBCXX_NOEXCEPT
401 { _S_copy(__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, '\\0'
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, '\\0' 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>
3173 class basic_string
3174 {
3175 typedef typename __gnu_cxx::__alloc_traits<_Alloc>::template
3176 rebind<_CharT>::other _CharT_alloc_type;
3177 typedef __gnu_cxx::__alloc_traits<_CharT_alloc_type> _CharT_alloc_traits;
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;
3198 typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
3199 typedef std::reverse_iterator<iterator> reverse_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:
3230 typedef typename __gnu_cxx::__alloc_traits<_Alloc>::template
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 */
3580 basic_string()
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 */
3602 basic_string(const basic_string& __str)
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, '\\0'
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 */
3684 basic_string(basic_string&& __str)
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&
3807 operator=(basic_string&& __str)
3808 _GLIBCXX_NOEXCEPT_IF(allocator_traits<_Alloc>::is_always_equal::value)
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&
3820 operator=(initializer_list<_CharT> __l)
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
4167 front()
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
4189 back()
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&
4245 operator+=(initializer_list<_CharT> __l)
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&
4324 append(initializer_list<_CharT> __l)
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&
4406 assign(basic_string&& __str)
4407 noexcept(allocator_traits<_Alloc>::is_always_equal::value)
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&
4495 assign(initializer_list<_CharT> __l)
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
4573 insert(iterator __p, initializer_list<_CharT> __l)
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,
5091 initializer_list<_CharT> __l)
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
5440 noexcept(is_same<_Tp, __sv_type>::value)
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
5608 noexcept(is_same<_Tp, __sv_type>::value)
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
5771 noexcept(is_same<_Tp, __sv_type>::value)
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
5831 noexcept(is_same<_Tp, __sv_type>::value)
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
5855 noexcept(is_same<_Tp, __sv_type>::value)
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
5875 noexcept(is_same<_Tp, __sv_type>::value)
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, '\\0' 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>
6094 operator+(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
6095 const basic_string<_CharT, _Traits, _Alloc>& __rhs)
6096 {
6097 basic_string<_CharT, _Traits, _Alloc> __str(__lhs);
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>
6131 operator+(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
6132 const _CharT* __rhs)
6133 {
6134 basic_string<_CharT, _Traits, _Alloc> __str(__lhs);
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>
6147 operator+(const basic_string<_CharT, _Traits, _Alloc>& __lhs, _CharT __rhs)
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,
6226 const basic_string<_CharT, _Traits, _Alloc>& __rhs)
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,
6289 const basic_string<_CharT, _Traits, _Alloc>& __rhs)
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,
6302 const basic_string<_CharT, _Traits, _Alloc>& __rhs)
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,
6315 const basic_string<_CharT, _Traits, _Alloc>& __rhs)
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,
6340 const basic_string<_CharT, _Traits, _Alloc>& __rhs)
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,
6365 const basic_string<_CharT, _Traits, _Alloc>& __rhs)
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
6377 operator>(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
6378 const basic_string<_CharT, _Traits, _Alloc>& __rhs)
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
6390 operator>(const basic_string<_CharT, _Traits, _Alloc>& __lhs,
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,
6403 const basic_string<_CharT, _Traits, _Alloc>& __rhs)
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,
6416 const basic_string<_CharT, _Traits, _Alloc>& __rhs)
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,
6441 const basic_string<_CharT, _Traits, _Alloc>& __rhs)
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,
6454 const basic_string<_CharT, _Traits, _Alloc>& __rhs)
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,
6479 const basic_string<_CharT, _Traits, _Alloc>& __rhs)
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
6492 swap(basic_string<_CharT, _Traits, _Alloc>& __lhs,
6493 basic_string<_CharT, _Traits, _Alloc>& __rhs)
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>&
6517 operator>>(basic_istream<char>& __is, basic_string<char>& __str);
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>
6529 inline basic_ostream<_CharT, _Traits>&
6530 operator<<(basic_ostream<_CharT, _Traits>& __os,
6531 const basic_string<_CharT, _Traits, _Alloc>& __str)
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 is extracted but not stored into
6549 * @a __str.
6550 */
6551 template<typename _CharT, typename _Traits, typename _Alloc>
6552 basic_istream<_CharT, _Traits>&
6553 getline(basic_istream<_CharT, _Traits>& __is,
6554 basic_string<_CharT, _Traits, _Alloc>& __str, _CharT __delim);
6555
6556 /**
6557 * @brief Read a line from stream into a string.
6558 * @param __is Input stream.
6559 * @param __str Buffer to store into.
6560 * @return Reference to the input stream.
6561 *
6562 * Stores characters from is into @a __str until '\n' is
6563 * found, the end of the stream is encountered, or str.max_size()
6564 * is reached. Any previous contents of @a __str are erased. If
6565 * end of line is encountered, it is extracted but not stored into
6566 * @a __str.
6567 */
6568 template<typename _CharT, typename _Traits, typename _Alloc>
6569 inline basic_istream<_CharT, _Traits>&
6570 getline(basic_istream<_CharT, _Traits>& __is,
6571 basic_string<_CharT, _Traits, _Alloc>& __str)
6572 { return std::getline(__is, __str, __is.widen('\n')); }
6573
6574 #if __cplusplus >= 201103L
6575 /// Read a line from an rvalue stream into a string.
6576 template<typename _CharT, typename _Traits, typename _Alloc>
6577 inline basic_istream<_CharT, _Traits>&
6578 getline(basic_istream<_CharT, _Traits>&& __is,
6579 basic_string<_CharT, _Traits, _Alloc>& __str, _CharT __delim)
6580 { return std::getline(__is, __str, __delim); }
6581
6582 /// Read a line from an rvalue stream into a string.
6583 template<typename _CharT, typename _Traits, typename _Alloc>
6584 inline basic_istream<_CharT, _Traits>&
6585 getline(basic_istream<_CharT, _Traits>&& __is,
6586 basic_string<_CharT, _Traits, _Alloc>& __str)
6587 { return std::getline(__is, __str); }
6588 #endif
6589
6590 template<>
6591 basic_istream<char>&
6592 getline(basic_istream<char>& __in, basic_string<char>& __str,
6593 char __delim);
6594
6595 #ifdef _GLIBCXX_USE_WCHAR_T
6596 template<>
6597 basic_istream<wchar_t>&
6598 getline(basic_istream<wchar_t>& __in, basic_string<wchar_t>& __str,
6599 wchar_t __delim);
6600 #endif
6601
6602 _GLIBCXX_END_NAMESPACE_VERSION
6603 } // namespace
6604
6605 #if __cplusplus >= 201103L
6606
6607 #include <ext/string_conversions.h>
6608 #include <bits/charconv.h>
6609
6610 namespace std _GLIBCXX_VISIBILITY(default)
6611 {
6612 _GLIBCXX_BEGIN_NAMESPACE_VERSION
6613 _GLIBCXX_BEGIN_NAMESPACE_CXX11
6614
6615 #if _GLIBCXX_USE_C99_STDLIB
6616 // 21.4 Numeric Conversions [string.conversions].
6617 inline int
6618 stoi(const string& __str, size_t* __idx = 0, int __base = 10)
6619 { return __gnu_cxx::__stoa<long, int>(&std::strtol, "stoi", __str.c_str(),
6620 __idx, __base); }
6621
6622 inline long
6623 stol(const string& __str, size_t* __idx = 0, int __base = 10)
6624 { return __gnu_cxx::__stoa(&std::strtol, "stol", __str.c_str(),
6625 __idx, __base); }
6626
6627 inline unsigned long
6628 stoul(const string& __str, size_t* __idx = 0, int __base = 10)
6629 { return __gnu_cxx::__stoa(&std::strtoul, "stoul", __str.c_str(),
6630 __idx, __base); }
6631
6632 inline long long
6633 stoll(const string& __str, size_t* __idx = 0, int __base = 10)
6634 { return __gnu_cxx::__stoa(&std::strtoll, "stoll", __str.c_str(),
6635 __idx, __base); }
6636
6637 inline unsigned long long
6638 stoull(const string& __str, size_t* __idx = 0, int __base = 10)
6639 { return __gnu_cxx::__stoa(&std::strtoull, "stoull", __str.c_str(),
6640 __idx, __base); }
6641
6642 // NB: strtof vs strtod.
6643 inline float
6644 stof(const string& __str, size_t* __idx = 0)
6645 { return __gnu_cxx::__stoa(&std::strtof, "stof", __str.c_str(), __idx); }
6646
6647 inline double
6648 stod(const string& __str, size_t* __idx = 0)
6649 { return __gnu_cxx::__stoa(&std::strtod, "stod", __str.c_str(), __idx); }
6650
6651 inline long double
6652 stold(const string& __str, size_t* __idx = 0)
6653 { return __gnu_cxx::__stoa(&std::strtold, "stold", __str.c_str(), __idx); }
6654 #endif // _GLIBCXX_USE_C99_STDLIB
6655
6656 // DR 1261. Insufficent overloads for to_string / to_wstring
6657
6658 inline string
6659 to_string(int __val)
6660 {
6661 const bool __neg = __val < 0;
6662 const unsigned __uval = __neg ? (unsigned)~__val + 1u : __val;
6663 const auto __len = __detail::__to_chars_len(__uval);
6664 string __str(__neg + __len, '-');
6665 __detail::__to_chars_10_impl(&__str[__neg], __len, __uval);
6666 return __str;
6667 }
6668
6669 inline string
6670 to_string(unsigned __val)
6671 {
6672 string __str(__detail::__to_chars_len(__val), '\0');
6673 __detail::__to_chars_10_impl(&__str[0], __str.size(), __val);
6674 return __str;
6675 }
6676
6677 inline string
6678 to_string(long __val)
6679 {
6680 const bool __neg = __val < 0;
6681 const unsigned long __uval = __neg ? (unsigned long)~__val + 1ul : __val;
6682 const auto __len = __detail::__to_chars_len(__uval);
6683 string __str(__neg + __len, '-');
6684 __detail::__to_chars_10_impl(&__str[__neg], __len, __uval);
6685 return __str;
6686 }
6687
6688 inline string
6689 to_string(unsigned long __val)
6690 {
6691 string __str(__detail::__to_chars_len(__val), '\0');
6692 __detail::__to_chars_10_impl(&__str[0], __str.size(), __val);
6693 return __str;
6694 }
6695
6696 inline string
6697 to_string(long long __val)
6698 {
6699 const bool __neg = __val < 0;
6700 const unsigned long long __uval
6701 = __neg ? (unsigned long long)~__val + 1ull : __val;
6702 const auto __len = __detail::__to_chars_len(__uval);
6703 string __str(__neg + __len, '-');
6704 __detail::__to_chars_10_impl(&__str[__neg], __len, __uval);
6705 return __str;
6706 }
6707
6708 inline string
6709 to_string(unsigned long long __val)
6710 {
6711 string __str(__detail::__to_chars_len(__val), '\0');
6712 __detail::__to_chars_10_impl(&__str[0], __str.size(), __val);
6713 return __str;
6714 }
6715
6716 #if _GLIBCXX_USE_C99_STDIO
6717 // NB: (v)snprintf vs sprintf.
6718
6719 inline string
6720 to_string(float __val)
6721 {
6722 const int __n =
6723 __gnu_cxx::__numeric_traits<float>::__max_exponent10 + 20;
6724 return __gnu_cxx::__to_xstring<string>(&std::vsnprintf, __n,
6725 "%f", __val);
6726 }
6727
6728 inline string
6729 to_string(double __val)
6730 {
6731 const int __n =
6732 __gnu_cxx::__numeric_traits<double>::__max_exponent10 + 20;
6733 return __gnu_cxx::__to_xstring<string>(&std::vsnprintf, __n,
6734 "%f", __val);
6735 }
6736
6737 inline string
6738 to_string(long double __val)
6739 {
6740 const int __n =
6741 __gnu_cxx::__numeric_traits<long double>::__max_exponent10 + 20;
6742 return __gnu_cxx::__to_xstring<string>(&std::vsnprintf, __n,
6743 "%Lf", __val);
6744 }
6745 #endif // _GLIBCXX_USE_C99_STDIO
6746
6747 #if defined(_GLIBCXX_USE_WCHAR_T) && _GLIBCXX_USE_C99_WCHAR
6748 inline int
6749 stoi(const wstring& __str, size_t* __idx = 0, int __base = 10)
6750 { return __gnu_cxx::__stoa<long, int>(&std::wcstol, "stoi", __str.c_str(),
6751 __idx, __base); }
6752
6753 inline long
6754 stol(const wstring& __str, size_t* __idx = 0, int __base = 10)
6755 { return __gnu_cxx::__stoa(&std::wcstol, "stol", __str.c_str(),
6756 __idx, __base); }
6757
6758 inline unsigned long
6759 stoul(const wstring& __str, size_t* __idx = 0, int __base = 10)
6760 { return __gnu_cxx::__stoa(&std::wcstoul, "stoul", __str.c_str(),
6761 __idx, __base); }
6762
6763 inline long long
6764 stoll(const wstring& __str, size_t* __idx = 0, int __base = 10)
6765 { return __gnu_cxx::__stoa(&std::wcstoll, "stoll", __str.c_str(),
6766 __idx, __base); }
6767
6768 inline unsigned long long
6769 stoull(const wstring& __str, size_t* __idx = 0, int __base = 10)
6770 { return __gnu_cxx::__stoa(&std::wcstoull, "stoull", __str.c_str(),
6771 __idx, __base); }
6772
6773 // NB: wcstof vs wcstod.
6774 inline float
6775 stof(const wstring& __str, size_t* __idx = 0)
6776 { return __gnu_cxx::__stoa(&std::wcstof, "stof", __str.c_str(), __idx); }
6777
6778 inline double
6779 stod(const wstring& __str, size_t* __idx = 0)
6780 { return __gnu_cxx::__stoa(&std::wcstod, "stod", __str.c_str(), __idx); }
6781
6782 inline long double
6783 stold(const wstring& __str, size_t* __idx = 0)
6784 { return __gnu_cxx::__stoa(&std::wcstold, "stold", __str.c_str(), __idx); }
6785
6786 #ifndef _GLIBCXX_HAVE_BROKEN_VSWPRINTF
6787 // DR 1261.
6788 inline wstring
6789 to_wstring(int __val)
6790 { return __gnu_cxx::__to_xstring<wstring>(&std::vswprintf, 4 * sizeof(int),
6791 L"%d", __val); }
6792
6793 inline wstring
6794 to_wstring(unsigned __val)
6795 { return __gnu_cxx::__to_xstring<wstring>(&std::vswprintf,
6796 4 * sizeof(unsigned),
6797 L"%u", __val); }
6798
6799 inline wstring
6800 to_wstring(long __val)
6801 { return __gnu_cxx::__to_xstring<wstring>(&std::vswprintf, 4 * sizeof(long),
6802 L"%ld", __val); }
6803
6804 inline wstring
6805 to_wstring(unsigned long __val)
6806 { return __gnu_cxx::__to_xstring<wstring>(&std::vswprintf,
6807 4 * sizeof(unsigned long),
6808 L"%lu", __val); }
6809
6810 inline wstring
6811 to_wstring(long long __val)
6812 { return __gnu_cxx::__to_xstring<wstring>(&std::vswprintf,
6813 4 * sizeof(long long),
6814 L"%lld", __val); }
6815
6816 inline wstring
6817 to_wstring(unsigned long long __val)
6818 { return __gnu_cxx::__to_xstring<wstring>(&std::vswprintf,
6819 4 * sizeof(unsigned long long),
6820 L"%llu", __val); }
6821
6822 inline wstring
6823 to_wstring(float __val)
6824 {
6825 const int __n =
6826 __gnu_cxx::__numeric_traits<float>::__max_exponent10 + 20;
6827 return __gnu_cxx::__to_xstring<wstring>(&std::vswprintf, __n,
6828 L"%f", __val);
6829 }
6830
6831 inline wstring
6832 to_wstring(double __val)
6833 {
6834 const int __n =
6835 __gnu_cxx::__numeric_traits<double>::__max_exponent10 + 20;
6836 return __gnu_cxx::__to_xstring<wstring>(&std::vswprintf, __n,
6837 L"%f", __val);
6838 }
6839
6840 inline wstring
6841 to_wstring(long double __val)
6842 {
6843 const int __n =
6844 __gnu_cxx::__numeric_traits<long double>::__max_exponent10 + 20;
6845 return __gnu_cxx::__to_xstring<wstring>(&std::vswprintf, __n,
6846 L"%Lf", __val);
6847 }
6848 #endif // _GLIBCXX_HAVE_BROKEN_VSWPRINTF
6849 #endif // _GLIBCXX_USE_WCHAR_T && _GLIBCXX_USE_C99_WCHAR
6850
6851 _GLIBCXX_END_NAMESPACE_CXX11
6852 _GLIBCXX_END_NAMESPACE_VERSION
6853 } // namespace
6854
6855 #endif /* C++11 */
6856
6857 #if __cplusplus >= 201103L
6858
6859 #include <bits/functional_hash.h>
6860
6861 namespace std _GLIBCXX_VISIBILITY(default)
6862 {
6863 _GLIBCXX_BEGIN_NAMESPACE_VERSION
6864
6865 // DR 1182.
6866
6867 #ifndef _GLIBCXX_COMPATIBILITY_CXX0X
6868 /// std::hash specialization for string.
6869 template<>
6870 struct hash<string>
6871 : public __hash_base<size_t, string>
6872 {
6873 size_t
6874 operator()(const string& __s) const noexcept
6875 { return std::_Hash_impl::hash(__s.data(), __s.length()); }
6876 };
6877
6878 template<>
6879 struct __is_fast_hash<hash<string>> : std::false_type
6880 { };
6881
6882 #ifdef _GLIBCXX_USE_WCHAR_T
6883 /// std::hash specialization for wstring.
6884 template<>
6885 struct hash<wstring>
6886 : public __hash_base<size_t, wstring>
6887 {
6888 size_t
6889 operator()(const wstring& __s) const noexcept
6890 { return std::_Hash_impl::hash(__s.data(),
6891 __s.length() * sizeof(wchar_t)); }
6892 };
6893
6894 template<>
6895 struct __is_fast_hash<hash<wstring>> : std::false_type
6896 { };
6897 #endif
6898 #endif /* _GLIBCXX_COMPATIBILITY_CXX0X */
6899
6900 #ifdef _GLIBCXX_USE_CHAR8_T
6901 /// std::hash specialization for u8string.
6902 template<>
6903 struct hash<u8string>
6904 : public __hash_base<size_t, u8string>
6905 {
6906 size_t
6907 operator()(const u8string& __s) const noexcept
6908 { return std::_Hash_impl::hash(__s.data(),
6909 __s.length() * sizeof(char8_t)); }
6910 };
6911
6912 template<>
6913 struct __is_fast_hash<hash<u8string>> : std::false_type
6914 { };
6915 #endif
6916
6917 /// std::hash specialization for u16string.
6918 template<>
6919 struct hash<u16string>
6920 : public __hash_base<size_t, u16string>
6921 {
6922 size_t
6923 operator()(const u16string& __s) const noexcept
6924 { return std::_Hash_impl::hash(__s.data(),
6925 __s.length() * sizeof(char16_t)); }
6926 };
6927
6928 template<>
6929 struct __is_fast_hash<hash<u16string>> : std::false_type
6930 { };
6931
6932 /// std::hash specialization for u32string.
6933 template<>
6934 struct hash<u32string>
6935 : public __hash_base<size_t, u32string>
6936 {
6937 size_t
6938 operator()(const u32string& __s) const noexcept
6939 { return std::_Hash_impl::hash(__s.data(),
6940 __s.length() * sizeof(char32_t)); }
6941 };
6942
6943 template<>
6944 struct __is_fast_hash<hash<u32string>> : std::false_type
6945 { };
6946
6947 #if __cplusplus >= 201402L
6948
6949 #define __cpp_lib_string_udls 201304
6950
6951 inline namespace literals
6952 {
6953 inline namespace string_literals
6954 {
6955 #pragma GCC diagnostic push
6956 #pragma GCC diagnostic ignored "-Wliteral-suffix"
6957 _GLIBCXX_DEFAULT_ABI_TAG
6958 inline basic_string<char>
6959 operator""s(const char* __str, size_t __len)
6960 { return basic_string<char>{__str, __len}; }
6961
6962 #ifdef _GLIBCXX_USE_WCHAR_T
6963 _GLIBCXX_DEFAULT_ABI_TAG
6964 inline basic_string<wchar_t>
6965 operator""s(const wchar_t* __str, size_t __len)
6966 { return basic_string<wchar_t>{__str, __len}; }
6967 #endif
6968
6969 #ifdef _GLIBCXX_USE_CHAR8_T
6970 _GLIBCXX_DEFAULT_ABI_TAG
6971 inline basic_string<char8_t>
6972 operator""s(const char8_t* __str, size_t __len)
6973 { return basic_string<char8_t>{__str, __len}; }
6974 #endif
6975
6976 _GLIBCXX_DEFAULT_ABI_TAG
6977 inline basic_string<char16_t>
6978 operator""s(const char16_t* __str, size_t __len)
6979 { return basic_string<char16_t>{__str, __len}; }
6980
6981 _GLIBCXX_DEFAULT_ABI_TAG
6982 inline basic_string<char32_t>
6983 operator""s(const char32_t* __str, size_t __len)
6984 { return basic_string<char32_t>{__str, __len}; }
6985
6986 #pragma GCC diagnostic pop
6987 } // inline namespace string_literals
6988 } // inline namespace literals
6989
6990 #if __cplusplus >= 201703L
6991 namespace __detail::__variant
6992 {
6993 template<typename> struct _Never_valueless_alt; // see <variant>
6994
6995 // Provide the strong exception-safety guarantee when emplacing a
6996 // basic_string into a variant, but only if moving the string cannot throw.
6997 template<typename _Tp, typename _Traits, typename _Alloc>
6998 struct _Never_valueless_alt<std::basic_string<_Tp, _Traits, _Alloc>>
6999 : __and_<
7000 is_nothrow_move_constructible<std::basic_string<_Tp, _Traits, _Alloc>>,
7001 is_nothrow_move_assignable<std::basic_string<_Tp, _Traits, _Alloc>>
7002 >::type
7003 { };
7004 } // namespace __detail::__variant
7005 #endif // C++17
7006 #endif // C++14
7007
7008 _GLIBCXX_END_NAMESPACE_VERSION
7009 } // namespace std
7010
7011 #endif // C++11
7012
7013 #endif /* _BASIC_STRING_H */
7014