+/*!
+@defgroup api-tir-field Fields
+@ingroup api-tir
+
+@brief
+ Containers of trace data.
+
+<strong><em>Fields</em></strong> are containers of trace data: they are
+found in \bt_p_ev and \bt_p_pkt.
+
+Fields are instances of \bt_p_fc:
+
+@image html field-class-zoom.png
+
+Borrow the class of a field with bt_field_borrow_class() and
+bt_field_borrow_class_const().
+
+Fields are \ref api-tir "trace IR" data objects.
+
+There are many types of fields. They can be divided into two main
+categories:
+
+<dl>
+ <dt>Scalar</dt>
+ <dd>
+ Fields which contain a simple value.
+
+ The scalar fields are:
+
+ - \ref api-tir-field-bool "Boolean"
+ - \ref api-tir-field-ba "Bit array"
+ - \ref api-tir-field-int "Integer" (unsigned and signed)
+ - \ref api-tir-field-enum "Enumeration" (unsigned and signed)
+ - \ref api-tir-field-real "Real" (single-precision and double-precision)
+ - \ref api-tir-field-string "String"
+ </dd>
+
+ <dt>Container</dt>
+ <dd>
+ Fields which contain other fields.
+
+ The container fields are:
+
+ - \ref api-tir-field-array "Array" (static and dynamic)
+ - \ref api-tir-field-struct "Structure"
+ - \ref api-tir-field-opt "Option"
+ - \ref api-tir-field-var "Variant"
+ </dd>
+</dl>
+
+@image html fc-to-field.png "Fields (green) are instances of field classes (orange)."
+
+You cannot directly create a field: there are no
+<code>bt_field_*_create()</code> functions. The \bt_name library
+creates fields within an \bt_ev or a \bt_pkt from \bt_p_fc.
+Therefore, to fill the payload fields of an \bt_ev, you must first
+borrow the event's existing payload \bt_struct_field with
+bt_event_borrow_payload_field() and then borrow each field, recursively,
+to set their values.
+
+The functions to borrow a field from an event or a packet are:
+
+- bt_packet_borrow_context_field() and
+ bt_packet_borrow_context_field_const()
+- bt_event_borrow_common_context_field() and
+ bt_event_borrow_common_context_field_const()
+- bt_event_borrow_specific_context_field() and
+ bt_event_borrow_specific_context_field_const()
+- bt_event_borrow_payload_field() and
+ bt_event_borrow_payload_field_const()
+
+Some fields conceptually inherit other fields, eventually
+making an inheritance hierarchy. For example, an \bt_enum_field
+\em is an \bt_int_field. Therefore, an enumeration field holds an
+integral value, just like an integer field does.
+
+The complete field inheritance hierarchy is:
+
+@image html all-fields.png
+
+This is the same inheritance hierarchy as the \bt_fc inheritance
+hierarchy.
+
+In the illustration above:
+
+- A field with a dark background is instantiated from a concrete \bt_fc,
+ which you can directly create with a dedicated
+ <code>bt_field_class_*_create()</code> function.
+
+- A field with a pale background is an \em abstract field: it's not a
+ concrete instance, but it can have properties, therefore there can be
+ functions which apply to it.
+
+ For example, bt_field_integer_signed_set_value() applies to any
+ \bt_sint_field.
+
+Fields are \ref api-fund-unique-object "unique objects": they belong
+to an \bt_ev or to a \bt_pkt.
+
+Some library functions \ref api-fund-freezing "freeze" fields on
+success. The documentation of those functions indicate this
+postcondition.
+
+All the field types share the same C type, #bt_field.
+
+Get the type enumerator of a field's class with bt_field_get_class_type().
+Get whether or not a field class type conceptually \em is a given type
+with the inline bt_field_class_type_is() function.
+
+<h1>\anchor api-tir-field-bool Boolean field</h1>
+
+A <strong><em>boolean field</em></strong> is a \bt_bool_fc instance.
+
+A boolean field contains a boolean value (#BT_TRUE or #BT_FALSE).
+
+Set the value of a boolean field with bt_field_bool_set_value().
+
+Get the value of a boolean field with bt_field_bool_get_value().
+
+<h1>\anchor api-tir-field-ba Bit array field</h1>
+
+A <strong><em>bit array field</em></strong> is a \bt_ba_fc instance.
+
+A bit array field contains a fixed-length array of bits. Its length
+is \ref api-tir-fc-ba-prop-len "given by its class".
+
+The bit array field API interprets the array as an unsigned integer
+value: the least significant bit's index is 0.
+
+For example, to get whether or not bit 3 of a bit array field is
+set:
+
+@code
+uint64_t value = bt_field_bit_array_get_value_as_integer(field);
+
+if (value & (UINT64_C(1) << UINT64_C(3))) {
+ // Bit 3 is set
+}
+@endcode
+
+Set the bits of a bit array field with
+bt_field_bit_array_set_value_as_integer().
+
+Get the bits of a bit array field with
+bt_field_bit_array_get_value_as_integer().
+
+<h1>\anchor api-tir-field-int Integer fields</h1>
+
+<strong><em>Integer fields</em></strong> are \bt_int_fc instances.
+
+Integer fields contain integral values.
+
+An integer field is an \em abstract field. The concrete integer fields
+are:
+
+<dl>
+ <dt>Unsigned integer field</dt>
+ <dd>
+ An \bt_uint_fc instance.
+
+ An unsigned integer field contains an unsigned integral value
+ (\c uint64_t).
+
+ Set the value of an unsigned integer field with
+ bt_field_integer_unsigned_set_value().
+
+ Get the value of an unsigned integer field with
+ bt_field_integer_unsigned_get_value().
+ </dd>
+
+ <dt>Signed integer field</dt>
+ <dd>
+ A \bt_sint_fc instance.
+
+ A signed integer field contains a signed integral value (\c int64_t).
+
+ Set the value of a signed integer field with
+ bt_field_integer_signed_set_value().
+
+ Get the value of a signed integer field with
+ bt_field_integer_signed_get_value().
+ </dd>
+</dl>
+
+<h2>\anchor api-tir-field-enum Enumeration fields</h2>
+
+<strong><em>Enumeration fields</em></strong> are \bt_enum_fc instances.
+
+Enumeration fields \em are \bt_p_int_field: they contain integral
+values.
+
+An enumeration field is an \em abstract field.
+The concrete enumeration fields are:
+
+<dl>
+ <dt>Unsigned enumeration field</dt>
+ <dd>
+ An \bt_uenum_fc instance.
+
+ An unsigned enumeration field contains an unsigned integral value
+ (\c uint64_t).
+
+ Set the value of an unsigned enumeration field with
+ bt_field_integer_unsigned_set_value().
+
+ Get the value of an unsigned enumeration field with
+ bt_field_integer_unsigned_get_value().
+
+ Get all the enumeration field class labels mapped to the value of a
+ given unsigned enumeration field with
+ bt_field_enumeration_unsigned_get_mapping_labels().
+ </dd>
+
+ <dt>Signed enumeration field</dt>
+ <dd>
+ A \bt_senum_fc instance.
+
+ A signed enumeration field contains a signed integral value
+ (\c int64_t).
+
+ Set the value of a signed enumeration field with
+ bt_field_integer_signed_set_value().
+
+ Get the value of a signed enumeration field with
+ bt_field_integer_signed_get_value().
+
+ Get all the enumeration field class labels mapped to the value of a
+ given signed enumeration field with
+ bt_field_enumeration_signed_get_mapping_labels().
+ </dd>
+</dl>
+
+<h1>\anchor api-tir-field-real Real fields</h1>
+
+<strong><em>Real fields</em></strong> are \bt_real_fc instances.
+
+Real fields contain
+<a href="https://en.wikipedia.org/wiki/Real_number">real</a>
+values (\c float or \c double types).
+
+A real field is an \em abstract field. The concrete real fields are:
+
+<dl>
+ <dt>Single-precision real field</dt>
+ <dd>
+ A single-precision real field class instance.
+
+ A single-precision real field contains a \c float value.
+
+ Set the value of a single-precision real field with
+ bt_field_real_single_precision_set_value().
+
+ Get the value of a single-precision real field with
+ bt_field_real_single_precision_get_value().
+ </dd>
+
+ <dt>Double-precision real field</dt>
+ <dd>
+ A double-precision real field class instance.
+
+ A double-precision real field contains a \c double value.
+
+ Set the value of a double-precision real field with
+ bt_field_real_double_precision_set_value().
+
+ Get the value of a double-precision real field with
+ bt_field_real_double_precision_get_value().
+ </dd>
+</dl>
+
+<h1>\anchor api-tir-field-string String field</h1>
+
+A <strong><em>string field</em></strong> is a \bt_string_fc instance.
+
+A string field contains an UTF-8 string value.
+
+Set the value of a string field with
+bt_field_string_set_value().
+
+Get the value of a string field with
+bt_field_string_get_value().
+
+Get the length of a string field with
+bt_field_string_get_length().
+
+Append a string to a string field's current value with
+bt_field_string_append() and bt_field_string_append_with_length().
+
+Clear a string field with bt_field_string_clear().
+
+<h1>\anchor api-tir-field-array Array fields</h1>
+
+<strong><em>Array fields</em></strong> are \bt_array_fc instances.
+
+Array fields contain zero or more fields which have the same class.
+
+An array field is an \em abstract field. The concrete array fields are:
+
+<dl>
+ <dt>Static array field</dt>
+ <dd>
+ A \bt_sarray_fc instance.
+
+ A static array field contains a fixed number of fields. Its length
+ is \ref api-tir-fc-sarray-prop-len "given by its class".
+ </dd>
+
+ <dt>Dynamic array field class</dt>
+ <dd>
+ A \bt_darray_fc instance.
+
+ A dynamic array field contains a variable number of fields, that is,
+ each instance of the same dynamic array field class can contain a
+ different number of elements.
+
+ Set a dynamic array field's length with
+ bt_field_array_dynamic_set_length() before you borrow any of its
+ fields.
+ </dd>
+</dl>
+
+Get an array field's length with bt_field_array_get_length().
+
+Borrow a field from an array field at a given index with
+bt_field_array_borrow_element_field_by_index() and
+bt_field_array_borrow_element_field_by_index_const().
+
+<h1>\anchor api-tir-field-struct Structure field</h1>
+
+A <strong><em>structure field</em></strong> is a \bt_struct_fc instance.
+
+A structure field contains an ordered list of zero or more members. A
+structure field member contains a field: it's an instance of a structure
+field class member.
+
+Borrow a member's field from a structure field at a given index with
+bt_field_structure_borrow_member_field_by_index() and
+bt_field_structure_borrow_member_field_by_index_const().
+
+Borrow a member's field from a structure field by name with
+bt_field_structure_borrow_member_field_by_name() and
+bt_field_structure_borrow_member_field_by_name_const().
+
+<h1>\anchor api-tir-field-opt Option field</h1>
+
+An <strong><em>option field</em></strong> is an \bt_opt_fc instance.
+
+An option field either does or doesn't contain a field.
+
+Set whether or not an option field has a field with
+bt_field_option_set_has_field().
+
+Borrow the field from an option field with
+bt_field_option_borrow_field() or
+bt_field_option_borrow_field_const().
+
+<h1>\anchor api-tir-field-var Variant field</h1>
+
+A <strong><em>variant field</em></strong> is a \bt_var_fc instance.
+
+A variant field has a single selected option amongst one or more
+possible options. A variant field option contains a field: it's an
+instance of a variant field class option.
+
+Set the current option of a variant field with
+bt_field_variant_select_option_by_index().
+
+Get a variant field's selected option's index with
+bt_field_variant_get_selected_option_index().
+
+Borrow a variant field's selected option's field with
+bt_field_variant_borrow_selected_option_field() and
+bt_field_variant_borrow_selected_option_field_const().
+
+Borrow the class of a variant field's selected
+option with bt_field_variant_borrow_selected_option_class_const(),
+bt_field_variant_with_selector_field_integer_unsigned_borrow_selected_option_class_const(),
+and
+bt_field_variant_with_selector_field_integer_signed_borrow_selected_option_class_const().
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_field bt_field;
+
+@brief
+ Field.
+
+@}
+*/
+
+/*!
+@name Type query
+@{
+*/
+
+/*!
+@brief
+ Returns the type enumerator of the \ref api-tir-fc "class" of the
+ field \bt_p{field}.
+
+This function returns
+
+@code
+bt_field_class_get_type(bt_field_borrow_class(field))
+@endcode
+
+@param[in] field
+ Field of which to get the class's type enumerator
+
+@returns
+ Type enumerator of the class of \bt_p{field}.
+
+@bt_pre_not_null{field}
+
+@sa bt_field_class_get_type() —
+ Returns the type enumerator of a \bt_fc.
+*/
+extern bt_field_class_type bt_field_get_class_type(
+ const bt_field *field);
+
+/*! @} */
+
+/*!
+@name Class access
+@{
+*/
+
+/*!
+@brief
+ Borrows the \ref api-tir-fc "class" of the field \bt_p{field}.
+
+@param[in] field
+ Field of which to borrow the class.
+
+@returns
+ \em Borrowed reference of the class of \bt_p{field}.
+
+@bt_pre_not_null{field}
+
+@sa bt_field_borrow_class_const() —
+ \c const version of this function.
+*/