X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace%2Fctf-ir%2Ffield-types.h;h=7ae3ae55bbd3506392bd70dd90da09901bb67971;hb=96e8f959f3f895366c26f945c418a006e6ea397c;hp=87ef957886307bb9b1d1215e8516f5177198d057;hpb=18fcd1c9a2c2ac031c2269cb2cb1b142beb2f233;p=babeltrace.git diff --git a/include/babeltrace/ctf-ir/field-types.h b/include/babeltrace/ctf-ir/field-types.h index 87ef9578..7ae3ae55 100644 --- a/include/babeltrace/ctf-ir/field-types.h +++ b/include/babeltrace/ctf-ir/field-types.h @@ -178,9 +178,10 @@ You cannot modify a frozen field type object: it is considered immutable, except for \link refs reference counting\endlink. @sa ctfirfields +@sa \ref ctfirfieldtypesexamples "Examples" @file -@brief CTF IR field type type and functions. +@brief CTF IR field types type and functions. @sa ctfirfieldtypes @addtogroup ctfirfieldtypes @@ -650,6 +651,7 @@ in the detailed description of this module). @prenotnull{field_type} @postrefcountsame{field_type} @postsuccessrefcountret1 +@post On success, the returned field type is not frozen. */ extern struct bt_ctf_field_type *bt_ctf_field_type_copy( struct bt_ctf_field_type *field_type); @@ -731,6 +733,7 @@ An integer field type has the following properties: @sa ctfirintfield @sa ctfirfieldtypes +@sa \ref ctfirfieldtypesexamples_intfieldtype "Examples" @addtogroup ctfirintfieldtype @{ @@ -1045,6 +1048,7 @@ A floating point number field type has the following properties: @sa ctfirfloatfield @sa ctfirfieldtypes +@sa \ref ctfirfieldtypesexamples_floatfieldtype "Examples" @addtogroup ctfirfloatfieldtype @{ @@ -1172,6 +1176,36 @@ extern int bt_ctf_field_type_floating_point_set_mantissa_digits( /** @} */ +struct bt_ctf_field_type_enumeration_mapping_iterator * + bt_ctf_field_type_enumeration_find_mappings_by_name( + struct bt_ctf_field_type *type, + const char *name); + +struct bt_ctf_field_type_enumeration_mapping_iterator * + bt_ctf_field_type_enumeration_find_mappings_by_signed_value( + struct bt_ctf_field_type *type, + int64_t value); + +struct bt_ctf_field_type_enumeration_mapping_iterator * + bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value( + struct bt_ctf_field_type *type, + uint64_t value); + +int bt_ctf_field_type_enumeration_mapping_iterator_get_name( + struct bt_ctf_field_type_enumeration_mapping_iterator *iter, + const char **mapping_name); + +int bt_ctf_field_type_enumeration_mapping_iterator_get_signed( + struct bt_ctf_field_type_enumeration_mapping_iterator *iter, + const char **mapping_name, int64_t *lower, int64_t *upper); + +int bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned( + struct bt_ctf_field_type_enumeration_mapping_iterator *iter, + const char **mapping_name, uint64_t *lower, uint64_t *upper); + +int bt_ctf_field_type_enumeration_mapping_iterator_next( + struct bt_ctf_field_type_enumeration_mapping_iterator *iter); + /** @defgroup ctfirenumfieldtype CTF IR enumeration field type @ingroup ctfirfieldtypes @@ -1201,8 +1235,8 @@ bt_ctf_field_type_enumeration_add_mapping() or bt_ctf_field_type_enumeration_add_mapping_unsigned(), depending on the signedness of the wrapped @intft. -Many mappings can share the same name, but the ranges of a given -enumeration field type must not overlap. For example, +Many mappings can share the same name, and the ranges of a given +enumeration field type are allowed to overlap. For example, this is a valid set of mappings: @verbatim @@ -1212,7 +1246,7 @@ CHERRY -> [ 25, 34] APPLE -> [ 55, 55] @endverbatim -The following set of mappings is \em not valid, however: +The following set of mappings is also valid: @verbatim APPLE -> [ 3, 19] @@ -1282,6 +1316,10 @@ struct bt_ctf_field_type *bt_ctf_field_type_enumeration_get_container_type( extern int bt_ctf_field_type_enumeration_get_mapping_count( struct bt_ctf_field_type *enum_field_type); +extern int bt_ctf_field_type_enumeration_get_mapping_name( + struct bt_ctf_field_type *enum_field_type, int index, + const char **name); + /** @brief Returns the signed mapping of the @enumft \p enum_field_type at index \p index. @@ -1316,11 +1354,11 @@ On success, \p enum_field_type remains the sole owner of \p *name. bt_ctf_field_type_enumeration_get_mapping_count()). @postrefcountsame{enum_field_type} -@sa bt_ctf_field_type_enumeration_get_mapping_unsigned(): Returns the - unsigned mapping contained by a given enumeration field type +@sa bt_ctf_field_type_enumeration_get_mapping_signed(): Returns the + signed mapping contained by a given enumeration field type at a given index. */ -extern int bt_ctf_field_type_enumeration_get_mapping( +extern int bt_ctf_field_type_enumeration_get_mapping_signed( struct bt_ctf_field_type *enum_field_type, int index, const char **name, int64_t *range_begin, int64_t *range_end); @@ -1358,8 +1396,8 @@ On success, \p enum_field_type remains the sole owner of \p *name. bt_ctf_field_type_enumeration_get_mapping_count()). @postrefcountsame{enum_field_type} -@sa bt_ctf_field_type_enumeration_get_mapping(): Returns the - signed mapping contained by a given enumeration field type +@sa bt_ctf_field_type_enumeration_get_mapping_unsigned(): Returns the + unsigned mapping contained by a given enumeration field type at a given index. */ extern int bt_ctf_field_type_enumeration_get_mapping_unsigned( @@ -1367,75 +1405,6 @@ extern int bt_ctf_field_type_enumeration_get_mapping_unsigned( const char **name, uint64_t *range_begin, uint64_t *range_end); -/** @cond DOCUMENT */ -/* - * TODO: Document once we know what to do with this function (return - * the first match?). - */ -extern int bt_ctf_field_type_enumeration_get_mapping_index_by_name( - struct bt_ctf_field_type *enum_field_type, const char *name); -/** @endcond */ - -/** -@brief Returns the index of the signed mapping of the @enumft - \p field_type which contains the value \p value. - -The @intft wrapped by \p enum_field_type, as returned by -bt_ctf_field_type_enumeration_get_container_type(), must be -\b signed to use this function. - -@param[in] enum_field_type Enumeration field type of which to get - the index of the mapping which contains - \p value. -@param[in] value Value of the mapping to find. -@returns Index of the mapping of - \p enum_field_type which contains - \p value, or a negative value if the - function cannot find such a mapping or - on error. - -@prenotnull{enum_field_type} -@preisenumft{enum_field_type} -@pre The wrapped @intft of \p enum_field_type is signed. -@postrefcountsame{enum_field_type} - -@sa bt_ctf_field_type_enumeration_get_mapping_index_by_unsigned_value(): - Finds the index of an unsigned mapping of a given enumeration - field type by value. -*/ -extern int bt_ctf_field_type_enumeration_get_mapping_index_by_value( - struct bt_ctf_field_type *enum_field_type, int64_t value); - -/** -@brief Returns the index of the unsigned mapping of the @enumft - \p field_type which contains the value \p value. - -The @intft wrapped by \p enum_field_type, as returned by -bt_ctf_field_type_enumeration_get_container_type(), must be -\b unsigned to use this function. - -@param[in] enum_field_type Enumeration field type of which to get - the index of the mapping which contains - \p value. -@param[in] value Value of the mapping to find. -@returns Index of the mapping of - \p enum_field_type which contains - \p value, or a negative value if the - function cannot find such a mapping or - on error. - -@prenotnull{enum_field_type} -@preisenumft{enum_field_type} -@pre The wrapped @intft of \p enum_field_type is unsigned. -@postrefcountsame{enum_field_type} - -@sa bt_ctf_field_type_enumeration_get_mapping_index_by_unsigned_value(): - Finds the index of a signed mapping of a given enumeration - field type by value. -*/ -extern int bt_ctf_field_type_enumeration_get_mapping_index_by_unsigned_value( - struct bt_ctf_field_type *enum_field_type, uint64_t value); - /** @brief Adds a mapping to the @enumft \p enum_field_type which maps the name \p name to the signed range \p range_begin (included) to @@ -1448,9 +1417,7 @@ The @intft wrapped by \p enum_field_type, as returned by bt_ctf_field_type_enumeration_get_container_type(), must be \b signed to use this function. -A mapping in \p enum_field_type can exist with the name \p name, but -there must be no overlap amongst all the ranges of -\p enum_field_type. +A mapping in \p enum_field_type can exist with the name \p name. @param[in] enum_field_type Enumeration field type to which to add a mapping. @@ -1488,9 +1455,7 @@ The @intft wrapped by \p enum_field_type, as returned by bt_ctf_field_type_enumeration_get_container_type(), must be \b unsigned to use this function. -A mapping in \p enum_field_type can exist with the name \p name, but -there must be no overlap amongst all the ranges of -\p enum_field_type. +A mapping in \p enum_field_type can exist with the name \p name. @param[in] enum_field_type Enumeration field type to which to add a mapping.