public member class
<istream> <iostream>

std::istream::sentry

class sentry;
Prepare stream for input
Member class that performs a series of operations before and after each input operation:

Its constructor performs the following operations on the stream object passed as its argument (in the same order):

In case of failure during construction, it may set the stream's failbit flag.

There are no required operations to be performed by its destructor. But implementations may use the construction and destruction of sentry objects to perform additional initialization or cleanup operations on the stream common to all input operations.

All member functions that perform an input operation automatically construct an object of this class and then evaluate it (which returns true if no state flag was set). Only if this object evaluates to true, the function attempts the input operation (otherwise, it returns without performing it). Before returning, the function destroys the sentry object.

The operator>> formatted input operations construct the sentry object by passing false as second argument (which skips leading whitespaces). All other member functions that construct a sentry object pass true as second argument (which does not skip leading whitespaces).

The structure of this class is:
1
2
3
4
5
6
7
8
9
 
class sentry {
public:
  explicit sentry (istream& is, bool noskipws = false);
  ~sentry();
  operator bool() const;
private:
  sentry (const sentry&);             // not defined
  sentry& operator= (const sentry&);  // not defined
};

1
2
3
4
5
6
7
8
 
class sentry {
public:
  explicit sentry (istream& is, bool noskipws = false);
  ~sentry();
  explicit operator bool() const;
  sentry (const sentry&) = delete;
  sentry& operator= (const sentry&) = delete;
};


Members

explicit sentry (istream& is, bool noskipws = false);
Prepares the output stream for an output operation, performing the actions described above.
~sentry();
Performs no operations (implementation-defined).
explicit operator bool() const;
When the object is evaluated, it returns a bool value indicating whether the sentry constructor successfully performed all its tasks: If at some point of the construction process, an internal error flags was set, this function always returns false for that object.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
 
// istream::sentry example
#include <iostream>     // std::istream, std::cout
#include <string>       // std::string
#include <sstream>      // std::stringstream
#include <locale>       // std::isspace, std::isdigit

struct Phone {
  std::string digits;
};

// custom extractor for objects of type Phone
std::istream& operator>>(std::istream& is, Phone& tel)
{
    std::istream::sentry s(is);
    if (s) while (is.good()) {
      char c = is.get();
      if (std::isspace(c,is.getloc())) break;
      if (std::isdigit(c,is.getloc())) tel.digits+=c;
    }
    return is;
}

int main () {
  std::stringstream parseme ("   (555)2326");
  Phone myphone;
  parseme >> myphone;
  std::cout << "digits parsed: " << myphone.digits << '\n';
  return 0;
}


Output:

digits parsed: 5552326

See also

istream::operator>>
Extract formatted input (public member function )

C++

<istream>