HOWTO implement an input stream

The base class datrw::idatstream takes care of many organizational issues for you. You are only responsible to provide code which is capable to actually read the data from a file stream.

You have to provide at least a derived stream class like datrw::isffstream, which has to be equipped with:

• a static field like datrw::isffstream::openmode, which indicates the stream open mode which should be used for the C++ ostream (this field is used to distinguish between ASCII and binary data files)
• a constructor like datrw::isffstream::isffstream(), which calls the base class constructor datrw::idatstream::idatstream() and passes the appropriate flags;

  See also

  Constructor of stream class

• four virtual functions like
  • Tdseries datrw::isffstream::dseries(),
  • Tfseries datrw::isffstream::fseries(),
  • Tiseries datrw::isffstream::iseries(), and/or
  • void datrw::isffstream::skipseries()
  these functions are responsible to read the actual trace data from file; this includes the WID2 data, the INFO data, the trace FREE block, and the actual time series which is returned by the function;

  See also

  Reading the samples, Skipping a trace

• a function like datrw::isffstream::help(), which returns some details on the underlying file format properties to an output stream as online help for the end-user
• a virtual destructor like datrw::isffstream::~isffstream(); the destructor in most cases has an empty function body

That's all.

Finally check files readany.h, readany.cc, formats.h, and formats.cc and add appropriate lines to make the new stream visible through the generic interface of datrw::ianystream and the functions presented in readany.h.

Constructor of stream class

The constructor of the input stream initializes its base class datrw::idatstream by passing appropriate parameter values to the constructor datrw::idatstream::idatstream(). The parameters to datrw::idatstream::idatstream() indicate, wheter the stream will provide integer data through virtual member function iseries(), single presicion data through virtual member function fseries(), and/or double presicion data through virtual member function dseries(). Only implement those of the virtual sample access functions, which are supported indeed. For other request the base class will then throw an exception.

See also

datrw::idatstream::iseries(), datrw::idatstream::fseries(), datrw::idatstream::dseries()

For reading from the C++ input stream, the member data datrw::idatstream::Mis is provided to all derived classes.

After initializing the base class, the constructor reads a file header if there is one. The information read from file are passed to the base class through functions

• datrw::idatstream::setfilefree() and

  this->setfilefree(freeblock);

• datrw::idatstream::setsrce().

  this->setsrce(srceline);

These functions will set flags appropriately and store the information in member data fields, such that they can be provided to the user through the base class interface functions.

• datrw::idatstream::hasfree(),
• datrw::idatstream::free(),
• datrw::idatstream::hassrce(), and
• datrw::idatstream::srce().

Reading the samples

The actual reading of traces is controlled by virtual member functions iseries(), fseries(), and dseries(). They all three behave identical and just return series containers of different content type. Only those supported have to be implemented (see above). Each of these functions does the following:

1. Call the base class member function datrw::idatstream::newtrace()

   this->newtrace();

2. Read the trace (trace header and samples). In most cases it is efficient to implement a private member function readheader() like datrw::isustream::readheader(), which reads the header fields for the current trace and passes them to the base class member fields, since this operation is identical for all reading functions. Member functions are then used to set the member data fields. The samples of the time series trace have to be read then into a series container of appropriate type and be returned by the member function. Member functions to set trace header data to member data fields are:
   • datrw::idatstream::setwid2(),

     this->setwid2(wid2line);

   • datrw::idatstream::setinfo(), and

     this->setinfo(infoline);

   • datrw::idatstream::settracefree()

     this->settracefree(freeblock);

3. If the trace just read is the last trace in the input stream, the base class function datrw::idatstream::setlast() has to be called.

   this->setlast();

In some cases it is efficient to implement only one of the reading functions with all details and to implement the others by simple type conversion, like datrw::isustream::dseries(). When reading ASCII data the template function datrw::util::readasciidouble() can be useful.

Skipping a trace

The skipseries() member function is implemented exactly like the trace reading functions. This function has to read the trace header too and must pass the parameters of the trace header to the appropriate member data fields. It just does not allocate memory to read samples. This can make this function slightly more efficient, if the user just wants to scan the data file and check trace header information.

See also

HOWTO read data of any supported format, Description of reading operation, HOWTO implement an output stream, HOWTO use format modifiers

Date

09/2011