std::basic_...stringstream(3)

🦋 std::basic_...stringstream(3) 🦋

okay bestie, this is the std::basic_...stringstream(3) page from the C++ Standard Libary manual — yes, “Libary” is literally in the header and we are not fixing it. We’re doing string-stream constructors today, all twelve overloads, and yes it’s giving main-character energy. 💅

---

🌸 NAME 🌸

std::basic_istringstream::basic_istringstream — that’s the constructor. The whole NAME is just the constructor. Iconic, honestly.

✨ Synopsis ✨

Constructs new string stream. Periodt.

Given:

• base_type as std::basic_istream<CharT, Traits>, and
• buf_type as std::basic_stringbuf<CharT, Traits, Allocator>,

the std::basic_istream base and the exposition-only data member sb are initialized as follows.

🎀 The overloads, all twelve of them 🎀

(1) (until C++11)

explicit basic_istringstream( std::ios_base::openmode mode = std::ios_base::in );

(1) (since C++11)

explicit basic_istringstream( std::ios_base::openmode mode );

(2) (since C++11)

basic_istringstream()
    : basic_istringstream(std::ios_base::in) {}

(3)

explicit basic_istringstream(
    const std::basic_string<CharT, Traits, Allocator>& str,
    std::ios_base::openmode mode = std::ios_base::in );

(4) (since C++20)

explicit basic_istringstream(
    std::basic_string<CharT, Traits, Allocator>&& str,
    std::ios_base::openmode mode = std::ios_base::in );

(5) (since C++20)

basic_istringstream( std::ios_base::openmode mode, const Allocator& a );

(6) (since C++20)

template< class SAlloc >
basic_istringstream(
    const std::basic_string<CharT, Traits, SAlloc>& str,
    std::ios_base::openmode mode, const Allocator& a );

(7) (since C++20)

template< class SAlloc >
basic_istringstream(
    const std::basic_string<CharT, Traits, SAlloc>& str,
    const Allocator& a )
    : basic_istringstream(str, std::ios_base::in, a) {}

(8) (since C++20)

template< class SAlloc >
explicit basic_istringstream(
    const std::basic_string<CharT, Traits, SAlloc>& str,
    std::ios_base::openmode mode = std::ios_base::in );

(9) (since C++26)

template< class StringViewLike >
explicit basic_istringstream(
    const StringViewLike& t,
    std::ios_base::openmode mode = std::ios_base::in );

(10) (since C++26)

template< class StringViewLike >
basic_istringstream(
    const StringViewLike& t,
    std::ios_base::openmode mode, const Allocator& a );

(11) (since C++26)

template< class StringViewLike >
basic_istringstream( const StringViewLike& t, const Allocator& a );

(12) (since C++11)

basic_istringstream( basic_istringstream&& other );

🧚 Init table, but make it a list 🧚

If I don’t mention the std::basic_istream base for an overload, the table left that cell blank — I’m not skipping it, it’s literally blank.

• (1) — sb: buf_type(mode | std::ios_base::in).
• (2) — sb: buf_type(std::ios_base::in).
• (3) — sb: buf_type(str, mode | std::ios_base::in).
• (4) — sb: buf_type(std::move(str), mode | std::ios_base::in).
• (5) — base: base_type(std::addressof(sb))^[1]; sb: buf_type(mode | std::ios_base::in, a).
• (6) — sb: buf_type(str, mode | std::ios_base::in, a).
• (7) — sb: buf_type(str, std::ios_base::in, a).
• (8) — sb: buf_type(str, mode | std::ios_base::in).
• (9) — base: std::addressof(sb); sb: {t, mode | std::ios_base::in, Allocator()}.
• (10) — sb: {t, mode | std::ios_base::in, a}.
• (11) — sb: {t, std::ios_base::in, a}.
• (12) — base: move constructed from other's std::basic_istream base; sb: move constructed from other.sb.

1. ↑ The std::basic_iostream base was intialized with base_type(&sb) (for overloads (1,3)) until C++11.

💀 Overload-resolution gatekeeping 💀

• 8) This overload participates in overload resolution only if std::is_same_v<SAlloc, Allocator> is false.
• 9-11) These overloads participate in overload resolution only if std::is_convertible_v<const StringViewLike&, std::basic_string_view<CharT, Traits>> is true.

💖 Parameters 💖

• str — string to use as initial contents of the string stream.
• t — an object (convertible to std::basic_string_view) to use as initial contents of the string stream.
• a — allocator used for allocating the contents of the string stream.
• mode — specifies stream open mode. It is a BitmaskType, and these constants are defined:
  • app — seek to the end of stream before each write
  • binary — open in binary mode
  • in — open for reading
  • out — open for writing
  • trunc — discard the contents of the stream when opening
  • ate — seek to the end of stream immediately after open
  • noreplace (C++23) — open in exclusive mode
• other — another string stream to use as source.

🌈 Notes 🌈

Construction of one-off basic_istringstream objects in a tight loop, such as when used for string conversion, may be significantly more costly than calling str() to reuse the same object. So don’t be out here making a fresh one every single loop if you can recycle, bestie. 🫶

• __cpp_lib_sstream_from_string_view — value 202306L, std (C++26), feature: Interfacing std::stringstreams with std::string_view, (9-11).

🍓 Example 🍓

// Run this code

#include <iostream>
#include <sstream>

int main()
{
    // default constructor (input/output stream)
    std::stringstream buf1;
    buf1 << 7;
    int n = 0;
    buf1 >> n;
    std::cout << "buf1 = " << buf1.str() << " n = " << n << '\n';

    // input stream
    std::istringstream inbuf("-10");
    inbuf >> n;
    std::cout << "n = " << n << '\n';

    // output stream in append mode (C++11)
    std::ostringstream buf2("test", std::ios_base::ate);
    buf2 << '1';
    std::cout << buf2.str() << '\n';
}

📤 Output:

buf1 = 7 n = 7
n = -10
test1

🧚 Defect reports 🧚

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

• P0935R0 — applied to C++11 — behavior as published: the default constructor was explicit; correct behavior: made implicit.

👑 See also 👑

• str — gets or sets the contents of underlying string device object (public member function).
• constructor — constructs a basic_stringbuf object (public member function of std::basic_stringbuf<CharT,Traits,Allocator>).

---

cute sign-off: source/version is http://cppreference.com, date is 2024.06.10, and the footer title is std::basic_...stringstream(3). bye bestie, go construct responsibly 💜✨