Omit 'value' from is_set and reset field functions

[babeltrace.git] / include / babeltrace / ctf-ir / fields.h

diff --git a/include/babeltrace/ctf-ir/fields.h b/include/babeltrace/ctf-ir/fields.h
index 144b1e31773b296a7396708ed7716e8f9909f869..a6250ed7ab7f1b10b3ede5ae0cdd1276a5fe0cc8 100644 (file)
--- a/include/babeltrace/ctf-ir/fields.h
+++ b/include/babeltrace/ctf-ir/fields.h
@@ -32,13 +32,16 @@
 
 #include <stdint.h>
 #include <stddef.h>
-#include <babeltrace/ctf-ir/field-types.h>
+
+/* For bt_bool */
 #include <babeltrace/types.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+struct bt_ctf_field_type;
+
 /**
 @defgroup ctfirfields CTF IR fields
 @ingroup ctfir
@@ -85,13 +88,14 @@ contained fields with the following getters if such fields do not exist
 yet:
 
 - bt_ctf_field_enumeration_get_container()
-- bt_ctf_field_structure_get_field()
+- bt_ctf_field_structure_get_field_by_name()
 - bt_ctf_field_array_get_field()
 - bt_ctf_field_sequence_get_field()
 - bt_ctf_field_variant_get_field()
 
 If you already have a field object, you can also assign it to a specific
-name within a @structfield with bt_ctf_field_structure_set_field().
+name within a @structfield with
+bt_ctf_field_structure_set_field_by_name().
 
 You can get a reference to the @ft which was used to create a field with
 bt_ctf_field_get_type(). You can get the
@@ -212,7 +216,13 @@ extern struct bt_ctf_field_type *bt_ctf_field_get_type(
 @sa bt_ctf_field_is_variant(): Returns whether or not a given field is a
        @varfield.
 */
-extern enum bt_ctf_field_type_id bt_ctf_field_get_type_id(struct bt_ctf_field *field);
+extern enum bt_ctf_field_type_id bt_ctf_field_get_type_id(
+               struct bt_ctf_field *field);
+
+
+extern bt_bool bt_ctf_field_is_set(struct bt_ctf_field *field);
+
+extern int bt_ctf_field_reset(struct bt_ctf_field *field);
 
 /*
  * bt_ctf_field_signed_integer_get_value: get a signed integer field's value
@@ -828,10 +838,10 @@ contains an ordered list of zero or more named @fields which can be
 different @fts, and which is described by a @structft.
 
 To set the value of a specific field of a structure field, you need to
-first get the field with bt_ctf_field_structure_get_field() or
+first get the field with bt_ctf_field_structure_get_field_by_name() or
 bt_ctf_field_structure_get_field_by_index(). If you already have a
 field object, you can assign it to a specific name within a structure
-field with bt_ctf_field_structure_set_field().
+field with bt_ctf_field_structure_set_field_by_name().
 
 @sa ctfirstructfieldtype
 @sa ctfirfields
@@ -861,8 +871,8 @@ exist.
 
 @sa bt_ctf_field_structure_get_field_by_index(): Returns the field of a
        given structure field by index.
-@sa bt_ctf_field_structure_set_field(): Sets the field of a given
-       structure field.
+@sa bt_ctf_field_structure_set_field_by_name(): Sets the field of a
+       given structure field by name.
 */
 extern struct bt_ctf_field *bt_ctf_field_structure_get_field_by_name(
                struct bt_ctf_field *struct_field, const char *name);
@@ -888,10 +898,10 @@ extern struct bt_ctf_field *bt_ctf_field_structure_get_field_by_name(
 @postrefcountsame{struct_field}
 @postsuccessrefcountretinc
 
-@sa bt_ctf_field_structure_get_field(): Returns the field of a
+@sa bt_ctf_field_structure_get_field_by_name(): Returns the field of a
+       given structure field by name.
+@sa bt_ctf_field_structure_set_field_by_name(): Sets the field of a
        given structure field by name.
-@sa bt_ctf_field_structure_set_field(): Sets the field of a given
-       structure field.
 */
 extern struct bt_ctf_field *bt_ctf_field_structure_get_field_by_index(
                struct bt_ctf_field *struct_field, uint64_t index);
@@ -900,8 +910,9 @@ extern struct bt_ctf_field *bt_ctf_field_structure_get_field_by_index(
 @brief Sets the field of the @structfield \p struct_field named \p name
        to the @field \p field.
 
-If \p struct_field already contains a field named \p name, then its
-reference count is decremented, and \p field replaces it.
+If \p struct_field already contains a field named \p name, then it may
+either be replaced by \p field and its reference count is decremented,
+or \p field's value is assigned to it.
 
 The field type of \p field, as returned by bt_ctf_field_get_type(),
 \em must be equivalent to the field type returned by
@@ -926,17 +937,17 @@ bt_ctf_trace_get_packet_header_type() for the parent trace class of
        bt_ctf_field_type_structure_get_field_type_by_name() for the
        field type of \p struct_field with the name \p name.
 @postrefcountsame{struct_field}
-@post <strong>On success, if there's an existing field in
-       \p struct_field named \p name</strong>, its reference count is
-       decremented.
+@post <strong>On success, the field in \p struct_field named \p name</strong>
+       may either be replaced by \p field or have the same value as \p field.
 @postsuccessrefcountinc{field}
 
 @sa bt_ctf_field_structure_get_field_by_index(): Returns the field of a
        given structure field by index.
-@sa bt_ctf_field_structure_get_field(): Returns the field of a
+@sa bt_ctf_field_structure_get_field_by_name(): Returns the field of a
        given structure field by name.
 */
-extern int bt_ctf_field_structure_set_field(struct bt_ctf_field *struct_field,
+extern int bt_ctf_field_structure_set_field_by_name(
+               struct bt_ctf_field *struct_field,
                const char *name, struct bt_ctf_field *field);
 
 /** @} */