X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace%2Fctf-ir%2Ffield-types.h;h=3e35a8d04fa6135f5243b307f6d45782afb4f1af;hb=544d0515ffa2d011247e4f1d7cad5770b8ec7033;hp=9bca9bc6f8e34342686452986083b31802ea0076;hpb=4089d5a6a9f14067306f1f681dd27f5797d3c289;p=babeltrace.git diff --git a/include/babeltrace/ctf-ir/field-types.h b/include/babeltrace/ctf-ir/field-types.h index 9bca9bc6..3e35a8d0 100644 --- a/include/babeltrace/ctf-ir/field-types.h +++ b/include/babeltrace/ctf-ir/field-types.h @@ -31,6 +31,7 @@ */ #include +#include #ifdef __cplusplus extern "C" { @@ -96,49 +97,49 @@ The standard CTF field types are: CTF IR field which you can create from this field type - #BT_CTF_TYPE_ID_INTEGER + #BT_CTF_FIELD_TYPE_ID_INTEGER \ref ctfirintfieldtype \ref ctfirintfield - #BT_CTF_TYPE_ID_FLOAT + #BT_CTF_FIELD_TYPE_ID_FLOAT \ref ctfirfloatfieldtype \ref ctfirfloatfield - #BT_CTF_TYPE_ID_ENUM + #BT_CTF_FIELD_TYPE_ID_ENUM \ref ctfirenumfieldtype \ref ctfirenumfield - #BT_CTF_TYPE_ID_STRING + #BT_CTF_FIELD_TYPE_ID_STRING \ref ctfirstringfieldtype \ref ctfirstringfield - #BT_CTF_TYPE_ID_STRUCT + #BT_CTF_FIELD_TYPE_ID_STRUCT \ref ctfirstructfieldtype \ref ctfirstructfield - #BT_CTF_TYPE_ID_ARRAY + #BT_CTF_FIELD_TYPE_ID_ARRAY \ref ctfirarrayfieldtype \ref ctfirarrayfield - #BT_CTF_TYPE_ID_SEQUENCE + #BT_CTF_FIELD_TYPE_ID_SEQUENCE \ref ctfirseqfieldtype \ref ctfirseqfield - #BT_CTF_TYPE_ID_VARIANT + #BT_CTF_FIELD_TYPE_ID_VARIANT \ref ctfirvarfieldtype \ref ctfirvarfield Each field type has its own type ID (see -#bt_ctf_type_id). You get the type ID of a field type object +#bt_ctf_field_type_id). You get the type ID of a field type object with bt_ctf_field_type_get_type_id(). You can get a deep copy of a field type with bt_ctf_field_type_copy(). @@ -174,10 +175,14 @@ The following functions can \em freeze field type objects: - bt_ctf_event_create() freezes the root field types of its event class parameter and of ther parent stream class of this event class. +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 @@ -194,13 +199,14 @@ struct bt_ctf_event_class; struct bt_ctf_event; struct bt_ctf_field; struct bt_ctf_field_path; +struct bt_ctf_field_type_enumeration_mapping_iterator; /** @cond DOCUMENT */ /* * Babeltrace 1.x enumerations that were also used in CTF writer's API. * They are left here for backward compatibility reasons, but - * enum bt_ctf_type_id and enum bt_ctf_string_encoding should be used + * enum bt_ctf_field_type_id and enum bt_ctf_string_encoding should be used * in new code. Both new enumerations are compatible with their legacy * counterpart. */ @@ -269,37 +275,37 @@ enum bt_ctf_scope { /** @brief Type ID of a @ft. */ -enum bt_ctf_type_id { +enum bt_ctf_field_type_id { /// Unknown, used for errors. - BT_CTF_TYPE_ID_UNKNOWN = CTF_TYPE_UNKNOWN, + BT_CTF_FIELD_TYPE_ID_UNKNOWN = CTF_TYPE_UNKNOWN, /// \ref ctfirintfieldtype - BT_CTF_TYPE_ID_INTEGER = CTF_TYPE_INTEGER, + BT_CTF_FIELD_TYPE_ID_INTEGER = CTF_TYPE_INTEGER, /// \ref ctfirfloatfieldtype - BT_CTF_TYPE_ID_FLOAT = CTF_TYPE_FLOAT, + BT_CTF_FIELD_TYPE_ID_FLOAT = CTF_TYPE_FLOAT, /// \ref ctfirenumfieldtype - BT_CTF_TYPE_ID_ENUM = CTF_TYPE_ENUM, + BT_CTF_FIELD_TYPE_ID_ENUM = CTF_TYPE_ENUM, /// \ref ctfirstringfieldtype - BT_CTF_TYPE_ID_STRING = CTF_TYPE_STRING, + BT_CTF_FIELD_TYPE_ID_STRING = CTF_TYPE_STRING, /// \ref ctfirstructfieldtype - BT_CTF_TYPE_ID_STRUCT = CTF_TYPE_STRUCT, + BT_CTF_FIELD_TYPE_ID_STRUCT = CTF_TYPE_STRUCT, /// @cond DOCUMENT BT_CTF_TYPE_ID_UNTAGGED_VARIANT = CTF_TYPE_UNTAGGED_VARIANT, /// @endcond /// \ref ctfirarrayfieldtype - BT_CTF_TYPE_ID_ARRAY = CTF_TYPE_ARRAY, + BT_CTF_FIELD_TYPE_ID_ARRAY = CTF_TYPE_ARRAY, /// \ref ctfirseqfieldtype - BT_CTF_TYPE_ID_SEQUENCE = CTF_TYPE_SEQUENCE, + BT_CTF_FIELD_TYPE_ID_SEQUENCE = CTF_TYPE_SEQUENCE, /// \ref ctfirvarfieldtype - BT_CTF_TYPE_ID_VARIANT = CTF_TYPE_VARIANT, + BT_CTF_FIELD_TYPE_ID_VARIANT = CTF_TYPE_VARIANT, /// Number of enumeration entries. BT_CTF_NR_TYPE_IDS = NR_CTF_TYPES, @@ -310,12 +316,12 @@ enum bt_ctf_type_id { @param[in] field_type Field type of which to get the type ID. @returns Type ID of \p field_type, - or #BT_CTF_TYPE_ID_UNKNOWN on error. + or #BT_CTF_FIELD_TYPE_ID_UNKNOWN on error. @prenotnull{field_type} @postrefcountsame{field_type} -@sa #bt_ctf_type_id: CTF IR field type ID. +@sa #bt_ctf_field_type_id: CTF IR field type ID. @sa bt_ctf_field_type_is_integer(): Returns whether or not a given field type is a @intft. @sa bt_ctf_field_type_is_floating_point(): Returns whether or not a @@ -333,7 +339,7 @@ enum bt_ctf_type_id { @sa bt_ctf_field_type_is_variant(): Returns whether or not a given field type is a @varft. */ -extern enum bt_ctf_type_id bt_ctf_field_type_get_type_id( +extern enum bt_ctf_field_type_id bt_ctf_field_type_get_type_id( struct bt_ctf_field_type *field_type); /** @@ -647,6 +653,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); @@ -696,13 +703,13 @@ An integer field type has the following properties: integer fields Specified at creation bt_ctf_field_type_integer_get_size() - None: specified at creation (bt_ctf_field_type_integer_create()) + bt_ctf_field_type_integer_set_size() Signedness of the described integer fields Unsigned - bt_ctf_field_type_integer_get_signed() - bt_ctf_field_type_integer_set_signed() + bt_ctf_field_type_integer_is_signed() + bt_ctf_field_type_integer_set_is_signed() Preferred display base of the described @@ -721,13 +728,14 @@ An integer field type has the following properties: Mapped \link ctfirclockclass CTF IR clock class\endlink None - bt_ctf_field_type_integer_get_mapped_clock() - bt_ctf_field_type_integer_set_mapped_clock() + bt_ctf_field_type_integer_get_mapped_clock_class() + bt_ctf_field_type_integer_set_mapped_clock_class() @sa ctfirintfield @sa ctfirfieldtypes +@sa \ref ctfirfieldtypesexamples_intfieldtype "Examples" @addtogroup ctfirintfieldtype @{ @@ -757,6 +765,10 @@ enum bt_ctf_integer_base { @brief Creates a default @intft with \p size bits as the storage size of the @intfields it describes. +You can change the storage size of the integer fields described by +the created integer field type later with +bt_ctf_field_type_integer_set_size(). + @param[in] size Storage size (bits) of the described integer fields. @returns Created integer field type, or \c NULL on error. @@ -780,10 +792,36 @@ extern struct bt_ctf_field_type *bt_ctf_field_type_integer_create( @prenotnull{int_field_type} @preisintft{int_field_type} @postrefcountsame{int_field_type} + +@sa bt_ctf_field_type_integer_set_size(): Sets the storage size of the + integer fields described by a given integer field type. */ extern int bt_ctf_field_type_integer_get_size( struct bt_ctf_field_type *int_field_type); +/** +@brief Sets the storage size, in bits, of the @intfields described by + the @intft \p int_field_type. + +@param[in] int_field_type Integer field type which describes the + integer fields of which to set the + storage size. +@param[in] size Storage size (bits) of the integer fields + described by \p int_field_type. +@returns 0 on success, or a negative value on error. + +@prenotnull{int_field_type} +@preisintft{int_field_type} +@prehot{int_field_type} +@pre \p size is greater than 0 and lesser than or equal to 64. +@postrefcountsame{int_field_type} + +@sa bt_ctf_field_type_integer_get_size(): Returns the storage size of + the integer fields described by a given integer field type. +*/ +extern int bt_ctf_field_type_integer_set_size( + struct bt_ctf_field_type *int_field_type, size_t size); + /** @brief Returns whether or not the @intfields described by the @intft \p int_field_type are signed. @@ -800,12 +838,15 @@ extern int bt_ctf_field_type_integer_get_size( @preisintft{int_field_type} @postrefcountsame{int_field_type} -@sa bt_ctf_field_type_integer_set_signed(): Sets the signedness of the +@sa bt_ctf_field_type_integer_set_is_signed(): Sets the signedness of the integer fields described by a given integer field type. */ -extern int bt_ctf_field_type_integer_get_signed( +extern int bt_ctf_field_type_integer_is_signed( struct bt_ctf_field_type *int_field_type); +/* Pre-2.0 CTF writer compatibility */ +#define bt_ctf_field_type_integer_get_signed bt_ctf_field_type_integer_is_signed + /** @brief Sets whether or not the @intfields described by the @intft \p int_field_type are signed. @@ -822,14 +863,17 @@ extern int bt_ctf_field_type_integer_get_signed( @preisintft{int_field_type} @prehot{int_field_type} @pre \p is_signed is 0 or 1. -@postrefcountsame{event_class} +@postrefcountsame{int_field_type} -@sa bt_ctf_field_type_integer_get_signed(): Returns the signedness of +@sa bt_ctf_field_type_integer_is_signed(): Returns the signedness of the integer fields described by a given integer field type. */ -extern int bt_ctf_field_type_integer_set_signed( +extern int bt_ctf_field_type_integer_set_is_signed( struct bt_ctf_field_type *int_field_type, int is_signed); +/* Pre-2.0 CTF writer compatibility */ +#define bt_ctf_field_type_integer_set_signed bt_ctf_field_type_integer_set_is_signed + /** @brief Returns the preferred display base (radix) of the @intfields described by the @intft \p int_field_type. @@ -951,15 +995,15 @@ This mapped clock class is only indicative. @postrefcountsame{int_field_type} @postsuccessrefcountretinc -@sa bt_ctf_field_type_integer_set_mapped_clock(): Sets the mapped +@sa bt_ctf_field_type_integer_set_mapped_clock_class(): Sets the mapped clock class of a given integer field type. */ -extern struct bt_ctf_clock *bt_ctf_field_type_integer_get_mapped_clock( +extern struct bt_ctf_clock_class *bt_ctf_field_type_integer_get_mapped_clock_class( struct bt_ctf_field_type *int_field_type); /** @brief Sets the \link ctfirclockclass CTF IR clock class\endlink mapped - to the @intft \p int_field_type to \p mapped_clock. + to the @intft \p int_field_type to \p clock_class. The mapped clock class, if any, indicates the class of the clock which an integer field described by \p int_field_type should sample or update. @@ -977,12 +1021,12 @@ This mapped clock class is only indicative. @postrefcountsame{int_field_type} @postsuccessrefcountinc{clock_class} -@sa bt_ctf_field_type_integer_get_mapped_clock(): Returns the mapped +@sa bt_ctf_field_type_integer_get_mapped_clock_class(): Returns the mapped clock class of a given integer field type. */ -extern int bt_ctf_field_type_integer_set_mapped_clock( +extern int bt_ctf_field_type_integer_set_mapped_clock_class( struct bt_ctf_field_type *int_field_type, - struct bt_ctf_clock *clock_class); + struct bt_ctf_clock_class *clock_class); /** @} */ @@ -1042,6 +1086,7 @@ A floating point number field type has the following properties: @sa ctfirfloatfield @sa ctfirfieldtypes +@sa \ref ctfirfieldtypesexamples_floatfieldtype "Examples" @addtogroup ctfirfloatfieldtype @{ @@ -1198,8 +1243,22 @@ 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, +You can find mappings by name or by value with the following find +operations: + +- bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the + mappings with a given name. +- bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(): + Finds the mappings which contain a given unsigned value in their + range. +- bt_ctf_field_type_enumeration_find_mappings_by_signed_value(): + Finds the mappings which contain a given signed value in their range. + +Those functions return a @enumftiter on the result set of the find +operation. + +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 @@ -1209,7 +1268,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] @@ -1221,6 +1280,7 @@ APPLE -> [ 30, 55] Here, the range of the second \c APPLE mapping overlaps the range of the \c CHERRY mapping. +@sa ctfirenumftmappingiter @sa ctfirenumfield @sa ctfirfieldtypes @@ -1276,7 +1336,7 @@ struct bt_ctf_field_type *bt_ctf_field_type_enumeration_get_container_type( @preisenumft{enum_field_type} @postrefcountsame{enum_field_type} */ -extern int bt_ctf_field_type_enumeration_get_mapping_count( +extern int64_t bt_ctf_field_type_enumeration_get_mapping_count( struct bt_ctf_field_type *enum_field_type); /** @@ -1291,7 +1351,7 @@ On success, \p enum_field_type remains the sole owner of \p *name. @param[in] enum_field_type Enumeration field type of which to get the mapping at index \p index. -­@param[in] index Index of the mapping to get from +@param[in] index Index of the mapping to get from \p enum_field_type. @param[out] name Returned name of the mapping at index \p index. @@ -1317,7 +1377,7 @@ On success, \p enum_field_type remains the sole owner of \p *name. unsigned 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); @@ -1333,7 +1393,7 @@ On success, \p enum_field_type remains the sole owner of \p *name. @param[in] enum_field_type Enumeration field type of which to get the mapping at index \p index. -­@param[in] index Index of the mapping to get from +@param[in] index Index of the mapping to get from \p enum_field_type. @param[out] name Returned name of the mapping at index \p index. @@ -1355,7 +1415,7 @@ 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 +@sa bt_ctf_field_type_enumeration_get_mapping_signed(): Returns the signed mapping contained by a given enumeration field type at a given index. */ @@ -1364,74 +1424,112 @@ 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. +@brief Finds the mappings of the @enumft \p enum_field_type which + are named \p name. -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. +This function returns an iterator on the result set of this find +operation. See \ref ctfirenumftmappingiter for more details. -@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 +@param[in] enum_field_type Enumeration field type of which to find + the mappings named \p name. +@param[in] name Name of the mappings to find in + \p enum_field_type. +@returns @enumftiter on the set of mappings named + \p name in \p enum_field_type, or + \c NULL if no mappings were found or on error. @prenotnull{enum_field_type} +@prenotnull{name} @preisenumft{enum_field_type} -@pre The wrapped @intft of \p enum_field_type is signed. @postrefcountsame{enum_field_type} +@postsuccessrefcountret1 +@post On success, the returned @enumftiter can iterate + on at least one mapping. -@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. +@sa bt_ctf_field_type_enumeration_find_mappings_by_signed_value(): Finds + the mappings of a given enumeration field type which contain + a given signed value in their range. +@sa bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(): Finds + the mappings of a given enumeration field type which contain + a given unsigned value in their range. */ -extern int bt_ctf_field_type_enumeration_get_mapping_index_by_value( - struct bt_ctf_field_type *enum_field_type, int64_t value); +extern struct bt_ctf_field_type_enumeration_mapping_iterator * +bt_ctf_field_type_enumeration_find_mappings_by_name( + struct bt_ctf_field_type *enum_field_type, + const char *name); /** -@brief Returns the index of the unsigned mapping of the @enumft - \p field_type which contains the value \p value. +@brief Finds the mappings of the @enumft \p enum_field_type which + contain the signed value \p value in their range. -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. +This function returns an iterator on the result set of this find +operation. See \ref ctfirenumftmappingiter for more details. -@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 +@param[in] enum_field_type Enumeration field type of which to find + the mappings which contain \p value. +@param[in] value Value to find in the ranges of the + mappings of \p enum_field_type. +@returns @enumftiter on the set of mappings of + \p enum_field_type which contain + \p value in their range, or \c NULL if + no mappings were found or on error. + +@prenotnull{enum_field_type} +@preisenumft{enum_field_type} +@postrefcountsame{enum_field_type} +@postsuccessrefcountret1 +@post On success, the returned @enumftiter can iterate + on at least one mapping. + +@sa bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the + mappings of a given enumeration field type which have a given + name. +@sa bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(): Finds + the mappings of a given enumeration field type which contain + a given unsigned value in their range. +*/ +extern struct bt_ctf_field_type_enumeration_mapping_iterator * +bt_ctf_field_type_enumeration_find_mappings_by_signed_value( + struct bt_ctf_field_type *enum_field_type, + int64_t value); + +/** +@brief Finds the mappings of the @enumft \p enum_field_type which + contain the unsigned value \p value in their range. + +This function returns an iterator on the result set of this find +operation. See \ref ctfirenumftmappingiter for more details. + +@param[in] enum_field_type Enumeration field type of which to find + the mappings which contain \p value. +@param[in] value Value to find in the ranges of the + mappings of \p enum_field_type. +@returns @enumftiter on the set of mappings of + \p enum_field_type which contain + \p value in their range, or \c NULL + if no mappings were found 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} +@postsuccessrefcountret1 +@post On success, the returned @enumftiter can iterate + on at least one mapping. -@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. +@sa bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the + mappings of a given enumeration field type which have a given + name. +@sa bt_ctf_field_type_enumeration_find_mappings_by_signed_value(): Finds + the mappings of a given enumeration field type which contain + a given unsigned value in their range. */ -extern int bt_ctf_field_type_enumeration_get_mapping_index_by_unsigned_value( - struct bt_ctf_field_type *enum_field_type, uint64_t value); +extern struct bt_ctf_field_type_enumeration_mapping_iterator * +bt_ctf_field_type_enumeration_find_mappings_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 @@ -1445,9 +1543,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. @@ -1461,6 +1557,7 @@ there must be no overlap amongst all the ranges of @prenotnull{enum_field_type} @prenotnull{name} +@prehot{enum_field_type} @preisenumft{enum_field_type} @pre The wrapped @intft of \p enum_field_type is signed. @pre \p range_end is greater than or equal to \p range_begin. @@ -1485,9 +1582,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. @@ -1501,6 +1596,7 @@ there must be no overlap amongst all the ranges of @prenotnull{enum_field_type} @prenotnull{name} +@prehot{enum_field_type} @preisenumft{enum_field_type} @pre The wrapped @intft of \p enum_field_type is unsigned. @pre \p range_end is greater than or equal to \p range_begin. @@ -1515,6 +1611,167 @@ extern int bt_ctf_field_type_enumeration_add_mapping_unsigned( /** @} */ +/** +@defgroup ctfirenumftmappingiter CTF IR enumeration field type mapping iterator +@ingroup ctfirenumfieldtype +@brief CTF IR enumeration field type mapping iterator. + +@code +#include +@endcode + +A CTF IR enumeration field type mapping +iterator is an iterator on @enumft mappings. + +You can get an enumeration mapping iterator from one of the following +functions: + +- Find operations of an @enumft object: + - bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the + mappings with a given name. + - bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(): + Finds the mappings which contain a given unsigned value in their + range. + - bt_ctf_field_type_enumeration_find_mappings_by_signed_value(): + Finds the mappings which contain a given signed value in their range. +- bt_ctf_field_enumeration_get_mappings(): Finds the mappings in the + @enumft of an @enumfield containing its current integral value in + their range. + +Those functions guarantee that the returned iterator can iterate on +at least one mapping. Otherwise, they return \c NULL. + +You can get the name and the range of a mapping iterator's current +mapping with +bt_ctf_field_type_enumeration_mapping_iterator_get_signed() +or +bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned(), +depending on the signedness of the @intft wrapped by the +@enumft. If you only need the name of the current mapping, you can +use any of the two functions and set the \p range_begin and \p range_end +parameters to \c NULL. + +You can advance an enumeration field type mapping iterator to the next +mapping with +bt_ctf_field_type_enumeration_mapping_iterator_next(). This +function returns a negative value when you reach the end of the +result set. + +As with any Babeltrace object, CTF IR enumeration field type mapping +iterator objects have reference +counts. See \ref refs to learn more about the reference counting +management of Babeltrace objects. + +@sa ctfirenumfieldtype + +@addtogroup ctfirenumftmappingiter +@{ +*/ + +/** +@struct bt_ctf_field_type_enumeration_mapping_iterator +@brief A CTF IR enumeration field type mapping iterator. +@sa ctfirenumftmappingiter +*/ + +/** +@brief Returns the name and the range of the current (signed) mapping + of the @enumftiter \p iter. + +If one of \p range_begin or \p range_end is not \c NULL, the @intft +wrapped by the @enumft from which \p iter was obtained, as returned by +bt_ctf_field_type_enumeration_get_container_type(), must be +\b signed to use this function. Otherwise, if you only need to get the +name of the current mapping, set \p range_begin and \p range_end to +\c NULL. + +On success, if \p name is not \c NULL, \p *name remains valid as long +as \p iter exists and +bt_ctf_field_type_enumeration_mapping_iterator_next() is +\em not called on \p iter. + +@param[in] iter Enumeration field type mapping iterator + of which to get the range of the current + mapping. +@param[out] name Returned name of the current mapping of + \p iter (can be \c NULL to ignore). +@param[out] range_begin Returned beginning of the range + (included) of the current mapping of + \p iter (can be \c NULL to ignore). +@param[out] range_end Returned end of the range + (included) of the current mapping of + \p iter (can be \c NULL to ignore). +@returns 0 on success, or a negative value on error. + +@prenotnull{iter} +@postrefcountsame{iter} + +@sa bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned(): + Returns the name and the unsigned range of the current mapping + of a given enumeration field type mapping iterator. +*/ +extern int bt_ctf_field_type_enumeration_mapping_iterator_get_signed( + struct bt_ctf_field_type_enumeration_mapping_iterator *iter, + const char **name, int64_t *range_begin, int64_t *range_end); + +/** +@brief Returns the name and the range of the current (unsigned) mapping + of the @enumftiter \p iter. + +If one of \p range_begin or \p range_end is not \c NULL, the @intft +wrapped by the @enumft from which \p iter was obtained, as returned by +bt_ctf_field_type_enumeration_get_container_type(), must be +\b unsigned to use this function. Otherwise, if you only need to get the +name of the current mapping, set \p range_begin and \p range_end to +\c NULL. + +On success, if \p name is not \c NULL, \p *name remains valid as long +as \p iter exists and +bt_ctf_field_type_enumeration_mapping_iterator_next() is +\em not called on \p iter. + +@param[in] iter Enumeration field type mapping iterator + of which to get the range of the current + mapping. +@param[out] name Returned name of the current mapping of + \p iter (can be \c NULL to ignore). +@param[out] range_begin Returned beginning of the range + (included) of the current mapping of + \p iter (can be \c NULL to ignore). +@param[out] range_end Returned end of the range + (included) of the current mapping of + \p iter (can be \c NULL to ignore). +@returns 0 on success, or a negative value on error. + +@prenotnull{iter} +@postrefcountsame{iter} + +@sa + bt_ctf_field_type_enumeration_mapping_iterator_get_signed(): + Returns the name and the signed range of the current mapping of + a given enumeration field type mapping iterator. +*/ +extern int bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned( + struct bt_ctf_field_type_enumeration_mapping_iterator *iter, + const char **name, uint64_t *range_begin, uint64_t *range_end); + +/** +@brief Advances the @enumftiter \p iter to the next mapping. + +@param[in] iter Enumeration field type mapping iterator to + advance. +@returns 0 on success, or a negative value on error or + when you reach the end of the set. + +@prenotnull{iter} +@postrefcountsame{iter} +*/ +extern int bt_ctf_field_type_enumeration_mapping_iterator_next( + struct bt_ctf_field_type_enumeration_mapping_iterator *iter); + +/** @} */ + /** @defgroup ctfirstringfieldtype CTF IR string field type @ingroup ctfirfieldtypes @@ -1664,7 +1921,7 @@ extern struct bt_ctf_field_type *bt_ctf_field_type_structure_create(void); @preisstructft{struct_field_type} @postrefcountsame{struct_field_type} */ -extern int bt_ctf_field_type_structure_get_field_count( +extern int64_t bt_ctf_field_type_structure_get_field_count( struct bt_ctf_field_type *struct_field_type); /** @@ -2143,7 +2400,7 @@ extern struct bt_ctf_field_path *bt_ctf_field_type_variant_get_tag_field_path( @preisvarft{variant_field_type} @postrefcountsame{variant_field_type} */ -extern int bt_ctf_field_type_variant_get_field_count( +extern int64_t bt_ctf_field_type_variant_get_field_count( struct bt_ctf_field_type *variant_field_type); /**