Data Structures
struct	XField
	An SMA-X field, typically as part of an XStructure. A field may be a reference to a nested XStructure itself. More...

struct	XLookupTable

struct	XStructure
	SMA-X structure object, containing a linked-list of XField elements. More...

Macros
#define	_TYPEDEF_BOOLEAN
	Precompiler constant to indicate if boolean was defined.

#define	FALSE 0
	Boolean 'false' value, if not already defined.

#define	MAX_DEBUG_ERROR_COUNT 100
	Stop reporting errors if the number of them exceeds this count.

#define	NAN (0.0/0.0)
	Not-a-number in case it's not already defined in math.h.

#define	str_1(s) #s
	Stringify level 1 macro.

#define	str_2(s) str_1(s)
	Stringify level 2 macro.

#define	TRUE 1
	Boolean 'true' value, if not already defined.

#define	X_ALREADY_OPEN (-2)
	can't open the device twice

#define	X_BOOLEAN
	boolean XType

#define	X_BYTE
	single byte XType

#define	X_BYTE_HEX
	single byte XType in dexadecimal representation

#define	X_CHARS(length)
	A fixed-size sequence of 'length' bytes.

#define	X_DOUBLE
	double-precision (64) bit floating point XType

#define	X_FAILURE (-1)
	didn't quite work

#define	X_FIELD_INIT {NULL}

#define	X_FLOAT
	32-bit floating point XType

#define	X_GROUP_INVALID (-20)
	there's no such variable group or hash table

#define	X_INCOMPLETE (-9)
	incomplete data transfer

#define	X_INT
	native int XType (usually 16-bits)

#define	X_INT_HEX
	native int XType in hexadecimal representation

#define	X_INTERRUPTED (-8)
	a waiting call interrupted by user

#define	X_LONG
	64-bit int XType

#define	X_LONG_HEX
	64-bit int XType in hexadecimal representation

#define	X_MAX_DIMS 20
	Maximum number of dimensionas (2^20 -> 1 million points).

#define	X_MAX_ELEMENTS
	Maximum number of array elements (~1 million).

#define	X_MAX_STRING_DIMS
	Maximum length of string representation of dimensions.

#define	X_NAME_INVALID (-21)
	invalid field/key name

#define	X_NO_BLOCKED_READ (-5)
	there are no blocked read calls

#define	X_NO_INIT (-3)
	must initialize first

#define	X_NO_PIPELINE (-6)
	pipelining is not configured or supported

#define	X_NO_SERVICE (-4)
	no connection to server

#define	X_NOT_ENOUGH_TOKENS (-12)
	number of components fewer than expected

#define	X_NULL (-10)
	something essential is NULL

#define	X_PARSE_ERROR (-11)
	parsing failure

#define	X_RAW
	raw Redis (string) value XType, as stored in database

#define	X_SEP ":"
	sepatator for patterning of notification channels, e.g. "changed:<table>:<key>"

#define	X_SEP_LENGTH (sizeof(X_SEP) - 1)
	String length of hierarchical separator.

#define	X_SHORT
	native short XType (usually 16-bits)

#define	X_SHORT_HEX
	native short XType in hexadecimal representation

#define	X_SIZE_INVALID (-23)
	invalid data size

#define	X_STRING
	a terminated string XType

#define	X_STRUCT
	An XStructure XType.

#define	X_STRUCT_INIT {NULL}

#define	X_STRUCT_INVALID (-24)
	invalid data structure

#define	X_SUCCESS 0
	hooray!

#define	X_TIMEDOUT (-7)
	the operation timed out.

#define	X_TIMESTAMP_LENGTH 18
	Characters in timestamp, 10 + 6 + 2 = 18 including termination.

#define	X_TYPE_INVALID (-22)
	invalid data type

#define	X_UNKNOWN 0
	Unknown XType (default)

#define	XCHANGE_MAJOR_VERSION 0
	API major version.

#define	XCHANGE_MINOR_VERSION 9
	API minor version.

#define	XCHANGE_PATCHLEVEL 1
	Integer sub version of the release.

#define	XCHANGE_RELEASE_STRING "-devel"
	Additional release information in version, e.g. "-1", or "-rc1".

#define	XCHANGE_VERSION_STRING
	The version string for this library.

#define	xdprintf if(xDebug) printf
	Use for generating debug output.

#define	xvprintf if(xVerbose) printf
	Use for generating verbose output.

Typedefs
typedef int	boolean
	boolean TRUE/FALSE data type.

typedef int	XType
	SMA-X data type.

Functions
void *	xAlloc (XType type, int count)

XLookupTable *	xAllocLookup (unsigned int size)

void	xClearStruct (XStructure *s)

char *	xCopyIDToken (const char *id)

XField *	xCopyOfField (const XField *f)

XStructure *	xCopyOfStruct (const XStructure *s)

int	xCountFields (const XStructure *s)

XField *	xCreate1DField (const char name, XType type, int count, const void values)

XField *	xCreateBooleanField (const char *name, boolean value)

XField *	xCreateDoubleField (const char *name, double value)

XField *	xCreateField (const char name, XType type, int ndim, const int sizes, const void *value)

XField *	xCreateIntField (const char *name, int value)

XField *	xCreateLongField (const char *name, long long value)

XLookupTable *	xCreateLookup (const XStructure *s, boolean recursive)

XField *	xCreateScalarField (const char name, XType type, const void value)

XField *	xCreateStringField (const char name, const char value)

XStructure *	xCreateStruct ()

long	xDeepCountFields (const XStructure *s)

void	xDestroyField (XField *f)

void	xDestroyLookup (XLookupTable *tab)

void	xDestroyStruct (XStructure *s)

int	xElementSizeOf (XType type)

int	xError (const char *fn, int code)

const char *	xErrorDescription (int code)

char *	xGetAggregateID (const char group, const char key)

int	xGetElementCount (int ndim, const int *sizes)

XField *	xGetField (const XStructure s, const char name)

int	xGetFieldCount (const XField *f)

XStructure *	xGetSubstruct (const XStructure s, const char id)

boolean	xIsCharSequence (XType type)

boolean	xIsFieldValid (const XField *f)

boolean	xIsVerbose ()

char *	xLastSeparator (const char *id)

long	xLookupCount (const XLookupTable *tab)

XField *	xLookupField (const XLookupTable tab, const char id)

int	xLookupPut (XLookupTable tab, const char prefix, const XField field, XField *oldValue)

int	xLookupPutAll (XLookupTable tab, const char prefix, const XStructure *s, boolean recursive)

XField *	xLookupRemove (XLookupTable tab, const char id)

int	xLookupRemoveAll (XLookupTable tab, const char prefix, const XStructure *s, boolean recursive)

int	xMatchNextID (const char token, const char id)

char *	xNextIDToken (const char *id)

boolean	xParseBoolean (char str, char *end)

int	xParseDims (const char src, int sizes)

double	xParseDouble (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)

int	xReduceAllDims (XStructure *s)

int	xReduceDims (int ndim, int sizes)

XField *	xRemoveField (XStructure s, const char name)

int	xReverseFieldOrder (XStructure *s, boolean recursive)

void	xSetDebug (boolean value)

XField *	xSetField (XStructure s, XField f)

XField *	xSetSubstruct (XStructure s, const char name, XStructure *substruct)

void	xSetVerbose (boolean value)

int	xSortFields (XStructure s, int(cmp)(const XField f1, const XField f2), boolean recursive)

int	xSortFieldsByName (XStructure *s, boolean recursive)

int	xSplitID (char id, char *pKey)

char *	xStringCopyOf (const char *str)

int	xStringElementSizeOf (XType type)

char	xTypeChar (XType type)

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

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

boolean	xVerbose
	Switch to enable verbose console output for XChange operations.

Detailed Description

Date: Mar 14, 2019

Author: Attila Kovacs

A Basic set of utilities to allow platform-independent structured data exchange from C/C++. It also includes a JSON parser and emitter implementation.

Version: 0.9.1

Macro Definition Documentation

◆ X_FIELD_INIT

#define X_FIELD_INIT {NULL}

Static initializer for the XField data structure.

◆ X_STRUCT_INIT

#define X_STRUCT_INIT {NULL}

Static initializer for an XStructure data structure.

◆ XCHANGE_VERSION_STRING

#define XCHANGE_VERSION_STRING

Value:

str_2(XCHANGE_MAJOR_VERSION) "." str_2(XCHANGE_MINOR_VERSION) \

"." str_2(XCHANGE_PATCHLEVEL) XCHANGE_RELEASE_STRING

str_2

#define str_2(s)

Stringify level 2 macro.

Definition xchange.h:35

XCHANGE_MAJOR_VERSION

#define XCHANGE_MAJOR_VERSION

API major version.

Definition xchange.h:18

XCHANGE_RELEASE_STRING

#define XCHANGE_RELEASE_STRING

Additional release information in version, e.g. "-1", or "-rc1".

Definition xchange.h:27

XCHANGE_MINOR_VERSION

#define XCHANGE_MINOR_VERSION

API minor version.

Definition xchange.h:21

XCHANGE_PATCHLEVEL

#define XCHANGE_PATCHLEVEL

Integer sub version of the release.

Definition xchange.h:24

The version string for this library.

Function Documentation

◆ 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().

◆ xAllocLookup()

XLookupTable * xAllocLookup ( unsigned int size )

Allocates a new lookup with the specified hash size. The hash size should correspond to the number of elements stored in the lookup. If it's larger or roughtly equal to the number of elements to be stored, then the lookup time will stay approximately constant with the number of elements. If the size is much smaller than the number of elements N stored, then the lookup time will scale as O(N/size) typically.

Parameters

size	The number of hash bins to allocate

Returns: The new lookup table, or else NULL if there was an error.

See also: xCreateLookup(); xDestroyLookup()

References FALSE, XLookupTable::priv, and x_error().

◆ xClearStruct()

void xClearStruct ( XStructure * s )

Destroys the contents of an X structure, leaving the structure empty.

Parameters

s	Pointer to the structure to be cleared.

See also: smaDestroyStruct()

References XStructure::firstField, XField::next, and xDestroyField().

◆ xCopyIDToken()

char * xCopyIDToken ( const char * id )

Returns a copy of the next next component in a compound ID. Leading ID separators are ignored.

Parameters

id	Aggregate X ID.

Returns: Pointer to the start of the next compound ID token, or NULL if there is no more components in the ID.

References x_error(), X_SEP, X_SEP_LENGTH, and xNextIDToken().

◆ xCopyOfField()

XField * xCopyOfField ( const XField * f )

Returns a deep copy of the supplied field. The returned copy is a standalone field, unlinked to another to avoid corrupting any structure in which the original field may reside in. Note, that this only works with vanilla xchange structures with native storage fields. For example, SMA-X structures store data in serialized forms, and therefore it needs its own implementation for making deep copies of fields!

Parameters

f	Pointer to the original field or NULL.

Returns: A fully independent (deep) copy of the argument or NULL if the input field is NULL.

See also: xCopyOfStruct()

References XStructure::firstField, XField::isSerialized, XField::name, XField::next, XField::type, XField::value, x_error(), X_RAW, X_STRING, X_STRUCT, x_trace_null(), xCopyOfStruct(), xDestroyField(), xElementSizeOf(), xGetFieldCount(), and xStringCopyOf().

◆ xCopyOfStruct()

XStructure * xCopyOfStruct ( const XStructure * s )

Returns a deep copy of the supplied structure. Note that this only works with vanilla xchange structures with native storage fields. For example, SMA-X structures store data in serialized forms, and therefore it needs its own implementation for making deep copies of structs!

Parameters

s	Pointer to the original structure or NULL.

Returns: A fully independent (deep) copy of the argument or NULL if the input structure is NULL.

See also: xCopyOfField()

References XStructure::firstField, XField::next, XField::type, XField::value, x_error(), X_STRUCT, x_trace_null(), xCopyOfField(), xCreateStruct(), xDestroyStruct(), and xGetFieldCount().

◆ xCountFields()

int xCountFields ( const XStructure * s )

Returns the number of fields contained inside the structure. It is not recursive.

Parameters

s	Pointer to the structure to investigate

Returns: the number of fields cotnained in the structure (but not counting fields in sub-structures).

See also: xDeepCountFields()

References XStructure::firstField, and XField::next.

◆ xCreate1DField()

XField * xCreate1DField	(	const char *	name,
		XType	type,
		int	count,
		const void *	values
	)

Creates a generic field for a 1D array of a given name and native data. The structure will hold a copy of the value that is pointed at.

Parameters

name	Field name (it may not contain a separator X_SEP)
type	Storage type, e.g. X_INT.
count	Number of elements in array
values	Pointer to an array of native values.

Returns: A newly created field with the supplied data, or NULL if there was an error.

References x_trace_null(), and xCreateField().

◆ xCreateBooleanField()

XField * xCreateBooleanField	(	const char *	name,
		boolean	value
	)

Creates a field holding a single boolean value value.

Parameters

name	Field name (it may not contain a separator X_SEP)
value	Associated value

Returns: A newly created field with the supplied data, or NULL if there was an error.

References X_BOOLEAN, x_trace_null(), and xCreateScalarField().

◆ xCreateDoubleField()

XField * xCreateDoubleField	(	const char *	name,
		double	value
	)

Creates a field holding a single double-precision value value.

Parameters

name	Field name (it may not contain a separator X_SEP)
value	Associated value

Returns: A newly created field with the supplied data, or NULL if there was an error.

References X_DOUBLE, x_trace_null(), and xCreateScalarField().

◆ xCreateField()

XField * xCreateField	(	const char *	name,
		XType	type,
		int	ndim,
		const int *	sizes,
		const void *	value
	)

Creates a generic field of a given name and type and dimensions using a copy of the specified native data, unless type is X_STRUCT in which case the value is referenced directly inside the field.

Parameters

name	Field name (it may not contain a separator X_SEP)
type	Storage type, e.g. X_INT.
ndim	Number of dimensionas (1:20). If ndim < 1, it will be reinterpreted as ndim=1, size[0]=1;
sizes	Array of sizes along each dimensions, with at least ndim elements, or NULL with ndim<1.
value	Pointer to the native data location in memory, or NULL to leave unassigned for now.

Returns: A newly created field with the copy of the supplied data, or NULL if there was an error.

References XField::name, XField::ndim, XField::sizes, XField::type, XField::value, x_error(), X_MAX_DIMS, X_RAW, X_STRING, X_STRUCT, xDestroyField(), xElementSizeOf(), xGetElementCount(), xLastSeparator(), and xStringCopyOf().

◆ xCreateIntField()

XField * xCreateIntField	(	const char *	name,
		int	value
	)

Creates a field holding a single ineger value value.

Parameters

name	Field name (it may not contain a separator X_SEP)
value	Associated value

Returns: A newly created field with the supplied data, or NULL if there was an error.

See also: xCreateLongField()

References X_INT, x_trace_null(), and xCreateScalarField().

◆ xCreateLongField()

XField * xCreateLongField	(	const char *	name,
		long long	value
	)

Creates a field holding a single ineger value value.

Parameters

name	Field name (it may not contain a separator X_SEP)
value	Associated value

Returns: A newly created field with the supplied data, or NULL if there was an error.

See also: xCreateIntField()

References X_LONG, x_trace_null(), and xCreateScalarField().

◆ xCreateLookup()

XLookupTable * xCreateLookup	(	const XStructure *	s,
		boolean	recursive
	)

Creates a fast name lookup table for the fields of structure, with or without including fields of embedded substructures also. For structures with a large number of fields, such a lookup can significantly improve access times for retrieving specific fields from a structure. However, the lookup will not track fields added or removed after its creation, and so it is suited for accessing structures with a fixed layout only.

Since the lookup table contains references to the structure, you should not destroy the structure as long as the lookup table is used.

Once the lookup table is no longer used, the caller should explicitly destroy it with xDestroyLookup()

Parameters

s	Pointer to a structure, for which to create a field lookup.
recursive	Whether to include fields from substructures recursively in the lookup.

Returns: The lookup table, or NULL if there was an error (errno will inform about the type of error).

See also: xLookupField(); xDestroyLookup()

References x_error(), x_trace_null(), xAllocLookup(), xCountFields(), and xDeepCountFields().

◆ xCreateScalarField()

XField * xCreateScalarField	(	const char *	name,
		XType	type,
		const void *	value
	)

Creates a generic scalar field of a given name and native value. The structure will hold a copy of the value that is pointed at.

Parameters

name	Field name (it may not contain a separator X_SEP)
type	Storage type, e.g. X_INT.
value	Pointer to the native data location in memory.

Returns: A newly created field with the supplied data, or NULL if there was an error.

References x_trace_null(), and xCreateField().

◆ xCreateStringField()

XField * xCreateStringField	(	const char *	name,
		const char *	value
	)

Creates a field holding a single string value.

Parameters

name	Field name (it may not contain a separator X_SEP)
value	Associated value. NULL values will be treated as empty strings.

Returns: A newly created field referencing the supplied string, or NULL if there was an error.

References X_STRING, x_trace_null(), and xCreateScalarField().

◆ xCreateStruct()

XStructure * xCreateStruct ( )

Creates a new empty XStructure.

See also: smaxDestroyStruct()

◆ xDeepCountFields()

long xDeepCountFields ( const XStructure * s )

Counts the number of fields in a structure, including the field count for all embedded substructures also recursively.

Parameters

s	Pointer to a structure

Returns: The total number of fields present in the structure and all its sub-structures.

See also: xCountFields()

References XStructure::firstField, XField::name, XField::next, XField::type, XField::value, x_error(), X_STRUCT, x_trace(), xDeepCountFields(), and xGetFieldCount().

◆ xDestroyField()

void xDestroyField ( XField * f )

Destroys an X structure field, freeing up resources used. For

Parameters

f	Pointer to the field to be destroyed.

References XField::name, XField::type, XField::value, X_STRUCT, xClearStruct(), and xGetFieldCount().

◆ xDestroyLookup()

void xDestroyLookup ( XLookupTable * tab )

Destroys a lookup table, freeing up it's in-memory resources.

Parameters

tab	Pointer to the lookup table to destroy.

See also: xCreateLookup()

References XLookupTable::priv.

◆ xDestroyStruct()

void xDestroyStruct ( XStructure * s )

Destroys an X structure, freeing up resources used by name and value.

Parameters

s	Pointer to the structure to be destroyed.

References xClearStruct().

◆ 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_BYTE_HEX, X_DOUBLE, X_FLOAT, X_INT, X_INT_HEX, X_LONG, X_LONG_HEX, X_RAW, X_SHORT, X_SHORT_HEX, 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.

◆ xGetAggregateID()

char * xGetAggregateID	(	const char *	table,
		const char *	key
	)

Returns the aggregated (hierarchical) <table>:<key> ID. The caller is responsible for calling free() on the returned string after use.

Parameters

table	SMA-X hastable name
key	The lower-level id to concatenate.

Returns: The aggregated ID, or NULL if both arguments were NULL themselves.

See also: xSplitID()

References x_error(), X_SEP, X_SEP_LENGTH, and xStringCopyOf().

◆ xGetElementCount()

int 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.

◆ xGetField()

XField * xGetField	(	const XStructure *	s,
		const char *	id
	)

Return the field by the specified name, or NULL if no such field exists.

Parameters

s	Structure from which to retrieve a given field.
id	Name or aggregate ID of the field to retrieve

Returns: Matching field from the structure or NULL if there is no match or one of the arguments is NULL.

See also: xLookupField(); xSetField(); xGetSubstruct()

References XStructure::firstField, XField::name, XField::next, XField::type, x_error(), X_STRUCT, X_SUCCESS, xGetField(), xMatchNextID(), and xNextIDToken().

◆ xGetFieldCount()

int xGetFieldCount ( const XField * f )

Returns the total number of primitive elements in a field.

Parameters

f The field

Returns: The total number of primitive elements contained in the field.

References XField::ndim, XField::sizes, and xGetElementCount().

◆ xGetSubstruct()

XStructure * xGetSubstruct	(	const XStructure *	s,
		const char *	id
	)

Returns a substructure by the specified name, or NULL if no such sub-structure exists.

Parameters

s	Structure from which to retrieve a given sub-structure.
id	Name or aggregate ID of the substructure to retrieve

Returns: Matching sub-structure from the structure or NULL if there is no match or one of the arguments is NULL.

See also: xSetSubstruct(); xGetField()

References XField::type, XField::value, X_STRUCT, and xGetField().

◆ xIsCharSequence()

boolean xIsCharSequence ( XType type )

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

Parameters

type	X-Change type to check.

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

◆ xIsFieldValid()

boolean xIsFieldValid ( const XField * f )

Checks if a given field has valid data.

Parameters

f	Pointer to the field to check.

Returns: TRUE is the field seems to contain valid data, otherwise FALSE.

References FALSE, XField::name, XField::ndim, XField::sizes, TRUE, XField::type, XField::value, X_STRUCT, xElementSizeOf(), and xLastSeparator().

◆ 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.

◆ xLastSeparator()

char * xLastSeparator ( const char * id )

Returns the string pointer to the begining of the last separator in the ID.

Parameters

id	Compound SMA-X ID.

Returns: Pointer to the beginning of the last separator in the ID, or NULL if the ID does not contain a separator.

See also: xSplitID()

References x_error(), X_SEP, and X_SEP_LENGTH.

◆ xLookupCount()

long xLookupCount ( const XLookupTable * tab )

Returns the number of fields in the lookup table.

Parameters

tab	Pointer to the lookup table

Returns: the number of fields stored.

References XLookupTable::priv.

◆ xLookupField()

XField * xLookupField	(	const XLookupTable *	tab,
		const char *	id
	)

Returns a named field from a lookup table. When retriving a large number (hundreds or more) fields by name from very large structures, this methods of locating the relevant data can be significantly faster than the xGetField() / xGetSubstruct() approach.

Note however, that preparing the lookup table has significant O(N) computational cost also, whereas retrieving M fields with xGetField() / xGetSubstruct() have costs that scale O(N×M). Therefore, a lookup table is practical only if you are going to use it repeatedly, many times over. As a rule of thumb, lookups may have the advantage if accessing fields in a structure by name hundreds of times, or more.

Parameters

tab	Pointer to the lookup table
id	The aggregate ID of the field to find.

Returns: The corresponding field or NULL if no such field exists or tab was NULL.

See also: xCreateLookup(); xGetField()

References XLookupTable::priv, and x_error().

◆ xLookupPut()

int xLookupPut	(	XLookupTable *	tab,
		const char *	prefix,
		const XField *	field,
		XField **	oldValue
	)

Puts a field into the lookup table with the specified aggregate ID prefix. For example, if the prefix is "system:subsystem", and the field's name is "property", then the field will be available as "system:subsystem:property" in the lookup.

Parameters

tab	Pointer to a lookup table
prefix	The aggregate ID prefix before the field's name, not including a separator
field	The field
oldValue	(optional) pointer to a buffer in which to return the old field value (if any) stored under the same name. It may be NULL if not needed.

Returns: 0 if successfully added a new field, 1 if updated an existing fields, or else X_NULL if either of the arguments were NULL, or X_FAILURE if some other error.

See also: xLookupPutAll(); xLookupRemove()

References XLookupTable::priv, x_error(), X_FAILURE, and X_NULL.

◆ xLookupPutAll()

int xLookupPutAll	(	XLookupTable *	tab,
		const char *	prefix,
		const XStructure *	s,
		boolean	recursive
	)

Puts all fields from a structure into the lookup table with the specified aggregate ID prefix, with or without including embedded substructures. For example, if the prefix is "system:subsystem", and a field's name is "property", then that field will be available as "system:subsystem:property" in the lookup.

Parameters

tab	Pointer to a lookup table
prefix	The aggregate ID prefix before the field's name, not including a separator
s	The structure
recursive	Whether to include fields in all substructures recursively also.

Returns: the number of fields added (<=0), or else X_NULL if either of the arguments were NULL, or X_FAILURE if some other error.

See also: xLookupRemoveAll()

References XLookupTable::priv, x_error(), X_FAILURE, and X_NULL.

◆ xLookupRemove()

XField * xLookupRemove	(	XLookupTable *	tab,
		const char *	id
	)

Removes a field from a lookup table.

Parameters

tab	Pointer to the lookup table
id	The aggregate ID of the field as stored in the lookup

Returns: The field that was removed, or else NULL if not found.

See also: xLookupRemoveAll(); xLookupPut()

References XLookupTable::priv, x_error(), and X_NULL.

◆ xLookupRemoveAll()

int xLookupRemoveAll	(	XLookupTable *	tab,
		const char *	prefix,
		const XStructure *	s,
		boolean	recursive
	)

Removes all fields of a structure from the lookup table with the specified aggregate ID prefix, with or without including embedded substructures. For example, if the prefix is "system:subsystem", and a field's name is "property", then the field referred to as "system:subsystem:property" in the lookup is affected.

Parameters

tab	Pointer to a lookup table
prefix	The aggregate ID prefix before the field's name, not including a separator
s	The structure
recursive	Whether to include fields in all substructures recursively also.

Returns: the number of fields removed (<=0), or else X_NULL if either of the arguments were NULL, or X_FAILURE if some other error.

See also: xLookupRemoveAll()

References XLookupTable::priv, x_error(), X_FAILURE, and X_NULL.

◆ xMatchNextID()

int xMatchNextID	(	const char *	token,
		const char *	id
	)

Checks if the next component in a compound id matches a given token.

Parameters

token	Full token to check for
id	Compount X ID.

Returns: X_SUCCESS if it's a match. Otherwise X_FAILURE or another X error if the arguments are invalid.

References x_error(), X_FAILURE, X_GROUP_INVALID, X_NAME_INVALID, X_NULL, X_SEP, X_SEP_LENGTH, and X_SUCCESS.

◆ xNextIDToken()

char * xNextIDToken ( const char * id )

Returns a pointer to the beginning of the next component in a compound ID. Leading ID separators are ignored.

Parameters

id	Aggregate X ID.

Returns: Pointer to the start of the next compound ID token, or NULL if there is no more components in the ID.

References X_SEP, and X_SEP_LENGTH.

◆ 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
	)

Same as strtod() on C99, but with explicit parsing of NaN and Infinity values on older platforms also.

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.

References NAN, and x_error().

◆ 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 IEEE 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 IEEE double precision range, "nan" will be printed.

Parameters

str	Pointer to buffer for printed value.
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 IEEE 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 IEEE double precision range, "nan" will be printed.

Parameters

str	Pointer to buffer for printed value.
value	Value to print.

Returns: Number of characters printed into the buffer.

References x_error().

◆ xReduceAllDims()

int xReduceAllDims ( XStructure * s )

Recursively eliminates unneccessary embedding of singular structures inside a structure as well as reduces the dimension of all array fields with xReduceDims().

Parameters

s	Pointer to a structure.

Returns: X_SUCCESS (0) if successful or else X_STRUCT_INVALID if the argument is NULL (errno is also set to EINVAL)

See also: xReduceDims()

References XStructure::firstField, XField::name, XField::ndim, XField::next, XStructure::parent, XField::sizes, XField::type, x_error(), X_STRUCT, X_STRUCT_INVALID, x_trace(), xGetFieldCount(), xReduceAllDims(), and xReduceDims().

◆ xReduceDims()

int xReduceDims	(	int *	ndim,
		int *	sizes
	)

Reduces the dimensions by eliminating axes that contain a singular elements. Thus a size of {1, 3, 1, 5} will reduce to {3, 5} containing the same number of elements, in fewer dimensions. If any of the dimensions are zero then it reduces to { 0 }.

Parameters

[in,out]	ndim	Pointer to the dimensions (will be updated in situ)
[in,out]	sizes	Array of sizes along the dimensions (will be updated in situ)

Returns: X_SUCCESS (0) if successful or else X_SIZE_INVALID if the ndim argument is NULL, or if it is greater than zero but the sizes argument is NULL (errno set to EINVAL in both cases)

See also: xReduceAllDims()

References x_error(), X_SIZE_INVALID, and X_SUCCESS.

◆ xRemoveField()

XField * xRemoveField	(	XStructure *	s,
		const char *	name
	)

Removes as field from the structure, returning it if found.

Parameters

s	Pointer to structure
name	Name of field to remove

Returns: Pointer to the removed field or else NULL if the was an error or if no matching field existed in the structure.

References XStructure::firstField, XField::name, XField::next, XStructure::parent, XField::type, XField::value, x_error(), X_STRUCT, and xGetFieldCount().

◆ xReverseFieldOrder()

int xReverseFieldOrder	(	XStructure *	s,
		boolean	recursive
	)

Reverse the order of fields in a structure.

Parameters

s	The structure, whose field order to reverse.
recursive	Whether to apply the reversal to all ebmbedded substructures also

Returns: X_SUCCESS (0) if successful, or else X_NULL if the structure is NULL.

See also: xSortFields(); xSortFieldsByName(); xInsertField()

References XStructure::firstField, XField::next, TRUE, XField::type, XField::value, x_error(), X_NULL, X_STRUCT, X_SUCCESS, xGetFieldCount(), and xReverseFieldOrder().

◆ 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.

◆ xSetField()

XField * xSetField	(	XStructure *	s,
		XField *	f
	)

Adds or replaces a field in the structure with the specified field value, returning the previous value for the same field. It is up to the caller whether or not the old value should be destoyed or kept. Note though that you should check first to see if the replaced field is the same as the new one before attempting to destroy...

The field's name may not contain a compound ID. To add fields to embedded sub-structures, you may want to use xGetSubstruct() first to add the field directly to the relevant embedded component.

A note of caution: There is no safeguard against adding the same field to more than one structure, which will result in a corruption of the affected structures, since both structures would link to the field, but the field links to only one specific successive element. Therefore, the user is responsible to ensure that fields are assigned to structures uniquely, and if necessary remove the field from one structure before assigning it to another.

Parameters

s	Structure to which to add the field
f	Field to be added.

Returns: Previous field by the same name, or NULL if the field is new or if there was an error (errno will be set to EINVAL)

See also: xInsertField(); xSetSubstruct(); xGetSubstruct()

References XStructure::firstField, XField::name, XField::next, and x_error().

◆ xSetSubstruct()

XField * xSetSubstruct	(	XStructure *	s,
		const char *	name,
		XStructure *	substruct
	)

Inserts a structure within a parent structure, returning the old field that may have existed under the requested name before.

The name may not contain a compound ID. To add the structure to embedded sub-structures, you may want to use xGetSubstruct() first to add the new structure directly to the relevant embedded component.

Parameters

s	Pointer to the parent structure
name	Name of the sub-structure
substruct	Pointer to the sub-structure. It is added directly as a reference, without making a copy.

return The prior field stored under the same name or NULL. If there is an error then NULL is returned and errno is set to indicate the nature of the issue. (a message is also printed to stderr if xDebug is enabled.)

See also: xGetSubstruct()

References XStructure::parent, x_error(), X_STRUCT, x_trace_null(), xCreateScalarField(), and xSetField().

◆ 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.

◆ xSortFields()

int xSortFields	(	XStructure *	s,
		int()(const XField f1, const XField *f2)	cmp,
		boolean	recursive
	)

Sort the fields in a structure using a specific comparator function.

Parameters

s	The structure, whose fields to sort
cmp	The comparator function. It takes two pointers to XField locations as arguments.
recursive	Whether to apply the sorting to all ebmbedded substructures also

Returns: X_SUCCESS (0) if successful, or else X_NULL if the structure or the comparator function is NULL.

See also: xSortFieldsByName(); xReverseFieldOrder()

References XStructure::firstField, XField::next, TRUE, XField::type, XField::value, x_error(), X_NULL, X_STRUCT, X_SUCCESS, xGetFieldCount(), and xSortFields().

◆ xSortFieldsByName()

int xSortFieldsByName	(	XStructure *	s,
		boolean	recursive
	)

Sorts the fields of a structure by field name, in ascending alphabetical order.

Parameters

s	The structure, whose fields to sort
recursive	Whether to apply the sorting to all ebmbedded substructures also

Returns: X_SUCCESS (0) if successful, or else X_NULL if the structure is NULL.

See also: xReverseFieldOrder()

References X_SUCCESS, and xSortFields().

◆ xSplitID()

int xSplitID	(	char *	id,
		char **	pKey
	)

Splits the id into two strings (sharing the same input buffer): (1) the id of the embedding structure, and (2) the embedded field name. The original input id is string terminated after the table name. And the pointer to the key part that follows after the last separator is returned in the second (optional argument).

Parameters

[in,out]	id	String containing an aggregate ID, which will be terminated after the last substructure.
[out]	pKey	Returned pointer to the second component after the separator within the same buffer. This is not an independent pointer. Use xStringCopyOf() if you need an idependent string on which free() can be called! The returned value pointed to may be NULL if the ID could not be split. The argument may also be null, in which case the input string is just terminated at the stem, without returning the second part.

Returns: X_SUCCESS (0) if the ID was successfully split into two components. X_NULL if the id argument is NULL. X_NAME_INVALID if no separator was found

See also: xGetAggregateID(); xLastSeparator()

References x_error(), X_NAME_INVALID, X_NULL, X_SEP_LENGTH, X_SUCCESS, and xLastSeparator().

◆ 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_BYTE_HEX, X_DOUBLE, x_error(), X_FLOAT, X_INT, X_INT_HEX, X_LONG, X_LONG_HEX, X_SHORT, and X_SHORT_HEX.

◆ 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().

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ X_FIELD_INIT

◆ X_STRUCT_INIT

◆ XCHANGE_VERSION_STRING

Function Documentation

◆ xAlloc()

◆ xAllocLookup()

◆ xClearStruct()

◆ xCopyIDToken()

◆ xCopyOfField()

◆ xCopyOfStruct()

◆ xCountFields()

◆ xCreate1DField()

◆ xCreateBooleanField()

◆ xCreateDoubleField()

◆ xCreateField()

◆ xCreateIntField()

◆ xCreateLongField()

◆ xCreateLookup()

◆ xCreateScalarField()

◆ xCreateStringField()

◆ xCreateStruct()

◆ xDeepCountFields()

◆ xDestroyField()

◆ xDestroyLookup()

◆ xDestroyStruct()

◆ xElementSizeOf()

◆ xError()

◆ xErrorDescription()

◆ xGetAggregateID()

◆ xGetElementCount()

◆ xGetField()

◆ xGetFieldCount()

◆ xGetSubstruct()

◆ xIsCharSequence()

◆ xIsFieldValid()

◆ xIsVerbose()

◆ xLastSeparator()

◆ xLookupCount()

◆ xLookupField()

◆ xLookupPut()

◆ xLookupPutAll()

◆ xLookupRemove()

◆ xLookupRemoveAll()

◆ xMatchNextID()

◆ xNextIDToken()

◆ xParseBoolean()

◆ xParseDims()

◆ xParseDouble()

◆ xPrintDims()

◆ xPrintDouble()

◆ xPrintFloat()

◆ xReduceAllDims()

◆ xReduceDims()

◆ xRemoveField()

◆ xReverseFieldOrder()

◆ xSetDebug()

◆ xSetField()

◆ xSetSubstruct()

◆ xSetVerbose()

◆ xSortFields()

◆ xSortFieldsByName()

◆ xSplitID()

◆ xStringCopyOf()

◆ xStringElementSizeOf()

◆ xTypeChar()

◆ xZero()