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