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	INFINITY (1.0/0.0)
	Infinity in case it's not already defined in math.h.

#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_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
	XType for an XField or array thereof.

#define	X_FIELD_INIT {NULL, NULL, X_UNKNOWN, NULL, 0, {0}, FALSE, 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_INTERRUPTED (-8)
	a waiting call interrupted by user

#define	X_LONG
	64-bit int XType

#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_SIZE_INVALID (-23)
	invalid data size

#define	X_STRING
	a terminated string XType

#define	X_STRUCT
	XType for an XStructure or array thereof.

#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 1
	API major version.

#define	XCHANGE_MINOR_VERSION 0
	API minor version.

#define	XCHANGE_PATCHLEVEL 0
	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	xClearField (XField *f)

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 *	xCreateMixed1DField (const char name, int size, XField value)

XField *	xCreateMixedArrayField (const char name, int ndim, const int sizes, XField *value)

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)

double	xGetAsDouble (const XField *f)

double	xGetAsDoubleAtIndex (const XField *f, int idx)

long	xGetAsLong (const XField *f, long defaultValue)

long	xGetAsLongAtIndex (const XField *f, int idx, long defaultValue)

void *	xGetElementAtIndex (const XField *f, int idx)

int	xGetElementCount (int ndim, const int *sizes)

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

int	xGetFieldCount (const XField *f)

char *	xGetStringAtIndex (const XField *f, int idx)

char *	xGetStringValue (const XField *f)

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

boolean	xIsCharSequence (XType type)

boolean	xIsDecimal (XType type)

boolean	xIsFieldValid (const XField *f)

boolean	xIsInteger (XType type)

boolean	xIsNumeric (XType type)

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	xReduceDims (int ndim, int sizes)

int	xReduceField (XField *f)

int	xReduceStruct (XStructure *s)

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)

int	xSetSubtype (XField f, const char type)

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

Version: 1.0

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

Macro Definition Documentation

◆ X_FIELD_INIT

#define X_FIELD_INIT {NULL, NULL, X_UNKNOWN, NULL, 0, {0}, FALSE, 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().

◆ xClearField()

void xClearField ( XField * f )

Clears an X structure field, freeing up all referfenced resources. However, the field itself is kept, but its contents are reset.

Parameters

f	Pointer to the field to be cleared.

See also: xDestroyField()

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

◆ 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_NULL, 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 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, x_trace_null(), 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 fields in the structure, you should not destroy the fields as long as the lookup table is used (but you may call free() the structure itself).

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

◆ xCreateMixed1DField()

XField * xCreateMixed1DField	(	const char *	name,
		int	size,
		XField *	array
	)

Creates a field containing a 1D array of heterogeneous fields. Each element of the array may have a different type and/or size.

Parameters

name	The name of the array field
size	The number of heterogeneous fields in the array.
array	The XField array of rows containing varying types and dimensions within them.

Returns: A field containing a heterogeneous array of entries, or NULL if there was an error. The entries are initially empty, except for their names bearing '.' followed by the 1-based array index, e.g. '.1', '.2'...

See also: xCreateMixedArrayField()

References X_MAX_DIMS, and xCreateMixedArrayField().

◆ xCreateMixedArrayField()

XField * xCreateMixedArrayField	(	const char *	name,
		int	ndim,
		const int *	sizes,
		XField *	array
	)

Creates a field containing an array of heterogeneous fields. Each element of the array may have a different type and/or size.

Parameters

name	The name of the array field
ndim	The dimensionality of the heterogeneous components
sizes	The individual sizes along each dimension
array	The XField array of elements containing varying types and dimensions within them.

Returns: A field containing a heterogeneous array of entries, or NULL if there was an error. The entries are initially empty, except for their names bearing '.' followed by the 1-based array index, e.g. '.1', '.2'...

See also: xCreateMixed1DField()

References XField::name, X_FIELD, x_trace_null(), xCreateField(), xGetElementCount(), and xStringCopyOf().

◆ 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. The field will hold a copy of the supplied value, so the caller may destroy the string safely after the call.

Parameters

name	Field name (it may not contain a separator X_SEP)
value	Associated value (it may be NULL). The string will be copied, not referenced.

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 all referenced resources, and destroying the field itself.

Parameters

f	Pointer to the field to be destroyed.

See also: xClearField()

References xClearField().

◆ 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_DOUBLE, X_FIELD, X_FLOAT, X_INT, X_LONG, X_RAW, X_SHORT, 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().

◆ xGetAsDouble()

double xGetAsDouble ( const XField * f )

Return a double-precision floating point value associated to the field, or else NAN if the field cannot be represented as a decimal value. This call will use widening conversions as necessary to convert between numerical types (e.g. short to double), while for string values will attempt to parse a decomal value.

If the field is an array, the first element is converted and returned.

Parameters

f	Pointer to field

Returns: The value of the field, represented as a double-precision floating point value, if possible, or else NAN. In case of error errno will be set to a non-zero value indicating the type of error.

See also: xGetAsDoubleAtIndex(); xGetAsLong(); xGetStringValue()

References x_trace_null(), and xGetAsDoubleAtIndex().

◆ xGetAsDoubleAtIndex()

double xGetAsDoubleAtIndex	(	const XField *	f,
		int	idx
	)

Return a double-precision floating point value associated to the field, or else NAN if the element cannot be represented as a decimal value. This call will use widening conversions as necessary to convert between numerical types (e.g. short to double), while for string values will attempt to parse a decomal value.

Parameters

f	Pointer to field
idx	Array index (zero-based) of the element of interest.

Returns: The value of the field, represented as a double-precision floating point value, if possible, or else NAN. In case of error errno will be set to a non-zero value indicating the type of error.

See also: xGetAsDouble(); xGetAsLongAtIndex(); xGetStringAtIndex()

References XField::isSerialized, NAN, XField::type, XField::value, X_BOOLEAN, X_BYTE, X_DOUBLE, x_error(), X_FLOAT, X_INT, X_LONG, X_RAW, X_SHORT, X_STRING, x_trace_null(), xElementSizeOf(), xGetElementAtIndex(), and xIsCharSequence().

◆ xGetAsLong()

long xGetAsLong	(	const XField *	f,
		long	defaultValue
	)

Return a signed integer value associated to the field, or else the specified default value if the field cannot be represented as an integer. This call will use both widening and narrowing conversions, and rounding, as necessary to convert between numerical types (e.g. float to long), while for string values will attempt to parse an integer value.

If the field is an array, the first element is converted and returned.

Parameters

f	Pointer to a field.
defaultValue	The value to return if the structure contains no field with the specified ID, or if it cannot be represented as an integer though narrowing or widening conversions, rounding, or through parsing.

Returns: The value of the field, represented as an integer, if possible, or else the specified default value. In case of error errno will be set to a non-zero value indicating the type of error.

See also: xGetAsLongAtIndex(); xGetAsDouble(); xGetStringValue()

References x_trace(), and xGetAsLongAtIndex().

◆ xGetAsLongAtIndex()

long xGetAsLongAtIndex	(	const XField *	f,
		int	idx,
		long	defaultValue
	)

Return a signed integer value associated to the value at the specified array index in the field, or else the specified default value if the element cannot be represented as an integer. This call will use both widening and narrowing conversions, and rounding, as necessary to convert between numerical types (e.g. float to long), while for string values will attempt to parse an integer value.

Parameters

f	Pointer to a field.
idx	Array index (zero-based) of the element of interest.
defaultValue	The value to return if the structure contains no field with the specified ID, or if it cannot be represented as an integer though narrowing or widening conversions, rounding, or through parsing.

Returns: The value of the field, represented as an integer, if possible, or else the specified default value. In case of error errno will be set to a non-zero value indicating the type of error.

See also: xGetAsLong(); xGetAsDoubleAtIndex(); xGetStringAtIndex()

References XField::isSerialized, NAN, XField::type, XField::value, X_BOOLEAN, X_BYTE, X_DOUBLE, x_error(), X_FLOAT, X_INT, X_LONG, X_RAW, X_SHORT, X_STRING, x_trace(), xElementSizeOf(), xGetElementAtIndex(), and xIsCharSequence().

◆ xGetElementAtIndex()

void * xGetElementAtIndex	(	const XField *	f,
		int	idx
	)

Returns a pointer to the array element at the specified index.

Parameters

f	Pointer to a field
idx	the array index of the requested element

Returns: A pointer to the element at the given index, or NULL if there was an error.

See also: xGetAsLongAtIndex(); xGetAsDoubleAtIndex(); xGetStringAtIndex()

References XField::type, XField::value, x_error(), x_trace_null(), xElementSizeOf(), and xGetFieldCount().

◆ 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 reference to 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: xGetAsLong(); xGetAsDouble(); xLookupField(); xSetField(); xGetSubstruct()

References XStructure::firstField, XField::name, XField::next, XField::type, XField::value, 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, x_error(), and xGetElementCount().

◆ xGetStringAtIndex()

char * xGetStringAtIndex	(	const XField *	f,
		int	idx
	)

Returns a reference to the string value at the specified array index in the field, or else NULL if the element is not string typed, or if the index is out of bounds. Only fields containing X_STRING or X_RAW type values, or fixed-sized character sequences (XCHARS(n) type), can will return a pointer reference to the value. Or, if the field is in serialized form, then the pointer to the serialized value is returned. For fixed-length character sequences the string pointed at may not be null-terminated.

Parameters

f	Pointer to field
idx	Array index (zero-based) of the element of interest.

Returns: Pointer to the string value of the field or NULL. In case of error errno will be set to a non-zero value indicating the type of error.

See also: xGetStringValue(); xGetAsLongAtIndex(); xGetDoubleAtIndex()

References XField::isSerialized, XField::type, XField::value, x_error(), X_RAW, X_STRING, x_trace_null(), xGetElementAtIndex(), and xIsCharSequence().

◆ xGetStringValue()

char * xGetStringValue ( const XField * f )

Returns a reference to the string value stored in the field, or else NULL if the element is not string typed. Only fields containing X_STRING or X_RAW type values, or fixed-sized character sequences (XCHARS(n) type), can will return a pointer reference to the value. Or, if the field is in serialized form, then the pointer to the serialized value is returned.For fixed-length character sequences the string pointed at may not be null-terminated.

If the field is an array, the first element is returned.

Parameters

f	Pointer to field

Returns: Pointer to the string value of the field or NULL. In case of error errno will be set to a non-zero value indicating the type of error.

See also: xGetStringAtIndex(); xGetAsLong(); xGetAsDouble()

References x_trace_null(), and xGetStringAtIndex().

◆ 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_error(), X_STRUCT, and xGetField().

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

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

◆ 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_INT, X_LONG, and X_SHORT.

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

◆ 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, or an error <0 (usually X_NO_INIT) if the lookup table is invalid

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_NO_INIT if the table was not properly initialized, or else 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_NO_INIT if the table was not initialized, or else 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_NO_INIT if the table was not initialized, or else 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 INFINITY, 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().

◆ 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: xReduceStruct()

References x_error(), X_SIZE_INVALID, and X_SUCCESS.

◆ xReduceField()

int xReduceField ( XField * f )

Reduces a field by eliminating extraneous dimensions, and/or wrapping recursively.

Parameters

f	Pointer to a field

Returns: X_SUCCESS (0) if successful, or else an xchange.h error code <0.

See also: xReduceStruct(); xReduceDims()

References XField::ndim, XField::sizes, XField::type, XField::value, x_error(), X_FIELD, X_NULL, X_STRUCT, X_SUCCESS, xGetFieldCount(), xReduceDims(), and xReduceStruct().

◆ xReduceStruct()

int xReduceStruct ( XStructure * s )

Recursively eliminates unneccessary embedding of singular structures inside a structure and reduces the dimensions of array fields with xReduceDims(), recursively. It will also eliminate the unnecessary wrapping of a singular array into a single XField.

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: xReduceField()

References XStructure::firstField, XField::next, XStructure::parent, XField::type, XField::value, x_error(), X_STRUCT, X_STRUCT_INVALID, X_SUCCESS, xGetFieldCount(), xReduceField(), and xReduceStruct().

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

◆ xSetSubtype()

int xSetSubtype	(	XField *	f,
		const char *	type
	)

Sets the optional subtype for a field's content to a copy of the specified string value. The subtype can be used to add any application specific information on how the specified value should be used. For example it may indicate a mime type or an encoding. It is entirely up to the user as to what meaning the subtype has for their application.

Parameters

f	Pointer to a field
type	The new subtype to be assigned to the field. A copy of the value is used rather than the reference, so that the string that was supplied can be safely discarded at any point after the call.

Returns: X_SUCCESS (0) if successful or else X_NULL if the intput field pointer is NULL.

References XField::subtype, x_error(), X_NULL, X_SUCCESS, and xStringCopyOf().

◆ 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_FAILURE, 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_DOUBLE, x_error(), X_FLOAT, X_INT, X_LONG, and X_SHORT.

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

◆ xClearField()

◆ xClearStruct()

◆ xCopyIDToken()

◆ xCopyOfField()

◆ xCopyOfStruct()

◆ xCountFields()

◆ xCreate1DField()

◆ xCreateBooleanField()

◆ xCreateDoubleField()

◆ xCreateField()

◆ xCreateIntField()

◆ xCreateLongField()

◆ xCreateLookup()

◆ xCreateMixed1DField()

◆ xCreateMixedArrayField()

◆ xCreateScalarField()

◆ xCreateStringField()

◆ xCreateStruct()

◆ xDeepCountFields()

◆ xDestroyField()

◆ xDestroyLookup()

◆ xDestroyStruct()

◆ xElementSizeOf()

◆ xError()

◆ xErrorDescription()

◆ xGetAggregateID()

◆ xGetAsDouble()

◆ xGetAsDoubleAtIndex()

◆ xGetAsLong()

◆ xGetAsLongAtIndex()

◆ xGetElementAtIndex()

◆ xGetElementCount()

◆ xGetField()

◆ xGetFieldCount()

◆ xGetStringAtIndex()

◆ xGetStringValue()

◆ xGetSubstruct()

◆ xIsCharSequence()

◆ xIsDecimal()

◆ xIsFieldValid()

◆ xIsInteger()

◆ xIsNumeric()

◆ xIsVerbose()

◆ xLastSeparator()

◆ xLookupCount()

◆ xLookupField()

◆ xLookupPut()

◆ xLookupPutAll()

◆ xLookupRemove()

◆ xLookupRemoveAll()

◆ xMatchNextID()

◆ xNextIDToken()

◆ xParseBoolean()

◆ xParseDims()

◆ xParseDouble()

◆ xPrintDims()

◆ xPrintDouble()

◆ xPrintFloat()

◆ xReduceDims()

◆ xReduceField()

◆ xReduceStruct()

◆ xRemoveField()

◆ xReverseFieldOrder()

◆ xSetDebug()

◆ xSetField()

◆ xSetSubstruct()

◆ xSetSubtype()