Module StreamSequenceInput.c

Detailed Description

Converts an input stream into a data sequence.

Author

Creighton, T. D.

Description

These routines read data from the I/O stream *stream until the end-of-input is reached. (The input can be of arbitrary length; the data is temporarily stored in a linked list of buffers.) Once read, a LAL sequence structure **sequence is created and the data stored in it. The routine passes back a pointer to the new structure.

The routine LALCHARReadSequence() simply stores the entire remaining contents of the I/O stream in a CHARSequence, including whitespace, newline '
', null '\0', or other special characters. (It can in principle be used to read and store binary data as a sequence of bytes. Note that the end-of-transmission byte '\004' does not necessarily mark the end-of-input, which is instead determined using the feof() function.)

The other routines in this module interpret the input as a sequence of whitespace-separated numbers, which are parsed directly from the I/O stream using fscanf(). The sequence is terminated at the end-of-input or at any point where fscanf() is unable to parse the input.

For the complex input routines LALCReadSequence() and LALZReadSequence(), each pair of numbers read are interpreted as the real and imaginary parts of a complex number. The usual input format is for each line to contain a pair of numbers, but fscanf() does not distinguish between newline and other whitespace characters, so neither do these routines.

Unlike the numerical routines in other StreamInput.h modules, these routines have no mechanism to deal with comments; every whitespace-delimited substring will be treated as a number.

Algorithm

These routines read data into a linked list of buffers, to allow memory allocation to occur in batches for improved efficiency. The numerical routines also use fscanf() directly on the I/O stream to avoid the inefficiency of storing and parsing intermediate character strings, as is done by the corresponding vector sequence input routines. This reduces robustness and versatility (as indicated, for instance, by the inability of dealing with comments), and increases the number of potential points-of-failure (by requiring a consistent implementation across platforms of getc() and fscanf(), rather than the single function fgets() used by other stream input routines). However, these sacrifices are necessary to allow LAL applications to ingest large quantities of numerical data efficiently.

Prototypes
int	XLALCHARReadSequence (CHARSequence **sequence, FILE *stream)
void	LALCHARReadSequence (LALStatus *status, CHARSequence **sequence, FILE *stream)
void	LALI2ReadSequence (LALStatus *status, INT2Sequence **sequence, FILE *stream)
void	LALI4ReadSequence (LALStatus *status, INT4Sequence **sequence, FILE *stream)
void	LALI8ReadSequence (LALStatus *status, INT8Sequence **sequence, FILE *stream)
void	LALU2ReadSequence (LALStatus *status, UINT2Sequence **sequence, FILE *stream)
void	LALU4ReadSequence (LALStatus *status, UINT4Sequence **sequence, FILE *stream)
void	LALU8ReadSequence (LALStatus *status, UINT8Sequence **sequence, FILE *stream)
void	LALSReadSequence (LALStatus *status, REAL4Sequence **sequence, FILE *stream)
void	LALDReadSequence (LALStatus *status, REAL8Sequence **sequence, FILE *stream)
void	LALCReadSequence (LALStatus *status, COMPLEX8Sequence **sequence, FILE *stream)
void	LALZReadSequence (LALStatus *status, COMPLEX16Sequence **sequence, FILE *stream)

Function Documentation

XLALCHARReadSequence()

int XLALCHARReadSequence	(	CHARSequence **	sequence,
		FILE *	stream
	)

Definition at line 117 of file StreamSequenceInput.c.

LALCHARReadSequence()

void LALCHARReadSequence	(	LALStatus *	status,
		CHARSequence **	sequence,
		FILE *	stream
	)

Definition at line 47 of file StreamSequenceInput.c.

LALI2ReadSequence()

void LALI2ReadSequence	(	LALStatus *	status,
		INT2Sequence **	sequence,
		FILE *	stream
	)

LALI4ReadSequence()

void LALI4ReadSequence	(	LALStatus *	status,
		INT4Sequence **	sequence,
		FILE *	stream
	)

LALI8ReadSequence()

void LALI8ReadSequence	(	LALStatus *	status,
		INT8Sequence **	sequence,
		FILE *	stream
	)

LALU2ReadSequence()

void LALU2ReadSequence	(	LALStatus *	status,
		UINT2Sequence **	sequence,
		FILE *	stream
	)

LALU4ReadSequence()

void LALU4ReadSequence	(	LALStatus *	status,
		UINT4Sequence **	sequence,
		FILE *	stream
	)

LALU8ReadSequence()

void LALU8ReadSequence	(	LALStatus *	status,
		UINT8Sequence **	sequence,
		FILE *	stream
	)

LALSReadSequence()

void LALSReadSequence	(	LALStatus *	status,
		REAL4Sequence **	sequence,
		FILE *	stream
	)

LALDReadSequence()

void LALDReadSequence	(	LALStatus *	status,
		REAL8Sequence **	sequence,
		FILE *	stream
	)

LALCReadSequence()

void LALCReadSequence	(	LALStatus *	status,
		COMPLEX8Sequence **	sequence,
		FILE *	stream
	)

LALZReadSequence()

void LALZReadSequence	(	LALStatus *	status,
		COMPLEX16Sequence **	sequence,
		FILE *	stream
	)