Port: __STRINGIFY exists on Cygwin

[babeltrace.git] / include / babeltrace / values.h

diff --git a/include/babeltrace/values.h b/include/babeltrace/values.h
index d5ffef0b94bd0dada2201102d227e9db6799bd42..d4a2214b1f35ff355ceeebadefa0f33a381c3c23 100644 (file)
--- a/include/babeltrace/values.h
+++ b/include/babeltrace/values.h
@@ -1,5 +1,5 @@
-#ifndef _BABELTRACE_VALUES_H
-#define _BABELTRACE_VALUES_H
+#ifndef BABELTRACE_VALUES_H
+#define BABELTRACE_VALUES_H

 
 /*
  * Babeltrace - Value objects
 
 /*
  * Babeltrace - Value objects


@@ -27,9 +27,9 @@
  */
 
 #include <stdint.h>
  */
 
 #include <stdint.h>

-#include <stdbool.h>

 #include <stddef.h>
 #include <babeltrace/ref.h>
 #include <stddef.h>
 #include <babeltrace/ref.h>

+#include <babeltrace/types.h>

 
 #ifdef __cplusplus
 extern "C" {
 
 #ifdef __cplusplus
 extern "C" {


@@ -40,6 +40,10 @@ extern "C" {
 @ingroup apiref
 @brief Value objects.
 
 @ingroup apiref
 @brief Value objects.
 

+@code
+#include <babeltrace/values.h>
+@endcode
+

 This is a set of <strong><em>value objects</em></strong>. With the
 functions documented here, you can create and modify:
 
 This is a set of <strong><em>value objects</em></strong>. With the
 functions documented here, you can create and modify:
 


@@ -143,7 +147,8 @@ to use for each value object type:
   </tr>
   <tr>
     <th>Map
   </tr>
   <tr>
     <th>Map

-    <td>bt_value_map_create()
+    <td>bt_value_map_create()<br>
+        bt_value_map_extend()

     <td>bt_value_is_map()
     <td>bt_value_map_get()<br>
         bt_value_map_foreach()
     <td>bt_value_is_map()
     <td>bt_value_map_get()<br>
         bt_value_map_foreach()


@@ -176,7 +181,7 @@ enum bt_value_status {
        BT_VALUE_STATUS_CANCELLED =     -3,
 
        /* -22 for compatibility with -EINVAL */
        BT_VALUE_STATUS_CANCELLED =     -3,
 
        /* -22 for compatibility with -EINVAL */

-       /// Invalid arguments.
+       /// Invalid argument.

        BT_VALUE_STATUS_INVAL =         -22,
 
        /// General error.
        BT_VALUE_STATUS_INVAL =         -22,
 
        /// General error.


@@ -230,7 +235,7 @@ enum bt_value_type {
        /// Null value object.
        BT_VALUE_TYPE_NULL =            0,
 
        /// Null value object.
        BT_VALUE_TYPE_NULL =            0,
 

-       /// Boolean value object (holds \c true or \c false).
+       /// Boolean value object (holds #BT_TRUE or #BT_FALSE).

        BT_VALUE_TYPE_BOOL =            1,
 
        /// Integer value object (holds a signed 64-bit integer raw value).
        BT_VALUE_TYPE_BOOL =            1,
 
        /// Integer value object (holds a signed 64-bit integer raw value).


@@ -287,7 +292,7 @@ An alternative to calling this function is to directly compare the value
 object pointer to the \ref bt_value_null variable.
 
 @param[in] object      Value object to check.
 object pointer to the \ref bt_value_null variable.
 
 @param[in] object      Value object to check.

-@returns               \c true if \p object is the null value object.
+@returns               #BT_TRUE if \p object is the null value object.

 
 @prenotnull{object}
 @postrefcountsame{object}
 
 @prenotnull{object}
 @postrefcountsame{object}


@@ -295,7 +300,7 @@ object pointer to the \ref bt_value_null variable.
 @sa bt_value_get_type(): Returns the type of a given value object.
 */
 static inline
 @sa bt_value_get_type(): Returns the type of a given value object.
 */
 static inline

-bool bt_value_is_null(const struct bt_value *object)
+bt_bool bt_value_is_null(const struct bt_value *object)

 {
        return bt_value_get_type(object) == BT_VALUE_TYPE_NULL;
 }
 {
        return bt_value_get_type(object) == BT_VALUE_TYPE_NULL;
 }


@@ -305,7 +310,7 @@ bool bt_value_is_null(const struct bt_value *object)
        value object.
 
 @param[in] object      Value object to check.
        value object.
 
 @param[in] object      Value object to check.

-@returns               \c true if \p object is a boolean value object.
+@returns               #BT_TRUE if \p object is a boolean value object.

 
 @prenotnull{object}
 @postrefcountsame{object}
 
 @prenotnull{object}
 @postrefcountsame{object}


@@ -313,7 +318,7 @@ bool bt_value_is_null(const struct bt_value *object)
 @sa bt_value_get_type(): Returns the type of a given value object.
 */
 static inline
 @sa bt_value_get_type(): Returns the type of a given value object.
 */
 static inline

-bool bt_value_is_bool(const struct bt_value *object)
+bt_bool bt_value_is_bool(const struct bt_value *object)

 {
        return bt_value_get_type(object) == BT_VALUE_TYPE_BOOL;
 }
 {
        return bt_value_get_type(object) == BT_VALUE_TYPE_BOOL;
 }


@@ -323,12 +328,12 @@ bool bt_value_is_bool(const struct bt_value *object)
        value object.
 
 @param[in] object      Value object to check.
        value object.
 
 @param[in] object      Value object to check.

-@returns               \c true if \p object is an integer value object.
+@returns               #BT_TRUE if \p object is an integer value object.

 
 @sa bt_value_get_type(): Returns the type of a given value object.
 */
 static inline
 
 @sa bt_value_get_type(): Returns the type of a given value object.
 */
 static inline

-bool bt_value_is_integer(const struct bt_value *object)
+bt_bool bt_value_is_integer(const struct bt_value *object)

 {
        return bt_value_get_type(object) == BT_VALUE_TYPE_INTEGER;
 }
 {
        return bt_value_get_type(object) == BT_VALUE_TYPE_INTEGER;
 }


@@ -338,7 +343,7 @@ bool bt_value_is_integer(const struct bt_value *object)
        point number value object.
 
 @param[in] object      Value object to check.
        point number value object.
 
 @param[in] object      Value object to check.

-@returns               \c true if \p object is a floating point
+@returns               #BT_TRUE if \p object is a floating point

                        number value object.
 
 @prenotnull{object}
                        number value object.
 
 @prenotnull{object}


@@ -347,7 +352,7 @@ bool bt_value_is_integer(const struct bt_value *object)
 @sa bt_value_get_type(): Returns the type of a given value object.
 */
 static inline
 @sa bt_value_get_type(): Returns the type of a given value object.
 */
 static inline

-bool bt_value_is_float(const struct bt_value *object)
+bt_bool bt_value_is_float(const struct bt_value *object)

 {
        return bt_value_get_type(object) == BT_VALUE_TYPE_FLOAT;
 }
 {
        return bt_value_get_type(object) == BT_VALUE_TYPE_FLOAT;
 }


@@ -357,7 +362,7 @@ bool bt_value_is_float(const struct bt_value *object)
        value object.
 
 @param[in] object      Value object to check.
        value object.
 
 @param[in] object      Value object to check.

-@returns               \c true if \p object is a string value object.
+@returns               #BT_TRUE if \p object is a string value object.

 
 @prenotnull{object}
 @postrefcountsame{object}
 
 @prenotnull{object}
 @postrefcountsame{object}


@@ -365,7 +370,7 @@ bool bt_value_is_float(const struct bt_value *object)
 @sa bt_value_get_type(): Returns the type of a given value object.
 */
 static inline
 @sa bt_value_get_type(): Returns the type of a given value object.
 */
 static inline

-bool bt_value_is_string(const struct bt_value *object)
+bt_bool bt_value_is_string(const struct bt_value *object)

 {
        return bt_value_get_type(object) == BT_VALUE_TYPE_STRING;
 }
 {
        return bt_value_get_type(object) == BT_VALUE_TYPE_STRING;
 }


@@ -375,7 +380,7 @@ bool bt_value_is_string(const struct bt_value *object)
        value object.
 
 @param[in] object      Value object to check.
        value object.
 
 @param[in] object      Value object to check.

-@returns               \c true if \p object is an array value object.
+@returns               #BT_TRUE if \p object is an array value object.

 
 @prenotnull{object}
 @postrefcountsame{object}
 
 @prenotnull{object}
 @postrefcountsame{object}


@@ -383,7 +388,7 @@ bool bt_value_is_string(const struct bt_value *object)
 @sa bt_value_get_type(): Returns the type of a given value object.
 */
 static inline
 @sa bt_value_get_type(): Returns the type of a given value object.
 */
 static inline

-bool bt_value_is_array(const struct bt_value *object)
+bt_bool bt_value_is_array(const struct bt_value *object)

 {
        return bt_value_get_type(object) == BT_VALUE_TYPE_ARRAY;
 }
 {
        return bt_value_get_type(object) == BT_VALUE_TYPE_ARRAY;
 }


@@ -393,7 +398,7 @@ bool bt_value_is_array(const struct bt_value *object)
        object.
 
 @param[in] object      Value object to check.
        object.
 
 @param[in] object      Value object to check.

-@returns               \c true if \p object is a map value object.
+@returns               #BT_TRUE if \p object is a map value object.

 
 @prenotnull{object}
 @postrefcountsame{object}
 
 @prenotnull{object}
 @postrefcountsame{object}


@@ -401,7 +406,7 @@ bool bt_value_is_array(const struct bt_value *object)
 @sa bt_value_get_type(): Returns the type of a given value object.
 */
 static inline
 @sa bt_value_get_type(): Returns the type of a given value object.
 */
 static inline

-bool bt_value_is_map(const struct bt_value *object)
+bt_bool bt_value_is_map(const struct bt_value *object)

 {
        return bt_value_get_type(object) == BT_VALUE_TYPE_MAP;
 }
 {
        return bt_value_get_type(object) == BT_VALUE_TYPE_MAP;
 }


@@ -427,7 +432,7 @@ Freezing a value object is typically used to make it immutable after
 it's built by its initial owner.
 
 @param[in] object      Value object to freeze.
 it's built by its initial owner.
 
 @param[in] object      Value object to freeze.

-@returns               One of #bt_value_status values. If \p object
+@returns               Status code. If \p object

                        is already frozen, however, #BT_VALUE_STATUS_OK
                        is returned anyway (that is, this function never
                        returns #BT_VALUE_STATUS_FROZEN).
                        is already frozen, however, #BT_VALUE_STATUS_OK
                        is returned anyway (that is, this function never
                        returns #BT_VALUE_STATUS_FROZEN).


@@ -446,12 +451,12 @@ extern enum bt_value_status bt_value_freeze(struct bt_value *object);
 @brief Returns whether or not the value object \p object is frozen.
 
 @param[in] object      Value object to check.
 @brief Returns whether or not the value object \p object is frozen.
 
 @param[in] object      Value object to check.

-@returns               \c true if \p object is frozen.
+@returns               #BT_TRUE if \p object is frozen.

 
 @prenotnull{object}
 @postrefcountsame{object}
 */
 
 @prenotnull{object}
 @postrefcountsame{object}
 */

-extern bool bt_value_is_frozen(const struct bt_value *object);
+extern bt_bool bt_value_is_frozen(const struct bt_value *object);

 
 /**
 @brief Creates a \em deep copy of the value object \p object.
 
 /**
 @brief Creates a \em deep copy of the value object \p object.


@@ -466,26 +471,25 @@ You can copy a frozen value object: the resulting copy is
 @prenotnull{object}
 @post <strong>On success, if the returned value object is not
        \ref bt_value_null</strong>, its reference count is 1.
 @prenotnull{object}
 @post <strong>On success, if the returned value object is not
        \ref bt_value_null</strong>, its reference count is 1.

-

 @postrefcountsame{object}
 */
 extern struct bt_value *bt_value_copy(const struct bt_value *object);
 
 /**
 @brief Recursively compares the value objects \p object_a and
 @postrefcountsame{object}
 */
 extern struct bt_value *bt_value_copy(const struct bt_value *object);
 
 /**
 @brief Recursively compares the value objects \p object_a and

-       \p object_b and returns \c true if they have the same
+       \p object_b and returns #BT_TRUE if they have the same

        \em content (raw values).
 
 @param[in] object_a    Value object A to compare to \p object_b.
 @param[in] object_b    Value object B to compare to \p object_a.
        \em content (raw values).
 
 @param[in] object_a    Value object A to compare to \p object_b.
 @param[in] object_b    Value object B to compare to \p object_a.

-@returns               \c true if \p object_a and \p object_b have the
-                       same \em content, or \c false if they differ
+@returns               #BT_TRUE if \p object_a and \p object_b have the
+                       same \em content, or #BT_FALSE if they differ

                        or on error.
 
 @postrefcountsame{object_a}
 @postrefcountsame{object_b}
 */
                        or on error.
 
 @postrefcountsame{object_a}
 @postrefcountsame{object_b}
 */

-extern bool bt_value_compare(const struct bt_value *object_a,
+extern bt_bool bt_value_compare(const struct bt_value *object_a,

                const struct bt_value *object_b);
 
 /** @} */
                const struct bt_value *object_b);
 
 /** @} */


@@ -498,7 +502,7 @@ extern bool bt_value_compare(const struct bt_value *object_a,
 /**
 @brief Creates a default boolean value object.
 
 /**
 @brief Creates a default boolean value object.
 

-The created boolean value object's initial raw value is \c false.
+The created boolean value object's initial raw value is #BT_FALSE.

 
 @returns       Created boolean value object on success, or \c NULL
                on error.
 
 @returns       Created boolean value object on success, or \c NULL
                on error.


@@ -522,7 +526,7 @@ extern struct bt_value *bt_value_bool_create(void);
 
 @sa bt_value_bool_create(): Creates a default boolean value object.
 */
 
 @sa bt_value_bool_create(): Creates a default boolean value object.
 */

-extern struct bt_value *bt_value_bool_create_init(bool val);
+extern struct bt_value *bt_value_bool_create_init(bt_bool val);

 
 /**
 @brief Returns the boolean raw value of the boolean value object
 
 /**
 @brief Returns the boolean raw value of the boolean value object


@@ -531,7 +535,7 @@ extern struct bt_value *bt_value_bool_create_init(bool val);
 @param[in] bool_obj    Boolean value object of which to get the
                        raw value.
 @param[out] val                Returned boolean raw value.
 @param[in] bool_obj    Boolean value object of which to get the
                        raw value.
 @param[out] val                Returned boolean raw value.

-@returns               One of #bt_value_status values.
+@returns               Status code.

 
 @prenotnull{bool_obj}
 @prenotnull{val}
 
 @prenotnull{bool_obj}
 @prenotnull{val}


@@ -541,7 +545,7 @@ extern struct bt_value *bt_value_bool_create_init(bool val);
 @sa bt_value_bool_set(): Sets the raw value of a boolean value object.
 */
 extern enum bt_value_status bt_value_bool_get(
 @sa bt_value_bool_set(): Sets the raw value of a boolean value object.
 */
 extern enum bt_value_status bt_value_bool_get(

-               const struct bt_value *bool_obj, bool *val);
+               const struct bt_value *bool_obj, bt_bool *val);

 
 /**
 @brief Sets the boolean raw value of the boolean value object
 
 /**
 @brief Sets the boolean raw value of the boolean value object


@@ -550,7 +554,7 @@ extern enum bt_value_status bt_value_bool_get(
 @param[in] bool_obj    Boolean value object of which to set
                        the raw value.
 @param[in] val         New boolean raw value.
 @param[in] bool_obj    Boolean value object of which to set
                        the raw value.
 @param[in] val         New boolean raw value.

-@returns               One of #bt_value_status values.
+@returns               Status code.

 
 @prenotnull{bool_obj}
 @pre \p bool_obj is a boolean value object.
 
 @prenotnull{bool_obj}
 @pre \p bool_obj is a boolean value object.


@@ -561,7 +565,7 @@ extern enum bt_value_status bt_value_bool_get(
        value object.
 */
 extern enum bt_value_status bt_value_bool_set(struct bt_value *bool_obj,
        value object.
 */
 extern enum bt_value_status bt_value_bool_set(struct bt_value *bool_obj,

-               bool val);
+               bt_bool val);

 
 /** @} */
 
 
 /** @} */
 


@@ -607,7 +611,7 @@ extern struct bt_value *bt_value_integer_create_init(int64_t val);
 @param[in] integer_obj Integer value object of which to get the
                        raw value.
 @param[out] val                Returned integer raw value.
 @param[in] integer_obj Integer value object of which to get the
                        raw value.
 @param[out] val                Returned integer raw value.

-@returns               One of #bt_value_status values.
+@returns               Status code.

 
 @prenotnull{integer_obj}
 @prenotnull{val}
 
 @prenotnull{integer_obj}
 @prenotnull{val}


@@ -627,7 +631,7 @@ extern enum bt_value_status bt_value_integer_get(
 @param[in] integer_obj Integer value object of which to set
                        the raw value.
 @param[in] val         New integer raw value.
 @param[in] integer_obj Integer value object of which to set
                        the raw value.
 @param[in] val         New integer raw value.

-@returns               One of #bt_value_status values.
+@returns               Status code.

 
 @prenotnull{integer_obj}
 @pre \p integer_obj is an integer value object.
 
 @prenotnull{integer_obj}
 @pre \p integer_obj is an integer value object.


@@ -684,7 +688,7 @@ extern struct bt_value *bt_value_float_create_init(double val);
 @param[in] float_obj   Floating point number value object of which to
                        get the raw value.
 @param[out] val                Returned floating point number raw value
 @param[in] float_obj   Floating point number value object of which to
                        get the raw value.
 @param[out] val                Returned floating point number raw value

-@returns               One of #bt_value_status values.
+@returns               Status code.

 
 @prenotnull{float_obj}
 @prenotnull{val}
 
 @prenotnull{float_obj}
 @prenotnull{val}


@@ -704,7 +708,7 @@ extern enum bt_value_status bt_value_float_get(
 @param[in] float_obj   Floating point number value object of which to set
                        the raw value.
 @param[in] val         New floating point number raw value.
 @param[in] float_obj   Floating point number value object of which to set
                        the raw value.
 @param[in] val         New floating point number raw value.

-@returns               One of #bt_value_status values.
+@returns               Status code.

 
 @prenotnull{float_obj}
 @pre \p float_obj is a floating point number value object.
 
 @prenotnull{float_obj}
 @pre \p float_obj is a floating point number value object.


@@ -767,7 +771,7 @@ returned string is \em not transferred to the caller.
 @param[in] string_obj  String value object of which to get the
                        raw value.
 @param[out] val                Returned string raw value.
 @param[in] string_obj  String value object of which to get the
                        raw value.
 @param[out] val                Returned string raw value.

-@returns               One of #bt_value_status values.
+@returns               Status code.

 
 @prenotnull{string_obj}
 @prenotnull{val}
 
 @prenotnull{string_obj}
 @prenotnull{val}


@@ -789,7 +793,7 @@ On success, \p val is copied.
 @param[in] string_obj  String value object of which to set
                        the raw value.
 @param[in] val         New string raw value (copied on success).
 @param[in] string_obj  String value object of which to set
                        the raw value.
 @param[in] val         New string raw value (copied on success).

-@returns               One of #bt_value_status values.
+@returns               Status code.

 
 @prenotnull{string_obj}
 @prenotnull{val}
 
 @prenotnull{string_obj}
 @prenotnull{val}


@@ -839,14 +843,14 @@ extern struct bt_value *bt_value_array_create(void);
 @sa bt_value_array_is_empty(): Checks whether or not a given array
        value object is empty.
 */
 @sa bt_value_array_is_empty(): Checks whether or not a given array
        value object is empty.
 */

-extern int bt_value_array_size(const struct bt_value *array_obj);
+extern int64_t bt_value_array_size(const struct bt_value *array_obj);

 
 /**
 @brief Checks whether or not the array value object \p array_obj
        is empty.
 
 @param[in] array_obj   Array value object to check.
 
 /**
 @brief Checks whether or not the array value object \p array_obj
        is empty.
 
 @param[in] array_obj   Array value object to check.

-@returns               \c true if \p array_obj is empty.
+@returns               #BT_TRUE if \p array_obj is empty.

 
 @prenotnull{array_obj}
 @pre \p array_obj is an array value object.
 
 @prenotnull{array_obj}
 @pre \p array_obj is an array value object.


@@ -855,7 +859,7 @@ extern int bt_value_array_size(const struct bt_value *array_obj);
 @sa bt_value_array_size(): Returns the size of a given array value
        object.
 */
 @sa bt_value_array_size(): Returns the size of a given array value
        object.
 */

-extern bool bt_value_array_is_empty(const struct bt_value *array_obj);
+extern bt_bool bt_value_array_is_empty(const struct bt_value *array_obj);

 
 /**
 @brief Returns the value object contained in the array value object
 
 /**
 @brief Returns the value object contained in the array value object


@@ -868,13 +872,14 @@ extern bool bt_value_array_is_empty(const struct bt_value *array_obj);
 
 @prenotnull{array_obj}
 @pre \p array_obj is an array value object.
 
 @prenotnull{array_obj}
 @pre \p array_obj is an array value object.

-@pre \p index is lesser than the size of \p array_obj.
+@pre \p index is lesser than the size of \p array_obj (see
+       bt_value_array_size()).

 @post <strong>On success, if the returned value object is not
        \ref bt_value_null</strong>, its reference count is incremented.
 @postrefcountsame{array_obj}
 */
 extern struct bt_value *bt_value_array_get(const struct bt_value *array_obj,
 @post <strong>On success, if the returned value object is not
        \ref bt_value_null</strong>, its reference count is incremented.
 @postrefcountsame{array_obj}
 */
 extern struct bt_value *bt_value_array_get(const struct bt_value *array_obj,

-               size_t index);
+               uint64_t index);

 
 /**
 @brief Appends the value object \p element_obj to the array value
 
 /**
 @brief Appends the value object \p element_obj to the array value


@@ -883,7 +888,7 @@ extern struct bt_value *bt_value_array_get(const struct bt_value *array_obj,
 @param[in] array_obj   Array value object in which to append
                        \p element_obj.
 @param[in] element_obj Value object to append.
 @param[in] array_obj   Array value object in which to append
                        \p element_obj.
 @param[in] element_obj Value object to append.

-@returns               One of #bt_value_status values.
+@returns               Status code.

 
 @prenotnull{array_obj}
 @prenotnull{element_obj}
 
 @prenotnull{array_obj}
 @prenotnull{element_obj}


@@ -918,7 +923,7 @@ value object before appending it.
 
 @param[in] array_obj   Array value object in which to append \p val.
 @param[in] val         Boolean raw value to append to \p array_obj.
 
 @param[in] array_obj   Array value object in which to append \p val.
 @param[in] val         Boolean raw value to append to \p array_obj.

-@returns               One of #bt_value_status values.
+@returns               Status code.

 
 @prenotnull{array_obj}
 @pre \p array_obj is an array value object.
 
 @prenotnull{array_obj}
 @pre \p array_obj is an array value object.


@@ -929,7 +934,7 @@ value object before appending it.
        array value object.
 */
 extern enum bt_value_status bt_value_array_append_bool(
        array value object.
 */
 extern enum bt_value_status bt_value_array_append_bool(

-               struct bt_value *array_obj, bool val);
+               struct bt_value *array_obj, bt_bool val);

 
 /**
 @brief Appends the integer raw value \p val to the array value object
 
 /**
 @brief Appends the integer raw value \p val to the array value object


@@ -940,7 +945,7 @@ value object before appending it.
 
 @param[in] array_obj   Array value object in which to append \p val.
 @param[in] val         Integer raw value to append to \p array_obj.
 
 @param[in] array_obj   Array value object in which to append \p val.
 @param[in] val         Integer raw value to append to \p array_obj.

-@returns               One of #bt_value_status values.
+@returns               Status code.

 
 @prenotnull{array_obj}
 @pre \p array_obj is an array value object.
 
 @prenotnull{array_obj}
 @pre \p array_obj is an array value object.


@@ -963,7 +968,7 @@ point number value object before appending it.
 @param[in] array_obj   Array value object in which to append \p val.
 @param[in] val         Floating point number raw value to append
                        to \p array_obj.
 @param[in] array_obj   Array value object in which to append \p val.
 @param[in] val         Floating point number raw value to append
                        to \p array_obj.

-@returns               One of #bt_value_status values.
+@returns               Status code.

 
 @prenotnull{array_obj}
 @pre \p array_obj is an array value object.
 
 @prenotnull{array_obj}
 @pre \p array_obj is an array value object.


@@ -988,7 +993,7 @@ On success, \p val is copied.
 @param[in] array_obj   Array value object in which to append \p val.
 @param[in] val         String raw value to append to \p array_obj
                        (copied on success).
 @param[in] array_obj   Array value object in which to append \p val.
 @param[in] val         String raw value to append to \p array_obj
                        (copied on success).

-@returns               One of #bt_value_status values.
+@returns               Status code.

 
 @prenotnull{array_obj}
 @pre \p array_obj is an array value object.
 
 @prenotnull{array_obj}
 @pre \p array_obj is an array value object.


@@ -1011,7 +1016,7 @@ object before appending it.
 
 @param[in] array_obj   Array value object in which to append an
                        empty array value object
 
 @param[in] array_obj   Array value object in which to append an
                        empty array value object

-@returns               One of #bt_value_status values.
+@returns               Status code.

 
 @prenotnull{array_obj}
 @pre \p array_obj is an array value object.
 
 @prenotnull{array_obj}
 @pre \p array_obj is an array value object.


@@ -1033,7 +1038,7 @@ object before appending it.
 
 @param[in] array_obj   Array value object in which to append an empty
                        map value object.
 
 @param[in] array_obj   Array value object in which to append an empty
                        map value object.

-@returns               One of #bt_value_status values.
+@returns               Status code.

 
 @prenotnull{array_obj}
 @pre \p array_obj is an array value object.
 
 @prenotnull{array_obj}
 @pre \p array_obj is an array value object.


@@ -1056,12 +1061,13 @@ extern enum bt_value_status bt_value_array_append_empty_map(
                                \p array_obj.
 @param[in] element_obj         New value object at position \p index of
                                \p array_obj.
                                \p array_obj.
 @param[in] element_obj         New value object at position \p index of
                                \p array_obj.

-@returns                       One of #bt_value_status values.
+@returns                       Status code.

 
 @prenotnull{array_obj}
 @prenotnull{element_obj}
 @pre \p array_obj is an array value object.
 
 @prenotnull{array_obj}
 @prenotnull{element_obj}
 @pre \p array_obj is an array value object.

-@pre \p index is lesser than the size of \p array_obj.
+@pre \p index is lesser than the size of \p array_obj (see
+       bt_value_array_size()).

 @prehot{array_obj}
 @post <strong>On success, if the replaced value object is not
        \ref bt_value_null</strong>, its reference count is decremented.
 @prehot{array_obj}
 @post <strong>On success, if the replaced value object is not
        \ref bt_value_null</strong>, its reference count is decremented.


@@ -1070,7 +1076,7 @@ extern enum bt_value_status bt_value_array_append_empty_map(
 @postrefcountsame{array_obj}
 */
 extern enum bt_value_status bt_value_array_set(struct bt_value *array_obj,
 @postrefcountsame{array_obj}
 */
 extern enum bt_value_status bt_value_array_set(struct bt_value *array_obj,

-               size_t index, struct bt_value *element_obj);
+               uint64_t index, struct bt_value *element_obj);

 
 /** @} */
 
 
 /** @} */
 


@@ -1105,13 +1111,13 @@ extern struct bt_value *bt_value_map_create(void);
 @sa bt_value_map_is_empty(): Checks whether or not a given map value
        object is empty.
 */
 @sa bt_value_map_is_empty(): Checks whether or not a given map value
        object is empty.
 */

-extern int bt_value_map_size(const struct bt_value *map_obj);
+extern int64_t bt_value_map_size(const struct bt_value *map_obj);

 
 /**
 @brief Checks whether or not the map value object \p map_obj is empty.
 
 @param[in] map_obj     Map value object to check.
 
 /**
 @brief Checks whether or not the map value object \p map_obj is empty.
 
 @param[in] map_obj     Map value object to check.

-@returns               \c true if \p map_obj is empty.
+@returns               #BT_TRUE if \p map_obj is empty.

 
 @prenotnull{map_obj}
 @pre \p map_obj is a map value object.
 
 @prenotnull{map_obj}
 @pre \p map_obj is a map value object.


@@ -1119,7 +1125,7 @@ extern int bt_value_map_size(const struct bt_value *map_obj);
 
 @sa bt_value_map_size(): Returns the size of a given map value object.
 */
 
 @sa bt_value_map_size(): Returns the size of a given map value object.
 */

-extern bool bt_value_map_is_empty(const struct bt_value *map_obj);
+extern bt_bool bt_value_map_is_empty(const struct bt_value *map_obj);

 
 /**
 @brief Returns the value object associated with the key \p key within
 
 /**
 @brief Returns the value object associated with the key \p key within


@@ -1134,7 +1140,6 @@ extern bool bt_value_map_is_empty(const struct bt_value *map_obj);
 @prenotnull{key}
 @pre \p map_obj is a map value object.
 @postrefcountsame{map_obj}
 @prenotnull{key}
 @pre \p map_obj is a map value object.
 @postrefcountsame{map_obj}

-

 @post <strong>On success, if the returned value object is not
        \ref bt_value_null</strong>, its reference count is incremented.
 */
 @post <strong>On success, if the returned value object is not
        \ref bt_value_null</strong>, its reference count is incremented.
 */


@@ -1145,22 +1150,22 @@ extern struct bt_value *bt_value_map_get(const struct bt_value *map_obj,
 @brief User function type to use with bt_value_map_foreach().
 
 \p object is a <em>weak reference</em>: you \em must pass it to bt_get()
 @brief User function type to use with bt_value_map_foreach().
 
 \p object is a <em>weak reference</em>: you \em must pass it to bt_get()

-if you need your own reference.
+if you need to keep a reference after this function returns.

 
 

-This function \em must return \c true to continue the map value object
-traversal, or \c false to break it.
+This function \em must return #BT_TRUE to continue the map value object
+traversal, or #BT_FALSE to break it.

 
 @param[in] key         Key of map entry.
 @param[in] object      Value object of map entry (weak reference).
 @param[in] data                User data.
 
 @param[in] key         Key of map entry.
 @param[in] object      Value object of map entry (weak reference).
 @param[in] data                User data.

-@returns               \c true to continue the loop, or \c false to break it.
+@returns               #BT_TRUE to continue the loop, or #BT_FALSE to break it.

 
 @prenotnull{key}
 @prenotnull{object}
 @post The reference count of \p object is not lesser than what it is
        when the function is called.
 */
 
 @prenotnull{key}
 @prenotnull{object}
 @post The reference count of \p object is not lesser than what it is
        when the function is called.
 */

-typedef bool (* bt_value_map_foreach_cb)(const char *key,
+typedef bt_bool (* bt_value_map_foreach_cb)(const char *key,

        struct bt_value *object, void *data);
 
 /**
        struct bt_value *object, void *data);
 
 /**


@@ -1168,18 +1173,19 @@ typedef bool (* bt_value_map_foreach_cb)(const char *key,
        map value object \p map_obj.
 
 The value object passed to the user function is a <b>weak reference</b>:
        map value object \p map_obj.
 
 The value object passed to the user function is a <b>weak reference</b>:

-you \em must pass it to bt_get() if you need your own reference.
+you \em must pass it to bt_get() if you need to keep a persistent
+reference after the user function returns.

 
 The key passed to the user function is only valid in the scope of
 this user function call.
 
 
 The key passed to the user function is only valid in the scope of
 this user function call.
 

-The user function \em must return \c true to continue the traversal of
-\p map_obj, or \c false to break it.
+The user function \em must return #BT_TRUE to continue the traversal of
+\p map_obj, or #BT_FALSE to break it.

 
 @param[in] map_obj     Map value object on which to iterate.
 @param[in] cb          User function to call back.
 @param[in] data                User data passed to the user function.
 
 @param[in] map_obj     Map value object on which to iterate.
 @param[in] cb          User function to call back.
 @param[in] data                User data passed to the user function.

-@returns               One of #bt_value_status values. More
+@returns               Status code. More

                        specifically, #BT_VALUE_STATUS_CANCELLED is
                        returned if the loop was cancelled by the user
                        function.
                        specifically, #BT_VALUE_STATUS_CANCELLED is
                        returned if the loop was cancelled by the user
                        function.


@@ -1199,8 +1205,8 @@ extern enum bt_value_status bt_value_map_foreach(
 
 @param[in] map_obj     Map value object to check.
 @param[in] key         Key to check.
 
 @param[in] map_obj     Map value object to check.
 @param[in] key         Key to check.

-@returns               \c true if \p map_obj has an entry mapped to the
-                       key \p key, or \c false if it does not or
+@returns               #BT_TRUE if \p map_obj has an entry mapped to the
+                       key \p key, or #BT_FALSE if it does not or

                        on error.
 
 @prenotnull{map_obj}
                        on error.
 
 @prenotnull{map_obj}


@@ -1208,7 +1214,7 @@ extern enum bt_value_status bt_value_map_foreach(
 @pre \p map_obj is a map value object.
 @postrefcountsame{map_obj}
 */
 @pre \p map_obj is a map value object.
 @postrefcountsame{map_obj}
 */

-extern bool bt_value_map_has_key(const struct bt_value *map_obj,
+extern bt_bool bt_value_map_has_key(const struct bt_value *map_obj,

                const char *key);
 
 /**
                const char *key);
 
 /**


@@ -1227,7 +1233,7 @@ On success, \p key is copied.
                        value object to insert is mapped.
 @param[in] element_obj Value object to insert, mapped to the
                        key \p key.
                        value object to insert is mapped.
 @param[in] element_obj Value object to insert, mapped to the
                        key \p key.

-@returns               One of #bt_value_status values.
+@returns               Status code.

 
 @prenotnull{map_obj}
 @prenotnull{key}
 
 @prenotnull{map_obj}
 @prenotnull{key}


@@ -1269,7 +1275,7 @@ On success, \p key is copied.
                        value object to insert is mapped.
 @param[in] val         Boolean raw value to insert, mapped to
                        the key \p key.
                        value object to insert is mapped.
 @param[in] val         Boolean raw value to insert, mapped to
                        the key \p key.

-@returns               One of #bt_value_status values.
+@returns               Status code.

 
 @prenotnull{map_obj}
 @prenotnull{key}
 
 @prenotnull{map_obj}
 @prenotnull{key}


@@ -1281,7 +1287,7 @@ On success, \p key is copied.
        value object.
 */
 extern enum bt_value_status bt_value_map_insert_bool(
        value object.
 */
 extern enum bt_value_status bt_value_map_insert_bool(

-               struct bt_value *map_obj, const char *key, bool val);
+               struct bt_value *map_obj, const char *key, bt_bool val);

 
 /**
 @brief Inserts the integer raw value \p val mapped to the key \p key
 
 /**
 @brief Inserts the integer raw value \p val mapped to the key \p key


@@ -1297,7 +1303,7 @@ On success, \p key is copied.
                        value object to insert is mapped.
 @param[in] val         Integer raw value to insert, mapped to
                        the key \p key.
                        value object to insert is mapped.
 @param[in] val         Integer raw value to insert, mapped to
                        the key \p key.

-@returns               One of #bt_value_status values.
+@returns               Status code.

 
 @prenotnull{map_obj}
 @prenotnull{key}
 
 @prenotnull{map_obj}
 @prenotnull{key}


@@ -1325,7 +1331,7 @@ On success, \p key is copied.
                        point number value object to insert is mapped.
 @param[in] val         Floating point number raw value to insert,
                        mapped to the key \p key.
                        point number value object to insert is mapped.
 @param[in] val         Floating point number raw value to insert,
                        mapped to the key \p key.

-@returns               One of #bt_value_status values.
+@returns               Status code.

 
 @prenotnull{map_obj}
 @prenotnull{key}
 
 @prenotnull{map_obj}
 @prenotnull{key}


@@ -1353,7 +1359,7 @@ On success, \p val and \p key are copied.
                        value object to insert is mapped.
 @param[in] val         String raw value to insert (copied on success),
                        mapped to the key \p key.
                        value object to insert is mapped.
 @param[in] val         String raw value to insert (copied on success),
                        mapped to the key \p key.

-@returns               One of #bt_value_status values.
+@returns               Status code.

 
 @prenotnull{map_obj}
 @prenotnull{key}
 
 @prenotnull{map_obj}
 @prenotnull{key}


@@ -1381,7 +1387,7 @@ On success, \p key is copied.
                        array value object.
 @param[in] key         Key (copied on success) to which the empty array
                        value object to insert is mapped.
                        array value object.
 @param[in] key         Key (copied on success) to which the empty array
                        value object to insert is mapped.

-@returns               One of #bt_value_status values.
+@returns               Status code.

 
 @prenotnull{map_obj}
 @prenotnull{key}
 
 @prenotnull{map_obj}
 @prenotnull{key}


@@ -1408,7 +1414,7 @@ On success, \p key is copied.
                        map object.
 @param[in] key         Key (copied on success) to which the empty map
                        value object to insert is mapped.
                        map object.
 @param[in] key         Key (copied on success) to which the empty map
                        value object to insert is mapped.

-@returns               One of #bt_value_status values.
+@returns               Status code.

 
 @prenotnull{map_obj}
 @prenotnull{key}
 
 @prenotnull{map_obj}
 @prenotnull{key}


@@ -1435,28 +1441,28 @@ value objects.
 
 For example, consider the following \p base_map_obj (JSON representation):
 
 
 For example, consider the following \p base_map_obj (JSON representation):
 

-@code{.unparsed}
+@verbatim

 {
   "hello": 23,
   "code": -17,
   "em": false,
   "return": [5, 6, null]
 }
 {
   "hello": 23,
   "code": -17,
   "em": false,
   "return": [5, 6, null]
 }

-@endcode
+@endverbatim

 
 and the following \p extension_map_obj (JSON representation):
 
 
 and the following \p extension_map_obj (JSON representation):
 

-@code{.unparsed}
+@verbatim

 {
   "comma": ",",
   "code": 22,
   "return": 17.88
 }
 {
   "comma": ",",
   "code": 22,
   "return": 17.88
 }

-@endcode
+@endverbatim

 
 The extended object is (JSON representation):
 
 
 The extended object is (JSON representation):
 

-@code{.unparsed}
+@verbatim

 {
   "hello": 23,
   "code": 22,
 {
   "hello": 23,
   "code": 22,


@@ -1464,7 +1470,7 @@ The extended object is (JSON representation):
   "return": 17.88,
   "comma": ","
 }
   "return": 17.88,
   "comma": ","
 }

-@endcode
+@endverbatim

 
 @param[in] base_map_obj                Base map value object with initial
                                entries.
 
 @param[in] base_map_obj                Base map value object with initial
                                entries.


@@ -1493,4 +1499,4 @@ extern struct bt_value *bt_value_map_extend(struct bt_value *base_map_obj,
 }
 #endif
 
 }
 #endif
 

-#endif /* _BABELTRACE_VALUES_H */
+#endif /* BABELTRACE_VALUES_H */