Header StringInput.h

Detailed Description

Provides routines to parse CHARVectors into other LAL datatypes.

Author

Creighton, T. D.

Synopsis

#include "StringInput.h"

This header provides prototypes for routines that construct LAL data structures using the data from a character string. As in standard C, a string is a block of non-null bytes of arbitrary length, terminated by a null byte '\0', and referred to by a value of type CHAR * pointing to the first byte in the string. It is not to be confused with a CHARVector, a LAL structure referring to a block of data of a specified length, which may or may not contain one or more instances of '\0'.

In general, the routines under this header will have string inputs of type const CHAR * (in order to allow, for instance, string literals to be used as inputs), but will allocate CHARVector structures to store string outputs. Unless otherwise specified, these outputs are guaranteed to contain at least one '\0' character, so their data fields are valid strings. It is the responsibility of the calling routine to ensure that the string input contains a terminating '\0' within the memory segment pointed to by the CHAR * input, in order to avoid segmentation violation.

These routines are intended to work in conjunction with the functions in StreamInput.h to add LAL robustness to otherwise ad-hoc data input routines. However, the functions in StringInput.h are fully LAL-compliant and use only LAL types, so they are included in liblal proper.

Constants

The following constants are format strings that can be used by the various C scanf() or printf() functions to parse or write sequences of characters corresponding to base LAL datatypes. Since the C datatypes (short, int, long, long long, float, double, etc.) do not have fixed mappings to LAL base datatypes (INT2, INT4, INT8, REAL4, REAL8, etc.), the appropriate format strings for each LAL datatype must be determined at configuration time and set at compile time.

These format strings give only the conversion character preceded by any length modifier according to the type (short, long, etc.). In particular they do not contain the initial '' character that initiates the conversion specification. However, being #defined string literals, they can be combined with "%" string literals or more complicated format strings through implicit concatenation. Thus to scan string for a UINT4 number n one would write:

sscanf( string, "%" LAL_UINT4_FORMAT, &n );

Similarly, to print a REAL8 number x with 12 digits following the decimal place, one could use the following:

printf( "%.12" LAL_REAL8_FORMAT, x );

Of course, floating-point numbers are more commonly printed using the "%e" conversion specifier, which does not generally require type-dependent length modifiers.

Name	Usual value
LAL_INT2_FORMAT	"hd"
LAL_INT4_FORMAT	"d" or "ld"
LAL_INT8_FORMAT	"ld" or "lld"
LAL_UINT2_FORMAT	"hu"
LAL_UINT4_FORMAT	"u" or "lu"
LAL_UINT8_FORMAT	"lu" or "llu"
LAL_REAL4_FORMAT	"f"
LAL_REAL8_FORMAT	"lf"

Data Structures
struct	TokenList
	This structure stores a number of null-terminated strings of arbitrary length. More...

Files
file	StringConvert.c
	Converts a string into a numerical value.
file	StringToken.c
	Converts a string into a series of tokens, for use by other routines.

Error Codes
#define	STRINGINPUTH_ENUL   1
	Unexpected null pointer in arguments. More...
#define	STRINGINPUTH_EOUT   2
	Output handle points to a non-null pointer. More...
#define	STRINGINPUTH_EMEM   3
	Memory allocation error. More...

Macro Definition Documentation

STRINGINPUTH_ENUL

#define STRINGINPUTH_ENUL   1

Unexpected null pointer in arguments.

Definition at line 120 of file StringInput.h.

STRINGINPUTH_EOUT

#define STRINGINPUTH_EOUT   2

Output handle points to a non-null pointer.

Definition at line 121 of file StringInput.h.

STRINGINPUTH_EMEM

#define STRINGINPUTH_EMEM   3

Memory allocation error.

Definition at line 122 of file StringInput.h.