std::basic_istream::sync(3)

✨ std::basic_istream::sync(3) ✨

okay so welcome to the <pink>C++ Standard Libary</pink> page for std::basic_istream::sync, bestie 🫶. this one is short, iconic, and lowkey mysterious because "what does sync even do" is a whole vibe check. let's get into it. 💅

---

🌸 NAME 🌸

std::basic_istream::sync - std::basic_istream::sync (yes bestie, the name is the name — self-titled album energy, no cap 💿)

📜 Synopsis 📜

int sync();

The way that this works: it synchronizes the input buffer with the associated data source, periodt. It behaves as UnformattedInputFunction, except that gcount() is not affected. After constructing and checking the sentry object:

• If rdbuf() is a null pointer, it returns -1.
• Otherwise, it calls rdbuf()->pubsync(). If that function returns -1, it calls setstate(badbit) and returns -1. Otherwise, it returns 0.

That's literally the whole flow, fr fr.

🧾 Parameters 🧾

(none) — not me expecting parameters and getting none, she takes no arguments and she's still main character energy ✨

🔁 Return value 🔁

0 on success, -1 on failure or if the stream does not support this operation (is unbuffered). so if you get -1, it's giving "not supported" or "failed," not slay.

📝 Notes 📝

As with readsome(), it is implementation-defined whether this function does anything with library-supplied streams. The intent is typically for the next read operation to pick up any changes that may have been made to the associated input sequence after the stream buffer last filled its get area. To achieve that, sync() may empty the get area, or it may refill it, or it may do nothing. ngl, this is highkey unhinged behavior, but okay.

A notable exception is Visual Studio, where this operation discards the unprocessed input when called with a standard input stream. Visual Studio really said "unprocessed input? don't know her" 💀

💻 Example 💻

Demonstrates the use of input stream sync() with file input. Note that output here is implementation-defined, since calls to std::basic_filebuf::sync are implementation-defined for reads. so don't come for me if your output is different, bestie — that's the standard's whole thing.

Run this code:

#include <fstream>
#include <iostream>

void file_abc()
{
    std::ofstream f("test.txt");
    f << "abc\n";
}

void file_123()
{
    std::ofstream f("test.txt");
    f << "123\n";
}

int main()
{
    file_abc(); // file now contains "abc"
    std::ifstream f("test.txt");
    std::cout << "Reading from the file\n";
    char c;
    f >> c;
    std::cout << c;
    file_123(); // file now contains "123"
    f >> c;
    std::cout << c;
    f >> c;
    std::cout << c << '\n';
    f.close();

    file_abc(); // file now contains "abc"
    f.open("test.txt");
    std::cout << "Reading from the file, with sync()\n";
    f >> c;
    std::cout << c;
    file_123(); // file now contains "123"
    f.sync();
    f >> c;
    std::cout << c;
    f >> c;
    std::cout << c << '\n';
}

🌈 Possible output 🌈

Reading from the file
abc
Reading from the file, with sync()
a23

🩹 Defect reports 🩹

The following behavior-changing defect reports were applied retroactively to previously published C++ standards. retroactive glow-up, iykyk 💅

• DR LWG 62 — applied to C++98. Behavior as published: sync() returned traits::eof() if rdbuf()->pubsync() returns -1. Correct behavior: returns -1 in this case.

👀 See also 👀

• sync — synchronizes the buffers with the associated character sequence; [virtual] virtual protected member function of std::basic_streambuf<CharT,Traits>.
• flush — synchronizes with the underlying storage device; public member function of std::basic_ostream<CharT,Traits>.

---

signed, sealed, delivered by your fav C++ bestie 💌 — source/version/date: http://cppreference.com, 2024.06.10, page std::basic_istream::sync(3). this page ate, no cap — obsessed with this for us 🫶