From 8dc7eb94471b9ca685b244d7e735b47af57da0d6 Mon Sep 17 00:00:00 2001 From: =?utf8?q?J=C3=A9r=C3=A9mie=20Galarneau?= Date: Mon, 23 Jan 2017 21:31:05 -0500 Subject: [PATCH] Docs: add documentation for bt_ctf_field_type_enumeration_find_mappings* MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Signed-off-by: Jérémie Galarneau --- doc/api/Doxyfile.in | 1 + include/babeltrace/ctf-ir/field-types.h | 91 +++++++++++++++++++------ include/babeltrace/ctf-ir/fields.h | 6 +- 3 files changed, 73 insertions(+), 25 deletions(-) diff --git a/doc/api/Doxyfile.in b/doc/api/Doxyfile.in index 9adbac22..7670a36f 100644 --- a/doc/api/Doxyfile.in +++ b/doc/api/Doxyfile.in @@ -49,6 +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 += enumiter="\link ctfirenummappingiter CTF IR enumeration 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" diff --git a/include/babeltrace/ctf-ir/field-types.h b/include/babeltrace/ctf-ir/field-types.h index 420ae7f4..05c21384 100644 --- a/include/babeltrace/ctf-ir/field-types.h +++ b/include/babeltrace/ctf-ir/field-types.h @@ -1177,34 +1177,19 @@ extern int bt_ctf_field_type_floating_point_set_mantissa_digits( /** @} */ -struct bt_ctf_field_type_enumeration_mapping_iterator * - bt_ctf_field_type_enumeration_find_mappings_by_name( - struct bt_ctf_field_type *type, - const char *name); - -struct bt_ctf_field_type_enumeration_mapping_iterator * - bt_ctf_field_type_enumeration_find_mappings_by_signed_value( - struct bt_ctf_field_type *type, - int64_t value); - -struct bt_ctf_field_type_enumeration_mapping_iterator * - bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value( - struct bt_ctf_field_type *type, - uint64_t value); - -int bt_ctf_field_type_enumeration_mapping_iterator_get_name( +extern int bt_ctf_field_type_enumeration_mapping_iterator_get_name( struct bt_ctf_field_type_enumeration_mapping_iterator *iter, const char **mapping_name); -int bt_ctf_field_type_enumeration_mapping_iterator_get_signed( +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 *lower, int64_t *upper); -int bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned( +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 *lower, uint64_t *upper); -int bt_ctf_field_type_enumeration_mapping_iterator_next( +extern int bt_ctf_field_type_enumeration_mapping_iterator_next( struct bt_ctf_field_type_enumeration_mapping_iterator *iter); /** @@ -1261,6 +1246,7 @@ the \c CHERRY mapping. @sa ctfirenumfield @sa ctfirfieldtypes +@sa ctfirenummappingiter @addtogroup ctfirenumfieldtype @{ @@ -1329,7 +1315,7 @@ 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 +@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. @@ -1371,7 +1357,7 @@ 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 +@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. @@ -1402,6 +1388,69 @@ extern int bt_ctf_field_type_enumeration_get_mapping_unsigned( const char **name, uint64_t *range_begin, uint64_t *range_end); +/** +@brief Returns a @enumiter on the mappings of the @enumft + \p enum_field_type that match \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. + +@prenotnull{enum_field_type} +@prenotnull{name} +@preisenumft{enum_field_type} +@postrefcountsame{enum_field_type} +@postsuccessrefcountret1 +*/ +extern struct bt_ctf_field_type_enumeration_mapping_iterator * +bt_ctf_field_type_enumeration_find_mappings_by_name( + struct bt_ctf_field_type *enum_field_type, + const char *name); + +/** +@brief Returns the mappings of the @enumft + \p enum_field_type that match \p value. + +@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. + +@prenotnull{enum_field_type} +@prenotnull{name} +@preisenumft{enum_field_type} +@postrefcountsame{enum_field_type} +@postsuccessrefcountret1 +*/ +extern struct bt_ctf_field_type_enumeration_mapping_iterator * +bt_ctf_field_type_enumeration_find_mappings_by_signed_value( + struct bt_ctf_field_type *enum_field_type, + int64_t value); + +/** +@brief Returns the mappings of the @enumft + \p enum_field_type that match \p value. + +@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. + +@prenotnull{enum_field_type} +@prenotnull{name} +@preisenumft{enum_field_type} +@postrefcountsame{enum_field_type} +@postsuccessrefcountret1 +*/ +extern struct bt_ctf_field_type_enumeration_mapping_iterator * +bt_ctf_field_type_enumeration_find_mappings_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 diff --git a/include/babeltrace/ctf-ir/fields.h b/include/babeltrace/ctf-ir/fields.h index 4cc8b03d..3a4c76a6 100644 --- a/include/babeltrace/ctf-ir/fields.h +++ b/include/babeltrace/ctf-ir/fields.h @@ -639,12 +639,9 @@ extern struct bt_ctf_field *bt_ctf_field_enumeration_get_container( struct bt_ctf_field *enum_field); /** -@brief Returns an iterator to the mappings selected by the current +@brief Returns a @enumiter to the mappings selected by the current integral value of the @enumfield \p enum_field. -On success, \p enum_field remains the sole owner of the returned -value. - @param[in] enum_field Enumeration field of which to get the name of mapping associated to its current integral value. @@ -657,6 +654,7 @@ value. @pre The wrapped integer field of \p enum_field contains an integral value. @postrefcountsame{enum_field} +@postsuccessrefcountret1 */ extern struct bt_ctf_field_type_enumeration_mapping_iterator * bt_ctf_field_enumeration_get_mappings(struct bt_ctf_field *enum_field); -- 2.34.1