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