std::basic_istream::sentry(3)

🌸 NAME — std::basic_istream::sentry 🌸

Okay bestie, this is the std::basic_istream::sentry(3) page from the C++ Standard Libary manual, and it's literally the tiny main-character bodyguard for your input stream 💅✨.

std::basic_istream::sentry — the sentry class. No cap, that's the name.

🦋 Synopsis 🦋

class sentry;

An object of class basic_istream::sentry is constructed in local scope at the beginning of each member function of std::basic_istream that performs input (both formatted and unformatted). Its constructor prepares the input stream: checks if the stream is already in a failed state, flushes the tie()'d output streams, skips leading whitespace unless noskipws flag is set, and performs other implementation-defined tasks if necessary. All cleanup, if necessary, is performed in the destructor, so that it is guaranteed to happen if exceptions are thrown during input.

👑 Member types 👑

• traits_type — Traits.

🎀 Member functions 🎀

Lowkey tiny section, highkey important:

• constructor — constructs the sentry object. All the preparation tasks are done here (public member function).
• destructor — finalizes the stream object after formatted input or after exception, if necessary (public member function).
• operator= — not copy assignable [deleted] (public member function).
• operator bool — checks if the preparation of the stream object was successful (public member function).

💖 std::basic_istream::sentry::sentry 💖

explicit sentry( std::basic_istream<CharT, Traits>& is, bool noskipws = false );

Prepares the stream for formatted input. Here's the whole prep routine, bestie — read it fr fr:

• If is.good() is false, calls is.setstate(std::ios_base::failbit) and returns.
• Otherwise, if is.tie() is not a null pointer, calls is.tie()->flush() to synchronize the output sequence with external streams. This call can be suppressed if the put area of is.tie() is empty. The implementation may defer the call to flush() until a call of is.rdbuf()->underflow() occurs. If no such call occurs before the sentry object is destroyed, it may be eliminated entirely.
• If noskipws is zero and is.flags() & std::ios_base::skipws is nonzero, the function extracts and discards all whitespace characters until the next available character is not a whitespace character (as determined by the currently imbued locale in is). If is.rdbuf()->sbumpc() or is.rdbuf()->sgetc() returns traits::eof(), the function calls setstate(std::ios_base::failbit | std::ios_base::eofbit) (which may throw std::ios_base::failure).
• Additional implementation-defined preparation may take place, which may call setstate(std::ios_base::failbit) (which may throw std::ios_base::failure).
• If after preparation is completed, is.good() == true, then any subsequent calls to operator bool will return true.

🌈 Parameters 🌈

• is — input stream to prepare.
• noskipws — true if whitespace should not be skipped.

🔥 Exceptions 🔥

std::ios_base::failure if the end of file condition occurs when skipping whitespace.

🦋 std::basic_istream::sentry::~sentry 🦋

~sentry();

Does nothing. Literally nothing, it's off the clock 💀✨.

⭐ std::basic_istream::sentry::operator bool ⭐

explicit operator bool() const;

Checks whether the preparation of the input stream was successful.

Parameters

(none)

Return value

true if the initialization of the input stream was successful, false otherwise.

🍓 Example 🍓

This example ate and left no crumbs 🍓

// Run this code

#include <iostream>
#include <sstream>

struct Foo
{
    char n[5];
};

std::istream& operator>>(std::istream& is, Foo& f)
{
    std::istream::sentry s(is);
    if (s)
        is.read(f.n, 5);
    return is;
}

int main()
{
    std::string input = "   abcde";
    std::istringstream stream(input);
    Foo f;
    stream >> f;
    std::cout.write(f.n, 5);
    std::cout << '\n';
}

🌸 Output 🌸

abcde

🧚 Defect reports 🧚

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

• LWG 195 — Applied to C++98. Behavior as published: it was unclear whether the constructor would set eofbit. Correct behavior: made clear.
• LWG 419 — Applied to C++98. Behavior as published: the constructor did not set failbit if eofbit has been set. Correct behavior: sets failbit in this case.

💜 See also 💜

• operator>> — extracts formatted data (public member function).
• operator>>(std::basic_istream) — extracts characters and character arrays (function template).

---

Okay bestie, that's the whole page! Source/version/date tea: http://cppreference.com, 2024.06.10, manual std::basic_istream::sentry(3) 💖✨🫶