+/*!
+@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.