From Jason Turner

[strings]

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpzd7jj6sx/{from.md → to.md} +263 -500
tmp/tmpzd7jj6sx/{from.md → to.md} RENAMED
@@ -1,13 +1,15 @@
1
  # Strings library <a id="strings">[[strings]]</a>
2
 
3
  ## General <a id="strings.general">[[strings.general]]</a>
4
 
5
  This Clause describes components for manipulating sequences of any
6
- non-array trivial standard-layout [[term.standard.layout.type]] type.
7
- Such types are called *char-like types*, and objects of char-like types
8
- are called *char-like objects* or simply *characters*.
 
 
9
 
10
  The following subclauses describe a character traits class, string
11
  classes, and null-terminated sequence utilities, as summarized in
12
  [[strings.summary]].
13
 
@@ -43,11 +45,11 @@ functions for the character container type `C`; `c` and `d` denote
43
  values of type `C`; `p` and `q` denote values of type `const C*`; `s`
44
  denotes a value of type `C*`; `n`, `i` and `j` denote values of type
45
  `size_t`; `e` and `f` denote values of type `X::int_type`; `pos` denotes
46
  a value of type `X::pos_type`; and `r` denotes an lvalue of type `C`. No
47
  expression which is part of the character traits requirements specified
48
- in this subclause [[char.traits.require]] shall exit via an exception.
49
 
50
  The class template
51
 
52
  ``` cpp
53
  template<class charT> struct char_traits;
@@ -312,37 +314,37 @@ own implicit conversions to `std::basic_string_view<charT>` in order to
312
  interoperate with these functions. — *end note*]
313
 
314
  ### Header `<string_view>` synopsis <a id="string.view.synop">[[string.view.synop]]</a>
315
 
316
  ``` cpp
 
317
  #include <compare> // see [compare.syn]
318
 
319
  namespace std {
320
  // [string.view.template], class template basic_string_view
321
  template<class charT, class traits = char_traits<charT>>
322
- class basic_string_view;
323
 
324
  template<class charT, class traits>
325
- constexpr bool ranges::enable_view<basic_string_view<charT, traits>> = true;
326
  template<class charT, class traits>
327
- constexpr bool ranges::enable_borrowed_range<basic_string_view<charT, traits>> = true;
328
 
329
  // [string.view.comparison], non-member comparison functions
330
  template<class charT, class traits>
331
  constexpr bool operator==(basic_string_view<charT, traits> x,
332
- basic_string_view<charT, traits> y) noexcept;
333
  template<class charT, class traits>
334
  constexpr see below operator<=>(basic_string_view<charT, traits> x,
335
- \itcorr basic_string_view<charT, traits> y) noexcept;
336
-
337
- // see [string.view.comparison], sufficient additional overloads of comparison functions
338
 
339
  // [string.view.io], inserters and extractors
340
  template<class charT, class traits>
341
  basic_ostream<charT, traits>&
342
  operator<<(basic_ostream<charT, traits>& os,
343
- basic_string_view<charT, traits> str);
344
 
345
  // basic_string_view typedef-names
346
  using string_view = basic_string_view<char>;
347
  using u8string_view = basic_string_view<char8_t>;
348
  using u16string_view = basic_string_view<char16_t>;
@@ -421,36 +423,43 @@ namespace std {
421
 
422
  // [string.view.capacity], capacity
423
  constexpr size_type size() const noexcept;
424
  constexpr size_type length() const noexcept;
425
  constexpr size_type max_size() const noexcept;
426
- [[nodiscard]] constexpr bool empty() const noexcept;
427
 
428
  // [string.view.access], element access
429
  constexpr const_reference operator[](size_type pos) const;
430
- constexpr const_reference at(size_type pos) const;
431
  constexpr const_reference front() const;
432
  constexpr const_reference back() const;
433
  constexpr const_pointer data() const noexcept;
434
 
435
  // [string.view.modifiers], modifiers
436
  constexpr void remove_prefix(size_type n);
437
  constexpr void remove_suffix(size_type n);
438
  constexpr void swap(basic_string_view& s) noexcept;
439
 
440
  // [string.view.ops], string operations
441
- constexpr size_type copy(charT* s, size_type n, size_type pos = 0) const;
 
442
 
443
- constexpr basic_string_view substr(size_type pos = 0, size_type n = npos) const;
 
 
 
444
 
445
  constexpr int compare(basic_string_view s) const noexcept;
446
- constexpr int compare(size_type pos1, size_type n1, basic_string_view s) const;
 
447
  constexpr int compare(size_type pos1, size_type n1, basic_string_view s,
448
- size_type pos2, size_type n2) const;
449
  constexpr int compare(const charT* s) const;
450
- constexpr int compare(size_type pos1, size_type n1, const charT* s) const;
451
- constexpr int compare(size_type pos1, size_type n1, const charT* s, size_type n2) const;
 
 
452
 
453
  constexpr bool starts_with(basic_string_view x) const noexcept;
454
  constexpr bool starts_with(charT x) const noexcept;
455
  constexpr bool starts_with(const charT* x) const;
456
  constexpr bool ends_with(basic_string_view x) const noexcept;
@@ -514,15 +523,14 @@ same type as `charT`. — *end note*]
514
 
515
  For a `basic_string_view str`, any operation that invalidates a pointer
516
  in the range
517
 
518
  ``` cpp
519
- {[}str.data(), {str.data() + str.size()}{)}
520
  ```
521
 
522
- invalidates pointers, iterators, and references returned from `str`’s
523
- member functions.
524
 
525
  The complexity of `basic_string_view` member functions is 𝑂(1) unless
526
  otherwise specified.
527
 
528
  `basic_string_view<charT, traits>` is a trivially copyable type
@@ -532,31 +540,31 @@ otherwise specified.
532
 
533
  ``` cpp
534
  constexpr basic_string_view() noexcept;
535
  ```
536
 
537
- *Ensures:* `size_ == 0` and `data_ == nullptr`.
538
 
539
  ``` cpp
540
  constexpr basic_string_view(const charT* str);
541
  ```
542
 
543
  *Preconditions:* \[`str`, `str + traits::length(str)`) is a valid range.
544
 
545
- *Effects:* Constructs a `basic_string_view`, initializing `data_` with
546
- `str` and initializing `size_` with `traits::length(str)`.
547
 
548
  *Complexity:* 𝑂(`traits::length(str)`).
549
 
550
  ``` cpp
551
  constexpr basic_string_view(const charT* str, size_type len);
552
  ```
553
 
554
  *Preconditions:* \[`str`, `str + len`) is a valid range.
555
 
556
- *Effects:* Constructs a `basic_string_view`, initializing `data_` with
557
- `str` and initializing `size_` with `len`.
558
 
559
  ``` cpp
560
  template<class It, class End>
561
  constexpr basic_string_view(It begin, End end);
562
  ```
@@ -572,12 +580,12 @@ template<class It, class End>
572
 
573
  - \[`begin`, `end`) is a valid range.
574
  - `It` models `contiguous_iterator`.
575
  - `End` models `sized_sentinel_for<It>`.
576
 
577
- *Effects:* Initializes `data_` with `to_address(begin)` and initializes
578
- `size_` with `end - begin`.
579
 
580
  *Throws:* When and what `end - begin` throws.
581
 
582
  ``` cpp
583
  template<class R>
@@ -593,11 +601,11 @@ Let `d` be an lvalue of type `remove_cvref_t<R>`.
593
  - `is_same_v<ranges::range_value_t<R>, charT>` is `true`,
594
  - `is_convertible_v<R, const charT*>` is `false`, and
595
  - `d.operator ::std::basic_string_view<charT, traits>()` is not a valid
596
  expression.
597
 
598
- *Effects:* Initializes `data_` with `ranges::data(r)` and `size_` with
599
  `ranges::size(r)`.
600
 
601
  *Throws:* Any exception thrown by `ranges::data(r)` and
602
  `ranges::size(r)`.
603
 
@@ -640,11 +648,11 @@ constexpr const_iterator begin() const noexcept;
640
  constexpr const_iterator cbegin() const noexcept;
641
  ```
642
 
643
  *Returns:* An iterator such that
644
 
645
- - if `!empty()`, `addressof(*begin()) == data_`,
646
  - otherwise, an unspecified value such that \[`begin()`, `end()`) is a
647
  valid range.
648
 
649
  ``` cpp
650
  constexpr const_iterator end() const noexcept;
@@ -672,74 +680,73 @@ constexpr const_reverse_iterator crend() const noexcept;
672
  ``` cpp
673
  constexpr size_type size() const noexcept;
674
  constexpr size_type length() const noexcept;
675
  ```
676
 
677
- *Returns:* `size_`.
678
 
679
  ``` cpp
680
  constexpr size_type max_size() const noexcept;
681
  ```
682
 
683
  *Returns:* The largest possible number of char-like objects that can be
684
  referred to by a `basic_string_view`.
685
 
686
  ``` cpp
687
- [[nodiscard]] constexpr bool empty() const noexcept;
688
  ```
689
 
690
- *Returns:* `size_ == 0`.
691
 
692
  #### Element access <a id="string.view.access">[[string.view.access]]</a>
693
 
694
  ``` cpp
695
  constexpr const_reference operator[](size_type pos) const;
696
  ```
697
 
698
- *Preconditions:* `pos < size()`.
699
 
700
- *Returns:* `data_[pos]`.
 
 
 
701
 
702
  *Throws:* Nothing.
703
 
704
- [*Note 1*: Unlike `basic_string::operator[]`,
705
- `basic_string_view::operator[](size())` has undefined behavior instead
706
- of returning `charT()`. — *end note*]
707
-
708
  ``` cpp
709
  constexpr const_reference at(size_type pos) const;
710
  ```
711
 
712
- *Returns:* `data_[pos]`.
713
 
714
  *Throws:* `out_of_range` if `pos >= size()`.
715
 
716
  ``` cpp
717
  constexpr const_reference front() const;
718
  ```
719
 
720
- *Preconditions:* `!empty()`.
721
 
722
- *Returns:* `data_[0]`.
723
 
724
  *Throws:* Nothing.
725
 
726
  ``` cpp
727
  constexpr const_reference back() const;
728
  ```
729
 
730
- *Preconditions:* `!empty()`.
731
 
732
- *Returns:* `data_[size() - 1]`.
733
 
734
  *Throws:* Nothing.
735
 
736
  ``` cpp
737
  constexpr const_pointer data() const noexcept;
738
  ```
739
 
740
- *Returns:* `data_`.
741
 
742
  [*Note 2*: Unlike `basic_string::data()` and *string-literal*s,
743
  `data()` can return a pointer to a buffer that is not null-terminated.
744
  Therefore it is typically a mistake to pass `data()` to a function that
745
  takes just a `const charT*` and expects a null-terminated
@@ -749,21 +756,21 @@ string. — *end note*]
749
 
750
  ``` cpp
751
  constexpr void remove_prefix(size_type n);
752
  ```
753
 
754
- *Preconditions:* `n <= size()`.
755
 
756
- *Effects:* Equivalent to: `data_ += n; size_ -= n;`
757
 
758
  ``` cpp
759
  constexpr void remove_suffix(size_type n);
760
  ```
761
 
762
- *Preconditions:* `n <= size()`.
763
 
764
- *Effects:* Equivalent to: `size_ -= n;`
765
 
766
  ``` cpp
767
  constexpr void swap(basic_string_view& s) noexcept;
768
  ```
769
 
@@ -787,10 +794,11 @@ Let `rlen` be the smaller of `n` and `size() - pos`.
787
 
788
  *Complexity:* 𝑂(`rlen`).
789
 
790
  ``` cpp
791
  constexpr basic_string_view substr(size_type pos = 0, size_type n = npos) const;
 
792
  ```
793
 
794
  Let `rlen` be the smaller of `n` and `size() - pos`.
795
 
796
  *Effects:* Determines `rlen`, the effective length of the string to
@@ -861,11 +869,13 @@ constexpr int compare(size_type pos1, size_type n1, const charT* s, size_type n2
861
 
862
  ``` cpp
863
  constexpr bool starts_with(basic_string_view x) const noexcept;
864
  ```
865
 
866
- *Effects:* Equivalent to: `return substr(0, x.size()) == x;`
 
 
867
 
868
  ``` cpp
869
  constexpr bool starts_with(charT x) const noexcept;
870
  ```
871
 
@@ -879,14 +889,16 @@ constexpr bool starts_with(const charT* x) const;
879
 
880
  ``` cpp
881
  constexpr bool ends_with(basic_string_view x) const noexcept;
882
  ```
883
 
 
 
884
  *Effects:* Equivalent to:
885
 
886
  ``` cpp
887
- return size() >= x.size() && compare(size() - x.size(), npos, x) == 0;
888
  ```
889
 
890
  ``` cpp
891
  constexpr bool ends_with(charT x) const noexcept;
892
  ```
@@ -943,12 +955,12 @@ constexpr size_type find(basic_string_view str, size_type pos = 0) const noexcep
943
  Let `xpos` be the lowest position, if possible, such that the following
944
  conditions hold:
945
 
946
  - `pos <= xpos`
947
  - `xpos + str.size() <= size()`
948
- - `traits::eq(at(xpos + I), str.at(I))` for all elements `I` of the
949
- string referenced by `str`.
950
 
951
  *Effects:* Determines `xpos`.
952
 
953
  *Returns:* `xpos` if the function can determine such a value for `xpos`.
954
  Otherwise, returns `npos`.
@@ -960,12 +972,12 @@ constexpr size_type rfind(basic_string_view str, size_type pos = npos) const noe
960
  Let `xpos` be the highest position, if possible, such that the following
961
  conditions hold:
962
 
963
  - `xpos <= pos`
964
  - `xpos + str.size() <= size()`
965
- - `traits::eq(at(xpos + I), str.at(I))` for all elements `I` of the
966
- string referenced by `str`.
967
 
968
  *Effects:* Determines `xpos`.
969
 
970
  *Returns:* `xpos` if the function can determine such a value for `xpos`.
971
  Otherwise, returns `npos`.
@@ -977,12 +989,12 @@ constexpr size_type find_first_of(basic_string_view str, size_type pos = 0) cons
977
  Let `xpos` be the lowest position, if possible, such that the following
978
  conditions hold:
979
 
980
  - `pos <= xpos`
981
  - `xpos < size()`
982
- - `traits::eq(at(xpos), str.at(I))` for some element `I` of the string
983
- referenced by `str`.
984
 
985
  *Effects:* Determines `xpos`.
986
 
987
  *Returns:* `xpos` if the function can determine such a value for `xpos`.
988
  Otherwise, returns `npos`.
@@ -994,12 +1006,12 @@ constexpr size_type find_last_of(basic_string_view str, size_type pos = npos) co
994
  Let `xpos` be the highest position, if possible, such that the following
995
  conditions hold:
996
 
997
  - `xpos <= pos`
998
  - `xpos < size()`
999
- - `traits::eq(at(xpos), str.at(I))` for some element `I` of the string
1000
- referenced by `str`.
1001
 
1002
  *Effects:* Determines `xpos`.
1003
 
1004
  *Returns:* `xpos` if the function can determine such a value for `xpos`.
1005
  Otherwise, returns `npos`.
@@ -1011,12 +1023,12 @@ constexpr size_type find_first_not_of(basic_string_view str, size_type pos = 0)
1011
  Let `xpos` be the lowest position, if possible, such that the following
1012
  conditions hold:
1013
 
1014
  - `pos <= xpos`
1015
  - `xpos < size()`
1016
- - `traits::eq(at(xpos), str.at(I))` for no element `I` of the string
1017
- referenced by `str`.
1018
 
1019
  *Effects:* Determines `xpos`.
1020
 
1021
  *Returns:* `xpos` if the function can determine such a value for `xpos`.
1022
  Otherwise, returns `npos`.
@@ -1028,87 +1040,48 @@ constexpr size_type find_last_not_of(basic_string_view str, size_type pos = npos
1028
  Let `xpos` be the highest position, if possible, such that the following
1029
  conditions hold:
1030
 
1031
  - `xpos <= pos`
1032
  - `xpos < size()`
1033
- - `traits::eq(at(xpos), str.at(I))` for no element `I` of the string
1034
- referenced by `str`.
1035
 
1036
  *Effects:* Determines `xpos`.
1037
 
1038
  *Returns:* `xpos` if the function can determine such a value for `xpos`.
1039
  Otherwise, returns `npos`.
1040
 
1041
  ### Non-member comparison functions <a id="string.view.comparison">[[string.view.comparison]]</a>
1042
 
1043
- Let `S` be `basic_string_view<charT, traits>`, and `sv` be an instance
1044
- of `S`. Implementations shall provide sufficient additional overloads
1045
- marked `constexpr` and `noexcept` so that an object `t` with an implicit
1046
- conversion to `S` can be compared according to
1047
- [[string.view.comparison.overloads]].
1048
-
1049
- **Table: Additional `basic_string_view` comparison overloads** <a id="string.view.comparison.overloads">[string.view.comparison.overloads]</a>
1050
-
1051
- | Expression | Equivalent to |
1052
- | ---------- | ------------- |
1053
- | `t == sv` | `S(t) == sv` |
1054
- | `sv == t` | `sv == S(t)` |
1055
- | `t != sv` | `S(t) != sv` |
1056
- | `sv != t` | `sv != S(t)` |
1057
- | `t < sv` | `S(t) < sv` |
1058
- | `sv < t` | `sv < S(t)` |
1059
- | `t > sv` | `S(t) > sv` |
1060
- | `sv > t` | `sv > S(t)` |
1061
- | `t <= sv` | `S(t) <= sv` |
1062
- | `sv <= t` | `sv <= S(t)` |
1063
- | `t >= sv` | `S(t) >= sv` |
1064
- | `sv >= t` | `sv >= S(t)` |
1065
- | `t <=> sv` | `S(t) <=> sv` |
1066
- | `sv <=> t` | `sv <=> S(t)` |
1067
-
1068
-
1069
- [*Example 1*:
1070
-
1071
- A sample conforming implementation for `operator==` would be:
1072
-
1073
  ``` cpp
1074
  template<class charT, class traits>
1075
  constexpr bool operator==(basic_string_view<charT, traits> lhs,
1076
- basic_string_view<charT, traits> rhs) noexcept {
1077
- return lhs.compare(rhs) == 0;
1078
- }
1079
- template<class charT, class traits>
1080
- constexpr bool operator==(basic_string_view<charT, traits> lhs,
1081
- type_identity_t<basic_string_view<charT, traits>> rhs) noexcept {
1082
- return lhs.compare(rhs) == 0;
1083
- }
1084
- ```
1085
-
1086
- — *end example*]
1087
-
1088
- ``` cpp
1089
- template<class charT, class traits>
1090
- constexpr bool operator==(basic_string_view<charT, traits> lhs,
1091
- basic_string_view<charT, traits> rhs) noexcept;
1092
  ```
1093
 
1094
  *Returns:* `lhs.compare(rhs) == 0`.
1095
 
1096
  ``` cpp
1097
  template<class charT, class traits>
1098
  constexpr see below operator<=>(basic_string_view<charT, traits> lhs,
1099
- \itcorr basic_string_view<charT, traits> rhs) noexcept;
1100
  ```
1101
 
1102
  Let `R` denote the type `traits::comparison_category` if that
1103
  *qualified-id* is valid and denotes a type [[temp.deduct]], otherwise
1104
  `R` is `weak_ordering`.
1105
 
1106
  *Mandates:* `R` denotes a comparison category type [[cmp.categories]].
1107
 
1108
  *Returns:* `static_cast<R>(lhs.compare(rhs) <=> 0)`.
1109
 
 
 
 
 
 
 
1110
  ### Inserters and extractors <a id="string.view.io">[[string.view.io]]</a>
1111
 
1112
  ``` cpp
1113
  template<class charT, class traits>
1114
  basic_ostream<charT, traits>&
@@ -1121,11 +1094,11 @@ sequence `seq`, initially consisting of the elements defined by the
1121
  range \[`str.begin()`, `str.end()`). Determines padding for `seq` as
1122
  described in  [[ostream.formatted.reqmts]]. Then inserts `seq` as if by
1123
  calling `os.rdbuf()->sputn(seq, n)`, where `n` is the larger of
1124
  `os.width()` and `str.size()`; then calls `os.width(0)`.
1125
 
1126
- *Returns:* `os`
1127
 
1128
  ### Hash support <a id="string.view.hash">[[string.view.hash]]</a>
1129
 
1130
  ``` cpp
1131
  template<> struct hash<string_view>;
@@ -1190,16 +1163,16 @@ manipulating varying-length sequences of char-like objects and five
1190
  #include <compare> // see [compare.syn]
1191
  #include <initializer_list> // see [initializer.list.syn]
1192
 
1193
  namespace std {
1194
  // [char.traits], character traits
1195
- template<class charT> struct char_traits;
1196
- template<> struct char_traits<char>;
1197
- template<> struct char_traits<char8_t>;
1198
- template<> struct char_traits<char16_t>;
1199
- template<> struct char_traits<char32_t>;
1200
- template<> struct char_traits<wchar_t>;
1201
 
1202
  // [basic.string], basic_string
1203
  template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
1204
  class basic_string;
1205
 
@@ -1249,10 +1222,26 @@ namespace std {
1249
  charT rhs);
1250
  template<class charT, class traits, class Allocator>
1251
  constexpr basic_string<charT, traits, Allocator>
1252
  operator+(basic_string<charT, traits, Allocator>&& lhs,
1253
  charT rhs);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1254
 
1255
  template<class charT, class traits, class Allocator>
1256
  constexpr bool
1257
  operator==(const basic_string<charT, traits, Allocator>& lhs,
1258
  const basic_string<charT, traits, Allocator>& rhs) noexcept;
@@ -1301,11 +1290,11 @@ namespace std {
1301
  basic_istream<charT, traits>&
1302
  getline(basic_istream<charT, traits>&& is,
1303
  basic_string<charT, traits, Allocator>& str);
1304
 
1305
  // [string.erasure], erasure
1306
- template<class charT, class traits, class Allocator, class U>
1307
  constexpr typename basic_string<charT, traits, Allocator>::size_type
1308
  erase(basic_string<charT, traits, Allocator>& c, const U& value);
1309
  template<class charT, class traits, class Allocator, class Predicate>
1310
  constexpr typename basic_string<charT, traits, Allocator>::size_type
1311
  erase_if(basic_string<charT, traits, Allocator>& c, Predicate pred);
@@ -1413,14 +1402,14 @@ namespace std {
1413
  public:
1414
  // types
1415
  using traits_type = traits;
1416
  using value_type = charT;
1417
  using allocator_type = Allocator;
1418
- using size_type = typename allocator_traits<Allocator>::size_type;
1419
- using difference_type = typename allocator_traits<Allocator>::difference_type;
1420
- using pointer = typename allocator_traits<Allocator>::pointer;
1421
- using const_pointer = typename allocator_traits<Allocator>::const_pointer;
1422
  using reference = value_type&;
1423
  using const_reference = const value_type&;
1424
 
1425
  using iterator = implementation-defined // type of basic_string::iterator; // see [container.requirements]
1426
  using const_iterator = implementation-defined // type of basic_string::const_iterator; // see [container.requirements]
@@ -1496,11 +1485,11 @@ namespace std {
1496
  template<class Operation> constexpr void resize_and_overwrite(size_type n, Operation op);
1497
  constexpr size_type capacity() const noexcept;
1498
  constexpr void reserve(size_type res_arg);
1499
  constexpr void shrink_to_fit();
1500
  constexpr void clear() noexcept;
1501
- [[nodiscard]] constexpr bool empty() const noexcept;
1502
 
1503
  // [string.access], element access
1504
  constexpr const_reference operator[](size_type pos) const;
1505
  constexpr reference operator[](size_type pos);
1506
  constexpr const_reference at(size_type n) const;
@@ -1662,10 +1651,12 @@ namespace std {
1662
  constexpr size_type find_last_not_of(const charT* s, size_type pos = npos) const;
1663
  constexpr size_type find_last_not_of(charT c, size_type pos = npos) const noexcept;
1664
 
1665
  constexpr basic_string substr(size_type pos = 0, size_type n = npos) const &;
1666
  constexpr basic_string substr(size_type pos = 0, size_type n = npos) &&;
 
 
1667
 
1668
  template<class T>
1669
  constexpr int compare(const T& t) const noexcept(see below);
1670
  template<class T>
1671
  constexpr int compare(size_type pos1, size_type n1, const T& t) const;
@@ -1735,24 +1726,23 @@ operation throws an exception object of type `length_error`.
1735
 
1736
  If any member function or operator of `basic_string` throws an
1737
  exception, that function or operator has no other effect on the
1738
  `basic_string` object.
1739
 
1740
- In every specialization `basic_string<charT, traits, Allocator>`, the
1741
- type `allocator_traits<Allocator>::value_type` shall name the same type
1742
- as `charT`. Every object of type
1743
- `basic_string<charT, traits, Allocator>` uses an object of type
1744
- `Allocator` to allocate and free storage for the contained `charT`
1745
- objects as needed. The `Allocator` object used is obtained as described
1746
- in [[container.requirements.general]]. In every specialization
1747
  `basic_string<charT, traits, Allocator>`, the type `traits` shall meet
1748
  the character traits requirements [[char.traits]].
1749
 
1750
  [*Note 1*: Every specialization
1751
- `basic_string<charT, traits, Allocator>` is an allocator-aware
1752
- container, but does not use the allocator’s `construct` and `destroy`
1753
- member functions [[container.requirements.general]]. — *end note*]
 
 
1754
 
1755
  [*Note 2*: The program is ill-formed if `traits::char_type` is not the
1756
  same type as `charT`. — *end note*]
1757
 
1758
  References, pointers, and iterators referring to the elements of a
@@ -1858,11 +1848,11 @@ is equal to `0`.
1858
  ``` cpp
1859
  constexpr basic_string(const charT* s, const Allocator& a = Allocator());
1860
  ```
1861
 
1862
  *Constraints:* `Allocator` is a type that qualifies as an
1863
- allocator [[container.requirements.general]].
1864
 
1865
  [*Note 1*: This affects class template argument
1866
  deduction. — *end note*]
1867
 
1868
  *Effects:* Equivalent to: `basic_string(s, traits::length(s), a)`.
@@ -1870,11 +1860,11 @@ deduction. — *end note*]
1870
  ``` cpp
1871
  constexpr basic_string(size_type n, charT c, const Allocator& a = Allocator());
1872
  ```
1873
 
1874
  *Constraints:* `Allocator` is a type that qualifies as an
1875
- allocator [[container.requirements.general]].
1876
 
1877
  [*Note 2*: This affects class template argument
1878
  deduction. — *end note*]
1879
 
1880
  *Effects:* Constructs an object whose value consists of `n` copies of
@@ -1884,11 +1874,11 @@ deduction. — *end note*]
1884
  template<class InputIterator>
1885
  constexpr basic_string(InputIterator begin, InputIterator end, const Allocator& a = Allocator());
1886
  ```
1887
 
1888
  *Constraints:* `InputIterator` is a type that qualifies as an input
1889
- iterator [[container.requirements.general]].
1890
 
1891
  *Effects:* Constructs a string from the values in the range \[`begin`,
1892
  `end`), as specified in [[sequence.reqmts]].
1893
 
1894
  ``` cpp
@@ -1926,11 +1916,11 @@ template<class InputIterator,
1926
  Allocator>;
1927
  ```
1928
 
1929
  *Constraints:* `InputIterator` is a type that qualifies as an input
1930
  iterator, and `Allocator` is a type that qualifies as an
1931
- allocator [[container.requirements.general]].
1932
 
1933
  ``` cpp
1934
  template<class charT,
1935
  class traits,
1936
  class Allocator = allocator<charT>>
@@ -1945,11 +1935,11 @@ template<class charT,
1945
  const Allocator& = Allocator())
1946
  -> basic_string<charT, traits, Allocator>;
1947
  ```
1948
 
1949
  *Constraints:* `Allocator` is a type that qualifies as an
1950
- allocator [[container.requirements.general]].
1951
 
1952
  ``` cpp
1953
  constexpr basic_string& operator=(const basic_string& str);
1954
  ```
1955
 
@@ -1962,13 +1952,12 @@ Otherwise, replaces the value of `*this` with a copy of `str`.
1962
  constexpr basic_string& operator=(basic_string&& str)
1963
  noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
1964
  allocator_traits<Allocator>::is_always_equal::value);
1965
  ```
1966
 
1967
- *Effects:* Move assigns as a sequence
1968
- container [[container.requirements]], except that iterators, pointers
1969
- and references may be invalidated.
1970
 
1971
  *Returns:* `*this`.
1972
 
1973
  ``` cpp
1974
  template<class T>
@@ -2134,14 +2123,14 @@ constexpr size_type capacity() const noexcept;
2134
  constexpr void reserve(size_type res_arg);
2135
  ```
2136
 
2137
  *Effects:* A directive that informs a `basic_string` of a planned change
2138
  in size, so that the storage allocation can be managed accordingly.
2139
- After `reserve()`, `capacity()` is greater or equal to the argument of
2140
- `reserve` if reallocation happens; and equal to the previous value of
2141
- `capacity()` otherwise. Reallocation happens at this point if and only
2142
- if the current capacity is less than the argument of `reserve()`.
2143
 
2144
  *Throws:* `length_error` if `res_arg > max_size()` or any exceptions
2145
  thrown by `allocator_traits` `<Allocator>::allocate`.
2146
 
2147
  ``` cpp
@@ -2172,11 +2161,11 @@ constexpr void clear() noexcept;
2172
  ```
2173
 
2174
  *Effects:* Equivalent to: `erase(begin(), end());`
2175
 
2176
  ``` cpp
2177
- [[nodiscard]] constexpr bool empty() const noexcept;
2178
  ```
2179
 
2180
  *Effects:* Equivalent to: `return size() == 0;`
2181
 
2182
  #### Element access <a id="string.access">[[string.access]]</a>
@@ -2184,11 +2173,11 @@ constexpr void clear() noexcept;
2184
  ``` cpp
2185
  constexpr const_reference operator[](size_type pos) const;
2186
  constexpr reference operator[](size_type pos);
2187
  ```
2188
 
2189
- *Preconditions:* `pos <= size()`.
2190
 
2191
  *Returns:* `*(begin() + pos)` if `pos < size()`. Otherwise, returns a
2192
  reference to an object of type `charT` with value `charT()`, where
2193
  modifying the object to any value other than `charT()` leads to
2194
  undefined behavior.
@@ -2209,20 +2198,20 @@ constexpr reference at(size_type pos);
2209
  ``` cpp
2210
  constexpr const charT& front() const;
2211
  constexpr charT& front();
2212
  ```
2213
 
2214
- *Preconditions:* `!empty()`.
2215
 
2216
  *Effects:* Equivalent to: `return operator[](0);`
2217
 
2218
  ``` cpp
2219
  constexpr const charT& back() const;
2220
  constexpr charT& back();
2221
  ```
2222
 
2223
- *Preconditions:* `!empty()`.
2224
 
2225
  *Effects:* Equivalent to: `return operator[](size() - 1);`
2226
 
2227
  #### Modifiers <a id="string.modifiers">[[string.modifiers]]</a>
2228
 
@@ -2352,11 +2341,11 @@ constexpr basic_string& append(size_type n, charT c);
2352
  template<class InputIterator>
2353
  constexpr basic_string& append(InputIterator first, InputIterator last);
2354
  ```
2355
 
2356
  *Constraints:* `InputIterator` is a type that qualifies as an input
2357
- iterator [[container.requirements.general]].
2358
 
2359
  *Effects:* Equivalent to:
2360
  `return append(basic_string(first, last, get_allocator()));`
2361
 
2362
  ``` cpp
@@ -2480,11 +2469,11 @@ return *this;
2480
  template<class InputIterator>
2481
  constexpr basic_string& assign(InputIterator first, InputIterator last);
2482
  ```
2483
 
2484
  *Constraints:* `InputIterator` is a type that qualifies as an input
2485
- iterator [[container.requirements.general]].
2486
 
2487
  *Effects:* Equivalent to:
2488
  `return assign(basic_string(first, last, get_allocator()));`
2489
 
2490
  ``` cpp
@@ -2580,11 +2569,11 @@ constexpr basic_string& insert(size_type pos, size_type n, charT c);
2580
  ```
2581
 
2582
  *Effects:* Inserts `n` copies of `c` before the character at position
2583
  `pos` if `pos < size()`, or otherwise at the end of the string.
2584
 
2585
- *Returns:* `*this`
2586
 
2587
  *Throws:*
2588
 
2589
  - `out_of_range` if `pos > size()`,
2590
  - `length_error` if `n > max_size() - size()`, or
@@ -2615,11 +2604,11 @@ constexpr iterator insert(const_iterator p, size_type n, charT c);
2615
  template<class InputIterator>
2616
  constexpr iterator insert(const_iterator p, InputIterator first, InputIterator last);
2617
  ```
2618
 
2619
  *Constraints:* `InputIterator` is a type that qualifies as an input
2620
- iterator [[container.requirements.general]].
2621
 
2622
  *Preconditions:* `p` is a valid iterator on `*this`.
2623
 
2624
  *Effects:* Equivalent to
2625
  `insert(p - begin(), basic_string(first, last, get_allocator()))`.
@@ -2679,11 +2668,11 @@ constexpr iterator erase(const_iterator first, const_iterator last);
2679
  ```
2680
 
2681
  *Preconditions:* `first` and `last` are valid iterators on `*this`.
2682
  \[`first`, `last`) is a valid range.
2683
 
2684
- *Effects:* Removes the characters in the range `[first, last)`.
2685
 
2686
  *Returns:* An iterator which points to the element pointed to by `last`
2687
  prior to the other elements being erased. If no such element exists,
2688
  `end()` is returned.
2689
 
@@ -2691,11 +2680,11 @@ prior to the other elements being erased. If no such element exists,
2691
 
2692
  ``` cpp
2693
  constexpr void pop_back();
2694
  ```
2695
 
2696
- *Preconditions:* `!empty()`.
2697
 
2698
  *Effects:* Equivalent to `erase(end() - 1)`.
2699
 
2700
  *Throws:* Nothing.
2701
 
@@ -2797,12 +2786,12 @@ the function replaces the characters in the range \[`begin() + pos1`,
2797
  *Returns:* `*this`.
2798
 
2799
  *Throws:*
2800
 
2801
  - `out_of_range` if `pos1 > size()`,
2802
- - `length_error` if the length of the resulting string would
2803
- exceed`max_size()`, or
2804
  - any exceptions thrown by `allocator_traits<Allocator>::allocate.`
2805
 
2806
  ``` cpp
2807
  constexpr basic_string& replace(const_iterator i1, const_iterator i2, const basic_string& str);
2808
  ```
@@ -2857,11 +2846,11 @@ template<class InputIterator>
2857
  constexpr basic_string& replace(const_iterator i1, const_iterator i2,
2858
  InputIterator j1, InputIterator j2);
2859
  ```
2860
 
2861
  *Constraints:* `InputIterator` is a type that qualifies as an input
2862
- iterator [[container.requirements.general]].
2863
 
2864
  *Effects:* Equivalent to:
2865
  `return replace(i1, i2, basic_string(j1, j2, get_allocator()));`
2866
 
2867
  ``` cpp
@@ -3037,10 +3026,17 @@ constexpr basic_string substr(size_type pos = 0, size_type n = npos) &&;
3037
  ```
3038
 
3039
  *Effects:* Equivalent to:
3040
  `return basic_string(std::move(*this), pos, n);`
3041
 
 
 
 
 
 
 
 
3042
  ##### `basic_string::compare` <a id="string.compare">[[string.compare]]</a>
3043
 
3044
  ``` cpp
3045
  template<class T>
3046
  constexpr int compare(const T& t) const noexcept(see below);
@@ -3324,10 +3320,74 @@ template<class charT, class traits, class Allocator>
3324
  ``` cpp
3325
  lhs.push_back(rhs);
3326
  return std::move(lhs);
3327
  ```
3328
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3329
  #### Non-member comparison operator functions <a id="string.cmp">[[string.cmp]]</a>
3330
 
3331
  ``` cpp
3332
  template<class charT, class traits, class Allocator>
3333
  constexpr bool
@@ -3452,11 +3512,11 @@ template<class charT, class traits, class Allocator>
3452
  *Returns:* `getline(is, str, is.widen(’\n’))`.
3453
 
3454
  #### Erasure <a id="string.erasure">[[string.erasure]]</a>
3455
 
3456
  ``` cpp
3457
- template<class charT, class traits, class Allocator, class U>
3458
  constexpr typename basic_string<charT, traits, Allocator>::size_type
3459
  erase(basic_string<charT, traits, Allocator>& c, const U& value);
3460
  ```
3461
 
3462
  *Effects:* Equivalent to:
@@ -3542,16 +3602,11 @@ string to_string(unsigned long long val);
3542
  string to_string(float val);
3543
  string to_string(double val);
3544
  string to_string(long double val);
3545
  ```
3546
 
3547
- *Returns:* Each function returns a `string` object holding the character
3548
- representation of the value of its argument that would be generated by
3549
- calling `sprintf(buf, fmt, val)` with a format specifier of `"%d"`,
3550
- `"%u"`, `"%ld"`, `"%lu"`, `"%lld"`, `"%llu"`, `"%f"`, `"%f"`, or
3551
- `"%Lf"`, respectively, where `buf` designates an internal character
3552
- buffer of sufficient size.
3553
 
3554
  ``` cpp
3555
  int stoi(const wstring& str, size_t* idx = nullptr, int base = 10);
3556
  long stol(const wstring& str, size_t* idx = nullptr, int base = 10);
3557
  unsigned long stoul(const wstring& str, size_t* idx = nullptr, int base = 10);
@@ -3606,16 +3661,11 @@ wstring to_wstring(unsigned long long val);
3606
  wstring to_wstring(float val);
3607
  wstring to_wstring(double val);
3608
  wstring to_wstring(long double val);
3609
  ```
3610
 
3611
- *Returns:* Each function returns a `wstring` object holding the
3612
- character representation of the value of its argument that would be
3613
- generated by calling `swprintf(buf, buffsz, fmt, val)` with a format
3614
- specifier of `L"%d"`, `L"%u"`, `L"%ld"`, `L"%lu"`, `L"%lld"`, `L"%llu"`,
3615
- `L"%f"`, `L"%f"`, or `L"%Lf"`, respectively, where `buf` designates an
3616
- internal character buffer of sufficient size `buffsz`.
3617
 
3618
  ### Hash support <a id="basic.string.hash">[[basic.string.hash]]</a>
3619
 
3620
  ``` cpp
3621
  template<class A> struct hash<basic_string<char, char_traits<char>, A>>;
@@ -3666,365 +3716,80 @@ denoting seconds but there is no conflict, since duration suffixes apply
3666
  to numbers and string literal suffixes apply to character array
3667
  literals. — *end note*]
3668
 
3669
  ## Null-terminated sequence utilities <a id="c.strings">[[c.strings]]</a>
3670
 
3671
- ### Header `<cctype>` synopsis <a id="cctype.syn">[[cctype.syn]]</a>
3672
-
3673
- ``` cpp
3674
- namespace std {
3675
- int isalnum(int c);
3676
- int isalpha(int c);
3677
- int isblank(int c);
3678
- int iscntrl(int c);
3679
- int isdigit(int c);
3680
- int isgraph(int c);
3681
- int islower(int c);
3682
- int isprint(int c);
3683
- int ispunct(int c);
3684
- int isspace(int c);
3685
- int isupper(int c);
3686
- int isxdigit(int c);
3687
- int tolower(int c);
3688
- int toupper(int c);
3689
- }
3690
- ```
3691
-
3692
- The contents and meaning of the header `<cctype>` are the same as the C
3693
- standard library header `<ctype.h>`.
3694
-
3695
- See also: ISO C 7.4
3696
-
3697
- ### Header `<cwctype>` synopsis <a id="cwctype.syn">[[cwctype.syn]]</a>
3698
-
3699
- ``` cpp
3700
- namespace std {
3701
- using wint_t = see below;
3702
- using wctrans_t = see below;
3703
- using wctype_t = see below;
3704
-
3705
- int iswalnum(wint_t wc);
3706
- int iswalpha(wint_t wc);
3707
- int iswblank(wint_t wc);
3708
- int iswcntrl(wint_t wc);
3709
- int iswdigit(wint_t wc);
3710
- int iswgraph(wint_t wc);
3711
- int iswlower(wint_t wc);
3712
- int iswprint(wint_t wc);
3713
- int iswpunct(wint_t wc);
3714
- int iswspace(wint_t wc);
3715
- int iswupper(wint_t wc);
3716
- int iswxdigit(wint_t wc);
3717
- int iswctype(wint_t wc, wctype_t desc);
3718
- wctype_t wctype(const char* property);
3719
- wint_t towlower(wint_t wc);
3720
- wint_t towupper(wint_t wc);
3721
- wint_t towctrans(wint_t wc, wctrans_t desc);
3722
- wctrans_t wctrans(const char* property);
3723
- }
3724
-
3725
- #define WEOF see below
3726
- ```
3727
-
3728
- The contents and meaning of the header `<cwctype>` are the same as the C
3729
- standard library header `<wctype.h>`.
3730
-
3731
- See also: ISO C 7.30
3732
-
3733
  ### Header `<cstring>` synopsis <a id="cstring.syn">[[cstring.syn]]</a>
3734
 
3735
  ``` cpp
 
 
3736
  namespace std {
3737
- using size_t = see [support.types.layout];
3738
 
3739
- void* memcpy(void* s1, const void* s2, size_t n);
3740
- void* memmove(void* s1, const void* s2, size_t n);
3741
- char* strcpy(char* s1, const char* s2);
3742
- char* strncpy(char* s1, const char* s2, size_t n);
3743
- char* strcat(char* s1, const char* s2);
3744
- char* strncat(char* s1, const char* s2, size_t n);
3745
- int memcmp(const void* s1, const void* s2, size_t n);
3746
- int strcmp(const char* s1, const char* s2);
 
 
 
3747
  int strcoll(const char* s1, const char* s2);
3748
- int strncmp(const char* s1, const char* s2, size_t n);
3749
  size_t strxfrm(char* s1, const char* s2, size_t n);
3750
- const void* memchr(const void* s, int c, size_t n); // see [library.c]
3751
- void* memchr(void* s, int c, size_t n); // see [library.c]
3752
- const char* strchr(const char* s, int c); // see [library.c]
3753
- char* strchr(char* s, int c); // see [library.c]
3754
- size_t strcspn(const char* s1, const char* s2);
3755
- const char* strpbrk(const char* s1, const char* s2); // see [library.c]
3756
- char* strpbrk(char* s1, const char* s2); // see [library.c]
3757
- const char* strrchr(const char* s, int c); // see [library.c]
3758
- char* strrchr(char* s, int c); // see [library.c]
3759
- size_t strspn(const char* s1, const char* s2);
3760
- const char* strstr(const char* s1, const char* s2); // see [library.c]
3761
- char* strstr(char* s1, const char* s2); // see [library.c]
3762
  char* strtok(char* s1, const char* s2);
3763
- void* memset(void* s, int c, size_t n);
 
3764
  char* strerror(int errnum);
3765
- size_t strlen(const char* s);
3766
  }
3767
 
3768
- #define NULL see [support.types.nullptr]
3769
  ```
3770
 
3771
  The contents and meaning of the header `<cstring>` are the same as the C
3772
  standard library header `<string.h>`.
3773
 
3774
  The functions `strerror` and `strtok` are not required to avoid data
3775
  races [[res.on.data.races]].
3776
 
3777
  The functions `memcpy` and `memmove` are signal-safe [[support.signal]].
3778
- Both functions implicitly create objects [[intro.object]] in the
3779
- destination region of storage immediately prior to copying the sequence
3780
- of characters to the destination.
 
 
3781
 
3782
  [*Note 1*: The functions `strchr`, `strpbrk`, `strrchr`, `strstr`, and
3783
  `memchr`, have different signatures in this document, but they have the
3784
  same behavior as in the C standard library [[library.c]]. — *end note*]
3785
 
3786
- See also: ISO C 7.24
3787
-
3788
- ### Header `<cwchar>` synopsis <a id="cwchar.syn">[[cwchar.syn]]</a>
3789
-
3790
- ``` cpp
3791
- namespace std {
3792
- using size_t = see [support.types.layout];
3793
- using mbstate_t = see below;
3794
- using wint_t = see below;
3795
-
3796
- struct tm;
3797
-
3798
- int fwprintf(FILE* stream, const wchar_t* format, ...);
3799
- int fwscanf(FILE* stream, const wchar_t* format, ...);
3800
- int swprintf(wchar_t* s, size_t n, const wchar_t* format, ...);
3801
- int swscanf(const wchar_t* s, const wchar_t* format, ...);
3802
- int vfwprintf(FILE* stream, const wchar_t* format, va_list arg);
3803
- int vfwscanf(FILE* stream, const wchar_t* format, va_list arg);
3804
- int vswprintf(wchar_t* s, size_t n, const wchar_t* format, va_list arg);
3805
- int vswscanf(const wchar_t* s, const wchar_t* format, va_list arg);
3806
- int vwprintf(const wchar_t* format, va_list arg);
3807
- int vwscanf(const wchar_t* format, va_list arg);
3808
- int wprintf(const wchar_t* format, ...);
3809
- int wscanf(const wchar_t* format, ...);
3810
- wint_t fgetwc(FILE* stream);
3811
- wchar_t* fgetws(wchar_t* s, int n, FILE* stream);
3812
- wint_t fputwc(wchar_t c, FILE* stream);
3813
- int fputws(const wchar_t* s, FILE* stream);
3814
- int fwide(FILE* stream, int mode);
3815
- wint_t getwc(FILE* stream);
3816
- wint_t getwchar();
3817
- wint_t putwc(wchar_t c, FILE* stream);
3818
- wint_t putwchar(wchar_t c);
3819
- wint_t ungetwc(wint_t c, FILE* stream);
3820
- double wcstod(const wchar_t* nptr, wchar_t** endptr);
3821
- float wcstof(const wchar_t* nptr, wchar_t** endptr);
3822
- long double wcstold(const wchar_t* nptr, wchar_t** endptr);
3823
- long int wcstol(const wchar_t* nptr, wchar_t** endptr, int base);
3824
- long long int wcstoll(const wchar_t* nptr, wchar_t** endptr, int base);
3825
- unsigned long int wcstoul(const wchar_t* nptr, wchar_t** endptr, int base);
3826
- unsigned long long int wcstoull(const wchar_t* nptr, wchar_t** endptr, int base);
3827
- wchar_t* wcscpy(wchar_t* s1, const wchar_t* s2);
3828
- wchar_t* wcsncpy(wchar_t* s1, const wchar_t* s2, size_t n);
3829
- wchar_t* wmemcpy(wchar_t* s1, const wchar_t* s2, size_t n);
3830
- wchar_t* wmemmove(wchar_t* s1, const wchar_t* s2, size_t n);
3831
- wchar_t* wcscat(wchar_t* s1, const wchar_t* s2);
3832
- wchar_t* wcsncat(wchar_t* s1, const wchar_t* s2, size_t n);
3833
- int wcscmp(const wchar_t* s1, const wchar_t* s2);
3834
- int wcscoll(const wchar_t* s1, const wchar_t* s2);
3835
- int wcsncmp(const wchar_t* s1, const wchar_t* s2, size_t n);
3836
- size_t wcsxfrm(wchar_t* s1, const wchar_t* s2, size_t n);
3837
- int wmemcmp(const wchar_t* s1, const wchar_t* s2, size_t n);
3838
- const wchar_t* wcschr(const wchar_t* s, wchar_t c); // see [library.c]
3839
- wchar_t* wcschr(wchar_t* s, wchar_t c); // see [library.c]
3840
- size_t wcscspn(const wchar_t* s1, const wchar_t* s2);
3841
- const wchar_t* wcspbrk(const wchar_t* s1, const wchar_t* s2); // see [library.c]
3842
- wchar_t* wcspbrk(wchar_t* s1, const wchar_t* s2); // see [library.c]
3843
- const wchar_t* wcsrchr(const wchar_t* s, wchar_t c); // see [library.c]
3844
- wchar_t* wcsrchr(wchar_t* s, wchar_t c); // see [library.c]
3845
- size_t wcsspn(const wchar_t* s1, const wchar_t* s2);
3846
- const wchar_t* wcsstr(const wchar_t* s1, const wchar_t* s2); // see [library.c]
3847
- wchar_t* wcsstr(wchar_t* s1, const wchar_t* s2); // see [library.c]
3848
- wchar_t* wcstok(wchar_t* s1, const wchar_t* s2, wchar_t** ptr);
3849
- const wchar_t* wmemchr(const wchar_t* s, wchar_t c, size_t n); // see [library.c]
3850
- wchar_t* wmemchr(wchar_t* s, wchar_t c, size_t n); // see [library.c]
3851
- size_t wcslen(const wchar_t* s);
3852
- wchar_t* wmemset(wchar_t* s, wchar_t c, size_t n);
3853
- size_t wcsftime(wchar_t* s, size_t maxsize, const wchar_t* format, const tm* timeptr);
3854
- wint_t btowc(int c);
3855
- int wctob(wint_t c);
3856
-
3857
- // [c.mb.wcs], multibyte / wide string and character conversion functions
3858
- int mbsinit(const mbstate_t* ps);
3859
- size_t mbrlen(const char* s, size_t n, mbstate_t* ps);
3860
- size_t mbrtowc(wchar_t* pwc, const char* s, size_t n, mbstate_t* ps);
3861
- size_t wcrtomb(char* s, wchar_t wc, mbstate_t* ps);
3862
- size_t mbsrtowcs(wchar_t* dst, const char** src, size_t len, mbstate_t* ps);
3863
- size_t wcsrtombs(char* dst, const wchar_t** src, size_t len, mbstate_t* ps);
3864
- }
3865
-
3866
- #define NULL see [support.types.nullptr]
3867
- #define WCHAR_MAX see below
3868
- #define WCHAR_MIN see below
3869
- #define WEOF see below
3870
- ```
3871
-
3872
- The contents and meaning of the header `<cwchar>` are the same as the C
3873
- standard library header `<wchar.h>`, except that it does not declare a
3874
- type `wchar_t`.
3875
-
3876
- [*Note 1*: The functions `wcschr`, `wcspbrk`, `wcsrchr`, `wcsstr`, and
3877
- `wmemchr` have different signatures in this document, but they have the
3878
- same behavior as in the C standard library [[library.c]]. — *end note*]
3879
-
3880
- See also: ISO C 7.29
3881
-
3882
- ### Header `<cuchar>` synopsis <a id="cuchar.syn">[[cuchar.syn]]</a>
3883
-
3884
- ``` cpp
3885
- namespace std {
3886
- using mbstate_t = see below;
3887
- using size_t = see [support.types.layout];
3888
-
3889
- size_t mbrtoc8(char8_t* pc8, const char* s, size_t n, mbstate_t* ps);
3890
- size_t c8rtomb(char* s, char8_t c8, mbstate_t* ps);
3891
- size_t mbrtoc16(char16_t* pc16, const char* s, size_t n, mbstate_t* ps);
3892
- size_t c16rtomb(char* s, char16_t c16, mbstate_t* ps);
3893
- size_t mbrtoc32(char32_t* pc32, const char* s, size_t n, mbstate_t* ps);
3894
- size_t c32rtomb(char* s, char32_t c32, mbstate_t* ps);
3895
- }
3896
- ```
3897
-
3898
- The contents and meaning of the header `<cuchar>` are the same as the C
3899
- standard library header `<uchar.h>`, except that it declares the
3900
- additional `mbrtoc8` and `c8rtomb` functions and does not declare types
3901
- `char16_t` nor `char32_t`.
3902
-
3903
- See also: ISO C 7.28
3904
-
3905
- ### Multibyte / wide string and character conversion functions <a id="c.mb.wcs">[[c.mb.wcs]]</a>
3906
-
3907
- [*Note 1*: The headers `<cstdlib>`, `<cuchar>`, and `<cwchar>` declare
3908
- the functions described in this subclause. — *end note*]
3909
-
3910
- ``` cpp
3911
- int mbsinit(const mbstate_t* ps);
3912
- int mblen(const char* s, size_t n);
3913
- size_t mbstowcs(wchar_t* pwcs, const char* s, size_t n);
3914
- size_t wcstombs(char* s, const wchar_t* pwcs, size_t n);
3915
- ```
3916
-
3917
- *Effects:* These functions have the semantics specified in the C
3918
- standard library.
3919
-
3920
- See also: ISO C 7.22.7.1, 7.22.8, 7.29.6.2.1
3921
-
3922
- ``` cpp
3923
- int mbtowc(wchar_t* pwc, const char* s, size_t n);
3924
- int wctomb(char* s, wchar_t wchar);
3925
- ```
3926
-
3927
- *Effects:* These functions have the semantics specified in the C
3928
- standard library.
3929
-
3930
- *Remarks:* Calls to these functions may introduce a data
3931
- race [[res.on.data.races]] with other calls to the same function.
3932
-
3933
- See also: ISO C 7.22.7
3934
-
3935
- ``` cpp
3936
- size_t mbrlen(const char* s, size_t n, mbstate_t* ps);
3937
- size_t mbrtowc(wchar_t* pwc, const char* s, size_t n, mbstate_t* ps);
3938
- size_t wcrtomb(char* s, wchar_t wc, mbstate_t* ps);
3939
- size_t mbsrtowcs(wchar_t* dst, const char** src, size_t len, mbstate_t* ps);
3940
- size_t wcsrtombs(char* dst, const wchar_t** src, size_t len, mbstate_t* ps);
3941
- ```
3942
-
3943
- *Effects:* These functions have the semantics specified in the C
3944
- standard library.
3945
-
3946
- *Remarks:* Calling these functions with an `mbstate_t*` argument that is
3947
- a null pointer value may introduce a data race [[res.on.data.races]]
3948
- with other calls to the same function with an `mbstate_t*` argument that
3949
- is a null pointer value.
3950
-
3951
- See also: ISO C 7.29.6.3
3952
-
3953
- ``` cpp
3954
- size_t mbrtoc8(char8_t* pc8, const char* s, size_t n, mbstate_t* ps);
3955
- ```
3956
-
3957
- *Effects:* If `s` is a null pointer, equivalent to
3958
- `mbrtoc8(nullptr, "", 1, ps)`. Otherwise, the function inspects at most
3959
- `n` bytes beginning with the byte pointed to by `s` to determine the
3960
- number of bytes needed to complete the next multibyte character
3961
- (including any shift sequences). If the function determines that the
3962
- next multibyte character is complete and valid, it determines the values
3963
- of the corresponding UTF-8 code units and then, if `pc8` is not a null
3964
- pointer, stores the value of the first (or only) such code unit in the
3965
- object pointed to by `pc8`. Subsequent calls will store successive UTF-8
3966
- code units without consuming any additional input until all the code
3967
- units have been stored. If the corresponding Unicode character is
3968
- U+0000 (null), the resulting state described is the initial conversion
3969
- state.
3970
-
3971
- *Returns:* The first of the following that applies (given the current
3972
- conversion state):
3973
-
3974
- - `0`, if the next `n` or fewer bytes complete the multibyte character
3975
- that corresponds to the U+0000 (null) Unicode character (which is the
3976
- value stored).
3977
- - between `1` and `n` (inclusive), if the next n or fewer bytes complete
3978
- a valid multibyte character (whose first (or only) code unit is
3979
- stored); the value returned is the number of bytes that complete the
3980
- multibyte character.
3981
- - `(size_t)(-3)`, if the next code unit resulting from a previous call
3982
- has been stored (no bytes from the input have been consumed by this
3983
- call).
3984
- - `(size_t)(-2)`, if the next `n` bytes contribute to an incomplete (but
3985
- potentially valid) multibyte character, and all `n` bytes have been
3986
- processed (no value is stored).
3987
- - `(size_t)(-1)`, if an encoding error occurs, in which case the next
3988
- `n` or fewer bytes do not contribute to a complete and valid multibyte
3989
- character (no value is stored); the value of the macro `EILSEQ` is
3990
- stored in `errno`, and the conversion state is unspecified.
3991
-
3992
- ``` cpp
3993
- size_t c8rtomb(char* s, char8_t c8, mbstate_t* ps);
3994
- ```
3995
-
3996
- *Effects:* If `s` is a null pointer, equivalent to
3997
- `c8rtomb(buf, u8’`\`0’, ps)` where `buf` is an internal buffer.
3998
- Otherwise, if `c8` completes a sequence of valid UTF-8 code units,
3999
- determines the number of bytes needed to represent the multibyte
4000
- character (including any shift sequences), and stores the multibyte
4001
- character representation in the array whose first element is pointed to
4002
- by `s`. At most `MB_CUR_MAX` bytes are stored. If the multibyte
4003
- character is a null character, a null byte is stored, preceded by any
4004
- shift sequence needed to restore the initial shift state; the resulting
4005
- state described is the initial conversion state.
4006
-
4007
- *Returns:* The number of bytes stored in the array object (including any
4008
- shift sequences). If `c8` does not contribute to a sequence of `char8_t`
4009
- corresponding to a valid multibyte character, the value of the macro
4010
- `EILSEQ` is stored in `errno`, `(size_t) (-1)` is returned, and the
4011
- conversion state is unspecified.
4012
-
4013
- *Remarks:* Calls to `c8rtomb` with a null pointer argument for `s` may
4014
- introduce a data race [[res.on.data.races]] with other calls to
4015
- `c8rtomb` with a null pointer argument for `s`.
4016
 
4017
  <!-- Link reference definitions -->
4018
  [basic.indet]: basic.md#basic.indet
4019
  [basic.string]: #basic.string
4020
  [basic.string.general]: #basic.string.general
4021
  [basic.string.hash]: #basic.string.hash
4022
  [basic.string.literals]: #basic.string.literals
4023
- [c.mb.wcs]: #c.mb.wcs
4024
  [c.strings]: #c.strings
4025
- [cctype.syn]: #cctype.syn
4026
  [char.traits]: #char.traits
4027
  [char.traits.general]: #char.traits.general
4028
  [char.traits.req]: #char.traits.req
4029
  [char.traits.require]: #char.traits.require
4030
  [char.traits.specializations]: #char.traits.specializations
@@ -4034,21 +3799,19 @@ introduce a data race [[res.on.data.races]] with other calls to
4034
  [char.traits.specializations.char8.t]: #char.traits.specializations.char8.t
4035
  [char.traits.specializations.general]: #char.traits.specializations.general
4036
  [char.traits.specializations.wchar.t]: #char.traits.specializations.wchar.t
4037
  [char.traits.typedefs]: #char.traits.typedefs
4038
  [cmp.categories]: support.md#cmp.categories
 
4039
  [container.reqmts]: containers.md#container.reqmts
4040
  [container.requirements]: containers.md#container.requirements
4041
- [container.requirements.general]: containers.md#container.requirements.general
4042
  [cpp17.copyassignable]: #cpp17.copyassignable
4043
  [cpp17.copyconstructible]: #cpp17.copyconstructible
4044
  [cpp17.defaultconstructible]: #cpp17.defaultconstructible
4045
  [cpp17.destructible]: #cpp17.destructible
4046
  [cstring.syn]: #cstring.syn
4047
- [cuchar.syn]: #cuchar.syn
4048
- [cwchar.syn]: #cwchar.syn
4049
- [cwctype.syn]: #cwctype.syn
4050
  [defns.character.container]: intro.md#defns.character.container
4051
  [input.output]: input.md#input.output
4052
  [intro.object]: basic.md#intro.object
4053
  [iostream.forward]: input.md#iostream.forward
4054
  [iostreams.limits.pos]: input.md#iostreams.limits.pos
@@ -4058,10 +3821,11 @@ introduce a data race [[res.on.data.races]] with other calls to
4058
  [iterator.concept.winc]: iterators.md#iterator.concept.winc
4059
  [iterator.range]: iterators.md#iterator.range
4060
  [iterator.requirements.general]: iterators.md#iterator.requirements.general
4061
  [library.c]: library.md#library.c
4062
  [ostream.formatted.reqmts]: input.md#ostream.formatted.reqmts
 
4063
  [random.access.iterators]: iterators.md#random.access.iterators
4064
  [res.on.data.races]: library.md#res.on.data.races
4065
  [sequence.reqmts]: containers.md#sequence.reqmts
4066
  [string.access]: #string.access
4067
  [string.accessors]: #string.accessors
@@ -4098,11 +3862,10 @@ introduce a data race [[res.on.data.races]] with other calls to
4098
  [string.view]: #string.view
4099
  [string.view.access]: #string.view.access
4100
  [string.view.capacity]: #string.view.capacity
4101
  [string.view.compare]: #string.view.compare
4102
  [string.view.comparison]: #string.view.comparison
4103
- [string.view.comparison.overloads]: #string.view.comparison.overloads
4104
  [string.view.cons]: #string.view.cons
4105
  [string.view.deduct]: #string.view.deduct
4106
  [string.view.find]: #string.view.find
4107
  [string.view.general]: #string.view.general
4108
  [string.view.hash]: #string.view.hash
 
1
  # Strings library <a id="strings">[[strings]]</a>
2
 
3
  ## General <a id="strings.general">[[strings.general]]</a>
4
 
5
  This Clause describes components for manipulating sequences of any
6
+ non-array trivially copyable standard-layout
7
+ [[term.standard.layout.type]] type `T` where
8
+ `is_trivially_default_constructible_v<T>` is `true`. Such types are
9
+ called *char-like types*, and objects of char-like types are called
10
+ *char-like objects* or simply *characters*.
11
 
12
  The following subclauses describe a character traits class, string
13
  classes, and null-terminated sequence utilities, as summarized in
14
  [[strings.summary]].
15
 
 
45
  values of type `C`; `p` and `q` denote values of type `const C*`; `s`
46
  denotes a value of type `C*`; `n`, `i` and `j` denote values of type
47
  `size_t`; `e` and `f` denote values of type `X::int_type`; `pos` denotes
48
  a value of type `X::pos_type`; and `r` denotes an lvalue of type `C`. No
49
  expression which is part of the character traits requirements specified
50
+ in [[char.traits.require]] shall exit via an exception.
51
 
52
  The class template
53
 
54
  ``` cpp
55
  template<class charT> struct char_traits;
 
314
  interoperate with these functions. — *end note*]
315
 
316
  ### Header `<string_view>` synopsis <a id="string.view.synop">[[string.view.synop]]</a>
317
 
318
  ``` cpp
319
+ // mostly freestanding
320
  #include <compare> // see [compare.syn]
321
 
322
  namespace std {
323
  // [string.view.template], class template basic_string_view
324
  template<class charT, class traits = char_traits<charT>>
325
+ class basic_string_view; // partially freestanding
326
 
327
  template<class charT, class traits>
328
+ constexpr bool ranges::\libspec{enable_view}{basic_string_view}<basic_string_view<charT, traits>> = true;
329
  template<class charT, class traits>
330
+ constexpr bool ranges::\libspec{enable_borrowed_range}{basic_string_view}<basic_string_view<charT, traits>> = true;
331
 
332
  // [string.view.comparison], non-member comparison functions
333
  template<class charT, class traits>
334
  constexpr bool operator==(basic_string_view<charT, traits> x,
335
+ type_identity_t<basic_string_view<charT, traits>> y) noexcept;
336
  template<class charT, class traits>
337
  constexpr see below operator<=>(basic_string_view<charT, traits> x,
338
+ \itcorr type_identity_t<basic_string_view<charT,
339
+ \itcorr traits>> y) noexcept;
 
340
 
341
  // [string.view.io], inserters and extractors
342
  template<class charT, class traits>
343
  basic_ostream<charT, traits>&
344
  operator<<(basic_ostream<charT, traits>& os,
345
+ basic_string_view<charT, traits> str); // hosted
346
 
347
  // basic_string_view typedef-names
348
  using string_view = basic_string_view<char>;
349
  using u8string_view = basic_string_view<char8_t>;
350
  using u16string_view = basic_string_view<char16_t>;
 
423
 
424
  // [string.view.capacity], capacity
425
  constexpr size_type size() const noexcept;
426
  constexpr size_type length() const noexcept;
427
  constexpr size_type max_size() const noexcept;
428
+ constexpr bool empty() const noexcept;
429
 
430
  // [string.view.access], element access
431
  constexpr const_reference operator[](size_type pos) const;
432
+ constexpr const_reference at(size_type pos) const; // freestanding-deleted
433
  constexpr const_reference front() const;
434
  constexpr const_reference back() const;
435
  constexpr const_pointer data() const noexcept;
436
 
437
  // [string.view.modifiers], modifiers
438
  constexpr void remove_prefix(size_type n);
439
  constexpr void remove_suffix(size_type n);
440
  constexpr void swap(basic_string_view& s) noexcept;
441
 
442
  // [string.view.ops], string operations
443
+ constexpr size_type copy(charT* s, size_type n,
444
+ size_type pos = 0) const; // freestanding-deleted
445
 
446
+ constexpr basic_string_view substr(size_type pos = 0,
447
+ size_type n = npos) const; // freestanding-deleted
448
+ constexpr basic_string_view subview(size_type pos = 0,
449
+ size_type n = npos) const; // freestanding-deleted
450
 
451
  constexpr int compare(basic_string_view s) const noexcept;
452
+ constexpr int compare(size_type pos1, size_type n1,
453
+ basic_string_view s) const; // freestanding-deleted
454
  constexpr int compare(size_type pos1, size_type n1, basic_string_view s,
455
+ size_type pos2, size_type n2) const; // freestanding-deleted
456
  constexpr int compare(const charT* s) const;
457
+ constexpr int compare(size_type pos1, size_type n1,
458
+ const charT* s) const; // freestanding-deleted
459
+ constexpr int compare(size_type pos1, size_type n1, const charT* s,
460
+ size_type n2) const; // freestanding-deleted
461
 
462
  constexpr bool starts_with(basic_string_view x) const noexcept;
463
  constexpr bool starts_with(charT x) const noexcept;
464
  constexpr bool starts_with(const charT* x) const;
465
  constexpr bool ends_with(basic_string_view x) const noexcept;
 
523
 
524
  For a `basic_string_view str`, any operation that invalidates a pointer
525
  in the range
526
 
527
  ``` cpp
528
+ {[}str.data(), str.data() + str.size(){)}
529
  ```
530
 
531
+ invalidates pointers, iterators, and references to elements of `str`.
 
532
 
533
  The complexity of `basic_string_view` member functions is 𝑂(1) unless
534
  otherwise specified.
535
 
536
  `basic_string_view<charT, traits>` is a trivially copyable type
 
540
 
541
  ``` cpp
542
  constexpr basic_string_view() noexcept;
543
  ```
544
 
545
+ *Ensures:* *`size_`*` == 0` and *`data_`*` == nullptr`.
546
 
547
  ``` cpp
548
  constexpr basic_string_view(const charT* str);
549
  ```
550
 
551
  *Preconditions:* \[`str`, `str + traits::length(str)`) is a valid range.
552
 
553
+ *Effects:* Constructs a `basic_string_view`, initializing *data\_* with
554
+ `str` and initializing *size\_* with `traits::length(str)`.
555
 
556
  *Complexity:* 𝑂(`traits::length(str)`).
557
 
558
  ``` cpp
559
  constexpr basic_string_view(const charT* str, size_type len);
560
  ```
561
 
562
  *Preconditions:* \[`str`, `str + len`) is a valid range.
563
 
564
+ *Effects:* Constructs a `basic_string_view`, initializing *data\_* with
565
+ `str` and initializing *size\_* with `len`.
566
 
567
  ``` cpp
568
  template<class It, class End>
569
  constexpr basic_string_view(It begin, End end);
570
  ```
 
580
 
581
  - \[`begin`, `end`) is a valid range.
582
  - `It` models `contiguous_iterator`.
583
  - `End` models `sized_sentinel_for<It>`.
584
 
585
+ *Effects:* Initializes *data\_* with `to_address(begin)` and initializes
586
+ *size\_* with `end - begin`.
587
 
588
  *Throws:* When and what `end - begin` throws.
589
 
590
  ``` cpp
591
  template<class R>
 
601
  - `is_same_v<ranges::range_value_t<R>, charT>` is `true`,
602
  - `is_convertible_v<R, const charT*>` is `false`, and
603
  - `d.operator ::std::basic_string_view<charT, traits>()` is not a valid
604
  expression.
605
 
606
+ *Effects:* Initializes *data\_* with `ranges::data(r)` and *size\_* with
607
  `ranges::size(r)`.
608
 
609
  *Throws:* Any exception thrown by `ranges::data(r)` and
610
  `ranges::size(r)`.
611
 
 
648
  constexpr const_iterator cbegin() const noexcept;
649
  ```
650
 
651
  *Returns:* An iterator such that
652
 
653
+ - if `!empty()`, `addressof(*begin()) == `*`data_`*,
654
  - otherwise, an unspecified value such that \[`begin()`, `end()`) is a
655
  valid range.
656
 
657
  ``` cpp
658
  constexpr const_iterator end() const noexcept;
 
680
  ``` cpp
681
  constexpr size_type size() const noexcept;
682
  constexpr size_type length() const noexcept;
683
  ```
684
 
685
+ *Returns:* *size\_*.
686
 
687
  ``` cpp
688
  constexpr size_type max_size() const noexcept;
689
  ```
690
 
691
  *Returns:* The largest possible number of char-like objects that can be
692
  referred to by a `basic_string_view`.
693
 
694
  ``` cpp
695
+ constexpr bool empty() const noexcept;
696
  ```
697
 
698
+ *Returns:* *`size_`*` == 0`.
699
 
700
  #### Element access <a id="string.view.access">[[string.view.access]]</a>
701
 
702
  ``` cpp
703
  constexpr const_reference operator[](size_type pos) const;
704
  ```
705
 
706
+ `pos < size()` is `true`.
707
 
708
+ [*Note 1*: This precondition is stronger than the one on
709
+ `basic_string::operator[]`. — *end note*]
710
+
711
+ *Returns:* *`data_`*`[pos]`.
712
 
713
  *Throws:* Nothing.
714
 
 
 
 
 
715
  ``` cpp
716
  constexpr const_reference at(size_type pos) const;
717
  ```
718
 
719
+ *Returns:* *`data_`*`[pos]`.
720
 
721
  *Throws:* `out_of_range` if `pos >= size()`.
722
 
723
  ``` cpp
724
  constexpr const_reference front() const;
725
  ```
726
 
727
+ `empty()` is `false`.
728
 
729
+ *Returns:* *`data_`*`[0]`.
730
 
731
  *Throws:* Nothing.
732
 
733
  ``` cpp
734
  constexpr const_reference back() const;
735
  ```
736
 
737
+ `empty()` is `false`.
738
 
739
+ *Returns:* *`data_`*`[size() - 1]`.
740
 
741
  *Throws:* Nothing.
742
 
743
  ``` cpp
744
  constexpr const_pointer data() const noexcept;
745
  ```
746
 
747
+ *Returns:* *data\_*.
748
 
749
  [*Note 2*: Unlike `basic_string::data()` and *string-literal*s,
750
  `data()` can return a pointer to a buffer that is not null-terminated.
751
  Therefore it is typically a mistake to pass `data()` to a function that
752
  takes just a `const charT*` and expects a null-terminated
 
756
 
757
  ``` cpp
758
  constexpr void remove_prefix(size_type n);
759
  ```
760
 
761
+ `n <= size()` is `true`.
762
 
763
+ *Effects:* Equivalent to: *`data_`*` += n; `*`size_`*` -= n;`
764
 
765
  ``` cpp
766
  constexpr void remove_suffix(size_type n);
767
  ```
768
 
769
+ `n <= size()` is `true`.
770
 
771
+ *Effects:* Equivalent to: *`size_`*` -= n;`
772
 
773
  ``` cpp
774
  constexpr void swap(basic_string_view& s) noexcept;
775
  ```
776
 
 
794
 
795
  *Complexity:* 𝑂(`rlen`).
796
 
797
  ``` cpp
798
  constexpr basic_string_view substr(size_type pos = 0, size_type n = npos) const;
799
+ constexpr basic_string_view subview(size_type pos = 0, size_type n = npos) const;
800
  ```
801
 
802
  Let `rlen` be the smaller of `n` and `size() - pos`.
803
 
804
  *Effects:* Determines `rlen`, the effective length of the string to
 
869
 
870
  ``` cpp
871
  constexpr bool starts_with(basic_string_view x) const noexcept;
872
  ```
873
 
874
+ Let `rlen` be the smaller of `size()` and `x.size()`.
875
+
876
+ *Effects:* Equivalent to: `return basic_string_view(data(), rlen) == x;`
877
 
878
  ``` cpp
879
  constexpr bool starts_with(charT x) const noexcept;
880
  ```
881
 
 
889
 
890
  ``` cpp
891
  constexpr bool ends_with(basic_string_view x) const noexcept;
892
  ```
893
 
894
+ Let `rlen` be the smaller of `size()` and `x.size()`.
895
+
896
  *Effects:* Equivalent to:
897
 
898
  ``` cpp
899
+ return basic_string_view(data() + (size() - rlen), rlen) == x;
900
  ```
901
 
902
  ``` cpp
903
  constexpr bool ends_with(charT x) const noexcept;
904
  ```
 
955
  Let `xpos` be the lowest position, if possible, such that the following
956
  conditions hold:
957
 
958
  - `pos <= xpos`
959
  - `xpos + str.size() <= size()`
960
+ - `traits::eq(`*`data_`*`[xpos + I], str[I])` for all elements `I` of
961
+ the string referenced by `str`.
962
 
963
  *Effects:* Determines `xpos`.
964
 
965
  *Returns:* `xpos` if the function can determine such a value for `xpos`.
966
  Otherwise, returns `npos`.
 
972
  Let `xpos` be the highest position, if possible, such that the following
973
  conditions hold:
974
 
975
  - `xpos <= pos`
976
  - `xpos + str.size() <= size()`
977
+ - `traits::eq(`*`data_`*`[xpos + I], str[I])` for all elements `I` of
978
+ the string referenced by `str`.
979
 
980
  *Effects:* Determines `xpos`.
981
 
982
  *Returns:* `xpos` if the function can determine such a value for `xpos`.
983
  Otherwise, returns `npos`.
 
989
  Let `xpos` be the lowest position, if possible, such that the following
990
  conditions hold:
991
 
992
  - `pos <= xpos`
993
  - `xpos < size()`
994
+ - `traits::eq(`*`data_`*`[xpos], str[I])` for some element `I` of the
995
+ string referenced by `str`.
996
 
997
  *Effects:* Determines `xpos`.
998
 
999
  *Returns:* `xpos` if the function can determine such a value for `xpos`.
1000
  Otherwise, returns `npos`.
 
1006
  Let `xpos` be the highest position, if possible, such that the following
1007
  conditions hold:
1008
 
1009
  - `xpos <= pos`
1010
  - `xpos < size()`
1011
+ - `traits::eq(`*`data_`*`[xpos], str[I])` for some element `I` of the
1012
+ string referenced by `str`.
1013
 
1014
  *Effects:* Determines `xpos`.
1015
 
1016
  *Returns:* `xpos` if the function can determine such a value for `xpos`.
1017
  Otherwise, returns `npos`.
 
1023
  Let `xpos` be the lowest position, if possible, such that the following
1024
  conditions hold:
1025
 
1026
  - `pos <= xpos`
1027
  - `xpos < size()`
1028
+ - `traits::eq(`*`data_`*`[xpos], str[I])` for no element `I` of the
1029
+ string referenced by `str`.
1030
 
1031
  *Effects:* Determines `xpos`.
1032
 
1033
  *Returns:* `xpos` if the function can determine such a value for `xpos`.
1034
  Otherwise, returns `npos`.
 
1040
  Let `xpos` be the highest position, if possible, such that the following
1041
  conditions hold:
1042
 
1043
  - `xpos <= pos`
1044
  - `xpos < size()`
1045
+ - `traits::eq(`*`data_`*`[xpos], str[I])` for no element `I` of the
1046
+ string referenced by `str`.
1047
 
1048
  *Effects:* Determines `xpos`.
1049
 
1050
  *Returns:* `xpos` if the function can determine such a value for `xpos`.
1051
  Otherwise, returns `npos`.
1052
 
1053
  ### Non-member comparison functions <a id="string.view.comparison">[[string.view.comparison]]</a>
1054
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1055
  ``` cpp
1056
  template<class charT, class traits>
1057
  constexpr bool operator==(basic_string_view<charT, traits> lhs,
1058
+ type_identity_t<basic_string_view<charT, traits>> rhs) noexcept;
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1059
  ```
1060
 
1061
  *Returns:* `lhs.compare(rhs) == 0`.
1062
 
1063
  ``` cpp
1064
  template<class charT, class traits>
1065
  constexpr see below operator<=>(basic_string_view<charT, traits> lhs,
1066
+ \itcorr type_identity_t<basic_string_view<charT, traits>> rhs) noexcept;
1067
  ```
1068
 
1069
  Let `R` denote the type `traits::comparison_category` if that
1070
  *qualified-id* is valid and denotes a type [[temp.deduct]], otherwise
1071
  `R` is `weak_ordering`.
1072
 
1073
  *Mandates:* `R` denotes a comparison category type [[cmp.categories]].
1074
 
1075
  *Returns:* `static_cast<R>(lhs.compare(rhs) <=> 0)`.
1076
 
1077
+ [*Note 1*: The usage of `type_identity_t` as parameter ensures that an
1078
+ object of type `basic_string_view<charT, traits>` can always be compared
1079
+ with an object of a type `T` with an implicit conversion to
1080
+ `basic_string_view<charT, traits>`, and vice versa, as per
1081
+ [[over.match.oper]]. — *end note*]
1082
+
1083
  ### Inserters and extractors <a id="string.view.io">[[string.view.io]]</a>
1084
 
1085
  ``` cpp
1086
  template<class charT, class traits>
1087
  basic_ostream<charT, traits>&
 
1094
  range \[`str.begin()`, `str.end()`). Determines padding for `seq` as
1095
  described in  [[ostream.formatted.reqmts]]. Then inserts `seq` as if by
1096
  calling `os.rdbuf()->sputn(seq, n)`, where `n` is the larger of
1097
  `os.width()` and `str.size()`; then calls `os.width(0)`.
1098
 
1099
+ *Returns:* `os`.
1100
 
1101
  ### Hash support <a id="string.view.hash">[[string.view.hash]]</a>
1102
 
1103
  ``` cpp
1104
  template<> struct hash<string_view>;
 
1163
  #include <compare> // see [compare.syn]
1164
  #include <initializer_list> // see [initializer.list.syn]
1165
 
1166
  namespace std {
1167
  // [char.traits], character traits
1168
+ template<class charT> struct char_traits; // freestanding
1169
+ template<> struct char_traits<char>; // freestanding
1170
+ template<> struct char_traits<char8_t>; // freestanding
1171
+ template<> struct char_traits<char16_t>; // freestanding
1172
+ template<> struct char_traits<char32_t>; // freestanding
1173
+ template<> struct char_traits<wchar_t>; // freestanding
1174
 
1175
  // [basic.string], basic_string
1176
  template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
1177
  class basic_string;
1178
 
 
1222
  charT rhs);
1223
  template<class charT, class traits, class Allocator>
1224
  constexpr basic_string<charT, traits, Allocator>
1225
  operator+(basic_string<charT, traits, Allocator>&& lhs,
1226
  charT rhs);
1227
+ template<class charT, class traits, class Allocator>
1228
+ constexpr basic_string<charT, traits, Allocator>
1229
+ operator+(const basic_string<charT, traits, Allocator>& lhs,
1230
+ type_identity_t<basic_string_view<charT, traits>> rhs);
1231
+ template<class charT, class traits, class Allocator>
1232
+ constexpr basic_string<charT, traits, Allocator>
1233
+ operator+(basic_string<charT, traits, Allocator>&& lhs,
1234
+ type_identity_t<basic_string_view<charT, traits>> rhs);
1235
+ template<class charT, class traits, class Allocator>
1236
+ constexpr basic_string<charT, traits, Allocator>
1237
+ operator+(type_identity_t<basic_string_view<charT, traits>> lhs,
1238
+ const basic_string<charT, traits, Allocator>& rhs);
1239
+ template<class charT, class traits, class Allocator>
1240
+ constexpr basic_string<charT, traits, Allocator>
1241
+ operator+(type_identity_t<basic_string_view<charT, traits>> lhs,
1242
+ basic_string<charT, traits, Allocator>&& rhs);
1243
 
1244
  template<class charT, class traits, class Allocator>
1245
  constexpr bool
1246
  operator==(const basic_string<charT, traits, Allocator>& lhs,
1247
  const basic_string<charT, traits, Allocator>& rhs) noexcept;
 
1290
  basic_istream<charT, traits>&
1291
  getline(basic_istream<charT, traits>&& is,
1292
  basic_string<charT, traits, Allocator>& str);
1293
 
1294
  // [string.erasure], erasure
1295
+ template<class charT, class traits, class Allocator, class U = charT>
1296
  constexpr typename basic_string<charT, traits, Allocator>::size_type
1297
  erase(basic_string<charT, traits, Allocator>& c, const U& value);
1298
  template<class charT, class traits, class Allocator, class Predicate>
1299
  constexpr typename basic_string<charT, traits, Allocator>::size_type
1300
  erase_if(basic_string<charT, traits, Allocator>& c, Predicate pred);
 
1402
  public:
1403
  // types
1404
  using traits_type = traits;
1405
  using value_type = charT;
1406
  using allocator_type = Allocator;
1407
+ using size_type = allocator_traits<Allocator>::size_type;
1408
+ using difference_type = allocator_traits<Allocator>::difference_type;
1409
+ using pointer = allocator_traits<Allocator>::pointer;
1410
+ using const_pointer = allocator_traits<Allocator>::const_pointer;
1411
  using reference = value_type&;
1412
  using const_reference = const value_type&;
1413
 
1414
  using iterator = implementation-defined // type of basic_string::iterator; // see [container.requirements]
1415
  using const_iterator = implementation-defined // type of basic_string::const_iterator; // see [container.requirements]
 
1485
  template<class Operation> constexpr void resize_and_overwrite(size_type n, Operation op);
1486
  constexpr size_type capacity() const noexcept;
1487
  constexpr void reserve(size_type res_arg);
1488
  constexpr void shrink_to_fit();
1489
  constexpr void clear() noexcept;
1490
+ constexpr bool empty() const noexcept;
1491
 
1492
  // [string.access], element access
1493
  constexpr const_reference operator[](size_type pos) const;
1494
  constexpr reference operator[](size_type pos);
1495
  constexpr const_reference at(size_type n) const;
 
1651
  constexpr size_type find_last_not_of(const charT* s, size_type pos = npos) const;
1652
  constexpr size_type find_last_not_of(charT c, size_type pos = npos) const noexcept;
1653
 
1654
  constexpr basic_string substr(size_type pos = 0, size_type n = npos) const &;
1655
  constexpr basic_string substr(size_type pos = 0, size_type n = npos) &&;
1656
+ constexpr basic_string_view<charT, traits> subview(size_type pos = 0,
1657
+ size_type n = npos) const;
1658
 
1659
  template<class T>
1660
  constexpr int compare(const T& t) const noexcept(see below);
1661
  template<class T>
1662
  constexpr int compare(size_type pos1, size_type n1, const T& t) const;
 
1726
 
1727
  If any member function or operator of `basic_string` throws an
1728
  exception, that function or operator has no other effect on the
1729
  `basic_string` object.
1730
 
1731
+ Every object of type `basic_string<charT, traits, Allocator>` uses an
1732
+ object of type `Allocator` to allocate and free storage for the
1733
+ contained `charT` objects as needed. The `Allocator` object used is
1734
+ obtained as described in [[container.reqmts]]. In every specialization
 
 
 
1735
  `basic_string<charT, traits, Allocator>`, the type `traits` shall meet
1736
  the character traits requirements [[char.traits]].
1737
 
1738
  [*Note 1*: Every specialization
1739
+ `basic_string<charT, traits, Allocator>` is an allocator-aware container
1740
+ [[container.alloc.reqmts]], but does not use the allocator’s `construct`
1741
+ and `destroy` member functions [[container.requirements.pre]]. The
1742
+ program is ill-formed if `Allocator::value_type` is not the same type as
1743
+ `charT`. — *end note*]
1744
 
1745
  [*Note 2*: The program is ill-formed if `traits::char_type` is not the
1746
  same type as `charT`. — *end note*]
1747
 
1748
  References, pointers, and iterators referring to the elements of a
 
1848
  ``` cpp
1849
  constexpr basic_string(const charT* s, const Allocator& a = Allocator());
1850
  ```
1851
 
1852
  *Constraints:* `Allocator` is a type that qualifies as an
1853
+ allocator [[container.reqmts]].
1854
 
1855
  [*Note 1*: This affects class template argument
1856
  deduction. — *end note*]
1857
 
1858
  *Effects:* Equivalent to: `basic_string(s, traits::length(s), a)`.
 
1860
  ``` cpp
1861
  constexpr basic_string(size_type n, charT c, const Allocator& a = Allocator());
1862
  ```
1863
 
1864
  *Constraints:* `Allocator` is a type that qualifies as an
1865
+ allocator [[container.reqmts]].
1866
 
1867
  [*Note 2*: This affects class template argument
1868
  deduction. — *end note*]
1869
 
1870
  *Effects:* Constructs an object whose value consists of `n` copies of
 
1874
  template<class InputIterator>
1875
  constexpr basic_string(InputIterator begin, InputIterator end, const Allocator& a = Allocator());
1876
  ```
1877
 
1878
  *Constraints:* `InputIterator` is a type that qualifies as an input
1879
+ iterator [[container.reqmts]].
1880
 
1881
  *Effects:* Constructs a string from the values in the range \[`begin`,
1882
  `end`), as specified in [[sequence.reqmts]].
1883
 
1884
  ``` cpp
 
1916
  Allocator>;
1917
  ```
1918
 
1919
  *Constraints:* `InputIterator` is a type that qualifies as an input
1920
  iterator, and `Allocator` is a type that qualifies as an
1921
+ allocator [[container.reqmts]].
1922
 
1923
  ``` cpp
1924
  template<class charT,
1925
  class traits,
1926
  class Allocator = allocator<charT>>
 
1935
  const Allocator& = Allocator())
1936
  -> basic_string<charT, traits, Allocator>;
1937
  ```
1938
 
1939
  *Constraints:* `Allocator` is a type that qualifies as an
1940
+ allocator [[container.reqmts]].
1941
 
1942
  ``` cpp
1943
  constexpr basic_string& operator=(const basic_string& str);
1944
  ```
1945
 
 
1952
  constexpr basic_string& operator=(basic_string&& str)
1953
  noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
1954
  allocator_traits<Allocator>::is_always_equal::value);
1955
  ```
1956
 
1957
+ *Effects:* Move assigns as a sequence container [[sequence.reqmts]],
1958
+ except that iterators, pointers and references may be invalidated.
 
1959
 
1960
  *Returns:* `*this`.
1961
 
1962
  ``` cpp
1963
  template<class T>
 
2123
  constexpr void reserve(size_type res_arg);
2124
  ```
2125
 
2126
  *Effects:* A directive that informs a `basic_string` of a planned change
2127
  in size, so that the storage allocation can be managed accordingly.
2128
+ Following a call to `reserve`, `capacity()` is greater or equal to the
2129
+ argument of `reserve` if reallocation happens; and equal to the previous
2130
+ value of `capacity()` otherwise. Reallocation happens at this point if
2131
+ and only if the current capacity is less than the argument of `reserve`.
2132
 
2133
  *Throws:* `length_error` if `res_arg > max_size()` or any exceptions
2134
  thrown by `allocator_traits` `<Allocator>::allocate`.
2135
 
2136
  ``` cpp
 
2161
  ```
2162
 
2163
  *Effects:* Equivalent to: `erase(begin(), end());`
2164
 
2165
  ``` cpp
2166
+ constexpr bool empty() const noexcept;
2167
  ```
2168
 
2169
  *Effects:* Equivalent to: `return size() == 0;`
2170
 
2171
  #### Element access <a id="string.access">[[string.access]]</a>
 
2173
  ``` cpp
2174
  constexpr const_reference operator[](size_type pos) const;
2175
  constexpr reference operator[](size_type pos);
2176
  ```
2177
 
2178
+ `pos <= size()` is `true`.
2179
 
2180
  *Returns:* `*(begin() + pos)` if `pos < size()`. Otherwise, returns a
2181
  reference to an object of type `charT` with value `charT()`, where
2182
  modifying the object to any value other than `charT()` leads to
2183
  undefined behavior.
 
2198
  ``` cpp
2199
  constexpr const charT& front() const;
2200
  constexpr charT& front();
2201
  ```
2202
 
2203
+ `empty()` is `false`.
2204
 
2205
  *Effects:* Equivalent to: `return operator[](0);`
2206
 
2207
  ``` cpp
2208
  constexpr const charT& back() const;
2209
  constexpr charT& back();
2210
  ```
2211
 
2212
+ `empty()` is `false`.
2213
 
2214
  *Effects:* Equivalent to: `return operator[](size() - 1);`
2215
 
2216
  #### Modifiers <a id="string.modifiers">[[string.modifiers]]</a>
2217
 
 
2341
  template<class InputIterator>
2342
  constexpr basic_string& append(InputIterator first, InputIterator last);
2343
  ```
2344
 
2345
  *Constraints:* `InputIterator` is a type that qualifies as an input
2346
+ iterator [[container.reqmts]].
2347
 
2348
  *Effects:* Equivalent to:
2349
  `return append(basic_string(first, last, get_allocator()));`
2350
 
2351
  ``` cpp
 
2469
  template<class InputIterator>
2470
  constexpr basic_string& assign(InputIterator first, InputIterator last);
2471
  ```
2472
 
2473
  *Constraints:* `InputIterator` is a type that qualifies as an input
2474
+ iterator [[container.reqmts]].
2475
 
2476
  *Effects:* Equivalent to:
2477
  `return assign(basic_string(first, last, get_allocator()));`
2478
 
2479
  ``` cpp
 
2569
  ```
2570
 
2571
  *Effects:* Inserts `n` copies of `c` before the character at position
2572
  `pos` if `pos < size()`, or otherwise at the end of the string.
2573
 
2574
+ *Returns:* `*this`.
2575
 
2576
  *Throws:*
2577
 
2578
  - `out_of_range` if `pos > size()`,
2579
  - `length_error` if `n > max_size() - size()`, or
 
2604
  template<class InputIterator>
2605
  constexpr iterator insert(const_iterator p, InputIterator first, InputIterator last);
2606
  ```
2607
 
2608
  *Constraints:* `InputIterator` is a type that qualifies as an input
2609
+ iterator [[container.reqmts]].
2610
 
2611
  *Preconditions:* `p` is a valid iterator on `*this`.
2612
 
2613
  *Effects:* Equivalent to
2614
  `insert(p - begin(), basic_string(first, last, get_allocator()))`.
 
2668
  ```
2669
 
2670
  *Preconditions:* `first` and `last` are valid iterators on `*this`.
2671
  \[`first`, `last`) is a valid range.
2672
 
2673
+ *Effects:* Removes the characters in the range \[`first`, `last`).
2674
 
2675
  *Returns:* An iterator which points to the element pointed to by `last`
2676
  prior to the other elements being erased. If no such element exists,
2677
  `end()` is returned.
2678
 
 
2680
 
2681
  ``` cpp
2682
  constexpr void pop_back();
2683
  ```
2684
 
2685
+ `empty()` is `false`.
2686
 
2687
  *Effects:* Equivalent to `erase(end() - 1)`.
2688
 
2689
  *Throws:* Nothing.
2690
 
 
2786
  *Returns:* `*this`.
2787
 
2788
  *Throws:*
2789
 
2790
  - `out_of_range` if `pos1 > size()`,
2791
+ - `length_error` if the length of the resulting string would exceed
2792
+ `max_size()`, or
2793
  - any exceptions thrown by `allocator_traits<Allocator>::allocate.`
2794
 
2795
  ``` cpp
2796
  constexpr basic_string& replace(const_iterator i1, const_iterator i2, const basic_string& str);
2797
  ```
 
2846
  constexpr basic_string& replace(const_iterator i1, const_iterator i2,
2847
  InputIterator j1, InputIterator j2);
2848
  ```
2849
 
2850
  *Constraints:* `InputIterator` is a type that qualifies as an input
2851
+ iterator [[container.reqmts]].
2852
 
2853
  *Effects:* Equivalent to:
2854
  `return replace(i1, i2, basic_string(j1, j2, get_allocator()));`
2855
 
2856
  ``` cpp
 
3026
  ```
3027
 
3028
  *Effects:* Equivalent to:
3029
  `return basic_string(std::move(*this), pos, n);`
3030
 
3031
+ ``` cpp
3032
+ constexpr basic_string_view<charT, traits> subview(size_type pos = 0, size_type n = npos) const;
3033
+ ```
3034
+
3035
+ *Effects:* Equivalent to:
3036
+ `return basic_string_view<charT, traits>(*this).subview(pos, n);`
3037
+
3038
  ##### `basic_string::compare` <a id="string.compare">[[string.compare]]</a>
3039
 
3040
  ``` cpp
3041
  template<class T>
3042
  constexpr int compare(const T& t) const noexcept(see below);
 
3320
  ``` cpp
3321
  lhs.push_back(rhs);
3322
  return std::move(lhs);
3323
  ```
3324
 
3325
+ ``` cpp
3326
+ template<class charT, class traits, class Allocator>
3327
+ constexpr basic_string<charT, traits, Allocator>
3328
+ operator+(const basic_string<charT, traits, Allocator>& lhs,
3329
+ type_identity_t<basic_string_view<charT, traits>> rhs);
3330
+ ```
3331
+
3332
+ Equivalent to:
3333
+
3334
+ ``` cpp
3335
+ basic_string<charT, traits, Allocator> r = lhs;
3336
+ r.append(rhs);
3337
+ return r;
3338
+ ```
3339
+
3340
+ ``` cpp
3341
+ template<class charT, class traits, class Allocator>
3342
+ constexpr basic_string<charT, traits, Allocator>
3343
+ operator+(basic_string<charT, traits, Allocator>&& lhs,
3344
+ type_identity_t<basic_string_view<charT, traits>> rhs);
3345
+ ```
3346
+
3347
+ Equivalent to:
3348
+
3349
+ ``` cpp
3350
+ lhs.append(rhs);
3351
+ return std::move(lhs);
3352
+ ```
3353
+
3354
+ ``` cpp
3355
+ template<class charT, class traits, class Allocator>
3356
+ constexpr basic_string<charT, traits, Allocator>
3357
+ operator+(type_identity_t<basic_string_view<charT, traits>> lhs,
3358
+ const basic_string<charT, traits, Allocator>& rhs);
3359
+ ```
3360
+
3361
+ Equivalent to:
3362
+
3363
+ ``` cpp
3364
+ basic_string<charT, traits, Allocator> r = rhs;
3365
+ r.insert(0, lhs);
3366
+ return r;
3367
+ ```
3368
+
3369
+ ``` cpp
3370
+ template<class charT, class traits, class Allocator>
3371
+ constexpr basic_string<charT, traits, Allocator>
3372
+ operator+(type_identity_t<basic_string_view<charT, traits>> lhs,
3373
+ basic_string<charT, traits, Allocator>&& rhs);
3374
+ ```
3375
+
3376
+ Equivalent to:
3377
+
3378
+ ``` cpp
3379
+ rhs.insert(0, lhs);
3380
+ return std::move(rhs);
3381
+ ```
3382
+
3383
+ [*Note 1*: Using a specialization of `type_identity_t` as a parameter
3384
+ type ensures that an object of type
3385
+ `basic_string<charT, traits, Allocator>` can be concatenated with an
3386
+ object of a type `T` having an implicit conversion to
3387
+ `basic_string_view<charT, traits>` [[over.match.oper]]. — *end note*]
3388
+
3389
  #### Non-member comparison operator functions <a id="string.cmp">[[string.cmp]]</a>
3390
 
3391
  ``` cpp
3392
  template<class charT, class traits, class Allocator>
3393
  constexpr bool
 
3512
  *Returns:* `getline(is, str, is.widen(’\n’))`.
3513
 
3514
  #### Erasure <a id="string.erasure">[[string.erasure]]</a>
3515
 
3516
  ``` cpp
3517
+ template<class charT, class traits, class Allocator, class U = charT>
3518
  constexpr typename basic_string<charT, traits, Allocator>::size_type
3519
  erase(basic_string<charT, traits, Allocator>& c, const U& value);
3520
  ```
3521
 
3522
  *Effects:* Equivalent to:
 
3602
  string to_string(float val);
3603
  string to_string(double val);
3604
  string to_string(long double val);
3605
  ```
3606
 
3607
+ *Returns:* `format("{}", val)`.
 
 
 
 
 
3608
 
3609
  ``` cpp
3610
  int stoi(const wstring& str, size_t* idx = nullptr, int base = 10);
3611
  long stol(const wstring& str, size_t* idx = nullptr, int base = 10);
3612
  unsigned long stoul(const wstring& str, size_t* idx = nullptr, int base = 10);
 
3661
  wstring to_wstring(float val);
3662
  wstring to_wstring(double val);
3663
  wstring to_wstring(long double val);
3664
  ```
3665
 
3666
+ *Returns:* `format(L"{}", val)`.
 
 
 
 
 
3667
 
3668
  ### Hash support <a id="basic.string.hash">[[basic.string.hash]]</a>
3669
 
3670
  ``` cpp
3671
  template<class A> struct hash<basic_string<char, char_traits<char>, A>>;
 
3716
  to numbers and string literal suffixes apply to character array
3717
  literals. — *end note*]
3718
 
3719
  ## Null-terminated sequence utilities <a id="c.strings">[[c.strings]]</a>
3720
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3721
  ### Header `<cstring>` synopsis <a id="cstring.syn">[[cstring.syn]]</a>
3722
 
3723
  ``` cpp
3724
+ #define __STDC_VERSION_STRING_H__ 202311L
3725
+
3726
  namespace std {
3727
+ using size_t = see [support.types.layout]; // freestanding
3728
 
3729
+ void* memcpy(void* s1, const void* s2, size_t n); // freestanding
3730
+ void* memccpy(void* s1, const void* s2, int c, size_t n); // freestanding
3731
+ void* memmove(void* s1, const void* s2, size_t n); // freestanding
3732
+ char* strcpy(char* s1, const char* s2); // freestanding
3733
+ char* strncpy(char* s1, const char* s2, size_t n); // freestanding
3734
+ char* strdup(const char* s);
3735
+ char* strndup(const char* s, size_t size);
3736
+ char* strcat(char* s1, const char* s2); // freestanding
3737
+ char* strncat(char* s1, const char* s2, size_t n); // freestanding
3738
+ int memcmp(const void* s1, const void* s2, size_t n); // freestanding
3739
+ int strcmp(const char* s1, const char* s2); // freestanding
3740
  int strcoll(const char* s1, const char* s2);
3741
+ int strncmp(const char* s1, const char* s2, size_t n); // freestanding
3742
  size_t strxfrm(char* s1, const char* s2, size_t n);
3743
+ const void* memchr(const void* s, int c, size_t n); // freestanding; see [library.c]
3744
+ void* memchr(void* s, int c, size_t n); // freestanding; see [library.c]
3745
+ const char* strchr(const char* s, int c); // freestanding; see [library.c]
3746
+ char* strchr(char* s, int c); // freestanding; see [library.c]
3747
+ size_t strcspn(const char* s1, const char* s2); // freestanding
3748
+ const char* strpbrk(const char* s1, const char* s2); // freestanding; see [library.c]
3749
+ char* strpbrk(char* s1, const char* s2); // freestanding; see [library.c]
3750
+ const char* strrchr(const char* s, int c); // freestanding; see [library.c]
3751
+ char* strrchr(char* s, int c); // freestanding; see [library.c]
3752
+ size_t strspn(const char* s1, const char* s2); // freestanding
3753
+ const char* strstr(const char* s1, const char* s2); // freestanding; see [library.c]
3754
+ char* strstr(char* s1, const char* s2); // freestanding; see [library.c]
3755
  char* strtok(char* s1, const char* s2);
3756
+ void* memset(void* s, int c, size_t n); // freestanding
3757
+ void* memset_explicit(void* s, int c, size_t n); // freestanding
3758
  char* strerror(int errnum);
3759
+ size_t strlen(const char* s); // freestanding
3760
  }
3761
 
3762
+ #define NULL see [support.types.nullptr] // freestanding
3763
  ```
3764
 
3765
  The contents and meaning of the header `<cstring>` are the same as the C
3766
  standard library header `<string.h>`.
3767
 
3768
  The functions `strerror` and `strtok` are not required to avoid data
3769
  races [[res.on.data.races]].
3770
 
3771
  The functions `memcpy` and `memmove` are signal-safe [[support.signal]].
3772
+ Each of these functions implicitly creates objects [[intro.object]] in
3773
+ the destination region of storage immediately prior to copying the
3774
+ sequence of characters to the destination. Each of these functions
3775
+ returns a pointer to a suitable created object, if any, otherwise the
3776
+ value of the first parameter.
3777
 
3778
  [*Note 1*: The functions `strchr`, `strpbrk`, `strrchr`, `strstr`, and
3779
  `memchr`, have different signatures in this document, but they have the
3780
  same behavior as in the C standard library [[library.c]]. — *end note*]
3781
 
3782
+ See also: ISO C 7.26
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3783
 
3784
  <!-- Link reference definitions -->
3785
  [basic.indet]: basic.md#basic.indet
3786
  [basic.string]: #basic.string
3787
  [basic.string.general]: #basic.string.general
3788
  [basic.string.hash]: #basic.string.hash
3789
  [basic.string.literals]: #basic.string.literals
 
3790
  [c.strings]: #c.strings
 
3791
  [char.traits]: #char.traits
3792
  [char.traits.general]: #char.traits.general
3793
  [char.traits.req]: #char.traits.req
3794
  [char.traits.require]: #char.traits.require
3795
  [char.traits.specializations]: #char.traits.specializations
 
3799
  [char.traits.specializations.char8.t]: #char.traits.specializations.char8.t
3800
  [char.traits.specializations.general]: #char.traits.specializations.general
3801
  [char.traits.specializations.wchar.t]: #char.traits.specializations.wchar.t
3802
  [char.traits.typedefs]: #char.traits.typedefs
3803
  [cmp.categories]: support.md#cmp.categories
3804
+ [container.alloc.reqmts]: containers.md#container.alloc.reqmts
3805
  [container.reqmts]: containers.md#container.reqmts
3806
  [container.requirements]: containers.md#container.requirements
3807
+ [container.requirements.pre]: containers.md#container.requirements.pre
3808
  [cpp17.copyassignable]: #cpp17.copyassignable
3809
  [cpp17.copyconstructible]: #cpp17.copyconstructible
3810
  [cpp17.defaultconstructible]: #cpp17.defaultconstructible
3811
  [cpp17.destructible]: #cpp17.destructible
3812
  [cstring.syn]: #cstring.syn
 
 
 
3813
  [defns.character.container]: intro.md#defns.character.container
3814
  [input.output]: input.md#input.output
3815
  [intro.object]: basic.md#intro.object
3816
  [iostream.forward]: input.md#iostream.forward
3817
  [iostreams.limits.pos]: input.md#iostreams.limits.pos
 
3821
  [iterator.concept.winc]: iterators.md#iterator.concept.winc
3822
  [iterator.range]: iterators.md#iterator.range
3823
  [iterator.requirements.general]: iterators.md#iterator.requirements.general
3824
  [library.c]: library.md#library.c
3825
  [ostream.formatted.reqmts]: input.md#ostream.formatted.reqmts
3826
+ [over.match.oper]: over.md#over.match.oper
3827
  [random.access.iterators]: iterators.md#random.access.iterators
3828
  [res.on.data.races]: library.md#res.on.data.races
3829
  [sequence.reqmts]: containers.md#sequence.reqmts
3830
  [string.access]: #string.access
3831
  [string.accessors]: #string.accessors
 
3862
  [string.view]: #string.view
3863
  [string.view.access]: #string.view.access
3864
  [string.view.capacity]: #string.view.capacity
3865
  [string.view.compare]: #string.view.compare
3866
  [string.view.comparison]: #string.view.comparison
 
3867
  [string.view.cons]: #string.view.cons
3868
  [string.view.deduct]: #string.view.deduct
3869
  [string.view.find]: #string.view.find
3870
  [string.view.general]: #string.view.general
3871
  [string.view.hash]: #string.view.hash