std::basic_...gstream::str(3)

🎀 std::basic_istringstream::str(3) — C++ Standard Libary, bestie edition 💅

okay so this is the manual page for std::basic_istringstream::str from the C++ Standard Libary (yes that's how the header spells it, i don't make the rules ✨). coming to you straight from cppreference.com, dated 2024.06.10. let's get into it 🫶

---

🌸 NAME

std::basic_istringstream::str — literally the member that reads and rewrites the underlying string inside your string stream. the main character of this whole page, no cap 👑

---

✨ Synopsis

so there are seven overloads and they all want your attention. here they are, exactly as written, because i would never do you dirty like that:

std::basic_string<CharT, Traits, Allocator> str() const;

(until C++20)

std::basic_string<CharT, Traits, Allocator> str() const&;

(since C++20)

(2) (since C++20)

template< class SAlloc >
std::basic_string<CharT, Traits, SAlloc> str( const SAlloc& a
) const;

(3) (since C++20)

std::basic_string<CharT, Traits, Allocator> str() &&;

(4)

void str( const std::basic_string<CharT, Traits, Allocator>& s );

(5) (since C++20)

template< class SAlloc >
void str( const std::basic_string<CharT, Traits, SAlloc>& s );

(6) (since C++20)

void str( std::basic_string<CharT, Traits, Allocator>&& s );

(7) (since C++26)

template< class StringViewLike >
void str( const StringViewLike& t );

---

🦋 what it actually does

Manages the contents of the underlying string object. that's the whole job. but like, how — let me spell it out 💖

1. Returns a copy of the underlying string. Equivalent to return rdbuf()->str();.
2. Returns a copy of the underlying string, using a as allocator. Equivalent to

return rdbuf()->str(a);

3. Returns a string move-constructed from the underlying string. Equivalent to

return std::move(*rdbuf()).str();

4. , 5. Replaces the contents of the underlying string. Equivalent to rdbuf()->str(s);.
6. Replaces the contents of the underlying string. Equivalent to

rdbuf()->str(std::move(s));

7. Replaces the contents of the underlying string. Equivalent to rdbuf()->str(t);. This overload participates in overload resolution only if is_convertible_v<const T&, basic_string_view<charT, traits>> is true. (iykyk 🧚)

---

💜 Parameters

• s — new contents of the underlying string 🌸
• t — an object (convertible to std::basic_string_view) to use as the new contents of the underlying string
• a — allocator used to construct the returned string ✨

---

👑 Return value

1. , 2. A copy of the underlying string object. 🫶
3. A string move-constructed from the underlying string object. 💫
4. - 7. (none) — that's it, that's the whole return value, she gives nothing back 💀

---

🌈 Notes

⚠️ bestie listen to me. The copy of the underlying string returned by str is a temporary object that will be destructed at the end of the expression, so directly calling c_str() on the result of str() (for example in auto *ptr = out.str().c_str();) results in a dangling pointer. 😭 like fr fr do not do that. that's undefined behaviour territory and she will not be nice about it.

---

🔥 Feature-test macro

• __cpp_lib_sstream_from_string_view — value 202306L — std (C++26) — feature: Interfacing std::stringstreams with std::string_view, applies to overload (7) ⭐

---

🍓 Example

// Run this code

#include <iostream>
#include <sstream>

int main()
{
    int n;

    std::istringstream in; // could also use in("1 2")
    in.str("1 2");
    in >> n;
    std::cout << "After reading the first int from \"1 2\", the int is "
              << n << ", str() = \"" << in.str() << "\"\n";

    std::ostringstream out("1 2");
    out << 3;
    std::cout << "After writing the int '3' to output stream \"1 2\""
              << ", str() = \"" << out.str() << "\"\n";

    std::ostringstream ate("1 2", std::ios_base::ate);
    ate << 3;
    std::cout << "After writing the int '3' to append stream \"1 2\""
              << ", str() = \"" << ate.str() << "\"\n";
}

🌟 Output

After reading the first int from "1 2", the int is 1, str() = "1 2"
After writing the int '3' to output stream "1 2", str() = "3 2"
After writing the int '3' to append stream "1 2", str() = "1 23"

look at that. three streams, three little reveals. the ate one ate, honestly 🔥

---

🧚 See also

• rdbuf — returns the underlying raw string device object (public member function)
• str — replaces or obtains a copy of the associated character string (public member function of std::basic_stringbuf<CharT,Traits,Allocator>)

---

and that's the page, bestie 🦋 go forth and not dangle any pointers 💖

— http://cppreference.com, 2024.06.10 🌸 slay ✨