CTPL Reference Manual: CtplValue

## CtplValue CtplValue — Generic values |

## Functions

#define | CTPL_VALUE_HOLDS()
#define | CTPL_VALUE_HOLDS_INT()
#define | CTPL_VALUE_HOLDS_FLOAT()
#define | CTPL_VALUE_HOLDS_STRING()
#define | CTPL_VALUE_HOLDS_ARRAY()
void | ctpl_value_init ()
CtplValue * | ctpl_value_new ()
void | ctpl_value_copy ()
CtplValue * | ctpl_value_dup ()
void | ctpl_value_free_value ()
void | ctpl_value_free ()
CtplValue * | ctpl_value_new_int ()
CtplValue * | ctpl_value_new_float ()
CtplValue * | ctpl_value_new_string ()
CtplValue * | ctpl_value_new_arrayv ()
CtplValue * | ctpl_value_new_array ()
void | ctpl_value_set_int ()
void | ctpl_value_set_float ()
void | ctpl_value_set_string ()
void | ctpl_value_set_arrayv ()
void | ctpl_value_set_array ()
void | ctpl_value_set_array_intv ()
void | ctpl_value_set_array_int ()
void | ctpl_value_set_array_floatv ()
void | ctpl_value_set_array_float ()
void | ctpl_value_set_array_stringv ()
void | ctpl_value_set_array_string ()
void | ctpl_value_array_append ()
void | ctpl_value_array_prepend ()
void | ctpl_value_array_append_int ()
void | ctpl_value_array_prepend_int ()
void | ctpl_value_array_append_float ()
void | ctpl_value_array_prepend_float ()
void | ctpl_value_array_append_string ()
void | ctpl_value_array_prepend_string ()
gsize | ctpl_value_array_length ()
CtplValue * | ctpl_value_array_index ()
CtplValueType | ctpl_value_get_held_type ()
glong | ctpl_value_get_int ()
gdouble | ctpl_value_get_float ()
const gchar * | ctpl_value_get_string ()
const GSList * | ctpl_value_get_array ()
glong * | ctpl_value_get_array_int ()
gdouble * | ctpl_value_get_array_float ()
gchar ** | ctpl_value_get_array_string ()
gchar * | ctpl_value_to_string ()
gboolean | ctpl_value_convert ()
const gchar * | ctpl_value_type_get_name ()
#define | ctpl_value_get_held_type_name()

## Types and Values

enum | CtplValueType
struct | CtplValue

## Includes

    #include <ctpl/ctpl.h>

## 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);

## Functions

### CTPL_VALUE_HOLDS()

    #define             CTPL_VALUE_HOLDS(value, vtype)

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

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.

#### Parameters

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

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

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.

#### Parameters

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

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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]

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

#### Parameters

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]

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

#### Parameters

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]

### ctpl_value_to_string ()

    gchar *
    ctpl_value_to_string (const CtplValue *value);

Converts a CtplValue to a string.

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.

#### Parameters

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.

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

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

## Types and Values

### enum CtplValueType

Represents the types that a CtplValue can hold.

#### Members

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 |

### struct CtplValue

    struct CtplValue {
    };

Represents a generic value.