-#ifndef _BABELTRACE_VALUES_H
-#define _BABELTRACE_VALUES_H
+#ifndef BABELTRACE_VALUES_H
+#define BABELTRACE_VALUES_H
/*
* Babeltrace - Value objects
*/
#include <stdint.h>
-#include <stdbool.h>
#include <stddef.h>
#include <babeltrace/ref.h>
+#include <babeltrace/types.h>
#ifdef __cplusplus
extern "C" {
@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()
BT_VALUE_STATUS_CANCELLED = -3,
/* -22 for compatibility with -EINVAL */
- /// Invalid arguments.
+ /// Invalid argument.
BT_VALUE_STATUS_INVAL = -22,
/// General error.
/// Null value object.
BT_VALUE_TYPE_NULL = 0,
- /// Boolean value object (holds \c true or \c false).
+ /// Boolean value object (holds #BT_TRUE or #BT_FALSE).
BT_VALUE_TYPE_BOOL = 1,
/// Integer value object (holds a signed 64-bit integer raw value).
object pointer to the \ref bt_value_null variable.
@param[in] object Value object to check.
-@returns \c true if \p object is the null value object.
+@returns #BT_TRUE if \p object is the null value object.
@prenotnull{object}
@postrefcountsame{object}
@sa bt_value_get_type(): Returns the type of a given value object.
*/
static inline
-bool bt_value_is_null(const struct bt_value *object)
+bt_bool bt_value_is_null(const struct bt_value *object)
{
return bt_value_get_type(object) == BT_VALUE_TYPE_NULL;
}
value object.
@param[in] object Value object to check.
-@returns \c true if \p object is a boolean value object.
+@returns #BT_TRUE if \p object is a boolean value object.
@prenotnull{object}
@postrefcountsame{object}
@sa bt_value_get_type(): Returns the type of a given value object.
*/
static inline
-bool bt_value_is_bool(const struct bt_value *object)
+bt_bool bt_value_is_bool(const struct bt_value *object)
{
return bt_value_get_type(object) == BT_VALUE_TYPE_BOOL;
}
value object.
@param[in] object Value object to check.
-@returns \c true if \p object is an integer value object.
+@returns #BT_TRUE if \p object is an integer value object.
@sa bt_value_get_type(): Returns the type of a given value object.
*/
static inline
-bool bt_value_is_integer(const struct bt_value *object)
+bt_bool bt_value_is_integer(const struct bt_value *object)
{
return bt_value_get_type(object) == BT_VALUE_TYPE_INTEGER;
}
point number value object.
@param[in] object Value object to check.
-@returns \c true if \p object is a floating point
+@returns #BT_TRUE if \p object is a floating point
number value object.
@prenotnull{object}
@sa bt_value_get_type(): Returns the type of a given value object.
*/
static inline
-bool bt_value_is_float(const struct bt_value *object)
+bt_bool bt_value_is_float(const struct bt_value *object)
{
return bt_value_get_type(object) == BT_VALUE_TYPE_FLOAT;
}
value object.
@param[in] object Value object to check.
-@returns \c true if \p object is a string value object.
+@returns #BT_TRUE if \p object is a string value object.
@prenotnull{object}
@postrefcountsame{object}
@sa bt_value_get_type(): Returns the type of a given value object.
*/
static inline
-bool bt_value_is_string(const struct bt_value *object)
+bt_bool bt_value_is_string(const struct bt_value *object)
{
return bt_value_get_type(object) == BT_VALUE_TYPE_STRING;
}
value object.
@param[in] object Value object to check.
-@returns \c true if \p object is an array value object.
+@returns #BT_TRUE if \p object is an array value object.
@prenotnull{object}
@postrefcountsame{object}
@sa bt_value_get_type(): Returns the type of a given value object.
*/
static inline
-bool bt_value_is_array(const struct bt_value *object)
+bt_bool bt_value_is_array(const struct bt_value *object)
{
return bt_value_get_type(object) == BT_VALUE_TYPE_ARRAY;
}
object.
@param[in] object Value object to check.
-@returns \c true if \p object is a map value object.
+@returns #BT_TRUE if \p object is a map value object.
@prenotnull{object}
@postrefcountsame{object}
@sa bt_value_get_type(): Returns the type of a given value object.
*/
static inline
-bool bt_value_is_map(const struct bt_value *object)
+bt_bool bt_value_is_map(const struct bt_value *object)
{
return bt_value_get_type(object) == BT_VALUE_TYPE_MAP;
}
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).
@brief Returns whether or not the value object \p object is frozen.
@param[in] object Value object to check.
-@returns \c true if \p object is frozen.
+@returns #BT_TRUE if \p object is frozen.
@prenotnull{object}
@postrefcountsame{object}
*/
-extern bool bt_value_is_frozen(const struct bt_value *object);
+extern bt_bool bt_value_is_frozen(const struct bt_value *object);
/**
@brief Creates a \em deep copy of the value object \p object.
@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);
/**
@brief Recursively compares the value objects \p object_a and
- \p object_b and returns \c true if they have the same
+ \p object_b and returns #BT_TRUE if they have the same
\em content (raw values).
@param[in] object_a Value object A to compare to \p object_b.
@param[in] object_b Value object B to compare to \p object_a.
-@returns \c true if \p object_a and \p object_b have the
- same \em content, or \c false if they differ
+@returns #BT_TRUE if \p object_a and \p object_b have the
+ same \em content, or #BT_FALSE if they differ
or on error.
@postrefcountsame{object_a}
@postrefcountsame{object_b}
*/
-extern bool bt_value_compare(const struct bt_value *object_a,
+extern bt_bool bt_value_compare(const struct bt_value *object_a,
const struct bt_value *object_b);
/** @} */
/**
@brief Creates a default boolean value object.
-The created boolean value object's initial raw value is \c false.
+The created boolean value object's initial raw value is #BT_FALSE.
@returns Created boolean value object on success, or \c NULL
on error.
@sa bt_value_bool_create(): Creates a default boolean value object.
*/
-extern struct bt_value *bt_value_bool_create_init(bool val);
+extern struct bt_value *bt_value_bool_create_init(bt_bool val);
/**
@brief Returns the boolean raw value of the boolean 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}
@sa bt_value_bool_set(): Sets the raw value of a boolean value object.
*/
extern enum bt_value_status bt_value_bool_get(
- const struct bt_value *bool_obj, bool *val);
+ const struct bt_value *bool_obj, bt_bool *val);
/**
@brief Sets the boolean raw value of the boolean value object
@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.
value object.
*/
extern enum bt_value_status bt_value_bool_set(struct bt_value *bool_obj,
- bool val);
+ bt_bool val);
/** @} */
@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}
@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);
+extern int64_t 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.
+@returns #BT_TRUE if \p array_obj is empty.
@prenotnull{array_obj}
@pre \p array_obj is an array value object.
@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);
+extern bt_bool bt_value_array_is_empty(const struct bt_value *array_obj);
/**
@brief Returns the value object contained in the array value object
@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}
*/
extern struct bt_value *bt_value_array_get(const struct bt_value *array_obj,
- size_t index);
+ uint64_t index);
/**
@brief Appends the value object \p element_obj to the array value
@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.
array value object.
*/
extern enum bt_value_status bt_value_array_append_bool(
- struct bt_value *array_obj, bool val);
+ struct bt_value *array_obj, bt_bool val);
/**
@brief Appends the integer raw value \p val to the 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.
@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);
+ uint64_t index, struct bt_value *element_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);
+extern int64_t 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.
+@returns #BT_TRUE if \p map_obj is empty.
@prenotnull{map_obj}
@pre \p map_obj is a map value object.
@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);
+extern bt_bool bt_value_map_is_empty(const struct bt_value *map_obj);
/**
@brief Returns the value object associated with the key \p key within
@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.
+This function \em must return #BT_TRUE to continue the map value object
+traversal, or #BT_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.
+@returns #BT_TRUE to continue the loop, or #BT_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,
+typedef bt_bool (* bt_value_map_foreach_cb)(const char *key,
struct bt_value *object, void *data);
/**
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.
-The user function \em must return \c true to continue the traversal of
-\p map_obj, or \c false to break it.
+The user function \em must return #BT_TRUE to continue the traversal of
+\p map_obj, or #BT_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 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.
@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
+@returns #BT_TRUE if \p map_obj has an entry mapped to the
+ key \p key, or #BT_FALSE if it does not or
on error.
@prenotnull{map_obj}
@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,
+extern bt_bool bt_value_map_has_key(const struct bt_value *map_obj,
const char *key);
/**
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.
*/
extern enum bt_value_status bt_value_map_insert_bool(
- struct bt_value *map_obj, const char *key, bool val);
+ struct bt_value *map_obj, const char *key, bt_bool val);
/**
@brief Inserts the integer raw value \p val mapped to the key \p 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}
For example, consider the following \p base_map_obj (JSON representation):
-@code{.unparsed}
+@verbatim
{
"hello": 23,
"code": -17,
"em": false,
"return": [5, 6, null]
}
-@endcode
+@endverbatim
and the following \p extension_map_obj (JSON representation):
-@code{.unparsed}
+@verbatim
{
"comma": ",",
"code": 22,
"return": 17.88
}
-@endcode
+@endverbatim
The extended object is (JSON representation):
-@code{.unparsed}
+@verbatim
{
"hello": 23,
"code": 22,
"return": 17.88,
"comma": ","
}
-@endcode
+@endverbatim
@param[in] base_map_obj Base map value object with initial
entries.
}
#endif
-#endif /* _BABELTRACE_VALUES_H */
+#endif /* BABELTRACE_VALUES_H */
projects / babeltrace.git / blobdiff