Module StreamSeriesOutput.c

Writes a time or frequency series to an output stream.

Author

Creighton, T. D.

Prototypes

void
LAL<typecode>WriteTSeries( LALStatus            *stat,
FILE                 *stream,
<datatype>TimeSeries *series )
 
void
LAL<typecode>WriteTVectorSeries( LALStatus                  *stat,
FILE                       *stream,
<datatype>TimeVectorSeries *series )
 
void
LAL<typecode>WriteTArraySeries( LALStatus                 *stat,
FILE                      *stream,
<datatype>TimeArraySeries *series )
 
void
LAL<typecode>WriteFSeries( LALStatus                 *stat,
FILE                      *stream,
<datatype>FrequencySeries *series )

Description

These routines write the data and metadata in a time or frequency series *series to an output stream *stream in a standard format, described below. It returns an error if any attempt to write to the stream failed; *stream may then be left in a partially-written state.

For each of these prototype templates there are in fact 10 separate routines corresponding to all the atomic datatypes <datatype> (except CHAR) referred to by <typecode>:

<typecode>	<datatype>	<typecode>	<datatype>
I2	INT2	U2	UINT2
I4	INT4	U4	UINT4
I8	INT8	U8	UINT8
S	REAL4	C	COMPLEX8
D	REAL8	Z	COMPLEX16

Format for *stream:

The data written to the output stream will be formatted in a manner consistent with the input routines in StreamSeriesInput.c. That is, it will begin with a metadata header, consisting of multiple lines of the form:

# fieldname=value

where fieldname is the name of a field in *series and value is the value of that metadata field, in some standard format (below). The following metadata fields will be written, one per line, based on the type of *series:

<datatype>TimeSeries:

datatype, name,epoch, deltaT, f0, sampleUnits,length

<datatype>TimeVectorSeries:

datatype,name, epoch, deltaT, f0,sampleUnits, length, vectorLength

<datatype>TimeArraySeries:

datatype,name, epoch, deltaT, f0,sampleUnits, length, dimLength, arrayDim

<datatype>FrequencySeries:

datatype,name, epoch, deltaT, f0, deltaF,sampleUnits, length

After all metadata have been written, the contents of series->data->data will be written in standard integer or floating-point notation, according to <datatype>: integers will be written to full precision, while floating-point numbers will be written in exponential notation with sufficient digits to ensure that they represent a unique binary floating-point number under the IEEE Standard 754 (this means 9 digits for REAL4s and 17 digits for REAL8s). Complex datatypes are represented by pairs of floating-point numbers representing alternately the real and imaginary parts.

The body of the file will be formatted with newlines '\n' separating individual base, complex, vector, or array valued elements of the sequence series->data. Within each element, integer or floating-point components will be separated by single ' ' characters. Thus the value of series->data->length will always equal the number of lines following the metadata header.

Format for metadata fields:

Here we summarize briefly the format for the individual field values in the metadata header.

datatype:

value is a string (not surrounded by quotes) corresponding to the type of *series; e.g. COMPLEX8FrequencySeries.

name:

value is a string surrounded by double-quotes representing series->name. Standard C-language string literal notation is used: printable characters are written directly except for double-quotes and \ (rendered as \), characters with special C escape sequences are written as those sequences (e.g. \t for tab and \n for newline), and all other character bytes are written as three-digit octal codes \ooo. Writing stops at the first null byte \0.

epoch:

value is a single INT8 number representing series->epoch in GPS nanoseconds.

deltaT

(any time series): value is a single REAL8 number representing series->deltaT.

f0:

value is a single REAL8 number representing series->f0.

deltaF

(FrequencySeries only): value is a single REAL8 number representing series->deltaF.

sampleUnits:

value is string surrounded by double-quotes; inside the quotes is a unit string corresponding to series->sampleUnits as converted by the routine XLALUnitAsString().

length:

value is a single UINT4 representing series->data->length.

vectorLength

(TimeVectorSeries only): value is a single UINT4 representing series->data->vectorLength.

dimLength

(TimeArraySeries only): value consists of a sequence of UINT4s separated by single ' ' characters, representing the components of series->data->dimLength->data. The value of series->data->dimLength->length must be inferred from the number of components; it is not given as separate metadata.

arrayDim

(TimeArraySeries only): value is a single UINT4 representing series->data->arrayDim. If the array sequence was properly constructed, this will equal the product of the components of dimLength, above.