-You can create an enumeration field type with
-bt_ctf_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_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 <strong>must not overlap</strong>. 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 \em not valid, however:
-
-@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 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_ctf_field_type *bt_ctf_field_type_enumeration_create(
- struct bt_ctf_field_type *int_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
-*/
-extern
-struct bt_ctf_field_type *bt_ctf_field_type_enumeration_get_container_type(
- struct bt_ctf_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 int bt_ctf_field_type_enumeration_get_mapping_count(
- struct bt_ctf_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_ctf_field_type_enumeration_get_container_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_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
- at a given index.
-*/
-extern int bt_ctf_field_type_enumeration_get_mapping(
- struct bt_ctf_field_type *enum_field_type, int 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_ctf_field_type_enumeration_get_container_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_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
- at a given index.
-*/
-extern int bt_ctf_field_type_enumeration_get_mapping_unsigned(
- struct bt_ctf_field_type *enum_field_type, int index,
- 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
- \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_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.
-
-@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}
-@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_ctf_field_type_enumeration_add_mapping_unsigned(): Adds an
- unsigned mapping to a given enumeration field type.
-*/
-extern int bt_ctf_field_type_enumeration_add_mapping(
- struct bt_ctf_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_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.
-
-@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}
-@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_ctf_field_type_enumeration_add_mapping(): Adds a signed
- mapping to a given enumeration field type.
-*/
-extern int bt_ctf_field_type_enumeration_add_mapping_unsigned(
- struct bt_ctf_field_type *enum_field_type, const char *name,
- uint64_t range_begin, uint64_t range_end);
-
-/** @} */
-
-/**
-@defgroup ctfirstringfieldtype CTF IR string field type
-@ingroup ctfirfieldtypes
-@brief CTF IR string field type.
-
-@code
-#include <babeltrace/ctf-ir/field-types.h>
-@endcode
-
-A CTF IR <strong><em>string field type</em></strong> is a field type that
-you can use to create concrete @stringfields.
-
-You can create a string field type
-with bt_ctf_field_type_string_create().
-
-A string field type has only one property: the \b encoding of its
-described @stringfields. By default, the encoding of the string fields
-described by a string field type is #BT_CTF_STRING_ENCODING_UTF8. You
-can set the encoding of the string fields described by a string field
-type with bt_ctf_field_type_string_set_encoding().
-
-@sa ctfirstringfield
-@sa ctfirfieldtypes
-
-@addtogroup ctfirstringfieldtype
-@{
-*/
-
-/**
-@brief Creates a default @stringft.
-
-@returns Created string field type, or \c NULL on error.
-
-@postsuccessrefcountret1
-*/
-extern struct bt_ctf_field_type *bt_ctf_field_type_string_create(void);
-
-/**
-@brief Returns the encoding of the @stringfields described by
- the @stringft \p string_field_type.
-
-@param[in] string_field_type String field type which describes the
- string fields of which to get the
- encoding.
-@returns Encoding of the string
- fields described by \p string_field_type,
- or #BT_CTF_STRING_ENCODING_UNKNOWN on
- error.
-
-@prenotnull{string_field_type}
-@preisstringft{string_field_type}
-@postrefcountsame{string_field_type}
-
-@sa bt_ctf_field_type_string_set_encoding(): Sets the encoding
- of the string fields described by a given string field type.
-*/
-extern enum bt_ctf_string_encoding bt_ctf_field_type_string_get_encoding(
- struct bt_ctf_field_type *string_field_type);
-
-/**
-@brief Sets the encoding of the @stringfields described by the
- @stringft \p string_field_type to \p encoding.
-
-@param[in] string_field_type String field type which describes the
- string fields of which to set the
- encoding.
-@param[in] encoding Encoding of the string fields described
- by \p string_field_type.
-@returns 0 on success, or a negative value on error.
-
-@prenotnull{string_field_type}
-@preisstringft{string_field_type}
-@prehot{string_field_type}
-@pre \p encoding is #BT_CTF_STRING_ENCODING_ASCII or
- #BT_CTF_STRING_ENCODING_UTF8.
-@postrefcountsame{string_field_type}
-
-@sa bt_ctf_field_type_string_get_encoding(): Returns the encoding of
- the string fields described by a given string field type.
-*/
-extern int bt_ctf_field_type_string_set_encoding(
- struct bt_ctf_field_type *string_field_type,
- enum bt_ctf_string_encoding encoding);
-
-/** @} */
-
-/**
-@defgroup ctfirstructfieldtype CTF IR structure field type
-@ingroup ctfirfieldtypes
-@brief CTF IR structure field type.
-
-@code
-#include <babeltrace/ctf-ir/field-types.h>
-@endcode
-
-A CTF IR <strong><em>structure field type</em></strong> is
-a field type that you can use to create concrete @structfields.
-
-You can create a structure field type
-with bt_ctf_field_type_structure_create(). This function creates
-an empty structure field type, with no fields.
-
-You can add a field to a structure field type with
-bt_ctf_field_type_structure_add_field(). Two fields in a structure
-field type cannot have the same name.
-
-You can set the \em minimum alignment of the structure fields described
-by a structure field type with the common
-bt_ctf_field_type_set_alignment() function. The \em effective alignment
-of the structure fields described by a structure field type, as per
-<a href="http://diamon.org/ctf/">CTF</a>, is the \em maximum value amongst
-the effective alignments of all its fields. Note that the effective
-alignment of @varfields is always 1.
-
-You can set the byte order of <em>all the contained fields</em>,
-recursively, of a structure field type with the common
-bt_ctf_field_type_set_byte_order() function.
-
-@sa ctfirstructfield
-@sa ctfirfieldtypes
-
-@addtogroup ctfirstructfieldtype
-@{
-*/
-
-/**
-@brief Creates a default, empty @structft.
-
-@returns Created structure field type,
- or \c NULL on error.
-
-@postsuccessrefcountret1
-*/
-extern struct bt_ctf_field_type *bt_ctf_field_type_structure_create(void);
-
-/**
-@brief Returns the number of fields contained in the
- @structft \p struct_field_type.
-
-@param[in] struct_field_type Structure field type of which to get
- the number of contained fields.
-@returns Number of fields contained in
- \p struct_field_type, or a negative
- value on error.
-
-@prenotnull{struct_field_type}
-@preisstructft{struct_field_type}
-@postrefcountsame{struct_field_type}
-*/
-extern int bt_ctf_field_type_structure_get_field_count(
- struct bt_ctf_field_type *struct_field_type);
-
-/**
-@brief Returns the field of the @structft \p struct_field_type
- at index \p index.
-
-On success, the field's type is placed in \p *field_type if
-\p field_type is not \c NULL. The field's name is placed in
-\p *field_name if \p field_name is not \c NULL.
-\p struct_field_type remains the sole owner of \p *field_name.
-
-@param[in] struct_field_type Structure field type of which to get
- the field at index \p index.
-@param[out] field_name Returned name of the field at index
- \p index (can be \c NULL).
-@param[out] field_type Returned field type of the field
- at index \p index (can be \c NULL).
-@param[in] index Index of the field to get from
- \p struct_field_type.
-@returns 0 on success, or a negative value on error.
-
-@prenotnull{struct_field_type}
-@preisstructft{struct_field_type}
-@pre \p index is lesser than the number of fields contained in the
- structure field type \p struct_field_type (see
- bt_ctf_field_type_structure_get_field_count()).
-@postrefcountsame{struct_field_type}
-@post <strong>On success</strong>, the returned field's type is placed
- in \p *field_type and its reference count is incremented.
-
-@sa bt_ctf_field_type_structure_get_field_type_by_name(): Finds a
- structure field type's field by name.
-*/
-extern int bt_ctf_field_type_structure_get_field(
- struct bt_ctf_field_type *struct_field_type,
- const char **field_name, struct bt_ctf_field_type **field_type,
- int index);
-
-/**
-@brief Returns the type of the field named \p field_name found in
- the @structft \p struct_field_type.
-
-@param[in] struct_field_type Structure field type of which to get
- a field's type.
-@param[in] field_name Name of the field to find.
-@returns Type of the field named \p field_name in
- \p struct_field_type, or
- \c NULL on error.
-
-@prenotnull{struct_field_type}
-@prenotnull{field_name}
-@preisstructft{struct_field_type}
-@postrefcountsame{struct_field_type}
-@postsuccessrefcountretinc
-
-@sa bt_ctf_field_type_structure_get_field(): Finds a
- structure field type's field by index.
-*/