X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace%2Fvalues.h;h=89894f69ee5252bbd490d212bbf7ec9fe6f05c8b;hb=094ff7c009937bb23c056333baffe734308a6b06;hp=93622a86e17dea9a91304e1274c33cee5d369bbe;hpb=cbcfcefc450184b8c76e94e4e90f3e32d6cf71d7;p=babeltrace.git diff --git a/include/babeltrace/values.h b/include/babeltrace/values.h index 93622a86..89894f69 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,8 +27,12 @@ */ #include -#include #include + +/* For bt_bool */ +#include + +/* For bt_get() */ #include #ifdef __cplusplus @@ -40,6 +44,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: @@ -68,14 +76,6 @@ values of #bt_value_status. You can create a deep copy of any value object with bt_value_copy(). You can compare two value objects with bt_value_compare(). -You can \em freeze a value object with bt_value_freeze(). You can get -the raw value of a frozen value object, but you cannot modify it. -Reference counting still works on frozen value objects. You can copy -a frozen value object: the returned copy is not frozen. You can also -compare a frozen value object to another value object (frozen or not). -Freezing a value object is typically used to make it immutable after -it's built by its initial owner. - The following matrix shows some categorized value object functions to use for each value object type: @@ -170,14 +170,11 @@ to use for each value object type: @brief Status codes. */ enum bt_value_status { - /// Value object cannot be altered because it's frozen. - BT_VALUE_STATUS_FROZEN = -4, - - /// Operation cancelled. - BT_VALUE_STATUS_CANCELLED = -3, + /// Operation canceled. + BT_VALUE_STATUS_CANCELED = -3, /* -22 for compatibility with -EINVAL */ - /// Invalid arguments. + /// Invalid argument. BT_VALUE_STATUS_INVAL = -22, /// General error. @@ -231,7 +228,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). @@ -288,7 +285,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} @@ -296,7 +293,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; } @@ -306,7 +303,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} @@ -314,7 +311,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; } @@ -324,12 +321,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; } @@ -339,7 +336,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} @@ -348,7 +345,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; } @@ -358,7 +355,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} @@ -366,7 +363,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; } @@ -376,7 +373,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} @@ -384,7 +381,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; } @@ -394,7 +391,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} @@ -402,7 +399,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; } @@ -414,46 +411,6 @@ bool bt_value_is_map(const struct bt_value *object) @{ */ -/** -@brief Recursively freezes the value object \p object. - -You cannot modify a frozen value object: it is considered immutable. -Reference counting still works on a frozen value object, however: you -can pass a frozen value object to bt_get() and bt_put(). - -If \p object is an array value object or a map value object, this -function also freezes all its children recursively. - -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 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} -@postrefcountsame{object} -@post On success, \p object and all its children - are frozen. - -@sa bt_value_is_frozen(): Returns whether or not a value object is - frozen. -*/ -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. - -@prenotnull{object} -@postrefcountsame{object} -*/ -extern bool bt_value_is_frozen(const struct bt_value *object); - /** @brief Creates a \em deep copy of the value object \p object. @@ -473,19 +430,19 @@ 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 +455,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 +479,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 @@ -541,7 +498,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 @@ -561,7 +518,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); /** @} */ @@ -839,14 +796,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 +812,10 @@ 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); + +extern struct bt_value *bt_value_array_borrow(const struct bt_value *array_obj, + uint64_t index); /** @brief Returns the value object contained in the array value object @@ -874,8 +834,12 @@ extern bool bt_value_array_is_empty(const struct bt_value *array_obj); \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); +static inline +struct bt_value *bt_value_array_get(const struct bt_value *array_obj, + uint64_t index) +{ + return bt_get(bt_value_array_borrow(array_obj, index)); +} /** @brief Appends the value object \p element_obj to the array value @@ -930,7 +894,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 @@ -1072,7 +1036,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); /** @} */ @@ -1107,13 +1071,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. @@ -1121,7 +1085,10 @@ 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); + +extern struct bt_value *bt_value_map_borrow(const struct bt_value *map_obj, + const char *key); /** @brief Returns the value object associated with the key \p key within @@ -1139,8 +1106,12 @@ extern bool bt_value_map_is_empty(const struct bt_value *map_obj); @post On success, if the returned value object is not \ref bt_value_null, its reference count is incremented. */ -extern struct bt_value *bt_value_map_get(const struct bt_value *map_obj, - const char *key); +static inline +struct bt_value *bt_value_map_get(const struct bt_value *map_obj, + const char *key) +{ + return bt_get(bt_value_map_borrow(map_obj, key)); +} /** @brief User function type to use with bt_value_map_foreach(). @@ -1148,20 +1119,20 @@ extern struct bt_value *bt_value_map_get(const struct bt_value *map_obj, \p object is a weak reference: 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. +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); /** @@ -1175,15 +1146,15 @@ 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 Status code. More - specifically, #BT_VALUE_STATUS_CANCELLED is - returned if the loop was cancelled by the user + specifically, #BT_VALUE_STATUS_CANCELED is + returned if the loop was canceled by the user function. @prenotnull{map_obj} @@ -1201,8 +1172,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} @@ -1210,7 +1181,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); /** @@ -1283,7 +1254,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 @@ -1495,4 +1466,4 @@ extern struct bt_value *bt_value_map_extend(struct bt_value *base_map_obj, } #endif -#endif /* _BABELTRACE_VALUES_H */ +#endif /* BABELTRACE_VALUES_H */