All input streams are derived from datrw::idatstream. The interface of datrw::idatstream consequently defines the behaviour of all input stream classes. datrw::ianystream implements the same interface and behaviour. It is a general input stream, more or less, which selects one of the implemented stream classes based on the second parameter passed to its constructor datrw::ianystream::ianystream().

So, what happens when you are up to read a file?

Reading the file header

You create an instance of the input stream class by passing an C++ istream (usually a std::ifstream opened with the appropriate open mode as indicated by openmode of the libdatrwxx input stream class, like datrw::isffstream::openmode) from which data should be read to the constructor of the stream class. The constructor of the input stream starts reading the file by parsing the file header. Before continuing by reading the trace data, the user can extract information from the file header. This is done by the file header query functions

At this stage the functions datrw::idatstream::hasfree() and datrw::idatstream::free() provide access to the FREE block of the file header. After reading the first trace, the FREE block of the file header will no longer be accessible. This sequential behaviour ist the only way to distinguish between file FREE blocks and trace FREE blocks together with input operators.

Reading samples from a trace

Then the user continues by reading the samples of the first trace in the file by calling one of the series query functions

These functions immediately return a container of type aff::Series of appropriate type (as provided by typedefs datrw::Tdseries, datrw::Tfseries, and datrw::Tiseries). Not all of them may be provided by a specific stream class. To check for the available types, use the sample type query functions

The available data types usually reflect the data types used within the data file. Usually input stream classes for data formats containing floating point values for the samples do not provide integer type series query functions.

Reading a trace header

While parsing the trace data, the input stream classes collect trace header information. After returning the samples, this data is available through the header query functions

A WID2 line is provided in any case, containing data like the time of the first sample, the sampling rate and the number of samples. Notice that the functions datrw::idatstream::hasfree() and datrw::idatstream::free() now operate on the FREE block of the trace.

Reading the next trace

If the input provides more than one trace, the user continues to call the series query functions, causing the stream class to parse the next trace. After returning the trace data, the header data for this trace is available through the header query functions. The state query functions

indicate whether further data can be expected in the file.

What is skipseries() for?

Some file formats produce a significant overhead when data actually is read. One example is the class datrw::imseedstream for reading MiniSEED data. If the users likes to fast-forward to trace number 27, it is very inefficient to actually decode traces 1 to 26. In such a case calling the skip function

datrw::idatstream::skipseries()

for traces 1 to 26 and using one of the series query functions for trace 27 only can speed up the whole procedure. This however ist not the case for all file formats. The classes for reading multiplexing file formats like HPMO (datrw::ihpmostream) and TSOFT (datrw::itsoftstream) have to decode all traces at once and buffer them in internal storage in any case.

Nevertheless, datrw::idatstream::skipseries() parses the header data of the trace and provides all the extracted information through the header query functions. For this reason, using the skip function is a convenient way to browse a whole data file quickly to check its contents.

Ever heard of input operators?

Input operators support an easy way to apply the modules in this library. Almost all data query functions (be it header data or trace samples) can be accessed through input operators. This is the case for all classes. The operators are provided in namespace datrw.

See also: HOWTO read data of any supported format, datrw

Date: 11/2010