When should I concern myself with std::iostream::sentry?

Question

Online references have rather brief and vague descriptions on the purpose of std::iostream::sentry. When should I concern myself with this little critter? If it's only intended to be used internally, why make it public?

Answer 1

It's used whenever you need to extract or output data with a stream. That is, whenever you make an operator>>, the extraction operator, or operator<<, the insertion operator.

It's purpose is to simplify the logic: "Are any fail bits set? Synchronize the buffers. For input streams, optionally get any whitespace out of the way. Okay, ready?"

All extraction stream operators should begin with:

// second parameter to true to not skip whitespace, for input that uses it const std::istream::sentry ok(stream, icareaboutwhitespace);  if (ok) {     // ... } 

And all insertion stream operators should begin with:

const std::ostream::sentry ok(stream);   if (ok) {     // ... } 

It's just a cleaner way of doing (something similar to):

if (stream.good()) {     if (stream.tie())         stream.tie()->sync();      // the second parameter     if (!noskipwhitespace && stream.flags() & ios_base::skipws)     {         stream >> std::ws;                 } }  if (stream.good()) {     // ... } 

ostream just skips the whitespace part.

Answer 2

Most people will never write any code that needs to deal with creating sentry objects. A sentry object is needed when/if you extract data from (or insert it into) the stream buffer that underlies the stream object itself.

As long as your insertion/extraction operator uses other iostream members/operators to do its work, it does not have to deal with creating a sentry object (because those other iostream operators will create and destroy sentry objects as needed).