std::basic_ios::tie(3)

okay so welcome to std::basic_ios::tie(3) from the C++ Standard Libary — that's the manual name folded in near the top, bestie, and yes the header spells it "Libary" like that. 💅

💖 NAME 💖

The name is literally std::basic_ios::tie - std::basic_ios::tie. Iconic repetition, no notes.

✨ Synopsis ✨

std::basic_ostream<CharT, Traits>* tie() const;
(1)
std::basic_ostream<CharT, Traits>* tie( std::basic_ostream<CharT,
Traits>* str  (2)
);

This function manages the tied stream. A tied stream is an output stream which is synchronized with the sequence controlled by the stream buffer (rdbuf()), that is, flush() is called on the tied stream before any input/output operation on *this.

1. Returns the current tied stream. If there is no tied stream, a null pointer is returned.
2. Sets the current tied stream to str. Returns the tied stream before the operation. If there is no tied stream, a null pointer is returned. If str is not null and tie() is reachable by traversing the linked list of tied stream objects starting from str->tie(), the behavior is undefined. 🫠

🌸 Parameters 🌸

• str — an output stream to set as the tied stream.

🫶 Return value 🫶

The tied stream, or a null pointer if there was no tied stream.

😭 Exceptions 😭

May throw implementation-defined exceptions.

💅 Notes 💅

By default, the standard stream std::cout is tied to std::cin and std::cerr. Similarly, its wide counterpart std::wcout is tied to std::wcin and std::wcerr.

🎀 Example 🎀

// Run this code — yes bestie, run it:

#include <fstream>
#include <iomanip>
#include <iostream>
#include <string>

int main()
{
    std::ofstream os("test.txt");
    std::ifstream is("test.txt");
    std::string value("0");

    os << "Hello";
    is >> value;

    std::cout << "Result before tie(): " << std::quoted(value) << "\n";
    is.clear();
    is.tie(&os);

    is >> value;

    std::cout << "Result after tie(): " << std::quoted(value) << "\n";
}

🖥️ Output

Result before tie(): "0"
Result after tie(): "Hello"

🩹 Defect reports 🩹

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

• DR: LWG 835
• Applied to: C++98
• Behavior as published: two streams could be tied to each other^[1] (either directly or through another intermediate stream object)
• Correct behavior: the behavior is undefined in this case

1. ↑ std::basic_ostream::flush() is an UnformattedOutputFunction, so it creates a sentry object while being called. When flush() is called on a stream object, the constructor of the sentry object will call flush() on its tied stream, and that flush() will construct another sentry object and its constructor will call flush() on the tied stream of that stream and so on. Therefore, if streams a and b are (directly or indirectly) tied to each other, calling a.flush() will eventually call b.flush(), which will eventually call a.flush(), and will result in an infinite loop.

that's the whole page, bestie! source: http://cppreference.com, version/date: 2024.06.10 — now go tie your streams responsibly 💅✨