Fix API doc's content and style for enum. FT mapping iterator

Also, remove bt_ctf_field_type_enumeration_mapping_iterator_get_name(),
since you can achieve the same with
bt_ctf_field_type_enumeration_mapping_iterator_get_signed() or
bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned() with the
two last parameters set to NULL.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

diff --git a/doc/api/Doxyfile.in b/doc/api/Doxyfile.in
index 7670a36fb6ca75c5c0a82e4173be1b299b18e7f2..3ed3cac5783bdeac5d542e906be9be00f6d06923 100644 (file)
--- a/doc/api/Doxyfile.in
+++ b/doc/api/Doxyfile.in
@@ -49,7 +49,7 @@ ALIASES               += fts="\link ctfirfieldtypes CTF IR field types\endlink"
 ALIASES               += intft="\link ctfirintfieldtype CTF IR integer field type\endlink"
 ALIASES               += floatft="\link ctfirfloatfieldtype CTF IR floating point number field type\endlink"
 ALIASES               += enumft="\link ctfirenumfieldtype CTF IR enumeration field type\endlink"
 ALIASES               += intft="\link ctfirintfieldtype CTF IR integer field type\endlink"
 ALIASES               += floatft="\link ctfirfloatfieldtype CTF IR floating point number field type\endlink"
 ALIASES               += enumft="\link ctfirenumfieldtype CTF IR enumeration field type\endlink"

-ALIASES               += enumiter="\link ctfirenummappingiter CTF IR enumeration mapping iterator\endlink"
+ALIASES               += enumftiter="\link ctfirenumftmappingiter CTF IR enumeration field type mapping iterator\endlink"

 ALIASES               += stringft="\link ctfirstringfieldtype CTF IR string field type\endlink"
 ALIASES               += structft="\link ctfirstructfieldtype CTF IR structure field type\endlink"
 ALIASES               += arrayft="\link ctfirarrayfieldtype CTF IR array field type\endlink"
 ALIASES               += stringft="\link ctfirstringfieldtype CTF IR string field type\endlink"
 ALIASES               += structft="\link ctfirstructfieldtype CTF IR structure field type\endlink"
 ALIASES               += arrayft="\link ctfirarrayfieldtype CTF IR array field type\endlink"

diff --git a/formats/ctf/ir/field-types.c b/formats/ctf/ir/field-types.c
index 9e06840d4bda7dedfb6da2b2bf84609fc84cb861..02a47b366d900cb0d5e1aa29019ab5a00558d480 100644 (file)
--- a/formats/ctf/ir/field-types.c
+++ b/formats/ctf/ir/field-types.c
@@ -1146,24 +1146,6 @@ error:
        return NULL;
 }
 
        return NULL;
 }
 

-int bt_ctf_field_type_enumeration_mapping_iterator_get_name(
-               struct bt_ctf_field_type_enumeration_mapping_iterator *iter,
-               const char **mapping_name)
-{
-       int ret = 0;
-
-       if (!iter) {
-               ret = -1;
-               goto end;
-       }
-
-       ret = bt_ctf_field_type_enumeration_get_mapping_name(
-                       &iter->enumeration_type->parent, iter->index,
-                       mapping_name);
-end:
-       return ret;
-}
-

 int bt_ctf_field_type_enumeration_mapping_iterator_get_signed(
                struct bt_ctf_field_type_enumeration_mapping_iterator *iter,
                const char **mapping_name, int64_t *range_begin,
 int bt_ctf_field_type_enumeration_mapping_iterator_get_signed(
                struct bt_ctf_field_type_enumeration_mapping_iterator *iter,
                const char **mapping_name, int64_t *range_begin,


@@ -1894,8 +1876,8 @@ struct bt_ctf_field_type *bt_ctf_field_type_variant_get_field_type_from_tag(
                goto end;
        }
 
                goto end;
        }
 

-       ret = bt_ctf_field_type_enumeration_mapping_iterator_get_name(iter,
-               &enum_value);
+       ret = bt_ctf_field_type_enumeration_mapping_iterator_get_signed(iter,
+               &enum_value, NULL, NULL);

        if (ret) {
                goto end;
        }
        if (ret) {
                goto end;
        }

diff --git a/include/babeltrace/ctf-ir/field-types.h b/include/babeltrace/ctf-ir/field-types.h
index de4346481bf4f00ba3d014eb78cce159e965f14c..be004deaa7477c7341169c5395d012f4810b82df 100644 (file)
--- a/include/babeltrace/ctf-ir/field-types.h
+++ b/include/babeltrace/ctf-ir/field-types.h
@@ -1206,6 +1206,20 @@ bt_ctf_field_type_enumeration_add_mapping() or
 bt_ctf_field_type_enumeration_add_mapping_unsigned(), depending on the
 signedness of the wrapped @intft.
 
 bt_ctf_field_type_enumeration_add_mapping_unsigned(), depending on the
 signedness of the wrapped @intft.
 

+You can find mappings by name or by value with the following find
+operations:
+
+- bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the
+  mappings with a given name.
+- bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value():
+  Finds the mappings which contain a given unsigned value in their
+  range.
+- bt_ctf_field_type_enumeration_find_mappings_by_signed_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:
 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:


@@ -1229,9 +1243,9 @@ APPLE  -> [ 30, 55]
 Here, the range of the second \c APPLE mapping overlaps the range of
 the \c CHERRY mapping.
 
 Here, the range of the second \c APPLE mapping overlaps the range of
 the \c CHERRY mapping.
 

+@sa ctfirenumftmappingiter

 @sa ctfirenumfield
 @sa ctfirfieldtypes
 @sa ctfirenumfield
 @sa ctfirfieldtypes

-@sa ctfirenummappingiter

 
 @addtogroup ctfirenumfieldtype
 @{
 
 @addtogroup ctfirenumfieldtype
 @{


@@ -1374,20 +1388,35 @@ extern int bt_ctf_field_type_enumeration_get_mapping_unsigned(
                uint64_t *range_end);
 
 /**
                uint64_t *range_end);
 
 /**

-@brief  Returns a @enumiter on the mappings of the @enumft
-       \p enum_field_type that match \p name.
+@brief  Finds the mappings of the @enumft \p enum_field_type which
+       are named \p name.

 
 

-@param[in] enum_field_type     Enumeration field type of which to get
-                               the mapping at index \p index.
-@param[in] name                        Name of the mappings to find.
-@returns                       @enumiter that
-                               match \p name, or \c NULL on error.
+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
 
 @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_ctf_field_type_enumeration_find_mappings_by_signed_value(): Finds
+       the mappings of a given enumeration field type which contain
+       a given signed value in their range.
+@sa bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(): Finds
+       the mappings of a given enumeration field type which contain
+       a given unsigned value in their range.

 */
 extern struct bt_ctf_field_type_enumeration_mapping_iterator *
 bt_ctf_field_type_enumeration_find_mappings_by_name(
 */
 extern struct bt_ctf_field_type_enumeration_mapping_iterator *
 bt_ctf_field_type_enumeration_find_mappings_by_name(


@@ -1395,20 +1424,34 @@ bt_ctf_field_type_enumeration_find_mappings_by_name(
                const char *name);
 
 /**
                const char *name);
 
 /**

-@brief  Returns the mappings of the @enumft
-       \p enum_field_type that match \p value.
+@brief  Finds the mappings of the @enumft \p enum_field_type which
+       contain the signed value \p value in their range.

 
 

-@param[in] enum_field_type     Enumeration field type of which to get
-                               the mapping at index \p index.
-@param[in] value               Signed value of the mappings to find.
-@returns                       Iterator on enumeration mappings that
-                               match \p value, or \c NULL on error.
+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}
 
 @prenotnull{enum_field_type}

-@prenotnull{name}

 @preisenumft{enum_field_type}
 @postrefcountsame{enum_field_type}
 @postsuccessrefcountret1
 @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_ctf_field_type_enumeration_find_mappings_by_name(): Finds the
+       mappings of a given enumeration field type which have a given
+       name.
+@sa bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(): Finds
+       the mappings of a given enumeration field type which contain
+       a given unsigned value in their range.

 */
 extern struct bt_ctf_field_type_enumeration_mapping_iterator *
 bt_ctf_field_type_enumeration_find_mappings_by_signed_value(
 */
 extern struct bt_ctf_field_type_enumeration_mapping_iterator *
 bt_ctf_field_type_enumeration_find_mappings_by_signed_value(


@@ -1416,20 +1459,35 @@ bt_ctf_field_type_enumeration_find_mappings_by_signed_value(
                int64_t value);
 
 /**
                int64_t value);
 
 /**

-@brief  Returns the mappings of the @enumft
-       \p enum_field_type that match \p value.
+@brief  Finds the mappings of the @enumft \p enum_field_type which
+       contain the unsigned value \p value in their range.

 
 

-@param[in] enum_field_type     Enumeration field type of which to get
-                               the mapping at index \p index.
-@param[in] value               Unsigned value of the mappings to find.
-@returns                       Iterator on enumeration mappings that
-                               match \p value, or \c NULL on error.
+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}
 
 @prenotnull{enum_field_type}

-@prenotnull{name}

 @preisenumft{enum_field_type}
 @postrefcountsame{enum_field_type}
 @postsuccessrefcountret1
 @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_ctf_field_type_enumeration_find_mappings_by_name(): Finds the
+       mappings of a given enumeration field type which have a given
+       name.
+@sa bt_ctf_field_type_enumeration_find_mappings_by_signed_value(): Finds
+       the mappings of a given enumeration field type which contain
+       a given unsigned value in their range.

 */
 extern struct bt_ctf_field_type_enumeration_mapping_iterator *
 bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(
 */
 extern struct bt_ctf_field_type_enumeration_mapping_iterator *
 bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(


@@ -1515,129 +1573,157 @@ extern int bt_ctf_field_type_enumeration_add_mapping_unsigned(
 /** @} */
 
 /**
 /** @} */
 
 /**

-@defgroup ctfirenummappingiter CTF IR enumeration mapping iterator
-@ingroup ctfirfieldtypes
-@brief CTF IR enumeration mapping iterator.
-@struct bt_ctf_field_type_enumeration_mapping_iterator
+@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
 
 
 @code
 #include <babeltrace/ctf-ir/field-types.h>
 @endcode
 

-A CTF IR <strong><em>enumeration mapping iterator</em></strong> is an
-iterator on @enumft mappings.
-
-You can obtain an enumeration mapping iterator using one of the mapping
-query functions:bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(),
-bt_ctf_field_type_enumeration_find_mappings_by_signed_value(), and
-bt_ctf_field_type_enumeration_find_mappings_by_name().
-
-You can query an enumeration mapping's <strong>name</strong> from an iterator
-using bt_ctf_field_type_enumeration_mapping_iterator_get_name().
-
-You can also query an enumeration mapping's <strong>value range</strong>
-from an iterator with
-bt_ctf_field_type_enumeration_mapping_iterator_get_signed() or
-bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned(), depending on
-the signedness of the wrapped @intft.
-
-An <strong><em>enumeration mapping iterator</em></strong>'s position can
-be advanced using
-bt_ctf_field_type_enumeration_mapping_iterator_next().
+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_ctf_field_type_enumeration_find_mappings_by_name(): Finds the
+    mappings with a given name.
+  - bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value():
+    Finds the mappings which contain a given unsigned value in their
+    range.
+  - bt_ctf_field_type_enumeration_find_mappings_by_signed_value():
+    Finds the mappings which contain a given signed value in their range.
+- bt_ctf_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_ctf_field_type_enumeration_mapping_iterator_get_signed()
+or
+bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned(),
+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_ctf_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
 
 @sa ctfirenumfieldtype

-@sa ctfirenumfield

 
 

-@addtogroup ctfirenummappingiter
+@addtogroup ctfirenumftmappingiter

 @{
 */
 
 /**
 @{
 */
 
 /**

-@brief Returns the name of the @enumft mapping pointed to by
-       \p iter.
-
-On success, the returned \p mapping_name is valid as long as a reference
-is held on \p iter and its position is not changed.
-
-@param[in] iter                        Enumeration mapping iterator.
-@param[out] mapping_name       Returned name of the mapping pointed to
-                               by \p iter.
-@returns                       0 on success, or a negative value on error.
-
-@prenotnull{iter}
-@prenotnull{mapping_name}
-@postrefcountsame{iter}
+@struct bt_ctf_field_type_enumeration_mapping_iterator
+@brief A CTF IR enumeration field type mapping iterator.
+@sa ctfirenumftmappingiter

 */
 */

-extern int bt_ctf_field_type_enumeration_mapping_iterator_get_name(
-               struct bt_ctf_field_type_enumeration_mapping_iterator *iter,
-               const char **mapping_name);

 
 /**
 
 /**

-@brief Returns the range of the signed @enumft mapping pointed to by
-       \p iter.
+@brief  Returns the name and the range of the current (signed) mapping
+       of the @enumftiter \p iter.

 
 

-The @intft wrapped by \p enum_field_type, as returned by
+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_ctf_field_type_enumeration_get_container_type(), must be
 bt_ctf_field_type_enumeration_get_container_type(), must be

-\b signed to use this function.
-
-@param[in] iter                        Enumeration mapping iterator.
+\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_ctf_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
 @param[out] range_begin                Returned beginning of the range

-                               (included) of the mapping pointed to by
-                               \p iter.
-@param[out] range_end          Returned end of the range (included) of
-                               the mapping pointed to by \p iter.
+                               (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}
 @returns                       0 on success, or a negative value on error.
 
 @prenotnull{iter}

-@prenotnull{range_begin}
-@prenotnull{range_end}

 @postrefcountsame{iter}
 
 @postrefcountsame{iter}
 

-@sa bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned(): Returns
-       the range of the unsigned enumeration mapping pointed by an enumeration
-       mapping iterator.
+@sa bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned():
+       Returns the name and the unsigned range of the current mapping
+       of a given enumeration field type mapping iterator.

 */
 extern int bt_ctf_field_type_enumeration_mapping_iterator_get_signed(
                struct bt_ctf_field_type_enumeration_mapping_iterator *iter,
 */
 extern int bt_ctf_field_type_enumeration_mapping_iterator_get_signed(
                struct bt_ctf_field_type_enumeration_mapping_iterator *iter,

-               const char **mapping_name,
-               int64_t *range_begin, int64_t *range_end);
+               const char **name, int64_t *range_begin, int64_t *range_end);

 
 /**
 
 /**

-@brief Returns the range of the unsigned @enumft mapping pointed to by
-       \p iter.
+@brief  Returns the name and the range of the current (unsigned) mapping
+       of the @enumftiter \p iter.

 
 

-The @intft wrapped by \p enum_field_type, as returned by
+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_ctf_field_type_enumeration_get_container_type(), must be
 bt_ctf_field_type_enumeration_get_container_type(), must be

-\b unsigned to use this function.
-
-@param[in] iter                        Enumeration mapping iterator.
+\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_ctf_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
 @param[out] range_begin                Returned beginning of the range

-                               (included) of the mapping pointed to by
-                               \p iter.
-@param[out] range_end          Returned end of the range (included) of
-                               the mapping pointed to by \p iter.
+                               (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}
 @returns                       0 on success, or a negative value on error.
 
 @prenotnull{iter}

-@prenotnull{range_begin}
-@prenotnull{range_end}

 @postrefcountsame{iter}
 
 @postrefcountsame{iter}
 

-@sa bt_ctf_field_type_enumeration_mapping_iterator_get_signed(): Returns the
-       range of the signed enumeration mapping pointed by an enumeration
-       mapping iterator.
+@sa
+       bt_ctf_field_type_enumeration_mapping_iterator_get_signed():
+       Returns the name and the signed range of the current mapping of
+       a given enumeration field type mapping iterator.

 */
 extern int bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned(
                struct bt_ctf_field_type_enumeration_mapping_iterator *iter,
 */
 extern int bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned(
                struct bt_ctf_field_type_enumeration_mapping_iterator *iter,

-               const char **mapping_name,
-               uint64_t *range_begin, uint64_t *range_end);
+               const char **name, uint64_t *range_begin, uint64_t *range_end);

 
 /**
 
 /**

-@brief Advance the position of the @enumiter \p iter.
+@brief Advances the @enumftiter \p iter to the next mapping.

 
 

-@param[in] iter                        Enumeration mapping iterator.
-@returns                       0 on success, or a negative value on error or
-                               end of mappings set.
+@param[in] iter                Enumeration field type mapping iterator to
+                       advance.
+@returns               0 on success, or a negative value on error or
+                       when you reach the end of the set.

 
 @prenotnull{iter}
 @postrefcountsame{iter}
 
 @prenotnull{iter}
 @postrefcountsame{iter}

diff --git a/include/babeltrace/ctf-ir/fields.h b/include/babeltrace/ctf-ir/fields.h
index 3a4c76a66dc6b30286f20942d81319bbe81b1076..2ce3b633745ecfa712f125894697353dd2b1d7a0 100644 (file)
--- a/include/babeltrace/ctf-ir/fields.h
+++ b/include/babeltrace/ctf-ir/fields.h
@@ -607,9 +607,9 @@ bt_ctf_field_signed_integer_set_value() or
 bt_ctf_field_unsigned_integer_set_value().
 
 Once you set the integral value of an enumeration field by following the
 bt_ctf_field_unsigned_integer_set_value().
 
 Once you set the integral value of an enumeration field by following the

-previous paragraph, you can get the names of the mappings containing this
-value in the enumeration field with
-bt_ctf_field_enumeration_get_mappings().
+previous paragraph, you can get the mappings containing this value in
+their range with bt_ctf_field_enumeration_get_mappings(). This function
+returns a @enumftiter.

 
 @sa ctfirenumfieldtype
 @sa ctfirfields
 
 @sa ctfirenumfieldtype
 @sa ctfirfields


@@ -639,15 +639,23 @@ extern struct bt_ctf_field *bt_ctf_field_enumeration_get_container(
                struct bt_ctf_field *enum_field);
 
 /**
                struct bt_ctf_field *enum_field);
 
 /**

-@brief Returns a @enumiter to the mappings selected by the current
-       integral value of the @enumfield \p enum_field.
-
-@param[in] enum_field  Enumeration field of which to get the name of
-                       mapping associated to its current integral
-                       value.
-@returns               An iterator to the mappings associated to the
-                       current integral value of \p enum_field, or
-                       \c NULL on error.
+@brief Returns a @enumftiter on all the mappings of the field type of
+       \p enum_field which contain the current integral value of the
+       @enumfield \p enum_field in their range.
+
+This function is the equivalent of using
+bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value() or
+bt_ctf_field_type_enumeration_find_mappings_by_signed_value() with the
+current integral value of \p enum_field.
+
+@param[in] enum_field  Enumeration field of which to get the mappings
+                       containing the current integral value of \p
+                       enum_field in their range.
+@returns                @enumftiter on the set of mappings of the field
+                       type of \p enum_field which contain the current
+                       integral value of \p enum_field in their range,
+                       or \c NULL if no mappings were found or on
+                       error.

 
 @prenotnull{enum_field}
 @preisenumfield{enum_field}
 
 @prenotnull{enum_field}
 @preisenumfield{enum_field}


@@ -655,6 +663,8 @@ extern struct bt_ctf_field *bt_ctf_field_enumeration_get_container(
        value.
 @postrefcountsame{enum_field}
 @postsuccessrefcountret1
        value.
 @postrefcountsame{enum_field}
 @postsuccessrefcountret1

+@post <strong>On success</strong>, the returned @enumftiter can iterate
+       on at least one mapping.

 */
 extern struct bt_ctf_field_type_enumeration_mapping_iterator *
 bt_ctf_field_enumeration_get_mappings(struct bt_ctf_field *enum_field);
 */
 extern struct bt_ctf_field_type_enumeration_mapping_iterator *
 bt_ctf_field_enumeration_get_mappings(struct bt_ctf_field *enum_field);

diff --git a/tests/lib/test_ctf_writer.c b/tests/lib/test_ctf_writer.c
index eebb37fb2961317963abddb2d76f644acabd684b..70ca61f082fd670f7c0f6d654f40353233083d49 100644 (file)
--- a/tests/lib/test_ctf_writer.c
+++ b/tests/lib/test_ctf_writer.c
@@ -597,8 +597,8 @@ void append_simple_event(struct bt_ctf_stream_class *stream_class,
                "Set signed enumeration container value");
        iter = bt_ctf_field_enumeration_get_mappings(enum_field);
        ok(iter, "bt_ctf_field_enumeration_get_mappings returns an iterator to matching mappings");
                "Set signed enumeration container value");
        iter = bt_ctf_field_enumeration_get_mappings(enum_field);
        ok(iter, "bt_ctf_field_enumeration_get_mappings returns an iterator to matching mappings");

-       ret = bt_ctf_field_type_enumeration_mapping_iterator_get_name(iter, &ret_char);
-       ok(!ret && ret_char, "bt_ctf_field_type_enumeration_mapping_iterator_get_name return a mapping name");
+       ret = bt_ctf_field_type_enumeration_mapping_iterator_get_signed(iter, &ret_char, NULL, NULL);
+       ok(!ret && ret_char, "bt_ctf_field_type_enumeration_mapping_iterator_get_signed return a mapping name");

        ok(!strcmp(ret_char, mapping_name_negative_test),
                "bt_ctf_field_enumeration_get_single_mapping_name returns the correct mapping name with an signed container");
        ret = bt_ctf_event_set_payload(simple_event, "enum_field", enum_field);
        ok(!strcmp(ret_char, mapping_name_negative_test),
                "bt_ctf_field_enumeration_get_single_mapping_name returns the correct mapping name with an signed container");
        ret = bt_ctf_event_set_payload(simple_event, "enum_field", enum_field);


@@ -617,9 +617,9 @@ void append_simple_event(struct bt_ctf_stream_class *stream_class,
        assert(!ret);
        iter = bt_ctf_field_enumeration_get_mappings(enum_field_unsigned);
        assert(iter);
        assert(!ret);
        iter = bt_ctf_field_enumeration_get_mappings(enum_field_unsigned);
        assert(iter);

-       (void) bt_ctf_field_type_enumeration_mapping_iterator_get_name(iter, &ret_char);
+       (void) bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned(iter, &ret_char, NULL, NULL);

        ok(ret_char && !strcmp(ret_char, mapping_name_test),
        ok(ret_char && !strcmp(ret_char, mapping_name_test),

-               "bt_ctf_field_enumeration_get_single_mapping_name returns the correct mapping name with an unsigned container");
+               "bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned returns the correct mapping name with an unsigned container");

 
        ok(bt_ctf_clock_set_time(clock, current_time) == 0, "Set clock time");
 
 
        ok(bt_ctf_clock_set_time(clock, current_time) == 0, "Set clock time");
 


@@ -1717,8 +1717,8 @@ void field_copy_tests()
 
        /* validate e copy */
        e_iter = bt_ctf_field_enumeration_get_mappings(e_copy);
 
        /* validate e copy */
        e_iter = bt_ctf_field_enumeration_get_mappings(e_copy);

-       (void) bt_ctf_field_type_enumeration_mapping_iterator_get_name(e_iter,
-               &str_val);
+       (void) bt_ctf_field_type_enumeration_mapping_iterator_get_signed(e_iter,
+               &str_val, NULL, NULL);

        ok(str_val && !strcmp(str_val, "LABEL2"),
                "bt_ctf_field_copy creates a valid enum field copy");
 
        ok(str_val && !strcmp(str_val, "LABEL2"),
                "bt_ctf_field_copy creates a valid enum field copy");