-/** @} */
-
-/** @} */
-
-/**
-@defgroup ctfirintfieldtype CTF IR integer field type
-@ingroup ctfirfieldtypes
-@brief CTF IR integer field type.
-
-@code
-#include <babeltrace/ctf-ir/field-types.h>
-@endcode
-
-A CTF IR <strong><em>integer field type</em></strong> is a field type that
-you can use to create concrete @intfield objects.
-
-You can create an integer field type
-with bt_field_type_integer_create().
-
-An integer field type has the following properties:
-
-<table>
- <tr>
- <th>Property
- <th>Value at creation
- <th>Getter
- <th>Setter
- </tr>
- <tr>
- <td>\b Alignment (bits) of the described integer fields
- <td>1
- <td>bt_field_type_get_alignment()
- <td>bt_field_type_set_alignment()
- </tr>
- <tr>
- <td><strong>Byte order</strong> of the described integer fields
- <td>#BT_BYTE_ORDER_NATIVE
- <td>bt_field_type_get_byte_order()
- <td>bt_field_type_set_byte_order()
- </tr>
- <tr>
- <td><strong>Storage size</strong> (bits) of the described
- integer fields
- <td>Specified at creation
- <td>bt_field_type_integer_get_size()
- <td>bt_field_type_integer_set_size()
- </tr>
- <tr>
- <td><strong>Signedness</strong> of the described integer fields
- <td>Unsigned
- <td>bt_field_type_integer_is_signed()
- <td>bt_field_type_integer_set_is_signed()
- </tr>
- <tr>
- <td><strong>Preferred display base</strong> of the described
- integer fields
- <td>#BT_INTEGER_BASE_DECIMAL
- <td>bt_field_type_integer_get_base()
- <td>bt_field_type_integer_set_base()
- </tr>
- <tr>
- <td>\b Encoding of the described integer fields
- <td>#BT_STRING_ENCODING_NONE
- <td>bt_field_type_integer_get_encoding()
- <td>bt_field_type_integer_set_encoding()
- </tr>
- <tr>
- <td><strong>Mapped
- \link ctfirclockclass CTF IR clock class\endlink</strong>
- <td>None
- <td>bt_field_type_integer_get_mapped_clock_class()
- <td>bt_field_type_integer_set_mapped_clock_class()
- </tr>
-</table>
-
-@sa ctfirintfield
-@sa ctfirfieldtypes
-@sa \ref ctfirfieldtypesexamples_intfieldtype "Examples"
-
-@addtogroup ctfirintfieldtype
-@{
-*/
-
-/**
-@brief Preferred display base (radix) of a @intft.
-*/
-enum bt_integer_base {
- /// Unknown, used for errors.
- BT_INTEGER_BASE_UNKNOWN = -1,
-
- /// Unspecified by the tracer.
- BT_INTEGER_BASE_UNSPECIFIED = 0,
-
- /// Binary.
- BT_INTEGER_BASE_BINARY = 2,
-
- /// Octal.
- BT_INTEGER_BASE_OCTAL = 8,
-
- /// Decimal.
- BT_INTEGER_BASE_DECIMAL = 10,
-
- /// Hexadecimal.
- BT_INTEGER_BASE_HEXADECIMAL = 16,
-};
-
-/**
-@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_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.
-
-@pre \p size is greater than 0 and lesser than or equal to 64.
-@postsuccessrefcountret1
-*/
-extern struct bt_field_type *bt_field_type_integer_create(
- unsigned int size);
-
-/**
-@brief Returns 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 get the
- storage size.
-@returns Storage size (bits) of the integer
- fields described by \p int_field_type,
- or a negative value on error.
-
-@prenotnull{int_field_type}
-@preisintft{int_field_type}
-@postrefcountsame{int_field_type}
-
-@sa bt_field_type_integer_set_size(): Sets the storage size of the
- integer fields described by a given integer field type.
-*/
-extern int bt_field_type_integer_get_size(
- struct bt_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_field_type_integer_get_size(): Returns the storage size of
- the integer fields described by a given integer field type.
-*/
-extern int bt_field_type_integer_set_size(
- struct bt_field_type *int_field_type, unsigned int size);
-
-/**
-@brief Returns whether or not the @intfields described by the @intft
- \p int_field_type are signed.
-
-@param[in] int_field_type Integer field type which describes the
- integer fields of which to get the
- signedness.
-@returns #BT_TRUE if the integer fields described by
- \p int_field_type are signed, #BT_FALSE if they
- are unsigned.
-
-@prenotnull{int_field_type}
-@preisintft{int_field_type}
-@postrefcountsame{int_field_type}
-
-@sa bt_field_type_integer_set_is_signed(): Sets the signedness of the
- integer fields described by a given integer field type.
-*/
-extern bt_bool bt_field_type_integer_is_signed(
- struct bt_field_type *int_field_type);
-
-/**
-@brief Sets whether or not the @intfields described by
- the @intft \p int_field_type are signed.
-
-@param[in] int_field_type Integer field type which describes the
- integer fields of which to set the
- signedness.
-@param[in] is_signed Signedness of the integer fields
- described by \p int_field_type; #BT_FALSE means
- \em unsigned, #BT_TRUE means \em signed.
-@returns 0 on success, or a negative value on error.
-
-@prenotnull{int_field_type}
-@preisintft{int_field_type}
-@prehot{int_field_type}
-@postrefcountsame{int_field_type}
-
-@sa bt_field_type_integer_is_signed(): Returns the signedness of
- the integer fields described by a given integer field type.
-*/
-extern int bt_field_type_integer_set_is_signed(
- struct bt_field_type *int_field_type, bt_bool is_signed);
-
-/**
-@brief Returns the preferred display base (radix) 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 get the
- preferred display base.
-@returns Preferred display base of the integer
- fields described by \p int_field_type,
- #BT_INTEGER_BASE_UNSPECIFIED if
- not specified, or
- #BT_INTEGER_BASE_UNKNOWN on error.
-
-@prenotnull{int_field_type}
-@preisintft{int_field_type}
-@postrefcountsame{int_field_type}
-
-@sa bt_field_type_integer_set_base(): Sets the preferred display
- base of the integer fields described by a given integer field
- type.
-*/
-extern enum bt_integer_base bt_field_type_integer_get_base(
- struct bt_field_type *int_field_type);
-
-/**
-@brief Sets the preferred display base (radix) of the @intfields
- described by the @intft \p int_field_type to \p base.
-
-@param[in] int_field_type Integer field type which describes the
- integer fields of which to set the
- preferred display base.
-@param[in] base Preferred display base 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 base is #BT_INTEGER_BASE_UNSPECIFIED,
- #BT_INTEGER_BASE_BINARY, #BT_INTEGER_BASE_OCTAL,
- #BT_INTEGER_BASE_DECIMAL, or #BT_INTEGER_BASE_HEXADECIMAL.
-@postrefcountsame{int_field_type}
-
-@sa bt_field_type_integer_get_base(): Returns the preferred display
- base of the integer fields described by a given
- integer field type.
-*/
-extern int bt_field_type_integer_set_base(
- struct bt_field_type *int_field_type,
- enum bt_integer_base base);
-
-/**
-@brief Returns the encoding 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 get the
- encoding.
-@returns Encoding of the integer
- fields described by \p int_field_type,
- or #BT_STRING_ENCODING_UNKNOWN on
- error.
-
-@prenotnull{int_field_type}
-@preisintft{int_field_type}
-@postrefcountsame{int_field_type}
-
-@sa bt_field_type_integer_set_encoding(): Sets the encoding
- of the integer fields described by a given integer field type.
-*/
-extern enum bt_string_encoding bt_field_type_integer_get_encoding(
- struct bt_field_type *int_field_type);
-
-/**
-@brief Sets the encoding of the @intfields described by the @intft
- \p int_field_type to \p encoding.
-
-You can use this property, in CTF IR, to create "text" @arrayfts or
-@seqfts. A text array field type is array field type with an unsigned,
-8-bit integer field type having an encoding as its element field type.
-
-@param[in] int_field_type Integer field type which describes the
- integer fields of which to set the
- encoding.
-@param[in] encoding Encoding 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 encoding is #BT_STRING_ENCODING_NONE,
- #BT_STRING_ENCODING_ASCII, or
- #BT_STRING_ENCODING_UTF8.
-@postrefcountsame{int_field_type}
-
-@sa bt_field_type_integer_get_encoding(): Returns the encoding of
- the integer fields described by a given integer field type.
-*/
-extern int bt_field_type_integer_set_encoding(
- struct bt_field_type *int_field_type,
- enum bt_string_encoding encoding);
-
-extern struct bt_clock_class *bt_field_type_integer_borrow_mapped_clock_class(
- struct bt_field_type *int_field_type);
-
-/**
-@brief Returns the \link ctfirclockclass CTF IR clock class\endlink
- mapped to the @intft \p int_field_type.
-
-The mapped clock class, if any, indicates the class of the clock which
-an @intfield described by \p int_field_type should sample or update.
-This mapped clock class is only indicative.
-
-@param[in] int_field_type Integer field type of which to get the
- mapped clock class.
-@returns Mapped clock class of \p int_field_type,
- or \c NULL if there's no mapped clock
- class or on error.
-
-@prenotnull{int_field_type}
-@preisintft{int_field_type}
-@postrefcountsame{int_field_type}
-@postsuccessrefcountretinc
-
-@sa bt_field_type_integer_set_mapped_clock_class(): Sets the mapped
- clock class of a given integer field type.
-*/
-static inline
-struct bt_clock_class *bt_field_type_integer_get_mapped_clock_class(
- struct bt_field_type *int_field_type)
-{
- return bt_get(bt_field_type_integer_borrow_mapped_clock_class(
- int_field_type));
-}
-
-/**
-@brief Sets the \link ctfirclockclass CTF IR clock class\endlink mapped
- 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.
-This mapped clock class is only indicative.
-
-@param[in] int_field_type Integer field type of which to set the
- mapped clock class.
-@param[in] clock_class Mapped clock class of \p int_field_type.
-@returns 0 on success, or a negative value on error.
-
-@prenotnull{int_field_type}
-@prenotnull{clock_class}
-@preisintft{int_field_type}
-@prehot{int_field_type}
-@postrefcountsame{int_field_type}
-@postsuccessrefcountinc{clock_class}
-
-@sa bt_field_type_integer_get_mapped_clock_class(): Returns the mapped
- clock class of a given integer field type.
-*/
-extern int bt_field_type_integer_set_mapped_clock_class(
- struct bt_field_type *int_field_type,
- struct bt_clock_class *clock_class);
-
-/** @} */
-
-/**
-@defgroup ctfirfloatfieldtype CTF IR floating point number field type
-@ingroup ctfirfieldtypes
-@brief CTF IR floating point number field type.
-
-@code
-#include <babeltrace/ctf-ir/field-types.h>
-@endcode
-
-A CTF IR <strong><em>floating point number field type</em></strong> is
-a field type that you can use to create concrete @floatfields.
-
-You can create a floating point number field type
-with bt_field_type_floating_point_create().
-
-A floating point number field type has the following properties:
-
-<table>
- <tr>
- <th>Property
- <th>Value at creation
- <th>Getter
- <th>Setter
- </tr>
- <tr>
- <td>\b Alignment (bits) of the described floating point
- number fields
- <td>1
- <td>bt_field_type_get_alignment()
- <td>bt_field_type_set_alignment()
- </tr>
- <tr>
- <td><strong>Byte order</strong> of the described floating point
- number fields
- <td>#BT_BYTE_ORDER_NATIVE
- <td>bt_field_type_get_byte_order()
- <td>bt_field_type_set_byte_order()
- </tr>
- <tr>
- <td><strong>Exponent storage size</strong> (bits) of the described
- floating point number fields
- <td>8
- <td>bt_field_type_floating_point_get_exponent_digits()
- <td>bt_field_type_floating_point_set_exponent_digits()
- </tr>
- <tr>
- <td><strong>Mantissa and sign storage size</strong> (bits) of the
- described floating point number fields
- <td>24 (23-bit mantissa, 1-bit sign)
- <td>bt_field_type_floating_point_get_mantissa_digits()
- <td>bt_field_type_floating_point_set_mantissa_digits()
- </tr>
-</table>
-
-@sa ctfirfloatfield
-@sa ctfirfieldtypes
-@sa \ref ctfirfieldtypesexamples_floatfieldtype "Examples"
-
-@addtogroup ctfirfloatfieldtype
-@{
-*/
-
-/**
-@brief Creates a default @floatft.
-
-@returns Created floating point number field type,
- or \c NULL on error.
-
-@postsuccessrefcountret1
-*/
-extern struct bt_field_type *bt_field_type_floating_point_create(void);
-
-/**
-@brief Returns the exponent storage size of the @floatfields
- described by the @floatft \p float_field_type.
-
-@param[in] float_field_type Floating point number field type which
- describes the floating point number
- fields of which to get the exponent
- storage size.
-@returns Exponent storage size of the
- floating point number fields
- described by \p float_field_type,
- or a negative value on error.
-
-@prenotnull{float_field_type}
-@preisfloatft{float_field_type}
-@postrefcountsame{float_field_type}
-
-@sa bt_field_type_floating_point_set_exponent_digits(): Sets the
- exponent storage size of the floating point number fields
- described by a given floating point number field type.
-*/
-extern int bt_field_type_floating_point_get_exponent_digits(
- struct bt_field_type *float_field_type);
-
-/**
-@brief Sets the exponent storage size of the @floatfields described by
- the @floatft \p float_field_type to \p exponent_size.
-
-As of Babeltrace \btversion, \p exponent_size can only be 8 or 11.
-
-@param[in] float_field_type Floating point number field type which
- describes the floating point number
- fields of which to set the exponent
- storage size.
-@param[in] exponent_size Exponent storage size of the floating
- point number fields described by \p
- float_field_type.
-@returns 0 on success, or a negative value on error.
-
-@prenotnull{float_field_type}
-@preisfloatft{float_field_type}
-@prehot{float_field_type}
-@pre \p exponent_size is 8 or 11.
-@postrefcountsame{float_field_type}
-
-@sa bt_field_type_floating_point_get_exponent_digits(): Returns the
- exponent storage size of the floating point number fields
- described by a given floating point number field type.
-*/
-extern int bt_field_type_floating_point_set_exponent_digits(
- struct bt_field_type *float_field_type,
- unsigned int exponent_size);
-
-/**
-@brief Returns the mantissa and sign storage size of the @floatfields
- described by the @floatft \p float_field_type.
-
-On success, the returned value is the sum of the mantissa \em and
-sign storage sizes.
-
-@param[in] float_field_type Floating point number field type which
- describes the floating point number
- fields of which to get the mantissa and
- sign storage size.
-@returns Mantissa and sign storage size of the
- floating point number fields
- described by \p float_field_type,
- or a negative value on error.
-
-@prenotnull{float_field_type}
-@preisfloatft{float_field_type}
-@postrefcountsame{float_field_type}
-
-@sa bt_field_type_floating_point_set_mantissa_digits(): Sets the
- mantissa and size storage size of the floating point number
- fields described by a given floating point number field type.
-*/
-extern int bt_field_type_floating_point_get_mantissa_digits(
- struct bt_field_type *float_field_type);
-
-/**
-@brief Sets the mantissa and sign storage size of the @floatfields
- described by the @floatft \p float_field_type to \p
- mantissa_sign_size.
-
-As of Babeltrace \btversion, \p mantissa_sign_size can only be 24 or 53.
-
-@param[in] float_field_type Floating point number field type which
- describes the floating point number
- fields of which to set the mantissa and
- sign storage size.
-@param[in] mantissa_sign_size Mantissa and sign storage size of the
- floating point number fields described
- by \p float_field_type.
-@returns 0 on success, or a negative value on error.
-
-@prenotnull{float_field_type}
-@preisfloatft{float_field_type}
-@prehot{float_field_type}
-@pre \p mantissa_sign_size is 24 or 53.
-@postrefcountsame{float_field_type}
-
-@sa bt_field_type_floating_point_get_mantissa_digits(): Returns the
- mantissa and sign storage size of the floating point number
- fields described by a given floating point number field type.
-*/
-extern int bt_field_type_floating_point_set_mantissa_digits(
- struct bt_field_type *float_field_type,
- unsigned int mantissa_sign_size);
-
-/** @} */
-
-/**
-@defgroup ctfirenumfieldtype CTF IR enumeration field type
-@ingroup ctfirfieldtypes
-@brief CTF IR enumeration field type.
-
-@code
-#include <babeltrace/ctf-ir/field-types.h>
-@endcode
-
-A CTF IR <strong><em>enumeration field type</em></strong> is
-a field type that you can use to create concrete @enumfields.
-
-You can create an enumeration field type with
-bt_field_type_enumeration_create(). This function needs a @intft
-which represents the storage field type of the created enumeration field
-type. In other words, an enumeration field type wraps an integer field
-type and adds label-value mappings to it.
-
-An enumeration mapping has:
-
-- A <strong>name</strong>.
-- A <strong>range of values</strong> given by a beginning and an ending
- value, both included in the range.
-
-You can add a mapping to an enumeration field type with
-bt_field_type_enumeration_signed_add_mapping() or
-bt_field_type_enumeration_unsigned_add_mapping(), depending on the
-signedness of the wrapped @intft.
-
-You can find mappings by name or by value with the following find
-operations:
-
-- bt_field_type_enumeration_find_mappings_by_name(): Finds the
- mappings with a given name.
-- bt_field_type_enumeration_unsigned_find_mappings_by_value():
- Finds the mappings which contain a given unsigned value in their
- range.
-- bt_field_type_enumeration_signed_find_mappings_by_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
-APPLE -> [ 3, 19]
-BANANA -> [-15, 1]
-CHERRY -> [ 25, 34]
-APPLE -> [ 55, 55]
-@endverbatim
-
-The following set of mappings is also valid:
-
-@verbatim
-APPLE -> [ 3, 19]
-BANANA -> [-15, 1]
-CHERRY -> [ 25, 34]
-APPLE -> [ 30, 55]
-@endverbatim
-
-Here, the range of the second \c APPLE mapping overlaps the range of
-the \c CHERRY mapping.
-
-@sa ctfirenumftmappingiter
-@sa ctfirenumfield
-@sa ctfirfieldtypes
-
-@addtogroup ctfirenumfieldtype
-@{
-*/
-
-/**
-@brief Creates a default @enumft wrapping the @intft \p int_field_type.
-
-@param[in] int_field_type Integer field type wrapped by the
- created enumeration field type.
-@returns Created enumeration field type,
- or \c NULL on error.
-
-@prenotnull{int_field_type}
-@preisintft{int_field_type}
-@postsuccessrefcountinc{int_field_type}
-@postsuccessrefcountret1
-*/
-extern struct bt_field_type *bt_field_type_enumeration_create(
- struct bt_field_type *int_field_type);
-
-extern
-struct bt_field_type *bt_field_type_enumeration_borrow_container_field_type(
- struct bt_field_type *enum_field_type);
-
-/**
-@brief Returns the @intft wrapped by the @enumft \p enum_field_type.
-
-@param[in] enum_field_type Enumeration field type of which to get
- the wrapped integer field type.
-@returns Integer field type wrapped by
- \p enum_field_type, or \c NULL on
- error.
-
-@prenotnull{enum_field_type}
-@preisenumft{enum_field_type}
-@postrefcountsame{enum_field_type}
-@postsuccessrefcountretinc
-*/
-static inline
-struct bt_field_type *bt_field_type_enumeration_get_container_field_type(
- struct bt_field_type *enum_field_type)
-{
- return bt_get(bt_field_type_enumeration_borrow_container_field_type(
- enum_field_type));
-}
-
-/**
-@brief Returns the number of mappings contained in the
- @enumft \p enum_field_type.
-
-@param[in] enum_field_type Enumeration field type of which to get
- the number of contained mappings.
-@returns Number of mappings contained in
- \p enum_field_type, or a negative
- value on error.
-
-@prenotnull{enum_field_type}
-@preisenumft{enum_field_type}
-@postrefcountsame{enum_field_type}
-*/
-extern int64_t bt_field_type_enumeration_get_mapping_count(
- struct bt_field_type *enum_field_type);
-
-/**
-@brief Returns the signed mapping of the @enumft
- \p enum_field_type at index \p index.
-
-The @intft wrapped by \p enum_field_type, as returned by
-bt_field_type_enumeration_get_container_field_type(), must be \b signed
-to use this function.
-
-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
- \p enum_field_type.
-@param[out] name Returned name of the mapping at index
- \p index.
-@param[out] range_begin Returned beginning of the range
- (included) of the mapping at index \p
- index.
-@param[out] range_end Returned end of the range (included) of
- the mapping at index \p index.
-@returns 0 on success, or a negative value on error.
-
-@prenotnull{enum_field_type}
-@prenotnull{name}
-@prenotnull{range_begin}
-@prenotnull{range_end}
-@preisenumft{enum_field_type}
-@pre The wrapped @intft of \p enum_field_type is signed.
-@pre \p index is lesser than the number of mappings contained in the
- enumeration field type \p enum_field_type (see
- bt_field_type_enumeration_get_mapping_count()).
-@postrefcountsame{enum_field_type}
-
-@sa bt_field_type_enumeration_unsigned_get_mapping_by_index(): Returns the
- unsigned mapping contained by a given enumeration field type
- at a given index.
-*/
-extern int bt_field_type_enumeration_signed_get_mapping_by_index(
- struct bt_field_type *enum_field_type, uint64_t index,
- const char **name, int64_t *range_begin, int64_t *range_end);
-
-/**
-@brief Returns the unsigned mapping of the @enumft
- \p enum_field_type at index \p index.
-
-The @intft wrapped by \p enum_field_type, as returned by
-bt_field_type_enumeration_get_container_field_type(), must be
-\b unsigned to use this function.
-
-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
- \p enum_field_type.
-@param[out] name Returned name of the mapping at index
- \p index.
-@param[out] range_begin Returned beginning of the range
- (included) of the mapping at index \p
- index.
-@param[out] range_end Returned end of the range (included) of
- the mapping at index \p index.
-@returns 0 on success, or a negative value on error.
-
-@prenotnull{enum_field_type}
-@prenotnull{name}
-@prenotnull{range_begin}
-@prenotnull{range_end}
-@preisenumft{enum_field_type}
-@pre The wrapped @intft of \p enum_field_type is unsigned.
-@pre \p index is lesser than the number of mappings contained in the
- enumeration field type \p enum_field_type (see
- bt_field_type_enumeration_get_mapping_count()).
-@postrefcountsame{enum_field_type}
-
-@sa bt_field_type_enumeration_signed_get_mapping_by_index(): Returns the
- signed mapping contained by a given enumeration field type
- at a given index.
-*/
-extern int bt_field_type_enumeration_unsigned_get_mapping_by_index(
- struct bt_field_type *enum_field_type, uint64_t index,
- const char **name, uint64_t *range_begin,
- uint64_t *range_end);
-
-/**
-@brief Finds the mappings of the @enumft \p enum_field_type which
- are named \p name.
-
-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 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}
-@postrefcountsame{enum_field_type}
-@postsuccessrefcountret1
-@post <strong>On success</strong>, the returned @enumftiter can iterate
- on at least one mapping.
-
-@sa bt_field_type_enumeration_signed_find_mappings_by_value(): Finds
- the mappings of a given enumeration field type which contain
- a given signed value in their range.
-@sa bt_field_type_enumeration_unsigned_find_mappings_by_value(): Finds
- the mappings of a given enumeration field type which contain
- a given unsigned value in their range.
-*/
-extern struct bt_field_type_enumeration_mapping_iterator *
-bt_field_type_enumeration_find_mappings_by_name(
- struct bt_field_type *enum_field_type,
- const char *name);
-
-/**
-@brief Finds the mappings of the @enumft \p enum_field_type which
- contain the signed 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}
-@postrefcountsame{enum_field_type}
-@postsuccessrefcountret1
-@post <strong>On success</strong>, the returned @enumftiter can iterate
- on at least one mapping.
-
-@sa bt_field_type_enumeration_find_mappings_by_name(): Finds the
- mappings of a given enumeration field type which have a given
- name.
-@sa bt_field_type_enumeration_unsigned_find_mappings_by_value(): Finds
- the mappings of a given enumeration field type which contain
- a given unsigned value in their range.
-*/
-extern struct bt_field_type_enumeration_mapping_iterator *
-bt_field_type_enumeration_signed_find_mappings_by_value(
- struct bt_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}
-@postrefcountsame{enum_field_type}
-@postsuccessrefcountret1
-@post <strong>On success</strong>, the returned @enumftiter can iterate
- on at least one mapping.
-
-@sa bt_field_type_enumeration_find_mappings_by_name(): Finds the
- mappings of a given enumeration field type which have a given
- name.
-@sa bt_field_type_enumeration_signed_find_mappings_by_value(): Finds
- the mappings of a given enumeration field type which contain
- a given unsigned value in their range.
-*/
-extern struct bt_field_type_enumeration_mapping_iterator *
-bt_field_type_enumeration_unsigned_find_mappings_by_value(
- struct bt_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
- \p range_end (included).
-
-Make \p range_begin and \p range_end the same value to add a mapping
-to a single value.
-
-The @intft wrapped by \p enum_field_type, as returned by
-bt_field_type_enumeration_get_container_field_type(), must be
-\b signed to use this function.
-
-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.
-@param[in] name Name of the mapping to add (copied
- on success).
-@param[in] range_begin Beginning of the range of the mapping
- (included).
-@param[in] range_end End of the range of the mapping
- (included).
-@returns 0 on success, or a negative value on error.
-
-@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.
-@postrefcountsame{enum_field_type}
-
-@sa bt_field_type_enumeration_unsigned_add_mapping(): Adds an
- unsigned mapping to a given enumeration field type.
-*/
-extern int bt_field_type_enumeration_signed_add_mapping(
- struct bt_field_type *enum_field_type, const char *name,
- int64_t range_begin, int64_t range_end);
-
-/**
-@brief Adds a mapping to the @enumft \p enum_field_type which maps
- the name \p name to the unsigned
- range \p range_begin (included) to \p range_end (included).
-
-Make \p range_begin and \p range_end the same value to add a mapping
-to a single value.
-
-The @intft wrapped by \p enum_field_type, as returned by
-bt_field_type_enumeration_get_container_field_type(), must be
-\b unsigned to use this function.
-
-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.
-@param[in] name Name of the mapping to add (copied
- on success).
-@param[in] range_begin Beginning of the range of the mapping
- (included).
-@param[in] range_end End of the range of the mapping
- (included).
-@returns 0 on success, or a negative value on error.
-
-@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.
-@postrefcountsame{enum_field_type}
-
-@sa bt_field_type_enumeration_signed_add_mapping(): Adds a signed
- mapping to a given enumeration field type.
-*/
-extern int bt_field_type_enumeration_unsigned_add_mapping(
- struct bt_field_type *enum_field_type, const char *name,
- uint64_t range_begin, uint64_t range_end);
-
-/** @} */
-
-/**
-@defgroup ctfirenumftmappingiter CTF IR enumeration field type mapping iterator
-@ingroup ctfirenumfieldtype
-@brief CTF IR enumeration field type mapping iterator.
-
-@code
-#include <babeltrace/ctf-ir/field-types.h>
-@endcode
-
-A CTF IR <strong><em>enumeration field type mapping
-iterator</em></strong> 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_field_type_enumeration_find_mappings_by_name(): Finds the
- mappings with a given name.
- - bt_field_type_enumeration_unsigned_find_mappings_by_value():
- Finds the mappings which contain a given unsigned value in their
- range.
- - bt_field_type_enumeration_signed_find_mappings_by_value():
- Finds the mappings which contain a given signed value in their range.
-- bt_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_field_type_enumeration_mapping_iterator_signed_get()
-or
-bt_field_type_enumeration_mapping_iterator_unsigned_get(),
-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_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 <a
-href="https://en.wikipedia.org/wiki/Reference_counting">reference
-counts</a>. See \ref refs to learn more about the reference counting
-management of Babeltrace objects.
-
-@sa ctfirenumfieldtype
-
-@addtogroup ctfirenumftmappingiter
-@{
-*/
-
-/**
-@struct bt_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_field_type_enumeration_get_container_field_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_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_field_type_enumeration_mapping_iterator_unsigned_get():
- Returns the name and the unsigned range of the current mapping
- of a given enumeration field type mapping iterator.
-*/
-extern int bt_field_type_enumeration_mapping_iterator_signed_get(
- struct bt_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_field_type_enumeration_get_container_field_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_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_field_type_enumeration_mapping_iterator_signed_get():
- Returns the name and the signed range of the current mapping of
- a given enumeration field type mapping iterator.
-*/
-extern int bt_field_type_enumeration_mapping_iterator_unsigned_get(
- struct bt_field_type_enumeration_mapping_iterator *iter,
- const char **name, uint64_t *range_begin, uint64_t *range_end);