X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace%2Fvalues.h;h=d4a2214b1f35ff355ceeebadefa0f33a381c3c23;hb=20ccd9e16883d4adf91b944a1240d7f4c931aa9a;hp=d5ffef0b94bd0dada2201102d227e9db6799bd42;hpb=770750d3f959953ed4da34e0f9e44912ce387faf;p=babeltrace.git diff --git a/include/babeltrace/values.h b/include/babeltrace/values.h index d5ffef0b..d4a2214b 100644 --- a/include/babeltrace/values.h +++ b/include/babeltrace/values.h @@ -1,5 +1,5 @@ -#ifndef _BABELTRACE_VALUES_H -#define _BABELTRACE_VALUES_H +#ifndef BABELTRACE_VALUES_H +#define BABELTRACE_VALUES_H /* * Babeltrace - Value objects @@ -27,9 +27,9 @@ */ #include -#include #include #include +#include #ifdef __cplusplus extern "C" { @@ -40,6 +40,10 @@ extern "C" { @ingroup apiref @brief Value objects. +@code +#include +@endcode + This is a set of value objects. With the functions documented here, you can create and modify: @@ -143,7 +147,8 @@ to use for each value object type: Map - bt_value_map_create() + bt_value_map_create()
+ bt_value_map_extend() bt_value_is_map() bt_value_map_get()
bt_value_map_foreach() @@ -176,7 +181,7 @@ enum bt_value_status { BT_VALUE_STATUS_CANCELLED = -3, /* -22 for compatibility with -EINVAL */ - /// Invalid arguments. + /// Invalid argument. BT_VALUE_STATUS_INVAL = -22, /// General error. @@ -230,7 +235,7 @@ enum bt_value_type { /// 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). @@ -287,7 +292,7 @@ An alternative to calling this function is to directly compare the 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} @@ -295,7 +300,7 @@ object pointer to the \ref bt_value_null variable. @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; } @@ -305,7 +310,7 @@ bool bt_value_is_null(const struct bt_value *object) 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} @@ -313,7 +318,7 @@ bool bt_value_is_null(const struct bt_value *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; } @@ -323,12 +328,12 @@ bool bt_value_is_bool(const struct bt_value *object) 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; } @@ -338,7 +343,7 @@ bool bt_value_is_integer(const struct bt_value *object) 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} @@ -347,7 +352,7 @@ bool bt_value_is_integer(const struct bt_value *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; } @@ -357,7 +362,7 @@ bool bt_value_is_float(const struct bt_value *object) 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} @@ -365,7 +370,7 @@ bool bt_value_is_float(const struct bt_value *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; } @@ -375,7 +380,7 @@ bool bt_value_is_string(const struct bt_value *object) 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} @@ -383,7 +388,7 @@ bool bt_value_is_string(const struct bt_value *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; } @@ -393,7 +398,7 @@ bool bt_value_is_array(const struct bt_value *object) 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} @@ -401,7 +406,7 @@ bool bt_value_is_array(const struct bt_value *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; } @@ -427,7 +432,7 @@ Freezing a value object is typically used to make it immutable after 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). @@ -446,12 +451,12 @@ extern enum bt_value_status bt_value_freeze(struct bt_value *object); @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. @@ -466,26 +471,25 @@ You can copy a frozen value object: the resulting copy is @prenotnull{object} @post On success, if the returned value object is not \ref bt_value_null, 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); /** @} */ @@ -498,7 +502,7 @@ extern bool bt_value_compare(const struct bt_value *object_a, /** @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. @@ -522,7 +526,7 @@ extern struct bt_value *bt_value_bool_create(void); @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 @@ -531,7 +535,7 @@ extern struct bt_value *bt_value_bool_create_init(bool val); @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} @@ -541,7 +545,7 @@ extern struct bt_value *bt_value_bool_create_init(bool 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 @@ -550,7 +554,7 @@ extern enum bt_value_status bt_value_bool_get( @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. @@ -561,7 +565,7 @@ extern enum bt_value_status bt_value_bool_get( value object. */ extern enum bt_value_status bt_value_bool_set(struct bt_value *bool_obj, - bool val); + bt_bool val); /** @} */ @@ -607,7 +611,7 @@ extern struct bt_value *bt_value_integer_create_init(int64_t 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} @@ -627,7 +631,7 @@ extern enum bt_value_status bt_value_integer_get( @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. @@ -684,7 +688,7 @@ extern struct bt_value *bt_value_float_create_init(double val); @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} @@ -704,7 +708,7 @@ extern enum bt_value_status bt_value_float_get( @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. @@ -767,7 +771,7 @@ returned string is \em not transferred to the caller. @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} @@ -789,7 +793,7 @@ 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 One of #bt_value_status values. +@returns Status code. @prenotnull{string_obj} @prenotnull{val} @@ -839,14 +843,14 @@ extern struct bt_value *bt_value_array_create(void); @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. @@ -855,7 +859,7 @@ extern int bt_value_array_size(const struct bt_value *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); +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 @@ -868,13 +872,14 @@ extern bool bt_value_array_is_empty(const struct bt_value *array_obj); @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 On success, if the returned value object is not \ref bt_value_null, 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 @@ -883,7 +888,7 @@ extern struct bt_value *bt_value_array_get(const struct bt_value *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} @@ -918,7 +923,7 @@ 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 One of #bt_value_status values. +@returns Status code. @prenotnull{array_obj} @pre \p array_obj is an array value object. @@ -929,7 +934,7 @@ value object before appending it. 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 @@ -940,7 +945,7 @@ 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 One of #bt_value_status values. +@returns Status code. @prenotnull{array_obj} @pre \p array_obj is an array value object. @@ -963,7 +968,7 @@ 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 One of #bt_value_status values. +@returns Status code. @prenotnull{array_obj} @pre \p array_obj is an array value object. @@ -988,7 +993,7 @@ 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 One of #bt_value_status values. +@returns Status code. @prenotnull{array_obj} @pre \p array_obj is an array value object. @@ -1011,7 +1016,7 @@ object before appending it. @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. @@ -1033,7 +1038,7 @@ object before appending it. @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. @@ -1056,12 +1061,13 @@ extern enum bt_value_status bt_value_array_append_empty_map( \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 On success, if the replaced value object is not \ref bt_value_null, its reference count is decremented. @@ -1070,7 +1076,7 @@ extern enum bt_value_status bt_value_array_append_empty_map( @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); /** @} */ @@ -1105,13 +1111,13 @@ extern struct bt_value *bt_value_map_create(void); @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. @@ -1119,7 +1125,7 @@ extern int bt_value_map_size(const struct bt_value *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); +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 @@ -1134,7 +1140,6 @@ extern bool bt_value_map_is_empty(const struct bt_value *map_obj); @prenotnull{key} @pre \p map_obj is a map value object. @postrefcountsame{map_obj} - @post On success, if the returned value object is not \ref bt_value_null, its reference count is incremented. */ @@ -1145,22 +1150,22 @@ extern struct bt_value *bt_value_map_get(const struct bt_value *map_obj, @brief User function type to use with bt_value_map_foreach(). \p object is a weak reference: 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); /** @@ -1168,18 +1173,19 @@ typedef bool (* bt_value_map_foreach_cb)(const char *key, map value object \p map_obj. The value object passed to the user function is a weak reference: -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. @@ -1199,8 +1205,8 @@ extern enum bt_value_status bt_value_map_foreach( @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} @@ -1208,7 +1214,7 @@ extern enum bt_value_status bt_value_map_foreach( @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); /** @@ -1227,7 +1233,7 @@ On success, \p key is copied. 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} @@ -1269,7 +1275,7 @@ On success, \p key is copied. 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} @@ -1281,7 +1287,7 @@ On success, \p key is copied. 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 @@ -1297,7 +1303,7 @@ On success, \p key is copied. 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} @@ -1325,7 +1331,7 @@ On success, \p key is copied. 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} @@ -1353,7 +1359,7 @@ On success, \p val and \p key are copied. 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} @@ -1381,7 +1387,7 @@ On success, \p key is copied. 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} @@ -1408,7 +1414,7 @@ On success, \p key is copied. 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} @@ -1435,28 +1441,28 @@ value objects. 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, @@ -1464,7 +1470,7 @@ The extended object is (JSON representation): "return": 17.88, "comma": "," } -@endcode +@endverbatim @param[in] base_map_obj Base map value object with initial entries. @@ -1493,4 +1499,4 @@ extern struct bt_value *bt_value_map_extend(struct bt_value *base_map_obj, } #endif -#endif /* _BABELTRACE_VALUES_H */ +#endif /* BABELTRACE_VALUES_H */