CtplValue

CtplValue — Generic values

Synopsis

#include <ctpl/ctpl.h>

enum                CtplValueType;
                    CtplValue;
#define             CTPL_VALUE_HOLDS                    (value,
                                                         vtype)
#define             CTPL_VALUE_HOLDS_INT                (value)
#define             CTPL_VALUE_HOLDS_FLOAT              (value)
#define             CTPL_VALUE_HOLDS_STRING             (value)
#define             CTPL_VALUE_HOLDS_ARRAY              (value)
void                ctpl_value_init                     (CtplValue *value);
CtplValue *         ctpl_value_new                      (void);
void                ctpl_value_copy                     (const CtplValue *src_value,
                                                         CtplValue *dst_value);
CtplValue *         ctpl_value_dup                      (const CtplValue *value);
void                ctpl_value_free_value               (CtplValue *value);
void                ctpl_value_free                     (CtplValue *value);
CtplValue *         ctpl_value_new_int                  (glong val);
CtplValue *         ctpl_value_new_float                (gdouble val);
CtplValue *         ctpl_value_new_string               (const gchar *val);
CtplValue *         ctpl_value_new_arrayv               (CtplValueType type,
                                                         gsize count,
                                                         va_list ap);
CtplValue *         ctpl_value_new_array                (CtplValueType type,
                                                         gsize count,
                                                         ...);
void                ctpl_value_set_int                  (CtplValue *value,
                                                         glong val);
void                ctpl_value_set_float                (CtplValue *value,
                                                         gdouble val);
void                ctpl_value_set_string               (CtplValue *value,
                                                         const gchar *val);
void                ctpl_value_set_arrayv               (CtplValue *value,
                                                         CtplValueType type,
                                                         gsize count,
                                                         va_list ap);
void                ctpl_value_set_array                (CtplValue *value,
                                                         CtplValueType type,
                                                         gsize count,
                                                         ...);
void                ctpl_value_set_array_intv           (CtplValue *value,
                                                         gsize count,
                                                         va_list ap);
void                ctpl_value_set_array_int            (CtplValue *value,
                                                         gsize count,
                                                         ...);
void                ctpl_value_set_array_floatv         (CtplValue *value,
                                                         gsize count,
                                                         va_list ap);
void                ctpl_value_set_array_float          (CtplValue *value,
                                                         gsize count,
                                                         ...);
void                ctpl_value_set_array_stringv        (CtplValue *value,
                                                         gsize count,
                                                         va_list ap);
void                ctpl_value_set_array_string         (CtplValue *value,
                                                         gsize count,
                                                         ...);
void                ctpl_value_array_append             (CtplValue *value,
                                                         const CtplValue *val);
void                ctpl_value_array_prepend            (CtplValue *value,
                                                         const CtplValue *val);
void                ctpl_value_array_append_int         (CtplValue *value,
                                                         glong val);
void                ctpl_value_array_prepend_int        (CtplValue *value,
                                                         glong val);
void                ctpl_value_array_append_float       (CtplValue *value,
                                                         gdouble val);
void                ctpl_value_array_prepend_float      (CtplValue *value,
                                                         gdouble val);
void                ctpl_value_array_append_string      (CtplValue *value,
                                                         const gchar *val);
void                ctpl_value_array_prepend_string     (CtplValue *value,
                                                         const gchar *val);
gsize               ctpl_value_array_length             (const CtplValue *value);
CtplValue *         ctpl_value_array_index              (const CtplValue *value,
                                                         gsize idx);
CtplValueType       ctpl_value_get_held_type            (const CtplValue *value);
glong               ctpl_value_get_int                  (const CtplValue *value);
gdouble             ctpl_value_get_float                (const CtplValue *value);
const gchar *       ctpl_value_get_string               (const CtplValue *value);
const GSList *      ctpl_value_get_array                (const CtplValue *value);
glong *             ctpl_value_get_array_int            (const CtplValue *value,
                                                         gsize *length);
gdouble *           ctpl_value_get_array_float          (const CtplValue *value,
                                                         gsize *length);
gchar **            ctpl_value_get_array_string         (const CtplValue *value,
                                                         gsize *length);
gchar *             ctpl_value_to_string                (const CtplValue *value);
gboolean            ctpl_value_convert                  (CtplValue *value,
                                                         CtplValueType vtype);
const gchar *       ctpl_value_type_get_name            (CtplValueType type);
#define             ctpl_value_get_held_type_name       (v)

Description

A generic value manager.

Dynamically allocated CtplValue are created with ctpl_value_new() and freed with ctpl_value_free(). Statically allocated ones are initialized with ctpl_value_init() and uninitialized with ctpl_value_free_value().

You can set the data they holds with ctpl_value_set_int(), ctpl_value_set_float(), ctpl_value_set_string() and ctpl_value_set_array(); you can add elements to an array value with ctpl_value_array_append(), ctpl_value_array_prepend(), ctpl_value_array_append_int(), ctpl_value_array_prepend_int(), ctpl_value_array_append_float(), ctpl_value_array_prepend_float(), ctpl_value_array_append_string() and ctpl_value_array_prepend_string().

To get the value held by a CtplValue, use ctpl_value_get_int(), ctpl_value_get_float(), ctpl_value_get_string(), ctpl_value_get_array_int(), ctpl_value_get_array_float() or ctpl_value_get_array_string() depending on the type of the value. For array value, yo can also use ctpl_value_get_array() to get the list of the different values in that array. You can get the type held by a value with ctpl_value_get_held_type().

Value may be converted to other types with ctpl_value_convert(), and to a string representation using ctpl_value_to_string().

Example 8. Simple usage of dynamically allocated generic values

1
2
3
4
5
6
7
CtplValue *val;

val = ctpl_value_new ();
ctpl_value_set_int (val, 42);

/* Free all data allocated for the value and the held data */
ctpl_value_free (val);


Example 9. Simple usage of statically allocated generic values

1
2
3
4
5
6
7
8
CtplValue val;

ctpl_value_init (&val);
ctpl_value_set_int (&val, 42);

/* Free all memory that might have been allocated for the held
 * data */
ctpl_value_free_value (&val);


Details

enum CtplValueType

typedef enum _CtplValueType
{
  CTPL_VTYPE_INT,
  CTPL_VTYPE_FLOAT,
  CTPL_VTYPE_STRING,
  CTPL_VTYPE_ARRAY
} CtplValueType;

Represents the types that a CtplValue can hold.

CTPL_VTYPE_INT

Integer (C's long int)

CTPL_VTYPE_FLOAT

Floating point value (C's double)

CTPL_VTYPE_STRING

0-terminated string (C string)

CTPL_VTYPE_ARRAY

Array of CtplValues

CtplValue

typedef struct {
} CtplValue;

Represents a generic value.


CTPL_VALUE_HOLDS()

#define             CTPL_VALUE_HOLDS(value, vtype)

Checks whether a CtplValue holds a value of the given type.

value :

A CtplValue

vtype :

A CtplValueType

Returns :

TRUE if value holds a value of vtype, FALSE otherwise.

CTPL_VALUE_HOLDS_INT()

#define             CTPL_VALUE_HOLDS_INT(value)

Check whether a CtplValue holds an integer value.

value :

A CtplValue

Returns :

TRUE if value holds an integer, FALSE otherwise.

CTPL_VALUE_HOLDS_FLOAT()

#define             CTPL_VALUE_HOLDS_FLOAT(value)

Check whether a CtplValue holds a floating point value.

value :

A CtplValue

Returns :

TRUE if value holds a float, FALSE otherwise.

CTPL_VALUE_HOLDS_STRING()

#define             CTPL_VALUE_HOLDS_STRING(value)

Check whether a CtplValue holds a string.

value :

A CtplValue

Returns :

TRUE if value holds a string, FALSE otherwise.

CTPL_VALUE_HOLDS_ARRAY()

#define             CTPL_VALUE_HOLDS_ARRAY(value)

Check whether a CtplValue holds an array of values.

value :

A CtplValue

Returns :

TRUE if value holds an array, FALSE otherwise.

ctpl_value_init ()

void                ctpl_value_init                     (CtplValue *value);

Initializes a CtplValue. This function is useful for statically allocated values, and is not required for dynamically allocated values created by ctpl_value_new().

value :

An uninitialized CtplValue

ctpl_value_new ()

CtplValue *         ctpl_value_new                      (void);

Creates a new empty CtplValue.

Returns :

A newly allocated CtplValue that should be freed using ctpl_value_free()

ctpl_value_copy ()

void                ctpl_value_copy                     (const CtplValue *src_value,
                                                         CtplValue *dst_value);

Copies the value of a CtplValue into another. See ctpl_value_dup() if you want to duplicate the value and not only its content.

src_value :

A CtplValue to copy

dst_value :

A CtplValue into which copy src_value

ctpl_value_dup ()

CtplValue *         ctpl_value_dup                      (const CtplValue *value);

Duplicates a CtplValue. This function simply creates a new CtplValue with ctpl_value_new() then copies value into it using ctpl_value_copy().

value :

A CtplValue to copy

Returns :

A newly allocated CtplValue

ctpl_value_free_value ()

void                ctpl_value_free_value               (CtplValue *value);

Frees the data held by a CtplValue. This function is only useful to the end user for statically allocated values since ctpl_value_free() does all the job needed to completely release an allocated CtplValue.

value :

A CtplValue

ctpl_value_free ()

void                ctpl_value_free                     (CtplValue *value);

Frees all resources used by a CtplValue. This function can't be used with statically allocated values since it also frees the value itself and not only its content. If you want to free a statically allocated value, use ctpl_value_free_value().

value :

A CtplValue

ctpl_value_new_int ()

CtplValue *         ctpl_value_new_int                  (glong val);

Creates a new CtplValue and sets its value to val. See ctpl_value_new() and ctpl_value_set_int().

val :

An integer

Returns :

A newly allocated CtplValue holding val.

ctpl_value_new_float ()

CtplValue *         ctpl_value_new_float                (gdouble val);

Creates a new CtplValue and sets its value to val. See ctpl_value_new() and ctpl_value_set_float().

val :

A float

Returns :

A newly allocated CtplValue holding val.

ctpl_value_new_string ()

CtplValue *         ctpl_value_new_string               (const gchar *val);

Creates a new CtplValue and sets its value to val. See ctpl_value_new() and ctpl_value_set_string().

val :

A string

Returns :

A newly allocated CtplValue holding val.

ctpl_value_new_arrayv ()

CtplValue *         ctpl_value_new_arrayv               (CtplValueType type,
                                                         gsize count,
                                                         va_list ap);

Creates a new CtplValue and sets its values to the given ones. See ctpl_value_new() and ctpl_value_set_arrayv().

Warning

As this function takes a variadic argument, there is no control on the values neither on their type nor on any other of their properties. Then, you have to take care to pass strictly right data to it if you won't see your program crash -- in the better case.

type :

The type of the array's elements

count :

The number of elements

ap :

A va_list containing the values of the type specified by type, ended by a NULL value

Returns :

A newly allocated CtplValue holding given values.

ctpl_value_new_array ()

CtplValue *         ctpl_value_new_array                (CtplValueType type,
                                                         gsize count,
                                                         ...);

Creates a new CtplValue and sets its values to the given ones. See ctpl_value_new_arrayv().

Warning

As this function takes a variadic argument, there is no control on the values neither on their type nor on any other of their properties. Then, you have to take care to pass strictly right data to it if you won't see your program crash -- in the better case.

type :

The type of the array's elements

count :

The number of elements

... :

A NULL-ended list of elements of the type specified by type

Returns :

A newly allocated CtplValue holding given values.

ctpl_value_set_int ()

void                ctpl_value_set_int                  (CtplValue *value,
                                                         glong val);

Sets the value of a CtplValue to the given integer.

value :

A CtplValue

val :

An integer

ctpl_value_set_float ()

void                ctpl_value_set_float                (CtplValue *value,
                                                         gdouble val);

Sets the value of a CtplValue to the given float.

value :

A CtplValue

val :

A float

ctpl_value_set_string ()

void                ctpl_value_set_string               (CtplValue *value,
                                                         const gchar *val);

Sets the value of a CtplValue to the given string. The string is copied.

value :

A CtplValue

val :

A string

ctpl_value_set_arrayv ()

void                ctpl_value_set_arrayv               (CtplValue *value,
                                                         CtplValueType type,
                                                         gsize count,
                                                         va_list ap);

Sets the value of a CtplValue from the given list of elements. See ctpl_value_array_append(), ctpl_value_array_append_int(), ctpl_value_array_append_float() and ctpl_value_array_append_string().

Warning

As this function takes a variadic argument, there is no control on the values neither on their type nor on any other of their properties. Then, you have to take care to pass strictly right data to it if you won't see your program crash -- in the better case.

value :

A CtplValue

type :

The type of the given elements

count :

The number of elements

ap :

A NULL-ended va_list of the elements

ctpl_value_set_array ()

void                ctpl_value_set_array                (CtplValue *value,
                                                         CtplValueType type,
                                                         gsize count,
                                                         ...);

Sets the value of a CtplValue from the given elements. See ctpl_value_set_arrayv().

Warning

As this function takes a variadic argument, there is no control on the values neither on their type nor on any other of their properties. Then, you have to take care to pass strictly right data to it if you won't see your program crash -- in the better case.

value :

A CtplValue

type :

The type of the given elements

count :

The number of elements

... :

A NULL-ended list of elements

ctpl_value_set_array_intv ()

void                ctpl_value_set_array_intv           (CtplValue *value,
                                                         gsize count,
                                                         va_list ap);

Sets the value of a CtplValue from the given integers. This is a convenience wrapper around ctpl_value_set_arrayv(), and the same care have to been taken about.

value :

A CtplValue

count :

The number of given elements

ap :

A NULL-ended va_list of integers

ctpl_value_set_array_int ()

void                ctpl_value_set_array_int            (CtplValue *value,
                                                         gsize count,
                                                         ...);

Sets the value of a CtplValue from the given integers. This is a convenience wrapper around ctpl_value_set_array(), and the same care have to been taken about.

value :

A CtplValue

count :

The number of given elements

... :

A NULL-ended list of integers

ctpl_value_set_array_floatv ()

void                ctpl_value_set_array_floatv         (CtplValue *value,
                                                         gsize count,
                                                         va_list ap);

Sets the value of a CtplValue from the given floats. This is a convenience wrapper around ctpl_value_set_arrayv(), and the same care have to been taken about.

value :

A CtplValue

count :

The number of given elements

ap :

A NULL-ended va_list of floats

ctpl_value_set_array_float ()

void                ctpl_value_set_array_float          (CtplValue *value,
                                                         gsize count,
                                                         ...);

Sets the value of a CtplValue from the given floats. This is a convenience wrapper around ctpl_value_set_array(), and the same care have to been taken about.

value :

A CtplValue

count :

The number of given elements

... :

A NULL-ended list of floats

ctpl_value_set_array_stringv ()

void                ctpl_value_set_array_stringv        (CtplValue *value,
                                                         gsize count,
                                                         va_list ap);

Sets the value of a CtplValue from the given strings. This is a convenience wrapper around ctpl_value_set_arrayv(), and the same care have to been taken about.

value :

A CtplValue

count :

The number of given elements

ap :

A NULL-ended va_list of strings (as const char*)

ctpl_value_set_array_string ()

void                ctpl_value_set_array_string         (CtplValue *value,
                                                         gsize count,
                                                         ...);

Sets the value of a CtplValue from the given strings. This is a convenience wrapper around ctpl_value_set_array(), and the same care have to been taken about.

value :

A CtplValue

count :

The number of given elements

... :

A NULL-ended list of strings (as const char*)

ctpl_value_array_append ()

void                ctpl_value_array_append             (CtplValue *value,
                                                         const CtplValue *val);

Appends a CtplValue to another CtplValue holding an array. The appended value is copied.

value :

A CtplValue holding an array

val :

A CtplValue to append

ctpl_value_array_prepend ()

void                ctpl_value_array_prepend            (CtplValue *value,
                                                         const CtplValue *val);

Prepends a CtplValue to another CtplValue holding an array. The prepended value is copied.

value :

A CtplValue holding an array

val :

A CtplValue to prepend

ctpl_value_array_append_int ()

void                ctpl_value_array_append_int         (CtplValue *value,
                                                         glong val);

Appends an integer to a CtplValue holding an array.

value :

A CtplValue holding an array

val :

An integer to append

ctpl_value_array_prepend_int ()

void                ctpl_value_array_prepend_int        (CtplValue *value,
                                                         glong val);

Prepends an integer to a CtplValue holding an array.

value :

A CtplValue holding an array

val :

An integer to prepend

ctpl_value_array_append_float ()

void                ctpl_value_array_append_float       (CtplValue *value,
                                                         gdouble val);

Appends a float to a CtplValue holding an array.

value :

A CtplValue holding an array

val :

A float to append

ctpl_value_array_prepend_float ()

void                ctpl_value_array_prepend_float      (CtplValue *value,
                                                         gdouble val);

Prepends a float to a CtplValue holding an array.

value :

A CtplValue holding an array

val :

A float to prepend

ctpl_value_array_append_string ()

void                ctpl_value_array_append_string      (CtplValue *value,
                                                         const gchar *val);

Appends a string to a CtplValue holding an array. The string is copied.

value :

A CtplValue holding an array

val :

A string to append

ctpl_value_array_prepend_string ()

void                ctpl_value_array_prepend_string     (CtplValue *value,
                                                         const gchar *val);

Prepends a string to a CtplValue holding an array. The string is copied.

value :

A CtplValue holding an array

val :

A string to prepend

ctpl_value_array_length ()

gsize               ctpl_value_array_length             (const CtplValue *value);

Gets the number of elements in a CtplValue that holds an array.

value :

A CtplValue holding an array

Returns :

The number of elements in value.

ctpl_value_array_index ()

CtplValue *         ctpl_value_array_index              (const CtplValue *value,
                                                         gsize idx);

Index an array, getting its idx-th element.

value :

A CtplValue holding an array

idx :

The array's index to get

Returns :

The idx-th element of value, or NULL if idx is out of bounds.

ctpl_value_get_held_type ()

CtplValueType       ctpl_value_get_held_type            (const CtplValue *value);

Gets the type held by the a CtplValue.

value :

A CtplValue

Returns :

The type held by the value.

ctpl_value_get_int ()

glong               ctpl_value_get_int                  (const CtplValue *value);

Gets the value of a CtplValue holding a integer.

value :

A CtplValue holding a int

Returns :

The integer value held by value.

ctpl_value_get_float ()

gdouble             ctpl_value_get_float                (const CtplValue *value);

Gets the value of a CtplValue holding a float.

value :

A CtplValue holding a float

Returns :

The float value held by value.

ctpl_value_get_string ()

const gchar *       ctpl_value_get_string               (const CtplValue *value);

Gets the value of a CtplValue holding a string.

value :

A CtplValue holding a string

Returns :

A string owned by the value that should not be modified or freed, or NULL if an error occurs.

ctpl_value_get_array ()

const GSList *      ctpl_value_get_array                (const CtplValue *value);

Gets the values of a CtplValue holding an array as a GSList in which each element holds a CtplValue holding the element value.

value :

A CtplValue holding an array

Returns :

A GSList owned by the value that must not be freed, neither the list itself nor its values, or NULL on error. [element-type Ctpl.Value][transfer none Ctpl.Value]

ctpl_value_get_array_int ()

glong *             ctpl_value_get_array_int            (const CtplValue *value,
                                                         gsize *length);

Gets the values of a CtplValue as an array of int. The value must hold an array and all array's elements must be integers.

value :

A CtplValue holding an array of integers

length :

Return location for the array length, or NULL. [out][allow-none]

Returns :

A newly allocated array of integers that should be freed with g_free() or NULL on error. [array length=length][transfer full length=length]

ctpl_value_get_array_float ()

gdouble *           ctpl_value_get_array_float          (const CtplValue *value,
                                                         gsize *length);

Gets the values of a CtplValue as an array of floats. value must hold an array and all array's elements must be floats.

value :

A CtplValue holding an array of floats

length :

Return location for the array length, or NULL. [out][allow-none]

Returns :

A newly allocated array of floats that should be freed with g_free() or NULL on error. [array length=length][transfer full length=length]

ctpl_value_get_array_string ()

gchar **            ctpl_value_get_array_string         (const CtplValue *value,
                                                         gsize *length);

Gets the values held by a CtplValue as an array of strings. value must hold an array containing only strings.

value :

A CtplValue holding an array of strings

length :

Return location for the length of the returned array, or NULL. [out][allow-none]

Returns :

A newly allocated NULL-terminated array of strings, or NULL on error. Free with g_strfreev() when no longer needed. [array length=length][transfer full length=length]

ctpl_value_to_string ()

gchar *             ctpl_value_to_string                (const CtplValue *value);

Converts a CtplValue to a string.

Note

Arrays are flattened to the form [val1, val2, val3]. It may not be what you want, but flattening an array is not the primary goal of this function and you should consider doing it yourself if it is what you want - flattening an array.

value :

A CtplValue

Returns :

A newly allocated string representing the value. You should free this value with g_free() when no longer needed.

ctpl_value_convert ()

gboolean            ctpl_value_convert                  (CtplValue *value,
                                                         CtplValueType vtype);

Tries to convert a CtplValue to another type.

The performed conversion might be called "non-destructive": the value will not loose precision, but the conversion will rather fail if it would lead to a loss. An good example is converting a floating-point value to an integer one: the conversion will only happen if it would not truncate the floating part.

Warning

The current implementation of floating-point value comparison might be lossy, and then the above example might be somewhat wrong in practice.

Note

Converting to a string uses ctpl_value_to_string(). Even if it will never fail, the result might not be the one you expect when converting an array.

value :

A CtplValue to convert

vtype :

The type to which convert value

Returns :

TRUE if the conversion succeeded, FALSE otherwise.

ctpl_value_type_get_name ()

const gchar *       ctpl_value_type_get_name            (CtplValueType type);

Gets a human-readable name for a value type.

type :

A CtplValueType

Returns :

A static string of a displayable name for type. This string must not be modified or freed.

ctpl_value_get_held_type_name()

#define             ctpl_value_get_held_type_name(v)

Gets a human-readable name for the type held by a value. See also ctpl_value_type_get_name().

v :

A CtplValue pointer

Returns :

A static string of a displayable name of the type held by v. This string must not be modified or freed.