A collection of commonly used functions for generic structured data exchange. More...

Macros
#define	__XCHANGE_INTERNAL_API__
	Use internal definitions.

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

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

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

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	xDestroyStruct (XStructure *s)

char *	xGetAggregateID (const char table, 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)

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

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)

int	xInsertField (XStructure s, XField f)

boolean	xIsFieldValid (const XField *f)

char *	xLastSeparator (const char *id)

int	xMatchNextID (const char token, const char id)

char *	xNextIDToken (const char *id)

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)

XField *	xSetField (XStructure s, XField f)

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

int	xSetSubtype (XField f, const char type)

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)

Detailed Description

A collection of commonly used functions for generic structured data exchange.

Date: Nov 25, 2020

Author: Attila Kovacs

Function Documentation

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

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

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

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

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

◆ xInsertField()

int xInsertField	(	XStructure *	s,
		XField *	f
	)

(expert) Inserts a field into the structure at its head position. That is, the specified field will become the first field in the structure. And, unlike xSetField(), this function does not check for (nor remove) previously present fields by the same name. Thus, it is left up to the caller to ensure that there are no duplicate field names added to the structure.

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.

See also: xSetField(); xReverseFieldOrder()

References XStructure::firstField, XField::name, XField::next, x_error(), X_NAME_INVALID, X_NULL, X_STRUCT_INVALID, X_SUCCESS, and xLastSeparator().

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

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

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

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

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

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

Macros

Functions

Detailed Description

Function Documentation

◆ xClearField()

◆ xClearStruct()

◆ xCopyIDToken()

◆ xCopyOfField()

◆ xCopyOfStruct()

◆ xCountFields()

◆ xCreate1DField()

◆ xCreateBooleanField()

◆ xCreateDoubleField()

◆ xCreateField()

◆ xCreateIntField()

◆ xCreateLongField()

◆ xCreateMixed1DField()

◆ xCreateMixedArrayField()

◆ xCreateScalarField()

◆ xCreateStringField()

◆ xCreateStruct()

◆ xDeepCountFields()

◆ xDestroyField()

◆ xDestroyStruct()

◆ xGetAggregateID()

◆ xGetAsDouble()

◆ xGetAsDoubleAtIndex()

◆ xGetAsLong()

◆ xGetAsLongAtIndex()

◆ xGetElementAtIndex()

◆ xGetField()

◆ xGetFieldCount()

◆ xGetStringAtIndex()

◆ xGetStringValue()

◆ xGetSubstruct()

◆ xInsertField()

◆ xIsFieldValid()

◆ xLastSeparator()

◆ xMatchNextID()

◆ xNextIDToken()

◆ xReduceDims()

◆ xReduceField()

◆ xReduceStruct()

◆ xRemoveField()

◆ xReverseFieldOrder()

◆ xSetField()

◆ xSetSubstruct()

◆ xSetSubtype()

◆ xSortFields()

◆ xSortFieldsByName()

◆ xSplitID()