std::basic_istream::sentry - cppreference.com

##### cppreference.com

##### Search

Create account

##### Namespaces

- Page
- Discussion

##### Variants

##### Views

- View
- Edit
- History

##### Actions

# std::basic_istream::sentry

From cppreference.com
< cpp‎ | io‎ | basic istream

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.

### [edit] Member types

`traits_type` | Traits

### [edit] Member functions

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

## std::basic_istream::sentry::sentry

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

Prepares the stream for formatted input.

If is.good() is false, calls is.setstate(failbit)(since c++11) 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() & 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(failbit | eofbit) (which may throw std::ios_base::failure).

Additional implementation-defined preparation may take place, which may call setstate(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.

## 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.

### [edit] Example

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

### [edit] See also

operator>> | extracts formatted data (public member function) [edit]
operator>>(std::basic_istream) | extracts characters and character arrays (function template) [edit]

Retrieved from "http://en.cppreference.com/mwiki/index.php?title=cpp/io/basic_istream/sentry&oldid=69993"