21 Strings library [strings]

21.4 Class template basic_string [basic.string]

21.4.8 basic_string non-member functions [string.nonmembers]

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

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

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

21.4.8.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.

21.4.8.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.

21.4.8.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.

21.4.8.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.

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.

21.4.8.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.

21.4.8.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.

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

1

Effects: Equivalent to lhs.swap(rhs);

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

2

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

3

If the function extracts no characters, it calls is.setstate(ios::failbit), which may throw ios_base::failure ([iostate.flags]).

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: Behaves as a formatted output function ([ostream.formatted.reqmts]) 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 [ostream.formatted.reqmts]. 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).

6

Returns: os

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

7

Effects: Behaves as an unformatted input function ([istream.unformatted]), 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:

  • (7.1)

    end-of-file occurs on the input sequence (in which case, the getline function calls is.setstate(ios_base::eofbit)).

  • (7.2)

    traits::eq(c, delim) for the next available input character c (in which case, c is extracted but not appended) ([iostate.flags])

  • (7.3)

    str.max_size() characters are stored (in which case, the function calls is.setstate(ios_base::failbit)) ([iostate.flags])

8

The conditions are tested in the order shown. In any case, after the last character is extracted, the sentry object k is destroyed.

9

If the function extracts no characters, it calls is.setstate(ios_base::failbit) which may throw ios_base::failure ([iostate.flags]).

10

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

11

Returns: getline(is,str,is.widen('\n'))