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 Class Reference 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() function for setting the stream's error state. It automatically throws the 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. Hence, imbuing a stream with a new locale will only affect the stream's locale and never the stream buffer's locale.15
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 would cause a deadlock in a multithreading situation, since the sentry object locks the stream through the stream's mutex (= mutual 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 stream's 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.
Let us now go back and apply the recommendations to the extractor and inserter for class date in the example we have been constructing. Here is an improved version of the extractor:
template<class charT, class Traits>
basic_istream<charT, Traits>& operator >>
(basic_istream<charT, Traits >& is, date& dat)
{
ios_base::iostate err = 0; //1
try { //2
typename basic_istream<charT, Traits>::sentry ipfx(is); //3
if(ipfx) //4
{
use_facet<time_get<charT,Traits> >(is.getloc())
.get_date(is, istreambuf_iterator<charT,Traits>()
,is, err, &dat.tm_date); //5
if (!dat) err |= ios_base::failbit; //6
}
} // try
catch(...) //7
{
bool flag = FALSE;
try { is.setstate(ios_base::failbit); } //8
catch( ios_base::failure ) { flag= TRUE; } //9
if ( flag ) throw; //10
}
if ( err ) is.setstate(err); /11
return is;
}
| //1 | The variable err will keep track of errors as they occur. In this example, it is handed over to the time_get facet, which will set 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 has a conversion to bool that allows this kind of check. |
| //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, e.g., 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 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>
basic_ostream<charT, Traits>& operator <<
(basic_ostream<charT, Traits >& os, const date& dat)
{
ios_base::iostate err = 0;
try {
typename basic_ostream<charT, Traits>::sentry opfx(os);
if(opfx)
{
char patt[3] = "%x";
charT fmt[3];
use_facet<ctype<charT> >(os.getloc())
.widen(patt,patt+2,fmt); //1
if (
use_facet<time_put<charT,ostreambuf_iterator<charT,Traits> > >
(os.getloc())
.put(os,os,os.fill(),&dat.tm_date,fmt,(fmt+2)) //2
.failed() //3
)
err = ios_base::badbit; //4
os.width(0); //5
}
} //try
catch(...)
{
bool flag = FALSE;
try {
os.setstate(ios_base::failbit);
}
catch( ios_base::failure ) { 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 iterators 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. |
Why is it seemingly so complicated to implement an inserter or extractor? Why doesn't the first simple approach suffice?
First, it is not really as complicated as it seems if you stick to the patterns: we give these patterns in the next section. Second, 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 is not a great concern.
However, whenever you care about the runtime efficiency of your input and output operations, it is advisable to access the stream buffer directly. In such cases, you will be using fast low-level services and hence will have to add format control, error handling, etc., because low-level services do not handle this for you. In our example, we aimed at optimal performance; the extractor and inserter for locale-dependent parsing and formatting of dates are very efficient because the facets directly access the stream buffer. In all these cases, you should follow the patterns we are about to give.
©Copyright 1998, Rogue Wave Software, Inc.
Send mail to report errors or comment on the documentation.