From cfb61c11ca4199917f6cd0e12a3d3951929dbe83 Mon Sep 17 00:00:00 2001 From: =?utf8?q?J=C3=A9r=C3=A9mie=20Galarneau?= Date: Mon, 23 Jan 2017 23:41:18 -0500 Subject: [PATCH] Docs: document enumeration mapping iterator API MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Signed-off-by: Jérémie Galarneau --- include/babeltrace/ctf-ir/field-types.h | 156 +++++++++++++++++++++--- 1 file changed, 137 insertions(+), 19 deletions(-) diff --git a/include/babeltrace/ctf-ir/field-types.h b/include/babeltrace/ctf-ir/field-types.h index 05c21384..de434648 100644 --- a/include/babeltrace/ctf-ir/field-types.h +++ b/include/babeltrace/ctf-ir/field-types.h @@ -1177,21 +1177,6 @@ extern int bt_ctf_field_type_floating_point_set_mantissa_digits( /** @} */ -extern int bt_ctf_field_type_enumeration_mapping_iterator_get_name( - struct bt_ctf_field_type_enumeration_mapping_iterator *iter, - const char **mapping_name); - -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); - -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); - -extern int bt_ctf_field_type_enumeration_mapping_iterator_next( - struct bt_ctf_field_type_enumeration_mapping_iterator *iter); - /** @defgroup ctfirenumfieldtype CTF IR enumeration field type @ingroup ctfirfieldtypes @@ -1337,8 +1322,8 @@ On success, \p enum_field_type remains the sole owner of \p *name. bt_ctf_field_type_enumeration_get_mapping_count()). @postrefcountsame{enum_field_type} -@sa bt_ctf_field_type_enumeration_get_mapping_signed(): Returns the - signed mapping contained by a given enumeration field type +@sa bt_ctf_field_type_enumeration_get_mapping_unsigned(): Returns the + unsigned mapping contained by a given enumeration field type at a given index. */ extern int bt_ctf_field_type_enumeration_get_mapping_signed( @@ -1379,8 +1364,8 @@ On success, \p enum_field_type remains the sole owner of \p *name. bt_ctf_field_type_enumeration_get_mapping_count()). @postrefcountsame{enum_field_type} -@sa bt_ctf_field_type_enumeration_get_mapping_unsigned(): Returns the - unsigned mapping contained by a given enumeration field type +@sa bt_ctf_field_type_enumeration_get_mapping_signed(): Returns the + signed mapping contained by a given enumeration field type at a given index. */ extern int bt_ctf_field_type_enumeration_get_mapping_unsigned( @@ -1529,6 +1514,139 @@ 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 + +@code +#include +@endcode + +A CTF IR enumeration mapping iterator 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 name from an iterator +using bt_ctf_field_type_enumeration_mapping_iterator_get_name(). + +You can also query an enumeration mapping's value range +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 enumeration mapping iterator's position can +be advanced using +bt_ctf_field_type_enumeration_mapping_iterator_next(). + +@sa ctfirenumfieldtype +@sa ctfirenumfield + +@addtogroup ctfirenummappingiter +@{ +*/ + +/** +@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} +*/ +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. + +The @intft wrapped by \p enum_field_type, as returned by +bt_ctf_field_type_enumeration_get_container_type(), must be +\b signed to use this function. + +@param[in] iter Enumeration mapping iterator. +@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. +@returns 0 on success, or a negative value on error. + +@prenotnull{iter} +@prenotnull{range_begin} +@prenotnull{range_end} +@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. +*/ +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); + +/** +@brief Returns the range of the unsigned @enumft mapping pointed to by + \p iter. + +The @intft wrapped by \p enum_field_type, as returned by +bt_ctf_field_type_enumeration_get_container_type(), must be +\b unsigned to use this function. + +@param[in] iter Enumeration mapping iterator. +@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. +@returns 0 on success, or a negative value on error. + +@prenotnull{iter} +@prenotnull{range_begin} +@prenotnull{range_end} +@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. +*/ +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); + +/** +@brief Advance the position of the @enumiter \p iter. + +@param[in] iter Enumeration mapping iterator. +@returns 0 on success, or a negative value on error or + end of mappings set. + +@prenotnull{iter} +@postrefcountsame{iter} +*/ +extern int bt_ctf_field_type_enumeration_mapping_iterator_next( + struct bt_ctf_field_type_enumeration_mapping_iterator *iter); + +/** @} */ + /** @defgroup ctfirstringfieldtype CTF IR string field type @ingroup ctfirfieldtypes -- 2.34.1