More Improved Extractors and Inserters

Previous file Top of Document Contents Index page Next file

Apache C++ Standard Library User's Guide

32.5 More Improved Extractors and Inserters

Insertion and extraction still do not fit seamlessly into the iostream framework. The inserters and extractors for built-in types can be controlled through formatting flags that our operators thus far ignore. Our operators don't observe a field width while inserting, or skip whitespaces while extracting, and so on.

They don't care about error indication either. So what if the extracted date is February 31? So what if the insertion fails because the underlying buffer can't access the external device for some obscure reason? So what if a facet throws an exception? We should certainly set some state bits in the respective stream's state and throw or rethrow exceptions, if the exception mask says so.

However, the more general question here is: What are inserters and extractors supposed to do? Some recommendations follow.

Regarding format flags, inserters and extractors should:

Create a sentry object right at the beginning of every inserter and extractor. In its constructor and destructor, the sentry performs certain standard tasks, like skipping white characters, flushing tied streams, etc. See the Apache C++ Standard Library Reference Guide for a detailed explanation.
Reset the width after each usage.

Regarding state bits, inserters and extractors should:

Set badbit for all problems with the stream buffer.
Set failbit if the formatting or parsing itself fails.
Set eofbit when the end of the input sequence is reached.

Regarding the exception mask, inserters and extractors should:

Use the setstate() member function for setting the stream's error state. It automatically throws the std::ios_base::failure exception according to the exceptions switch in the stream's exception mask.
Catch exceptions thrown during the parsing or formatting, set failbit or badbit, and rethrow the original exception.

Regarding locales, inserters and extractors should:

Use the stream's locale, not the stream buffer's locale. The stream buffer's locale is supposed to be used solely for code conversion.

Regarding the stream buffer:

If you use a sentry object in your extractor or inserter, you should not call any functions from the formatting layer. This might cause a deadlock in a thread-safe library, since the sentry object locks the stream buffer associated with the stream object through the stream buffer's mutex (mutually exclusive lock). A nested call to one of the stream's member functions would again create a sentry object, which would wait for the same mutually exclusive lock and, voilà, you have deadlock. Use the stream buffer's functions instead. They do not use the mutex, and are more efficient anyway.

NOTE -- Do not call the stream's input or output functions after creating a sentry object in your inserter or extractor. Use the stream buffer's functions instead.

32.5.1 Applying the Recommendations to the Example

Let us now go back and apply the recommendations to the extractor and inserter for class date in the example we are constructing. Here is an improved version of the extractor:

template<class charT, class Traits>
std::basic_istream<charT, Traits>& 
operator >> (std::basic_istream<charT, Traits >& is, date& dat)
{
 std::ios_base::iostate err = 0; //1
 try { //2
 typename std::basic_istream<charT,
 Traits>::sentry ipfx(is); //3
 if(ipfx) { //4
 std::use_facet<std::time_get<charT,Traits> >
 (is.getloc())
 .get_date(is,
 std::istreambuf_iterator<charT,Traits>(),
 is, err, &dat.tm_date); //5
 if (!dat)
 err |= std::ios_base::failbit; //6
 }
 }
 catch(...) { //7
 bool flag = false;
 try {
 is.setstate(std::ios_base::failbit); //8
 }
 catch(...) {
 flag = true; //9
 }
 if (flag)
 throw; //10
 }
 if (err)
 is.setstate(err); //11
 return is;
}

//1 The variable err keeps track of errors as they occur. In this example, it is handed over to the time_get facet, which sets the respective state bits.

//2 All operations inside an extractor or inserter should be inside a try-block, so that the respective error states could be set correctly before the exception is actually thrown.

//3 Here we define the sentry object that does all the preliminary work, like skipping leading white spaces.

//4 We check whether the preliminaries were done successfully. Class sentry defines a conversion to bool that returns true if the sentry constructor completed successfully, and false otherwise.

//5 This is the call to the time parsing facet of the stream's locale, as in the primitive version of the extractor.

//6 Let's assume our date class allows us to check whether the date is semantically valid; for example, it would detect wrong dates like February 30. Extracting an invalid date should be treated as a failure, so we set the failbit.

//7 Note that in this case it is not advisable to set the failbit through the stream's setstate() function, because setstate() also raises exceptions if they are switched on in the stream's exception mask. We don't want to throw an exception at this point, so we add the failbit to the state variable err.

//8 Here we catch all exceptions that might have been thrown so far. The intent is to set the stream's error state before the exception terminates the extractor, and to rethrow the original exception.

//9 Now we eventually set the stream's error state through its setstate() function. This call might throw an std::ios_base::failure exception according to the stream's exception mask.

//10 We catch this exception because we want the original exception thrown rather than the ios_base::failure in all cases.

//11 We rethrow the original exception. If there was no exception raised so far, we set the stream's error state through its setstate() function.

The inserter is implemented using the same pattern:

template<class charT, class Traits>
std::basic_ostream<charT, Traits>& 
operator << (std::basic_ostream<charT, Traits >& os,
 const date& dat)
{
 std::ios_base::iostate err = 0;
 try {
 typename std::basic_ostream<charT, Traits>::sentry opfx(os);
 if(opfx) {
 const char patt[3] = "%x";
 charT fmt[3];
 std::use_facet<std::ctype<charT> >(os.getloc())
 .widen(patt, patt+2, fmt); //1
 typedef std::time_put<charT,
 ostreambuf_iterator<charT,Traits> >
 time_put;
 if (std::use_facet<time_put>(os.getloc())
 .put(os,os,os.fill(),&dat.tm_date,fmt,(fmt+2)) //2
 .failed()) //3
 err = std::ios_base::badbit; //4
 os.width(0); //5
 }
 }
 catch(...) {
 bool flag = false;
 try {
 os.setstate(std::ios_base::failbit);
 }
 catch(...) {
 flag = true;
 }
 if (flag)
 throw;
 }
 if (err)
 os.setstate(err);
 return os;
}

The inserter and the extractor have only a few minor differences:

//1 We prefer to use the other put() function of the locale's time_put facet. It is more flexible and allows us to specify a sequence of format specifiers instead of just one. We declare a character array that contains the sequence of format specifiers and widen it to wide characters, if necessary.

//2 Here we provide the format specifiers to the time_put facet's put() function.

//3 The put() function returns an iterator pointing immediately after the last character produced. We check the success of the previous output by calling the streambuf iterator's failed() function.

//4 If the output failed then the stream is presumably broken, and we set badbit.

//5 Here we reset the field width, because the facet's put() function uses the stream's format settings and adjusts the output according to the respective field width. The rule is that the field width shall be reset after each usage.

32.5.2 An Afterthought

Why is it seemingly so complicated to implement an inserter or extractor? Why doesn't the first simple approach suffice?

The simple extractors and inserters in our first approach do suffice in many cases, when the user-defined type consists mostly of data members of built-in types, and runtime efficiency or atomicity of output is not a great concern.

Working directly with the stream buffer may be necessary:

To improve runtime speed
To guarantee atomic operations on a stream which may be shared among threads

In these cases, you use fast, low-level services. You must decide whether or not to add format control, error handling, and so on, depending on the needs of your application. If you need these capabilities, you must provide them yourself. You must provide a sentry, and be careful to avoid deadlock by only calling functions on the stream buffer itself.

Working with the stream buffer directly need not be as complicated as it seems. The next section contains patterns that provide outlines for you to fill in. The patterns include error-handling, and guarantee atomicity thanks to the single sentry object they create.

Previous file Top of Document Contents Index page Next file