-On success, \p val is copied.
-
-@param[in] string_obj String value object of which to set
- the raw value.
-@param[in] val New string raw value (copied on success).
-@returns Status code.
-
-@prenotnull{string_obj}
-@prenotnull{val}
-@pre \p string_obj is a string value object.
-@prehot{string_obj}
-@postrefcountsame{string_obj}
-
-@sa bt_value_string_get(): Returns the raw value of a given string
- value object.
-*/
-extern enum bt_value_status bt_value_string_set(struct bt_value *string_obj,
- const char *val);
-
-/**
- * @}
- */
-
-/**
- * @name Array value object functions
- * @{
- */
-
-/**
-@brief Creates an empty array value object.
-
-@returns Created array value object on success, or \c NULL
- on error.
-
-@postsuccessrefcountret1
-*/
-extern struct bt_value *bt_value_array_create(void);
-
-/**
-@brief Returns the size of the array value object \p array_obj, that is,
- the number of value objects contained in \p array_obj.
-
-@param[in] array_obj Array value object of which to get the size.
-@returns Number of value objects contained in
- \p array_obj if the return value is 0 (empty)
- or a positive value, or one of
- #bt_value_status negative values otherwise.
-
-@prenotnull{array_obj}
-@pre \p array_obj is an array value object.
-@postrefcountsame{array_obj}
-
-@sa bt_value_array_is_empty(): Checks whether or not a given array
- value object is empty.
-*/
-extern int bt_value_array_size(const struct bt_value *array_obj);
-
-/**
-@brief Checks whether or not the array value object \p array_obj
- is empty.
-
-@param[in] array_obj Array value object to check.
-@returns \c true if \p array_obj is empty.
-
-@prenotnull{array_obj}
-@pre \p array_obj is an array value object.
-@postrefcountsame{array_obj}
-
-@sa bt_value_array_size(): Returns the size of a given array value
- object.
-*/
-extern bool bt_value_array_is_empty(const struct bt_value *array_obj);
-
-/**
-@brief Returns the value object contained in the array value object
- \p array_obj at the index \p index.
-
-@param[in] array_obj Array value object of which to get an element.
-@param[in] index Index of value object to get.
-@returns Value object at index \p index on
- success, or \c NULL on error.
-
-@prenotnull{array_obj}
-@pre \p array_obj is an array value object.
-@pre \p index is lesser than the size of \p array_obj (see
- bt_value_array_size()).
-@post <strong>On success, if the returned value object is not
- \ref bt_value_null</strong>, its reference count is incremented.
-@postrefcountsame{array_obj}
-*/
-extern struct bt_value *bt_value_array_get(const struct bt_value *array_obj,
- size_t index);
-
-/**
-@brief Appends the value object \p element_obj to the array value
- object \p array_obj.
-
-@param[in] array_obj Array value object in which to append
- \p element_obj.
-@param[in] element_obj Value object to append.
-@returns Status code.
-
-@prenotnull{array_obj}
-@prenotnull{element_obj}
-@pre \p array_obj is an array value object.
-@prehot{array_obj}
-@post <strong>On success, if \p element_obj is not
- \ref bt_value_null</strong>, its reference count is incremented.
-@postrefcountsame{array_obj}
-
-@sa bt_value_array_append_bool(): Appends a boolean raw value to a
- given array value object.
-@sa bt_value_array_append_integer(): Appends an integer raw value
- to a given array value object.
-@sa bt_value_array_append_float(): Appends a floating point number
- raw value to a given array value object.
-@sa bt_value_array_append_string(): Appends a string raw value to a
- given array value object.
-@sa bt_value_array_append_empty_array(): Appends an empty array value
- object to a given array value object.
-@sa bt_value_array_append_empty_map(): Appends an empty map value
- object to a given array value object.
-*/
-extern enum bt_value_status bt_value_array_append(struct bt_value *array_obj,
- struct bt_value *element_obj);
-
-/**
-@brief Appends the boolean raw value \p val to the array value object
- \p array_obj.
-
-This is a convenience function which creates the underlying boolean
-value object before appending it.
-
-@param[in] array_obj Array value object in which to append \p val.
-@param[in] val Boolean raw value to append to \p array_obj.
-@returns Status code.
-
-@prenotnull{array_obj}
-@pre \p array_obj is an array value object.
-@prehot{array_obj}
-@postrefcountsame{array_obj}
-
-@sa bt_value_array_append(): Appends a value object to a given
- array value object.
-*/
-extern enum bt_value_status bt_value_array_append_bool(
- struct bt_value *array_obj, bool val);
-
-/**
-@brief Appends the integer raw value \p val to the array value object
- \p array_obj.
-
-This is a convenience function which creates the underlying integer
-value object before appending it.
-
-@param[in] array_obj Array value object in which to append \p val.
-@param[in] val Integer raw value to append to \p array_obj.
-@returns Status code.
-
-@prenotnull{array_obj}
-@pre \p array_obj is an array value object.
-@prehot{array_obj}
-@postrefcountsame{array_obj}
-
-@sa bt_value_array_append(): Appends a value object to a given
- array value object.
-*/
-extern enum bt_value_status bt_value_array_append_integer(
- struct bt_value *array_obj, int64_t val);
-
-/**
-@brief Appends the floating point number raw value \p val to the array
- value object \p array_obj.
-
-This is a convenience function which creates the underlying floating
-point number value object before appending it.
-
-@param[in] array_obj Array value object in which to append \p val.
-@param[in] val Floating point number raw value to append
- to \p array_obj.
-@returns Status code.
-
-@prenotnull{array_obj}
-@pre \p array_obj is an array value object.
-@prehot{array_obj}
-@postrefcountsame{array_obj}
-
-@sa bt_value_array_append(): Appends a value object to a given
- array value object.
-*/
-extern enum bt_value_status bt_value_array_append_float(
- struct bt_value *array_obj, double val);
-
-/**
-@brief Appends the string raw value \p val to the array value object
- \p array_obj.
-
-This is a convenience function which creates the underlying string value
-object before appending it.
-
-On success, \p val is copied.
-
-@param[in] array_obj Array value object in which to append \p val.
-@param[in] val String raw value to append to \p array_obj
- (copied on success).
-@returns Status code.
-
-@prenotnull{array_obj}
-@pre \p array_obj is an array value object.
-@prenotnull{val}
-@prehot{array_obj}
-@postrefcountsame{array_obj}
-
-@sa bt_value_array_append(): Appends a value object to a given
- array value object.
-*/
-extern enum bt_value_status bt_value_array_append_string(
- struct bt_value *array_obj, const char *val);
-
-/**
-@brief Appends an empty array value object to the array value object
- \p array_obj.
-
-This is a convenience function which creates the underlying array value
-object before appending it.
-
-@param[in] array_obj Array value object in which to append an
- empty array value object
-@returns Status code.
-
-@prenotnull{array_obj}
-@pre \p array_obj is an array value object.
-@prehot{array_obj}
-@postrefcountsame{array_obj}
-
-@sa bt_value_array_append(): Appends a value object to a given
- array value object.
-*/
-extern enum bt_value_status bt_value_array_append_empty_array(
- struct bt_value *array_obj);
-
-/**
-@brief Appends an empty map value object to the array value object
- \p array_obj.
-
-This is a convenience function which creates the underlying map value
-object before appending it.
-
-@param[in] array_obj Array value object in which to append an empty
- map value object.
-@returns Status code.
-
-@prenotnull{array_obj}
-@pre \p array_obj is an array value object.
-@prehot{array_obj}
-@postrefcountsame{array_obj}
-
-@sa bt_value_array_append(): Appends a value object to a given
- array value object.
-*/
-extern enum bt_value_status bt_value_array_append_empty_map(
- struct bt_value *array_obj);
-
-/**
-@brief Replaces the value object contained in the array value object
- \p array_obj at the index \p index by \p element_obj.
-
-@param[in] array_obj Array value object in which to replace
- an element.
-@param[in] index Index of value object to replace in
- \p array_obj.
-@param[in] element_obj New value object at position \p index of
- \p array_obj.
-@returns Status code.
-
-@prenotnull{array_obj}
-@prenotnull{element_obj}
-@pre \p array_obj is an array value object.
-@pre \p index is lesser than the size of \p array_obj (see
- bt_value_array_size()).
-@prehot{array_obj}
-@post <strong>On success, if the replaced value object is not
- \ref bt_value_null</strong>, its reference count is decremented.
-@post <strong>On success, if \p element_obj is not
- \ref bt_value_null</strong>, its reference count is incremented.
-@postrefcountsame{array_obj}
-*/
-extern enum bt_value_status bt_value_array_set(struct bt_value *array_obj,
- size_t index, struct bt_value *element_obj);
-
-/** @} */
-
-/**
-@name Map value object functions
-@{
-*/
-
-/**
-@brief Creates an empty map value object.
-
-@returns Created map value object on success, or \c NULL on error.
-
-@postsuccessrefcountret1
-*/
-extern struct bt_value *bt_value_map_create(void);
-
-/**
-@brief Returns the size of the map value object \p map_obj, that is, the
- number of entries contained in \p map_obj.
-
-@param[in] map_obj Map value object of which to get the size.
-@returns Number of entries contained in \p map_obj if the
- return value is 0 (empty) or a positive value,
- or one of #bt_value_status negative values
- otherwise.
-
-@prenotnull{map_obj}
-@pre \p map_obj is a map value object.
-@postrefcountsame{map_obj}
-
-@sa bt_value_map_is_empty(): Checks whether or not a given map value
- object is empty.
-*/
-extern int bt_value_map_size(const struct bt_value *map_obj);
-
-/**
-@brief Checks whether or not the map value object \p map_obj is empty.
-
-@param[in] map_obj Map value object to check.
-@returns \c true if \p map_obj is empty.
-
-@prenotnull{map_obj}
-@pre \p map_obj is a map value object.
-@postrefcountsame{map_obj}
-
-@sa bt_value_map_size(): Returns the size of a given map value object.
-*/
-extern bool bt_value_map_is_empty(const struct bt_value *map_obj);
-
-/**
-@brief Returns the value object associated with the key \p key within
- the map value object \p map_obj.
-
-@param[in] map_obj Map value object of which to get an entry.
-@param[in] key Key of the value object to get.
-@returns Value object associated with the key \p key
- on success, or \c NULL on error.
-
-@prenotnull{map_obj}
-@prenotnull{key}
-@pre \p map_obj is a map value object.
-@postrefcountsame{map_obj}
-@post <strong>On success, if the returned value object is not
- \ref bt_value_null</strong>, its reference count is incremented.
-*/
-extern struct bt_value *bt_value_map_get(const struct bt_value *map_obj,
- const char *key);
-
-/**
-@brief User function type to use with bt_value_map_foreach().
-
-\p object is a <em>weak reference</em>: you \em must pass it to bt_get()
-if you need to keep a reference after this function returns.
-
-This function \em must return \c true to continue the map value object
-traversal, or \c false to break it.
-
-@param[in] key Key of map entry.
-@param[in] object Value object of map entry (weak reference).
-@param[in] data User data.
-@returns \c true to continue the loop, or \c false to break it.
-
-@prenotnull{key}
-@prenotnull{object}
-@post The reference count of \p object is not lesser than what it is
- when the function is called.
-*/
-typedef bool (* bt_value_map_foreach_cb)(const char *key,
- struct bt_value *object, void *data);
-
-/**
-@brief Calls a provided user function \p cb for each value object of the
- map value object \p map_obj.
-
-The value object passed to the user function is a <b>weak reference</b>:
-you \em must pass it to bt_get() if you need to keep a persistent
-reference after the user function returns.
-
-The key passed to the user function is only valid in the scope of
-this user function call.
-
-The user function \em must return \c true to continue the traversal of
-\p map_obj, or \c false to break it.
-
-@param[in] map_obj Map value object on which to iterate.
-@param[in] cb User function to call back.
-@param[in] data User data passed to the user function.
-@returns Status code. More
- specifically, #BT_VALUE_STATUS_CANCELLED is
- returned if the loop was cancelled by the user
- function.
-
-@prenotnull{map_obj}
-@prenotnull{cb}
-@pre \p map_obj is a map value object.
-@postrefcountsame{map_obj}
-*/
-extern enum bt_value_status bt_value_map_foreach(
- const struct bt_value *map_obj, bt_value_map_foreach_cb cb,
- void *data);
-
-/**
-@brief Returns whether or not the map value object \p map_obj contains
- an entry mapped to the key \p key.
-
-@param[in] map_obj Map value object to check.
-@param[in] key Key to check.
-@returns \c true if \p map_obj has an entry mapped to the
- key \p key, or \c false if it does not or
- on error.
-
-@prenotnull{map_obj}
-@prenotnull{key}
-@pre \p map_obj is a map value object.
-@postrefcountsame{map_obj}
-*/
-extern bool bt_value_map_has_key(const struct bt_value *map_obj,
- const char *key);
-
-/**
-@brief Inserts the value object \p element_obj mapped to the key
- \p key into the map value object \p map_obj.
-
-If a value object is already mapped to \p key in \p map_obj, the
-associated value object is first put, and then replaced by
-\p element_obj.
-
-On success, \p key is copied.
-
-@param[in] map_obj Map value object in which to insert
- \p element_obj.
-@param[in] key Key (copied on success) to which the
- value object to insert is mapped.
-@param[in] element_obj Value object to insert, mapped to the
- key \p key.
-@returns Status code.
-
-@prenotnull{map_obj}
-@prenotnull{key}
-@prenotnull{element_obj}
-@pre \p map_obj is a map value object.
-@prehot{map_obj}
-@post <strong>On success, if \p element_obj is not
- \ref bt_value_null</strong>, its reference count is incremented.
-@postrefcountsame{map_obj}
-
-@sa bt_value_map_insert_bool(): Inserts a boolean raw value into a
- given map value object.
-@sa bt_value_map_insert_integer(): Inserts an integer raw value into
- a given map value object.
-@sa bt_value_map_insert_float(): Inserts a floating point number raw
- value into a given map value object.
-@sa bt_value_map_insert_string(): Inserts a string raw value into a
- given map value object.
-@sa bt_value_map_insert_empty_array(): Inserts an empty array value
- object into a given map value object.
-@sa bt_value_map_insert_empty_map(): Inserts an empty map value
- object into a given map value object.
-*/
-extern enum bt_value_status bt_value_map_insert(
- struct bt_value *map_obj, const char *key,
- struct bt_value *element_obj);
-
-/**
-@brief Inserts the boolean raw value \p val mapped to the key \p key
- into the map value object \p map_obj.
-
-This is a convenience function which creates the underlying boolean
-value object before inserting it.
-
-On success, \p key is copied.
-
-@param[in] map_obj Map value object in which to insert \p val.
-@param[in] key Key (copied on success) to which the boolean
- value object to insert is mapped.
-@param[in] val Boolean raw value to insert, mapped to
- the key \p key.
-@returns Status code.
-
-@prenotnull{map_obj}
-@prenotnull{key}
-@pre \p map_obj is a map value object.
-@prehot{map_obj}
-@postrefcountsame{map_obj}
-
-@sa bt_value_map_insert(): Inserts a value object into a given map
- value object.
-*/
-extern enum bt_value_status bt_value_map_insert_bool(
- struct bt_value *map_obj, const char *key, bool val);
-
-/**
-@brief Inserts the integer raw value \p val mapped to the key \p key
- into the map value object \p map_obj.
-
-This is a convenience function which creates the underlying integer
-value object before inserting it.
-
-On success, \p key is copied.
-
-@param[in] map_obj Map value object in which to insert \p val.
-@param[in] key Key (copied on success) to which the integer
- value object to insert is mapped.
-@param[in] val Integer raw value to insert, mapped to
- the key \p key.
-@returns Status code.
-
-@prenotnull{map_obj}
-@prenotnull{key}
-@pre \p map_obj is a map value object.
-@prehot{map_obj}
-@postrefcountsame{map_obj}
-
-@sa bt_value_map_insert(): Inserts a value object into a given map
- value object.
-*/
-extern enum bt_value_status bt_value_map_insert_integer(
- struct bt_value *map_obj, const char *key, int64_t val);
-
-/**
-@brief Inserts the floating point number raw value \p val mapped to
- the key \p key into the map value object \p map_obj.
-
-This is a convenience function which creates the underlying floating
-point number value object before inserting it.
-
-On success, \p key is copied.
-
-@param[in] map_obj Map value object in which to insert \p val.
-@param[in] key Key (copied on success) to which the floating
- point number value object to insert is mapped.
-@param[in] val Floating point number raw value to insert,
- mapped to the key \p key.
-@returns Status code.
-
-@prenotnull{map_obj}
-@prenotnull{key}
-@pre \p map_obj is a map value object.
-@prehot{map_obj}
-@postrefcountsame{map_obj}
-
-@sa bt_value_map_insert(): Inserts a value object into a given map
- value object.
-*/
-extern enum bt_value_status bt_value_map_insert_float(
- struct bt_value *map_obj, const char *key, double val);
-
-/**
-@brief Inserts the string raw value \p val mapped to the key \p key
- into the map value object \p map_obj.
-
-This is a convenience function which creates the underlying string value
-object before inserting it.
-
-On success, \p val and \p key are copied.
-
-@param[in] map_obj Map value object in which to insert \p val.
-@param[in] key Key (copied on success) to which the string
- value object to insert is mapped.
-@param[in] val String raw value to insert (copied on success),
- mapped to the key \p key.
-@returns Status code.
-
-@prenotnull{map_obj}
-@prenotnull{key}
-@prenotnull{val}
-@pre \p map_obj is a map value object.
-@prehot{map_obj}
-@postrefcountsame{map_obj}
-
-@sa bt_value_map_insert(): Inserts a value object into a given map
- value object.
-*/
-extern enum bt_value_status bt_value_map_insert_string(
- struct bt_value *map_obj, const char *key, const char *val);
-
-/**
-@brief Inserts an empty array value object mapped to the key \p key
- into the map value object \p map_obj.
-
-This is a convenience function which creates the underlying array value
-object before inserting it.
-
-On success, \p key is copied.
-
-@param[in] map_obj Map value object in which to insert an empty
- array value object.
-@param[in] key Key (copied on success) to which the empty array
- value object to insert is mapped.
-@returns Status code.
-
-@prenotnull{map_obj}
-@prenotnull{key}
-@pre \p map_obj is a map value object.
-@prehot{map_obj}
-@postrefcountsame{map_obj}
-
-@sa bt_value_map_insert(): Inserts a value object into a given map
- value object.
-*/
-extern enum bt_value_status bt_value_map_insert_empty_array(
- struct bt_value *map_obj, const char *key);
-
-/**
-@brief Inserts an empty map value object mapped to the key \p key into
- the map value object \p map_obj.
-
-This is a convenience function which creates the underlying map value
-object before inserting it.
-
-On success, \p key is copied.
-
-@param[in] map_obj Map value object in which to insert an empty
- map object.
-@param[in] key Key (copied on success) to which the empty map
- value object to insert is mapped.
-@returns Status code.
-
-@prenotnull{map_obj}
-@prenotnull{key}
-@pre \p map_obj is a map value object.
-@prehot{map_obj}
-@postrefcountsame{map_obj}
-
-@sa bt_value_map_insert(): Inserts a value object into a given map
- value object.
-*/
-extern enum bt_value_status bt_value_map_insert_empty_map(
- struct bt_value *map_obj, const char *key);
-
-/**
-@brief Creates a copy of the base map value object \p base_map_obj
- superficially extended with the entries of the extension map
- value object \p extension_map_obj.
-
-This function creates a superficial extension of \p base_map_obj with
-\p extension_map_obj by adding new entries to it and replacing the
-ones that share the keys in the extension object. The extension is
-\em superficial because it does not merge internal array and map
-value objects.
-
-For example, consider the following \p base_map_obj (JSON representation):
-
-@verbatim