cppdraft_translate/cppdraft/string/nonmembers.md

[string.nonmembers]

27 Strings library [strings]

27.4 String classes [string.classes]

27.4.4 Non-member functions [string.nonmembers]

27.4.4.1 operator+ [string.op.plus]

🔗

template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(const basic_string<charT, traits, Allocator>& lhs, const basic_string<charT, traits, Allocator>& rhs); template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(const basic_string<charT, traits, Allocator>& lhs, const charT* rhs);

1

#

Effects: Equivalent to:basic_string<charT, traits, Allocator> r = lhs; r.append(rhs);return r;

🔗

template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(basic_string<charT, traits, Allocator>&& lhs, const basic_string<charT, traits, Allocator>& rhs); template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(basic_string<charT, traits, Allocator>&& lhs, const charT* rhs);

2

#

Effects: Equivalent to:lhs.append(rhs);return std::move(lhs);

🔗

template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(basic_string<charT, traits, Allocator>&& lhs, basic_string<charT, traits, Allocator>&& rhs);

3

#

Effects: Equivalent to:lhs.append(rhs);return std::move(lhs); except that both lhs and rhs are left in valid but unspecified states.

[Note 1:

If lhs and rhs have equal allocators, the implementation can move from either.

— end note]

🔗

template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(const basic_string<charT, traits, Allocator>& lhs, basic_string<charT, traits, Allocator>&& rhs); template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(const charT* lhs, basic_string<charT, traits, Allocator>&& rhs);

4

#

Effects: Equivalent to:rhs.insert(0, lhs);return std::move(rhs);

🔗

template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(const charT* lhs, const basic_string<charT, traits, Allocator>& rhs);

5

#

Effects: Equivalent to:basic_string<charT, traits, Allocator> r = rhs; r.insert(0, lhs);return r;

🔗

template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(charT lhs, const basic_string<charT, traits, Allocator>& rhs);

6

#

Effects: Equivalent to:basic_string<charT, traits, Allocator> r = rhs; r.insert(r.begin(), lhs);return r;

🔗

template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(charT lhs, basic_string<charT, traits, Allocator>&& rhs);

7

#

Effects: Equivalent to:rhs.insert(rhs.begin(), lhs);return std::move(rhs);

🔗

template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(const basic_string<charT, traits, Allocator>& lhs, charT rhs);

8

#

Effects: Equivalent to:basic_string<charT, traits, Allocator> r = lhs; r.push_back(rhs);return r;

🔗

template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(basic_string<charT, traits, Allocator>&& lhs, charT rhs);

9

#

Effects: Equivalent to:lhs.push_back(rhs);return std::move(lhs);

🔗

template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(const basic_string<charT, traits, Allocator>& lhs, type_identity_t<basic_string_view<charT, traits>> rhs);

10

#

Equivalent to:basic_string<charT, traits, Allocator> r = lhs; r.append(rhs);return r;

🔗

template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(basic_string<charT, traits, Allocator>&& lhs, type_identity_t<basic_string_view<charT, traits>> rhs);

11

#

Equivalent to:lhs.append(rhs);return std::move(lhs);

🔗

template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(type_identity_t<basic_string_view<charT, traits>> lhs, const basic_string<charT, traits, Allocator>& rhs);

12

#

Equivalent to:basic_string<charT, traits, Allocator> r = rhs; r.insert(0, lhs);return r;

🔗

template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(type_identity_t<basic_string_view<charT, traits>> lhs, basic_string<charT, traits, Allocator>&& rhs);

13

#

Equivalent to:rhs.insert(0, lhs);return std::move(rhs);

14

#

[Note 2:

Using a specialization of type_identity_t as a parameter type ensures that an object of type basic_string<charT, traits, Allocator> can be concatenated with an object of a type T having an implicit conversion tobasic_string_view<charT, traits> ([over.match.oper]).

— end note]

27.4.4.2 Non-member comparison operator functions [string.cmp]

🔗

`template<class charT, class traits, class Allocator> constexpr bool operator==(const basic_string<charT, traits, Allocator>& lhs, const basic_string<charT, traits, Allocator>& rhs) noexcept; template<class charT, class traits, class Allocator> constexpr bool operator==(const basic_string<charT, traits, Allocator>& lhs, const charT* rhs);

template<class charT, class traits, class Allocator> constexpr see below operator<=>(const basic_string<charT, traits, Allocator>& lhs, const basic_string<charT, traits, Allocator>& rhs) noexcept; template<class charT, class traits, class Allocator> constexpr see below operator<=>(const basic_string<charT, traits, Allocator>& lhs, const charT* rhs); `

1

#

Effects: Let op be the operator.

Equivalent to:return basic_string_view<charT, traits>(lhs) op basic_string_view<charT, traits>(rhs);

27.4.4.3 swap [string.special]

🔗

template<class charT, class traits, class Allocator> constexpr 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).

27.4.4.4 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 ([istream.formatted.reqmts]).

After constructing a sentry object, if the sentry object returns true when converted to a value of type bool, calls str.erase() and then extracts characters from is and appends them to str as if by callingstr.append(1, c).

Ifis.width() is greater than zero, the maximum number n of characters appended isis.width(); otherwise n isstr.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 characterc.

2

#

After the last character (if any) is extracted,is.width(0) is called and thesentry object is destroyed.

3

#

If the function extracts no characters,ios_base​::​failbit is set in the input function's local error state before setstate is called.

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 ([istream.unformatted]), except that it does not affect the value returned by subsequent calls tobasic_istream<>​::​gcount().

After constructing a sentry object, if the sentry object returns true when converted to a value of type bool, calls str.erase() and then extracts characters from is and appends them to str as if by callingstr.append(1, c) until any of the following occurs:

• (6.1)

end-of-file occurs on the input sequence;

• (6.2)

traits​::​eq(c, delim) for the next available input characterc (in which case,c is extracted but not appended);

• (6.3)

str.max_size() characters are stored (in which case,ios_base​::​failbit is set in the input function's local error state).

7

#

The conditions are tested in the order shown.

In any case, after the last character is extracted, thesentry object is destroyed.

8

#

If the function extracts no characters,ios_base​::​failbit is set in the input function's local error state before setstate is called.

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')).

27.4.4.5 Erasure [string.erasure]

🔗

template<class charT, class traits, class Allocator, class U = charT> constexpr typename basic_string<charT, traits, Allocator>::size_type erase(basic_string<charT, traits, Allocator>& c, const U& value);

1

#

Effects: Equivalent to:auto it = remove(c.begin(), c.end(), value);auto r = distance(it, c.end()); c.erase(it, c.end());return r;

🔗

template<class charT, class traits, class Allocator, class Predicate> constexpr typename basic_string<charT, traits, Allocator>::size_type erase_if(basic_string<charT, traits, Allocator>& c, Predicate pred);

2

#

Effects: Equivalent to:auto it = remove_if(c.begin(), c.end(), pred);auto r = distance(it, c.end()); c.erase(it, c.end());return r;