Converts a string into a numerical value. More...

Prototypes
void	LALStringToU2 (LALStatus stat, UINT2 value, const CHAR string, CHAR *endptr)

void	LALStringToU4 (LALStatus stat, UINT4 value, const CHAR string, CHAR *endptr)

void	LALStringToU8 (LALStatus stat, UINT8 value, const CHAR string, CHAR *endptr)

void	LALStringToI2 (LALStatus stat, INT2 value, const CHAR string, CHAR *endptr)

void	LALStringToI4 (LALStatus stat, INT4 value, const CHAR string, CHAR *endptr)

void	LALStringToI8 (LALStatus stat, INT8 value, const CHAR string, CHAR *endptr)

void	LALStringToS (LALStatus stat, REAL4 value, const CHAR string, CHAR *endptr)

void	LALStringToD (LALStatus stat, REAL8 value, const CHAR string, CHAR *endptr)

void	LALStringToC (LALStatus stat, COMPLEX8 value, const CHAR string, CHAR *endptr)

void	LALStringToZ (LALStatus stat, COMPLEX16 value, const CHAR string, CHAR *endptr)

Detailed Description

Converts a string into a numerical value.

Authors: Creighton, T. D.; Shawhan, P. S.

Description

These routines parse the string *string and compute a numerical value *value of the appropriate datatype. If endptr \(\neq\)NULL, then after conversion *endptr will point to the character after the last character used in the conversion. The routine will always return without error if the arguments are valid, regardless of the contents of string; failure to parse a number is indicated by *endptr being set equal to string (provided endptr \(\neq\)NULL).

For integer or floating-point conversion to occur, string must consist of zero or more whitespace characters followed by a number in any standard base-ten integer or floating-point representation (described in detail below); the conversion will stop as soon as the routine encounters a character that is not part of the number. For instance, parsing the string " 123bad" will return *value=123, and *endptr will point to the substring "bad"; it is up to the calling routine to determine whether this is an acceptable input. By contrast, parsing the string " bad" will leave *value unchanged and *endptr pointing to the start of the original string. In general, if the routine returns with *endptr \(\neq\)string and **endptr is a whitespace or '\0' character, then the format was unambiguously acceptable.

Complex conversion is essentially equivalent to performing floating-point conversion on string to get the real part, and again on *endptr to get the imaginary part. Normally this means that an acceptable format is two floating-point representations separated by (and possibly preceded with) whitespace, although the intervening whitespace can be omitted if the separation between the two numbers is unambiguous. Thus the string "-1.0+3.5" will be unambiguously read as \(-1.0+3.5i\), but "-1.03.5" will be read as \(-1.03+0.5i\) (since the conversion of the real part stops at the second '.' character), which may or may not be the intended conversion.

Algorithm

These functions emulate the standard C functions strtol(), strtoul(), and strtod(), except that they follow LAL calling conventions and return values of the appropriate LAL datatypes. For integer conversion, only base-ten (decimal) representations are supported. Otherwise, the valid format is as for the corresponding C functions, which we summarize below:

A string to be converted to an INT \(n\) (where \(n\)=2, 4, or 8) consists of zero or more whitespace characters as determined by isspace(), followed optionally by a single '+' or '-' character, followed by one or more decimal digits; conversion stops at the first non-digit character after this. If the result would overflow or underflow the INT \(n\) representation, then the value is set to LAL_INT \(n\)_MAX \(=2^{8n-1}-1\) or LAL_INT \(n\)_MIN \(=-2^{8n-1}\), respectively.

A string to be converted to a UINT \(n\) follows the same format, except that a leading negative sign character '-' is ignored (the routine will compute the magnitude of the result), and the return value is capped at LAL_UINT \(n\)_MAX \(=2^{8n}-1\).

A string to be converted to a floating-point number (REAL4 or REAL8) consists of zero or more whitespace characters as determined by isspace(), followed optionally by a single '+' or '-' character, followed by a sequence of one or more decimal digits optionally containing a decimal point '.', optionally followed by an exponent. An exponent consists of a single 'E' or 'e' character, followed optionally by a single '+' or '-' character, followed by a sequence of one or more decimal digits. If the converted value would overflow, \(\pm\)LAL_REAL \(n\)_MAX is returned, as appropriate. If the value would underflow, 0 is returned.

A string to be converted to a complex number (COMPLEX8 or COMPLEX16) consists of two floating-point format substrings concatenated together, where the first character of the second substring cannot be interpreted as a continuation of the first number. Usually this means that the second substring will contain at least one leading whitespace character, though this is not strictly necessary. Overflow or underflow is dealt with as above.

Definition in file StringConvert.c.

Go to the source code of this file.

Function Documentation

◆ LALStringToU2()

void LALStringToU2	(	LALStatus *	stat,
		UINT2 *	value,
		const CHAR *	string,
		CHAR **	endptr
	)

Definition at line 198 of file StringConvert.c.

◆ LALStringToU4()

void LALStringToU4	(	LALStatus *	stat,
		UINT4 *	value,
		const CHAR *	string,
		CHAR **	endptr
	)

Definition at line 232 of file StringConvert.c.

◆ LALStringToU8()

void LALStringToU8	(	LALStatus *	stat,
		UINT8 *	value,
		const CHAR *	string,
		CHAR **	endptr
	)

Definition at line 266 of file StringConvert.c.

◆ LALStringToI2()

void LALStringToI2	(	LALStatus *	stat,
		INT2 *	value,
		const CHAR *	string,
		CHAR **	endptr
	)

Definition at line 297 of file StringConvert.c.

◆ LALStringToI4()

void LALStringToI4	(	LALStatus *	stat,
		INT4 *	value,
		const CHAR *	string,
		CHAR **	endptr
	)

Definition at line 338 of file StringConvert.c.

◆ LALStringToI8()

void LALStringToI8	(	LALStatus *	stat,
		INT8 *	value,
		const CHAR *	string,
		CHAR **	endptr
	)

Definition at line 379 of file StringConvert.c.

◆ LALStringToS()

void LALStringToS	(	LALStatus *	stat,
		REAL4 *	value,
		const CHAR *	string,
		CHAR **	endptr
	)

Definition at line 420 of file StringConvert.c.

◆ LALStringToD()

void LALStringToD	(	LALStatus *	stat,
		REAL8 *	value,
		const CHAR *	string,
		CHAR **	endptr
	)

Definition at line 455 of file StringConvert.c.

◆ LALStringToC()

void LALStringToC	(	LALStatus *	stat,
		COMPLEX8 *	value,
		const CHAR *	string,
		CHAR **	endptr
	)

Definition at line 490 of file StringConvert.c.

◆ LALStringToZ()

void LALStringToZ	(	LALStatus *	stat,
		COMPLEX16 *	value,
		const CHAR *	string,
		CHAR **	endptr
	)

Definition at line 525 of file StringConvert.c.

Prototypes