Detailed Description

Sub-module for parsing of input 'string values' as various 'types' (as defined in Header UserInput.h).

Author: Reinhard Prix

Prototypes
int	XLALParseStringValueAsINT4PlusFrac (INT4 valINT4, REAL8 valFrac, const char *valString)
	Parse a string containing a floating-point number into integer and fractional part, such that val = valINT + valFrac. More...

int	XLALParseStringValueAsINT8 (INT8 valINT8, const char valString)
	Parse a string into an INT8 This ignores initial whitespace, but throws an error on any non-converted trailing characters (including whitespace) More...

int	XLALParseStringValueAsINT4 (INT4 valINT4, const char valString)
	Parse a string into an INT4 This ignores initial whitespace, but throws an error on any non-converted trailing characters (including whitespace) More...

int	XLALParseStringValueAsUINT8 (UINT8 valUINT8, const char valString)
	Parse a string into an UINT8 This ignores initial whitespace, but throws an error on any non-converted trailing characters (including whitespace) More...

int	XLALParseStringValueAsUINT4 (UINT4 valUINT4, const char valString)
	Parse a string into an UINT4 This ignores initial whitespace, but throws an error on any non-converted trailing characters (including whitespace) More...

int	XLALParseStringValueAsREAL8 (REAL8 valREAL8, const char valString)
	Parse a string into a REAL8 This ignores initial whitespace, but throws an error on any non-converted trailing characters (including whitespace) More...

int	XLALParseStringValueAsREAL4 (REAL4 valREAL4, const char valString)
	Parse a string into a REAL4. More...

int	XLALParseStringValueAsBOOLEAN (BOOLEAN valBOOLEAN, const char valString)
	Parse a string into a BOOLEAN Allowed string-values are (case-insensitive): {"yes", "true", "1"} --> TRUE {"no", "false", "0"} --> FALSE. More...

int	XLALParseStringValueAsGPS (LIGOTimeGPS gps, const char valString)
	Parse a string representing a GPS time into LIGOTimeGPS, without loss of (ns) accuracy. More...

int	XLALParseStringValueAsEPOCH (LIGOTimeGPS gps, const char valString)
	Parse a string representing an 'epoch' into an LIGOTimeGPS, allowing both GPS and MJD(TT) inputs, at ns accuracy. More...

int	XLALParseStringValueAsRAJ (REAL8 valRAJ, const char valString)
	Parse a string representing an 'equatorial longitude' (aka right ascension or RA) into REAL8 radians, allowing for both radians or "hours:minutes:seconds" as input. More...

int	XLALParseStringValueAsDECJ (REAL8 valDECJ, const char valString)
	Parse a string representing an 'equatorial latitude' (aka declination or DEC) into REAL8 radians, allowing for both radians or "degrees:minutes:seconds" as input. More...

int	XLALParseStringValueAsINT4Range (INT4Range int4Range, const char *valString)
	Parse a string representing a range of INT4 values into a INT4Range. More...

int	XLALParseStringValueAsREAL8Range (REAL8Range real8Range, const char *valString)
	Parse a string representing a range of REAL8 values into a REAL8Range. More...

int	XLALParseStringValueAsEPOCHRange (LIGOTimeGPSRange gpsRange, const char *valString)
	Parse a string representing a range of LIGOTimeGPS values into a LIGOTimeGPSRange. More...

int	XLALParseStringValueAsRAJRange (REAL8Range rajRange, const char *valString)
	Parse a string representing a range of RAJ values into a REAL8Range. More...

int	XLALParseStringValueAsDECJRange (REAL8Range decjRange, const char *valString)
	Parse a string representing a range of DECJ values into a REAL8Range. More...

int	XLALParseStringValueAsUserEnum (int valEnum, const UserChoices enumData, const char *valString)
	Parse a string representing a user selection of an enumeration value. More...

int	XLALParseStringValueAsUserFlag (int valFlag, const UserChoices flagData, const char *valString)
	Parse a string representing a user selection of a set of bitflags. More...

int	XLALParseStringValueAsSTRING (CHAR *valOut, const char valString)
	Duplicate string 'in', removing surrounding quotes " or \' if present. More...

int	XLALParseStringValueAsSTRINGVector (LALStringVector *valSTRINGVector, const CHAR valString)
	Parse a string containing a list of comma-separated values (CSV) into a StringVector. More...

	DECL_XLALParseStringValueAsVector (INT4)

	DECL_XLALParseStringValueAsVector (UINT4)

	DECL_XLALParseStringValueAsVector (REAL8)

Data Structures
struct	UserChoices
	Possible choices the user may select for an enumeration or bitflag. More...

Typedefs
typedef REAL8	REAL8Range[2]
	A range of REAL8 values; first element is minimum, second element is maximum of range. More...

typedef INT4	INT4Range[2]
	A range of INT4 values; first element is minimum, second element is maximum of range. More...

typedef LIGOTimeGPS	LIGOTimeGPSRange[2]
	A range of GPS times; first element is minimum, second element is maximum of range. More...

Macros
#define	XLAL_IDX2BIT(i) (1UL << ((unsigned long)(i)))
	Convert an unsigned long index `i` into a bit, i.e. More...

#define	XLAL_BIT2IDX(b)
	Convert an unsigned long single bit `b` into an index, i.e. More...

#define	DECL_XLALParseStringValueAsVector(CTYPE) int XLALParseStringValueAs ##CTYPE## Vector ( CTYPE ## Vector *vect, const CHAR valString )

Function Documentation

◆ XLALParseStringValueAsINT4PlusFrac()

int XLALParseStringValueAsINT4PlusFrac	(	INT4 *	valINT4,
		REAL8 *	valFrac,
		const char *	valString
	)

Parse a string containing a floating-point number into integer and fractional part, such that val = valINT + valFrac.

This is useful for parsing strings representing GPS or MJD times wihout loss of ns accuracy.

Parameters

[out]	valINT4	return INT4 integer part 'xxx'
[out]	valFrac	return fractional part '0.yyyy'
[in]	valString	input string value representing a floating-point number "xxx.yyyy"

Definition at line 203 of file UserInputParse.c.

◆ XLALParseStringValueAsINT8()

int XLALParseStringValueAsINT8	(	INT8 *	valINT8,
		const char *	valString
	)

Parse a string into an INT8 This ignores initial whitespace, but throws an error on any non-converted trailing characters (including whitespace)

Parameters

[out]	valINT8	return INT8 value
[in]	valString	input string value

Definition at line 50 of file UserInputParse.c.

◆ XLALParseStringValueAsINT4()

int XLALParseStringValueAsINT4	(	INT4 *	valINT4,
		const char *	valString
	)

Parse a string into an INT4 This ignores initial whitespace, but throws an error on any non-converted trailing characters (including whitespace)

Parameters

[out]	valINT4	return INT4 value
[in]	valString	input string value

Definition at line 79 of file UserInputParse.c.

◆ XLALParseStringValueAsUINT8()

int XLALParseStringValueAsUINT8	(	UINT8 *	valUINT8,
		const char *	valString
	)

Parse a string into an UINT8 This ignores initial whitespace, but throws an error on any non-converted trailing characters (including whitespace)

Parameters

[out]	valUINT8	return UINT8 value
[in]	valString	input string value

Definition at line 102 of file UserInputParse.c.

◆ XLALParseStringValueAsUINT4()

int XLALParseStringValueAsUINT4	(	UINT4 *	valUINT4,
		const char *	valString
	)

Parse a string into an UINT4 This ignores initial whitespace, but throws an error on any non-converted trailing characters (including whitespace)

Parameters

[out]	valUINT4	return UINT4 value
[in]	valString	input string value

Definition at line 135 of file UserInputParse.c.

◆ XLALParseStringValueAsREAL8()

int XLALParseStringValueAsREAL8	(	REAL8 *	valREAL8,
		const char *	valString
	)

Parse a string into a REAL8 This ignores initial whitespace, but throws an error on any non-converted trailing characters (including whitespace)

Parameters

[out]	valREAL8	return REAL8 value
[in]	valString	input string value

Definition at line 158 of file UserInputParse.c.

◆ XLALParseStringValueAsREAL4()

int XLALParseStringValueAsREAL4	(	REAL4 *	valREAL4,
		const char *	valString
	)

Parse a string into a REAL4.

This ignores initial whitespace, but throws an error on any non-converted trailing characters (including whitespace)

Parameters

[out]	valREAL4	return REAL4 value
[in]	valString	input string value

Definition at line 179 of file UserInputParse.c.

◆ XLALParseStringValueAsBOOLEAN()

int XLALParseStringValueAsBOOLEAN	(	BOOLEAN *	valBOOLEAN,
		const char *	valString
	)

Parse a string into a BOOLEAN Allowed string-values are (case-insensitive): {"yes", "true", "1"} --> TRUE {"no", "false", "0"} --> FALSE.

NOTE: This throws an error on any extraneous leading or trailing characters or whitespace

Parameters

[out]	valBOOLEAN	return BOOLEAN value
[in]	valString	input string value

Definition at line 248 of file UserInputParse.c.

◆ XLALParseStringValueAsGPS()

int XLALParseStringValueAsGPS	(	LIGOTimeGPS *	gps,
		const char *	valString
	)

Parse a string representing a GPS time into LIGOTimeGPS, without loss of (ns) accuracy.

Parameters

[out]	gps	returned GPS time
[in]	valString	input string representing MJD(TT) time

Definition at line 287 of file UserInputParse.c.

◆ XLALParseStringValueAsEPOCH()

int XLALParseStringValueAsEPOCH	(	LIGOTimeGPS *	gps,
		const char *	valString
	)

Parse a string representing an 'epoch' into an LIGOTimeGPS, allowing both GPS and MJD(TT) inputs, at ns accuracy.

Allowed input string formats are "INT4.INT4[GPS|MJD]", where the optional postfix 'GPS' or 'MJD' indicates the time 'units', which defaults to GPS if no postfix is given. Note that MJD input is interpreted as MJD(TT), and translated into GPS using XLALTranslateStringMJDTTtoGPS(). This ignores initial whitespace, but throws an error on any non-converted trailing characters (including whitespace)

Parameters

[out]	gps	return LIGOTimeGPS value
[in]	valString	input string value

Definition at line 314 of file UserInputParse.c.

◆ XLALParseStringValueAsRAJ()

int XLALParseStringValueAsRAJ	(	REAL8 *	valRAJ,
		const char *	valString
	)

Parse a string representing an 'equatorial longitude' (aka right ascension or RA) into REAL8 radians, allowing for both radians or "hours:minutes:seconds" as input.

Note that "h:m:s" input is translated into radians using XLALTranslateHMStoRAD().

Parameters

[out]	valRAJ	return longitude value in radians
[in]	valString	input string value

Definition at line 365 of file UserInputParse.c.

◆ XLALParseStringValueAsDECJ()

int XLALParseStringValueAsDECJ	(	REAL8 *	valDECJ,
		const char *	valString
	)

Parse a string representing an 'equatorial latitude' (aka declination or DEC) into REAL8 radians, allowing for both radians or "degrees:minutes:seconds" as input.

Note that "d:m:s" input is translated into radians using XLALTranslateDMStoRAD().

Parameters

[out]	valDECJ	return latitude value in radians
[in]	valString	input string value

Definition at line 392 of file UserInputParse.c.

◆ XLALParseStringValueAsINT4Range()

int XLALParseStringValueAsINT4Range	(	INT4Range	int4Range,
		const char *	valString
	)

Parse a string representing a range of INT4 values into a INT4Range.

Possible formats are start, start,end, start/band, or start~plusminus. Output range is always low,high with range[0] = low; range[1] = high.

Parameters

[out]	int4Range	output range of INT4 values
[in]	valString	input string

Definition at line 510 of file UserInputParse.c.

◆ XLALParseStringValueAsREAL8Range()

int XLALParseStringValueAsREAL8Range	(	REAL8Range	real8Range,
		const char *	valString
	)

Parse a string representing a range of REAL8 values into a REAL8Range.

Possible formats are start, start,end, start/band, or start~plusminus. Output range is always low,high with range[0] = low; range[1] = high.

Parameters

[out]	real8Range	output range of REAL8 values
[in]	valString	input string

Definition at line 473 of file UserInputParse.c.

◆ XLALParseStringValueAsEPOCHRange()

int XLALParseStringValueAsEPOCHRange	(	LIGOTimeGPSRange	gpsRange,
		const char *	valString
	)

Parse a string representing a range of LIGOTimeGPS values into a LIGOTimeGPSRange.

Possible formats are start, start,end, start/band, or start~plusminus. Output range is always low,high with range[0] = low; range[1] = high.

Parameters

[out]	gpsRange	output range of LIGOTimeGPS values
[in]	valString	input string

Definition at line 548 of file UserInputParse.c.

◆ XLALParseStringValueAsRAJRange()

int XLALParseStringValueAsRAJRange	(	REAL8Range	rajRange,
		const char *	valString
	)

Parse a string representing a range of RAJ values into a REAL8Range.

Possible formats are start, start,end, start/band, or start~plusminus. Output range is always low,high with range[0] = low; range[1] = high.

Parameters

[out]	rajRange	output range of RAJ values
[in]	valString	input string

Definition at line 586 of file UserInputParse.c.

◆ XLALParseStringValueAsDECJRange()

int XLALParseStringValueAsDECJRange	(	REAL8Range	decjRange,
		const char *	valString
	)

Parse a string representing a range of DECJ values into a REAL8Range.

Possible formats are start, start,end, start/band, or start~plusminus. Output range is always low,high with range[0] = low; range[1] = high.

Parameters

[out]	decjRange	output range of DECJ values
[in]	valString	input string

Definition at line 624 of file UserInputParse.c.

◆ XLALParseStringValueAsUserEnum()

int XLALParseStringValueAsUserEnum	(	int *	valEnum,
		const UserChoices *	enumData,
		const char *	valString
	)

Parse a string representing a user selection of an enumeration value.

Enumeration choices with values < 0 are ignored.
Enumeration choice names are case insensitive.

Parameters

[out]	valEnum	output enumeration value
[in]	enumData	possible choices for enumeration values
[in]	valString	input string value

Definition at line 662 of file UserInputParse.c.

◆ XLALParseStringValueAsUserFlag()

int XLALParseStringValueAsUserFlag	(	int *	valFlag,
		const UserChoices *	flagData,
		const char *	valString
	)

Parse a string representing a user selection of a set of bitflags.

If the first bitflag choice has a value of zero, it is treated
Bitflag choices with values <= 0 are ignored.
Bigflag choice names are separated by ',' and are case insensitive.

Parameters

[out]	valFlag	output bitflag value
[in]	flagData	possible choices for bitflag values
[in]	valString	input string value

Definition at line 695 of file UserInputParse.c.

◆ XLALParseStringValueAsSTRING()

int XLALParseStringValueAsSTRING	(	CHAR **	out,
		const CHAR *	valStr
	)

Duplicate string 'in', removing surrounding quotes " or \' if present.

Note: Quotes at the beginning of the string must be matched at the end, otherwise we return an error.; The output string (*out) must be NULL

Parameters

[out]	out	return allocated string
[in]	valStr	input string value

Definition at line 757 of file UserInputParse.c.

◆ XLALParseStringValueAsSTRINGVector()

int XLALParseStringValueAsSTRINGVector	(	LALStringVector **	strVect,
		const CHAR *	valString
	)

Parse a string containing a list of comma-separated values (CSV) into a StringVector.

Note: surrounding whitespace and quotes (\' or ") are removed from the individual list entries.; The output string-vector (*strVect) must be NULL

Parameters

[out]	strVect	allocated string vector
[in]	valString	input string value

Definition at line 805 of file UserInputParse.c.

◆ DECL_XLALParseStringValueAsVector() [1/3]

DECL_XLALParseStringValueAsVector ( INT4 )

◆ DECL_XLALParseStringValueAsVector() [2/3]

DECL_XLALParseStringValueAsVector ( UINT4 )

◆ DECL_XLALParseStringValueAsVector() [3/3]

DECL_XLALParseStringValueAsVector ( REAL8 )

Typedef Documentation

◆ REAL8Range

typedef REAL8 REAL8Range[2]

A range of REAL8 values; first element is minimum, second element is maximum of range.

Definition at line 61 of file UserInputParse.h.

◆ INT4Range

typedef INT4 INT4Range[2]

A range of INT4 values; first element is minimum, second element is maximum of range.

Definition at line 66 of file UserInputParse.h.

◆ LIGOTimeGPSRange

typedef LIGOTimeGPS LIGOTimeGPSRange[2]

A range of GPS times; first element is minimum, second element is maximum of range.

Definition at line 71 of file UserInputParse.h.

Macro Definition Documentation

◆ XLAL_IDX2BIT

#define XLAL_IDX2BIT ( i ) (1UL << ((unsigned long)(i)))

Convert an unsigned long index i into a bit, i.e.

\(b = 2^i\)

Definition at line 44 of file UserInputParse.h.

◆ XLAL_BIT2IDX

#define XLAL_BIT2IDX ( b )

Value:

    ( \
    (((((unsigned long)(b)) & 0xAAAAAAAAAAAAAAAAUL) != 0)) | \
    (((((unsigned long)(b)) & 0xCCCCCCCCCCCCCCCCUL) != 0) << 1UL) | \
    (((((unsigned long)(b)) & 0xF0F0F0F0F0F0F0F0UL) != 0) << 2UL) | \
    (((((unsigned long)(b)) & 0xFF00FF00FF00FF00UL) != 0) << 3UL) | \
    (((((unsigned long)(b)) & 0xFFFF0000FFFF0000UL) != 0) << 4UL) | \
    (((((unsigned long)(b)) & 0xFFFFFFFF00000000UL) != 0) << 5UL) \
    )

Convert an unsigned long single bit b into an index, i.e.

\(i = \log_2 b \)

Definition at line 49 of file UserInputParse.h.

◆ DECL_XLALParseStringValueAsVector

#define DECL_XLALParseStringValueAsVector ( CTYPE ) int XLALParseStringValueAs ##CTYPE## Vector ( CTYPE ## Vector **vect, const CHAR *valString )

Definition at line 118 of file UserInputParse.h.

Detailed Description

Prototypes

Data Structures

Typedefs

Macros

Function Documentation

◆ XLALParseStringValueAsINT4PlusFrac()

◆ XLALParseStringValueAsINT8()

◆ XLALParseStringValueAsINT4()

◆ XLALParseStringValueAsUINT8()

◆ XLALParseStringValueAsUINT4()

◆ XLALParseStringValueAsREAL8()

◆ XLALParseStringValueAsREAL4()

◆ XLALParseStringValueAsBOOLEAN()

◆ XLALParseStringValueAsGPS()

◆ XLALParseStringValueAsEPOCH()

◆ XLALParseStringValueAsRAJ()

◆ XLALParseStringValueAsDECJ()

◆ XLALParseStringValueAsINT4Range()

◆ XLALParseStringValueAsREAL8Range()

◆ XLALParseStringValueAsEPOCHRange()

◆ XLALParseStringValueAsRAJRange()

◆ XLALParseStringValueAsDECJRange()

◆ XLALParseStringValueAsUserEnum()

◆ XLALParseStringValueAsUserFlag()

◆ XLALParseStringValueAsSTRING()

◆ XLALParseStringValueAsSTRINGVector()

◆ DECL_XLALParseStringValueAsVector() [1/3]

◆ DECL_XLALParseStringValueAsVector() [2/3]

◆ DECL_XLALParseStringValueAsVector() [3/3]

Typedef Documentation

◆ REAL8Range

◆ INT4Range

◆ LIGOTimeGPSRange

Macro Definition Documentation

◆ XLAL_IDX2BIT

◆ XLAL_BIT2IDX

◆ DECL_XLALParseStringValueAsVector