variant

Collaboration diagram for variant:

Modules
	variant type ids
	variant flags
	variant utils
	variant type helper functions
	Variant type specific helper functions.

Data Structures
struct	_amxc_var
	The variant struct definition. More...

Macros
#define	amxc_var_set(type, var, data)   amxc_var_set_ ## type(var, data)
	Convenience macro for setting a value in a variant. More...
#define	amxc_var_add(type, var, data)   amxc_var_add_new_ ## type(var, data)
	Convenience macro for adding a variant to composite variant type. More...
#define	amxc_var_add_key(type, var, key, data)   amxc_var_add_new_key_ ## type(var, key, data)
	Convenience macro for adding a variant to composite variant type. More...
#define	amxc_var_dyncast(type, var)   amxc_var_get_ ## type(var)
	Dynamic cast a variant to a certain type. More...
#define	amxc_var_constcast(type, var)   amxc_var_get_const_ ## type(var)
	Takes the content from a variant. More...
#define	amxc_var_take(type, var)   amxc_var_take_ ## type(var)
	Takes the content from a variant. More...
#define	amxc_var_push(type, var, val)   amxc_var_push_ ## type(var, val)
	Pushes a value into the variant. More...
#define	amxc_var_for_each(var, var_list)
	When the variant is a htable or list variant, iterates over the variants in the htable or list. More...
#define	amxc_var_for_each_reverse(var, var_list)
	When the variant is a htable or list variant, iterates over the variants in reverse order. More...

Typedefs
typedef struct _amxc_var	amxc_var_t
	The variant struct definition. More...

Functions
int	amxc_var_new (amxc_var_t **var)
	Allocates a variant and initializes it to the null variant type. More...
void	amxc_var_delete (amxc_var_t **var)
	Frees the previously allocated variant. More...
int	amxc_var_init (amxc_var_t *const var)
	Initializes a variant. More...
void	amxc_var_clean (amxc_var_t *const var)
	Clean-up and reset variant. More...
int	amxc_var_set_type (amxc_var_t *const var, const uint32_t type)
	Change the variant data type. More...
int	amxc_var_copy (amxc_var_t *const dest, const amxc_var_t *const src)
	Copy the type and data from one variant (source) in another variant (destination). More...
int	amxc_var_move (amxc_var_t *const dest, amxc_var_t *const src)
	Moves the type and data from one variant (source) in another variant (destination). More...
int	amxc_var_convert (amxc_var_t *const dest, const amxc_var_t *src, const uint32_t type_id)
	Converts one variant (source) to another variant(destination) using the specified variant type id. More...
int	amxc_var_cast (amxc_var_t *const var, const uint32_t type_id)
	Casts the variant to another variant type id. More...
int	amxc_var_compare (const amxc_var_t *const var1, const amxc_var_t *const var2, int *const result)
	Compares two variants. More...
AMXC_INLINE void	amxc_var_take_it (amxc_var_t *const var)
	Removes the variant for a llist and/or a htable. More...
amxc_var_t *	amxc_var_get_key (const amxc_var_t *const var, const char *const key, const int flags)
	Get a reference to a part of composed variant using a key. More...
int	amxc_var_set_key (amxc_var_t *const var, const char *const key, amxc_var_t *data, const int flags)
	Sets a part of composed variant using a key. More...
AMXC_INLINE amxc_var_t *	amxc_var_take_key (amxc_var_t *const var, const char *const key)
	Get a reference to a part of composed variant using a key and removes it from the composed variant. More...
amxc_var_t *	amxc_var_get_index (const amxc_var_t *const var, const int64_t index, const int flags)
	Get a reference to a part of composed variant using an index. More...
int	amxc_var_set_index (amxc_var_t *const var, const int64_t index, amxc_var_t *data, const int flags)
	Set a part of composed variant using an index. More...
AMXC_INLINE amxc_var_t *	amxc_var_take_index (amxc_var_t *const var, const int64_t index)
	Get a reference to a part of composed variant using an index and removes it from the composed variant. More...
amxc_var_t *	amxc_var_add_new_key (amxc_var_t *const var, const char *key)
	Adds a new variant with a key to a composite variant. More...
amxc_var_t *	amxc_var_add_new (amxc_var_t *const var)
	Adds a new variant to a composite variant. More...
amxc_var_t *	amxc_var_get_path (const amxc_var_t *const var, const char *const path, const int flags)
	Retrieves the variant at the given path of a composite variant. More...
amxc_var_t *	amxc_var_get_pathf (const amxc_var_t *const var, const int flags, const char *const fmt,...) __attribute__((format(printf
	Retrieves the variant at the given path of a composite variant. More...
amxc_var_t int	amxc_var_set_path (amxc_var_t *const var, const char *const path, amxc_var_t *data, const int flags)
	Sets the variant at the given path of a composite variant. More...
int	amxc_var_set_pathf (amxc_var_t *const var, amxc_var_t *data, const int flags, const char *const fmt,...) __attribute__((format(printf
	Sets the variant at the given path of a composite variant. More...
int amxc_var_t *	amxc_var_get_first (const amxc_var_t *const var)
	Gets the first variant in a htable or list variant. More...
amxc_var_t *	amxc_var_get_last (const amxc_var_t *const var)
	Gets the last variant in a htable or list variant. More...
amxc_var_t *	amxc_var_get_next (const amxc_var_t *const var)
	Gets the next variant. More...
amxc_var_t *	amxc_var_get_previous (const amxc_var_t *const var)
	Gets the previous variant. More...
amxc_var_t *	amxc_var_get_parent (const amxc_var_t *const var)
	Gets the containing variant. More...
const char *	amxc_var_key (const amxc_var_t *const var)
	Gets the key, with which the variant is stored in a htable variant. More...
uint32_t	amxc_var_type_of (const amxc_var_t *const var)
	Gets the variant type id of a variant. More...
const char *	amxc_var_type_name_of (const amxc_var_t *const var)
	Gets the variant type name of a variant. More...
AMXC_INLINE bool	amxc_var_is_null (const amxc_var_t *const var)
	Checks if the given variant is of the "null" type. More...

Detailed Description

A variant is a generic data container and can contain primitive types or composite types.

Variant Primitive Types

• null (void - no value)
• cstring_t (char *)
• int8_t
• uint8_t
• int16_t
• uint16_t
• int32_t
• uint32_t
• int64_t
• uint64_t
• float
• double
• bool
• fd_t (file descriptor)
• ts_t (timestamp)

Variant Composite Types

• amxc_llist_t - contains a list of variants
• amxc_htable_t - contains a hash table with key value pairs where the key is a string and the value is a variant

Macro Definition Documentation

amxc_var_add

#define amxc_var_add	(		type,
			var,
			data
	)		amxc_var_add_new_ ## type(var, data)

Convenience macro for adding a variant to composite variant type.

Macro expands to amxc_var_add_new_<TYPE>>(var, data)

Definition at line 618 of file amxc_variant.h.

amxc_var_add_key

#define amxc_var_add_key	(		type,
			var,
			key,
			data
	)		amxc_var_add_new_key_ ## type(var, key, data)

Convenience macro for adding a variant to composite variant type.

Macro expands to amxc_var_add_new_key_<TYPE>>(var, key, data)

Definition at line 627 of file amxc_variant.h.

amxc_var_constcast

#define amxc_var_constcast	(		type,
			var
	)		amxc_var_get_const_ ## type(var)

Takes the content from a variant.

If the given variant is not of the type specified, it will return a default value, NULL for pointers, 0 for integers or double, false for boolean. Only works on variants containing pointer types.

The type of the variant can be queried using amxc_var_type_of

Warning

No conversions are done using this macro. If the returned value is not what you expect, you can try amxc_var_dyncast. If this works, the original variant type is different from your requested type in amxc_var_constcast.

Note

When pointers are returned, the pointers are refering to the data in the variant and must not be freed.

This macro expands to amxc_var_get_const_<TYPE>(var) The default variant type implementation provides these functions:

• amxc_var_get_const_bool - returns a bool
• amxc_var_get_const_int8_t - returns a int8_t
• amxc_var_get_const_uint8_t - returns a uint8_t
• amxc_var_get_const_int16_t - returns a int16_t
• amxc_var_get_const_uint16_t - returns a uint16_t
• amxc_var_get_const_int32_t - returns a int32_t
• amxc_var_get_const_uint32_t - returns a uint32_t
• amxc_var_get_const_int64_t - returns a int64_t
• amxc_var_get_const_uint64_t - returns a uint64_t
• amxc_var_get_const_double - returns a double
• amxc_var_get_const_fd_t - returns a file descriptor
• amxc_var_get_const_amxc_htable_t - returns a const pointer to a hash table,
• amxc_var_get_const_amxc_llist_t - returns a const pointer to a linked list
• amxc_var_get_const_cstring_t - returns a const char*
• amxc_var_get_const_amxc_ts_t - returns a const pointer to a timestamp

Custom variant type implementations may implement a amxc_var_get_const_<CUSTOM_TYPE> function, see the documentation of the custom types for more information.

Definition at line 722 of file amxc_variant.h.

amxc_var_dyncast

#define amxc_var_dyncast	(		type,
			var
	)		amxc_var_get_ ## type(var)

Dynamic cast a variant to a certain type.

Conversion is applied and a copy is given. If a pointer is returned, the allocated memory must be freed. If a value is returned, there is no memory allocation.

When the requested type is not the same type as the type of the variant the value in the variant is converted to the requested type. If the conversion is not possible or fails, a default value is returned.

It is possible that memory is allocated to be able to store the requested type, this is only the case when a pointer is returned. For primitive types like uint32_t, bool, double, ... no memory is allocated, the value is returned.

When a pointer is returned it must be freed.

Note

This macro expands to amxc_var_get_<TYPE>(var) The default variant type implementation provides these functions:

• amxc_var_get_bool - returns a bool
• amxc_var_get_int8_t - returns a int8_t
• amxc_var_get_uint8_t - returns a uint8_t
• amxc_var_get_int16_t - returns a int16_t
• amxc_var_get_uint16_t - returns a uint16_t
• amxc_var_get_int32_t - returns a int32_t
• amxc_var_get_uint32_t - returns a uint32_t
• amxc_var_get_int64_t - returns a int64_t
• amxc_var_get_uint64_t - returns a uint64_t
• amxc_var_get_double - returns a double
• amxc_var_get_fd_t - returns a file descriptor
• amxc_var_get_amxc_htable_t - returns a pointer to a hash table, this must be freed when not needed anymore use amxc_htable_delete
• amxc_var_get_amxc_llist_t - returns a pointer to a linked list this must be freed when not needed anymore use amxc_llist_delete
• amxc_var_get_cstring_t - returns a char* this must be freed when not needed anymore use free()
• amxc_var_get_amxc_ts_t - returns a pointer to a timestamp this must be freed when not needed anymore use free()

Custom variant type implementations may implement a amxc_var_get_<CUSTOM_TYPE> function, see the documentation of the custom types for more information.

Definition at line 678 of file amxc_variant.h.

amxc_var_for_each

#define amxc_var_for_each	(		var,
			var_list
	)

Value:

    for(amxc_var_t* var = amxc_var_get_first(var_list), \
        * var ## _next = amxc_var_get_next(var); \
        var; \
        var = var ## _next, \
        var ## _next = amxc_var_get_next(var))

When the variant is a htable or list variant, iterates over the variants in the htable or list.

When the variant is not of a htable or list type, this macro will do nothing

It is save to delete the current variant in the loop.

Warning

When a variant is contained in a list and in a htable, the next variant will be the next in the htable. If you want to iterate over all variants in a variant list and all or some of variants are also in a htable, it is better to cast the container variant to a llist using amxc_var_constcast and use amxc_llist_for_each to iterate over all variants in the list.

Definition at line 819 of file amxc_variant.h.

amxc_var_for_each_reverse

#define amxc_var_for_each_reverse	(		var,
			var_list
	)

Value:

    for(amxc_var_t* var = amxc_var_get_last(var_list), \
        * var ## _prev = amxc_var_get_previous(var); \
        var; \
        var = var ## _prev, \
        var ## _prev = amxc_var_get_previous(var))

When the variant is a htable or list variant, iterates over the variants in reverse order.

When the variant is not of a htable or list type, this macro will do nothing

It is save to delete the current variant in the loop.

Warning

When a variant is contained in a list and in a htable, the previous variant will be the previous in the htable. If you want to iterate over all variants in a variant list and all or some of variants are also in a htable, it is better to cast the container variant to a llist using amxc_var_constcast and use amxc_llist_for_each_reverse to iterate over all variants in the list.

Definition at line 843 of file amxc_variant.h.

amxc_var_push

#define amxc_var_push	(		type,
			var,
			val
	)		amxc_var_push_ ## type(var, val)

Pushes a value into the variant.

Only works on variants containing pointer types.

No conversions are applied, no copies are done. The ownership of the pointer is transferred to the variant.

Note

Macro expands to amxc_var_push_<TYPE>(var, val) The default variant type implementation provides these functions:

• amxc_var_push_cstring_t
• amxc_var_push_amxc_string_t
• amxc_var_take_csv_string_t
• amxc_var_take_ssv_string_t

Custom variant type implementations may implement a amxc_var_push_<CUSTOM_TYPE> function, see the documentation of the custom types for more information.

Definition at line 780 of file amxc_variant.h.

amxc_var_set

#define amxc_var_set	(		type,
			var,
			data
	)		amxc_var_set_ ## type(var, data)

Convenience macro for setting a value in a variant.

Macro expands to amxc_var_set_<TYPE>>(var, data)

Definition at line 609 of file amxc_variant.h.

amxc_var_take

#define amxc_var_take	(		type,
			var
	)		amxc_var_take_ ## type(var)

Takes the content from a variant.

If the given variant is not of the type specified, it will return NULL. Only works on variants containing pointer types.

No conversions are applied, no copies are done. The pointer returned is the pointer in the variant. The variant is reset to the "null" variant.

Ownership of the pointer is transferred to the caller. When not needed anymore the memory must be freed.

Note

This macro expands to amxc_var_take_<TYPE>(var) The default variant type implementation provides these functions:

• amxc_var_take_cstring_t - returns char* this must be freed when not needed anymore use free()
• amxc_var_take_amxc_string_t - returns amxc_string_t* this must be freed when not needed anymore use amxc_string_delete
• amxc_var_take_csv_string_t - returns char* this must be freed when not needed anymore use free()
• amxc_var_take_ssv_string_t - returns char* this must be freed when not needed anymore use free()

Custom variant type implementations may implement a amxc_var_take_<CUSTOM_TYPE> function, see the documentation of the custom types for more information.

Definition at line 757 of file amxc_variant.h.

Typedef Documentation

amxc_var_t

typedef struct _amxc_var amxc_var_t

The variant struct definition.

A variant is a tagged union, which can be added to a linked list or to a hash table as value.

Which field of the union is valid is depending of the type id field in the struct.

Function Documentation

amxc_var_add_new()

amxc_var_t* amxc_var_add_new

(

amxc_var_t *const

var

)

Adds a new variant to a composite variant.

The type of the given variant must be of a composite type and must at least support the get_index and set_index functions. A new variant object is added to the composite variant. The new variant is of the null-type.

Parameters

var	pointer to a variant struct

Returns

Pointer to the new added variant or NULL when it was not possible to add a new key to the variant.

Definition at line 551 of file amxc_variant.c.

                                                    {
    amxc_var_t* data = NULL;
    amxc_var_type_t* var_type = NULL;
    int retval = -1;
    when_null(var, exit);
 
    var_type = amxc_var_get_type(var->type_id);
    when_null(var_type, exit);
 
    when_failed(amxc_var_new(&data), exit);
    retval = var_type->set_index != NULL ?
        var_type->set_index(var, data, -1, AMXC_VAR_FLAG_DEFAULT) :
        -1;
 
    if(retval != 0) {
        amxc_var_delete(&data);
    }
 
exit:
    return data;
}

amxc_var_add_new_key()

amxc_var_t* amxc_var_add_new_key	(	amxc_var_t *const	var,
		const char *	key
	)

Adds a new variant with a key to a composite variant.

The type of the given variant must be of a composite type and must at least support the get_key and set_key functions. A new variant object is added to the composite variant. The new variant is of the null-type.

Parameters

var	pointer to a variant struct to which a new variant will be added.
key	the new key that needs to be added

Returns

Pointer to the new added variant or NULL when it was not possible to add a new key to the variant.

Definition at line 526 of file amxc_variant.c.

                                                  {
    amxc_var_t* data = NULL;
    amxc_var_type_t* var_type = NULL;
    int retval = -1;
    when_null(var, exit);
    when_null(key, exit);
    when_true(*key == 0, exit);
 
    var_type = amxc_var_get_type(var->type_id);
    when_null(var_type, exit);
 
    when_failed(amxc_var_new(&data), exit);
    retval = var_type->set_key != NULL ?
        var_type->set_key(var, data, key, AMXC_VAR_FLAG_DEFAULT) :
        -1;
 
    if(retval != 0) {
        amxc_var_delete(&data);
    }
 
exit:
    return data;
}

amxc_var_cast()

int amxc_var_cast	(	amxc_var_t *const	var,
		const uint32_t	type_id
	)

Casts the variant to another variant type id.

The content of the variant is converted to the requested type. If AMXC_VAR_ID_ANY is given, automatic conversion is applied. Not all types support automatic type conversion.

If no type is found with the given type id, the conversion fails. If no conversion methods are available the conversion fails.

If type conversion fails or is not supported the variant is unchanged

Parameters

var	pointer to a variant struct
type_id	the variant type id to which the variant must be converted

Returns

When the conversion fails, this functions returns a none 0 value and the variant is not changed.

Definition at line 372 of file amxc_variant.c.

                                          {
    int retval = -1;
    amxc_var_t intermediate;
 
    amxc_var_init(&intermediate);
    when_null(var, exit);
 
    if(var->type_id == type_id) {
        retval = 0;
        goto exit;
    }
 
    retval = amxc_var_convert(&intermediate, var, type_id);
    when_failed(retval, exit);
 
    if(var->type_id != intermediate.type_id) {
        amxc_var_move(var, &intermediate);
    }
 
exit:
    amxc_var_clean(&intermediate);
    return retval;
}

amxc_var_clean()

void amxc_var_clean

(

amxc_var_t *const

var

)

Clean-up and reset variant.

If memory was allocated to contain the data for the variant, it will be freed. The variant is reset to the null variant.

Parameters

var	pointer to a variant structure.

Definition at line 237 of file amxc_variant.c.

                                           {
    amxc_var_type_t* var_type = NULL;
    when_null(var, exit);
 
    var_type = amxc_var_get_type(var->type_id);
    // ISSUE: No type available anymore, probably unregister,
    //        dangling variant !!
    if(var_type == NULL) {
        goto clean;
    }
 
    if((var_type != NULL) &&
       (var_type->del != NULL)) {
        var_type->del(var);
    }
 
clean:
    var->type_id = 0;
    var->data.data = NULL;
 
exit:
    return;
}

amxc_var_compare()

int amxc_var_compare	(	const amxc_var_t *const	var1,
		const amxc_var_t *const	var2,
		int *const	result
	)

Compares two variants.

Tries to compare the data of two variants. If it is not possible to compare the two variants, the function fails and returns a non 0 value.

The comparison result is put in result:

• when 0: var1 == var2
• when > 0: var1 > var2
• when < 0: var1 < var2

Parameters

var1	pointer to variant structure, the left value
var2	pointer to variant structure, the right value
result	pointer to integer, will contain comparison result

Returns

if it is not possible to compare the variants (depends on the types), this function returns none 0.

Definition at line 397 of file amxc_variant.c.

                                  {
    int retval = -1;
    amxc_var_type_t* var1_type = NULL;
    amxc_var_type_t* var2_type = NULL;
    amxc_var_t converted_var;
    amxc_var_init(&converted_var);
    when_null(result, exit);
 
    *result = 0;
 
    if((var1 == NULL) && (var2 == NULL)) {
        retval = 0;
        goto exit;
    }
 
    if((var1 != NULL) && (var2 == NULL)) {
        retval = 0;
        *result = 1;
        goto exit;
    }
 
    if(var1 == NULL) {
        retval = 0;
        *result = -1;
        goto exit;
    }
 
    var1_type = amxc_var_get_type(var1->type_id);
    var2_type = amxc_var_get_type(var2->type_id);
 
    when_null(var1_type, exit);
    when_null(var2_type, exit);
 
    if((var1_type->compare != NULL) &&
       ( amxc_var_convert(&converted_var,
                          var2,
                          amxc_var_type_of(var1)) == 0)) {
        retval = var1_type->compare(var1, &converted_var, result);
    } else if((var2_type->compare != NULL) &&
              ( amxc_var_convert(&converted_var,
                                 var1,
                                 amxc_var_type_of(var2)) == 0)) {
        retval = var2_type->compare(&converted_var, var2, result);
    }
 
exit:
    amxc_var_clean(&converted_var);
    return retval;
}

amxc_var_convert()

int amxc_var_convert	(	amxc_var_t *const	dest,
		const amxc_var_t *	src,
		const uint32_t	type_id
	)

Converts one variant (source) to another variant(destination) using the specified variant type id.

If no type is found with the given type id, the conversion fails. If no conversion methods are available the conversion fails.

If the source variant type has a convert to method, this is called first. If that function fails to convert, the convert from method of the destination variant type is called.

If conversion fails or is not supported the destination variant is reset to the null variant.

Parameters

dest	pointer to a variant struct, the destination
src	pointer to a variant struct, the source
type_id	the variant type id to which the source data needs to be converted to

Returns

When the conversion fails, this functions returns a none 0 value and the destination variant is reset to a null variant.

Definition at line 333 of file amxc_variant.c.

                                       {
    int retval = -1;
    amxc_var_type_t* src_type = NULL;
    amxc_var_type_t* dst_type = NULL;
    when_null(dest, exit);
    when_null(src, exit);
 
    src_type = amxc_var_get_type(src->type_id);
    when_null(src_type, exit);
 
    if(type_id != AMXC_VAR_ID_ANY) {
        dst_type = amxc_var_get_type(type_id);
        when_null(dst_type, exit);
        when_failed(amxc_var_set_type(dest, type_id), exit);
    } else {
        when_failed(amxc_var_set_type(dest, AMXC_VAR_ID_NULL), exit);
        dest->type_id = AMXC_VAR_ID_ANY;
    }
 
    // try to convert src to dst using covert_to function from src type
    retval = src_type->convert_to != NULL ?
        src_type->convert_to(dest, src) : -1;
    when_true(retval == 0, exit);
 
    if(type_id != AMXC_VAR_ID_ANY) {
        // try to convert src to dst using covert_from function from dest type
        retval = dst_type->convert_from != NULL ?
            dst_type->convert_from(dest, src) : -1;
    }
 
exit:
    if(retval != 0) {
        amxc_var_clean(dest);
    }
    return retval;
}

amxc_var_copy()

int amxc_var_copy	(	amxc_var_t *const	dest,
		const amxc_var_t *const	src
	)

Copy the type and data from one variant (source) in another variant (destination).

The destination variant is first set to the same type as the source variant using amxc_var_set_type and then the data is copied.

The content of both variants after a copy is identical. If the copy fails, the destination variant is a null variant.

The list and htable iterators are not copied.

Parameters

dest	pointer to variant struct, the destination
src	pointer to variant struct, the source

Returns

When the copy fails, this functions returns a none 0 value and the destination variant is reset to a null variant.

Definition at line 285 of file amxc_variant.c.

                                                                       {
    int retval = -1;
    amxc_var_type_t* type = NULL;
    when_null(dest, exit);
    when_null(src, exit);
 
    // reset destinationn variant
    amxc_var_clean(dest);
    // get the type function pointers of the src
    type = amxc_var_get_type(src->type_id);
    when_null(type, exit);
    when_null(type->copy, exit);
 
    when_failed(amxc_var_set_type(dest, src->type_id), exit);
    retval = type->copy(dest, src);
    if(retval != 0) {
        amxc_var_clean(dest);
    }
 
exit:
    return retval;
}

amxc_var_delete()

void amxc_var_delete

(

amxc_var_t **

var

)

Frees the previously allocated variant.

Frees the allocated memory and sets the pointer to NULL.

Note

Only call this function for variants that are allocated on the heap using amxc_var_new

Parameters

var	a pointer to the location where the pointer to the variant is stored

Definition at line 207 of file amxc_variant.c.

                                       {
    when_null(var, exit);
 
    if(*var != NULL) {
        amxc_var_clean(*var);
        amxc_llist_it_clean(&((*var)->lit), NULL);
        amxc_htable_it_clean(&((*var)->hit), NULL);
    }
 
    free(*var);
    *var = NULL;
 
exit:
    return;
}

amxc_var_get_first()

int amxc_var_t* amxc_var_get_first

(

const amxc_var_t *const

var

)

Gets the first variant in a htable or list variant.

Returns the first variant contained in composite htable or list variant.

If the provided variant pointer is not of a htable or list type, this function will return NULL.

If the provided htable or list variant is empty a NULL pointer is returned.

Parameters

var	pointer to a variant struct

Returns

The first variant in the htable or list variant or NULL.

Definition at line 712 of file amxc_variant.c.

                                                            {
    amxc_var_t* first = NULL;
 
    when_null(var, exit);
 
    switch(amxc_var_type_of(var)) {
    case AMXC_VAR_ID_HTABLE: {
        amxc_htable_it_t* it = amxc_htable_get_first(&var->data.vm);
        when_null(it, exit);
        first = amxc_var_from_htable_it(it);
    }
    break;
    case AMXC_VAR_ID_LIST: {
        amxc_llist_it_t* it = amxc_llist_get_first(&var->data.vl);
        when_null(it, exit);
        first = amxc_var_from_llist_it(it);
    }
    break;
    default:
        break;
    }
 
exit:
    return first;
}

amxc_var_get_index()

amxc_var_t* amxc_var_get_index	(	const amxc_var_t *const	var,
		const int64_t	index,
		const int	flags
	)

Get a reference to a part of composed variant using an index.

If the data contained in the variant is composed of different parts and some or all parts can be identified with an index, a reference to such part can be retrieved with this function.

Parameters

var	pointer to variant structure, containing the composed data
index	the index
flags	can be one of AMXC_VAR_FLAG_DEFAULT, AMXC_VAR_FLAG_COPY

Returns

When no part is found with the given key a null pointer is returned. The pointer returned is pointing to a real part.

Definition at line 489 of file amxc_variant.c.

                                                {
 
    amxc_var_t* retval = NULL;
    amxc_var_type_t* var_type = NULL;
    when_null(var, exit);
 
    var_type = amxc_var_get_type(var->type_id);
    when_null(var_type, exit);
 
    retval = var_type->get_index != NULL ?
        var_type->get_index(var, index, flags) : NULL;
 
exit:
    return retval;
}

amxc_var_get_key()

amxc_var_t* amxc_var_get_key	(	const amxc_var_t *const	var,
		const char *const	key,
		const int	flags
	)

Get a reference to a part of composed variant using a key.

If the data contained in the variant is composed of different parts and some or all parts can be identified with a key, a reference to such part can be retrieved with this function.

Parameters

var	pointer to variant structure, containing the composed data
key	string containing the key
flags	can be one of AMXC_VAR_FLAG_DEFAULT, AMXC_VAR_FLAG_COPY

Returns

When no part is found with the given key a null pointer is returned. The pointer returned is pointing to a real part and should not be freed unless the variant part must be removed from the composed variant.

Definition at line 449 of file amxc_variant.c.

                                              {
    amxc_var_t* retval = NULL;
    amxc_var_type_t* var_type = NULL;
    when_null(var, exit);
    when_null(key, exit);
    when_true(*key == 0, exit);
 
    var_type = amxc_var_get_type(var->type_id);
    when_null(var_type, exit);
 
    retval = var_type->get_key != NULL ?
        var_type->get_key(var, key, flags) : NULL;
 
exit:
    return retval;
}

amxc_var_get_last()

amxc_var_t* amxc_var_get_last

(

const amxc_var_t *const

var

)

Gets the last variant in a htable or list variant.

Returns the last variant contained in composite htable or list variant.

If the provided variant pointer is not of a htable or list type, this function will return NULL.

If the provided htable or list variant is empty a NULL pointer is returned.

Parameters

var	pointer to a variant struct

Returns

The first variant in the htable or list variant or NULL.

Definition at line 738 of file amxc_variant.c.

                                                           {
    amxc_var_t* last = NULL;
 
    when_null(var, exit);
 
    switch(amxc_var_type_of(var)) {
    case AMXC_VAR_ID_HTABLE: {
        amxc_htable_it_t* it = amxc_htable_get_last(&var->data.vm);
        when_null(it, exit);
        last = amxc_var_from_htable_it(it);
    }
    break;
    case AMXC_VAR_ID_LIST: {
        amxc_llist_it_t* it = amxc_llist_get_last(&var->data.vl);
        when_null(it, exit);
        last = amxc_var_from_llist_it(it);
    }
    break;
    default:
        break;
    }
 
exit:
    return last;
}

amxc_var_get_next()

amxc_var_t* amxc_var_get_next

(

const amxc_var_t *const

var

)

Gets the next variant.

If the variant is contained in a htable or list variant fetches the pointer to the next variant.

If the provided variant pointer is not in a htable or list variant, this function will return NULL.

If the provided variant is the last in the htable or list a NULL pointer is returned.

If the provided variant is in a list and in a htable, the next variant in the htable will be returned.

Parameters

var	pointer to a variant struct

Returns

The next variant in the htable or list variant or NULL

Definition at line 764 of file amxc_variant.c.

                                                           {
    amxc_var_t* next = NULL;
 
    when_null(var, exit);
 
    if(var->hit.ait != NULL) {
        amxc_htable_it_t* it = amxc_htable_it_get_next(&var->hit);
        when_null(it, exit);
        next = amxc_var_from_htable_it(it);
    } else if(var->lit.llist != NULL) {
        amxc_llist_it_t* it = amxc_llist_it_get_next(&var->lit);
        when_null(it, exit);
        next = amxc_var_from_llist_it(it);
    }
 
exit:
    return next;
}

amxc_var_get_parent()

amxc_var_t* amxc_var_get_parent

(

const amxc_var_t *const

var

)

Gets the containing variant.

If the variant is contained in a htable or list variant fetches the pointer to the container variant.

If the provided variant pointer is not in a htable or list variant, this function will return NULL.

If the provided variant is contained in a htable and in a list variant, the pointer to the containing htable variant is returned.

Parameters

var	pointer to a variant struct

Returns

The pointer to the containing variant or NULL

Definition at line 802 of file amxc_variant.c.

                                                             {
    amxc_var_t* parent = NULL;
 
    when_null(var, exit);
 
    if(var->hit.ait != NULL) {
        if(var->hit.ait->array != NULL) {
            amxc_htable_t* ptable = amxc_container_of(var->hit.ait->array, amxc_htable_t, table);
            parent = amxc_container_of(ptable, amxc_var_t, data);
        }
    } else if(var->lit.llist != NULL) {
        amxc_llist_t* plist = var->lit.llist;
        parent = amxc_container_of(plist, amxc_var_t, data);
    }
 
exit:
    return parent;
}

amxc_var_get_path()

amxc_var_t* amxc_var_get_path	(	const amxc_var_t *const	var,
		const char *const	path,
		const int	flags
	)

Retrieves the variant at the given path of a composite variant.

The type of the given variant is a composite type and some of the parts are composite variants as well, this function makes it easy to retrieve a variant deep down in the composite variant structure. The path consists of a sequence of keys and/or indexes separated by a '.'. If the path exists, the pointer to the variant at that position is returned.

When a key contains a '.' the key should be put between quotes (single or double)

Parameters

var	pointer to a variant struct, the variant type should be a composite type
path	path to a variant in the composite variant structure, a path is a sequence of indexes and/or keys separated by a '.'
flags	bitmap, see AMXC_VAR_FLAG_DEFAULT, AMXC_VAR_FLAG_COPY, AMXC_VAR_FLAG_NO_INDEX

Returns

Pointer to the variant at the given path or NULL if the path does not exist.

Definition at line 573 of file amxc_variant.c.

                                               {
    amxc_var_t* retval = NULL;
 
    retval = amxc_var_find((amxc_var_t*) var, path, flags & ~AMXC_VAR_FLAG_AUTO_ADD);
    when_null(retval, exit);
 
    if((flags & AMXC_VAR_FLAG_COPY) == AMXC_VAR_FLAG_COPY) {
        amxc_var_t* copy = NULL;
        if(amxc_var_new(&copy) != 0) {
            retval = NULL;
            goto exit;
        }
        if(amxc_var_copy(copy, retval) != 0) {
            retval = NULL;
            free(copy);
            goto exit;
        }
        retval = copy;
    }
 
exit:
    return retval;
}

amxc_var_get_pathf()

amxc_var_t* amxc_var_get_pathf	(	const amxc_var_t *const	var,
		const int	flags,
		const char *const	fmt,
			...
	)

Retrieves the variant at the given path of a composite variant.

The type of the given variant is a composite type and some of the parts are composite variants as well, this function makes it easy to retrieve a variant deep down in the composite variant structure. The path consists of a sequence of keys and/or indexes separated by a '.'. If the path exists, the pointer to the variant at that position is returned.

When a key contains a '.' the key should be put between quotes (single or double)

Parameters

var	pointer to a variant struct, the variant type should be a composite type
flags	bitmap, see AMXC_VAR_FLAG_DEFAULT, AMXC_VAR_FLAG_COPY, AMXC_VAR_FLAG_UPDATE
fmt	path to a variant in the composite variant structure, a path is a sequence of indexes and/or keys seperated by a '.'. Does support printf format.

Returns

Pointer to the variant at the given path or NULL if the path does not exist.

amxc_var_get_previous()

amxc_var_t* amxc_var_get_previous

(

const amxc_var_t *const

var

)

Gets the previous variant.

If the variant is contained in a htable or list variant fetches the pointer to the previous variant.

If the provided variant pointer is not in a htable or list variant, this function will return NULL.

If the provided variant is the first in the htable or list a NULL pointer is returned.

If the provided variant is in a list and in a htable, the previous variant in the htable will be returned.

Parameters

var	pointer to a variant struct

Returns

The previous variant in the htable or list variant or NULL

Definition at line 783 of file amxc_variant.c.

                                                               {
    amxc_var_t* prev = NULL;
 
    when_null(var, exit);
 
    if(var->hit.ait != NULL) {
        amxc_htable_it_t* it = amxc_htable_it_get_previous(&var->hit);
        when_null(it, exit);
        prev = amxc_var_from_htable_it(it);
    } else if(var->lit.llist != NULL) {
        amxc_llist_it_t* it = amxc_llist_it_get_previous(&var->lit);
        when_null(it, exit);
        prev = amxc_var_from_llist_it(it);
    }
 
exit:
    return prev;
}

amxc_var_init()

int amxc_var_init

(

amxc_var_t *const

var

)

Initializes a variant.

Call this to initialize variants structures (amxc_var_t) allocated on the stack.

When the variant is not needed anymore call amxc_var_clean to make sure that all allocated memory to store the data is freed. Failing to do so could lead to a memory leak.

The variant will be initialized as a null variant. To change the variant type use amxc_var_set_type.

Do not re-initialize an already initialized or used variant. The data contained in the variant is lost, no memory is freed if needed. To reset the variant back to a null variant use amxc_var_clean.

Parameters

var	pointer to a variant structure.

Returns

When initialization is successful, this functions returns 0.

Definition at line 223 of file amxc_variant.c.

                                         {
    int retval = -1;
    when_null(var, exit);
 
    var->type_id = 0;
    var->data.data = NULL;
    when_failed(amxc_llist_it_init(&var->lit), exit);
    when_failed(amxc_htable_it_init(&var->hit), exit);
    retval = 0;
 
exit:
    return retval;
}

amxc_var_is_null()

AMXC_INLINE bool amxc_var_is_null

(

const amxc_var_t *const

var

)

Checks if the given variant is of the "null" type.

Parameters

var	pointer to a variant struct

Returns

true when variant pointer is NULL or the variant is of the "null" type.

Definition at line 1594 of file amxc_variant.h.

                                                   {
    return var == NULL ? true : (var->type_id == AMXC_VAR_ID_NULL);
}

amxc_var_key()

const char* amxc_var_key

(

const amxc_var_t *const

var

)

Gets the key, with which the variant is stored in a htable variant.

If the variant is contained in a htable variant fetches the key with which the variant is stored in the htable

If the provided variant pointer is not in a htable, this function will return NULL.

Parameters

var	pointer to a variant struct

Returns

The key or NULL

Definition at line 821 of file amxc_variant.c.

                                                      {
    const char* key = NULL;
 
    when_null(var, exit);
 
    if(var->hit.ait != NULL) {
        key = amxc_htable_it_get_key(&var->hit);
    }
 
exit:
    return key;
}

amxc_var_move()

int amxc_var_move	(	amxc_var_t *const	dest,
		amxc_var_t *const	src
	)

Moves the type and data from one variant (source) in another variant (destination).

The destination variant is first set to the same type as the source variant using amxc_var_set_type and then the data is moved.

After the move the destination variant is identical to the source variant and the source variant is reset to the null variant type.

The iterators (linked list and htable) of the source variant are not moved.

Parameters

dest	pointer to variant struct, the destination
src	pointer to variant struct, the source

Returns

When the move fails, this functions returns a none 0 value and the destination variant is reset to a null variant.

Definition at line 308 of file amxc_variant.c.

                                                                 {
    int retval = -1;
    amxc_var_type_t* type = NULL;
    when_null(dest, exit);
    when_null(src, exit);
 
    // reset destinationn variant
    amxc_var_clean(dest);
    // get the type function pointers of the src
    type = amxc_var_get_type(src->type_id);
    when_null(type, exit);
    when_null(type->move, exit);
 
    when_failed(amxc_var_set_type(dest, src->type_id), exit);
    retval = type->move(dest, src);
    if(retval != 0) {
        amxc_var_clean(dest);
    } else {
        amxc_var_clean(src);
    }
 
exit:
    return retval;
}

amxc_var_new()

int amxc_var_new

(

amxc_var_t **

var

)

Allocates a variant and initializes it to the null variant type.

A variant is a container that can hold any type.

Note

The allocated memory must be freed when not used anymore, use amxc_var_delete to free the memory

Parameters

var	pointer to a pointer that points to the new allocated variant

Returns

When allocation is successfull, this functions returns 0.

Definition at line 194 of file amxc_variant.c.

                                   {
    int retval = -1;
    when_null(var, exit);
 
    *var = (amxc_var_t*) calloc(1, sizeof(amxc_var_t));
    when_null(*var, exit);
 
    retval = amxc_var_init(*var);
 
exit:
    return retval;
}

amxc_var_set_index()

int amxc_var_set_index	(	amxc_var_t *const	var,
		const int64_t	index,
		amxc_var_t *	data,
		const int	flags
	)

Set a part of composed variant using an index.

If the data contained in the variant is composed of different parts and some or all parts can be identified with an index, the data of such a part can be changed with this function.

As a convention, when using as the index -1, the data is added to the end.

Example: if the variant is containing a list of variants, adding a new data variant using index -1, will add it to the end of the list.

Parameters

var	pointer to variant structure, containing the composed data
index	the index
data	a variant containing the data the will be set
flags	bitmap, see AMXC_VAR_FLAG_DEFAULT, AMXC_VAR_FLAG_COPY, AMXC_VAR_FLAG_UPDATE

Returns

When the data has been set this function returns 0, when failed, the function returns a non-zero value.

Definition at line 507 of file amxc_variant.c.

                                        {
    int retval = -1;
    amxc_var_type_t* var_type = NULL;
    when_null(var, exit);
    when_null(data, exit);
 
    var_type = amxc_var_get_type(var->type_id);
    when_null(var_type, exit);
 
    retval = var_type->set_index != NULL ?
        var_type->set_index(var, data, index, flags) : -1;
 
exit:
    return retval;
}

amxc_var_set_key()

int amxc_var_set_key	(	amxc_var_t *const	var,
		const char *const	key,
		amxc_var_t *	data,
		const int	flags
	)

Sets a part of composed variant using a key.

If the data contained in the variant is composed of different parts and some or all parts can be identified with a key, the data of such a part can be changed with this function.

The default behaviour is not to copy anything, just store the given variant. Using AMXC_VAR_FLAG_COPY this behavior can be changed into copy the variant and the variant data.

Note

The behaviour depends on the variant type of the destination variant (var parameter). Please read the documentation of the destination variant type.

Parameters

var	pointer to variant structure, containing the composed data
key	string containing the key
data	a variant containing the data the will be set
flags	bitmap, see AMXC_VAR_FLAG_DEFAULT, AMXC_VAR_FLAG_COPY, AMXC_VAR_FLAG_UPDATE

Returns

When the data has been set this function returns 0, when failed, the function returns a non-zero value.

Definition at line 468 of file amxc_variant.c.

                                      {
    int retval = -1;
    amxc_var_type_t* var_type = NULL;
    when_null(var, exit);
    when_null(key, exit);
    when_true(*key == 0, exit);
    when_null(data, exit);
 
    var_type = amxc_var_get_type(var->type_id);
    when_null(var_type, exit);
 
    retval = var_type->set_key != NULL ?
        var_type->set_key(var, data, key, flags) : -1;
 
exit:
    return retval;
}

amxc_var_set_path()

amxc_var_t int amxc_var_set_path	(	amxc_var_t *const	var,
		const char *const	path,
		amxc_var_t *	data,
		const int	flags
	)

Sets the variant at the given path of a composite variant.

The type of the given variant is a composite type and some of the parts are composite variants as well, this function makes it easy to set a variant deep down in the composite variant structure. The path consists of a sequence of keys and/or indexes separated by a '.'.

If the path exists, the value of the variant at that position is changed.

If the path doesn't exist and the flag AMXC_VAR_FLAG_AUTO_ADD is set the variants on that path are added.

When a key contains a '.' the key should be put between quotes (single or double)

Parameters

var	pointer to a variant struct, the variant type should be a composite type
path	path to a variant in the composite variant structure, a path is a sequence of indexes and/or keys separated by a '.'
data	the new value
flags	bitmap, see AMXC_VAR_FLAG_DEFAULT, AMXC_VAR_FLAG_COPY, AMXC_VAR_FLAG_NO_INDEX, AMXC_VAR_FLAG_AUTO_ADD

Returns

0 when the value was set, any other value indicates an error.

Definition at line 623 of file amxc_variant.c.

                                       {
    amxc_var_t* variant = NULL;
    int retval = -1;
 
    variant = amxc_var_find(var, path, flags);
    when_null(variant, exit);
 
    if((flags & AMXC_VAR_FLAG_COPY) == AMXC_VAR_FLAG_COPY) {
        retval = amxc_var_copy(variant, data);
    } else {
        retval = amxc_var_move(variant, data);
    }
 
exit:
    return retval;
}

amxc_var_set_pathf()

int amxc_var_set_pathf	(	amxc_var_t *const	var,
		amxc_var_t *	data,
		const int	flags,
		const char *const	fmt,
			...
	)

Sets the variant at the given path of a composite variant.

The type of the given variant is a composite type and some of the parts are composite variants as well, this function makes it easy to set a variant deep down in the composite variant structure. The path consists of a sequence of keys and/or indexes separated by a '.'.

If the path exists, the value of the variant at that position is changed.

If the path doesn't exist and the flag AMXC_VAR_FLAG_AUTO_ADD is set the variants on that path are added.

When a key contains a '.' the key should be put between quotes (single or double)

Parameters

var	pointer to a variant struct, the variant type should be a composite type
data	the new value
flags	bitmap, see AMXC_VAR_FLAG_DEFAULT, AMXC_VAR_FLAG_COPY, AMXC_VAR_FLAG_NO_INDEX, AMXC_VAR_FLAG_AUTO_ADD
fmt	path to a variant in the composite variant structure, a path is a sequence of indexes and/or keys separated by a '.'. Does support printf format.

Returns

0 when the value was set, any other value indicates an error.

amxc_var_set_type()

int amxc_var_set_type	(	amxc_var_t *const	var,
		const uint32_t	type
	)

Change the variant data type.

If the variant was already containing data, this will be cleaned up. The type is changed and the data part reset to default value. (0, NULL, false, ...)

Parameters

var	pointer to variant struct
type	the variant type id

Returns

When the type is set, this functions returns 0, any other value in case of failure.

Definition at line 261 of file amxc_variant.c.

                                                                  {
    int retval = -1;
    amxc_var_type_t* var_type = NULL;
    when_null(var, exit);
 
    var_type = amxc_var_get_type(type);
    when_null(var_type, exit);
 
    // first clean the variant
    // this to make sure all allocated memory for the content of the variant
    // is freed
    amxc_var_clean(var);
 
    var->type_id = type;
    if(var_type->init != NULL) {
        retval = var_type->init(var);
    } else {
        retval = 0;
    }
 
exit:
    return retval;
}

amxc_var_take_index()

AMXC_INLINE amxc_var_t* amxc_var_take_index	(	amxc_var_t *const	var,
		const int64_t	index
	)

Get a reference to a part of composed variant using an index and removes it from the composed variant.

If the data contained in the variant is composed of different parts and some or all parts can be identified with an index, a reference to such part can be retrieved with this function.

The variant referenced by the index is removed from the composed variant.

The returned variant must be freed using amxc_var_delete

Parameters

var	pointer to variant structure, containing the composed data
index	the index

Returns

When no part is found with the given index a null pointer is returned. The pointer returned is pointing to a real part.

Definition at line 1268 of file amxc_variant.h.

                                                     {
    amxc_var_t* rv = amxc_var_get_index(var, index, AMXC_VAR_FLAG_DEFAULT);
    amxc_var_take_it(rv);
    return rv;
}

amxc_var_take_it()

AMXC_INLINE void amxc_var_take_it

(

amxc_var_t *const

var

)

Removes the variant for a llist and/or a htable.

When the variant is stored in a linked list and/or a hash table, it is removed from these. The variant itself is not deleted.

Parameters

var	pointer to a variant struct

Definition at line 1107 of file amxc_variant.h.

                                             {
    if(var != NULL) {
        amxc_llist_it_take(&var->lit);
        amxc_htable_it_take(&var->hit);
    }
}

amxc_var_take_key()

AMXC_INLINE amxc_var_t* amxc_var_take_key	(	amxc_var_t *const	var,
		const char *const	key
	)

Get a reference to a part of composed variant using a key and removes it from the composed variant.

If the data contained in the variant is composed of different parts and some or all parts can be identified with a key, a reference to such part can be retrieved with this function.

The variant referenced by the key is removed from the composed variant.

The returned variant must be freed using amxc_var_delete

Parameters

var	pointer to variant structure, containing the composed data
key	string containing the key

Returns

When no part is found with the given key a null pointer is returned. The pointer returned is pointing to a real part.

Definition at line 1189 of file amxc_variant.h.

                                                     {
    amxc_var_t* rv = amxc_var_get_key(var, key, AMXC_VAR_FLAG_DEFAULT);
    amxc_var_take_it(rv);
    return rv;
}

amxc_var_type_name_of()

const char* amxc_var_type_name_of

(

const amxc_var_t *const

var

)

Gets the variant type name of a variant.

Parameters

var	pointer to a variant struct

Returns

A constant string containing the name of the variant type. Or a null pointer when the type does not exists or it is an invalid variant.

Definition at line 672 of file amxc_variant.c.

                                                               {
    return var != NULL ? amxc_var_get_type_name_from_id(var->type_id) : NULL;
}

amxc_var_type_of()

uint32_t amxc_var_type_of

(

const amxc_var_t *const

var

)

Gets the variant type id of a variant.

Parameters

var	pointer to a variant struct

Returns

The variant type id, or -1 if the type does not exists or if it is an invalid variant.

Definition at line 668 of file amxc_variant.c.

                                                       {
    return var != NULL ? var->type_id : AMXC_VAR_ID_INVALID;
}