xchange.c File Reference

A collection of commonly used functions for standard data exchange for scalars and arrays, and ASCII representations. More...

Macros
#define	__XCHANGE_INTERNAL_API__
	Use internal definitions.
#define	EXPLICIT_PARSE_SPECIAL_DOUBLES   TRUE
	Use our own parser for NAN/INF values.

Functions
int	x_error (int ret, int en, const char *from, const char *desc,...)
int	x_trace (const char *loc, const char *op, int n)
void *	x_trace_null (const char *loc, const char *op)
int	x_warn (const char *from, const char *desc,...)
void *	xAlloc (XType type, int count)
int	xElementSizeOf (XType type)
int	xError (const char *fn, int code)
const char *	xErrorDescription (int code)
long	xGetElementCount (int ndim, const int *sizes)
boolean	xIsCharSequence (XType type)
boolean	xIsDecimal (XType type)
boolean	xIsInteger (XType type)
boolean	xIsNumeric (XType type)
boolean	xIsVerbose ()
boolean	xParseBoolean (char *str, char **end)
int	xParseDims (const char *src, int *sizes)
double	xParseDouble (const char *str, char **tail)
float	xParseFloat (const char *str, char **tail)
int	xPrintDims (char *dst, int ndim, const int *sizes)
int	xPrintDouble (char *str, double value)
int	xPrintFloat (char *str, float value)
void	xSetDebug (boolean value)
void	xSetVerbose (boolean value)
char *	xStringCopyOf (const char *str)
int	xStringElementSizeOf (XType type)
char	xTypeChar (XType type)
void	xZero (void *buf, XType type, int count)

Variables
boolean	xDebug = FALSE
	Switch to enable debugging (very verbose) output for XChange operations.
boolean	xVerbose
	Switch to enable verbose console output for XChange operations.

Detailed Description

A collection of commonly used functions for standard data exchange for scalars and arrays, and ASCII representations.

Date

Nov 25, 2020

Author

Attila Kovacs

Function Documentation

x_error()

int x_error	(	int	ret,
		int	en,
		const char *	from,
		const char *	desc,
			...
	)

(for internal use) Sets errno and reports errors to the standard error, depending on the current debug mode, before returning the supplied return code.

Parameters

ret	return value
en	UNIX error code (see errno.h)
from	function (:location) where error originated
desc	description of error, with information to convey to user.

See also

x_set_errno()

x_trace()

References xDebug.

x_trace()

int x_trace	(	const char *	loc,
		const char *	op,
		int	n
	)

(for internal use) Propagates an error (if any). If the error is non-zero, it returns with the offset error value. Otherwise it keeps going as if it weren't even there...

Parameters

loc	Function [:location] where error was produced.
op	(optional) further info or NULL.
n	error code that was received.

Returns

n

References xDebug.

x_trace_null()

void * x_trace_null	(	const char *	loc,
		const char *	op
	)

(for internal use) Traces an error before returning NULL.

Parameters

loc	Function [:location] where error was produced.
op	(optional) further info or NULL.

Returns

NULL

References xDebug.

x_warn()

int x_warn	(	const char *	from,
		const char *	desc,
			...
	)

(for internal use) Prints a warning message.

Parameters

from	function (:location) where error originated
desc	description of error, with information to convey to user.

See also

x_set_errno()

x_trace()

References xDebug.

xAlloc()

void * xAlloc	(	XType	type,
		int	count
	)

Allocates a buffer for a given SMA-X type and element count. The buffer is initialized with zeroes.

Parameters

type	SMA-X type
count	number of elements.

Returns

Pointer to the initialized buffer or NULL if there was an error (errno will be set accordingly).

References x_error(), x_trace_null(), and xElementSizeOf().

xElementSizeOf()

int xElementSizeOf

(

XType

type

)

Returns the storage byte size of a single element of a given type.

Parameters

type	The data type, as defined in 'xchange.h'

Returns

[bytes] the native storage size of a single element of that type. E.g. for X_CHAR(20) it will return 20. X_DOUBLE will return 8, etc. Unrecognised types will return 0.

References X_BOOLEAN, X_BYTE, X_DOUBLE, X_FIELD, X_FLOAT, X_INT16, X_INT32, X_INT64, X_RAW, X_STRING, and X_STRUCT.

xError()

int xError	(	const char *	fn,
		int	code
	)

Prints a descriptive error message to stderr, and returns the error code.

Parameters

fn	String that describes the function or location where the error occurred.
code	The xchange error code that describes the failure (see xchange.h).

Returns

Same error code as specified on input.

References X_ALREADY_OPEN, x_error(), X_FAILURE, X_GROUP_INVALID, X_INCOMPLETE, X_INTERRUPTED, X_NAME_INVALID, X_NO_BLOCKED_READ, X_NO_INIT, X_NO_PIPELINE, X_NO_SERVICE, X_NOT_ENOUGH_TOKENS, X_NULL, X_PARSE_ERROR, X_SIZE_INVALID, X_SUCCESS, X_TIMEDOUT, and X_TYPE_INVALID.

xErrorDescription()

const char * xErrorDescription

(

int

code

)

Returns a string description for one of the standard X-change error codes, and sets errno as appropriate also. (The mapping to error codes is not one-to-one. The same errno may be used to describe different X-change errors. Nevertheless, it is a guide that can be used when the X-change error is not directtly available, e.g. because it is not returned by a given function.)

Parameters

code	One of the error codes defined in 'xchange.h'

Returns

A constant string with the error description.

References X_ALREADY_OPEN, X_FAILURE, X_GROUP_INVALID, X_INCOMPLETE, X_INTERRUPTED, X_NAME_INVALID, X_NO_BLOCKED_READ, X_NO_INIT, X_NO_PIPELINE, X_NO_SERVICE, X_NOT_ENOUGH_TOKENS, X_NULL, X_PARSE_ERROR, X_SIZE_INVALID, X_SUCCESS, X_TIMEDOUT, and X_TYPE_INVALID.

xGetElementCount()

long xGetElementCount	(	int	ndim,
		const int *	sizes
	)

Returns the total element count specified by along a number of dimensions. It ignores dimensions that have size components <= 0;

Parameters

ndim	Number of dimensions
sizes	Sizes along each dimension.

Returns

Total element count specified by the dimensions. Defaults to 1.

References x_error(), and X_MAX_DIMS.

xIsCharSequence()

boolean xIsCharSequence

(

XType

type

)

Checks if the type represents a fixed-size character / binary sequence.

Parameters

type	xchange type to check.

Returns

TRUE (1) if it is a type for a (fixed size) character array, otherwise FALSE (0).

xIsDecimal()

boolean xIsDecimal

(

XType

type

)

Checks if the type represents a floating-point value of any width.

Parameters

type	xchange type to check.

Returns

TRUE (1) if the type is for a floating-point value, or else FALSE (0)

See also

xIsInteger()

xIsNumeric()

xGetAsDouble()

References X_DOUBLE, and X_FLOAT.

xIsInteger()

boolean xIsInteger

(

XType

type

)

Checks if the type represents a signed integer value of any width.

Parameters

type	xchange type to check.

Returns

TRUE (1) if the type is for an integer value, or else FALSE (0)

See also

xIsDecimal()

xIsNumeric()

xGetAsLong()

References FALSE, TRUE, X_BOOLEAN, X_BYTE, X_INT16, X_INT32, and X_INT64.

xIsNumeric()

boolean xIsNumeric

(

XType

type

)

Checks if the type represents a numerical value.

Parameters

type	xchange type to check.

Returns

TRUE (1) if the type is for a number value, or else FALSE (0)

See also

xIsInteger()

xIsDecimal()

References xIsDecimal(), and xIsInteger().

xIsVerbose()

boolean xIsVerbose

(

)

Checks if verbosity is enabled for the xchange library.

Returns

TRUE (1) if verbosity is enabled, or else FALSE (0).

See also

xSetVerbose()

xSetDebug()

References xVerbose.

xParseBoolean()

boolean xParseBoolean	(	char *	str,
		char **	end
	)

Parses a boolean value, either as a zero/non-zero number or as a case-insensitive match to the next token to one of the recognized boolean terms, such as "true"/"false", "on"/"off", "yes"/"no", "t"/"f", "y"/"n", "enabled"/"disabled" or "active"/"inactive". If a boolean value cannot be matched, FALSE is returned, and errno is set to ERANGE.

Parameters

str	Pointer to the string token.
end	Where the pointer to after the successfully parsed token is returned, on NULL.

Returns

TRUE (1) or FALSE (0).

References FALSE, TRUE, and x_error().

xParseDims()

int xParseDims	(	const char *	src,
		int *	sizes
	)

Deserializes the sizes from a space-separated list of dimensions. The parsing will terminate at the first non integer value or the end of string, whichever comes first. Integer values <= 0 are ignored.

Parameters

src	Pointer to a string buffer that contains the serialized dimensions, as a list of space separated integers.
sizes	Pointer to an array of ints (usually of X_MAX_DIMS size) to which the valid dimensions are deserialized.

Returns

Number of valid (i.e. positive) dimensions parsed.

References x_error(), and X_MAX_DIMS.

xParseDouble()

double xParseDouble	(	const char *	str,
		char **	tail
	)

Parses a double-precision floating point value from its decimal string representation. Effectively the same as strtod() on C99, but it checks the input string for NULL, resets errno before parsing so you don't have to, and will parse Infinity values even on older platforms that do not have built-in support for these.

Parameters

str	String to parse floating-point value from
tail	(optional) reference to pointed in which to return the parse position after successfully parsing a floating-point value.

Returns

the floating-point value at the head of the string, or NAN if the input string is NULL, or 0.0 if the string does not start with a numerical value, or is a value near zero that cannot be represented by a float (underflow) or +/- INFINITY (or HUGE_VAL if INFINITY is not defined in math.h) if the value exceeds the float range (overflow). In cases of underflow or overflow errno will be set to ERANGE.

See also

xParseFloat()

xPrintDouble()

References INFINITY, NAN, and x_error().

xParseFloat()

float xParseFloat	(	const char *	str,
		char **	tail
	)

Parses a single-precision floating point value from its decimal string representation. Effectively the same as or similar to strtof(), but it checks the input string for NULL, resets errno before parsing so you don't have to, and will parse Infinity values even on older platforms that do not have built-in support for these.

On older platforms, which do not have a builtin strtof() function, this will parse the string as as double, before checking for range and returning the result recast as a float. The conversion may result in a decimal rounding 'error' if the returned value is then printed, whereby the last decimal digit may differ by one from the original input string.

Parameters

str	String to parse floating-point value from
tail	(optional) reference to pointed in which to return the parse position after successfully parsing a floating-point value.

Returns

the floating-point value at the head of the string, or NAN if the input string is NULL, or 0.0F if the string does not start with a numerical value, or is a value near zero that cannot be represented by a float (underflow) or +/- INFINITY (or HUGE_VAL if INFINITY is not defined in math.h) if the value exceeds the float range (overflow). In cases of underflow or overflow errno will be set to ERANGE.

Since

1.1

See also

xParseDouble()

xPrintFloat()

References INFINITY, NAN, x_error(), and xParseDouble().

xPrintDims()

int xPrintDims	(	char *	dst,
		int	ndim,
		const int *	sizes
	)

Serializes the dimensions to a string as a space-separated list of integers.

Parameters

[out]	dst	Pointer to a string buffer with at least X_MAX_STRING_DIMS bytes size.
[in]	ndim	Number of dimensions
[in]	sizes	Sizes along each dimension.

Returns

Number of characters written into the destination buffer, not counting the string termination, or -1 if an the essential pointer arguments is NULL.

References x_error(), and X_MAX_DIMS.

xPrintDouble()

int xPrintDouble	(	char *	str,
		double	value
	)

Prints a double precision number, restricted to legal double-precision range. If the native value has abolute value smaller than the smallest non-zero value, then 0 will printed instead. For values that exceed the legal double precision range, "-inf" or "inf" will be used as appropriate, and NAN values will be printed as "nan".

Parameters

str	Pointer to buffer for printed value. It should have at least 25 bytes of space allocated after the specidied address.
value	Value to print.

Returns

Number of characters printed into the buffer, or -1 if there was an error.

References x_error().

xPrintFloat()

int xPrintFloat	(	char *	str,
		float	value
	)

Prints a single-precision number, restricted to the legal single-precision range. If the native value has abolute value smaller than the smallest non-zero value, then 0 will printed instead. For values that exceed the legal double precision range, "-inf" or "inf" will be used as appropriate, and NAN values will be printed as "nan".

Parameters

str	Pointer to buffer for printed value. It should have at least 16 bytes of space allocated after the specified address.
value	Value to print.

Returns

Number of characters printed into the buffer.

References x_error().

xSetDebug()

void xSetDebug

(

boolean

value

)

Enables or disables debugging output.

Parameters

value

TRUE (non-zero) to enable verbose output, or else FALSE (0).

See also

xSetVerbose()

References FALSE, TRUE, and xDebug.

xSetVerbose()

void xSetVerbose

(

boolean

value

)

Sets verbose output for the xchange library.

Parameters

value

TRUE (non-zero) to enable verbose output, or else FALSE (0).

See also

xIsVerbose()

References FALSE, TRUE, and xVerbose.

xStringCopyOf()

char * xStringCopyOf

(

const char *

str

)

Returns a freshly allocated string with the same content as the argument.

Parameters

str	Pointer to string we want to copy.

Returns

A copy of the supplied string, or NULL if the argument itself was NULL.

xStringElementSizeOf()

int xStringElementSizeOf

(

XType

type

)

Returns the number of characters, including a '\0' termination that a single element of the might be expected to fill.

Parameters

type	X-Change type to check.

Returns

Number of characters (including termination) required for the string representation of an element of the given variable, or 0 if the variable is of unknown type.

References X_BOOLEAN, X_BYTE, X_DOUBLE, x_error(), X_FLOAT, X_INT16, X_INT32, and X_INT64.

xTypeChar()

char xTypeChar

(

XType

type

)

Returns the character of the field type. For X_CHAR types it returns 'C' (without the length specification), and for all other types it returns the constant XType value itself.

Parameters

type	The single-character IF of the field type.

Returns

A character that represented the type.

References x_error().

xZero()

void xZero	(	void *	buf,
		XType	type,
		int	count
	)

Zeroes out the contents of an SMA-X buffer.

Parameters

buf	Pointer to the buffer to fill with zeroes.
type	SMA-X type
count	number of elements.

References xElementSizeOf().