Synopsis

#include "StreamInput.h"

This header provides prototypes for routines that construct LAL data structures using the data from a file (or other I/O) stream. The routines do not provide a system-level interface to create files and open or close file streams; they simply assume that they have been passed an open, readable stream. Nonetheless, because they involve I/O stream manipulation, these routines are placed in the lalsupport library rather than in lal proper.

The routines in StreamVectorInput.c and StreamVectorSequenceInput.c are compartmentalized in such a way that they can easily be converted if the LAL specification later changes the way in which I/O streams are handled. In partucular, the only file I/O commands used are fgets() and feof(). Thus the upgrade would involve only the following global changes:

1. Replace all occurrences of FILE * with the name of the LAL I/O stream pointer type.
2. Replace all occurrences of fgets() and feof() with equivalent LAL functions.

In particular, there is no need to translate routines such as fscanf(); one should simply read data into a LAL CHARVector and then use sscanf() to format the input. This is the approach used in the numerical input routines in StreamVectorInput.c and StreamVectorSequenceInput.c.

The routines in StreamSequenceInput.c are less robust but much more efficient: they use fscanf() to parse the input stream directly. They are intended primarily for test programs that may need to read large datafiles of undetermined length. The routines in StreamSeriesInput.c and StreamGridInput.c also parse the input stream directly using fscanf(), to avoid potentially crippling computational overhead.