1 #ifndef BABELTRACE_VALUES_H
2 #define BABELTRACE_VALUES_H
5 * Babeltrace - Value objects
7 * Copyright (c) 2015-2016 EfficiOS Inc. and Linux Foundation
8 * Copyright (c) 2015-2016 Philippe Proulx <pproulx@efficios.com>
10 * Permission is hereby granted, free of charge, to any person obtaining a copy
11 * of this software and associated documentation files (the "Software"), to deal
12 * in the Software without restriction, including without limitation the rights
13 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14 * copies of the Software, and to permit persons to whom the Software is
15 * furnished to do so, subject to the following conditions:
17 * The above copyright notice and this permission notice shall be included in
18 * all copies or substantial portions of the Software.
20 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
33 #include <babeltrace/types.h>
36 #include <babeltrace/ref.h>
43 @defgroup values Value objects
48 #include <babeltrace/values.h>
51 This is a set of <strong><em>value objects</em></strong>. With the
52 functions documented here, you can create and modify:
54 - \link bt_value_bool_create() Boolean value objects\endlink.
55 - \link bt_value_integer_create() Integer value objects\endlink.
56 - \link bt_value_float_create() Floating point number
57 value objects\endlink.
58 - \link bt_value_string_create() String value objects\endlink.
59 - \link bt_value_array_create() Array value objects\endlink,
60 containing zero or more value objects.
61 - \link bt_value_map_create() Map value objects\endlink, mapping
62 string keys to value objects.
64 As with any Babeltrace object, value objects have
65 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
66 counts</a>. When you \link bt_value_array_append() append a value object
67 to an array value object\endlink, or when you \link bt_value_map_insert()
68 insert a value object into a map value object\endlink, its reference
69 count is incremented, as well as when you get a value object back from
70 those objects. See \ref refs to learn more about the reference counting
71 management of Babeltrace objects.
73 Most functions of this API return a <em>status code</em>, one of the
74 values of #bt_value_status.
76 You can create a deep copy of any value object with bt_value_copy(). You
77 can compare two value objects with bt_value_compare().
79 The following matrix shows some categorized value object functions
80 to use for each value object type:
84 <th>Function role →<br>
85 Value object type ↓
93 <td>Use the \ref bt_value_null variable
94 <td>bt_value_is_null()
100 <td>bt_value_bool_create()<br>
101 bt_value_bool_create_init()
102 <td>bt_value_is_bool()
103 <td>bt_value_bool_get()
104 <td>bt_value_bool_set()
108 <td>bt_value_integer_create()<br>
109 bt_value_integer_create_init()
110 <td>bt_value_is_integer()
111 <td>bt_value_integer_get()
112 <td>bt_value_integer_set()
115 <th>Floating point<br>number
116 <td>bt_value_float_create()<br>
117 bt_value_float_create_init()
118 <td>bt_value_is_float()
119 <td>bt_value_float_get()
120 <td>bt_value_float_set()
124 <td>bt_value_string_create()<br>
125 bt_value_string_create_init()
126 <td>bt_value_is_string()
127 <td>bt_value_string_get()
128 <td>bt_value_string_set()
132 <td>bt_value_array_create()
133 <td>bt_value_is_array()
134 <td>bt_value_array_get()
135 <td>bt_value_array_append()<br>
136 bt_value_array_append_bool()<br>
137 bt_value_array_append_integer()<br>
138 bt_value_array_append_float()<br>
139 bt_value_array_append_string()<br>
140 bt_value_array_append_empty_array()<br>
141 bt_value_array_append_empty_map()<br>
146 <td>bt_value_map_create()<br>
147 bt_value_map_extend()
148 <td>bt_value_is_map()
149 <td>bt_value_map_get()<br>
150 bt_value_map_foreach()
151 <td>bt_value_map_insert()<br>
152 bt_value_map_insert_bool()<br>
153 bt_value_map_insert_integer()<br>
154 bt_value_map_insert_float()<br>
155 bt_value_map_insert_string()<br>
156 bt_value_map_insert_empty_array()<br>
157 bt_value_map_insert_empty_map()
162 @brief Value object types and functions.
172 enum bt_value_status
{
173 /// Operation canceled.
174 BT_VALUE_STATUS_CANCELED
= -3,
176 /* -22 for compatibility with -EINVAL */
177 /// Invalid argument.
178 BT_VALUE_STATUS_INVAL
= -22,
181 BT_VALUE_STATUS_ERROR
= -1,
184 BT_VALUE_STATUS_OK
= 0,
189 @brief A value object.
195 @brief The null value object singleton.
197 You \em must use this variable when you need the null value object.
199 The null value object singleton has no reference count: there is only
200 one. You can compare any value object address to the null value object
201 singleton to check if it's the null value object, or otherwise with
204 You can pass \ref bt_value_null to bt_get() or bt_put(): it has
207 The null value object singleton is <em>always frozen</em> (see
208 bt_value_is_frozen()).
210 The functions of this API return this variable when the value object
211 is actually the null value object (of type #BT_VALUE_TYPE_NULL),
212 whereas \c NULL means an error of some sort.
214 extern struct bt_value
*bt_value_null
;
217 @name Type information
222 @brief Value object type.
225 /// Null value object.
226 BT_VALUE_TYPE_NULL
= 0,
228 /// Boolean value object (holds #BT_TRUE or #BT_FALSE).
229 BT_VALUE_TYPE_BOOL
= 1,
231 /// Integer value object (holds a signed 64-bit integer raw value).
232 BT_VALUE_TYPE_INTEGER
= 2,
234 /// Floating point number value object (holds a \c double raw value).
235 BT_VALUE_TYPE_REAL
= 3,
237 /// String value object.
238 BT_VALUE_TYPE_STRING
= 4,
240 /// Array value object.
241 BT_VALUE_TYPE_ARRAY
= 5,
243 /// Map value object.
244 BT_VALUE_TYPE_MAP
= 6,
248 @brief Returns the type of the value object \p object.
250 @param[in] object Value object of which to get the type.
251 @returns Type of value object \p object,
252 or #BT_VALUE_TYPE_UNKNOWN on error.
255 @postrefcountsame{object}
257 @sa #bt_value_type: Value object types.
258 @sa bt_value_is_null(): Returns whether or not a given value object
259 is the null value object.
260 @sa bt_value_is_bool(): Returns whether or not a given value object
261 is a boolean value object.
262 @sa bt_value_is_integer(): Returns whether or not a given value
263 object is an integer value object.
264 @sa bt_value_is_float(): Returns whether or not a given value object
265 is a floating point number value object.
266 @sa bt_value_is_string(): Returns whether or not a given value object
267 is a string value object.
268 @sa bt_value_is_array(): Returns whether or not a given value object
269 is an array value object.
270 @sa bt_value_is_map(): Returns whether or not a given value object
271 is a map value object.
273 extern enum bt_value_type
bt_value_get_type(const struct bt_value
*object
);
276 @brief Returns whether or not the value object \p object is the null
279 The only valid null value object is \ref bt_value_null.
281 An alternative to calling this function is to directly compare the value
282 object pointer to the \ref bt_value_null variable.
284 @param[in] object Value object to check.
285 @returns #BT_TRUE if \p object is the null value object.
288 @postrefcountsame{object}
290 @sa bt_value_get_type(): Returns the type of a given value object.
293 bt_bool
bt_value_is_null(const struct bt_value
*object
)
295 return bt_value_get_type(object
) == BT_VALUE_TYPE_NULL
;
299 @brief Returns whether or not the value object \p object is a boolean
302 @param[in] object Value object to check.
303 @returns #BT_TRUE if \p object is a boolean value object.
306 @postrefcountsame{object}
308 @sa bt_value_get_type(): Returns the type of a given value object.
311 bt_bool
bt_value_is_bool(const struct bt_value
*object
)
313 return bt_value_get_type(object
) == BT_VALUE_TYPE_BOOL
;
317 @brief Returns whether or not the value object \p object is an integer
320 @param[in] object Value object to check.
321 @returns #BT_TRUE if \p object is an integer value object.
323 @sa bt_value_get_type(): Returns the type of a given value object.
326 bt_bool
bt_value_is_integer(const struct bt_value
*object
)
328 return bt_value_get_type(object
) == BT_VALUE_TYPE_INTEGER
;
332 @brief Returns whether or not the value object \p object is a floating
333 point number value object.
335 @param[in] object Value object to check.
336 @returns #BT_TRUE if \p object is a floating point
340 @postrefcountsame{object}
342 @sa bt_value_get_type(): Returns the type of a given value object.
345 bt_bool
bt_value_is_real(const struct bt_value
*object
)
347 return bt_value_get_type(object
) == BT_VALUE_TYPE_REAL
;
351 @brief Returns whether or not the value object \p object is a string
354 @param[in] object Value object to check.
355 @returns #BT_TRUE if \p object is a string value object.
358 @postrefcountsame{object}
360 @sa bt_value_get_type(): Returns the type of a given value object.
363 bt_bool
bt_value_is_string(const struct bt_value
*object
)
365 return bt_value_get_type(object
) == BT_VALUE_TYPE_STRING
;
369 @brief Returns whether or not the value object \p object is an array
372 @param[in] object Value object to check.
373 @returns #BT_TRUE if \p object is an array value object.
376 @postrefcountsame{object}
378 @sa bt_value_get_type(): Returns the type of a given value object.
381 bt_bool
bt_value_is_array(const struct bt_value
*object
)
383 return bt_value_get_type(object
) == BT_VALUE_TYPE_ARRAY
;
387 @brief Returns whether or not the value object \p object is a map value
390 @param[in] object Value object to check.
391 @returns #BT_TRUE if \p object is a map value object.
394 @postrefcountsame{object}
396 @sa bt_value_get_type(): Returns the type of a given value object.
399 bt_bool
bt_value_is_map(const struct bt_value
*object
)
401 return bt_value_get_type(object
) == BT_VALUE_TYPE_MAP
;
407 @name Common value object functions
412 @brief Creates a \em deep copy of the value object \p object.
414 You can copy a frozen value object: the resulting copy is
417 @param[in] object Value object to copy.
418 @returns Deep copy of \p object on success, or \c NULL
422 @post <strong>On success, if the returned value object is not
423 \ref bt_value_null</strong>, its reference count is 1.
424 @postrefcountsame{object}
426 extern struct bt_value
*bt_value_copy(const struct bt_value
*object
);
429 @brief Recursively compares the value objects \p object_a and
430 \p object_b and returns #BT_TRUE if they have the same
431 \em content (raw values).
433 @param[in] object_a Value object A to compare to \p object_b.
434 @param[in] object_b Value object B to compare to \p object_a.
435 @returns #BT_TRUE if \p object_a and \p object_b have the
436 same \em content, or #BT_FALSE if they differ
439 @postrefcountsame{object_a}
440 @postrefcountsame{object_b}
442 extern bt_bool
bt_value_compare(const struct bt_value
*object_a
,
443 const struct bt_value
*object_b
);
448 @name Boolean value object functions
453 @brief Creates a default boolean value object.
455 The created boolean value object's initial raw value is #BT_FALSE.
457 @returns Created boolean value object on success, or \c NULL
460 @postsuccessrefcountret1
462 @sa bt_value_bool_create_init(): Creates an initialized boolean
465 extern struct bt_value
*bt_value_bool_create(void);
468 @brief Creates a boolean value object with its initial raw value set to
471 @param[in] val Initial raw value.
472 @returns Created boolean value object on success, or
475 @postsuccessrefcountret1
477 @sa bt_value_bool_create(): Creates a default boolean value object.
479 extern struct bt_value
*bt_value_bool_create_init(bt_bool val
);
482 @brief Returns the boolean raw value of the boolean value object
485 @param[in] bool_obj Boolean value object of which to get the
487 @param[out] val Returned boolean raw value.
488 @returns Status code.
490 @prenotnull{bool_obj}
492 @pre \p bool_obj is a boolean value object.
493 @postrefcountsame{bool_obj}
495 @sa bt_value_bool_set(): Sets the raw value of a boolean value object.
497 extern enum bt_value_status
bt_value_bool_get(
498 const struct bt_value
*bool_obj
, bt_bool
*val
);
501 @brief Sets the boolean raw value of the boolean value object
502 \p bool_obj to \p val.
504 @param[in] bool_obj Boolean value object of which to set
506 @param[in] val New boolean raw value.
507 @returns Status code.
509 @prenotnull{bool_obj}
510 @pre \p bool_obj is a boolean value object.
512 @postrefcountsame{bool_obj}
514 @sa bt_value_bool_get(): Returns the raw value of a given boolean
517 extern enum bt_value_status
bt_value_bool_set(struct bt_value
*bool_obj
,
523 @name Integer value object functions
528 @brief Creates a default integer value object.
530 The created integer value object's initial raw value is 0.
532 @returns Created integer value object on success, or \c NULL
535 @postsuccessrefcountret1
537 @sa bt_value_integer_create_init(): Creates an initialized integer
540 extern struct bt_value
*bt_value_integer_create(void);
543 @brief Creates an integer value object with its initial raw value set to
546 @param[in] val Initial raw value.
547 @returns Created integer value object on success, or
550 @postsuccessrefcountret1
552 @sa bt_value_integer_create(): Creates a default integer
555 extern struct bt_value
*bt_value_integer_create_init(int64_t val
);
558 @brief Returns the integer raw value of the integer value object
561 @param[in] integer_obj Integer value object of which to get the
563 @param[out] val Returned integer raw value.
564 @returns Status code.
566 @prenotnull{integer_obj}
568 @pre \p integer_obj is an integer value object.
569 @postrefcountsame{integer_obj}
571 @sa bt_value_integer_set(): Sets the raw value of an integer value
574 extern enum bt_value_status
bt_value_integer_get(
575 const struct bt_value
*integer_obj
, int64_t *val
);
578 @brief Sets the integer raw value of the integer value object
579 \p integer_obj to \p val.
581 @param[in] integer_obj Integer value object of which to set
583 @param[in] val New integer raw value.
584 @returns Status code.
586 @prenotnull{integer_obj}
587 @pre \p integer_obj is an integer value object.
589 @postrefcountsame{integer_obj}
591 @sa bt_value_integer_get(): Returns the raw value of a given integer
594 extern enum bt_value_status
bt_value_integer_set(
595 struct bt_value
*integer_obj
, int64_t val
);
600 @name Floating point number value object functions
605 @brief Creates a default floating point number value object.
607 The created floating point number value object's initial raw value is 0.
609 @returns Created floating point number value object on success,
612 @postsuccessrefcountret1
614 @sa bt_value_float_create_init(): Creates an initialized floating
615 point number value object.
617 extern struct bt_value
*bt_value_real_create(void);
620 @brief Creates a floating point number value object with its initial raw
623 @param[in] val Initial raw value.
624 @returns Created floating point number value object on
625 success, or \c NULL on error.
627 @postsuccessrefcountret1
629 @sa bt_value_float_create(): Creates a default floating point number
632 extern struct bt_value
*bt_value_real_create_init(double val
);
635 @brief Returns the floating point number raw value of the floating point
636 number value object \p float_obj.
638 @param[in] float_obj Floating point number value object of which to
640 @param[out] val Returned floating point number raw value
641 @returns Status code.
643 @prenotnull{float_obj}
645 @pre \p float_obj is a floating point number value object.
646 @postrefcountsame{float_obj}
648 @sa bt_value_float_set(): Sets the raw value of a given floating
649 point number value object.
651 extern enum bt_value_status
bt_value_real_get(
652 const struct bt_value
*real_obj
, double *val
);
655 @brief Sets the floating point number raw value of the floating point
656 number value object \p float_obj to \p val.
658 @param[in] float_obj Floating point number value object of which to set
660 @param[in] val New floating point number raw value.
661 @returns Status code.
663 @prenotnull{float_obj}
664 @pre \p float_obj is a floating point number value object.
666 @postrefcountsame{float_obj}
668 @sa bt_value_float_get(): Returns the raw value of a floating point
671 extern enum bt_value_status
bt_value_real_set(
672 struct bt_value
*real_obj
, double val
);
677 @name String value object functions
682 @brief Creates a default string value object.
684 The string value object is initially empty.
686 @returns Created string value object on success, or \c NULL
689 @postsuccessrefcountret1
691 @sa bt_value_string_create_init(): Creates an initialized string
694 extern struct bt_value
*bt_value_string_create(void);
697 @brief Creates a string value object with its initial raw value set to
700 On success, \p val is copied.
702 @param[in] val Initial raw value (copied on success).
703 @returns Created string value object on success, or
707 @postsuccessrefcountret1
709 @sa bt_value_float_create(): Creates a default string value object.
711 extern struct bt_value
*bt_value_string_create_init(const char *val
);
714 @brief Returns the string raw value of the string value object
717 The returned string is placed in \p *val. It is valid as long as this
718 value object exists and is \em not modified. The ownership of the
719 returned string is \em not transferred to the caller.
721 @param[in] string_obj String value object of which to get the
723 @param[out] val Returned string raw value.
724 @returns Status code.
726 @prenotnull{string_obj}
728 @pre \p string_obj is a string value object.
729 @postrefcountsame{string_obj}
731 @sa bt_value_string_set(): Sets the raw value of a string
734 extern enum bt_value_status
bt_value_string_get(
735 const struct bt_value
*string_obj
, const char **val
);
738 @brief Sets the string raw value of the string value object
739 \p string_obj to \p val.
741 On success, \p val is copied.
743 @param[in] string_obj String value object of which to set
745 @param[in] val New string raw value (copied on success).
746 @returns Status code.
748 @prenotnull{string_obj}
750 @pre \p string_obj is a string value object.
752 @postrefcountsame{string_obj}
754 @sa bt_value_string_get(): Returns the raw value of a given string
757 extern enum bt_value_status
bt_value_string_set(struct bt_value
*string_obj
,
765 * @name Array value object functions
770 @brief Creates an empty array value object.
772 @returns Created array value object on success, or \c NULL
775 @postsuccessrefcountret1
777 extern struct bt_value
*bt_value_array_create(void);
780 @brief Returns the size of the array value object \p array_obj, that is,
781 the number of value objects contained in \p array_obj.
783 @param[in] array_obj Array value object of which to get the size.
784 @returns Number of value objects contained in
785 \p array_obj if the return value is 0 (empty)
786 or a positive value, or one of
787 #bt_value_status negative values otherwise.
789 @prenotnull{array_obj}
790 @pre \p array_obj is an array value object.
791 @postrefcountsame{array_obj}
793 @sa bt_value_array_is_empty(): Checks whether or not a given array
794 value object is empty.
796 extern int64_t bt_value_array_size(const struct bt_value
*array_obj
);
799 @brief Checks whether or not the array value object \p array_obj
802 @param[in] array_obj Array value object to check.
803 @returns #BT_TRUE if \p array_obj is empty.
805 @prenotnull{array_obj}
806 @pre \p array_obj is an array value object.
807 @postrefcountsame{array_obj}
809 @sa bt_value_array_size(): Returns the size of a given array value
812 extern bt_bool
bt_value_array_is_empty(const struct bt_value
*array_obj
);
814 extern struct bt_value
*bt_value_array_borrow(const struct bt_value
*array_obj
,
818 @brief Returns the value object contained in the array value object
819 \p array_obj at the index \p index.
821 @param[in] array_obj Array value object of which to get an element.
822 @param[in] index Index of value object to get.
823 @returns Value object at index \p index on
824 success, or \c NULL on error.
826 @prenotnull{array_obj}
827 @pre \p array_obj is an array value object.
828 @pre \p index is lesser than the size of \p array_obj (see
829 bt_value_array_size()).
830 @post <strong>On success, if the returned value object is not
831 \ref bt_value_null</strong>, its reference count is incremented.
832 @postrefcountsame{array_obj}
835 struct bt_value
*bt_value_array_get(const struct bt_value
*array_obj
,
838 return bt_get(bt_value_array_borrow(array_obj
, index
));
842 @brief Appends the value object \p element_obj to the array value
845 @param[in] array_obj Array value object in which to append
847 @param[in] element_obj Value object to append.
848 @returns Status code.
850 @prenotnull{array_obj}
851 @prenotnull{element_obj}
852 @pre \p array_obj is an array value object.
854 @post <strong>On success, if \p element_obj is not
855 \ref bt_value_null</strong>, its reference count is incremented.
856 @postrefcountsame{array_obj}
858 @sa bt_value_array_append_bool(): Appends a boolean raw value to a
859 given array value object.
860 @sa bt_value_array_append_integer(): Appends an integer raw value
861 to a given array value object.
862 @sa bt_value_array_append_float(): Appends a floating point number
863 raw value to a given array value object.
864 @sa bt_value_array_append_string(): Appends a string raw value to a
865 given array value object.
866 @sa bt_value_array_append_empty_array(): Appends an empty array value
867 object to a given array value object.
868 @sa bt_value_array_append_empty_map(): Appends an empty map value
869 object to a given array value object.
871 extern enum bt_value_status
bt_value_array_append(struct bt_value
*array_obj
,
872 struct bt_value
*element_obj
);
875 @brief Appends the boolean raw value \p val to the array value object
878 This is a convenience function which creates the underlying boolean
879 value object before appending it.
881 @param[in] array_obj Array value object in which to append \p val.
882 @param[in] val Boolean raw value to append to \p array_obj.
883 @returns Status code.
885 @prenotnull{array_obj}
886 @pre \p array_obj is an array value object.
888 @postrefcountsame{array_obj}
890 @sa bt_value_array_append(): Appends a value object to a given
893 extern enum bt_value_status
bt_value_array_append_bool(
894 struct bt_value
*array_obj
, bt_bool val
);
897 @brief Appends the integer raw value \p val to the array value object
900 This is a convenience function which creates the underlying integer
901 value object before appending it.
903 @param[in] array_obj Array value object in which to append \p val.
904 @param[in] val Integer raw value to append to \p array_obj.
905 @returns Status code.
907 @prenotnull{array_obj}
908 @pre \p array_obj is an array value object.
910 @postrefcountsame{array_obj}
912 @sa bt_value_array_append(): Appends a value object to a given
915 extern enum bt_value_status
bt_value_array_append_integer(
916 struct bt_value
*array_obj
, int64_t val
);
919 @brief Appends the floating point number raw value \p val to the array
920 value object \p array_obj.
922 This is a convenience function which creates the underlying floating
923 point number value object before appending it.
925 @param[in] array_obj Array value object in which to append \p val.
926 @param[in] val Floating point number raw value to append
928 @returns Status code.
930 @prenotnull{array_obj}
931 @pre \p array_obj is an array value object.
933 @postrefcountsame{array_obj}
935 @sa bt_value_array_append(): Appends a value object to a given
938 extern enum bt_value_status
bt_value_array_append_real(
939 struct bt_value
*array_obj
, double val
);
942 @brief Appends the string raw value \p val to the array value object
945 This is a convenience function which creates the underlying string value
946 object before appending it.
948 On success, \p val is copied.
950 @param[in] array_obj Array value object in which to append \p val.
951 @param[in] val String raw value to append to \p array_obj
953 @returns Status code.
955 @prenotnull{array_obj}
956 @pre \p array_obj is an array value object.
959 @postrefcountsame{array_obj}
961 @sa bt_value_array_append(): Appends a value object to a given
964 extern enum bt_value_status
bt_value_array_append_string(
965 struct bt_value
*array_obj
, const char *val
);
968 @brief Appends an empty array value object to the array value object
971 This is a convenience function which creates the underlying array value
972 object before appending it.
974 @param[in] array_obj Array value object in which to append an
975 empty array value object
976 @returns Status code.
978 @prenotnull{array_obj}
979 @pre \p array_obj is an array value object.
981 @postrefcountsame{array_obj}
983 @sa bt_value_array_append(): Appends a value object to a given
986 extern enum bt_value_status
bt_value_array_append_empty_array(
987 struct bt_value
*array_obj
);
990 @brief Appends an empty map value object to the array value object
993 This is a convenience function which creates the underlying map value
994 object before appending it.
996 @param[in] array_obj Array value object in which to append an empty
998 @returns Status code.
1000 @prenotnull{array_obj}
1001 @pre \p array_obj is an array value object.
1003 @postrefcountsame{array_obj}
1005 @sa bt_value_array_append(): Appends a value object to a given
1008 extern enum bt_value_status
bt_value_array_append_empty_map(
1009 struct bt_value
*array_obj
);
1012 @brief Replaces the value object contained in the array value object
1013 \p array_obj at the index \p index by \p element_obj.
1015 @param[in] array_obj Array value object in which to replace
1017 @param[in] index Index of value object to replace in
1019 @param[in] element_obj New value object at position \p index of
1021 @returns Status code.
1023 @prenotnull{array_obj}
1024 @prenotnull{element_obj}
1025 @pre \p array_obj is an array value object.
1026 @pre \p index is lesser than the size of \p array_obj (see
1027 bt_value_array_size()).
1029 @post <strong>On success, if the replaced value object is not
1030 \ref bt_value_null</strong>, its reference count is decremented.
1031 @post <strong>On success, if \p element_obj is not
1032 \ref bt_value_null</strong>, its reference count is incremented.
1033 @postrefcountsame{array_obj}
1035 extern enum bt_value_status
bt_value_array_set(struct bt_value
*array_obj
,
1036 uint64_t index
, struct bt_value
*element_obj
);
1041 @name Map value object functions
1046 @brief Creates an empty map value object.
1048 @returns Created map value object on success, or \c NULL on error.
1050 @postsuccessrefcountret1
1052 extern struct bt_value
*bt_value_map_create(void);
1055 @brief Returns the size of the map value object \p map_obj, that is, the
1056 number of entries contained in \p map_obj.
1058 @param[in] map_obj Map value object of which to get the size.
1059 @returns Number of entries contained in \p map_obj if the
1060 return value is 0 (empty) or a positive value,
1061 or one of #bt_value_status negative values
1064 @prenotnull{map_obj}
1065 @pre \p map_obj is a map value object.
1066 @postrefcountsame{map_obj}
1068 @sa bt_value_map_is_empty(): Checks whether or not a given map value
1071 extern int64_t bt_value_map_size(const struct bt_value
*map_obj
);
1074 @brief Checks whether or not the map value object \p map_obj is empty.
1076 @param[in] map_obj Map value object to check.
1077 @returns #BT_TRUE if \p map_obj is empty.
1079 @prenotnull{map_obj}
1080 @pre \p map_obj is a map value object.
1081 @postrefcountsame{map_obj}
1083 @sa bt_value_map_size(): Returns the size of a given map value object.
1085 extern bt_bool
bt_value_map_is_empty(const struct bt_value
*map_obj
);
1087 extern struct bt_value
*bt_value_map_borrow(const struct bt_value
*map_obj
,
1091 @brief Returns the value object associated with the key \p key within
1092 the map value object \p map_obj.
1094 @param[in] map_obj Map value object of which to get an entry.
1095 @param[in] key Key of the value object to get.
1096 @returns Value object associated with the key \p key
1097 on success, or \c NULL on error.
1099 @prenotnull{map_obj}
1101 @pre \p map_obj is a map value object.
1102 @postrefcountsame{map_obj}
1103 @post <strong>On success, if the returned value object is not
1104 \ref bt_value_null</strong>, its reference count is incremented.
1107 struct bt_value
*bt_value_map_get(const struct bt_value
*map_obj
,
1110 return bt_get(bt_value_map_borrow(map_obj
, key
));
1114 @brief User function type to use with bt_value_map_foreach().
1116 \p object is a <em>weak reference</em>: you \em must pass it to bt_get()
1117 if you need to keep a reference after this function returns.
1119 This function \em must return #BT_TRUE to continue the map value object
1120 traversal, or #BT_FALSE to break it.
1122 @param[in] key Key of map entry.
1123 @param[in] object Value object of map entry (weak reference).
1124 @param[in] data User data.
1125 @returns #BT_TRUE to continue the loop, or #BT_FALSE to break it.
1129 @post The reference count of \p object is not lesser than what it is
1130 when the function is called.
1132 typedef bt_bool (* bt_value_map_foreach_cb
)(const char *key
,
1133 struct bt_value
*object
, void *data
);
1136 @brief Calls a provided user function \p cb for each value object of the
1137 map value object \p map_obj.
1139 The value object passed to the user function is a <b>weak reference</b>:
1140 you \em must pass it to bt_get() if you need to keep a persistent
1141 reference after the user function returns.
1143 The key passed to the user function is only valid in the scope of
1144 this user function call.
1146 The user function \em must return #BT_TRUE to continue the traversal of
1147 \p map_obj, or #BT_FALSE to break it.
1149 @param[in] map_obj Map value object on which to iterate.
1150 @param[in] cb User function to call back.
1151 @param[in] data User data passed to the user function.
1152 @returns Status code. More
1153 specifically, #BT_VALUE_STATUS_CANCELED is
1154 returned if the loop was canceled by the user
1157 @prenotnull{map_obj}
1159 @pre \p map_obj is a map value object.
1160 @postrefcountsame{map_obj}
1162 extern enum bt_value_status
bt_value_map_foreach(
1163 const struct bt_value
*map_obj
, bt_value_map_foreach_cb cb
,
1167 @brief Returns whether or not the map value object \p map_obj contains
1168 an entry mapped to the key \p key.
1170 @param[in] map_obj Map value object to check.
1171 @param[in] key Key to check.
1172 @returns #BT_TRUE if \p map_obj has an entry mapped to the
1173 key \p key, or #BT_FALSE if it does not or
1176 @prenotnull{map_obj}
1178 @pre \p map_obj is a map value object.
1179 @postrefcountsame{map_obj}
1181 extern bt_bool
bt_value_map_has_key(const struct bt_value
*map_obj
,
1185 @brief Inserts the value object \p element_obj mapped to the key
1186 \p key into the map value object \p map_obj.
1188 If a value object is already mapped to \p key in \p map_obj, the
1189 associated value object is first put, and then replaced by
1192 On success, \p key is copied.
1194 @param[in] map_obj Map value object in which to insert
1196 @param[in] key Key (copied on success) to which the
1197 value object to insert is mapped.
1198 @param[in] element_obj Value object to insert, mapped to the
1200 @returns Status code.
1202 @prenotnull{map_obj}
1204 @prenotnull{element_obj}
1205 @pre \p map_obj is a map value object.
1207 @post <strong>On success, if \p element_obj is not
1208 \ref bt_value_null</strong>, its reference count is incremented.
1209 @postrefcountsame{map_obj}
1211 @sa bt_value_map_insert_bool(): Inserts a boolean raw value into a
1212 given map value object.
1213 @sa bt_value_map_insert_integer(): Inserts an integer raw value into
1214 a given map value object.
1215 @sa bt_value_map_insert_float(): Inserts a floating point number raw
1216 value into a given map value object.
1217 @sa bt_value_map_insert_string(): Inserts a string raw value into a
1218 given map value object.
1219 @sa bt_value_map_insert_empty_array(): Inserts an empty array value
1220 object into a given map value object.
1221 @sa bt_value_map_insert_empty_map(): Inserts an empty map value
1222 object into a given map value object.
1224 extern enum bt_value_status
bt_value_map_insert(
1225 struct bt_value
*map_obj
, const char *key
,
1226 struct bt_value
*element_obj
);
1229 @brief Inserts the boolean raw value \p val mapped to the key \p key
1230 into the map value object \p map_obj.
1232 This is a convenience function which creates the underlying boolean
1233 value object before inserting it.
1235 On success, \p key is copied.
1237 @param[in] map_obj Map value object in which to insert \p val.
1238 @param[in] key Key (copied on success) to which the boolean
1239 value object to insert is mapped.
1240 @param[in] val Boolean raw value to insert, mapped to
1242 @returns Status code.
1244 @prenotnull{map_obj}
1246 @pre \p map_obj is a map value object.
1248 @postrefcountsame{map_obj}
1250 @sa bt_value_map_insert(): Inserts a value object into a given map
1253 extern enum bt_value_status
bt_value_map_insert_bool(
1254 struct bt_value
*map_obj
, const char *key
, bt_bool val
);
1257 @brief Inserts the integer raw value \p val mapped to the key \p key
1258 into the map value object \p map_obj.
1260 This is a convenience function which creates the underlying integer
1261 value object before inserting it.
1263 On success, \p key is copied.
1265 @param[in] map_obj Map value object in which to insert \p val.
1266 @param[in] key Key (copied on success) to which the integer
1267 value object to insert is mapped.
1268 @param[in] val Integer raw value to insert, mapped to
1270 @returns Status code.
1272 @prenotnull{map_obj}
1274 @pre \p map_obj is a map value object.
1276 @postrefcountsame{map_obj}
1278 @sa bt_value_map_insert(): Inserts a value object into a given map
1281 extern enum bt_value_status
bt_value_map_insert_integer(
1282 struct bt_value
*map_obj
, const char *key
, int64_t val
);
1285 @brief Inserts the floating point number raw value \p val mapped to
1286 the key \p key into the map value object \p map_obj.
1288 This is a convenience function which creates the underlying floating
1289 point number value object before inserting it.
1291 On success, \p key is copied.
1293 @param[in] map_obj Map value object in which to insert \p val.
1294 @param[in] key Key (copied on success) to which the floating
1295 point number value object to insert is mapped.
1296 @param[in] val Floating point number raw value to insert,
1297 mapped to the key \p key.
1298 @returns Status code.
1300 @prenotnull{map_obj}
1302 @pre \p map_obj is a map value object.
1304 @postrefcountsame{map_obj}
1306 @sa bt_value_map_insert(): Inserts a value object into a given map
1309 extern enum bt_value_status
bt_value_map_insert_real(
1310 struct bt_value
*map_obj
, const char *key
, double val
);
1313 @brief Inserts the string raw value \p val mapped to the key \p key
1314 into the map value object \p map_obj.
1316 This is a convenience function which creates the underlying string value
1317 object before inserting it.
1319 On success, \p val and \p key are copied.
1321 @param[in] map_obj Map value object in which to insert \p val.
1322 @param[in] key Key (copied on success) to which the string
1323 value object to insert is mapped.
1324 @param[in] val String raw value to insert (copied on success),
1325 mapped to the key \p key.
1326 @returns Status code.
1328 @prenotnull{map_obj}
1331 @pre \p map_obj is a map value object.
1333 @postrefcountsame{map_obj}
1335 @sa bt_value_map_insert(): Inserts a value object into a given map
1338 extern enum bt_value_status
bt_value_map_insert_string(
1339 struct bt_value
*map_obj
, const char *key
, const char *val
);
1342 @brief Inserts an empty array value object mapped to the key \p key
1343 into the map value object \p map_obj.
1345 This is a convenience function which creates the underlying array value
1346 object before inserting it.
1348 On success, \p key is copied.
1350 @param[in] map_obj Map value object in which to insert an empty
1352 @param[in] key Key (copied on success) to which the empty array
1353 value object to insert is mapped.
1354 @returns Status code.
1356 @prenotnull{map_obj}
1358 @pre \p map_obj is a map value object.
1360 @postrefcountsame{map_obj}
1362 @sa bt_value_map_insert(): Inserts a value object into a given map
1365 extern enum bt_value_status
bt_value_map_insert_empty_array(
1366 struct bt_value
*map_obj
, const char *key
);
1369 @brief Inserts an empty map value object mapped to the key \p key into
1370 the map value object \p map_obj.
1372 This is a convenience function which creates the underlying map value
1373 object before inserting it.
1375 On success, \p key is copied.
1377 @param[in] map_obj Map value object in which to insert an empty
1379 @param[in] key Key (copied on success) to which the empty map
1380 value object to insert is mapped.
1381 @returns Status code.
1383 @prenotnull{map_obj}
1385 @pre \p map_obj is a map value object.
1387 @postrefcountsame{map_obj}
1389 @sa bt_value_map_insert(): Inserts a value object into a given map
1392 extern enum bt_value_status
bt_value_map_insert_empty_map(
1393 struct bt_value
*map_obj
, const char *key
);
1396 @brief Creates a copy of the base map value object \p base_map_obj
1397 superficially extended with the entries of the extension map
1398 value object \p extension_map_obj.
1400 This function creates a superficial extension of \p base_map_obj with
1401 \p extension_map_obj by adding new entries to it and replacing the
1402 ones that share the keys in the extension object. The extension is
1403 \em superficial because it does not merge internal array and map
1406 For example, consider the following \p base_map_obj (JSON representation):
1413 "return": [5, 6, null]
1417 and the following \p extension_map_obj (JSON representation):
1427 The extended object is (JSON representation):
1439 @param[in] base_map_obj Base map value object with initial
1441 @param[in] extension_map_obj Extension map value object containing
1442 the entries to add to or replace in
1444 @returns Created extended map value object, or
1447 @prenotnull{base_map_obj}
1448 @prenotnull{extension_map_obj}
1449 @pre \p base_map_obj is a map value object.
1450 @pre \p extension_map_obj is a map value object.
1451 @postrefcountsame{base_map_obj}
1452 @postrefcountsame{extension_map_obj}
1453 @postsuccessrefcountret1
1455 extern struct bt_value
*bt_value_map_extend(struct bt_value
*base_map_obj
,
1456 struct bt_value
*extension_map_obj
);
1466 #endif /* BABELTRACE_VALUES_H */