From 5c3f3b7ee3f3eb7a781266f660da3c9bb523277d Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Tue, 24 Jan 2017 20:11:53 -0500 Subject: [PATCH] Fix API doc's content and style for enum. FT mapping iterator MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit 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 Signed-off-by: Jérémie Galarneau --- doc/api/Doxyfile.in | 2 +- formats/ctf/ir/field-types.c | 22 +- include/babeltrace/ctf-ir/field-types.h | 296 +++++++++++++++--------- include/babeltrace/ctf-ir/fields.h | 34 ++- tests/lib/test_ctf_writer.c | 12 +- 5 files changed, 222 insertions(+), 144 deletions(-) diff --git a/doc/api/Doxyfile.in b/doc/api/Doxyfile.in index 7670a36f..3ed3cac5 100644 --- 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 += 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" diff --git a/formats/ctf/ir/field-types.c b/formats/ctf/ir/field-types.c index 9e06840d..02a47b36 100644 --- a/formats/ctf/ir/field-types.c +++ b/formats/ctf/ir/field-types.c @@ -1146,24 +1146,6 @@ error: 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, @@ -1894,8 +1876,8 @@ struct bt_ctf_field_type *bt_ctf_field_type_variant_get_field_type_from_tag( 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; } diff --git a/include/babeltrace/ctf-ir/field-types.h b/include/babeltrace/ctf-ir/field-types.h index de434648..be004dea 100644 --- 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. +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: @@ -1229,9 +1243,9 @@ APPLE -> [ 30, 55] Here, the range of the second \c APPLE mapping overlaps the range of the \c CHERRY mapping. +@sa ctfirenumftmappingiter @sa ctfirenumfield @sa ctfirfieldtypes -@sa ctfirenummappingiter @addtogroup ctfirenumfieldtype @{ @@ -1374,20 +1388,35 @@ extern int bt_ctf_field_type_enumeration_get_mapping_unsigned( 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 +@post On success, 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( @@ -1395,20 +1424,34 @@ bt_ctf_field_type_enumeration_find_mappings_by_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{name} @preisenumft{enum_field_type} @postrefcountsame{enum_field_type} @postsuccessrefcountret1 +@post On success, 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( @@ -1416,20 +1459,35 @@ bt_ctf_field_type_enumeration_find_mappings_by_signed_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{name} @preisenumft{enum_field_type} @postrefcountsame{enum_field_type} @postsuccessrefcountret1 +@post On success, 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( @@ -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 @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(). +A CTF IR enumeration field type mapping +iterator 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 reference +counts. See \ref refs to learn more about the reference counting +management of Babeltrace objects. @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 -\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 - (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} -@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. +@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, - 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 -\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 - (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} -@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. +@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, - 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} diff --git a/include/babeltrace/ctf-ir/fields.h b/include/babeltrace/ctf-ir/fields.h index 3a4c76a6..2ce3b633 100644 --- 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 -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 @@ -639,15 +639,23 @@ extern struct bt_ctf_field *bt_ctf_field_enumeration_get_container( 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} @@ -655,6 +663,8 @@ extern struct bt_ctf_field *bt_ctf_field_enumeration_get_container( value. @postrefcountsame{enum_field} @postsuccessrefcountret1 +@post On success, 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); diff --git a/tests/lib/test_ctf_writer.c b/tests/lib/test_ctf_writer.c index eebb37fb..70ca61f0 100644 --- 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"); - 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); @@ -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); - (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), - "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"); @@ -1717,8 +1717,8 @@ void field_copy_tests() /* 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"); -- 2.34.1