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>
40 @defgroup values Value objects
45 #include <babeltrace/values.h>
48 This is a set of <strong><em>value objects</em></strong>. With the
49 functions documented here, you can create and modify:
51 - \link bt_value_bool_create() Boolean value objects\endlink.
52 - \link bt_value_integer_create() Integer value objects\endlink.
53 - \link bt_value_float_create() Floating point number
54 value objects\endlink.
55 - \link bt_value_string_create() String value objects\endlink.
56 - \link bt_value_array_create() Array value objects\endlink,
57 containing zero or more value objects.
58 - \link bt_value_map_create() Map value objects\endlink, mapping
59 string keys to value objects.
61 As with any Babeltrace object, value objects have
62 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
63 counts</a>. When you \link bt_value_array_append() append a value object
64 to an array value object\endlink, or when you \link bt_value_map_insert()
65 insert a value object into a map value object\endlink, its reference
66 count is incremented, as well as when you get a value object back from
67 those objects. See \ref refs to learn more about the reference counting
68 management of Babeltrace objects.
70 Most functions of this API return a <em>status code</em>, one of the
71 values of #bt_value_status.
73 You can create a deep copy of any value object with bt_value_copy(). You
74 can compare two value objects with bt_value_compare().
76 You can \em freeze a value object with bt_value_freeze(). You can get
77 the raw value of a frozen value object, but you cannot modify it.
78 Reference counting still works on frozen value objects. You can copy
79 a frozen value object: the returned copy is not frozen. You can also
80 compare a frozen value object to another value object (frozen or not).
81 Freezing a value object is typically used to make it immutable after
82 it's built by its initial owner.
84 The following matrix shows some categorized value object functions
85 to use for each value object type:
89 <th>Function role →<br>
90 Value object type ↓
98 <td>Use the \ref bt_value_null variable
99 <td>bt_value_is_null()
105 <td>bt_value_bool_create()<br>
106 bt_value_bool_create_init()
107 <td>bt_value_is_bool()
108 <td>bt_value_bool_get()
109 <td>bt_value_bool_set()
113 <td>bt_value_integer_create()<br>
114 bt_value_integer_create_init()
115 <td>bt_value_is_integer()
116 <td>bt_value_integer_get()
117 <td>bt_value_integer_set()
120 <th>Floating point<br>number
121 <td>bt_value_float_create()<br>
122 bt_value_float_create_init()
123 <td>bt_value_is_float()
124 <td>bt_value_float_get()
125 <td>bt_value_float_set()
129 <td>bt_value_string_create()<br>
130 bt_value_string_create_init()
131 <td>bt_value_is_string()
132 <td>bt_value_string_get()
133 <td>bt_value_string_set()
137 <td>bt_value_array_create()
138 <td>bt_value_is_array()
139 <td>bt_value_array_get()
140 <td>bt_value_array_append()<br>
141 bt_value_array_append_bool()<br>
142 bt_value_array_append_integer()<br>
143 bt_value_array_append_float()<br>
144 bt_value_array_append_string()<br>
145 bt_value_array_append_empty_array()<br>
146 bt_value_array_append_empty_map()<br>
151 <td>bt_value_map_create()<br>
152 bt_value_map_extend()
153 <td>bt_value_is_map()
154 <td>bt_value_map_get()<br>
155 bt_value_map_foreach()
156 <td>bt_value_map_insert()<br>
157 bt_value_map_insert_bool()<br>
158 bt_value_map_insert_integer()<br>
159 bt_value_map_insert_float()<br>
160 bt_value_map_insert_string()<br>
161 bt_value_map_insert_empty_array()<br>
162 bt_value_map_insert_empty_map()
167 @brief Value object types and functions.
177 enum bt_value_status
{
178 /// Value object cannot be altered because it's frozen.
179 BT_VALUE_STATUS_FROZEN
= -4,
181 /// Operation cancelled.
182 BT_VALUE_STATUS_CANCELLED
= -3,
184 /* -22 for compatibility with -EINVAL */
185 /// Invalid argument.
186 BT_VALUE_STATUS_INVAL
= -22,
189 BT_VALUE_STATUS_ERROR
= -1,
192 BT_VALUE_STATUS_OK
= 0,
197 @brief A value object.
203 @brief The null value object singleton.
205 You \em must use this variable when you need the null value object.
207 The null value object singleton has no reference count: there is only
208 one. You can compare any value object address to the null value object
209 singleton to check if it's the null value object, or otherwise with
212 You can pass \ref bt_value_null to bt_get() or bt_put(): it has
215 The null value object singleton is <em>always frozen</em> (see
216 bt_value_is_frozen()).
218 The functions of this API return this variable when the value object
219 is actually the null value object (of type #BT_VALUE_TYPE_NULL),
220 whereas \c NULL means an error of some sort.
222 extern struct bt_value
*bt_value_null
;
225 @name Type information
230 @brief Value object type.
233 /// Unknown value object, used as an error code.
234 BT_VALUE_TYPE_UNKNOWN
= -1,
236 /// Null value object.
237 BT_VALUE_TYPE_NULL
= 0,
239 /// Boolean value object (holds #BT_TRUE or #BT_FALSE).
240 BT_VALUE_TYPE_BOOL
= 1,
242 /// Integer value object (holds a signed 64-bit integer raw value).
243 BT_VALUE_TYPE_INTEGER
= 2,
245 /// Floating point number value object (holds a \c double raw value).
246 BT_VALUE_TYPE_FLOAT
= 3,
248 /// String value object.
249 BT_VALUE_TYPE_STRING
= 4,
251 /// Array value object.
252 BT_VALUE_TYPE_ARRAY
= 5,
254 /// Map value object.
255 BT_VALUE_TYPE_MAP
= 6,
259 @brief Returns the type of the value object \p object.
261 @param[in] object Value object of which to get the type.
262 @returns Type of value object \p object,
263 or #BT_VALUE_TYPE_UNKNOWN on error.
266 @postrefcountsame{object}
268 @sa #bt_value_type: Value object types.
269 @sa bt_value_is_null(): Returns whether or not a given value object
270 is the null value object.
271 @sa bt_value_is_bool(): Returns whether or not a given value object
272 is a boolean value object.
273 @sa bt_value_is_integer(): Returns whether or not a given value
274 object is an integer value object.
275 @sa bt_value_is_float(): Returns whether or not a given value object
276 is a floating point number value object.
277 @sa bt_value_is_string(): Returns whether or not a given value object
278 is a string value object.
279 @sa bt_value_is_array(): Returns whether or not a given value object
280 is an array value object.
281 @sa bt_value_is_map(): Returns whether or not a given value object
282 is a map value object.
284 extern enum bt_value_type
bt_value_get_type(const struct bt_value
*object
);
287 @brief Returns whether or not the value object \p object is the null
290 The only valid null value object is \ref bt_value_null.
292 An alternative to calling this function is to directly compare the value
293 object pointer to the \ref bt_value_null variable.
295 @param[in] object Value object to check.
296 @returns #BT_TRUE if \p object is the null value object.
299 @postrefcountsame{object}
301 @sa bt_value_get_type(): Returns the type of a given value object.
304 bt_bool
bt_value_is_null(const struct bt_value
*object
)
306 return bt_value_get_type(object
) == BT_VALUE_TYPE_NULL
;
310 @brief Returns whether or not the value object \p object is a boolean
313 @param[in] object Value object to check.
314 @returns #BT_TRUE if \p object is a boolean value object.
317 @postrefcountsame{object}
319 @sa bt_value_get_type(): Returns the type of a given value object.
322 bt_bool
bt_value_is_bool(const struct bt_value
*object
)
324 return bt_value_get_type(object
) == BT_VALUE_TYPE_BOOL
;
328 @brief Returns whether or not the value object \p object is an integer
331 @param[in] object Value object to check.
332 @returns #BT_TRUE if \p object is an integer value object.
334 @sa bt_value_get_type(): Returns the type of a given value object.
337 bt_bool
bt_value_is_integer(const struct bt_value
*object
)
339 return bt_value_get_type(object
) == BT_VALUE_TYPE_INTEGER
;
343 @brief Returns whether or not the value object \p object is a floating
344 point number value object.
346 @param[in] object Value object to check.
347 @returns #BT_TRUE if \p object is a floating point
351 @postrefcountsame{object}
353 @sa bt_value_get_type(): Returns the type of a given value object.
356 bt_bool
bt_value_is_float(const struct bt_value
*object
)
358 return bt_value_get_type(object
) == BT_VALUE_TYPE_FLOAT
;
362 @brief Returns whether or not the value object \p object is a string
365 @param[in] object Value object to check.
366 @returns #BT_TRUE if \p object is a string value object.
369 @postrefcountsame{object}
371 @sa bt_value_get_type(): Returns the type of a given value object.
374 bt_bool
bt_value_is_string(const struct bt_value
*object
)
376 return bt_value_get_type(object
) == BT_VALUE_TYPE_STRING
;
380 @brief Returns whether or not the value object \p object is an array
383 @param[in] object Value object to check.
384 @returns #BT_TRUE if \p object is an array value object.
387 @postrefcountsame{object}
389 @sa bt_value_get_type(): Returns the type of a given value object.
392 bt_bool
bt_value_is_array(const struct bt_value
*object
)
394 return bt_value_get_type(object
) == BT_VALUE_TYPE_ARRAY
;
398 @brief Returns whether or not the value object \p object is a map value
401 @param[in] object Value object to check.
402 @returns #BT_TRUE if \p object is a map value object.
405 @postrefcountsame{object}
407 @sa bt_value_get_type(): Returns the type of a given value object.
410 bt_bool
bt_value_is_map(const struct bt_value
*object
)
412 return bt_value_get_type(object
) == BT_VALUE_TYPE_MAP
;
418 @name Common value object functions
423 @brief Recursively freezes the value object \p object.
425 You cannot modify a frozen value object: it is considered immutable.
426 Reference counting still works on a frozen value object, however: you
427 can pass a frozen value object to bt_get() and bt_put().
429 If \p object is an array value object or a map value object, this
430 function also freezes all its children recursively.
432 Freezing a value object is typically used to make it immutable after
433 it's built by its initial owner.
435 @param[in] object Value object to freeze.
436 @returns Status code. If \p object
437 is already frozen, however, #BT_VALUE_STATUS_OK
438 is returned anyway (that is, this function never
439 returns #BT_VALUE_STATUS_FROZEN).
442 @postrefcountsame{object}
443 @post <strong>On success</strong>, \p object and all its children
446 @sa bt_value_is_frozen(): Returns whether or not a value object is
449 extern enum bt_value_status
bt_value_freeze(struct bt_value
*object
);
452 @brief Returns whether or not the value object \p object is frozen.
454 @param[in] object Value object to check.
455 @returns #BT_TRUE if \p object is frozen.
458 @postrefcountsame{object}
460 extern bt_bool
bt_value_is_frozen(const struct bt_value
*object
);
463 @brief Creates a \em deep copy of the value object \p object.
465 You can copy a frozen value object: the resulting copy is
468 @param[in] object Value object to copy.
469 @returns Deep copy of \p object on success, or \c NULL
473 @post <strong>On success, if the returned value object is not
474 \ref bt_value_null</strong>, its reference count is 1.
475 @postrefcountsame{object}
477 extern struct bt_value
*bt_value_copy(const struct bt_value
*object
);
480 @brief Recursively compares the value objects \p object_a and
481 \p object_b and returns #BT_TRUE if they have the same
482 \em content (raw values).
484 @param[in] object_a Value object A to compare to \p object_b.
485 @param[in] object_b Value object B to compare to \p object_a.
486 @returns #BT_TRUE if \p object_a and \p object_b have the
487 same \em content, or #BT_FALSE if they differ
490 @postrefcountsame{object_a}
491 @postrefcountsame{object_b}
493 extern bt_bool
bt_value_compare(const struct bt_value
*object_a
,
494 const struct bt_value
*object_b
);
499 @name Boolean value object functions
504 @brief Creates a default boolean value object.
506 The created boolean value object's initial raw value is #BT_FALSE.
508 @returns Created boolean value object on success, or \c NULL
511 @postsuccessrefcountret1
513 @sa bt_value_bool_create_init(): Creates an initialized boolean
516 extern struct bt_value
*bt_value_bool_create(void);
519 @brief Creates a boolean value object with its initial raw value set to
522 @param[in] val Initial raw value.
523 @returns Created boolean value object on success, or
526 @postsuccessrefcountret1
528 @sa bt_value_bool_create(): Creates a default boolean value object.
530 extern struct bt_value
*bt_value_bool_create_init(bt_bool val
);
533 @brief Returns the boolean raw value of the boolean value object
536 @param[in] bool_obj Boolean value object of which to get the
538 @param[out] val Returned boolean raw value.
539 @returns Status code.
541 @prenotnull{bool_obj}
543 @pre \p bool_obj is a boolean value object.
544 @postrefcountsame{bool_obj}
546 @sa bt_value_bool_set(): Sets the raw value of a boolean value object.
548 extern enum bt_value_status
bt_value_bool_get(
549 const struct bt_value
*bool_obj
, bt_bool
*val
);
552 @brief Sets the boolean raw value of the boolean value object
553 \p bool_obj to \p val.
555 @param[in] bool_obj Boolean value object of which to set
557 @param[in] val New boolean raw value.
558 @returns Status code.
560 @prenotnull{bool_obj}
561 @pre \p bool_obj is a boolean value object.
563 @postrefcountsame{bool_obj}
565 @sa bt_value_bool_get(): Returns the raw value of a given boolean
568 extern enum bt_value_status
bt_value_bool_set(struct bt_value
*bool_obj
,
574 @name Integer value object functions
579 @brief Creates a default integer value object.
581 The created integer value object's initial raw value is 0.
583 @returns Created integer value object on success, or \c NULL
586 @postsuccessrefcountret1
588 @sa bt_value_integer_create_init(): Creates an initialized integer
591 extern struct bt_value
*bt_value_integer_create(void);
594 @brief Creates an integer value object with its initial raw value set to
597 @param[in] val Initial raw value.
598 @returns Created integer value object on success, or
601 @postsuccessrefcountret1
603 @sa bt_value_integer_create(): Creates a default integer
606 extern struct bt_value
*bt_value_integer_create_init(int64_t val
);
609 @brief Returns the integer raw value of the integer value object
612 @param[in] integer_obj Integer value object of which to get the
614 @param[out] val Returned integer raw value.
615 @returns Status code.
617 @prenotnull{integer_obj}
619 @pre \p integer_obj is an integer value object.
620 @postrefcountsame{integer_obj}
622 @sa bt_value_integer_set(): Sets the raw value of an integer value
625 extern enum bt_value_status
bt_value_integer_get(
626 const struct bt_value
*integer_obj
, int64_t *val
);
629 @brief Sets the integer raw value of the integer value object
630 \p integer_obj to \p val.
632 @param[in] integer_obj Integer value object of which to set
634 @param[in] val New integer raw value.
635 @returns Status code.
637 @prenotnull{integer_obj}
638 @pre \p integer_obj is an integer value object.
640 @postrefcountsame{integer_obj}
642 @sa bt_value_integer_get(): Returns the raw value of a given integer
645 extern enum bt_value_status
bt_value_integer_set(
646 struct bt_value
*integer_obj
, int64_t val
);
651 @name Floating point number value object functions
656 @brief Creates a default floating point number value object.
658 The created floating point number value object's initial raw value is 0.
660 @returns Created floating point number value object on success,
663 @postsuccessrefcountret1
665 @sa bt_value_float_create_init(): Creates an initialized floating
666 point number value object.
668 extern struct bt_value
*bt_value_float_create(void);
671 @brief Creates a floating point number value object with its initial raw
674 @param[in] val Initial raw value.
675 @returns Created floating point number value object on
676 success, or \c NULL on error.
678 @postsuccessrefcountret1
680 @sa bt_value_float_create(): Creates a default floating point number
683 extern struct bt_value
*bt_value_float_create_init(double val
);
686 @brief Returns the floating point number raw value of the floating point
687 number value object \p float_obj.
689 @param[in] float_obj Floating point number value object of which to
691 @param[out] val Returned floating point number raw value
692 @returns Status code.
694 @prenotnull{float_obj}
696 @pre \p float_obj is a floating point number value object.
697 @postrefcountsame{float_obj}
699 @sa bt_value_float_set(): Sets the raw value of a given floating
700 point number value object.
702 extern enum bt_value_status
bt_value_float_get(
703 const struct bt_value
*float_obj
, double *val
);
706 @brief Sets the floating point number raw value of the floating point
707 number value object \p float_obj to \p val.
709 @param[in] float_obj Floating point number value object of which to set
711 @param[in] val New floating point number raw value.
712 @returns Status code.
714 @prenotnull{float_obj}
715 @pre \p float_obj is a floating point number value object.
717 @postrefcountsame{float_obj}
719 @sa bt_value_float_get(): Returns the raw value of a floating point
722 extern enum bt_value_status
bt_value_float_set(
723 struct bt_value
*float_obj
, double val
);
728 @name String value object functions
733 @brief Creates a default string value object.
735 The string value object is initially empty.
737 @returns Created string value object on success, or \c NULL
740 @postsuccessrefcountret1
742 @sa bt_value_string_create_init(): Creates an initialized string
745 extern struct bt_value
*bt_value_string_create(void);
748 @brief Creates a string value object with its initial raw value set to
751 On success, \p val is copied.
753 @param[in] val Initial raw value (copied on success).
754 @returns Created string value object on success, or
758 @postsuccessrefcountret1
760 @sa bt_value_float_create(): Creates a default string value object.
762 extern struct bt_value
*bt_value_string_create_init(const char *val
);
765 @brief Returns the string raw value of the string value object
768 The returned string is placed in \p *val. It is valid as long as this
769 value object exists and is \em not modified. The ownership of the
770 returned string is \em not transferred to the caller.
772 @param[in] string_obj String value object of which to get the
774 @param[out] val Returned string raw value.
775 @returns Status code.
777 @prenotnull{string_obj}
779 @pre \p string_obj is a string value object.
780 @postrefcountsame{string_obj}
782 @sa bt_value_string_set(): Sets the raw value of a string
785 extern enum bt_value_status
bt_value_string_get(
786 const struct bt_value
*string_obj
, const char **val
);
789 @brief Sets the string raw value of the string value object
790 \p string_obj to \p val.
792 On success, \p val is copied.
794 @param[in] string_obj String value object of which to set
796 @param[in] val New string raw value (copied on success).
797 @returns Status code.
799 @prenotnull{string_obj}
801 @pre \p string_obj is a string value object.
803 @postrefcountsame{string_obj}
805 @sa bt_value_string_get(): Returns the raw value of a given string
808 extern enum bt_value_status
bt_value_string_set(struct bt_value
*string_obj
,
816 * @name Array value object functions
821 @brief Creates an empty array value object.
823 @returns Created array value object on success, or \c NULL
826 @postsuccessrefcountret1
828 extern struct bt_value
*bt_value_array_create(void);
831 @brief Returns the size of the array value object \p array_obj, that is,
832 the number of value objects contained in \p array_obj.
834 @param[in] array_obj Array value object of which to get the size.
835 @returns Number of value objects contained in
836 \p array_obj if the return value is 0 (empty)
837 or a positive value, or one of
838 #bt_value_status negative values otherwise.
840 @prenotnull{array_obj}
841 @pre \p array_obj is an array value object.
842 @postrefcountsame{array_obj}
844 @sa bt_value_array_is_empty(): Checks whether or not a given array
845 value object is empty.
847 extern int64_t bt_value_array_size(const struct bt_value
*array_obj
);
850 @brief Checks whether or not the array value object \p array_obj
853 @param[in] array_obj Array value object to check.
854 @returns #BT_TRUE if \p array_obj is empty.
856 @prenotnull{array_obj}
857 @pre \p array_obj is an array value object.
858 @postrefcountsame{array_obj}
860 @sa bt_value_array_size(): Returns the size of a given array value
863 extern bt_bool
bt_value_array_is_empty(const struct bt_value
*array_obj
);
866 @brief Returns the value object contained in the array value object
867 \p array_obj at the index \p index.
869 @param[in] array_obj Array value object of which to get an element.
870 @param[in] index Index of value object to get.
871 @returns Value object at index \p index on
872 success, or \c NULL on error.
874 @prenotnull{array_obj}
875 @pre \p array_obj is an array value object.
876 @pre \p index is lesser than the size of \p array_obj (see
877 bt_value_array_size()).
878 @post <strong>On success, if the returned value object is not
879 \ref bt_value_null</strong>, its reference count is incremented.
880 @postrefcountsame{array_obj}
882 extern struct bt_value
*bt_value_array_get(const struct bt_value
*array_obj
,
886 @brief Appends the value object \p element_obj to the array value
889 @param[in] array_obj Array value object in which to append
891 @param[in] element_obj Value object to append.
892 @returns Status code.
894 @prenotnull{array_obj}
895 @prenotnull{element_obj}
896 @pre \p array_obj is an array value object.
898 @post <strong>On success, if \p element_obj is not
899 \ref bt_value_null</strong>, its reference count is incremented.
900 @postrefcountsame{array_obj}
902 @sa bt_value_array_append_bool(): Appends a boolean raw value to a
903 given array value object.
904 @sa bt_value_array_append_integer(): Appends an integer raw value
905 to a given array value object.
906 @sa bt_value_array_append_float(): Appends a floating point number
907 raw value to a given array value object.
908 @sa bt_value_array_append_string(): Appends a string raw value to a
909 given array value object.
910 @sa bt_value_array_append_empty_array(): Appends an empty array value
911 object to a given array value object.
912 @sa bt_value_array_append_empty_map(): Appends an empty map value
913 object to a given array value object.
915 extern enum bt_value_status
bt_value_array_append(struct bt_value
*array_obj
,
916 struct bt_value
*element_obj
);
919 @brief Appends the boolean raw value \p val to the array value object
922 This is a convenience function which creates the underlying boolean
923 value object before appending it.
925 @param[in] array_obj Array value object in which to append \p val.
926 @param[in] val Boolean raw value to append to \p array_obj.
927 @returns Status code.
929 @prenotnull{array_obj}
930 @pre \p array_obj is an array value object.
932 @postrefcountsame{array_obj}
934 @sa bt_value_array_append(): Appends a value object to a given
937 extern enum bt_value_status
bt_value_array_append_bool(
938 struct bt_value
*array_obj
, bt_bool val
);
941 @brief Appends the integer raw value \p val to the array value object
944 This is a convenience function which creates the underlying integer
945 value object before appending it.
947 @param[in] array_obj Array value object in which to append \p val.
948 @param[in] val Integer raw value to append to \p array_obj.
949 @returns Status code.
951 @prenotnull{array_obj}
952 @pre \p array_obj is an array value object.
954 @postrefcountsame{array_obj}
956 @sa bt_value_array_append(): Appends a value object to a given
959 extern enum bt_value_status
bt_value_array_append_integer(
960 struct bt_value
*array_obj
, int64_t val
);
963 @brief Appends the floating point number raw value \p val to the array
964 value object \p array_obj.
966 This is a convenience function which creates the underlying floating
967 point number value object before appending it.
969 @param[in] array_obj Array value object in which to append \p val.
970 @param[in] val Floating point number raw value to append
972 @returns Status code.
974 @prenotnull{array_obj}
975 @pre \p array_obj is an array value object.
977 @postrefcountsame{array_obj}
979 @sa bt_value_array_append(): Appends a value object to a given
982 extern enum bt_value_status
bt_value_array_append_float(
983 struct bt_value
*array_obj
, double val
);
986 @brief Appends the string raw value \p val to the array value object
989 This is a convenience function which creates the underlying string value
990 object before appending it.
992 On success, \p val is copied.
994 @param[in] array_obj Array value object in which to append \p val.
995 @param[in] val String raw value to append to \p array_obj
997 @returns Status code.
999 @prenotnull{array_obj}
1000 @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_string(
1009 struct bt_value
*array_obj
, const char *val
);
1012 @brief Appends an empty array value object to the array value object
1015 This is a convenience function which creates the underlying array value
1016 object before appending it.
1018 @param[in] array_obj Array value object in which to append an
1019 empty array value object
1020 @returns Status code.
1022 @prenotnull{array_obj}
1023 @pre \p array_obj is an array value object.
1025 @postrefcountsame{array_obj}
1027 @sa bt_value_array_append(): Appends a value object to a given
1030 extern enum bt_value_status
bt_value_array_append_empty_array(
1031 struct bt_value
*array_obj
);
1034 @brief Appends an empty map value object to the array value object
1037 This is a convenience function which creates the underlying map value
1038 object before appending it.
1040 @param[in] array_obj Array value object in which to append an empty
1042 @returns Status code.
1044 @prenotnull{array_obj}
1045 @pre \p array_obj is an array value object.
1047 @postrefcountsame{array_obj}
1049 @sa bt_value_array_append(): Appends a value object to a given
1052 extern enum bt_value_status
bt_value_array_append_empty_map(
1053 struct bt_value
*array_obj
);
1056 @brief Replaces the value object contained in the array value object
1057 \p array_obj at the index \p index by \p element_obj.
1059 @param[in] array_obj Array value object in which to replace
1061 @param[in] index Index of value object to replace in
1063 @param[in] element_obj New value object at position \p index of
1065 @returns Status code.
1067 @prenotnull{array_obj}
1068 @prenotnull{element_obj}
1069 @pre \p array_obj is an array value object.
1070 @pre \p index is lesser than the size of \p array_obj (see
1071 bt_value_array_size()).
1073 @post <strong>On success, if the replaced value object is not
1074 \ref bt_value_null</strong>, its reference count is decremented.
1075 @post <strong>On success, if \p element_obj is not
1076 \ref bt_value_null</strong>, its reference count is incremented.
1077 @postrefcountsame{array_obj}
1079 extern enum bt_value_status
bt_value_array_set(struct bt_value
*array_obj
,
1080 uint64_t index
, struct bt_value
*element_obj
);
1085 @name Map value object functions
1090 @brief Creates an empty map value object.
1092 @returns Created map value object on success, or \c NULL on error.
1094 @postsuccessrefcountret1
1096 extern struct bt_value
*bt_value_map_create(void);
1099 @brief Returns the size of the map value object \p map_obj, that is, the
1100 number of entries contained in \p map_obj.
1102 @param[in] map_obj Map value object of which to get the size.
1103 @returns Number of entries contained in \p map_obj if the
1104 return value is 0 (empty) or a positive value,
1105 or one of #bt_value_status negative values
1108 @prenotnull{map_obj}
1109 @pre \p map_obj is a map value object.
1110 @postrefcountsame{map_obj}
1112 @sa bt_value_map_is_empty(): Checks whether or not a given map value
1115 extern int64_t bt_value_map_size(const struct bt_value
*map_obj
);
1118 @brief Checks whether or not the map value object \p map_obj is empty.
1120 @param[in] map_obj Map value object to check.
1121 @returns #BT_TRUE if \p map_obj is empty.
1123 @prenotnull{map_obj}
1124 @pre \p map_obj is a map value object.
1125 @postrefcountsame{map_obj}
1127 @sa bt_value_map_size(): Returns the size of a given map value object.
1129 extern bt_bool
bt_value_map_is_empty(const struct bt_value
*map_obj
);
1132 @brief Returns the value object associated with the key \p key within
1133 the map value object \p map_obj.
1135 @param[in] map_obj Map value object of which to get an entry.
1136 @param[in] key Key of the value object to get.
1137 @returns Value object associated with the key \p key
1138 on success, or \c NULL on error.
1140 @prenotnull{map_obj}
1142 @pre \p map_obj is a map value object.
1143 @postrefcountsame{map_obj}
1144 @post <strong>On success, if the returned value object is not
1145 \ref bt_value_null</strong>, its reference count is incremented.
1147 extern struct bt_value
*bt_value_map_get(const struct bt_value
*map_obj
,
1151 @brief User function type to use with bt_value_map_foreach().
1153 \p object is a <em>weak reference</em>: you \em must pass it to bt_get()
1154 if you need to keep a reference after this function returns.
1156 This function \em must return #BT_TRUE to continue the map value object
1157 traversal, or #BT_FALSE to break it.
1159 @param[in] key Key of map entry.
1160 @param[in] object Value object of map entry (weak reference).
1161 @param[in] data User data.
1162 @returns #BT_TRUE to continue the loop, or #BT_FALSE to break it.
1166 @post The reference count of \p object is not lesser than what it is
1167 when the function is called.
1169 typedef bt_bool (* bt_value_map_foreach_cb
)(const char *key
,
1170 struct bt_value
*object
, void *data
);
1173 @brief Calls a provided user function \p cb for each value object of the
1174 map value object \p map_obj.
1176 The value object passed to the user function is a <b>weak reference</b>:
1177 you \em must pass it to bt_get() if you need to keep a persistent
1178 reference after the user function returns.
1180 The key passed to the user function is only valid in the scope of
1181 this user function call.
1183 The user function \em must return #BT_TRUE to continue the traversal of
1184 \p map_obj, or #BT_FALSE to break it.
1186 @param[in] map_obj Map value object on which to iterate.
1187 @param[in] cb User function to call back.
1188 @param[in] data User data passed to the user function.
1189 @returns Status code. More
1190 specifically, #BT_VALUE_STATUS_CANCELLED is
1191 returned if the loop was cancelled by the user
1194 @prenotnull{map_obj}
1196 @pre \p map_obj is a map value object.
1197 @postrefcountsame{map_obj}
1199 extern enum bt_value_status
bt_value_map_foreach(
1200 const struct bt_value
*map_obj
, bt_value_map_foreach_cb cb
,
1204 @brief Returns whether or not the map value object \p map_obj contains
1205 an entry mapped to the key \p key.
1207 @param[in] map_obj Map value object to check.
1208 @param[in] key Key to check.
1209 @returns #BT_TRUE if \p map_obj has an entry mapped to the
1210 key \p key, or #BT_FALSE if it does not or
1213 @prenotnull{map_obj}
1215 @pre \p map_obj is a map value object.
1216 @postrefcountsame{map_obj}
1218 extern bt_bool
bt_value_map_has_key(const struct bt_value
*map_obj
,
1222 @brief Inserts the value object \p element_obj mapped to the key
1223 \p key into the map value object \p map_obj.
1225 If a value object is already mapped to \p key in \p map_obj, the
1226 associated value object is first put, and then replaced by
1229 On success, \p key is copied.
1231 @param[in] map_obj Map value object in which to insert
1233 @param[in] key Key (copied on success) to which the
1234 value object to insert is mapped.
1235 @param[in] element_obj Value object to insert, mapped to the
1237 @returns Status code.
1239 @prenotnull{map_obj}
1241 @prenotnull{element_obj}
1242 @pre \p map_obj is a map value object.
1244 @post <strong>On success, if \p element_obj is not
1245 \ref bt_value_null</strong>, its reference count is incremented.
1246 @postrefcountsame{map_obj}
1248 @sa bt_value_map_insert_bool(): Inserts a boolean raw value into a
1249 given map value object.
1250 @sa bt_value_map_insert_integer(): Inserts an integer raw value into
1251 a given map value object.
1252 @sa bt_value_map_insert_float(): Inserts a floating point number raw
1253 value into a given map value object.
1254 @sa bt_value_map_insert_string(): Inserts a string raw value into a
1255 given map value object.
1256 @sa bt_value_map_insert_empty_array(): Inserts an empty array value
1257 object into a given map value object.
1258 @sa bt_value_map_insert_empty_map(): Inserts an empty map value
1259 object into a given map value object.
1261 extern enum bt_value_status
bt_value_map_insert(
1262 struct bt_value
*map_obj
, const char *key
,
1263 struct bt_value
*element_obj
);
1266 @brief Inserts the boolean raw value \p val mapped to the key \p key
1267 into the map value object \p map_obj.
1269 This is a convenience function which creates the underlying boolean
1270 value object before inserting it.
1272 On success, \p key is copied.
1274 @param[in] map_obj Map value object in which to insert \p val.
1275 @param[in] key Key (copied on success) to which the boolean
1276 value object to insert is mapped.
1277 @param[in] val Boolean raw value to insert, mapped to
1279 @returns Status code.
1281 @prenotnull{map_obj}
1283 @pre \p map_obj is a map value object.
1285 @postrefcountsame{map_obj}
1287 @sa bt_value_map_insert(): Inserts a value object into a given map
1290 extern enum bt_value_status
bt_value_map_insert_bool(
1291 struct bt_value
*map_obj
, const char *key
, bt_bool val
);
1294 @brief Inserts the integer raw value \p val mapped to the key \p key
1295 into the map value object \p map_obj.
1297 This is a convenience function which creates the underlying integer
1298 value object before inserting it.
1300 On success, \p key is copied.
1302 @param[in] map_obj Map value object in which to insert \p val.
1303 @param[in] key Key (copied on success) to which the integer
1304 value object to insert is mapped.
1305 @param[in] val Integer raw value to insert, mapped to
1307 @returns Status code.
1309 @prenotnull{map_obj}
1311 @pre \p map_obj is a map value object.
1313 @postrefcountsame{map_obj}
1315 @sa bt_value_map_insert(): Inserts a value object into a given map
1318 extern enum bt_value_status
bt_value_map_insert_integer(
1319 struct bt_value
*map_obj
, const char *key
, int64_t val
);
1322 @brief Inserts the floating point number raw value \p val mapped to
1323 the key \p key into the map value object \p map_obj.
1325 This is a convenience function which creates the underlying floating
1326 point number value object before inserting it.
1328 On success, \p key is copied.
1330 @param[in] map_obj Map value object in which to insert \p val.
1331 @param[in] key Key (copied on success) to which the floating
1332 point number value object to insert is mapped.
1333 @param[in] val Floating point number raw value to insert,
1334 mapped to the key \p key.
1335 @returns Status code.
1337 @prenotnull{map_obj}
1339 @pre \p map_obj is a map value object.
1341 @postrefcountsame{map_obj}
1343 @sa bt_value_map_insert(): Inserts a value object into a given map
1346 extern enum bt_value_status
bt_value_map_insert_float(
1347 struct bt_value
*map_obj
, const char *key
, double val
);
1350 @brief Inserts the string raw value \p val mapped to the key \p key
1351 into the map value object \p map_obj.
1353 This is a convenience function which creates the underlying string value
1354 object before inserting it.
1356 On success, \p val and \p key are copied.
1358 @param[in] map_obj Map value object in which to insert \p val.
1359 @param[in] key Key (copied on success) to which the string
1360 value object to insert is mapped.
1361 @param[in] val String raw value to insert (copied on success),
1362 mapped to the key \p key.
1363 @returns Status code.
1365 @prenotnull{map_obj}
1368 @pre \p map_obj is a map value object.
1370 @postrefcountsame{map_obj}
1372 @sa bt_value_map_insert(): Inserts a value object into a given map
1375 extern enum bt_value_status
bt_value_map_insert_string(
1376 struct bt_value
*map_obj
, const char *key
, const char *val
);
1379 @brief Inserts an empty array value object mapped to the key \p key
1380 into the map value object \p map_obj.
1382 This is a convenience function which creates the underlying array value
1383 object before inserting it.
1385 On success, \p key is copied.
1387 @param[in] map_obj Map value object in which to insert an empty
1389 @param[in] key Key (copied on success) to which the empty array
1390 value object to insert is mapped.
1391 @returns Status code.
1393 @prenotnull{map_obj}
1395 @pre \p map_obj is a map value object.
1397 @postrefcountsame{map_obj}
1399 @sa bt_value_map_insert(): Inserts a value object into a given map
1402 extern enum bt_value_status
bt_value_map_insert_empty_array(
1403 struct bt_value
*map_obj
, const char *key
);
1406 @brief Inserts an empty map value object mapped to the key \p key into
1407 the map value object \p map_obj.
1409 This is a convenience function which creates the underlying map value
1410 object before inserting it.
1412 On success, \p key is copied.
1414 @param[in] map_obj Map value object in which to insert an empty
1416 @param[in] key Key (copied on success) to which the empty map
1417 value object to insert is mapped.
1418 @returns Status code.
1420 @prenotnull{map_obj}
1422 @pre \p map_obj is a map value object.
1424 @postrefcountsame{map_obj}
1426 @sa bt_value_map_insert(): Inserts a value object into a given map
1429 extern enum bt_value_status
bt_value_map_insert_empty_map(
1430 struct bt_value
*map_obj
, const char *key
);
1433 @brief Creates a copy of the base map value object \p base_map_obj
1434 superficially extended with the entries of the extension map
1435 value object \p extension_map_obj.
1437 This function creates a superficial extension of \p base_map_obj with
1438 \p extension_map_obj by adding new entries to it and replacing the
1439 ones that share the keys in the extension object. The extension is
1440 \em superficial because it does not merge internal array and map
1443 For example, consider the following \p base_map_obj (JSON representation):
1450 "return": [5, 6, null]
1454 and the following \p extension_map_obj (JSON representation):
1464 The extended object is (JSON representation):
1476 @param[in] base_map_obj Base map value object with initial
1478 @param[in] extension_map_obj Extension map value object containing
1479 the entries to add to or replace in
1481 @returns Created extended map value object, or
1484 @prenotnull{base_map_obj}
1485 @prenotnull{extension_map_obj}
1486 @pre \p base_map_obj is a map value object.
1487 @pre \p extension_map_obj is a map value object.
1488 @postrefcountsame{base_map_obj}
1489 @postrefcountsame{extension_map_obj}
1490 @postsuccessrefcountret1
1492 extern struct bt_value
*bt_value_map_extend(struct bt_value
*base_map_obj
,
1493 struct bt_value
*extension_map_obj
);
1503 #endif /* BABELTRACE_VALUES_H */