X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=blobdiff_plain;f=include%2Fbabeltrace2%2Fvalue.h;h=1bf683b5ce5037161c8e00862cc1076190307de6;hp=42e3cf96dd22496c406b7aaf2506ca9e67ed41e0;hb=43c59509042845f8d42c3e99ec74d45fa2dc0908;hpb=1cda4ff4025e4b3f7bd2a861baa51d2113c4cbf9 diff --git a/include/babeltrace2/value.h b/include/babeltrace2/value.h index 42e3cf96..1bf683b5 100644 --- a/include/babeltrace2/value.h +++ b/include/babeltrace2/value.h @@ -31,166 +31,2435 @@ #include #include -#include #ifdef __cplusplus extern "C" { #endif +/*! +@defgroup api-val Values + +@brief + 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, +\bt_name values are very similar to JSON +values. + +The value API is completely independent from the rest of the +\bt_api. + +\bt_c_comp initialization parameters, \ref bt_query_executor_create() +"query" parameters, as well as trace IR user attributes (for example, +bt_event_class_set_user_attributes()) use values. + +The available value types are: + +
+
Scalar values
+
+ - Null + - Boolean + - Unsigned integer (64-bit range) + - Signed integer (64-bit range) + - Real (\c double range) + - String +
+ +
Container values
+
+ - Array + - Map (string to value) +
+
+ +Values are \ref api-fund-shared-object "shared objects": get a new +reference with bt_value_get_ref() and put an existing reference with +bt_value_put_ref(). + +Some library functions \ref api-fund-freezing "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 \em 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 \em 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: + + + + + + + + + + + +
Name + Type enumerator + Type query function + Creation functions + Writing functions + Reading functions +
\em Null + #BT_VALUE_TYPE_NULL + bt_value_is_null() + \em N/A (use the #bt_value_null variable directly) + \em N/A + \em N/A +
\em Boolean + #BT_VALUE_TYPE_BOOL + bt_value_is_bool() + + bt_value_bool_create()
+ bt_value_bool_create_init() + 		bt_value_bool_set() + bt_value_bool_get() +
Unsigned integer + #BT_VALUE_TYPE_UNSIGNED_INTEGER + bt_value_is_unsigned_integer() + + bt_value_integer_unsigned_create()
+ bt_value_integer_unsigned_create_init() + 		bt_value_integer_unsigned_set() + bt_value_integer_unsigned_get() +
Signed integer + #BT_VALUE_TYPE_SIGNED_INTEGER + bt_value_is_signed_integer() + + bt_value_integer_signed_create()
+ bt_value_integer_signed_create_init() + 		bt_value_integer_signed_set() + bt_value_integer_signed_get() +
\em Real + #BT_VALUE_TYPE_REAL + bt_value_is_real() + + bt_value_real_create()
+ bt_value_real_create_init() + 		bt_value_real_set() + bt_value_real_get() +
\em String + #BT_VALUE_TYPE_STRING + bt_value_is_string() + + bt_value_string_create()
+ bt_value_string_create_init() + 		bt_value_string_set() + bt_value_string_get() +
\em Array + #BT_VALUE_TYPE_ARRAY + bt_value_is_array() + + bt_value_array_create() + + bt_value_array_append_element()
+ bt_value_array_append_bool_element()
+ bt_value_array_append_unsigned_integer_element()
+ bt_value_array_append_signed_integer_element()
+ bt_value_array_append_real_element()
+ bt_value_array_append_string_element()
+ bt_value_array_append_empty_array_element()
+ bt_value_array_append_empty_map_element()
+ bt_value_array_set_element_by_index() + 		+ bt_value_array_get_length()
+ bt_value_array_is_empty()
+ bt_value_array_borrow_element_by_index()
+ bt_value_array_borrow_element_by_index_const() +
\em Map + #BT_VALUE_TYPE_MAP + bt_value_is_map() + + bt_value_map_create() + + bt_value_map_insert_entry()
+ bt_value_map_insert_bool_entry()
+ bt_value_map_insert_unsigned_integer_entry()
+ bt_value_map_insert_signed_integer_entry()
+ bt_value_map_insert_real_entry()
+ bt_value_map_insert_string_entry()
+ bt_value_map_insert_empty_array_entry()
+ bt_value_map_insert_empty_map_entry()
+ bt_value_map_extend() + 		+ bt_value_map_get_size()
+ bt_value_map_is_empty()
+ bt_value_map_has_entry()
+ bt_value_map_borrow_entry_value()
+ bt_value_map_borrow_entry_value_const()
+ bt_value_map_foreach_entry()
+ bt_value_map_foreach_entry_const() +
+*/ + +/*! @{ */ + +/*! +@name Type +@{ + +@typedef struct bt_value bt_value; + +@brief + Value. + +@} +*/ + +/*! +@name Type query +@{ +*/ + +/*! +@brief + Value type enumerators. +*/ +typedef enum bt_value_type { + /*! + @brief + Null value. + */ + BT_VALUE_TYPE_NULL = 1 << 0, + + /*! + @brief + Boolean value. + */ + BT_VALUE_TYPE_BOOL = 1 << 1, + + /*! + @brief + Integer value. + + No value has this type: use it with bt_value_type_is(). + */ + BT_VALUE_TYPE_INTEGER = 1 << 2, + + /*! + @brief + Unsigned integer value. + + This type conceptually inherits #BT_VALUE_TYPE_INTEGER. + */ + BT_VALUE_TYPE_UNSIGNED_INTEGER = (1 << 3) | BT_VALUE_TYPE_INTEGER, + + /*! + @brief + Signed integer value. + + This type conceptually inherits #BT_VALUE_TYPE_INTEGER. + */ + BT_VALUE_TYPE_SIGNED_INTEGER = (1 << 4) | BT_VALUE_TYPE_INTEGER, + + /*! + @brief + Real value. + */ + BT_VALUE_TYPE_REAL = 1 << 5, + + /*! + @brief + String value. + */ + BT_VALUE_TYPE_STRING = 1 << 6, + + /*! + @brief + Array value. + */ + BT_VALUE_TYPE_ARRAY = 1 << 7, + + /*! + @brief + Map value. + */ + BT_VALUE_TYPE_MAP = 1 << 8, +} bt_value_type; + +/*! +@brief + Returns the type enumerator of the value \bt_p{value}. + +@param[in] value + Value of which to get the type enumerator + +@returns + Type enumerator of \bt_p{value}. + +@bt_pre_not_null{value} + +@sa bt_value_type_is() — + Returns whether or not the type of a value conceptually is a given + type. +@sa bt_value_is_null() — + Returns whether or not a value is a null value. +@sa bt_value_is_bool() — + Returns whether or not a value is a boolean value. +@sa bt_value_is_unsigned_integer() — + Returns whether or not a value is an unsigned integer value. +@sa bt_value_is_signed_integer() — + Returns whether or not a value is a signed integer value. +@sa bt_value_is_real() — + Returns whether or not a value is a real value. +@sa bt_value_is_string() — + Returns whether or not a value is a string value. +@sa bt_value_is_array() — + Returns whether or not a value is an array value. +@sa bt_value_is_map() — + Returns whether or not a value is a map value. +*/ +extern bt_value_type bt_value_get_type(const bt_value *value); + +/*! +@brief + Returns whether or not the value type \bt_p{type} conceptually + \em is the value type \bt_p{other_type}. + +For example, an unsigned integer value conceptually \em is an integer +value, so + +@code +bt_value_type_is(BT_VALUE_TYPE_UNSIGNED_INTEGER, BT_VALUE_TYPE_INTEGER) +@endcode + +returns #BT_TRUE. + +@param[in] type + Value type to check against \bt_p{other_type}. +@param[in] other_type + Value type against which to check \bt_p{type}. + +@returns + #BT_TRUE if \bt_p{type} conceptually \em is \bt_p{other_type}. + +@sa bt_value_get_type() — + Returns the type enumerator of a value. +@sa bt_value_is_null() — + Returns whether or not a value is a null value. +@sa bt_value_is_bool() — + Returns whether or not a value is a boolean value. +@sa bt_value_is_unsigned_integer() — + Returns whether or not a value is an unsigned integer value. +@sa bt_value_is_signed_integer() — + Returns whether or not a value is a signed integer value. +@sa bt_value_is_real() — + Returns whether or not a value is a real value. +@sa bt_value_is_string() — + Returns whether or not a value is a string value. +@sa bt_value_is_array() — + Returns whether or not a value is an array value. +@sa bt_value_is_map() — + Returns whether or not a value is a map value. +*/ +static inline +bt_bool bt_value_type_is(const bt_value_type type, + const bt_value_type other_type) +{ + return (type & other_type) == other_type; +} + +/*! +@brief + Returns whether or not the value \bt_p{value} is a null value. + +@note + Because all null values point to the same null value singleton, you + can also directly compare \bt_p{value} to the #bt_value_null + variable. + +@param[in] value + Value to check. + +@returns + #BT_TRUE if \bt_p{value} is a null value. + +@bt_pre_not_null{value} + +@sa bt_value_get_type() — + Returns the type enumerator of a value. +@sa bt_value_type_is() — + Returns whether or not the type of a value conceptually is a given + type. +@sa #bt_value_null — + The null value singleton. +*/ +static inline +bt_bool bt_value_is_null(const bt_value *value) +{ + return bt_value_get_type(value) == BT_VALUE_TYPE_NULL; +} + +/*! +@brief + Returns whether or not the value \bt_p{value} is a boolean value. + +@param[in] value + Value to check. + +@returns + #BT_TRUE if \bt_p{value} is a boolean value. + +@bt_pre_not_null{value} + +@sa bt_value_get_type() — + Returns the type enumerator of a value. +@sa bt_value_type_is() — + Returns whether or not the type of a value conceptually is a given + type. +*/ +static inline +bt_bool bt_value_is_bool(const bt_value *value) +{ + return bt_value_get_type(value) == BT_VALUE_TYPE_BOOL; +} + +/*! +@brief + Returns whether or not the value \bt_p{value} is an unsigned integer + value. + +@param[in] value + Value to check. + +@returns + #BT_TRUE if \bt_p{value} is an unsigned integer value. + +@bt_pre_not_null{value} + +@sa bt_value_get_type() — + Returns the type enumerator of a value. +@sa bt_value_type_is() — + Returns whether or not the type of a value conceptually is a given + type. +*/ +static inline +bt_bool bt_value_is_unsigned_integer(const bt_value *value) +{ + return bt_value_get_type(value) == BT_VALUE_TYPE_UNSIGNED_INTEGER; +} + +/*! +@brief + Returns whether or not the value \bt_p{value} is a signed integer + value. + +@param[in] value + Value to check. + +@returns + #BT_TRUE if \bt_p{value} is a signed integer value. + +@bt_pre_not_null{value} + +@sa bt_value_get_type() — + Returns the type enumerator of a value. +@sa bt_value_type_is() — + Returns whether or not the type of a value conceptually is a given + type. +*/ +static inline +bt_bool bt_value_is_signed_integer(const bt_value *value) +{ + return bt_value_get_type(value) == BT_VALUE_TYPE_SIGNED_INTEGER; +} + +/*! +@brief + Returns whether or not the value \bt_p{value} is a real value. + +@param[in] value + Value to check. + +@returns + #BT_TRUE if \bt_p{value} is a real value. + +@bt_pre_not_null{value} + +@sa bt_value_get_type() — + Returns the type enumerator of a value. +@sa bt_value_type_is() — + Returns whether or not the type of a value conceptually is a given + type. +*/ +static inline +bt_bool bt_value_is_real(const bt_value *value) +{ + return bt_value_get_type(value) == BT_VALUE_TYPE_REAL; +} + +/*! +@brief + Returns whether or not the value \bt_p{value} is a string value. + +@param[in] value + Value to check. + +@returns + #BT_TRUE if \bt_p{value} is a string value. + +@bt_pre_not_null{value} + +@sa bt_value_get_type() — + Returns the type enumerator of a value. +@sa bt_value_type_is() — + Returns whether or not the type of a value conceptually is a given + type. +*/ +static inline +bt_bool bt_value_is_string(const bt_value *value) +{ + return bt_value_get_type(value) == BT_VALUE_TYPE_STRING; +} + +/*! +@brief + Returns whether or not the value \bt_p{value} is an array value. + +@param[in] value + Value to check. + +@returns + #BT_TRUE if \bt_p{value} is an array value. + +@bt_pre_not_null{value} + +@sa bt_value_get_type() — + Returns the type enumerator of a value. +@sa bt_value_type_is() — + Returns whether or not the type of a value conceptually is a given + type. +*/ +static inline +bt_bool bt_value_is_array(const bt_value *value) +{ + return bt_value_get_type(value) == BT_VALUE_TYPE_ARRAY; +} + +/*! +@brief + Returns whether or not the value \bt_p{value} is a map value. + +@param[in] value + Value to check. + +@returns + #BT_TRUE if \bt_p{value} is a map value. + +@bt_pre_not_null{value} + +@sa bt_value_get_type() — + Returns the type enumerator of a value. +@sa bt_value_type_is() — + Returns whether or not the type of a value conceptually is a given + type. +*/ +static inline +bt_bool bt_value_is_map(const bt_value *value) +{ + return bt_value_get_type(value) == BT_VALUE_TYPE_MAP; +} + +/*! @} */ + +/*! +@name Null value +@{ +*/ + +/*! +@brief + The null value singleton. + +This is the \em 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 \c bt_value_null variable. + +@attention + @parblock + \c bt_value_null is different from \c NULL: the former is a true + \bt_name value object while the latter is a C definition which + usually means "no pointer". + + For example, bt_value_map_borrow_entry_value() can return + \c bt_value_null if the requested key is mapped to a null value, but + it can also return \c NULL if the key is not found. + @endparblock + +@sa bt_value_is_null() — + Returns whether or not a value is a null value. +*/ extern bt_value *const bt_value_null; +/*! @} */ + +/*! +@name Boolean value +@{ +*/ + +/*! +@brief + Creates and returns a boolean value initialized to #BT_FALSE. + +The returned value has the type #BT_VALUE_TYPE_BOOL. + +@returns + New boolean value reference, or \c NULL on memory error. + +@sa bt_value_bool_create_init() — + Creates a boolean value with a given initial raw value. +*/ extern bt_value *bt_value_bool_create(void); -extern bt_value *bt_value_bool_create_init(bt_bool val); +/*! +@brief + Creates and returns a boolean value initialized to \bt_p{raw_value}. + +The returned value has the type #BT_VALUE_TYPE_BOOL. + +@param[in] raw_value + Initial raw value of the boolean value to create. + +@returns + New boolean value reference, or \c NULL on memory error. + +@sa bt_value_bool_create() — + Creates a boolean value initialized to #BT_FALSE. +*/ +extern bt_value *bt_value_bool_create_init(bt_bool raw_value); + +/*! +@brief + Sets the raw value of the boolean value \bt_p{value} to + \bt_p{raw_value}. + +@param[in] value + Boolean value of which to set the raw value to \bt_p{raw_value}. +@param[in] raw_value + New raw value of \bt_p{value}. -extern void bt_value_bool_set(bt_value *bool_obj, bt_bool val); +@bt_pre_not_null{value} +@bt_pre_is_bool_val{value} +@bt_pre_hot{value} +@sa bt_value_bool_get() — + Returns the raw value of a boolean value. +*/ +extern void bt_value_bool_set(bt_value *value, bt_bool raw_value); + +/*! +@brief + Returns the raw value of the boolean value \bt_p{value}. + +@param[in] value + Boolean value of which to get the raw value. + +@returns + Raw value of \bt_p{value}. + +@bt_pre_not_null{value} +@bt_pre_is_bool_val{value} + +@sa bt_value_bool_set() — + Sets the raw value of a boolean value. +*/ +extern bt_bool bt_value_bool_get(const bt_value *value); + +/*! @} */ + +/*! +@name Unsigned integer value +@{ +*/ + +/*! +@brief + Creates and returns an unsigned integer value initialized to 0. + +The returned value has the type #BT_VALUE_TYPE_UNSIGNED_INTEGER. + +@returns + New unsigned integer value reference, or \c NULL on memory error. + +@sa bt_value_integer_unsigned_create_init() — + Creates an unsigned integer value with a given initial raw value. +*/ extern bt_value *bt_value_integer_unsigned_create(void); -extern bt_value *bt_value_integer_unsigned_create_init(uint64_t val); +/*! +@brief + Creates and returns an unsigned integer value initialized to + \bt_p{raw_value}. + +The returned value has the type #BT_VALUE_TYPE_UNSIGNED_INTEGER. + +@param[in] raw_value + Initial raw value of the unsigned integer value to create. + +@returns + New unsigned integer value reference, or \c NULL on memory error. + +@sa bt_value_bool_create() — + Creates an unsigned integer value initialized to 0. +*/ +extern bt_value *bt_value_integer_unsigned_create_init(uint64_t raw_value); -extern void bt_value_integer_unsigned_set(bt_value *integer_obj, uint64_t val); +/*! +@brief + Sets the raw value of the unsigned integer value \bt_p{value} to + \bt_p{raw_value}. +@param[in] value + Unsigned integer value of which to set the raw value to + \bt_p{raw_value}. +@param[in] raw_value + New raw value of \bt_p{value}. + +@bt_pre_not_null{value} +@bt_pre_is_uint_val{value} +@bt_pre_hot{value} + +@sa bt_value_integer_unsigned_get() — + Returns the raw value of an unsigned integer value. +*/ +extern void bt_value_integer_unsigned_set(bt_value *value, + uint64_t raw_value); + +/*! +@brief + Returns the raw value of the unsigned integer value \bt_p{value}. + +@param[in] value + Unsigned integer value of which to get the raw value. + +@returns + Raw value of \bt_p{value}. + +@bt_pre_not_null{value} +@bt_pre_is_uint_val{value} + +@sa bt_value_integer_unsigned_set() — + Sets the raw value of an unsigned integer value. +*/ +extern uint64_t bt_value_integer_unsigned_get(const bt_value *value); + +/*! @} */ + +/*! +@name Signed integer value +@{ +*/ + +/*! +@brief + Creates and returns a signed integer value initialized to 0. + +The returned value has the type #BT_VALUE_TYPE_SIGNED_INTEGER. + +@returns + New signed integer value reference, or \c NULL on memory error. + +@sa bt_value_integer_signed_create_init() — + Creates a signed integer value with a given initial raw value. +*/ extern bt_value *bt_value_integer_signed_create(void); -extern bt_value *bt_value_integer_signed_create_init(int64_t val); +/*! +@brief + Creates and returns a signed integer value initialized to + \bt_p{raw_value}. + +The returned value has the type #BT_VALUE_TYPE_SIGNED_INTEGER. + +@param[in] raw_value + Initial raw value of the signed integer value to create. -extern void bt_value_integer_signed_set(bt_value *integer_obj, int64_t val); +@returns + New signed integer value reference, or \c NULL on memory error. +@sa bt_value_bool_create() — + Creates a signed integer value initialized to 0. +*/ +extern bt_value *bt_value_integer_signed_create_init(int64_t raw_value); + +/*! +@brief + Sets the raw value of the signed integer value \bt_p{value} to + \bt_p{raw_value}. + +@param[in] value + Signed integer value of which to set the raw value to + \bt_p{raw_value}. +@param[in] raw_value + New raw value of \bt_p{value}. + +@bt_pre_not_null{value} +@bt_pre_is_sint_val{value} +@bt_pre_hot{value} + +@sa bt_value_integer_signed_get() — + Returns the raw value of a signed integer value. +*/ +extern void bt_value_integer_signed_set(bt_value *value, int64_t raw_value); + +/*! +@brief + Returns the raw value of the signed integer value \bt_p{value}. + +@param[in] value + Signed integer value of which to get the raw value. + +@returns + Raw value of \bt_p{value}. + +@bt_pre_not_null{value} +@bt_pre_is_sint_val{value} + +@sa bt_value_integer_signed_set() — + Sets the raw value of a signed integer value. +*/ +extern int64_t bt_value_integer_signed_get(const bt_value *value); + +/*! @} */ + +/*! +@name Real value +@{ +*/ + +/*! +@brief + Creates and returns a real value initialized to 0. + +The returned value has the type #BT_VALUE_TYPE_REAL. + +@returns + New real value reference, or \c NULL on memory error. + +@sa bt_value_real_create_init() — + Creates a real value with a given initial raw value. +*/ extern bt_value *bt_value_real_create(void); -extern bt_value *bt_value_real_create_init(double val); +/*! +@brief + Creates and returns a real value initialized to \bt_p{raw_value}. + +The returned value has the type #BT_VALUE_TYPE_REAL. + +@param[in] raw_value + Initial raw value of the real value to create. + +@returns + New real value reference, or \c NULL on memory error. + +@sa bt_value_real_create() — + Creates a real value initialized to 0. +*/ +extern bt_value *bt_value_real_create_init(double raw_value); + +/*! +@brief + Sets the raw value of the real value \bt_p{value} to + \bt_p{raw_value}. + +@param[in] value + Real value of which to set the raw value to \bt_p{raw_value}. +@param[in] raw_value + New raw value of \bt_p{value}. + +@bt_pre_not_null{value} +@bt_pre_is_real_val{value} +@bt_pre_hot{value} + +@sa bt_value_real_get() — + Returns the raw value of a real value. +*/ +extern void bt_value_real_set(bt_value *value, double raw_value); + +/*! +@brief + Returns the raw value of the real value \bt_p{value}. + +@param[in] value + Real value of which to get the raw value. + +@returns + Raw value of \bt_p{value}. + +@bt_pre_not_null{value} +@bt_pre_is_real_val{value} + +@sa bt_value_real_set() — + Sets the raw value of a real value. +*/ +extern double bt_value_real_get(const bt_value *value); + +/*! @} */ + +/*! +@name String value +@{ +*/ -extern void bt_value_real_set(bt_value *real_obj, double val); +/*! +@brief + Creates and returns an empty string value. +The returned value has the type #BT_VALUE_TYPE_STRING. + +@returns + New string value reference, or \c NULL on memory error. + +@sa bt_value_string_create_init() — + Creates a string value with a given initial raw value. +*/ extern bt_value *bt_value_string_create(void); -extern bt_value *bt_value_string_create_init(const char *val); +/*! +@brief + Creates and returns a string value initialized to a copy of + \bt_p{raw_value}. + +The returned value has the type #BT_VALUE_TYPE_STRING. + +@param[in] raw_value + Initial raw value of the string value to create (copied). +@returns + New string value reference, or \c NULL on memory error. + +@bt_pre_not_null{raw_value} + +@sa bt_value_string_create() — + Creates an empty string value. +*/ +extern bt_value *bt_value_string_create_init(const char *raw_value); + +/*! +@brief + Status codes for bt_value_string_set(). +*/ typedef enum bt_value_string_set_status { - BT_VALUE_STRING_SET_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, + /*! + @brief + Success. + */ BT_VALUE_STRING_SET_STATUS_OK = __BT_FUNC_STATUS_OK, + + /*! + @brief + Out of memory. + */ + BT_VALUE_STRING_SET_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, } bt_value_string_set_status; -extern bt_value_string_set_status bt_value_string_set(bt_value *string_obj, - const char *val); +/*! +@brief + Sets the raw value of the string value \bt_p{value} to a copy of + \bt_p{raw_value}. -extern bt_value *bt_value_array_create(void); +@param[in] value + String value of which to set the raw value to a copy of + \bt_p{raw_value}. +@param[in] raw_value + New raw value of \bt_p{value} (copied). -extern bt_value *bt_value_array_borrow_element_by_index(bt_value *array_obj, - uint64_t index); +@retval #BT_VALUE_STRING_SET_STATUS_OK + Success. +@retval #BT_VALUE_STRING_SET_STATUS_MEMORY_ERROR + Out of memory. + +@bt_pre_not_null{value} +@bt_pre_is_string_val{value} +@bt_pre_hot{value} +@bt_pre_not_null{raw_value} + +@sa bt_value_string_get() — + Returns the raw value of a string value. +*/ +extern bt_value_string_set_status bt_value_string_set(bt_value *value, + const char *raw_value); + +/*! +@brief + Returns the raw value of the string value \bt_p{value}. +@param[in] value + String value of which to get the raw value. + +@returns + @parblock + Raw value of \bt_p{value}. + + The returned pointer remains valid until \bt_p{value} is modified. + @endparblock + +@bt_pre_not_null{value} +@bt_pre_is_string_val{value} + +@sa bt_value_string_set() — + Sets the raw value of a string value. +*/ +extern const char *bt_value_string_get(const bt_value *value); + +/*! @} */ + +/*! +@name Array value +@{ +*/ + +/*! +@brief + Creates and returns an empty array value. + +The returned value has the type #BT_VALUE_TYPE_ARRAY. + +@returns + New array value reference, or \c NULL on memory error. +*/ +extern bt_value *bt_value_array_create(void); + +/*! +@brief + Status codes for the bt_value_array_append_*() + functions. +*/ typedef enum bt_value_array_append_element_status { - BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, + /*! + @brief + Success. + */ BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK = __BT_FUNC_STATUS_OK, + + /*! + @brief + Out of memory. + */ + BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, } bt_value_array_append_element_status; +/*! +@brief + Appends the value \bt_p{element_value} to the array value \bt_p{value}. + +To append a null value, pass #bt_value_null as \bt_p{element_value}. + +@param[in] value + Array value to which to append \bt_p{element_value}. +@param[in] element_value + Value to append to \bt_p{value}. + +@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK + Success. +@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR + Out of memory. + +@bt_pre_not_null{value} +@bt_pre_is_array_val{value} +@bt_pre_hot{value} +@bt_pre_not_null{element_value} +@pre + \bt_p{element_value} does not contain \bt_p{value}, recursively. + +@post + On success, the length of \bt_p{value} is + incremented. + +@sa bt_value_array_append_bool_element() — + Creates and appends a boolean value to an array value. +@sa bt_value_array_append_unsigned_integer_element() — + Creates and appends an unsigned integer value to an array value. +@sa bt_value_array_append_signed_integer_element() — + Creates and appends a signed integer value to an array value. +@sa bt_value_array_append_real_element() — + Creates and appends a real value to an array value. +@sa bt_value_array_append_string_element() — + Creates and appends a string value to an array value. +@sa bt_value_array_append_empty_array_element() — + Creates and appends an empty array value to an array value. +@sa bt_value_array_append_empty_map_element() — + Creates and appends an empty map value to an array value. +*/ extern bt_value_array_append_element_status bt_value_array_append_element( - bt_value *array_obj, bt_value *element_obj); + bt_value *value, bt_value *element_value); + +/*! +@brief + Creates a boolean value initialized to \bt_p{raw_value} and appends + it to the array value \bt_p{value}. + +@param[in] value + Array value to which to append the created boolean value. +@param[in] raw_value + Raw value of the boolean value to create and append to \bt_p{value}. + +@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK + Success. +@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR + Out of memory. +@bt_pre_not_null{value} +@bt_pre_is_array_val{value} +@bt_pre_hot{value} + +@post + On success, the length of \bt_p{value} is + incremented. + +@sa bt_value_array_append_element() — + Appends an existing value to an array value. +*/ extern bt_value_array_append_element_status -bt_value_array_append_bool_element(bt_value *array_obj, bt_bool val); +bt_value_array_append_bool_element(bt_value *value, bt_bool raw_value); + +/*! +@brief + Creates an unsigned integer value initialized to \bt_p{raw_value} + and appends it to the array value \bt_p{value}. + +@param[in] value + Array value to which to append the created unsigned integer value. +@param[in] raw_value + Raw value of the unsigned integer value to create and append to + \bt_p{value}. + +@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK + Success. +@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR + Out of memory. + +@bt_pre_not_null{value} +@bt_pre_is_array_val{value} +@bt_pre_hot{value} + +@post + On success, the length of \bt_p{value} is + incremented. +@sa bt_value_array_append_element() — + Appends an existing value to an array value. +*/ extern bt_value_array_append_element_status -bt_value_array_append_unsigned_integer_element(bt_value *array_obj, - uint64_t val); +bt_value_array_append_unsigned_integer_element(bt_value *value, + uint64_t raw_value); +/*! +@brief + Creates a signed integer value initialized to \bt_p{raw_value} and + appends it to the array value \bt_p{value}. + +@param[in] value + Array value to which to append the created signed integer value. +@param[in] raw_value + Raw value of the signed integer value to create and append to + \bt_p{value}. + +@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK + Success. +@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR + Out of memory. + +@bt_pre_not_null{value} +@bt_pre_is_array_val{value} +@bt_pre_hot{value} + +@post + On success, the length of \bt_p{value} is + incremented. + +@sa bt_value_array_append_element() — + Appends an existing value to an array value. +*/ extern bt_value_array_append_element_status -bt_value_array_append_signed_integer_element(bt_value *array_obj, int64_t val); +bt_value_array_append_signed_integer_element(bt_value *value, + int64_t raw_value); + +/*! +@brief + Creates a real value initialized to \bt_p{raw_value} and appends + it to the array value \bt_p{value}. + +@param[in] value + Array value to which to append the created real value. +@param[in] raw_value + Raw value of the real value to create and append to \bt_p{value}. +@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK + Success. +@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR + Out of memory. + +@bt_pre_not_null{value} +@bt_pre_is_array_val{value} +@bt_pre_hot{value} + +@post + On success, the length of \bt_p{value} is + incremented. + +@sa bt_value_array_append_element() — + Appends an existing value to an array value. +*/ extern bt_value_array_append_element_status -bt_value_array_append_real_element(bt_value *array_obj, double val); +bt_value_array_append_real_element(bt_value *value, double raw_value); + +/*! +@brief + Creates a string value initialized to a copy of \bt_p{raw_value} and + appends it to the array value \bt_p{value}. + +@param[in] value + Array value to which to append the created string value. +@param[in] raw_value + Raw value of the string value to create and append to \bt_p{value} + (copied). + +@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK + Success. +@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR + Out of memory. + +@bt_pre_not_null{value} +@bt_pre_is_array_val{value} +@bt_pre_hot{value} +@post + On success, the length of \bt_p{value} is + incremented. + +@sa bt_value_array_append_element() — + Appends an existing value to an array value. +*/ extern bt_value_array_append_element_status -bt_value_array_append_string_element(bt_value *array_obj, const char *val); +bt_value_array_append_string_element(bt_value *value, const char *raw_value); + +/*! +@brief + Creates an empty array value and appends it to the array + value \bt_p{value}. + +On success, if \bt_p{element_value} is not \c NULL, this function sets +\bt_p{*element_value} to a \em borrowed reference of the created empty +array value. + +@param[in] value + Array value to which to append the created empty array value. +@param[out] element_value + On success, if not \c NULL, \bt_p{*element_value} + is a \em borrowed reference of the created empty array value. +@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK + Success. +@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR + Out of memory. + +@bt_pre_not_null{value} +@bt_pre_is_array_val{value} +@bt_pre_hot{value} + +@post + On success, the length of \bt_p{value} is + incremented. + +@sa bt_value_array_append_element() — + Appends an existing value to an array value. +*/ extern bt_value_array_append_element_status -bt_value_array_append_empty_array_element(bt_value *array_obj, - bt_value **element_obj); +bt_value_array_append_empty_array_element(bt_value *value, + bt_value **element_value); + +/*! +@brief + Creates an empty map value and appends it to the array + value \bt_p{value}. +On success, if \bt_p{element_value} is not \c NULL, this function sets +\bt_p{*element_value} to a \em borrowed reference of the created empty +map value. + +@param[in] value + Array value to which to append the created empty array value. +@param[out] element_value + On success, if not \c NULL, \bt_p{*element_value} + is a \em borrowed reference of the created empty map value. + +@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK + Success. +@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR + Out of memory. + +@bt_pre_not_null{value} +@bt_pre_is_array_val{value} +@bt_pre_hot{value} + +@post + On success, the length of \bt_p{value} is + incremented. + +@sa bt_value_array_append_element() — + Appends an existing value to an array value. +*/ extern bt_value_array_append_element_status -bt_value_array_append_empty_map_element(bt_value *array_obj, - bt_value **element_obj); +bt_value_array_append_empty_map_element(bt_value *value, + bt_value **element_value); +/*! +@brief + Status codes for bt_value_array_set_element_by_index(). +*/ typedef enum bt_value_array_set_element_by_index_status { - BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, + /*! + @brief + Success. + */ BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_OK = __BT_FUNC_STATUS_OK, + + /*! + @brief + Out of memory. + */ + BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, } bt_value_array_set_element_by_index_status; +/*! +@brief + Sets the element of the array value \bt_p{value} at index + \bt_p{index} to the value \bt_p{element_value}. + +On success, this function replaces the existing element of \bt_p{value} +at index \bt_p{index}. + +@param[in] value + Array value of which to set the element at index \bt_p{index}. +@param[in] index + Index of the element to set in \bt_p{value}. +@param[in] element_value + Value to set as the element of \bt_p{value} at index \bt_p{index}. + +@retval #BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_OK + Success. +@retval #BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_MEMORY_ERROR + Out of memory. + +@bt_pre_not_null{value} +@bt_pre_is_array_val{value} +@bt_pre_hot{value} +@pre + \bt_p{index} is less than the length of \bt_p{value} (as returned by + bt_value_array_get_length()). +@bt_pre_not_null{element_value} +@pre + \bt_p{element_value} does not contain \bt_p{value}, recursively. + +@post + On success, the length of \bt_p{value} is + incremented. + +@sa bt_value_array_append_element() — + Appends a value to an array value. +*/ extern bt_value_array_set_element_by_index_status -bt_value_array_set_element_by_index(bt_value *array_obj, uint64_t index, - bt_value *element_obj); +bt_value_array_set_element_by_index(bt_value *value, uint64_t index, + bt_value *element_value); + +/*! +@brief + Borrows the element at index \bt_p{index} from the array value + \bt_p{value}. + +@param[in] value + Array value from which to borrow the element at index \bt_p{index}. +@param[in] index + Index of the element to borrow from \bt_p{value}. + +@returns + @parblock + \em Borrowed reference of the element of \bt_p{value} at index + \bt_p{index}. + + The returned pointer remains valid until \bt_p{value} is modified. + @endparblock + +@bt_pre_not_null{value} +@bt_pre_is_array_val{value} +@pre + \bt_p{index} is less than the length of \bt_p{value} (as returned by + bt_value_array_get_length()). + +@sa bt_value_array_borrow_element_by_index_const() — + \c const version of this function. +*/ +extern bt_value *bt_value_array_borrow_element_by_index(bt_value *value, + uint64_t index); + +/*! +@brief + Borrows the element at index \bt_p{index} from the array value + \bt_p{value} (\c const version). +See bt_value_array_borrow_element_by_index(). +*/ +extern const bt_value *bt_value_array_borrow_element_by_index_const( + const bt_value *value, uint64_t index); + +/*! +@brief + Returns the length of the array value \bt_p{value}. + +@param[in] value + Array value of which to get the length. + +@returns + Length (number of contained elements) of \bt_p{value}. + +@bt_pre_not_null{value} +@bt_pre_is_array_val{value} + +@sa bt_value_array_is_empty() — + Returns whether or not an array value is empty. +*/ +extern uint64_t bt_value_array_get_length(const bt_value *value); + +/*! +@brief + Returns whether or not the array value \bt_p{value} is empty. + +@param[in] value + Array value to check. + +@returns + #BT_TRUE if \bt_p{value} is empty (has the length 0). + +@bt_pre_not_null{value} +@bt_pre_is_array_val{value} + +@sa bt_value_array_get_length() — + Returns the length of an array value. +*/ +static inline +bt_bool bt_value_array_is_empty(const bt_value *value) +{ + return bt_value_array_get_length(value) == 0; +} + +/*! @} */ + +/*! +@name Map value +@{ +*/ + +/*! +@brief + Creates and returns an empty map value. + +The returned value has the type #BT_VALUE_TYPE_MAP. + +@returns + New map value reference, or \c NULL on memory error. +*/ extern bt_value *bt_value_map_create(void); +/*! +@brief + Status codes for the bt_value_map_insert_*() functions. +*/ +typedef enum bt_value_map_insert_entry_status { + /*! + @brief + Success. + */ + BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK = __BT_FUNC_STATUS_OK, + + /*! + @brief + Out of memory. + */ + BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, +} bt_value_map_insert_entry_status; + +/*! +@brief + Inserts or replaces an entry with the key \bt_p{key} and the value + \bt_p{entry_value} in the map value \bt_p{value}. + +To insert an entry having a null value, pass #bt_value_null as +\bt_p{entry_value}. + +On success, if \bt_p{value} already contains an entry with key +\bt_p{key}, this function replaces the existing entry's value with +\bt_p{entry_value}. + +@param[in] value + Map value in which to insert or replace an entry with key \bt_p{key} + and value \bt_p{entry_value}. +@param[in] key + Key of the entry to insert or replace in \bt_p{value} (copied). +@param[in] entry_value + Value of the entry to insert or replace in \bt_p{value}. + +@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK + Success. +@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR + Out of memory. + +@bt_pre_not_null{value} +@bt_pre_is_map_val{value} +@bt_pre_hot{value} +@bt_pre_not_null{key} +@bt_pre_not_null{entry_value} +@pre + \bt_p{entry_value} does not contain \bt_p{value}, recursively. + +@sa bt_value_map_insert_bool_entry() — + Creates a boolean value and uses it to insert an entry in a map + value. +@sa bt_value_map_insert_unsigned_integer_entry() — + Creates an unsigned integer value and uses it to insert an entry in + a map value. +@sa bt_value_map_insert_signed_integer_entry() — + Creates a signed value and uses it to insert an entry in a map + value. +@sa bt_value_map_insert_real_entry() — + Creates a real value and uses it to insert an entry in a map value. +@sa bt_value_map_insert_string_entry() — + Creates a string value and uses it to insert an entry in a map + value. +@sa bt_value_map_insert_empty_array_entry() — + Creates an empty array value and uses it to insert an entry in a map + value. +@sa bt_value_map_insert_empty_map_entry() — + Creates a map value and uses it to insert an entry in a map value. +*/ +extern bt_value_map_insert_entry_status bt_value_map_insert_entry( + bt_value *value, const char *key, bt_value *entry_value); + +/*! +@brief + Creates a boolean value initialized to \bt_p{raw_value} and + inserts or replaces an entry with the key \bt_p{key} and this value + in the map value \bt_p{value}. + +On success, if \bt_p{value} already contains an entry with key +\bt_p{key}, this function replaces the existing entry's value with the +created boolean value. + +@param[in] value + Map value in which to insert or replace an entry with key \bt_p{key} + and the created boolean value. +@param[in] key + Key of the entry to insert or replace in \bt_p{value} (copied). +@param[in] raw_value + Initial raw value of the boolean value to create. + +@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK + Success. +@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR + Out of memory. + +@bt_pre_not_null{value} +@bt_pre_is_map_val{value} +@bt_pre_hot{value} +@bt_pre_not_null{key} + +@sa bt_value_map_insert_entry() — + Inserts an entry with an existing value in a map value. +*/ +extern bt_value_map_insert_entry_status bt_value_map_insert_bool_entry( + bt_value *value, const char *key, bt_bool raw_value); + +/*! +@brief + Creates an unsigned integer value initialized to \bt_p{raw_value} + and inserts or replaces an entry with the key \bt_p{key} and this + value in the map value \bt_p{value}. + +On success, if \bt_p{value} already contains an entry with key +\bt_p{key}, this function replaces the existing entry's value with the +created unsigned integer value. + +@param[in] value + Map value in which to insert or replace an entry with key \bt_p{key} + and the created unsigned integer value. +@param[in] key + Key of the entry to insert or replace in \bt_p{value} (copied). +@param[in] raw_value + Initial raw value of the unsigned integer value to create. + +@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK + Success. +@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR + Out of memory. + +@bt_pre_not_null{value} +@bt_pre_is_map_val{value} +@bt_pre_hot{value} +@bt_pre_not_null{key} + +@sa bt_value_map_insert_entry() — + Inserts an entry with an existing value in a map value. +*/ +extern bt_value_map_insert_entry_status +bt_value_map_insert_unsigned_integer_entry(bt_value *value, const char *key, + uint64_t raw_value); + +/*! +@brief + Creates a signed integer value initialized to \bt_p{raw_value} and + inserts or replaces an entry with the key \bt_p{key} and this value + in the map value \bt_p{value}. + +On success, if \bt_p{value} already contains an entry with key +\bt_p{key}, this function replaces the existing entry's value with the +created signed integer value. + +@param[in] value + Map value in which to insert or replace an entry with key \bt_p{key} + and the created signed integer value. +@param[in] key + Key of the entry to insert or replace in \bt_p{value} (copied). +@param[in] raw_value + Initial raw value of the signed integer value to create. + +@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK + Success. +@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR + Out of memory. + +@bt_pre_not_null{value} +@bt_pre_is_map_val{value} +@bt_pre_hot{value} +@bt_pre_not_null{key} + +@sa bt_value_map_insert_entry() — + Inserts an entry with an existing value in a map value. +*/ +extern bt_value_map_insert_entry_status +bt_value_map_insert_signed_integer_entry(bt_value *value, const char *key, + int64_t raw_value); + +/*! +@brief + Creates a real value initialized to \bt_p{raw_value} and inserts or + replaces an entry with the key \bt_p{key} and this value in the map + value \bt_p{value}. + +On success, if \bt_p{value} already contains an entry with key +\bt_p{key}, this function replaces the existing entry's value with the +created real value. + +@param[in] value + Map value in which to insert or replace an entry with key \bt_p{key} + and the created real value. +@param[in] key + Key of the entry to insert or replace in \bt_p{value} (copied). +@param[in] raw_value + Initial raw value of the real value to create. + +@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK + Success. +@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR + Out of memory. + +@bt_pre_not_null{value} +@bt_pre_is_map_val{value} +@bt_pre_hot{value} +@bt_pre_not_null{key} + +@sa bt_value_map_insert_entry() — + Inserts an entry with an existing value in a map value. +*/ +extern bt_value_map_insert_entry_status bt_value_map_insert_real_entry( + bt_value *value, const char *key, double raw_value); + +/*! +@brief + Creates a string value initialized to a copy of \bt_p{raw_value} and + inserts or replaces an entry with the key \bt_p{key} and this value + in the map value \bt_p{value}. + +On success, if \bt_p{value} already contains an entry with key +\bt_p{key}, this function replaces the existing entry's value with the +created string value. + +@param[in] value + Map value in which to insert or replace an entry with key \bt_p{key} + and the created string value. +@param[in] key + Key of the entry to insert or replace in \bt_p{value} (copied). +@param[in] raw_value + Initial raw value of the string value to create (copied). + +@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK + Success. +@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR + Out of memory. + +@bt_pre_not_null{value} +@bt_pre_is_map_val{value} +@bt_pre_hot{value} +@bt_pre_not_null{key} + +@sa bt_value_map_insert_entry() — + Inserts an entry with an existing value in a map value. +*/ +extern bt_value_map_insert_entry_status +bt_value_map_insert_string_entry(bt_value *value, const char *key, + const char *raw_value); + +/*! +@brief + Creates an empty array value and inserts or replaces an entry with + the key \bt_p{key} and this value in the map value \bt_p{value}. + +On success, if \bt_p{entry_value} is not \c NULL, this function sets +\bt_p{*entry_value} to a \em borrowed reference of the created empty +array value. + +On success, if \bt_p{value} already contains an entry with key +\bt_p{key}, this function replaces the existing entry's value with the +created empty array value. + +@param[in] value + Map value in which to insert or replace an entry with key \bt_p{key} + and the created empty array value. +@param[in] key + Key of the entry to insert or replace in \bt_p{value} (copied). +@param[out] entry_value + On success, if not \c NULL, \bt_p{*entry_value} is + a \em borrowed reference of the created empty array value. + +@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK + Success. +@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR + Out of memory. + +@bt_pre_not_null{value} +@bt_pre_is_map_val{value} +@bt_pre_hot{value} +@bt_pre_not_null{key} + +@sa bt_value_map_insert_entry() — + Inserts an entry with an existing value in a map value. +*/ +extern bt_value_map_insert_entry_status +bt_value_map_insert_empty_array_entry(bt_value *value, const char *key, + bt_value **entry_value); + +/*! +@brief + Creates an empty map value and inserts or replaces an entry with + the key \bt_p{key} and this value in the map value \bt_p{value}. + +On success, if \bt_p{entry_value} is not \c NULL, this function sets +\bt_p{*entry_value} to a \em borrowed reference of the created empty map +value. + +On success, if \bt_p{value} already contains an entry with key +\bt_p{key}, this function replaces the existing entry's value with the +created empty map value. + +@param[in] value + Map value in which to insert or replace an entry with key \bt_p{key} + and the created empty map value. +@param[in] key + Key of the entry to insert or replace in \bt_p{value} (copied). +@param[out] entry_value + On success, if not \c NULL, \bt_p{*entry_value} is + a \em borrowed reference of the created empty map value. + +@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK + Success. +@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR + Out of memory. + +@bt_pre_not_null{value} +@bt_pre_is_map_val{value} +@bt_pre_hot{value} +@bt_pre_not_null{key} + +@sa bt_value_map_insert_entry() — + Inserts an entry with an existing value in a map value. +*/ +extern bt_value_map_insert_entry_status +bt_value_map_insert_empty_map_entry(bt_value *value, const char *key, + bt_value **entry_value); + +/*! +@brief + Borrows the value of the entry with the key \bt_p{key} in the map + value \bt_p{value}. + +If no entry with key \bt_p{key} exists in \bt_p{value}, this function +returns \c NULL. + +@param[in] value + Map value from which to borrow the value of the entry with the + key \bt_p{key}. +@param[in] key + Key of the entry from which to borrow the value in \bt_p{value}. + +@returns + @parblock + \em Borrowed reference of the value of the entry with key \bt_p{key} + in \bt_p{value}, or \c NULL if none. + + The returned pointer remains valid until \bt_p{value} is modified. + @endparblock + +@bt_pre_not_null{value} +@bt_pre_is_array_val{value} +@bt_pre_not_null{key} + +@sa bt_value_map_borrow_entry_value_const() — + \c const version of this function. +@sa bt_value_map_has_entry() — + Returns whether or not a map value has an entry with a given key. +*/ extern bt_value *bt_value_map_borrow_entry_value( - bt_value *map_obj, const char *key); + bt_value *value, const char *key); + +/*! +@brief + Borrows the value of the entry with the key \bt_p{key} in the map + value \bt_p{value} (\c const version). + +See bt_value_map_borrow_entry_value(). +*/ +extern const bt_value *bt_value_map_borrow_entry_value_const( + const bt_value *value, const char *key); +/*! +@brief + Status codes for #bt_value_map_foreach_entry_func. +*/ typedef enum bt_value_map_foreach_entry_func_status { + /*! + @brief + Success. + */ BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_OK = __BT_FUNC_STATUS_OK, - BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, - BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, + + /*! + @brief + Interrupt the iteration process. + */ BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_INTERRUPT = __BT_FUNC_STATUS_INTERRUPTED, + + /*! + @brief + Out of memory. + */ + BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, + + /*! + @brief + User error. + */ + BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, } bt_value_map_foreach_entry_func_status; +/*! +@brief + 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. + +@param[in] key + Key of the map value entry. +@param[in] value + Value of the map value entry. +@param[in] user_data + User data, as passed as the \bt_p{user_data} parameter of + bt_value_map_foreach_entry(). + +@retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_OK + Success. +@retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_INTERRUPT + Interrupt the iteration process. +@retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_MEMORY_ERROR + Out of memory. +@retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_ERROR + User error. + +@bt_pre_not_null{key} +@bt_pre_not_null{value} + +@sa bt_value_map_foreach_entry() — + Iterates the entries of a map value. +*/ typedef bt_value_map_foreach_entry_func_status (* bt_value_map_foreach_entry_func)(const char *key, - bt_value *object, void *data); + bt_value *value, void *user_data); +/*! +@brief + Status codes for bt_value_map_foreach_entry(). +*/ typedef enum bt_value_map_foreach_entry_status { + /*! + @brief + Success. + */ BT_VALUE_MAP_FOREACH_ENTRY_STATUS_OK = __BT_FUNC_STATUS_OK, - BT_VALUE_MAP_FOREACH_ENTRY_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, - BT_VALUE_MAP_FOREACH_ENTRY_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, - BT_VALUE_MAP_FOREACH_ENTRY_STATUS_USER_ERROR = __BT_FUNC_STATUS_USER_ERROR, + + /*! + @brief + User function interrupted the iteration process. + */ BT_VALUE_MAP_FOREACH_ENTRY_STATUS_INTERRUPTED = __BT_FUNC_STATUS_INTERRUPTED, + + /*! + @brief + User function error. + */ + BT_VALUE_MAP_FOREACH_ENTRY_STATUS_USER_ERROR = __BT_FUNC_STATUS_USER_ERROR, + + /*! + @brief + Out of memory. + */ + BT_VALUE_MAP_FOREACH_ENTRY_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, + + /*! + @brief + Other error. + */ + BT_VALUE_MAP_FOREACH_ENTRY_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, } bt_value_map_foreach_entry_status; +/*! +@brief + Iterates the entries of the map value \bt_p{value}, calling + \bt_p{user_func} for each entry. + +This function iterates the entries of \bt_p{value} in no particular +order. + +@attention + You must \em not modify \bt_p{value} during the iteration process. + +\bt_p{user_func} receives \bt_p{user_data} as its last parameter. + +The iteration process stops when one of: + +- \bt_p{user_func} was called for each entry. +- \bt_p{user_func} does not return + #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_OK. + +@param[in] value + Map value of which to iterate the entries. +@param[in] user_func + User function to call for each entry of \bt_p{value}. +@param[in] user_data + User data to pass as the \bt_p{user_data} parameter of each call to + \bt_p{user_func}. + +@retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_OK + Success. +@retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_INTERRUPTED + \bt_p{user_func} returned + #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_INTERRUPT to interrupt the + iteration process. +@retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_USER_ERROR + \bt_p{user_func} returned + #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_ERROR. +@retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_MEMORY_ERROR + Out of memory. +@retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_ERROR + Other error caused the bt_value_map_foreach_entry() + function itself. + +@bt_pre_not_null{value} +@bt_pre_is_map_val{value} +@bt_pre_not_null{user_func} + +@sa bt_value_map_foreach_entry_const() — + \c const version of this function. +@sa bt_value_map_borrow_entry_value() — + Borrows the value of a specific map value entry. +*/ extern bt_value_map_foreach_entry_status bt_value_map_foreach_entry( - bt_value *map_obj, bt_value_map_foreach_entry_func func, - void *data); + bt_value *value, bt_value_map_foreach_entry_func user_func, + void *user_data); -typedef enum bt_value_map_insert_entry_status { - BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, - BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK = __BT_FUNC_STATUS_OK, -} bt_value_map_insert_entry_status; +/*! +@brief + Status codes for #bt_value_map_foreach_entry_const_func. +*/ +typedef enum bt_value_map_foreach_entry_const_func_status { + /*! + @brief + Success. + */ + BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_OK = __BT_FUNC_STATUS_OK, -extern bt_value_map_insert_entry_status bt_value_map_insert_entry( - bt_value *map_obj, const char *key, bt_value *element_obj); + /*! + @brief + Interrupt the iteration process. + */ + BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_INTERRUPT = __BT_FUNC_STATUS_INTERRUPTED, -extern bt_value_map_insert_entry_status bt_value_map_insert_bool_entry( - bt_value *map_obj, const char *key, bt_bool val); + /*! + @brief + Out of memory. + */ + BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, -extern bt_value_map_insert_entry_status -bt_value_map_insert_unsigned_integer_entry(bt_value *map_obj, const char *key, - uint64_t val); + /*! + @brief + User error. + */ + BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, +} bt_value_map_foreach_entry_const_func_status; -extern bt_value_map_insert_entry_status -bt_value_map_insert_signed_integer_entry(bt_value *map_obj, const char *key, - int64_t val); +/*! +@brief + User function for bt_value_map_foreach_entry_const_func(). -extern bt_value_map_insert_entry_status bt_value_map_insert_real_entry( - bt_value *map_obj, const char *key, double val); +This is the type of the user function that +bt_value_map_foreach_entry_const_func() calls for each entry of the map +value. -extern bt_value_map_insert_entry_status -bt_value_map_insert_string_entry(bt_value *map_obj, const char *key, - const char *val); +@param[in] key + Key of the map value entry. +@param[in] value + Value of the map value entry. +@param[in] user_data + User data. -extern bt_value_map_insert_entry_status -bt_value_map_insert_empty_array_entry(bt_value *map_obj, const char *key, - bt_value **entry_obj); +@retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_OK + Success. +@retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_INTERRUPT + Interrupt the iteration process. +@retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_MEMORY_ERROR + Out of memory. +@retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_ERROR + User error. -extern bt_value_map_insert_entry_status -bt_value_map_insert_empty_map_entry(bt_value *map_obj, const char *key, - bt_value **entry_obj); +@bt_pre_not_null{key} +@bt_pre_not_null{value} + +@sa bt_value_map_foreach_entry_const() — + Iterates the entries of a \c const map value. +*/ +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); + +/*! +@brief + Status codes for bt_value_map_foreach_entry_const(). +*/ +typedef enum bt_value_map_foreach_entry_const_status { + /*! + @brief + Success. + */ + BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_OK = __BT_FUNC_STATUS_OK, + + /*! + @brief + User function interrupted the iteration process. + */ + BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_INTERRUPTED = __BT_FUNC_STATUS_INTERRUPTED, + + /*! + @brief + User function error. + */ + BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_USER_ERROR = __BT_FUNC_STATUS_USER_ERROR, + + /*! + @brief + Out of memory. + */ + BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, + + /*! + @brief + Other error. + */ + BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, +} bt_value_map_foreach_entry_const_status; + +/*! +@brief + Iterates the entries of the map value \bt_p{value}, calling + \bt_p{user_func} for each entry (\c const version). + +See bt_value_map_foreach_entry(). + +@sa bt_value_map_borrow_entry_value_const() — + Borrows the value of a specific map value entry. +*/ +extern 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); + +/*! +@brief + Returns the size of the map value \bt_p{value}. + +@param[in] value + Map value of which to get the size. + +@returns + Size (number of contained entries) of \bt_p{value}. + +@bt_pre_not_null{value} +@bt_pre_is_map_val{value} + +@sa bt_value_map_is_empty() — + Returns whether or not a map value is empty. +*/ +extern uint64_t bt_value_map_get_size(const bt_value *value); + +/*! +@brief + Returns whether or not the map value \bt_p{value} is empty. + +@param[in] value + Map value to check. + +@returns + #BT_TRUE if \bt_p{value} is empty (has the size 0). +@bt_pre_not_null{value} +@bt_pre_is_map_val{value} + +@sa bt_value_map_get_size() — + Returns the size of a map value. +*/ +static inline +bt_bool bt_value_map_is_empty(const bt_value *value) +{ + return bt_value_map_get_size(value) == 0; +} + +/*! +@brief + Returns whether or not the map value \bt_p{value} has an entry with + the key \bt_p{key}. + +@param[in] value + Map value to check. +@param[in] key + Key to check. + +@returns + #BT_TRUE if \bt_p{value} has an entry with the key \bt_p{key}. + +@bt_pre_not_null{value} +@bt_pre_is_map_val{value} +@bt_pre_not_null{key} + +@sa bt_value_map_borrow_entry_value_const() — + Borrows the value of a specific map value entry. +*/ +extern bt_bool bt_value_map_has_entry(const bt_value *value, + const char *key); + +/*! +@brief + Status codes for bt_value_map_extend(). +*/ typedef enum bt_value_map_extend_status { - BT_VALUE_MAP_EXTEND_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, + /*! + @brief + Success. + */ BT_VALUE_MAP_EXTEND_STATUS_OK = __BT_FUNC_STATUS_OK, + + /*! + @brief + Out of memory. + */ + BT_VALUE_MAP_EXTEND_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, } bt_value_map_extend_status; +/*! +@brief + Extends the map value \bt_p{value} with the map value + \bt_p{extension_value}. + +For each entry in \bt_p{extension_value}, this function calls +bt_value_map_insert_entry() to insert or replace it in the map value +\bt_p{value}. + +For example, with: + +
+
+ \bt_p{value} +
+
+ @code{.json} + { + "man": "giant", + "strange": 23 + } + @endcode +
+ +
+ \bt_p{extension_value} +
+
+ @code{.json} + { + "balance": -17 + "strange": false + } + @endcode +
+
+ +The map value \bt_p{value} becomes: + +@code{.json} +{ + "man": "giant", + "strange": false, + "balance": -17 +} +@endcode + +@param[in] value + Map value to extend. +@param[in] extension_value + Extension map value. + +@retval #BT_VALUE_MAP_EXTEND_STATUS_OK + Success. +@retval #BT_VALUE_MAP_EXTEND_STATUS_MEMORY_ERROR + Out of memory. + +@bt_pre_not_null{value} +@bt_pre_is_map_val{value} +@bt_pre_not_null{extension_value} +@bt_pre_is_map_val{extension_value} + +@sa bt_value_copy() — + Deep-copies a value. +*/ extern bt_value_map_extend_status bt_value_map_extend( - bt_value *base_map_obj, - const bt_value *extension_map_obj); + bt_value *value, const bt_value *extension_value); + +/*! @} */ + +/*! +@name General +@{ +*/ + +/*! +@brief + Status codes for bt_value_copy(). +*/ +typedef enum bt_value_copy_status { + /*! + @brief + Success. + */ + BT_VALUE_COPY_STATUS_OK = __BT_FUNC_STATUS_OK, + + /*! + @brief + Out of memory. + */ + BT_VALUE_COPY_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, +} bt_value_copy_status; + +/*! +@brief + Deep-copies a value object. + +This function deep-copies \bt_p{value} and sets \bt_p{*copy} to the +result. + +Because \bt_p{*copy} is a deep copy, it does not contain, recursively, +any reference that \bt_p{value} contains, but the raw values are +identical. + +@param[in] value + Value to deep-copy. +@param[in] copy_value + On success, \bt_p{*copy_value} is a deep copy of + \bt_p{value}. + +@retval #BT_VALUE_COPY_STATUS_OK + Success. +@retval #BT_VALUE_COPY_STATUS_MEMORY_ERROR + Out of memory. + +@bt_pre_not_null{value} +@bt_pre_not_null{copy_value} +*/ +extern bt_value_copy_status bt_value_copy(const bt_value *value, + bt_value **copy_value); + +/*! +@brief + Returns whether or not the value \bt_p{a_value} is equal, + recursively, to \bt_p{b_value}. + +@note + If you want to know whether or not a value is a null value, you can + also directly compare its pointer to the #bt_value_null variable. + +@param[in] a_value + Value A. +@param[in] b_value + Value B. + +@returns + #BT_TRUE if \bt_p{a_value} is equal, recursively, to \bt_p{b_value}. + +@bt_pre_not_null{a_value} +@bt_pre_not_null{b_value} +*/ +extern bt_bool bt_value_is_equal(const bt_value *a_value, + const bt_value *b_value); + +/*! @} */ + +/*! +@name Reference count +@{ +*/ + +/*! +@brief + Increments the \ref api-fund-shared-object "reference count" of + the value \bt_p{value}. + +@param[in] value + @parblock + Value of which to increment the reference count. + + Can be \c NULL. + @endparblock + +@sa bt_value_put_ref() — + Decrements the reference count of a value. +*/ +extern void bt_value_get_ref(const bt_value *value); + +/*! +@brief + Decrements the \ref api-fund-shared-object "reference count" of + the value \bt_p{value}. + +@param[in] value + @parblock + Value of which to decrement the reference count. + + Can be \c NULL. + @endparblock + +@sa bt_value_get_ref() — + Increments the reference count of a value. +*/ +extern void bt_value_put_ref(const bt_value *value); + +/*! +@brief + Decrements the reference count of the value \bt_p{_value}, and then + sets \bt_p{_value} to \c NULL. + +@param _value + @parblock + Value of which to decrement the reference count. + + Can contain \c NULL. + @endparblock + +@bt_pre_assign_expr{_value} +*/ +#define BT_VALUE_PUT_REF_AND_RESET(_value) \ + do { \ + bt_value_put_ref(_value); \ + (_value) = NULL; \ + } while (0) + +/*! +@brief + Decrements the reference count of the value \bt_p{_dst}, sets + \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL. + +This macro effectively moves a value reference from the expression +\bt_p{_src} to the expression \bt_p{_dst}, putting the existing +\bt_p{_dst} reference. + +@param _dst + @parblock + Destination expression. + + Can contain \c NULL. + @endparblock +@param _src + @parblock + Source expression. + + Can contain \c NULL. + @endparblock + +@bt_pre_assign_expr{_dst} +@bt_pre_assign_expr{_src} +*/ +#define BT_VALUE_MOVE_REF(_dst, _src) \ + do { \ + bt_value_put_ref(_dst); \ + (_dst) = (_src); \ + (_src) = NULL; \ + } while (0) + +/*! @} */ + +/*! @} */ #ifdef __cplusplus }