@ingroup apiref
@brief Value objects.
+@code
+#include <babeltrace/values.h>
+@endcode
+
This is a set of <strong><em>value objects</em></strong>. With the
functions documented here, you can create and modify:
</tr>
<tr>
<th>Map
- <td>bt_value_map_create()
+ <td>bt_value_map_create()<br>
+ bt_value_map_extend()
<td>bt_value_is_map()
<td>bt_value_map_get()<br>
bt_value_map_foreach()
it's built by its initial owner.
@param[in] object Value object to freeze.
-@returns One of #bt_value_status values. If \p object
+@returns Status code. If \p object
is already frozen, however, #BT_VALUE_STATUS_OK
is returned anyway (that is, this function never
returns #BT_VALUE_STATUS_FROZEN).
@prenotnull{object}
@post <strong>On success, if the returned value object is not
\ref bt_value_null</strong>, its reference count is 1.
-
@postrefcountsame{object}
*/
extern struct bt_value *bt_value_copy(const struct bt_value *object);
@param[in] bool_obj Boolean value object of which to get the
raw value.
@param[out] val Returned boolean raw value.
-@returns One of #bt_value_status values.
+@returns Status code.
@prenotnull{bool_obj}
@prenotnull{val}
@param[in] bool_obj Boolean value object of which to set
the raw value.
@param[in] val New boolean raw value.
-@returns One of #bt_value_status values.
+@returns Status code.
@prenotnull{bool_obj}
@pre \p bool_obj is a boolean value object.
@param[in] integer_obj Integer value object of which to get the
raw value.
@param[out] val Returned integer raw value.
-@returns One of #bt_value_status values.
+@returns Status code.
@prenotnull{integer_obj}
@prenotnull{val}
@param[in] integer_obj Integer value object of which to set
the raw value.
@param[in] val New integer raw value.
-@returns One of #bt_value_status values.
+@returns Status code.
@prenotnull{integer_obj}
@pre \p integer_obj is an integer value object.
@param[in] float_obj Floating point number value object of which to
get the raw value.
@param[out] val Returned floating point number raw value
-@returns One of #bt_value_status values.
+@returns Status code.
@prenotnull{float_obj}
@prenotnull{val}
@param[in] float_obj Floating point number value object of which to set
the raw value.
@param[in] val New floating point number raw value.
-@returns One of #bt_value_status values.
+@returns Status code.
@prenotnull{float_obj}
@pre \p float_obj is a floating point number value object.
@param[in] string_obj String value object of which to get the
raw value.
@param[out] val Returned string raw value.
-@returns One of #bt_value_status values.
+@returns Status code.
@prenotnull{string_obj}
@prenotnull{val}
@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 One of #bt_value_status values.
+@returns Status code.
@prenotnull{string_obj}
@prenotnull{val}
@prenotnull{array_obj}
@pre \p array_obj is an array value object.
-@pre \p index is lesser than the size of \p array_obj.
+@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}
@param[in] array_obj Array value object in which to append
\p element_obj.
@param[in] element_obj Value object to append.
-@returns One of #bt_value_status values.
+@returns Status code.
@prenotnull{array_obj}
@prenotnull{element_obj}
@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 One of #bt_value_status values.
+@returns Status code.
@prenotnull{array_obj}
@pre \p array_obj is an array value object.
@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 One of #bt_value_status values.
+@returns Status code.
@prenotnull{array_obj}
@pre \p array_obj is an array value object.
@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 One of #bt_value_status values.
+@returns Status code.
@prenotnull{array_obj}
@pre \p array_obj is an array value object.
@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 One of #bt_value_status values.
+@returns Status code.
@prenotnull{array_obj}
@pre \p array_obj is an array value object.
@param[in] array_obj Array value object in which to append an
empty array value object
-@returns One of #bt_value_status values.
+@returns Status code.
@prenotnull{array_obj}
@pre \p array_obj is an array value object.
@param[in] array_obj Array value object in which to append an empty
map value object.
-@returns One of #bt_value_status values.
+@returns Status code.
@prenotnull{array_obj}
@pre \p array_obj is an array value object.
\p array_obj.
@param[in] element_obj New value object at position \p index of
\p array_obj.
-@returns One of #bt_value_status values.
+@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.
+@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.
@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.
*/
@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 your own reference.
+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.
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 your own reference.
+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.
@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 One of #bt_value_status values. More
+@returns Status code. More
specifically, #BT_VALUE_STATUS_CANCELLED is
returned if the loop was cancelled by the user
function.
value object to insert is mapped.
@param[in] element_obj Value object to insert, mapped to the
key \p key.
-@returns One of #bt_value_status values.
+@returns Status code.
@prenotnull{map_obj}
@prenotnull{key}
value object to insert is mapped.
@param[in] val Boolean raw value to insert, mapped to
the key \p key.
-@returns One of #bt_value_status values.
+@returns Status code.
@prenotnull{map_obj}
@prenotnull{key}
value object to insert is mapped.
@param[in] val Integer raw value to insert, mapped to
the key \p key.
-@returns One of #bt_value_status values.
+@returns Status code.
@prenotnull{map_obj}
@prenotnull{key}
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 One of #bt_value_status values.
+@returns Status code.
@prenotnull{map_obj}
@prenotnull{key}
value object to insert is mapped.
@param[in] val String raw value to insert (copied on success),
mapped to the key \p key.
-@returns One of #bt_value_status values.
+@returns Status code.
@prenotnull{map_obj}
@prenotnull{key}
array value object.
@param[in] key Key (copied on success) to which the empty array
value object to insert is mapped.
-@returns One of #bt_value_status values.
+@returns Status code.
@prenotnull{map_obj}
@prenotnull{key}
map object.
@param[in] key Key (copied on success) to which the empty map
value object to insert is mapped.
-@returns One of #bt_value_status values.
+@returns Status code.
@prenotnull{map_obj}
@prenotnull{key}
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
+{
+ "hello": 23,
+ "code": -17,
+ "em": false,
+ "return": [5, 6, null]
+}
+@endverbatim
+
+and the following \p extension_map_obj (JSON representation):
+
+@verbatim
+{
+ "comma": ",",
+ "code": 22,
+ "return": 17.88
+}
+@endverbatim
+
+The extended object is (JSON representation):
+
+@verbatim
+{
+ "hello": 23,
+ "code": 22,
+ "em": false,
+ "return": 17.88,
+ "comma": ","
+}
+@endverbatim
+
+@param[in] base_map_obj Base map value object with initial
+ entries.
+@param[in] extension_map_obj Extension map value object containing
+ the entries to add to or replace in
+ \p base_map_obj.
+@returns Created extended map value object, or
+ \c NULL on error.
+
+@prenotnull{base_map_obj}
+@prenotnull{extension_map_obj}
+@pre \p base_map_obj is a map value object.
+@pre \p extension_map_obj is a map value object.
+@postrefcountsame{base_map_obj}
+@postrefcountsame{extension_map_obj}
+@postsuccessrefcountret1
+*/
+extern struct bt_value *bt_value_map_extend(struct bt_value *base_map_obj,
+ struct bt_value *extension_map_obj);
+
/** @} */
/** @} */