[string.nonmembers] (original) (raw)

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);

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);

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);

Effects: Equivalent to:lhs.append(rhs);return std::move(lhs);except that both lhs and rhsare 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);

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);

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);

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);

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);

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);

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);

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);

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);

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);

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

[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 Thaving 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);

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)));

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);

After constructing a sentry object, if the sentry object returns truewhen 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:

• _n_characters are stored;
• end-of-file occurs on the input sequence;
• isspace(c, is.getloc())is true for the next available input character_c_.

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

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

template<class charT, class traits, class Allocator> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os,const basic_string<charT, traits, Allocator>& str);

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);

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 truewhen 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:

• end-of-file occurs on the input sequence;
• traits​::​eq(c, delim)for the next available input character_c_(in which case,_c_is extracted but not appended);
• str.max_size()characters are stored (in which case,ios_base​::​failbit is set in the input function's local error state).

The conditions are tested in the order shown.

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

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

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);

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);

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);

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;