Babeltrace 2 C API
2.1.1
Open-source trace manipulation framework
|
Generic, JSON-like basic data containers.
Values are generic data containers. Except for the fact that integer values are explicitly unsigned or signed because of typing limitations, Babeltrace 2 values are very similar to JSON values.
The value API is completely independent from the rest of the Babeltrace 2 C API.
Component initialization parameters, query parameters, as well as trace IR user attributes (for example, bt_event_class_set_user_attributes()) use values.
The available value types are:
double
range)Values are shared objects: get a new reference with bt_value_get_ref() and put an existing reference with bt_value_put_ref().
Some library functions freeze values on success. The documentation of those functions indicate this postcondition.
All the value types share the same C type, bt_value.
Get the type enumerator of a value with bt_value_get_type(). Get whether or not a value type conceptually is a given type with the inline bt_value_type_is() function. Get whether or not a value has a specific type with one of the bt_value_is_*()
inline helpers.
The null value is special in that it's a singleton variable, bt_value_null. You can directly compare any value pointer to bt_value_null to check if it's a null value. Like other types of values, the null value is a shared object: if you get a new null value reference, then you must eventually put it.
Create a value with one of the bt_value_*_create()
or bt_value_*_create_init()
functions.
This documentation names the actual data that a scalar value wraps the raw value.
Set and get the raw values of scalar values with functions that are named bt_value_*_set()
and bt_value_*_get()
.
Check that two values are recursively equal with bt_value_is_equal().
Deep-copy a value with bt_value_copy().
Extend a map value with bt_value_map_extend().
The following table shows the available functions and types for each type of value:
Type | |
typedef struct bt_value | bt_value |
Value. | |
Type query | |
enum | bt_value_type { BT_VALUE_TYPE_NULL, BT_VALUE_TYPE_BOOL, BT_VALUE_TYPE_INTEGER, BT_VALUE_TYPE_UNSIGNED_INTEGER, BT_VALUE_TYPE_SIGNED_INTEGER, BT_VALUE_TYPE_REAL, BT_VALUE_TYPE_STRING, BT_VALUE_TYPE_ARRAY, BT_VALUE_TYPE_MAP } |
Value type enumerators. More... | |
typedef enum bt_value_type | bt_value_type |
Value type enumerators. | |
bt_value_type | bt_value_get_type (const bt_value *value) |
Returns the type enumerator of the value value . More... | |
static bt_bool | bt_value_type_is (const bt_value_type type, const bt_value_type other_type) |
Returns whether or not the value type type conceptually is the value type other_type . More... | |
static bt_bool | bt_value_is_null (const bt_value *value) |
Returns whether or not the value value is a null value. More... | |
static bt_bool | bt_value_is_bool (const bt_value *value) |
Returns whether or not the value value is a boolean value. More... | |
static bt_bool | bt_value_is_unsigned_integer (const bt_value *value) |
Returns whether or not the value value is an unsigned integer value. More... | |
static bt_bool | bt_value_is_signed_integer (const bt_value *value) |
Returns whether or not the value value is a signed integer value. More... | |
static bt_bool | bt_value_is_real (const bt_value *value) |
Returns whether or not the value value is a real value. More... | |
static bt_bool | bt_value_is_string (const bt_value *value) |
Returns whether or not the value value is a string value. More... | |
static bt_bool | bt_value_is_array (const bt_value *value) |
Returns whether or not the value value is an array value. More... | |
static bt_bool | bt_value_is_map (const bt_value *value) |
Returns whether or not the value value is a map value. More... | |
Null value | |
bt_value *const | bt_value_null |
The null value singleton. More... | |
Boolean value | |
bt_value * | bt_value_bool_create (void) |
Creates and returns a boolean value initialized to BT_FALSE. More... | |
bt_value * | bt_value_bool_create_init (bt_bool raw_value) |
Creates and returns a boolean value initialized to raw_value . More... | |
void | bt_value_bool_set (bt_value *value, bt_bool raw_value) |
Sets the raw value of the boolean value value to raw_value . More... | |
bt_bool | bt_value_bool_get (const bt_value *value) |
Returns the raw value of the boolean value value . More... | |
Unsigned integer value | |
bt_value * | bt_value_integer_unsigned_create (void) |
Creates and returns an unsigned integer value initialized to 0. More... | |
bt_value * | bt_value_integer_unsigned_create_init (uint64_t raw_value) |
Creates and returns an unsigned integer value initialized to raw_value . More... | |
void | bt_value_integer_unsigned_set (bt_value *value, uint64_t raw_value) |
Sets the raw value of the unsigned integer value value to raw_value . More... | |
uint64_t | bt_value_integer_unsigned_get (const bt_value *value) |
Returns the raw value of the unsigned integer value value . More... | |
Signed integer value | |
bt_value * | bt_value_integer_signed_create (void) |
Creates and returns a signed integer value initialized to 0. More... | |
bt_value * | bt_value_integer_signed_create_init (int64_t raw_value) |
Creates and returns a signed integer value initialized to raw_value . More... | |
void | bt_value_integer_signed_set (bt_value *value, int64_t raw_value) |
Sets the raw value of the signed integer value value to raw_value . More... | |
int64_t | bt_value_integer_signed_get (const bt_value *value) |
Returns the raw value of the signed integer value value . More... | |
Real value | |
bt_value * | bt_value_real_create (void) |
Creates and returns a real value initialized to 0. More... | |
bt_value * | bt_value_real_create_init (double raw_value) |
Creates and returns a real value initialized to raw_value . More... | |
void | bt_value_real_set (bt_value *value, double raw_value) |
Sets the raw value of the real value value to raw_value . More... | |
double | bt_value_real_get (const bt_value *value) |
Returns the raw value of the real value value . More... | |
String value | |
enum | bt_value_string_set_status { BT_VALUE_STRING_SET_STATUS_OK, BT_VALUE_STRING_SET_STATUS_MEMORY_ERROR } |
Status codes for bt_value_string_set(). More... | |
typedef enum bt_value_string_set_status | bt_value_string_set_status |
Status codes for bt_value_string_set(). | |
bt_value * | bt_value_string_create (void) |
Creates and returns an empty string value. More... | |
bt_value * | bt_value_string_create_init (const char *raw_value) |
Creates and returns a string value initialized to a copy of raw_value . More... | |
bt_value_string_set_status | bt_value_string_set (bt_value *value, const char *raw_value) |
Sets the raw value of the string value value to a copy of raw_value . More... | |
const char * | bt_value_string_get (const bt_value *value) |
Returns the raw value of the string value value . More... | |
Array value | |
enum | bt_value_array_append_element_status { BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK, BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR } |
Status codes for the bt_value_array_append_*() functions. More... | |
enum | bt_value_array_set_element_by_index_status { BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_OK, BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_MEMORY_ERROR } |
Status codes for bt_value_array_set_element_by_index(). More... | |
typedef enum bt_value_array_append_element_status | bt_value_array_append_element_status |
Status codes for the bt_value_array_append_*() functions. | |
typedef enum bt_value_array_set_element_by_index_status | bt_value_array_set_element_by_index_status |
Status codes for bt_value_array_set_element_by_index(). | |
bt_value * | bt_value_array_create (void) |
Creates and returns an empty array value. More... | |
bt_value_array_append_element_status | bt_value_array_append_element (bt_value *value, bt_value *element_value) |
Appends the value element_value to the array value value . More... | |
bt_value_array_append_element_status | bt_value_array_append_bool_element (bt_value *value, bt_bool raw_value) |
Creates a boolean value initialized to raw_value and appends it to the array value value . More... | |
bt_value_array_append_element_status | bt_value_array_append_unsigned_integer_element (bt_value *value, uint64_t raw_value) |
Creates an unsigned integer value initialized to raw_value and appends it to the array value value . More... | |
bt_value_array_append_element_status | bt_value_array_append_signed_integer_element (bt_value *value, int64_t raw_value) |
Creates a signed integer value initialized to raw_value and appends it to the array value value . More... | |
bt_value_array_append_element_status | bt_value_array_append_real_element (bt_value *value, double raw_value) |
Creates a real value initialized to raw_value and appends it to the array value value . More... | |
bt_value_array_append_element_status | bt_value_array_append_string_element (bt_value *value, const char *raw_value) |
Creates a string value initialized to a copy of raw_value and appends it to the array value value . More... | |
bt_value_array_append_element_status | bt_value_array_append_empty_array_element (bt_value *value, bt_value **element_value) |
Creates an empty array value and appends it to the array value value . More... | |
bt_value_array_append_element_status | bt_value_array_append_empty_map_element (bt_value *value, bt_value **element_value) |
Creates an empty map value and appends it to the array value value . More... | |
bt_value_array_set_element_by_index_status | bt_value_array_set_element_by_index (bt_value *value, uint64_t index, bt_value *element_value) |
Sets the element of the array value value at index index to the value element_value . More... | |
bt_value * | bt_value_array_borrow_element_by_index (bt_value *value, uint64_t index) |
Borrows the element at index index from the array value value . More... | |
const bt_value * | bt_value_array_borrow_element_by_index_const (const bt_value *value, uint64_t index) |
Borrows the element at index index from the array value value (const version). More... | |
uint64_t | bt_value_array_get_length (const bt_value *value) |
Returns the length of the array value value . More... | |
static bt_bool | bt_value_array_is_empty (const bt_value *value) |
Returns whether or not the array value value is empty. More... | |
General | |
enum | bt_value_copy_status { BT_VALUE_COPY_STATUS_OK, BT_VALUE_COPY_STATUS_MEMORY_ERROR } |
Status codes for bt_value_copy(). More... | |
typedef enum bt_value_copy_status | bt_value_copy_status |
Status codes for bt_value_copy(). | |
bt_value_copy_status | bt_value_copy (const bt_value *value, bt_value **copy_value) |
Deep-copies a value object. More... | |
bt_bool | bt_value_is_equal (const bt_value *a_value, const bt_value *b_value) |
Returns whether or not the value a_value is equal, recursively, to b_value . More... | |
Reference count | |
void | bt_value_get_ref (const bt_value *value) |
Increments the reference count of the value value . More... | |
void | bt_value_put_ref (const bt_value *value) |
Decrements the reference count of the value value . More... | |
#define | BT_VALUE_PUT_REF_AND_RESET(_value) |
Decrements the reference count of the value _value , and then sets _value to NULL . More... | |
#define | BT_VALUE_MOVE_REF(_dst, _src) |
Decrements the reference count of the value _dst , sets _dst to _src , and then sets _src to NULL . More... | |
typedef bt_value_map_foreach_entry_func_status(* bt_value_map_foreach_entry_func) (const char *key, bt_value *value, void *user_data) |
User function for bt_value_map_foreach_entry().
This is the type of the user function that bt_value_map_foreach_entry() calls for each entry of the map value.
[in] | key | Key of the map value entry. |
[in] | value | Value of the map value entry. |
[in] | user_data | User data, as passed as the user_data parameter of bt_value_map_foreach_entry(). |
BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_OK | Success. |
BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_INTERRUPT | Interrupt the iteration process. |
BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_MEMORY_ERROR | Out of memory. |
BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_ERROR | User error. |
key
is not NULL
. value
is not NULL
.typedef bt_value_map_foreach_entry_const_func_status(* bt_value_map_foreach_entry_const_func) (const char *key, const bt_value *value, void *user_data) |
User function for bt_value_map_foreach_entry_const_func().
This is the type of the user function that bt_value_map_foreach_entry_const_func() calls for each entry of the map value.
[in] | key | Key of the map value entry. |
[in] | value | Value of the map value entry. |
[in] | user_data | User data. |
BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_OK | Success. |
BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_INTERRUPT | Interrupt the iteration process. |
BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_MEMORY_ERROR | Out of memory. |
BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_ERROR | User error. |
key
is not NULL
. value
is not NULL
.const
map value. enum bt_value_type |
Value type enumerators.
Enumerator | |
---|---|
BT_VALUE_TYPE_NULL |
Null value. |
BT_VALUE_TYPE_BOOL |
Boolean value. |
BT_VALUE_TYPE_INTEGER |
Integer value. No value has this type: use it with bt_value_type_is(). |
BT_VALUE_TYPE_UNSIGNED_INTEGER |
Unsigned integer value. This type conceptually inherits BT_VALUE_TYPE_INTEGER. |
BT_VALUE_TYPE_SIGNED_INTEGER |
Signed integer value. This type conceptually inherits BT_VALUE_TYPE_INTEGER. |
BT_VALUE_TYPE_REAL |
Real value. |
BT_VALUE_TYPE_STRING |
String value. |
BT_VALUE_TYPE_ARRAY |
Array value. |
BT_VALUE_TYPE_MAP |
Map value. |
Status codes for bt_value_string_set().
Enumerator | |
---|---|
BT_VALUE_STRING_SET_STATUS_OK |
Success. |
BT_VALUE_STRING_SET_STATUS_MEMORY_ERROR |
Out of memory. |
Status codes for bt_value_array_set_element_by_index().
Enumerator | |
---|---|
BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_OK |
Success. |
BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_MEMORY_ERROR |
Out of memory. |
Status codes for bt_value_map_foreach_entry_func.
Status codes for bt_value_map_foreach_entry().
Status codes for bt_value_map_foreach_entry_const_func.
Status codes for bt_value_map_foreach_entry_const().
Status codes for bt_value_map_extend().
Enumerator | |
---|---|
BT_VALUE_MAP_EXTEND_STATUS_OK |
Success. |
BT_VALUE_MAP_EXTEND_STATUS_MEMORY_ERROR |
Out of memory. |
enum bt_value_copy_status |
Status codes for bt_value_copy().
Enumerator | |
---|---|
BT_VALUE_COPY_STATUS_OK |
Success. |
BT_VALUE_COPY_STATUS_MEMORY_ERROR |
Out of memory. |
#define BT_VALUE_PUT_REF_AND_RESET | ( | _value | ) |
Decrements the reference count of the value _value
, and then sets _value
to NULL
.
_value | Value of which to decrement the reference count. Can contain |
_value
is an assignable expression. #define BT_VALUE_MOVE_REF | ( | _dst, | |
_src | |||
) |
Decrements the reference count of the value _dst
, sets _dst
to _src
, and then sets _src
to NULL
.
This macro effectively moves a value reference from the expression _src
to the expression _dst
, putting the existing _dst
reference.
_dst | Destination expression. Can contain |
_src | Source expression. Can contain |
_dst
is an assignable expression. _src
is an assignable expression. bt_value* const bt_value_null |
The null value singleton.
This is the only instance of a null value.
Like any type of value, the null value is a shared object: if you get a new null value reference with bt_value_get_ref(), then you must eventually put it with bt_value_put_ref(). The reference count of the null value singleton must never reach 0: libbabeltrace2 logs a warning message when this programming error occurs.
Because all null values point to the same null value singleton, you can directly compare a value to the bt_value_null
variable.
bt_value_null
is different from NULL:
the former is a true Babeltrace 2 value object while the latter is a C definition which usually means "no pointer".
For example, bt_value_map_borrow_entry_value() can return bt_value_null
if the requested key is mapped to a null value, but it can also return NULL
if the key isn't found.
bt_value_type bt_value_get_type | ( | const bt_value * | value | ) |
Returns the type enumerator of the value value
.
[in] | value | Value of which to get the type enumerator |
value
.value
is not NULL
.
|
inlinestatic |
Returns whether or not the value type type
conceptually is the value type other_type
.
For example, an unsigned integer value conceptually is an integer value, so
returns BT_TRUE.
[in] | type | Value type to check against other_type . |
[in] | other_type | Value type against which to check type . |
type
conceptually is other_type
.Returns whether or not the value value
is a null value.
value
to the bt_value_null variable.[in] | value | Value to check. |
value
is a null value.value
is not NULL
.Returns whether or not the value value
is a boolean value.
[in] | value | Value to check. |
value
is a boolean value.value
is not NULL
.Returns whether or not the value value
is an unsigned integer value.
[in] | value | Value to check. |
value
is an unsigned integer value.value
is not NULL
.Returns whether or not the value value
is a signed integer value.
[in] | value | Value to check. |
value
is a signed integer value.value
is not NULL
.Returns whether or not the value value
is a real value.
[in] | value | Value to check. |
value
is a real value.value
is not NULL
.Returns whether or not the value value
is a string value.
[in] | value | Value to check. |
value
is a string value.value
is not NULL
.Returns whether or not the value value
is an array value.
[in] | value | Value to check. |
value
is an array value.value
is not NULL
.Returns whether or not the value value
is a map value.
[in] | value | Value to check. |
value
is a map value.value
is not NULL
.bt_value* bt_value_bool_create | ( | void | ) |
Creates and returns a boolean value initialized to BT_FALSE.
The returned value has the type BT_VALUE_TYPE_BOOL.
NULL
on memory error.Creates and returns a boolean value initialized to raw_value
.
The returned value has the type BT_VALUE_TYPE_BOOL.
[in] | raw_value | Initial raw value of the boolean value to create. |
NULL
on memory error.Sets the raw value of the boolean value value
to raw_value
.
[in] | value | Boolean value of which to set the raw value to raw_value . |
[in] | raw_value | New raw value of value . |
value
is not NULL
. value
is a boolean value (bt_value_is_bool() returns BT_TRUE). value
is not frozen.Returns the raw value of the boolean value value
.
[in] | value | Boolean value of which to get the raw value. |
value
.value
is not NULL
. value
is a boolean value (bt_value_is_bool() returns BT_TRUE).bt_value* bt_value_integer_unsigned_create | ( | void | ) |
Creates and returns an unsigned integer value initialized to 0.
The returned value has the type BT_VALUE_TYPE_UNSIGNED_INTEGER.
NULL
on memory error.bt_value* bt_value_integer_unsigned_create_init | ( | uint64_t | raw_value | ) |
Creates and returns an unsigned integer value initialized to raw_value
.
The returned value has the type BT_VALUE_TYPE_UNSIGNED_INTEGER.
[in] | raw_value | Initial raw value of the unsigned integer value to create. |
NULL
on memory error.void bt_value_integer_unsigned_set | ( | bt_value * | value, |
uint64_t | raw_value | ||
) |
Sets the raw value of the unsigned integer value value
to raw_value
.
[in] | value | Unsigned integer value of which to set the raw value to raw_value . |
[in] | raw_value | New raw value of value . |
value
is not NULL
. value
is an unsigned integer value (bt_value_is_unsigned_integer() returns BT_TRUE). value
is not frozen.uint64_t bt_value_integer_unsigned_get | ( | const bt_value * | value | ) |
Returns the raw value of the unsigned integer value value
.
[in] | value | Unsigned integer value of which to get the raw value. |
value
.value
is not NULL
. value
is an unsigned integer value (bt_value_is_unsigned_integer() returns BT_TRUE).bt_value* bt_value_integer_signed_create | ( | void | ) |
Creates and returns a signed integer value initialized to 0.
The returned value has the type BT_VALUE_TYPE_SIGNED_INTEGER.
NULL
on memory error.bt_value* bt_value_integer_signed_create_init | ( | int64_t | raw_value | ) |
Creates and returns a signed integer value initialized to raw_value
.
The returned value has the type BT_VALUE_TYPE_SIGNED_INTEGER.
[in] | raw_value | Initial raw value of the signed integer value to create. |
NULL
on memory error.void bt_value_integer_signed_set | ( | bt_value * | value, |
int64_t | raw_value | ||
) |
Sets the raw value of the signed integer value value
to raw_value
.
[in] | value | Signed integer value of which to set the raw value to raw_value . |
[in] | raw_value | New raw value of value . |
value
is not NULL
. value
is a signed integer value (bt_value_is_signed_integer() returns BT_TRUE). value
is not frozen.int64_t bt_value_integer_signed_get | ( | const bt_value * | value | ) |
Returns the raw value of the signed integer value value
.
[in] | value | Signed integer value of which to get the raw value. |
value
.value
is not NULL
. value
is a signed integer value (bt_value_is_signed_integer() returns BT_TRUE).bt_value* bt_value_real_create | ( | void | ) |
Creates and returns a real value initialized to 0.
The returned value has the type BT_VALUE_TYPE_REAL.
NULL
on memory error.bt_value* bt_value_real_create_init | ( | double | raw_value | ) |
Creates and returns a real value initialized to raw_value
.
The returned value has the type BT_VALUE_TYPE_REAL.
[in] | raw_value | Initial raw value of the real value to create. |
NULL
on memory error.void bt_value_real_set | ( | bt_value * | value, |
double | raw_value | ||
) |
Sets the raw value of the real value value
to raw_value
.
[in] | value | Real value of which to set the raw value to raw_value . |
[in] | raw_value | New raw value of value . |
value
is not NULL
. value
is a real value (bt_value_is_real() returns BT_TRUE). value
is not frozen.double bt_value_real_get | ( | const bt_value * | value | ) |
Returns the raw value of the real value value
.
[in] | value | Real value of which to get the raw value. |
value
.value
is not NULL
. value
is a real value (bt_value_is_real() returns BT_TRUE).bt_value* bt_value_string_create | ( | void | ) |
Creates and returns an empty string value.
The returned value has the type BT_VALUE_TYPE_STRING.
NULL
on memory error.bt_value* bt_value_string_create_init | ( | const char * | raw_value | ) |
Creates and returns a string value initialized to a copy of raw_value
.
The returned value has the type BT_VALUE_TYPE_STRING.
[in] | raw_value | Initial raw value of the string value to create (copied). |
NULL
on memory error.raw_value
is not NULL
.bt_value_string_set_status bt_value_string_set | ( | bt_value * | value, |
const char * | raw_value | ||
) |
Sets the raw value of the string value value
to a copy of raw_value
.
[in] | value | String value of which to set the raw value to a copy of raw_value . |
[in] | raw_value | New raw value of value (copied). |
BT_VALUE_STRING_SET_STATUS_OK | Success. |
BT_VALUE_STRING_SET_STATUS_MEMORY_ERROR | Out of memory. |
value
is not NULL
. value
is a string value (bt_value_is_string() returns BT_TRUE). value
is not frozen. raw_value
is not NULL
.const char* bt_value_string_get | ( | const bt_value * | value | ) |
Returns the raw value of the string value value
.
[in] | value | String value of which to get the raw value. |
Raw value of value
.
The returned pointer remains valid until value
is modified.
value
is not NULL
. value
is a string value (bt_value_is_string() returns BT_TRUE).bt_value* bt_value_array_create | ( | void | ) |
Creates and returns an empty array value.
The returned value has the type BT_VALUE_TYPE_ARRAY.
NULL
on memory error. bt_value_array_append_element_status bt_value_array_append_element | ( | bt_value * | value, |
bt_value * | element_value | ||
) |
Appends the value element_value
to the array value value
.
To append a null value, pass bt_value_null as element_value
.
[in] | value | Array value to which to append element_value . |
[in] | element_value | Value to append to value . |
BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK | Success. |
BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR | Out of memory. |
value
is not NULL
. value
is an array value (bt_value_is_array() returns BT_TRUE). value
is not frozen. element_value
is not NULL
. element_value
doesn't contain value
, recursively.value
is incremented.bt_value_array_append_element_status bt_value_array_append_bool_element | ( | bt_value * | value, |
bt_bool | raw_value | ||
) |
Creates a boolean value initialized to raw_value
and appends it to the array value value
.
[in] | value | Array value to which to append the created boolean value. |
[in] | raw_value | Raw value of the boolean value to create and append to value . |
BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK | Success. |
BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR | Out of memory. |
value
is not NULL
. value
is an array value (bt_value_is_array() returns BT_TRUE). value
is not frozen.value
is incremented.bt_value_array_append_element_status bt_value_array_append_unsigned_integer_element | ( | bt_value * | value, |
uint64_t | raw_value | ||
) |
Creates an unsigned integer value initialized to raw_value
and appends it to the array value value
.
[in] | value | Array value to which to append the created unsigned integer value. |
[in] | raw_value | Raw value of the unsigned integer value to create and append to value . |
BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK | Success. |
BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR | Out of memory. |
value
is not NULL
. value
is an array value (bt_value_is_array() returns BT_TRUE). value
is not frozen.value
is incremented.bt_value_array_append_element_status bt_value_array_append_signed_integer_element | ( | bt_value * | value, |
int64_t | raw_value | ||
) |
Creates a signed integer value initialized to raw_value
and appends it to the array value value
.
[in] | value | Array value to which to append the created signed integer value. |
[in] | raw_value | Raw value of the signed integer value to create and append to value . |
BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK | Success. |
BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR | Out of memory. |
value
is not NULL
. value
is an array value (bt_value_is_array() returns BT_TRUE). value
is not frozen.value
is incremented.bt_value_array_append_element_status bt_value_array_append_real_element | ( | bt_value * | value, |
double | raw_value | ||
) |
Creates a real value initialized to raw_value
and appends it to the array value value
.
[in] | value | Array value to which to append the created real value. |
[in] | raw_value | Raw value of the real value to create and append to value . |
BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK | Success. |
BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR | Out of memory. |
value
is not NULL
. value
is an array value (bt_value_is_array() returns BT_TRUE). value
is not frozen.value
is incremented.bt_value_array_append_element_status bt_value_array_append_string_element | ( | bt_value * | value, |
const char * | raw_value | ||
) |
Creates a string value initialized to a copy of raw_value
and appends it to the array value value
.
[in] | value | Array value to which to append the created string value. |
[in] | raw_value | Raw value of the string value to create and append to value (copied). |
BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK | Success. |
BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR | Out of memory. |
value
is not NULL
. value
is an array value (bt_value_is_array() returns BT_TRUE). value
is not frozen.value
is incremented.bt_value_array_append_element_status bt_value_array_append_empty_array_element | ( | bt_value * | value, |
bt_value ** | element_value | ||
) |
Creates an empty array value and appends it to the array value value
.
On success, if element_value
isn't NULL
, this function sets *element_value
to a borrowed reference of the created empty array value.
[in] | value | Array value to which to append the created empty array value. |
[out] | element_value | On success, if not NULL , *element_value is a borrowed reference of the created empty array value. |
BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK | Success. |
BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR | Out of memory. |
value
is not NULL
. value
is an array value (bt_value_is_array() returns BT_TRUE). value
is not frozen.value
is incremented.bt_value_array_append_element_status bt_value_array_append_empty_map_element | ( | bt_value * | value, |
bt_value ** | element_value | ||
) |
Creates an empty map value and appends it to the array value value
.
On success, if element_value
isn't NULL
, this function sets *element_value
to a borrowed reference of the created empty map value.
[in] | value | Array value to which to append the created empty array value. |
[out] | element_value | On success, if not NULL , *element_value is a borrowed reference of the created empty map value. |
BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK | Success. |
BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR | Out of memory. |
value
is not NULL
. value
is an array value (bt_value_is_array() returns BT_TRUE). value
is not frozen.value
is incremented.bt_value_array_set_element_by_index_status bt_value_array_set_element_by_index | ( | bt_value * | value, |
uint64_t | index, | ||
bt_value * | element_value | ||
) |
Sets the element of the array value value
at index index
to the value element_value
.
On success, this function replaces the existing element of value
at index index
.
[in] | value | Array value of which to set the element at index index . |
[in] | index | Index of the element to set in value . |
[in] | element_value | Value to set as the element of value at index index . |
BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_OK | Success. |
BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_MEMORY_ERROR | Out of memory. |
value
is not NULL
. value
is an array value (bt_value_is_array() returns BT_TRUE). value
is not frozen. index
is less than the length of value
(as returned by bt_value_array_get_length()). element_value
is not NULL
. element_value
doesn't contain value
, recursively.value
is incremented.Borrows the element at index index
from the array value value
.
[in] | value | Array value from which to borrow the element at index index . |
[in] | index | Index of the element to borrow from value . |
Borrowed reference of the element of value
at index index
.
The returned pointer remains valid until value
is modified.
value
is not NULL
. value
is an array value (bt_value_is_array() returns BT_TRUE). index
is less than the length of value
(as returned by bt_value_array_get_length()).const
version of this function. const bt_value* bt_value_array_borrow_element_by_index_const | ( | const bt_value * | value, |
uint64_t | index | ||
) |
Borrows the element at index index
from the array value value
(const
version).
uint64_t bt_value_array_get_length | ( | const bt_value * | value | ) |
Returns the length of the array value value
.
[in] | value | Array value of which to get the length. |
value
.value
is not NULL
. value
is an array value (bt_value_is_array() returns BT_TRUE).Returns whether or not the array value value
is empty.
[in] | value | Array value to check. |
value
is empty (has the length 0).value
is not NULL
. value
is an array value (bt_value_is_array() returns BT_TRUE).bt_value* bt_value_map_create | ( | void | ) |
Creates and returns an empty map value.
The returned value has the type BT_VALUE_TYPE_MAP.
NULL
on memory error. bt_value_map_insert_entry_status bt_value_map_insert_entry | ( | bt_value * | value, |
const char * | key, | ||
bt_value * | entry_value | ||
) |
Inserts or replaces an entry with the key key
and the value entry_value
in the map value value
.
To insert an entry having a null value, pass bt_value_null as entry_value
.
On success, if value
already contains an entry with key key
, this function replaces the value of the existing entry with entry_value
.
[in] | value | Map value in which to insert or replace an entry with key key and value entry_value . |
[in] | key | Key of the entry to insert or replace in value (copied). |
[in] | entry_value | Value of the entry to insert or replace in value . |
BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK | Success. |
BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR | Out of memory. |
value
is not NULL
. value
is a map value (bt_value_is_map() returns BT_TRUE). value
is not frozen. key
is not NULL
. entry_value
is not NULL
. entry_value
doesn't contain value
, recursively.bt_value_map_insert_entry_status bt_value_map_insert_bool_entry | ( | bt_value * | value, |
const char * | key, | ||
bt_bool | raw_value | ||
) |
Creates a boolean value initialized to raw_value
and inserts or replaces an entry with the key key
and this value in the map value value
.
On success, if value
already contains an entry with key key
, this function replaces the value of the existing entry with the created boolean value.
[in] | value | Map value in which to insert or replace an entry with key key and the created boolean value. |
[in] | key | Key of the entry to insert or replace in value (copied). |
[in] | raw_value | Initial raw value of the boolean value to create. |
BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK | Success. |
BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR | Out of memory. |
value
is not NULL
. value
is a map value (bt_value_is_map() returns BT_TRUE). value
is not frozen. key
is not NULL
.bt_value_map_insert_entry_status bt_value_map_insert_unsigned_integer_entry | ( | bt_value * | value, |
const char * | key, | ||
uint64_t | raw_value | ||
) |
Creates an unsigned integer value initialized to raw_value
and inserts or replaces an entry with the key key
and this value in the map value value
.
On success, if value
already contains an entry with key key
, this function replaces the value of the existing entry with the created unsigned integer value.
[in] | value | Map value in which to insert or replace an entry with key key and the created unsigned integer value. |
[in] | key | Key of the entry to insert or replace in value (copied). |
[in] | raw_value | Initial raw value of the unsigned integer value to create. |
BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK | Success. |
BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR | Out of memory. |
value
is not NULL
. value
is a map value (bt_value_is_map() returns BT_TRUE). value
is not frozen. key
is not NULL
.bt_value_map_insert_entry_status bt_value_map_insert_signed_integer_entry | ( | bt_value * | value, |
const char * | key, | ||
int64_t | raw_value | ||
) |
Creates a signed integer value initialized to raw_value
and inserts or replaces an entry with the key key
and this value in the map value value
.
On success, if value
already contains an entry with key key
, this function replaces the value of the existing entry with the created signed integer value.
[in] | value | Map value in which to insert or replace an entry with key key and the created signed integer value. |
[in] | key | Key of the entry to insert or replace in value (copied). |
[in] | raw_value | Initial raw value of the signed integer value to create. |
BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK | Success. |
BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR | Out of memory. |
value
is not NULL
. value
is a map value (bt_value_is_map() returns BT_TRUE). value
is not frozen. key
is not NULL
.bt_value_map_insert_entry_status bt_value_map_insert_real_entry | ( | bt_value * | value, |
const char * | key, | ||
double | raw_value | ||
) |
Creates a real value initialized to raw_value
and inserts or replaces an entry with the key key
and this value in the map value value
.
On success, if value
already contains an entry with key key
, this function replaces the value of the existing entry with the created real value.
[in] | value | Map value in which to insert or replace an entry with key key and the created real value. |
[in] | key | Key of the entry to insert or replace in value (copied). |
[in] | raw_value | Initial raw value of the real value to create. |
BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK | Success. |
BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR | Out of memory. |
value
is not NULL
. value
is a map value (bt_value_is_map() returns BT_TRUE). value
is not frozen. key
is not NULL
.bt_value_map_insert_entry_status bt_value_map_insert_string_entry | ( | bt_value * | value, |
const char * | key, | ||
const char * | raw_value | ||
) |
Creates a string value initialized to a copy of raw_value
and inserts or replaces an entry with the key key
and this value in the map value value
.
On success, if value
already contains an entry with key key
, this function replaces the value of the existing entry with the created string value.
[in] | value | Map value in which to insert or replace an entry with key key and the created string value. |
[in] | key | Key of the entry to insert or replace in value (copied). |
[in] | raw_value | Initial raw value of the string value to create (copied). |
BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK | Success. |
BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR | Out of memory. |
value
is not NULL
. value
is a map value (bt_value_is_map() returns BT_TRUE). value
is not frozen. key
is not NULL
.bt_value_map_insert_entry_status bt_value_map_insert_empty_array_entry | ( | bt_value * | value, |
const char * | key, | ||
bt_value ** | entry_value | ||
) |
Creates an empty array value and inserts or replaces an entry with the key key
and this value in the map value value
.
On success, if entry_value
isn't NULL
, this function sets *entry_value
to a borrowed reference of the created empty array value.
On success, if value
already contains an entry with key key
, this function replaces the value of the existing entry with the created empty array value.
[in] | value | Map value in which to insert or replace an entry with key key and the created empty array value. |
[in] | key | Key of the entry to insert or replace in value (copied). |
[out] | entry_value | On success, if not NULL , *entry_value is a borrowed reference of the created empty array value. |
BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK | Success. |
BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR | Out of memory. |
value
is not NULL
. value
is a map value (bt_value_is_map() returns BT_TRUE). value
is not frozen. key
is not NULL
.bt_value_map_insert_entry_status bt_value_map_insert_empty_map_entry | ( | bt_value * | value, |
const char * | key, | ||
bt_value ** | entry_value | ||
) |
Creates an empty map value and inserts or replaces an entry with the key key
and this value in the map value value
.
On success, if entry_value
isn't NULL
, this function sets *entry_value
to a borrowed reference of the created empty map value.
On success, if value
already contains an entry with key key
, this function replaces the value of the existing entry with the created empty map value.
[in] | value | Map value in which to insert or replace an entry with key key and the created empty map value. |
[in] | key | Key of the entry to insert or replace in value (copied). |
[out] | entry_value | On success, if not NULL , *entry_value is a borrowed reference of the created empty map value. |
BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK | Success. |
BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR | Out of memory. |
value
is not NULL
. value
is a map value (bt_value_is_map() returns BT_TRUE). value
is not frozen. key
is not NULL
.Borrows the value of the entry with the key key
in the map value value
.
If no entry with key key
exists in value
, then this function returns NULL
.
[in] | value | Map value from which to borrow the value of the entry with the key key . |
[in] | key | Key of the entry from which to borrow the value in value . |
Borrowed reference of the value of the entry with key key
in value
, or NULL
if none.
The returned pointer remains valid until value
is modified.
value
is not NULL
. value
is a map value (bt_value_is_map() returns BT_TRUE). key
is not NULL
.const
version of this function. Borrows the value of the entry with the key key
in the map value value
(const
version).
bt_value_map_foreach_entry_status bt_value_map_foreach_entry | ( | bt_value * | value, |
bt_value_map_foreach_entry_func | user_func, | ||
void * | user_data | ||
) |
Iterates the entries of the map value value
, calling user_func
for each entry.
This function iterates the entries of value
in no particular order.
value
during the iteration process.user_func
receives user_data
as its last parameter.
The iteration process stops when one of:
user_func
was called for each entry.user_func
doesn't return BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_OK.[in] | value | Map value of which to iterate the entries. |
[in] | user_func | User function to call for each entry of value . |
[in] | user_data | User data to pass as the user_data parameter of each call to user_func . |
BT_VALUE_MAP_FOREACH_ENTRY_STATUS_OK | Success. |
BT_VALUE_MAP_FOREACH_ENTRY_STATUS_INTERRUPTED | user_func returned BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_INTERRUPT to interrupt the iteration process. |
BT_VALUE_MAP_FOREACH_ENTRY_STATUS_USER_ERROR | user_func returned BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_ERROR. |
BT_VALUE_MAP_FOREACH_ENTRY_STATUS_MEMORY_ERROR | Out of memory. |
BT_VALUE_MAP_FOREACH_ENTRY_STATUS_ERROR | Other error caused the bt_value_map_foreach_entry() function itself. |
value
is not NULL
. value
is a map value (bt_value_is_map() returns BT_TRUE). user_func
is not NULL
.const
version of this function. bt_value_map_foreach_entry_const_status bt_value_map_foreach_entry_const | ( | const bt_value * | value, |
bt_value_map_foreach_entry_const_func | user_func, | ||
void * | user_data | ||
) |
Iterates the entries of the map value value
, calling user_func
for each entry (const
version).
See bt_value_map_foreach_entry().
uint64_t bt_value_map_get_size | ( | const bt_value * | value | ) |
Returns the size of the map value value
.
[in] | value | Map value of which to get the size. |
value
.value
is not NULL
. value
is a map value (bt_value_is_map() returns BT_TRUE).Returns whether or not the map value value
is empty.
[in] | value | Map value to check. |
value
is empty (has the size 0).value
is not NULL
. value
is a map value (bt_value_is_map() returns BT_TRUE).Returns whether or not the map value value
has an entry with the key key
.
[in] | value | Map value to check. |
[in] | key | Key to check. |
value
has an entry with the key key
.value
is not NULL
. value
is a map value (bt_value_is_map() returns BT_TRUE). key
is not NULL
.bt_value_map_extend_status bt_value_map_extend | ( | bt_value * | value, |
const bt_value * | extension_value | ||
) |
Extends the map value value
with the map value extension_value
.
For each entry in extension_value
, this function calls bt_value_map_insert_entry() to insert or replace it in the map value value
.
For example, with:
value
extension_value
The map value value
becomes:
[in] | value | Map value to extend. |
[in] | extension_value | Extension map value. |
BT_VALUE_MAP_EXTEND_STATUS_OK | Success. |
BT_VALUE_MAP_EXTEND_STATUS_MEMORY_ERROR | Out of memory. |
value
is not NULL
. value
is a map value (bt_value_is_map() returns BT_TRUE). extension_value
is not NULL
. extension_value
is a map value (bt_value_is_map() returns BT_TRUE).bt_value_copy_status bt_value_copy | ( | const bt_value * | value, |
bt_value ** | copy_value | ||
) |
Deep-copies a value object.
This function deep-copies value
and sets *copy
to the result.
Because *copy
is a deep copy, it doesn't contain, recursively, any reference that value
contains, but the raw values are identical.
[in] | value | Value to deep-copy. |
[in] | copy_value | On success, *copy_value is a deep copy of value . |
BT_VALUE_COPY_STATUS_OK | Success. |
BT_VALUE_COPY_STATUS_MEMORY_ERROR | Out of memory. |
value
is not NULL
. copy_value
is not NULL
. Returns whether or not the value a_value
is equal, recursively, to b_value
.
[in] | a_value | Value A. |
[in] | b_value | Value B. |
a_value
is equal, recursively, to b_value
.a_value
is not NULL
. b_value
is not NULL
. void bt_value_get_ref | ( | const bt_value * | value | ) |
Increments the reference count of the value value
.
[in] | value | Value of which to increment the reference count. Can be |
void bt_value_put_ref | ( | const bt_value * | value | ) |
Decrements the reference count of the value value
.
[in] | value | Value of which to decrement the reference count. Can be |