|
Babeltrace 2 C API
2.0.0
Open-source trace manipulation framework
|
|
Babeltrace 2 C API
2.0.0
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, 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. |
NULL. 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. |
NULL. 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 |
| #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 |
| 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(), you must eventually put it with bt_value_put_ref(). The null value singleton's reference count 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 is not 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 |
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. |
Returns whether or not the value value is a null value.
| [in] | value | Value to check. |
NULL.Returns whether or not the value value is a boolean value.
| [in] | value | Value to check. |
NULL.Returns whether or not the value value is an unsigned integer value.
| [in] | value | Value to check. |
NULL.Returns whether or not the value value is a signed integer value.
| [in] | value | Value to check. |
NULL.Returns whether or not the value value is a real value.
| [in] | value | Value to check. |
NULL.Returns whether or not the value value is a string value.
| [in] | value | Value to check. |
NULL.Returns whether or not the value value is an array value.
| [in] | value | Value to check. |
NULL.Returns whether or not the value value is a map value.
| [in] | value | Value to check. |
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. |
NULL. Returns the raw value of the boolean value value.
| [in] | value | Boolean value of which to get the raw value. |
NULL. | 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. |
NULL. | 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. |
NULL. | 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. |
NULL. | 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. |
NULL. | 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. |
NULL. | 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. |
NULL. | 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.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. |
NULL. 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.
NULL. | 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. |
NULL. NULL. | 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. |
NULL. | 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. |
NULL. | 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. |
NULL. | 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. |
NULL. | 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. |
NULL. | 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 is not 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. |
NULL. | 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 is not 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. |
NULL. | 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. |
NULL. NULL. 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.
NULL. 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. |
NULL. Returns whether or not the array value value is empty.
| [in] | value | Array value to check. |
NULL. | 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 existing entry's value 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. |
NULL. NULL. NULL. | 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 existing entry's value 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. |
NULL. 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 existing entry's value 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. |
NULL. 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 existing entry's value 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. |
NULL. 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 existing entry's value 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. |
NULL. 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 existing entry's value 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. |
NULL. 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 is not 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 existing entry's value 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. |
NULL. 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 is not 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 existing entry's value 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. |
NULL. 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, 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.
NULL. 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.
user_func receives user_data as its last parameter.
The iteration process stops when one of:
| [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. |
NULL. 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. |
NULL. Returns whether or not the map value value is empty.
| [in] | value | Map value to check. |
NULL. 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. |
NULL. 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:
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. |
NULL. NULL. | 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 does not 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. |
NULL. 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. |
NULL. 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 |
1.8.16