Working Draft, Standard for Programming Language C++ (N4713, 2017 year) - page 24
template<class InputIterator>
iterator insert(const_iterator p, InputIterator first, InputIterator last);
23
Requires: p is a valid iterator on *this. [first, last) is a valid range.
24
Effects: Equivalent to insert(p - begin(), basic_string(first, last, get_allocator())).
25
Returns: An iterator which refers to the copy of the first inserted character, or p if first == last.
iterator insert(const_iterator p, initializer_list<charT> il);
26
Effects: As if by insert(p, il.begin(), il.end()).
27
Returns: An iterator which refers to the copy of the first inserted character, or p if i1 is empty.
24.3.2.6.5
basic_string::erase
[string.erase]
basic_string& erase(size_type pos = 0, size_type n = npos);
1
Throws: out_of_range if pos > size().
2
Effects: Determines the effective length xlen of the string to be removed as the smaller of n and size()
- pos.
3
The function then replaces the string controlled by *this with a string of length size() - xlen whose
first pos elements are a copy of the initial elements of the original string controlled by *this, and whose
remaining elements are a copy of the elements of the original string controlled by *this beginning at
position pos + xlen.
4
Returns: *this.
iterator erase(const_iterator p);
5
Throws: Nothing.
6
Effects: Removes the character referred to by p.
7
Returns: An iterator which points to the element immediately following p prior to the element being
erased. If no such element exists, end() is returned.
iterator erase(const_iterator first, const_iterator last);
8
Requires: first and last are valid iterators on *this, defining a range [first, last).
9
Throws: Nothing.
10
Effects: Removes the characters in the range [first, last).
11
Returns: An iterator which points to the element pointed to by last prior to the other elements being
erased. If no such element exists, end() is returned.
void pop_back();
12
Requires: !empty().
13
Throws: Nothing.
14
Effects: Equivalent to erase(size() - 1, 1).
24.3.2.6.6
basic_string::replace
[string.replace]
basic_string& replace(size_type pos1, size_type n1, const basic_string& str);
1
Effects: Equivalent to: return replace(pos1, n1, str.data(), str.size());
basic_string& replace(size_type pos1, size_type n1, const basic_string& str,
size_type pos2, size_type n2 = npos);
2
Throws: out_of_range if pos1 > size() or pos2 > str.size().
3
Effects: Determines the effective length rlen of the string to be inserted as the smaller of n2 and
str.size() - pos2 and calls replace(pos1, n1, str.data() + pos2, rlen).
4
Returns: *this.
§ 24.3.2.6.6
682
basic_string& replace(size_type pos1, size_type n1,
basic_string_view<charT, traits> sv);
5
Effects: Equivalent to: return replace(pos1, n1, sv.data(), sv.size());
template<class T>
basic_string& replace(size_type pos1, size_type n1, const T& t,
size_type pos2, size_type n2 = npos);
6
Throws: out_of_range if pos1 > size() or pos2 > sv.size().
7
Effects: Creates a variable, sv, as if by basic_string_view<charT, traits> sv = t. Determines
the effective length rlen of the string to be inserted as the smaller of n2 and sv.size() - pos2 and
calls replace(pos1, n1, sv.data() + pos2, rlen).
8
Remarks: This function shall not participate in overload resolution unless is_convertible_v<const T&,
basic_string_view<charT, traits>> is true and is_convertible_v<const T&, const charT*>
is false.
9
Returns: *this.
basic_string& replace(size_type pos1, size_type n1, const charT* s, size_type n2);
10
Requires: s points to an array of at least n2 elements of charT.
11
Throws: out_of_range if pos1 > size() or length_error if the length of the resulting string would
exceed max_size() (see below).
12
Effects: Determines the effective length xlen of the string to be removed as the smaller of n1
and size() - pos1. If size() - xlen >= max_size() - n2 throws length_error. Otherwise, the
function replaces the string controlled by *this with a string of length size() - xlen + n2 whose
first pos1 elements are a copy of the initial elements of the original string controlled by *this, whose
next n2 elements are a copy of the initial n2 elements of s, and whose remaining elements are a copy of
the elements of the original string controlled by *this beginning at position pos + xlen.
13
Returns: *this.
basic_string& replace(size_type pos, size_type n, const charT* s);
14
Requires: s points to an array of at least traits::length(s) + 1 elements of charT.
15
Effects: Equivalent to: return replace(pos, n, s, traits::length(s));
basic_string& replace(size_type pos1, size_type n1, size_type n2, charT c);
16
Effects: Equivalent to: return replace(pos1, n1, basic_string(n2, c));
basic_string& replace(const_iterator i1, const_iterator i2, const basic_string& str);
17
Requires: [begin(), i1) and [i1, i2) are valid ranges.
18
Effects: Calls replace(i1 - begin(), i2 - i1, str).
19
Returns: *this.
basic_string& replace(const_iterator i1, const_iterator i2, basic_string_view<charT, traits> sv);
20
Requires: [begin(), i1) and [i1, i2) are valid ranges.
21
Effects: Calls replace(i1 - begin(), i2 - i1, sv).
22
Returns: *this.
basic_string& replace(const_iterator i1, const_iterator i2, const charT* s, size_type n);
23
Requires: [begin(), i1) and [i1, i2) are valid ranges and s points to an array of at least n elements
of charT.
24
Effects: Calls replace(i1 - begin(), i2 - i1, s, n).
25
Returns: *this.
basic_string& replace(const_iterator i1, const_iterator i2, const charT* s);
26
Requires: [begin(), i1) and [i1, i2) are valid ranges and s points to an array of at least traits::
length(s) + 1 elements of charT.
§ 24.3.2.6.6
683
27
Effects: Calls replace(i1 - begin(), i2 - i1, s, traits::length(s)).
28
Returns: *this.
basic_string& replace(const_iterator i1, const_iterator i2, size_type n, charT c);
29
Requires: [begin(), i1) and [i1, i2) are valid ranges.
30
Effects: Calls replace(i1 - begin(), i2 - i1, basic_string(n, c)).
31
Returns: *this.
template<class InputIterator>
basic_string& replace(const_iterator i1, const_iterator i2, InputIterator j1, InputIterator j2);
32
Requires: [begin(), i1), [i1, i2) and [j1, j2) are valid ranges.
33
Effects: Calls replace(i1 - begin(), i2 - i1, basic_string(j1, j2, get_allocator())).
34
Returns: *this.
basic_string& replace(const_iterator i1, const_iterator i2, initializer_list<charT> il);
35
Requires: [begin(), i1) and [i1, i2) are valid ranges.
36
Effects: Calls replace(i1 - begin(), i2 - i1, il.begin(), il.size()).
37
Returns: *this.
24.3.2.6.7
basic_string::copy
[string.copy]
size_type copy(charT* s, size_type n, size_type pos = 0) const;
1
Let rlen be the smaller of n and size() - pos.
2
Throws: out_of_range if pos > size().
3
Requires: [s, s + rlen) is a valid range.
4
Effects: Equivalent to traits::copy(s, data() + pos, rlen). [ Note: This does not terminate s
with a null object.
— end note ]
5
Returns: rlen.
24.3.2.6.8
basic_string::swap
[string.swap]
void swap(basic_string& s)
noexcept(allocator_traits<Allocator>::propagate_on_container_swap::value ||
allocator_traits<Allocator>::is_always_equal::value);
1
Postconditions: *this contains the same sequence of characters that was in s, s contains the same
sequence of characters that was in *this.
2
Throws: Nothing.
3
Complexity: Constant time.
24.3.2.7
basic_string string operations
[string.ops]
24.3.2.7.1
basic_string accessors
[string.accessors]
const charT* c_str() const noexcept;
const charT* data() const noexcept;
1
Returns: A pointer p such that p + i == &operator[](i) for each i in [0, size()].
2
Complexity: Constant time.
3
Requires: The program shall not alter any of the values stored in the character array.
charT* data() noexcept;
4
Returns: A pointer p such that p + i == &operator[](i) for each i in [0, size()].
5
Complexity: Constant time.
6
Requires: The program shall not alter the value stored at p + size().
§ 24.3.2.7.1
684
operator basic_string_view<charT, traits>() const noexcept;
7
Effects: Equivalent to: return basic_string_view<charT, traits>(data(), size());
allocator_type get_allocator() const noexcept;
8
Returns: A copy of the Allocator object used to construct the string or, if that allocator has been
replaced, a copy of the most recent replacement.
24.3.2.7.2
basic_string::find
[string.find]
size_type find(basic_string_view<charT, traits> sv, size_type pos = 0) const noexcept;
1
Effects: Determines the lowest position xpos, if possible, such that both of the following conditions
hold:
(1.1)
—
pos <= xpos and xpos + sv.size() <= size();
(1.2)
—
traits::eq(at(xpos + I), sv.at(I)) for all elements I of the data referenced by sv.
2
Returns: xpos if the function can determine such a value for xpos. Otherwise, returns npos.
size_type find(const basic_string& str, size_type pos = 0) const noexcept;
3
Effects: Equivalent to: return find(basic_string_view<charT, traits>(str), pos);
size_type find(const charT* s, size_type pos, size_type n) const;
4
Returns: find(basic_string_view<charT, traits>(s, n), pos).
size_type find(const charT* s, size_type pos = 0) const;
5
Requires: s points to an array of at least traits::length(s) + 1 elements of charT.
6
Returns: find(basic_string_view<charT, traits>(s), pos).
size_type find(charT c, size_type pos = 0) const;
7
Returns: find(basic_string(1, c), pos).
24.3.2.7.3
basic_string::rfind
[string.rfind]
size_type rfind(basic_string_view<charT, traits> sv, size_type pos = npos) const noexcept;
1
Effects: Determines the highest position xpos, if possible, such that both of the following conditions
hold:
(1.1)
—
xpos <= pos and xpos + sv.size() <= size();
(1.2)
—
traits::eq(at(xpos + I), sv.at(I)) for all elements I of the data referenced by sv.
2
Returns: xpos if the function can determine such a value for xpos. Otherwise, returns npos.
size_type rfind(const basic_string& str, size_type pos = npos) const noexcept;
3
Effects: Equivalent to: return rfind(basic_string_view<charT, traits>(str), pos);
size_type rfind(const charT* s, size_type pos, size_type n) const;
4
Returns: rfind(basic_string_view<charT, traits>(s, n), pos).
size_type rfind(const charT* s, size_type pos = npos) const;
5
Requires: s points to an array of at least traits::length(s) + 1 elements of charT.
6
Returns: rfind(basic_string_view<charT, traits>(s), pos).
size_type rfind(charT c, size_type pos = npos) const;
7
Returns: rfind(basic_string(1, c), pos).
24.3.2.7.4
basic_string::find_first_of
[string.find.first.of]
size_type find_first_of(basic_string_view<charT, traits> sv, size_type pos = 0) const noexcept;
1
Effects: Determines the lowest position xpos, if possible, such that both of the following conditions
hold:
§ 24.3.2.7.4
685
(1.1)
—
pos <= xpos and xpos < size();
(1.2)
—
traits::eq(at(xpos), sv.at(I)) for some element I of the data referenced by sv.
2
Returns: xpos if the function can determine such a value for xpos. Otherwise, returns npos.
size_type find_first_of(const basic_string& str, size_type pos = 0) const noexcept;
3
Effects: Equivalent to: return find_first_of(basic_string_view<charT, traits>(str), pos);
size_type find_first_of(const charT* s, size_type pos, size_type n) const;
4
Returns: find_first_of(basic_string_view<charT, traits>(s, n), pos).
size_type find_first_of(const charT* s, size_type pos = 0) const;
5
Requires: s points to an array of at least traits::length(s) + 1 elements of charT.
6
Returns: find_first_of(basic_string_view<charT, traits>(s), pos).
size_type find_first_of(charT c, size_type pos = 0) const;
7
Returns: find_first_of(basic_string(1, c), pos).
24.3.2.7.5
basic_string::find_last_of
[string.find.last.of]
size_type find_last_of(basic_string_view<charT, traits> sv, size_type pos = npos) const noexcept;
1
Effects: Determines the highest position xpos, if possible, such that both of the following conditions
hold:
(1.1)
—
xpos <= pos and xpos < size();
(1.2)
—
traits::eq(at(xpos), sv.at(I)) for some element I of the data referenced by sv.
2
Returns: xpos if the function can determine such a value for xpos. Otherwise, returns npos.
size_type find_last_of(const basic_string& str, size_type pos = npos) const noexcept;
3
Effects: Equivalent to: return find_last_of(basic_string_view<charT, traits>(str), pos);
size_type find_last_of(const charT* s, size_type pos, size_type n) const;
4
Returns: find_last_of(basic_string_view<charT, traits>(s, n), pos).
size_type find_last_of(const charT* s, size_type pos = npos) const;
5
Requires: s points to an array of at least traits::length(s) + 1 elements of charT.
6
Returns: find_last_of(basic_string_view<charT, traits>(s), pos).
size_type find_last_of(charT c, size_type pos = npos) const;
7
Returns: find_last_of(basic_string(1, c), pos).
24.3.2.7.6
basic_string::find_first_not_of
[string.find.first.not.of]
size_type find_first_not_of(basic_string_view<charT, traits> sv, size_type pos = 0) const noexcept;
1
Effects: Determines the lowest position xpos, if possible, such that both of the following conditions
hold:
(1.1)
—
pos <= xpos and xpos < size();
(1.2)
—
traits::eq(at(xpos), sv.at(I)) for no element I of the data referenced by sv.
2
Returns: xpos if the function can determine such a value for xpos. Otherwise, returns npos.
size_type find_first_not_of(const basic_string& str, size_type pos = 0) const noexcept;
3
Effects: Equivalent to:
return find_first_not_of(basic_string_view<charT, traits>(str), pos);
size_type find_first_not_of(const charT* s, size_type pos, size_type n) const;
4
Returns: find_first_not_of(basic_string_view<charT, traits>(s, n), pos).
§ 24.3.2.7.6
686
size_type find_first_not_of(const charT* s, size_type pos = 0) const;
5
Requires: s points to an array of at least traits::length(s) + 1 elements of charT.
6
Returns: find_first_not_of(basic_string_view<charT, traits>(s), pos).
size_type find_first_not_of(charT c, size_type pos = 0) const;
7
Returns: find_first_not_of(basic_string(1, c), pos).
24.3.2.7.7
basic_string::find_last_not_of
[string.find.last.not.of]
size_type find_last_not_of(basic_string_view<charT, traits> sv,
size_type pos = npos) const noexcept;
1
Effects: Determines the highest position xpos, if possible, such that both of the following conditions
hold:
(1.1)
—
xpos <= pos and xpos < size();
(1.2)
—
traits::eq(at(xpos), sv.at(I)) for no element I of the data referenced by sv.
2
Returns: xpos if the function can determine such a value for xpos. Otherwise, returns npos.
size_type find_last_not_of(const basic_string& str, size_type pos = npos) const noexcept;
3
Effects: Equivalent to:
return find_last_not_of(basic_string_view<charT, traits>(str), pos);
size_type find_last_not_of(const charT* s, size_type pos, size_type n) const;
4
Returns: find_last_not_of(basic_string_view<charT, traits>(s, n), pos).
size_type find_last_not_of(const charT* s, size_type pos = npos) const;
5
Requires: s points to an array of at least traits::length(s) + 1 elements of charT.
6
Returns: find_last_not_of(basic_string_view<charT, traits>(s), pos).
size_type find_last_not_of(charT c, size_type pos = npos) const;
7
Returns: find_last_not_of(basic_string(1, c), pos).
24.3.2.7.8
basic_string::substr
[string.substr]
basic_string substr(size_type pos = 0, size_type n = npos) const;
1
Throws: out_of_range if pos > size().
2
Effects: Determines the effective length rlen of the string to copy as the smaller of n and size() -
pos.
3
Returns: basic_string(data()+pos, rlen).
24.3.2.7.9
basic_string::compare
[string.compare]
int compare(basic_string_view<charT, traits> sv) const noexcept;
1
Effects: Determines the effective length rlen of the strings to compare as the smaller of size()
and sv.size(). The function then compares the two strings by calling traits::compare(data(),
sv.data(), rlen).
2
Returns: The nonzero result if the result of the comparison is nonzero. Otherwise, returns a value as
indicated in Table 63.
Table 63 — compare() results
Condition
Return Value
size() < sv.size()
< 0
size() == sv.size()
0
size() > sv.size()
> 0
§ 24.3.2.7.9
687
int compare(size_type pos1, size_type n1, basic_string_view<charT, traits> sv) const;
3
Effects: Equivalent to:
return basic_string_view<charT, traits>(data(), size()).substr(pos1, n1).compare(sv);
template<class T>
int compare(size_type pos1, size_type n1, const T& t, size_type pos2, size_type n2 = npos) const;
4
Effects: Equivalent to:
basic_string_view<charT, traits> sv = t;
return basic_string_view<charT, traits>(
data(), size()).substr(pos1, n1).compare(sv.substr(pos2, n2));
5
Remarks: This function shall not participate in overload resolution unless is_convertible_v<const T&,
basic_string_view<charT, traits>> is true and is_convertible_v<const T&, const charT*>
is false.
int
compare(const basic_string& str) const noexcept;
6
Effects: Equivalent to: return compare(basic_string_view<charT, traits>(str));
int
compare(size_type pos1, size_type n1, const basic_string& str) const;
7
Effects: Equivalent to: return compare(pos1, n1, basic_string_view<charT, traits>(str));
int
compare(size_type pos1, size_type n1, const basic_string& str,
size_type pos2, size_type n2 = npos) const;
8
Effects: Equivalent to:
return compare(pos1, n1, basic_string_view<charT, traits>(str), pos2, n2);
int
compare(const charT* s) const;
9
Returns: compare(basic_string(s)).
int
compare(size_type pos, size_type n1, const charT* s) const;
10
Returns: basic_string(*this, pos, n1).compare(basic_string(s)).
int
compare(size_type pos, size_type n1, const charT* s, size_type n2) const;
11
Returns: basic_string(*this, pos, n1).compare(basic_string(s, n2)).
24.3.2.7.10
basic_string::starts_with
[string.starts.with]
bool starts_with(basic_string_view<charT, traits> x) const noexcept;
bool starts_with(charT x) const noexcept;
bool starts_with(const charT* x) const;
1
Effects: Equivalent to:
return basic_string_view<charT, traits>(data(), size()).starts_with(x);
24.3.2.7.11
basic_string::ends_with
[string.ends.with]
bool ends_with(basic_string_view<charT, traits> x) const noexcept;
bool ends_with(charT x) const noexcept;
bool ends_with(const charT* x) const;
1
Effects: Equivalent to:
return basic_string_view<charT, traits>(data(), size()).ends_with(x);
24.3.3
basic_string non-member functions
[string.nonmembers]
24.3.3.1
operator+
[string.op+]
template<class charT, class traits, class Allocator>
basic_string<charT, traits, Allocator>
operator+(const basic_string<charT, traits, Allocator>& lhs,
const basic_string<charT, traits, Allocator>& rhs);
1
Returns: basic_string<charT, traits, Allocator>(lhs).append(rhs).
§ 24.3.3.1
688
template<class charT, class traits, class Allocator>
basic_string<charT, traits, Allocator>
operator+(basic_string<charT, traits, Allocator>&& lhs,
const basic_string<charT, traits, Allocator>& rhs);
2
Returns: std::move(lhs.append(rhs)).
template<class charT, class traits, class Allocator>
basic_string<charT, traits, Allocator>
operator+(const basic_string<charT, traits, Allocator>& lhs,
basic_string<charT, traits, Allocator>&& rhs);
3
Returns: std::move(rhs.insert(0, lhs)).
template<class charT, class traits, class Allocator>
basic_string<charT, traits, Allocator>
operator+(basic_string<charT, traits, Allocator>&& lhs,
basic_string<charT, traits, Allocator>&& rhs);
4
Returns: std::move(lhs.append(rhs)). [ Note: Or equivalently, std::move(rhs.insert(0,
lhs)).
— end note ]
template<class charT, class traits, class Allocator>
basic_string<charT, traits, Allocator>
operator+(const charT* lhs, const basic_string<charT, traits, Allocator>& rhs);
5
Returns: basic_string<charT, traits, Allocator>(lhs) + rhs.
6
Remarks: Uses traits::length().
template<class charT, class traits, class Allocator>
basic_string<charT, traits, Allocator>
operator+(const charT* lhs, basic_string<charT, traits, Allocator>&& rhs);
7
Returns: std::move(rhs.insert(0, lhs)).
8
Remarks: Uses traits::length().
template<class charT, class traits, class Allocator>
basic_string<charT, traits, Allocator>
operator+(charT lhs, const basic_string<charT, traits, Allocator>& rhs);
9
Returns: basic_string<charT, traits, Allocator>(1, lhs) + rhs.
template<class charT, class traits, class Allocator>
basic_string<charT, traits, Allocator>
operator+(charT lhs, basic_string<charT, traits, Allocator>&& rhs);
10
Returns: std::move(rhs.insert(0, 1, lhs)).
template<class charT, class traits, class Allocator>
basic_string<charT, traits, Allocator>
operator+(const basic_string<charT, traits, Allocator>& lhs, const charT* rhs);
11
Returns: lhs + basic_string<charT, traits, Allocator>(rhs).
12
Remarks: Uses traits::length().
template<class charT, class traits, class Allocator>
basic_string<charT, traits, Allocator>
operator+(basic_string<charT, traits, Allocator>&& lhs, const charT* rhs);
13
Returns: std::move(lhs.append(rhs)).
14
Remarks: Uses traits::length().
template<class charT, class traits, class Allocator>
basic_string<charT, traits, Allocator>
operator+(const basic_string<charT, traits, Allocator>& lhs, charT rhs);
15
Returns: lhs + basic_string<charT, traits, Allocator>(1, rhs).
§ 24.3.3.1
689
template<class charT, class traits, class Allocator>
basic_string<charT, traits, Allocator>
operator+(basic_string<charT, traits, Allocator>&& lhs, charT rhs);
16
Returns: std::move(lhs.append(1, rhs)).
24.3.3.2
operator==
[string.operator==]
template<class charT, class traits, class Allocator>
bool operator==(const basic_string<charT, traits, Allocator>& lhs,
const basic_string<charT, traits, Allocator>& rhs) noexcept;
1
Returns: lhs.compare(rhs) == 0.
template<class charT, class traits, class Allocator>
bool operator==(const charT* lhs, const basic_string<charT, traits, Allocator>& rhs);
2
Returns: rhs == lhs.
template<class charT, class traits, class Allocator>
bool operator==(const basic_string<charT, traits, Allocator>& lhs, const charT* rhs);
3
Requires: rhs points to an array of at least traits::length(rhs) + 1 elements of charT.
4
Returns: lhs.compare(rhs) == 0.
24.3.3.3
operator!=
[string.op!=]
template<class charT, class traits, class Allocator>
bool operator!=(const basic_string<charT, traits, Allocator>& lhs,
const basic_string<charT, traits, Allocator>& rhs) noexcept;
1
Returns: !(lhs == rhs).
template<class charT, class traits, class Allocator>
bool operator!=(const charT* lhs, const basic_string<charT, traits, Allocator>& rhs);
2
Returns: rhs != lhs.
template<class charT, class traits, class Allocator>
bool operator!=(const basic_string<charT, traits, Allocator>& lhs, const charT* rhs);
3
Requires: rhs points to an array of at least traits::length(rhs) + 1 elements of charT.
4
Returns: lhs.compare(rhs) != 0.
24.3.3.4
operator<
[string.op<]
template<class charT, class traits, class Allocator>
bool operator<(const basic_string<charT, traits, Allocator>& lhs,
const basic_string<charT, traits, Allocator>& rhs) noexcept;
1
Returns: lhs.compare(rhs) < 0.
template<class charT, class traits, class Allocator>
bool operator<(const charT* lhs, const basic_string<charT, traits, Allocator>& rhs);
2
Returns: rhs.compare(lhs) > 0.
template<class charT, class traits, class Allocator>
bool operator<(const basic_string<charT, traits, Allocator>& lhs, const charT* rhs);
3
Returns: lhs.compare(rhs) < 0.
24.3.3.5
operator>
[string.op>]
template<class charT, class traits, class Allocator>
bool operator>(const basic_string<charT, traits, Allocator>& lhs,
const basic_string<charT, traits, Allocator>& rhs) noexcept;
1
Returns: lhs.compare(rhs) > 0.
§ 24.3.3.5
690
template<class charT, class traits, class Allocator>
bool operator>(const charT* lhs, const basic_string<charT, traits, Allocator>& rhs);
2
Returns: rhs.compare(lhs) < 0.
template<class charT, class traits, class Allocator>
bool operator>(const basic_string<charT, traits, Allocator>& lhs, const charT* rhs);
3
Returns: lhs.compare(rhs) > 0.
24.3.3.6
operator<=
[string.op<=]
template<class charT, class traits, class Allocator>
bool operator<=(const basic_string<charT, traits, Allocator>& lhs,
const basic_string<charT, traits, Allocator>& rhs) noexcept;
1
Returns: lhs.compare(rhs) <= 0.
template<class charT, class traits, class Allocator>
bool operator<=(const charT* lhs, const basic_string<charT, traits, Allocator>&
rhs);
2
Returns: rhs.compare(lhs) >= 0.
template<class charT, class traits, class Allocator>
bool operator<=(const basic_string<charT, traits, Allocator>& lhs, const charT*
rhs);
3
Returns: lhs.compare(rhs) <= 0.
24.3.3.7
operator>=
[string.op>=]
template<class charT, class traits, class Allocator>
bool operator>=(const basic_string<charT, traits, Allocator>& lhs,
const basic_string<charT, traits, Allocator>& rhs) noexcept;
1
Returns: lhs.compare(rhs) >= 0.
template<class charT, class traits, class Allocator>
bool operator>=(const charT* lhs, const basic_string<charT, traits, Allocator>&
rhs);
2
Returns: rhs.compare(lhs) <= 0.
template<class charT, class traits, class Allocator>
bool operator>=(const basic_string<charT, traits, Allocator>& lhs, const charT*
rhs);
3
Returns: lhs.compare(rhs) >= 0.
24.3.3.8
swap
[string.special]
template<class charT, class traits, class Allocator>
void swap(basic_string<charT, traits, Allocator>& lhs,
basic_string<charT, traits, Allocator>& rhs)
noexcept(noexcept(lhs.swap(rhs)));
1
Effects: Equivalent to lhs.swap(rhs).
24.3.3.9
Inserters and extractors
[string.io]
template<class charT, class traits, class Allocator>
basic_istream<charT, traits>&
operator>>(basic_istream<charT, traits>& is, basic_string<charT, traits, Allocator>& str);
1
Effects: Behaves as a formatted input function (30.7.4.2.1). After constructing a sentry object, if the
sentry converts to true, calls str.erase() and then extracts characters from is and appends them to
str as if by calling str.append(1, c). If is.width() is greater than zero, the maximum number n
of characters appended is is.width(); otherwise n is str.max_size(). Characters are extracted and
appended until any of the following occurs:
(1.1)
—
n characters are stored;
(1.2)
—
end-of-file occurs on the input sequence;
(1.3)
—
isspace(c, is.getloc()) is true for the next available input character c.
§ 24.3.3.9
691
2
After the last character (if any) is extracted, is.width(0) is called and the sentry object is destroyed.
3
If the function extracts no characters, it calls is.setstate(ios::failbit), which may throw ios_-
base::failure (30.5.5.4).
4
Returns: is.
template<class charT, class traits, class Allocator>
basic_ostream<charT, traits>&
operator<<(basic_ostream<charT, traits>& os,
const basic_string<charT, traits, Allocator>& str);
5
Effects: Equivalent to: return os << basic_string_view<charT, traits>(str);
template<class charT, class traits, class Allocator>
basic_istream<charT, traits>&
getline(basic_istream<charT, traits>& is,
basic_string<charT, traits, Allocator>& str,
charT delim);
template<class charT, class traits, class Allocator>
basic_istream<charT, traits>&
getline(basic_istream<charT, traits>&& is,
basic_string<charT, traits, Allocator>& str,
charT delim);
6
Effects: Behaves as an unformatted input function (30.7.4.3), except that it does not affect the value
returned by subsequent calls to basic_istream<>::gcount(). After constructing a sentry object,
if the sentry converts to true, calls str.erase() and then extracts characters from is and appends
them to str as if by calling str.append(1, c) until any of the following occurs:
(6.1)
—
end-of-file occurs on the input sequence (in which case, the getline function calls is.setstate(
ios_base::eofbit)).
(6.2)
—
traits::eq(c, delim) for the next available input character c (in which case, c is extracted but
not appended) (30.5.5.4)
(6.3)
—
str.max_size() characters are stored (in which case, the function calls is.setstate(ios_-
base::failbit)) (30.5.5.4)
7
The conditions are tested in the order shown. In any case, after the last character is extracted, the
sentry object is destroyed.
8
If the function extracts no characters, it calls is.setstate(ios_base::failbit) which may throw
ios_base::failure (30.5.5.4).
9
Returns: is.
template<class charT, class traits, class Allocator>
basic_istream<charT, traits>&
getline(basic_istream<charT, traits>& is,
basic_string<charT, traits, Allocator>& str);
template<class charT, class traits, class Allocator>
basic_istream<charT, traits>&
getline(basic_istream<charT, traits>&& is,
basic_string<charT, traits, Allocator>& str);
10
Returns: getline(is, str, is.widen(’\n’)).
24.3.4
Numeric conversions
[string.conversions]
int stoi(const string& str, size_t* idx = nullptr, int base = 10);
long stol(const string& str, size_t* idx = nullptr, int base = 10);
unsigned long stoul(const string& str, size_t* idx = nullptr, int base = 10);
long long stoll(const string& str, size_t* idx = nullptr, int base = 10);
unsigned long long stoull(const string& str, size_t* idx = nullptr, int base = 10);
1
Effects: The first two functions call strtol(str.c_str(), ptr, base), and the last three functions call
strtoul(str.c_str(), ptr, base), strtoll(str.c_str(), ptr, base), and strtoull(str.c_-
str(), ptr, base), respectively. Each function returns the converted result, if any. The argument
ptr designates a pointer to an object internal to the function that is used to determine what to store
§ 24.3.4
692
at *idx. If the function does not throw an exception and idx != 0, the function stores in *idx the
index of the first unconverted element of str.
2
Returns: The converted result.
3
Throws: invalid_argument if strtol, strtoul, strtoll, or strtoull reports that no conversion
could be performed. Throws out_of_range if strtol, strtoul, strtoll or strtoull sets errno to
ERANGE, or if the converted value is outside the range of representable values for the return type.
float stof(const string& str, size_t* idx = nullptr);
double stod(const string& str, size_t* idx = nullptr);
long double stold(const string& str, size_t* idx = nullptr);
4
Effects: These functions call strtof(str.c_str(), ptr), strtod(str.c_str(), ptr), and strtold(
str.c_str(), ptr), respectively. Each function returns the converted result, if any. The argument
ptr designates a pointer to an object internal to the function that is used to determine what to store
at *idx. If the function does not throw an exception and idx != 0, the function stores in *idx the
index of the first unconverted element of str.
5
Returns: The converted result.
6
Throws: invalid_argument if strtof, strtod, or strtold reports that no conversion could be
performed. Throws out_of_range if strtof, strtod, or strtold sets errno to ERANGE or if the
converted value is outside the range of representable values for the return type.
string to_string(int val);
string to_string(unsigned val);
string to_string(long val);
string to_string(unsigned long val);
string to_string(long long val);
string to_string(unsigned long long val);
string to_string(float val);
string to_string(double val);
string to_string(long double val);
7
Returns: Each function returns a string object holding the character representation of the value of
its argument that would be generated by calling sprintf(buf, fmt, val) with a format specifier of
"%d", "%u", "%ld", "%lu", "%lld", "%llu", "%f", "%f", or "%Lf", respectively, where buf designates
an internal character buffer of sufficient size.
int stoi(const wstring& str, size_t* idx = nullptr, int base = 10);
long stol(const wstring& str, size_t* idx = nullptr, int base = 10);
unsigned long stoul(const wstring& str, size_t* idx = nullptr, int base = 10);
long long stoll(const wstring& str, size_t* idx = nullptr, int base = 10);
unsigned long long stoull(const wstring& str, size_t* idx = nullptr, int base = 10);
8
Effects: The first two functions call wcstol(str.c_str(), ptr, base), and the last three functions call
wcstoul(str.c_str(), ptr, base), wcstoll(str.c_str(), ptr, base), and wcstoull(str.c_-
str(), ptr, base), respectively. Each function returns the converted result, if any. The argument
ptr designates a pointer to an object internal to the function that is used to determine what to store
at *idx. If the function does not throw an exception and idx != 0, the function stores in *idx the
index of the first unconverted element of str.
9
Returns: The converted result.
10
Throws: invalid_argument if wcstol, wcstoul, wcstoll, or wcstoull reports that no conversion
could be performed. Throws out_of_range if the converted value is outside the range of representable
values for the return type.
float stof(const wstring& str, size_t* idx = nullptr);
double stod(const wstring& str, size_t* idx = nullptr);
long double stold(const wstring& str, size_t* idx = nullptr);
11
Effects: These functions call wcstof(str.c_str(), ptr), wcstod(str.c_str(), ptr), and wcstold(
str.c_str(), ptr), respectively. Each function returns the converted result, if any. The argument
ptr designates a pointer to an object internal to the function that is used to determine what to store
at *idx. If the function does not throw an exception and idx != 0, the function stores in *idx the
index of the first unconverted element of str.
§ 24.3.4
693
12
Returns: The converted result.
13
Throws: invalid_argument if wcstof, wcstod, or wcstold reports that no conversion could be
performed. Throws out_of_range if wcstof, wcstod, or wcstold sets errno to ERANGE.
wstring to_wstring(int val);
wstring to_wstring(unsigned val);
wstring to_wstring(long val);
wstring to_wstring(unsigned long val);
wstring to_wstring(long long val);
wstring to_wstring(unsigned long long val);
wstring to_wstring(float val);
wstring to_wstring(double val);
wstring to_wstring(long double val);
14
Returns: Each function returns a wstring object holding the character representation of the value of
its argument that would be generated by calling swprintf(buf, buffsz, fmt, val) with a format
specifier of L"%d", L"%u", L"%ld", L"%lu", L"%lld", L"%llu", L"%f", L"%f", or L"%Lf", respectively,
where buf designates an internal character buffer of sufficient size buffsz.
24.3.5
Hash support
[basic.string.hash]
template<> struct hash<string>;
template<> struct hash<u16string>;
template<> struct hash<u32string>;
template<> struct hash<wstring>;
template<> struct hash<pmr::string>;
template<> struct hash<pmr::u16string>;
template<> struct hash<pmr::u32string>;
template<> struct hash<pmr::wstring>;
1
If S is one of these string types, SV is the corresponding string view type, and s is an object of type S,
then hash<S>()(s) == hash<SV>()(SV(s)).
24.3.6
Suffix for basic_string literals
[basic.string.literals]
string operator""s(const char* str, size_t len);
1
Returns: string{str, len}.
u16string operator""s(const char16_t* str, size_t len);
2
Returns: u16string{str, len}.
u32string operator""s(const char32_t* str, size_t len);
3
Returns: u32string{str, len}.
wstring operator""s(const wchar_t* str, size_t len);
4
Returns: wstring{str, len}.
5
[Note: The same suffix s is used for chrono::duration literals denoting seconds but there is no conflict,
since duration suffixes apply to numbers and string literal suffixes apply to character array literals.
— end
note ]
24.4
String view classes
[string.view]
1
The class template basic_string_view describes an object that can refer to a constant contiguous sequence
of char-like (24.1) objects with the first element of the sequence at position zero. In the rest of this subclause,
the type of the char-like objects held in a basic_string_view object is designated by charT.
2
[Note: The library provides implicit conversions from const charT* and std::basic_string<charT,
...> to std::basic_string_view<charT, ...> so that user code can accept just std::basic_string_-
view<charT> as a non-templated parameter wherever a sequence of characters is expected. User-defined
types should define their own implicit conversions to std::basic_string_view in order to interoperate with
these functions.
— end note ]
3
The complexity of basic_string_view member functions is O(1) unless otherwise specified.
§ 24.4
694
24.4.1
Header <string_view> synopsis
[string.view.synop]
namespace std {
// 24.4.2, class template basic_string_view
template<class charT, class traits = char_traits<charT>>
class basic_string_view;
// 24.4.3, non-member comparison functions
template<class charT, class traits>
constexpr bool operator==(basic_string_view<charT, traits>
x,
basic_string_view<charT, traits>
y)
noexcept;
template<class charT, class traits>
constexpr bool operator!=(basic_string_view<charT, traits>
x,
basic_string_view<charT, traits>
y)
noexcept;
template<class charT, class traits>
constexpr bool operator< (basic_string_view<charT, traits>
x,
basic_string_view<charT, traits>
y)
noexcept;
template<class charT, class traits>
constexpr bool operator> (basic_string_view<charT, traits>
x,
basic_string_view<charT, traits>
y)
noexcept;
template<class charT, class traits>
constexpr bool operator<=(basic_string_view<charT, traits>
x,
basic_string_view<charT, traits>
y)
noexcept;
template<class charT, class traits>
constexpr bool operator>=(basic_string_view<charT, traits>
x,
basic_string_view<charT, traits>
y)
noexcept;
// see 24.4.3, sufficient additional overloads of comparison functions
// 24.4.4, inserters and extractors
template<class charT, class traits>
basic_ostream<charT, traits>&
operator<<(basic_ostream<charT, traits>& os,
basic_string_view<charT, traits> str);
// basic_string_view typedef names
using string_view
= basic_string_view<char>;
using u16string_view = basic_string_view<char16_t>;
using u32string_view = basic_string_view<char32_t>;
using wstring_view
= basic_string_view<wchar_t>;
// 24.4.5, hash support
template<class T> struct hash;
template<> struct hash<string_view>;
template<> struct hash<u16string_view>;
template<> struct hash<u32string_view>;
template<> struct hash<wstring_view>;
inline namespace literals {
inline namespace string_view_literals {
// 24.4.6, suffix for basic_string_view literals
constexpr string_view
operator""sv(const char* str, size_t
len) noexcept;
constexpr u16string_view operator""sv(const char16_t* str, size_t len) noexcept;
constexpr u32string_view operator""sv(const char32_t* str, size_t len) noexcept;
constexpr wstring_view operator""sv(const wchar_t* str, size_t len) noexcept;
}
}
}
1
The function templates defined in 23.2.2 and 27.7 are available when <string_view> is included.
24.4.2
Class template basic_string_view
[string.view.template]
template<class charT, class traits = char_traits<charT>>
class basic_string_view {
public:
// types
§ 24.4.2
695
using traits_type
= traits;
using value_type
= charT;
using pointer
= value_type*;
using const_pointer
= const value_type*;
using reference
= value_type&;
using const_reference
= const value_type&;
using const_iterator
= implementation-defined ; // see 24.4.2.2
using iterator
= const_iterator;232
using const_reverse_iterator = reverse_iterator<const_iterator>;
using reverse_iterator
= const_reverse_iterator;
using size_type
= size_t;
using difference_type
= ptrdiff_t;
static constexpr size_type npos = size_type(-1);
// 24.4.2.1, construction and assignment
constexpr basic_string_view() noexcept;
constexpr basic_string_view(const basic_string_view&) noexcept =
default;
constexpr basic_string_view& operator=(const basic_string_view&)
noexcept
=
default;
constexpr basic_string_view(const charT* str);
constexpr basic_string_view(const charT* str, size_type len);
// 24.4.2.2, iterator support
constexpr const_iterator begin() const noexcept;
constexpr const_iterator end() const noexcept;
constexpr const_iterator cbegin() const noexcept;
constexpr const_iterator cend() const noexcept;
constexpr const_reverse_iterator rbegin() const noexcept;
constexpr const_reverse_iterator rend() const noexcept;
constexpr const_reverse_iterator crbegin() const noexcept;
constexpr const_reverse_iterator crend() const noexcept;
// 24.4.2.3, capacity
constexpr size_type size() const noexcept;
constexpr size_type length() const noexcept;
constexpr size_type max_size() const noexcept;
[[nodiscard]] constexpr bool empty() const noexcept;
// 24.4.2.4, element access
constexpr const_reference operator[](size_type pos) const;
constexpr const_reference at(size_type pos) const;
constexpr const_reference front() const;
constexpr const_reference back() const;
constexpr const_pointer data() const noexcept;
// 24.4.2.5, modifiers
constexpr void remove_prefix(size_type n);
constexpr void remove_suffix(size_type n);
constexpr void swap(basic_string_view& s) noexcept;
// 24.4.2.6, string operations
size_type copy(charT* s, size_type n, size_type pos = 0) const;
constexpr basic_string_view substr(size_type pos = 0, size_type
n
=
npos)
const;
constexpr int compare(basic_string_view s) const noexcept;
constexpr int compare(size_type pos1, size_type n1, basic_string_view s) const;
constexpr int compare(size_type pos1, size_type n1, basic_string_view s,
size_type pos2, size_type n2) const;
constexpr int compare(const charT* s) const;
constexpr int compare(size_type pos1, size_type n1, const charT* s) const;
constexpr int compare(size_type pos1, size_type n1, const charT* s, size_type n2)
const;
232) Because basic_string_view refers to a constant sequence, iterator and const_iterator are the same type.
§ 24.4.2
696
constexpr
bool starts_with(basic_string_view x) const noexcept;
constexpr
bool starts_with(charT x) const noexcept;
constexpr
bool starts_with(const charT* x) const;
constexpr
bool ends_with(basic_string_view x) const noexcept;
constexpr
bool ends_with(charT x) const noexcept;
constexpr
bool ends_with(const charT* x) const;
constexpr
size_type find(basic_string_view s, size_type pos = 0) const noexcept;
constexpr
size_type find(charT c, size_type pos = 0) const noexcept;
constexpr
size_type find(const charT* s, size_type pos, size_type n) const;
constexpr
size_type find(const charT* s, size_type pos = 0) const;
constexpr
size_type rfind(basic_string_view s, size_type pos = npos) const noexcept;
constexpr
size_type rfind(charT c, size_type pos = npos) const noexcept;
constexpr
size_type rfind(const charT* s, size_type pos, size_type n) const;
constexpr
size_type rfind(const charT* s, size_type pos = npos) const;
constexpr
size_type find_first_of(basic_string_view s, size_type pos = 0) const noexcept;
constexpr
size_type find_first_of(charT c, size_type pos = 0) const noexcept;
constexpr
size_type find_first_of(const charT* s, size_type pos, size_type n) const;
constexpr
size_type find_first_of(const charT* s, size_type pos = 0) const;
constexpr
size_type find_last_of(basic_string_view s, size_type pos = npos) const noexcept;
constexpr
size_type find_last_of(charT c, size_type pos = npos) const noexcept;
constexpr
size_type find_last_of(const charT* s, size_type pos, size_type n) const;
constexpr
size_type find_last_of(const charT* s, size_type pos = npos) const;
constexpr
size_type find_first_not_of(basic_string_view s, size_type pos = 0) const noexcept;
constexpr
size_type find_first_not_of(charT c, size_type pos = 0) const noexcept;
constexpr
size_type find_first_not_of(const charT* s, size_type pos,
size_type n) const;
constexpr
size_type find_first_not_of(const charT* s, size_type pos = 0) const;
constexpr
size_type find_last_not_of(basic_string_view s,
size_type pos = npos) const noexcept;
constexpr
size_type find_last_not_of(charT c, size_type pos = npos) const noexcept;
constexpr
size_type find_last_not_of(const charT* s, size_type pos,
size_type n) const;
constexpr
size_type find_last_not_of(const charT* s, size_type pos = npos) const;
private:
const_pointer data_; // exposition only
size_type size_;
// exposition only
};
1
In every specialization basic_string_view<charT, traits>, the type traits shall satisfy the character
traits requirements (24.2), and the type traits::char_type shall name the same type as charT.
24.4.2.1
Construction and assignment
[string.view.cons]
constexpr basic_string_view() noexcept;
1
Effects: Constructs an empty basic_string_view.
2
Postconditions: size_ == 0 and data_ == nullptr.
constexpr basic_string_view(const charT* str);
3
Requires: [str, str + traits::length(str)) is a valid range.
4
Effects: Constructs a basic_string_view, with the postconditions in Table 64.
Table 64 — basic_string_view(const charT*) effects
Element
Value
data_
str
size_
traits::length(str)
5
Complexity: O(traits::length(str)).
§ 24.4.2.1
697
constexpr basic_string_view(const charT* str, size_type len);
6
Requires: [str, str + len) is a valid range.
7
Effects: Constructs a basic_string_view, with the postconditions in Table 65.
Table 65 — basic_string_view(const charT*, size_type) effects
Element
Value
data_
str
size_
len
24.4.2.2
Iterator support
[string.view.iterators]
using const_iterator = implementation-defined ;
1
A type that meets the requirements of a constant random access iterator (27.2.7) and of a contiguous
iterator (27.2.1) whose value_type is the template parameter charT.
2
For a basic_string_view str, any operation that invalidates a pointer in the range [str.data(),
str.data() + str.size()) invalidates pointers, iterators, and references returned from str’s member
functions.
3
All requirements on container iterators (26.2) apply to basic_string_view::const_iterator as well.
constexpr const_iterator begin() const noexcept;
constexpr const_iterator cbegin() const noexcept;
4
Returns: An iterator such that
(4.1)
—
if
!empty(), &*begin() == data_,
(4.2)
—
otherwise, an unspecified value such that [begin(), end()) is a valid range.
constexpr const_iterator end() const noexcept;
constexpr const_iterator cend() const noexcept;
5
Returns: begin() + size().
constexpr const_reverse_iterator rbegin() const noexcept;
constexpr const_reverse_iterator crbegin() const noexcept;
6
Returns: const_reverse_iterator(end()).
constexpr const_reverse_iterator rend() const noexcept;
constexpr const_reverse_iterator crend() const noexcept;
7
Returns: const_reverse_iterator(begin()).
24.4.2.3
Capacity
[string.view.capacity]
constexpr size_type size() const noexcept;
1
Returns: size_.
constexpr size_type length() const noexcept;
2
Returns: size_.
constexpr size_type max_size() const noexcept;
3
Returns: The largest possible number of char-like objects that can be referred to by a basic_string_-
view.
[[nodiscard]] constexpr bool empty() const noexcept;
4
Returns: size_ == 0.
24.4.2.4
Element access
[string.view.access]
constexpr const_reference operator[](size_type pos) const;
1
Requires: pos < size().
§ 24.4.2.4
698
2
Returns: data_[pos].
3
Throws: Nothing.
4
[Note: Unlike basic_string::operator[], basic_string_view::operator[](size()) has unde-
fined behavior instead of returning charT().
— end note ]
constexpr const_reference at(size_type pos) const;
5
Throws: out_of_range if pos >= size().
6
Returns: data_[pos].
constexpr const_reference front() const;
7
Requires: !empty().
8
Returns: data_[0].
9
Throws: Nothing.
constexpr const_reference back() const;
10
Requires: !empty().
11
Returns: data_[size() - 1].
12
Throws: Nothing.
constexpr const_pointer data() const noexcept;
13
Returns: data_.
14
[ Note: Unlike basic_string::data() and string literals, data() may return a pointer to a buffer that
is not null-terminated. Therefore it is typically a mistake to pass data() to a function that takes just a
const charT* and expects a null-terminated string.
— end note ]
24.4.2.5
Modifiers
[string.view.modifiers]
constexpr void remove_prefix(size_type n);
1
Requires: n <= size().
2
Effects: Equivalent to: data_ += n; size_ -= n;
constexpr void remove_suffix(size_type n);
3
Requires: n <= size().
4
Effects: Equivalent to: size_ -= n;
constexpr void swap(basic_string_view& s) noexcept;
5
Effects: Exchanges the values of *this and s.
24.4.2.6
String operations
[string.view.ops]
size_type copy(charT* s, size_type n, size_type pos =
0) const;
1
Let rlen be the smaller of n and size() - pos.
2
Throws: out_of_range if pos > size().
3
Requires: [s, s + rlen) is a valid range.
4
Effects: Equivalent to traits::copy(s, data() +
pos, rlen).
5
Returns: rlen.
6
Complexity: O(rlen).
constexpr basic_string_view substr(size_type pos = 0,
size_type n =
npos)
const;
7
Let rlen be the smaller of n and size() - pos.
8
Throws: out_of_range if pos > size().
9
Effects: Determines rlen, the effective length of the string to reference.
10
Returns: basic_string_view(data() + pos, rlen).
§ 24.4.2.6
699
constexpr int compare(basic_string_view str) const noexcept;
11
Let rlen be the smaller of size() and str.size().
12
Effects: Determines rlen, the effective length of the strings to compare. The function then compares
the two strings by calling traits::compare(data(), str.data(), rlen).
13
Complexity: O(rlen).
14
Returns: The nonzero result if the result of the comparison is nonzero. Otherwise, returns a value as
indicated in Table 66.
Table 66 — compare() results
Condition
Return Value
size() < str.size()
< 0
size() == str.size()
0
size() > str.size()
> 0
constexpr int compare(size_type pos1, size_type n1, basic_string_view str) const;
15
Effects: Equivalent to: return substr(pos1, n1).compare(str);
constexpr int compare(size_type pos1, size_type n1, basic_string_view str,
size_type pos2, size_type n2) const;
16
Effects: Equivalent to: return substr(pos1, n1).compare(str.substr(pos2, n2));
constexpr int compare(const charT* s) const;
17
Effects: Equivalent to: return compare(basic_string_view(s));
constexpr int compare(size_type pos1, size_type n1, const charT* s) const;
18
Effects: Equivalent to: return substr(pos1, n1).compare(basic_string_view(s));
constexpr int compare(size_type pos1, size_type n1, const charT* s, size_type n2) const;
19
Effects: Equivalent to: return substr(pos1, n1).compare(basic_string_view(s, n2));
constexpr bool starts_with(basic_string_view x) const noexcept;
20
Effects: Equivalent to: return compare(0, npos, x) == 0;
constexpr bool starts_with(charT x) const noexcept;
21
Effects: Equivalent to: return starts_with(basic_string_view(&x, 1));
constexpr bool starts_with(const charT* x) const;
22
Effects: Equivalent to: return starts_with(basic_string_view(x));
constexpr bool ends_with(basic_string_view x) const noexcept;
23
Effects: Equivalent to:
return size() >= x.size() && compare(size() - x.size(), npos, x) == 0;
constexpr bool ends_with(charT x) const noexcept;
24
Effects: Equivalent to: return ends_with(basic_string_view(&x, 1));
constexpr bool ends_with(const charT* x) const;
25
Effects: Equivalent to: return ends_with(basic_string_view(x));
24.4.2.7
Searching
[string.view.find]
1
This subclause specifies the basic_string_view member functions named find, rfind, find_first_of,
find_last_of, find_first_not_of, and find_last_not_of.
2
Member functions in this subclause have complexity O(size() * str.size()) at worst, although imple-
mentations should do better.
§ 24.4.2.7
700
3
Each member function of the form
constexpr return-type F (const charT* s, size_type pos);
is equivalent to return F (basic_string_view(s), pos);
4
Each member function of the form
constexpr return-type F (const charT* s, size_type pos, size_type n);
is equivalent to return F (basic_string_view(s, n), pos);
5
Each member function of the form
constexpr return-type F (charT c, size_type pos);
is equivalent to return F (basic_string_view(&c, 1), pos);
constexpr size_type find(basic_string_view str, size_type pos = 0) const noexcept;
6
Let xpos be the lowest position, if possible, such that the following conditions hold:
(6.1)
—
pos <= xpos
(6.2)
—
xpos + str.size() <= size()
(6.3)
—
traits::eq(at(xpos + I), str.at(I)) for all elements I of the string referenced by str.
7
Effects: Determines xpos.
8
Returns: xpos if the function can determine such a value for xpos. Otherwise, returns npos.
constexpr size_type rfind(basic_string_view str, size_type pos = npos) const noexcept;
9
Let xpos be the highest position, if possible, such that the following conditions hold:
(9.1)
—
xpos <= pos
(9.2)
—
xpos + str.size() <= size()
(9.3)
—
traits::eq(at(xpos + I), str.at(I)) for all elements I of the string referenced by str.
10
Effects: Determines xpos.
11
Returns: xpos if the function can determine such a value for xpos. Otherwise, returns npos.
constexpr size_type find_first_of(basic_string_view str, size_type pos = 0) const noexcept;
12
Let xpos be the lowest position, if possible, such that the following conditions hold:
(12.1)
—
pos <= xpos
(12.2)
—
xpos < size()
(12.3)
—
traits::eq(at(xpos), str.at(I)) for some element I of the string referenced by str.
13
Effects: Determines xpos.
14
Returns: xpos if the function can determine such a value for xpos. Otherwise, returns npos.
constexpr size_type find_last_of(basic_string_view str, size_type pos = npos) const noexcept;
15
Let xpos be the highest position, if possible, such that the following conditions hold:
(15.1)
—
xpos <= pos
(15.2)
—
xpos < size()
(15.3)
—
traits::eq(at(xpos), str.at(I)) for some element I of the string referenced by str.
16
Effects: Determines xpos.
17
Returns: xpos if the function can determine such a value for xpos. Otherwise, returns npos.
constexpr size_type find_first_not_of(basic_string_view str, size_type pos = 0) const noexcept;
18
Let xpos be the lowest position, if possible, such that the following conditions hold:
(18.1)
—
pos <= xpos
(18.2)
—
xpos < size()
(18.3)
—
traits::eq(at(xpos), str.at(I)) for no element I of the string referenced by str.
§ 24.4.2.7
701
19
Effects: Determines xpos.
20
Returns: xpos if the function can determine such a value for xpos. Otherwise, returns npos.
constexpr size_type find_last_not_of(basic_string_view str, size_type pos = npos) const noexcept;
21
Let xpos be the highest position, if possible, such that the following conditions hold:
(21.1)
—
xpos <= pos
(21.2)
—
xpos < size()
(21.3)
—
traits::eq(at(xpos), str.at(I)) for no element I of the string referenced by str.
22
Effects: Determines xpos.
23
Returns: xpos if the function can determine such a value for xpos. Otherwise, returns npos.
24.4.3
Non-member comparison functions
[string.view.comparison]
1
Let S be basic_string_view<charT, traits>, and sv be an instance of S. Implementations shall provide
sufficient additional overloads marked constexpr and noexcept so that an object t with an implicit conversion
to S can be compared according to Table 67.
Table 67 — Additional basic_string_view comparison overloads
Expression Equivalent to
t == sv
S(t) == sv
sv == t
sv == S(t)
t != sv
S(t) != sv
sv != t
sv != S(t)
t < sv
S(t) < sv
sv < t
sv < S(t)
t > sv
S(t) > sv
sv > t
sv > S(t)
t <= sv
S(t) <= sv
sv <= t
sv <= S(t)
t >= sv
S(t) >= sv
sv >= t
sv >= S(t)
[ Example: A sample conforming implementation for operator== would be:
template<class T> using __identity = decay_t<T>;
template<class charT, class traits>
constexpr bool operator==(basic_string_view<charT, traits> lhs,
basic_string_view<charT, traits> rhs) noexcept {
return lhs.compare(rhs) == 0;
}
template<class charT, class traits>
constexpr bool operator==(basic_string_view<charT, traits> lhs,
__identity<basic_string_view<charT, traits>> rhs)
noexcept
{
return lhs.compare(rhs) == 0;
}
template<class charT, class traits>
constexpr bool operator==(__identity<basic_string_view<charT, traits>> lhs,
basic_string_view<charT, traits> rhs) noexcept {
return lhs.compare(rhs) == 0;
}
— end example ]
template<class charT, class traits>
constexpr bool operator==(basic_string_view<charT, traits> lhs,
basic_string_view<charT, traits> rhs) noexcept;
2
Returns: lhs.compare(rhs) == 0.
§ 24.4.3
702
template<class charT, class traits>
constexpr bool operator!=(basic_string_view<charT, traits> lhs,
basic_string_view<charT, traits> rhs) noexcept;
3
Returns: lhs.compare(rhs) != 0.
template<class charT, class traits>
constexpr bool operator<(basic_string_view<charT, traits> lhs,
basic_string_view<charT, traits> rhs) noexcept;
4
Returns: lhs.compare(rhs) < 0.
template<class charT, class traits>
constexpr bool operator>(basic_string_view<charT, traits> lhs,
basic_string_view<charT, traits> rhs) noexcept;
5
Returns: lhs.compare(rhs) > 0.
template<class charT, class traits>
constexpr bool operator<=(basic_string_view<charT, traits> lhs,
basic_string_view<charT, traits> rhs) noexcept;
6
Returns: lhs.compare(rhs) <= 0.
template<class charT, class traits>
constexpr bool operator>=(basic_string_view<charT, traits> lhs,
basic_string_view<charT, traits> rhs) noexcept;
7
Returns: lhs.compare(rhs) >= 0.
24.4.4
Inserters and extractors
[string.view.io]
template<class charT, class traits>
basic_ostream<charT, traits>&
operator<<(basic_ostream<charT, traits>& os, basic_string_view<charT, traits>
str);
1
Effects: Behaves as a formatted output function (30.7.5.2.1) of os. Forms a character sequence seq,
initially consisting of the elements defined by the range [str.begin(), str.end()). Determines
padding for seq as described in 30.7.5.2.1. Then inserts seq as if by calling os.rdbuf()->sputn(seq,
n), where n is the larger of os.width() and str.size(); then calls os.width(0).
2
Returns: os
24.4.5
Hash support
[string.view.hash]
template<> struct hash<string_view>;
template<> struct hash<u16string_view>;
template<> struct hash<u32string_view>;
template<> struct hash<wstring_view>;
1
The specialization is enabled (23.14.15). [ Note: The hash value of a string view object is equal to the
hash value of the corresponding string object (24.3.5).
— end note ]
24.4.6
Suffix for basic_string_view literals
[string.view.literals]
constexpr string_view operator""sv(const char* str, size_t len) noexcept;
1
Returns: string_view{str, len}.
constexpr u16string_view operator""sv(const char16_t* str, size_t len) noexcept;
2
Returns: u16string_view{str, len}.
constexpr u32string_view operator""sv(const char32_t* str, size_t len) noexcept;
3
Returns: u32string_view{str, len}.
constexpr wstring_view operator""sv(const wchar_t* str, size_t len) noexcept;
4
Returns: wstring_view{str, len}.
§ 24.4.6
703
24.5
Null-terminated sequence utilities
[c.strings]
24.5.1
Header <cctype> synopsis
[cctype.syn]
namespace std {
int isalnum(int c);
int isalpha(int c);
int isblank(int c);
int iscntrl(int c);
int isdigit(int c);
int isgraph(int c);
int islower(int c);
int isprint(int c);
int ispunct(int c);
int isspace(int c);
int isupper(int c);
int isxdigit(int c);
int tolower(int c);
int toupper(int c);
}
1
The contents and meaning of the header <cctype> are the same as the C standard library header <ctype.h>.
See also: ISO C 7.4
24.5.2
Header <cwctype> synopsis
[cwctype.syn]
namespace std {
using wint_t = see below ;
using wctrans_t = see below ;
using wctype_t = see below ;
int iswalnum(wint_t wc);
int iswalpha(wint_t wc);
int iswblank(wint_t wc);
int iswcntrl(wint_t wc);
int iswdigit(wint_t wc);
int iswgraph(wint_t wc);
int iswlower(wint_t wc);
int iswprint(wint_t wc);
int iswpunct(wint_t wc);
int iswspace(wint_t wc);
int iswupper(wint_t wc);
int iswxdigit(wint_t wc);
int iswctype(wint_t wc, wctype_t desc);
wctype_t wctype(const char* property);
wint_t towlower(wint_t wc);
wint_t towupper(wint_t wc);
wint_t towctrans(wint_t wc, wctrans_t desc);
wctrans_t wctrans(const char* property);
}
#define WEOF see below
1
The contents and meaning of the header <cwctype> are the same as the C standard library header <wctype.h>.
See also: ISO C 7.30
24.5.3
Header <cstring> synopsis
[cstring.syn]
namespace std {
using size_t = see 21.2.4;
void* memcpy(void* s1, const void* s2, size_t n);
void* memmove(void* s1, const void* s2, size_t n);
char* strcpy(char* s1, const char* s2);
char* strncpy(char* s1, const char* s2, size_t n);
char* strcat(char* s1, const char* s2);
§ 24.5.3
704
char* strncat(char* s1, const char* s2, size_t n);
int memcmp(const void* s1, const void* s2, size_t n);
int strcmp(const char* s1, const char* s2);
int strcoll(const char* s1, const char* s2);
int strncmp(const char* s1, const char* s2, size_t n);
size_t strxfrm(char* s1, const char* s2, size_t n);
const void* memchr(const void* s, int c, size_t n);
// see 20.2
void* memchr(void* s, int c, size_t n);
// see 20.2
const char* strchr(const char* s, int c);
// see 20.2
char* strchr(char* s, int c);
// see 20.2
size_t strcspn(const char* s1, const char* s2);
const char* strpbrk(const char* s1, const char* s2);
// see 20.2
char* strpbrk(char* s1, const char* s2);
// see 20.2
const char* strrchr(const char* s, int c);
// see 20.2
char* strrchr(char* s, int c);
// see 20.2
size_t strspn(const char* s1, const char* s2);
const char* strstr(const char* s1, const char* s2);
// see 20.2
char* strstr(char* s1, const char* s2);
// see 20.2
char* strtok(char* s1, const char* s2);
void* memset(void* s, int c, size_t n);
char* strerror(int errnum);
size_t strlen(const char* s);
}
#define NULL see 21.2.3
1
The contents and meaning of the header <cstring> are the same as the C standard library header <string.h>.
2
The functions strerror and strtok are not required to avoid data races (20.5.5.9).
3
The functions memcpy and memmove are signal-safe (21.11.4).
4
[Note: The functions strchr, strpbrk, strrchr, strstr, and memchr, have different signatures in this
document, but they have the same behavior as in the C standard library (20.2).
— end note ]
See also: ISO C 7.24
24.5.4
Header <cwchar> synopsis
[cwchar.syn]
namespace std {
using size_t = see 21.2.4;
using mbstate_t = see below ;
using wint_t = see below ;
struct tm;
int fwprintf(FILE* stream, const wchar_t* format, ...);
int fwscanf(FILE* stream, const wchar_t* format, ...);
int swprintf(wchar_t* s, size_t n, const wchar_t* format, ...);
int swscanf(const wchar_t* s, const wchar_t* format, ...);
int vfwprintf(FILE* stream, const wchar_t* format, va_list arg);
int vfwscanf(FILE* stream, const wchar_t* format, va_list arg);
int vswprintf(wchar_t* s, size_t n, const wchar_t* format, va_list arg);
int vswscanf(const wchar_t* s, const wchar_t* format, va_list arg);
int vwprintf(const wchar_t* format, va_list arg);
int vwscanf(const wchar_t* format, va_list arg);
int wprintf(const wchar_t* format, ...);
int wscanf(const wchar_t* format, ...);
wint_t fgetwc(FILE* stream);
wchar_t* fgetws(wchar_t* s, int n, FILE* stream);
wint_t fputwc(wchar_t c, FILE* stream);
int fputws(const wchar_t* s, FILE* stream);
int fwide(FILE* stream, int mode);
wint_t getwc(FILE* stream);
wint_t getwchar();
wint_t putwc(wchar_t c, FILE* stream);
wint_t putwchar(wchar_t c);
§ 24.5.4
705
wint_t ungetwc(wint_t c, FILE* stream);
double wcstod(const wchar_t* nptr, wchar_t** endptr);
float wcstof(const wchar_t* nptr, wchar_t** endptr);
long double wcstold(const wchar_t* nptr, wchar_t** endptr);
long int wcstol(const wchar_t* nptr, wchar_t** endptr, int base);
long long int wcstoll(const wchar_t* nptr, wchar_t** endptr, int base);
unsigned long int wcstoul(const wchar_t* nptr, wchar_t** endptr, int base);
unsigned long long int wcstoull(const wchar_t* nptr, wchar_t** endptr, int base);
wchar_t* wcscpy(wchar_t* s1, const wchar_t* s2);
wchar_t* wcsncpy(wchar_t* s1, const wchar_t* s2, size_t n);
wchar_t* wmemcpy(wchar_t* s1, const wchar_t* s2, size_t n);
wchar_t* wmemmove(wchar_t* s1, const wchar_t* s2, size_t n);
wchar_t* wcscat(wchar_t* s1, const wchar_t* s2);
wchar_t* wcsncat(wchar_t* s1, const wchar_t* s2, size_t n);
int wcscmp(const wchar_t* s1, const wchar_t* s2);
int wcscoll(const wchar_t* s1, const wchar_t* s2);
int wcsncmp(const wchar_t* s1, const wchar_t* s2, size_t n);
size_t wcsxfrm(wchar_t* s1, const wchar_t* s2, size_t n);
int wmemcmp(const wchar_t* s1, const wchar_t* s2, size_t n);
const wchar_t* wcschr(const wchar_t* s, wchar_t c);
// see 20.2
wchar_t* wcschr(wchar_t* s, wchar_t c);
// see 20.2
size_t wcscspn(const wchar_t* s1, const wchar_t* s2);
const wchar_t* wcspbrk(const wchar_t* s1, const wchar_t* s2);
// see 20.2
wchar_t* wcspbrk(wchar_t* s1, const wchar_t* s2);
// see 20.2
const wchar_t* wcsrchr(const wchar_t* s, wchar_t c);
// see 20.2
wchar_t* wcsrchr(wchar_t* s, wchar_t c);
// see 20.2
size_t wcsspn(const wchar_t* s1, const wchar_t* s2);
const wchar_t* wcsstr(const wchar_t* s1, const wchar_t* s2);
// see 20.2
wchar_t* wcsstr(wchar_t* s1, const wchar_t* s2);
// see 20.2
wchar_t* wcstok(wchar_t* s1, const wchar_t* s2, wchar_t** ptr);
const wchar_t* wmemchr(const wchar_t* s, wchar_t c, size_t n);
// see 20.2
wchar_t* wmemchr(wchar_t* s, wchar_t c, size_t n);
// see 20.2
size_t wcslen(const wchar_t* s);
wchar_t* wmemset(wchar_t* s, wchar_t c, size_t n);
size_t wcsftime(wchar_t* s, size_t maxsize, const wchar_t* format, const struct
tm*
timeptr);
wint_t btowc(int c);
int wctob(wint_t c);
// 24.5.6, multibyte / wide string and character conversion functions
int mbsinit(const mbstate_t* ps);
size_t mbrlen(const char* s, size_t n, mbstate_t* ps);
size_t mbrtowc(wchar_t* pwc, const char* s, size_t n, mbstate_t* ps);
size_t wcrtomb(char* s, wchar_t wc, mbstate_t* ps);
size_t mbsrtowcs(wchar_t* dst, const char** src, size_t len, mbstate_t* ps);
size_t wcsrtombs(char* dst, const wchar_t** src, size_t len, mbstate_t* ps);
}
#define NULL see 21.2.3
#define WCHAR_MAX see below
#define WCHAR_MIN see below
#define WEOF see below
1
The contents and meaning of the header <cwchar> are the same as the C standard library header <wchar.h>,
except that it does not declare a type wchar_t.
2
[Note: The functions wcschr, wcspbrk, wcsrchr, wcsstr, and wmemchr have different signatures in this
document, but they have the same behavior as in the C standard library (20.2).
— end note ]
See also: ISO C 7.29
24.5.5
Header <cuchar> synopsis
[cuchar.syn]
namespace std {
using mbstate_t = see below ;
using size_t = see 21.2.4;
§ 24.5.5
706
size_t mbrtoc16(char16_t* pc16, const char* s, size_t n, mbstate_t* ps);
size_t c16rtomb(char* s, char16_t c16, mbstate_t* ps);
size_t mbrtoc32(char32_t* pc32, const char* s, size_t n, mbstate_t* ps);
size_t c32rtomb(char* s, char32_t c32, mbstate_t* ps);
}
1
The contents and meaning of the header <cuchar> are the same as the C standard library header <uchar.h>,
except that it does not declare types char16_t nor char32_t.
See also: ISO C 7.28
24.5.6
Multibyte / wide string and character conversion functions
[c.mb.wcs]
1
[Note: The headers <cstdlib> (21.2.2) and <cwchar> (24.5.4) declare the functions described in this
subclause.
— end note ]
int mbsinit(const mbstate_t* ps);
int mblen(const char* s, size_t n);
size_t mbstowcs(wchar_t* pwcs, const char* s, size_t n);
size_t wcstombs(char* s, const wchar_t* pwcs, size_t n);
2
Effects: These functions have the semantics specified in the C standard library.
See also: ISO C 7.22.7.1, 7.22.8, 7.29.6.2.1
int mbtowc(wchar_t* pwc, const char* s, size_t n);
int wctomb(char* s, wchar_t wchar);
3
Effects: These functions have the semantics specified in the C standard library.
4
Remarks: Calls to these functions may introduce a data race (20.5.5.9) with other calls to the same
function.
See also: ISO C 7.22.7
size_t mbrlen(const char* s, size_t n, mbstate_t* ps);
size_t mbrtowc(wchar_t* pwc, const char* s, size_t n, mbstate_t* ps);
size_t wcrtomb(char* s, wchar_t wc, mbstate_t* ps);
size_t mbsrtowcs(wchar_t* dst, const char** src, size_t len, mbstate_t* ps);
size_t wcsrtombs(char* dst, const wchar_t** src, size_t len, mbstate_t* ps);
5
Effects: These functions have the semantics specified in the C standard library.
6
Remarks: Calling these functions with an mbstate_t* argument that is a null pointer value may
introduce a data race (20.5.5.9) with other calls to the same function with an mbstate_t* argument
that is a null pointer value.
See also: ISO C 7.29.6.3
§ 24.5.6
707
25
Localization library
[localization]
25.1
General
[localization.general]
1
This Clause describes components that C++ programs may use to encapsulate (and therefore be more portable
when confronting) cultural differences. The locale facility includes internationalization support for character
classification and string collation, numeric, monetary, and date/time formatting and parsing, and message
retrieval.
2
The following subclauses describe components for locales themselves, the standard facets, and facilities from
the ISO C library, as summarized in Table 68.
Table 68 — Localization library summary
Subclause
Header(s)
25.3
Locales
<locale>
25.4
Standard locale Categories
25.5
C library locales
<clocale>
25.2
Header <locale> synopsis
[locale.syn]
namespace std {
// 25.3.1, locale
class locale;
template<class Facet> const Facet& use_facet(const locale&);
template<class Facet> bool
has_facet(const locale&) noexcept;
// 25.3.3, convenience interfaces
template<class charT> bool isspace (charT c, const locale& loc);
template<class charT> bool isprint (charT c, const locale& loc);
template<class charT> bool iscntrl (charT c, const locale& loc);
template<class charT> bool isupper (charT c, const locale& loc);
template<class charT> bool islower (charT c, const locale& loc);
template<class charT> bool isalpha (charT c, const locale& loc);
template<class charT> bool isdigit (charT c, const locale& loc);
template<class charT> bool ispunct (charT c, const locale& loc);
template<class charT> bool isxdigit(charT c, const locale& loc);
template<class charT> bool isalnum (charT c, const locale& loc);
template<class charT> bool isgraph (charT c, const locale& loc);
template<class charT> bool isblank (charT c, const locale& loc);
template<class charT> charT toupper(charT c, const locale& loc);
template<class charT> charT tolower(charT c, const locale& loc);
// 25.4.1, ctype
class ctype_base;
template<class charT> class ctype;
template<>
class ctype<char>;
// specialization
template<class charT> class ctype_byname;
class codecvt_base;
template<class internT, class externT, class stateT> class codecvt;
template<class internT, class externT, class stateT> class codecvt_byname;
// 25.4.2, numeric
template<class charT, class InputIterator = istreambuf_iterator<charT>>
class num_get;
template<class charT, class OutputIterator = ostreambuf_iterator<charT>>
class num_put;
template<class charT>
class numpunct;
§
25.2
708
template<class charT>
class numpunct_byname;
// 25.4.4, collation
template<class charT> class collate;
template<class charT> class collate_byname;
// 25.4.5, date and time
class time_base;
template<class charT, class InputIterator = istreambuf_iterator<charT>>
class time_get;
template<class charT, class InputIterator = istreambuf_iterator<charT>>
class time_get_byname;
template<class charT, class OutputIterator = ostreambuf_iterator<charT>>
class time_put;
template<class charT, class OutputIterator = ostreambuf_iterator<charT>>
class time_put_byname;
// 25.4.6, money
class money_base;
template<class charT, class InputIterator = istreambuf_iterator<charT>>
class money_get;
template<class charT, class OutputIterator = ostreambuf_iterator<charT>>
class money_put;
template<class charT, bool Intl = false>
class moneypunct;
template<class charT, bool Intl = false>
class moneypunct_byname;
// 25.4.7, message retrieval
class messages_base;
template<class charT> class messages;
template<class charT> class messages_byname;
}
1
The header <locale> defines classes and declares functions that encapsulate and manipulate the information
peculiar to a locale.233
25.3
Locales
[locales]
25.3.1
Class locale
[locale]
namespace std {
class locale {
public:
// types
class facet;
class id;
using category = int;
static const category
// values assigned here are for exposition only
none
= 0,
collate
= 0x010, ctype
= 0x020,
monetary = 0x040, numeric
= 0x080,
time
= 0x100, messages = 0x200,
all = collate | ctype | monetary | numeric | time
| messages;
// construct/copy/destroy
locale() noexcept;
locale(const locale& other) noexcept;
explicit locale(const char* std_name);
explicit locale(const string& std_name);
locale(const locale& other, const char* std_name, category);
locale(const locale& other, const string& std_name, category);
template<class Facet> locale(const locale& other, Facet* f);
233) In this subclause, the type name struct tm is an incomplete type that is defined in <ctime>.
§ 25.3.1
709
locale(const locale& other, const locale& one, category);
~locale();
// not virtual
const locale& operator=(const locale& other) noexcept;
template<class Facet> locale combine(const locale& other) const;
// locale operations
basic_string<char> name() const;
bool operator==(const locale& other) const;
bool operator!=(const locale& other) const;
template<class charT, class traits, class Allocator>
bool operator()(const basic_string<charT, traits, Allocator>& s1,
const basic_string<charT, traits, Allocator>& s2) const;
// global locale objects
static
locale global(const locale&);
static const locale& classic();
};
}
1
Class locale implements a type-safe polymorphic set of facets, indexed by facet type. In other words, a facet
has a dual role: in one sense, it’s just a class interface; at the same time, it’s an index into a locale’s set of
facets.
2
Access to the facets of a locale is via two function templates, use_facet<> and has_facet<>.
3
[ Example: An iostream operator<< might be implemented as:234
template<class charT, class traits>
basic_ostream<charT, traits>&
operator<< (basic_ostream<charT, traits>& s, Date d) {
typename basic_ostream<charT, traits>::sentry cerberos(s);
if (cerberos) {
ios_base::iostate err = ios_base::iostate::goodbit;
tm tmbuf; d.extract(tmbuf);
use_facet<time_put<charT, ostreambuf_iterator<charT, traits>>>(
s.getloc()).put(s, s, s.fill(), err, &tmbuf, ’x’);
s.setstate(err);
// might throw
}
return s;
}
— end example ]
4
In the call to use_facet<Facet>(loc), the type argument chooses a facet, making available all members
of the named type. If Facet is not present in a locale, it throws the standard exception bad_cast. A C++
program can check if a locale implements a particular facet with the function template has_facet<Facet>().
User-defined facets may be installed in a locale, and used identically as may standard facets (25.4.8).
5
[ Note: All locale semantics are accessed via use_facet<> and has_facet<>, except that:
—
(5.1)
A member operator template operator()(const basic_string<C, T, A>&, const basic_string<
C, T, A>&) is provided so that a locale may be used as a predicate argument to the standard collections,
to collate strings.
(5.2)
—
Convenient global interfaces are provided for traditional ctype functions such as isdigit() and
isspace(), so that given a locale object loc a C++ program can call isspace(c, loc). (This eases
upgrading existing extractors (30.7.4.2).)
— end note ]
6
Once a facet reference is obtained from a locale object by calling use_facet<>, that reference remains usable,
and the results from member functions of it may be cached and re-used, as long as some locale object refers
to that facet.
234) Note that in the call to put the stream is implicitly converted to an ostreambuf_iterator<charT, traits>.
§ 25.3.1
710
7
In successive calls to a locale facet member function on a facet object installed in the same locale, the returned
result shall be identical.
8
A locale constructed from a name string (such as "POSIX"), or from parts of two named locales, has a name;
all others do not. Named locales may be compared for equality; an unnamed locale is equal only to (copies
of) itself. For an unnamed locale, locale::name() returns the string "*".
9
Whether there is one global locale object for the entire program or one global locale object per thread is
implementation-defined. Implementations should provide one global locale object per thread. If there is a
single global locale object for the entire program, implementations are not required to avoid data races on
it (20.5.5.9).
25.3.1.1
locale types
[locale.types]
25.3.1.1.1
Type locale::category
[locale.category]
using category = int;
1
Valid category values include the locale member bitmask elements collate, ctype, monetary, numeric,
time, and messages, each of which represents a single locale category. In addition, locale member bitmask
constant none is defined as zero and represents no category. And locale member bitmask constant all is
defined such that the expression
(collate | ctype | monetary | numeric | time | messages | all) == all
is true, and represents the union of all categories. Further, the expression (X | Y), where X and Y each
represent a single category, represents the union of the two categories.
2
locale member functions expecting a category argument require one of the category values defined above,
or the union of two or more such values. Such a category value identifies a set of locale categories. Each
locale category, in turn, identifies a set of locale facets, including at least those shown in Table 69.
Table 69 — Locale category facets
Category
Includes facets
collate
collate<char>, collate<wchar_t>
ctype
ctype<char>, ctype<wchar_t>
codecvt<char, char, mbstate_t>
codecvt<char16_t, char, mbstate_t>
codecvt<char32_t, char, mbstate_t>
codecvt<wchar_t, char, mbstate_t>
monetary moneypunct<char>, moneypunct<wchar_t>
moneypunct<char, true>, moneypunct<wchar_t, true>
money_get<char>, money_get<wchar_t>
money_put<char>, money_put<wchar_t>
numeric
numpunct<char>, numpunct<wchar_t>
num_get<char>, num_get<wchar_t>
num_put<char>, num_put<wchar_t>
time
time_get<char>, time_get<wchar_t>
time_put<char>, time_put<wchar_t>
messages
messages<char>, messages<wchar_t>
3
For any locale loc either constructed, or returned by locale::classic(), and any facet Facet shown in
Table 69, has_facet<Facet>(loc) is true. Each locale member function which takes a locale::category
argument operates on the corresponding set of facets.
4
An implementation is required to provide those specializations for facet templates identified as members of a
category, and for those shown in Table 70.
5
The provided implementation of members of facets num_get<charT> and num_put<charT> calls use_fac-
et<F>(l) only for facet F of types numpunct<charT> and ctype<charT>, and for locale l the value obtained
by calling member getloc() on the ios_base& argument to these functions.
6
In declarations of facets, a template parameter with name InputIterator or OutputIterator indicates the
set of all possible specializations on parameters that satisfy the requirements of an Input Iterator or an
§ 25.3.1.1.1
711