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
32 #include <babeltrace/ref.h>
39 @defgroup values Value objects
43 This is a set of <strong><em>value objects</em></strong>. With the
44 functions documented here, you can create and modify:
46 - \link bt_value_bool_create() Boolean value objects\endlink.
47 - \link bt_value_integer_create() Integer value objects\endlink.
48 - \link bt_value_float_create() Floating point number
49 value objects\endlink.
50 - \link bt_value_string_create() String value objects\endlink.
51 - \link bt_value_array_create() Array value objects\endlink,
52 containing zero or more value objects.
53 - \link bt_value_map_create() Map value objects\endlink, mapping
54 string keys to value objects.
56 As with any Babeltrace object, value objects have
57 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
58 counts</a>. When you \link bt_value_array_append() append a value object
59 to an array value object\endlink, or when you \link bt_value_map_insert()
60 insert a value object into a map value object\endlink, its reference
61 count is incremented, as well as when you get a value object back from
62 those objects. See \ref refs to learn more about the reference counting
63 management of Babeltrace objects.
65 Most functions of this API return a <em>status code</em>, one of the
66 values of #bt_value_status.
68 You can create a deep copy of any value object with bt_value_copy(). You
69 can compare two value objects with bt_value_compare().
71 You can \em freeze a value object with bt_value_freeze(). You can get
72 the raw value of a frozen value object, but you cannot modify it.
73 Reference counting still works on frozen value objects. You can copy
74 a frozen value object: the returned copy is not frozen. You can also
75 compare a frozen value object to another value object (frozen or not).
76 Freezing a value object is typically used to make it immutable after
77 it's built by its initial owner.
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()
147 <td>bt_value_is_map()
148 <td>bt_value_map_get()<br>
149 bt_value_map_foreach()
150 <td>bt_value_map_insert()<br>
151 bt_value_map_insert_bool()<br>
152 bt_value_map_insert_integer()<br>
153 bt_value_map_insert_float()<br>
154 bt_value_map_insert_string()<br>
155 bt_value_map_insert_empty_array()<br>
156 bt_value_map_insert_empty_map()
161 @brief Value object types and functions.
171 enum bt_value_status
{
172 /// Value object cannot be altered because it's frozen.
173 BT_VALUE_STATUS_FROZEN
= -4,
175 /// Operation cancelled.
176 BT_VALUE_STATUS_CANCELLED
= -3,
178 /* -22 for compatibility with -EINVAL */
179 /// Invalid arguments.
180 BT_VALUE_STATUS_INVAL
= -22,
183 BT_VALUE_STATUS_ERROR
= -1,
186 BT_VALUE_STATUS_OK
= 0,
191 @brief A value object.
197 @brief The null value object singleton.
199 You \em must use this variable when you need the null value object.
201 The null value object singleton has no reference count: there is only
202 one. You can compare any value object address to the null value object
203 singleton to check if it's the null value object, or otherwise with
206 You can pass \ref bt_value_null to bt_get() or bt_put(): it has
209 The null value object singleton is <em>always frozen</em> (see
210 bt_value_is_frozen()).
212 The functions of this API return this variable when the value object
213 is actually the null value object (of type #BT_VALUE_TYPE_NULL),
214 whereas \c NULL means an error of some sort.
216 extern struct bt_value
*bt_value_null
;
219 @name Type information
224 @brief Value object type.
227 /// Unknown value object, used as an error code.
228 BT_VALUE_TYPE_UNKNOWN
= -1,
230 /// Null value object.
231 BT_VALUE_TYPE_NULL
= 0,
233 /// Boolean value object (holds \c true or \c false).
234 BT_VALUE_TYPE_BOOL
= 1,
236 /// Integer value object (holds a signed 64-bit integer raw value).
237 BT_VALUE_TYPE_INTEGER
= 2,
239 /// Floating point number value object (holds a \c double raw value).
240 BT_VALUE_TYPE_FLOAT
= 3,
242 /// String value object.
243 BT_VALUE_TYPE_STRING
= 4,
245 /// Array value object.
246 BT_VALUE_TYPE_ARRAY
= 5,
248 /// Map value object.
249 BT_VALUE_TYPE_MAP
= 6,
253 @brief Returns the type of the value object \p object.
255 @param[in] object Value object of which to get the type.
256 @returns Type of value object \p object,
257 or #BT_VALUE_TYPE_UNKNOWN on error.
260 @postrefcountsame{object}
262 @sa #bt_value_type: Value object types.
263 @sa bt_value_is_null(): Returns whether or not a given value object
264 is the null value object.
265 @sa bt_value_is_bool(): Returns whether or not a given value object
266 is a boolean value object.
267 @sa bt_value_is_integer(): Returns whether or not a given value
268 object is an integer value object.
269 @sa bt_value_is_float(): Returns whether or not a given value object
270 is a floating point number value object.
271 @sa bt_value_is_string(): Returns whether or not a given value object
272 is a string value object.
273 @sa bt_value_is_array(): Returns whether or not a given value object
274 is an array value object.
275 @sa bt_value_is_map(): Returns whether or not a given value object
276 is a map value object.
278 extern enum bt_value_type
bt_value_get_type(const struct bt_value
*object
);
281 @brief Returns whether or not the value object \p object is the null
284 The only valid null value object is \ref bt_value_null.
286 An alternative to calling this function is to directly compare the value
287 object pointer to the \ref bt_value_null variable.
289 @param[in] object Value object to check.
290 @returns \c true if \p object is the null value object.
293 @postrefcountsame{object}
295 @sa bt_value_get_type(): Returns the type of a given value object.
298 bool bt_value_is_null(const struct bt_value
*object
)
300 return bt_value_get_type(object
) == BT_VALUE_TYPE_NULL
;
304 @brief Returns whether or not the value object \p object is a boolean
307 @param[in] object Value object to check.
308 @returns \c true if \p object is a boolean value object.
311 @postrefcountsame{object}
313 @sa bt_value_get_type(): Returns the type of a given value object.
316 bool bt_value_is_bool(const struct bt_value
*object
)
318 return bt_value_get_type(object
) == BT_VALUE_TYPE_BOOL
;
322 @brief Returns whether or not the value object \p object is an integer
325 @param[in] object Value object to check.
326 @returns \c true if \p object is an integer value object.
328 @sa bt_value_get_type(): Returns the type of a given value object.
331 bool bt_value_is_integer(const struct bt_value
*object
)
333 return bt_value_get_type(object
) == BT_VALUE_TYPE_INTEGER
;
337 @brief Returns whether or not the value object \p object is a floating
338 point number value object.
340 @param[in] object Value object to check.
341 @returns \c true if \p object is a floating point
345 @postrefcountsame{object}
347 @sa bt_value_get_type(): Returns the type of a given value object.
350 bool bt_value_is_float(const struct bt_value
*object
)
352 return bt_value_get_type(object
) == BT_VALUE_TYPE_FLOAT
;
356 @brief Returns whether or not the value object \p object is a string
359 @param[in] object Value object to check.
360 @returns \c true if \p object is a string value object.
363 @postrefcountsame{object}
365 @sa bt_value_get_type(): Returns the type of a given value object.
368 bool bt_value_is_string(const struct bt_value
*object
)
370 return bt_value_get_type(object
) == BT_VALUE_TYPE_STRING
;
374 @brief Returns whether or not the value object \p object is an array
377 @param[in] object Value object to check.
378 @returns \c true if \p object is an array value object.
381 @postrefcountsame{object}
383 @sa bt_value_get_type(): Returns the type of a given value object.
386 bool bt_value_is_array(const struct bt_value
*object
)
388 return bt_value_get_type(object
) == BT_VALUE_TYPE_ARRAY
;
392 @brief Returns whether or not the value object \p object is a map value
395 @param[in] object Value object to check.
396 @returns \c true if \p object is a map value object.
399 @postrefcountsame{object}
401 @sa bt_value_get_type(): Returns the type of a given value object.
404 bool bt_value_is_map(const struct bt_value
*object
)
406 return bt_value_get_type(object
) == BT_VALUE_TYPE_MAP
;
412 @name Common value object functions
417 @brief Recursively freezes the value object \p object.
419 You cannot modify a frozen value object: it is considered immutable.
420 Reference counting still works on a frozen value object, however: you
421 can pass a frozen value object to bt_get() and bt_put().
423 If \p object is an array value object or a map value object, this
424 function also freezes all its children recursively.
426 Freezing a value object is typically used to make it immutable after
427 it's built by its initial owner.
429 @param[in] object Value object to freeze.
430 @returns One of #bt_value_status values. If \p object
431 is already frozen, however, #BT_VALUE_STATUS_OK
432 is returned anyway (that is, this function never
433 returns #BT_VALUE_STATUS_FROZEN).
436 @postrefcountsame{object}
437 @post <strong>On success</strong>, \p object and all its children
440 @sa bt_value_is_frozen(): Returns whether or not a value object is
443 extern enum bt_value_status
bt_value_freeze(struct bt_value
*object
);
446 @brief Returns whether or not the value object \p object is frozen.
448 @param[in] object Value object to check.
449 @returns \c true if \p object is frozen.
452 @postrefcountsame{object}
454 extern bool bt_value_is_frozen(const struct bt_value
*object
);
457 @brief Creates a \em deep copy of the value object \p object.
459 You can copy a frozen value object: the resulting copy is
462 @param[in] object Value object to copy.
463 @returns Deep copy of \p object on success, or \c NULL
467 @post <strong>On success, if the returned value object is not
468 \ref bt_value_null</strong>, its reference count is 1.
470 @postrefcountsame{object}
472 extern struct bt_value
*bt_value_copy(const struct bt_value
*object
);
475 @brief Recursively compares the value objects \p object_a and
476 \p object_b and returns \c true if they have the same
477 \em content (raw values).
479 @param[in] object_a Value object A to compare to \p object_b.
480 @param[in] object_b Value object B to compare to \p object_a.
481 @returns \c true if \p object_a and \p object_b have the
482 same \em content, or \c false if they differ
485 @postrefcountsame{object_a}
486 @postrefcountsame{object_b}
488 extern bool bt_value_compare(const struct bt_value
*object_a
,
489 const struct bt_value
*object_b
);
494 @name Boolean value object functions
499 @brief Creates a default boolean value object.
501 The created boolean value object's initial raw value is \c false.
503 @returns Created boolean value object on success, or \c NULL
506 @postsuccessrefcountret1
508 @sa bt_value_bool_create_init(): Creates an initialized boolean
511 extern struct bt_value
*bt_value_bool_create(void);
514 @brief Creates a boolean value object with its initial raw value set to
517 @param[in] val Initial raw value.
518 @returns Created boolean value object on success, or
521 @postsuccessrefcountret1
523 @sa bt_value_bool_create(): Creates a default boolean value object.
525 extern struct bt_value
*bt_value_bool_create_init(bool val
);
528 @brief Returns the boolean raw value of the boolean value object
531 @param[in] bool_obj Boolean value object of which to get the
533 @param[out] val Returned boolean raw value.
534 @returns One of #bt_value_status values.
536 @prenotnull{bool_obj}
538 @pre \p bool_obj is a boolean value object.
539 @postrefcountsame{bool_obj}
541 @sa bt_value_bool_set(): Sets the raw value of a boolean value object.
543 extern enum bt_value_status
bt_value_bool_get(
544 const struct bt_value
*bool_obj
, bool *val
);
547 @brief Sets the boolean raw value of the boolean value object
548 \p bool_obj to \p val.
550 @param[in] bool_obj Boolean value object of which to set
552 @param[in] val New boolean raw value.
553 @returns One of #bt_value_status values.
555 @prenotnull{bool_obj}
556 @pre \p bool_obj is a boolean value object.
558 @postrefcountsame{bool_obj}
560 @sa bt_value_bool_get(): Returns the raw value of a given boolean
563 extern enum bt_value_status
bt_value_bool_set(struct bt_value
*bool_obj
,
569 @name Integer value object functions
574 @brief Creates a default integer value object.
576 The created integer value object's initial raw value is 0.
578 @returns Created integer value object on success, or \c NULL
581 @postsuccessrefcountret1
583 @sa bt_value_integer_create_init(): Creates an initialized integer
586 extern struct bt_value
*bt_value_integer_create(void);
589 @brief Creates an integer value object with its initial raw value set to
592 @param[in] val Initial raw value.
593 @returns Created integer value object on success, or
596 @postsuccessrefcountret1
598 @sa bt_value_integer_create(): Creates a default integer
601 extern struct bt_value
*bt_value_integer_create_init(int64_t val
);
604 @brief Returns the integer raw value of the integer value object
607 @param[in] integer_obj Integer value object of which to get the
609 @param[out] val Returned integer raw value.
610 @returns One of #bt_value_status values.
612 @prenotnull{integer_obj}
614 @pre \p integer_obj is an integer value object.
615 @postrefcountsame{integer_obj}
617 @sa bt_value_integer_set(): Sets the raw value of an integer value
620 extern enum bt_value_status
bt_value_integer_get(
621 const struct bt_value
*integer_obj
, int64_t *val
);
624 @brief Sets the integer raw value of the integer value object
625 \p integer_obj to \p val.
627 @param[in] integer_obj Integer value object of which to set
629 @param[in] val New integer raw value.
630 @returns One of #bt_value_status values.
632 @prenotnull{integer_obj}
633 @pre \p integer_obj is an integer value object.
635 @postrefcountsame{integer_obj}
637 @sa bt_value_integer_get(): Returns the raw value of a given integer
640 extern enum bt_value_status
bt_value_integer_set(
641 struct bt_value
*integer_obj
, int64_t val
);
646 @name Floating point number value object functions
651 @brief Creates a default floating point number value object.
653 The created floating point number value object's initial raw value is 0.
655 @returns Created floating point number value object on success,
658 @postsuccessrefcountret1
660 @sa bt_value_float_create_init(): Creates an initialized floating
661 point number value object.
663 extern struct bt_value
*bt_value_float_create(void);
666 @brief Creates a floating point number value object with its initial raw
669 @param[in] val Initial raw value.
670 @returns Created floating point number value object on
671 success, or \c NULL on error.
673 @postsuccessrefcountret1
675 @sa bt_value_float_create(): Creates a default floating point number
678 extern struct bt_value
*bt_value_float_create_init(double val
);
681 @brief Returns the floating point number raw value of the floating point
682 number value object \p float_obj.
684 @param[in] float_obj Floating point number value object of which to
686 @param[out] val Returned floating point number raw value
687 @returns One of #bt_value_status values.
689 @prenotnull{float_obj}
691 @pre \p float_obj is a floating point number value object.
692 @postrefcountsame{float_obj}
694 @sa bt_value_float_set(): Sets the raw value of a given floating
695 point number value object.
697 extern enum bt_value_status
bt_value_float_get(
698 const struct bt_value
*float_obj
, double *val
);
701 @brief Sets the floating point number raw value of the floating point
702 number value object \p float_obj to \p val.
704 @param[in] float_obj Floating point number value object of which to set
706 @param[in] val New floating point number raw value.
707 @returns One of #bt_value_status values.
709 @prenotnull{float_obj}
710 @pre \p float_obj is a floating point number value object.
712 @postrefcountsame{float_obj}
714 @sa bt_value_float_get(): Returns the raw value of a floating point
717 extern enum bt_value_status
bt_value_float_set(
718 struct bt_value
*float_obj
, double val
);
723 @name String value object functions
728 @brief Creates a default string value object.
730 The string value object is initially empty.
732 @returns Created string value object on success, or \c NULL
735 @postsuccessrefcountret1
737 @sa bt_value_string_create_init(): Creates an initialized string
740 extern struct bt_value
*bt_value_string_create(void);
743 @brief Creates a string value object with its initial raw value set to
746 On success, \p val is copied.
748 @param[in] val Initial raw value (copied on success).
749 @returns Created string value object on success, or
753 @postsuccessrefcountret1
755 @sa bt_value_float_create(): Creates a default string value object.
757 extern struct bt_value
*bt_value_string_create_init(const char *val
);
760 @brief Returns the string raw value of the string value object
763 The returned string is placed in \p *val. It is valid as long as this
764 value object exists and is \em not modified. The ownership of the
765 returned string is \em not transferred to the caller.
767 @param[in] string_obj String value object of which to get the
769 @param[out] val Returned string raw value.
770 @returns One of #bt_value_status values.
772 @prenotnull{string_obj}
774 @pre \p string_obj is a string value object.
775 @postrefcountsame{string_obj}
777 @sa bt_value_string_set(): Sets the raw value of a string
780 extern enum bt_value_status
bt_value_string_get(
781 const struct bt_value
*string_obj
, const char **val
);
784 @brief Sets the string raw value of the string value object
785 \p string_obj to \p val.
787 On success, \p val is copied.
789 @param[in] string_obj String value object of which to set
791 @param[in] val New string raw value (copied on success).
792 @returns One of #bt_value_status values.
794 @prenotnull{string_obj}
796 @pre \p string_obj is a string value object.
798 @postrefcountsame{string_obj}
800 @sa bt_value_string_get(): Returns the raw value of a given string
803 extern enum bt_value_status
bt_value_string_set(struct bt_value
*string_obj
,
811 * @name Array value object functions
816 @brief Creates an empty array value object.
818 @returns Created array value object on success, or \c NULL
821 @postsuccessrefcountret1
823 extern struct bt_value
*bt_value_array_create(void);
826 @brief Returns the size of the array value object \p array_obj, that is,
827 the number of value objects contained in \p array_obj.
829 @param[in] array_obj Array value object of which to get the size.
830 @returns Number of value objects contained in
831 \p array_obj if the return value is 0 (empty)
832 or a positive value, or one of
833 #bt_value_status negative values otherwise.
835 @prenotnull{array_obj}
836 @pre \p array_obj is an array value object.
837 @postrefcountsame{array_obj}
839 @sa bt_value_array_is_empty(): Checks whether or not a given array
840 value object is empty.
842 extern int bt_value_array_size(const struct bt_value
*array_obj
);
845 @brief Checks whether or not the array value object \p array_obj
848 @param[in] array_obj Array value object to check.
849 @returns \c true if \p array_obj is empty.
851 @prenotnull{array_obj}
852 @pre \p array_obj is an array value object.
853 @postrefcountsame{array_obj}
855 @sa bt_value_array_size(): Returns the size of a given array value
858 extern bool bt_value_array_is_empty(const struct bt_value
*array_obj
);
861 @brief Returns the value object contained in the array value object
862 \p array_obj at the index \p index.
864 @param[in] array_obj Array value object of which to get an element.
865 @param[in] index Index of value object to get.
866 @returns Value object at index \p index on
867 success, or \c NULL on error.
869 @prenotnull{array_obj}
870 @pre \p array_obj is an array value object.
871 @pre \p index is lesser than the size of \p array_obj.
872 @post <strong>On success, if the returned value object is not
873 \ref bt_value_null</strong>, its reference count is incremented.
874 @postrefcountsame{array_obj}
876 extern struct bt_value
*bt_value_array_get(const struct bt_value
*array_obj
,
880 @brief Appends the value object \p element_obj to the array value
883 @param[in] array_obj Array value object in which to append
885 @param[in] element_obj Value object to append.
886 @returns One of #bt_value_status values.
888 @prenotnull{array_obj}
889 @prenotnull{element_obj}
890 @pre \p array_obj is an array value object.
892 @post <strong>On success, if \p element_obj is not
893 \ref bt_value_null</strong>, its reference count is incremented.
894 @postrefcountsame{array_obj}
896 @sa bt_value_array_append_bool(): Appends a boolean raw value to a
897 given array value object.
898 @sa bt_value_array_append_integer(): Appends an integer raw value
899 to a given array value object.
900 @sa bt_value_array_append_float(): Appends a floating point number
901 raw value to a given array value object.
902 @sa bt_value_array_append_string(): Appends a string raw value to a
903 given array value object.
904 @sa bt_value_array_append_empty_array(): Appends an empty array value
905 object to a given array value object.
906 @sa bt_value_array_append_empty_map(): Appends an empty map value
907 object to a given array value object.
909 extern enum bt_value_status
bt_value_array_append(struct bt_value
*array_obj
,
910 struct bt_value
*element_obj
);
913 @brief Appends the boolean raw value \p val to the array value object
916 This is a convenience function which creates the underlying boolean
917 value object before appending it.
919 @param[in] array_obj Array value object in which to append \p val.
920 @param[in] val Boolean raw value to append to \p array_obj.
921 @returns One of #bt_value_status values.
923 @prenotnull{array_obj}
924 @pre \p array_obj is an array value object.
926 @postrefcountsame{array_obj}
928 @sa bt_value_array_append(): Appends a value object to a given
931 extern enum bt_value_status
bt_value_array_append_bool(
932 struct bt_value
*array_obj
, bool val
);
935 @brief Appends the integer raw value \p val to the array value object
938 This is a convenience function which creates the underlying integer
939 value object before appending it.
941 @param[in] array_obj Array value object in which to append \p val.
942 @param[in] val Integer raw value to append to \p array_obj.
943 @returns One of #bt_value_status values.
945 @prenotnull{array_obj}
946 @pre \p array_obj is an array value object.
948 @postrefcountsame{array_obj}
950 @sa bt_value_array_append(): Appends a value object to a given
953 extern enum bt_value_status
bt_value_array_append_integer(
954 struct bt_value
*array_obj
, int64_t val
);
957 @brief Appends the floating point number raw value \p val to the array
958 value object \p array_obj.
960 This is a convenience function which creates the underlying floating
961 point number value object before appending it.
963 @param[in] array_obj Array value object in which to append \p val.
964 @param[in] val Floating point number raw value to append
966 @returns One of #bt_value_status values.
968 @prenotnull{array_obj}
969 @pre \p array_obj is an array value object.
971 @postrefcountsame{array_obj}
973 @sa bt_value_array_append(): Appends a value object to a given
976 extern enum bt_value_status
bt_value_array_append_float(
977 struct bt_value
*array_obj
, double val
);
980 @brief Appends the string raw value \p val to the array value object
983 This is a convenience function which creates the underlying string value
984 object before appending it.
986 On success, \p val is copied.
988 @param[in] array_obj Array value object in which to append \p val.
989 @param[in] val String raw value to append to \p array_obj
991 @returns One of #bt_value_status values.
993 @prenotnull{array_obj}
994 @pre \p array_obj is an array value object.
997 @postrefcountsame{array_obj}
999 @sa bt_value_array_append(): Appends a value object to a given
1002 extern enum bt_value_status
bt_value_array_append_string(
1003 struct bt_value
*array_obj
, const char *val
);
1006 @brief Appends an empty array value object to the array value object
1009 This is a convenience function which creates the underlying array value
1010 object before appending it.
1012 @param[in] array_obj Array value object in which to append an
1013 empty array value object
1014 @returns One of #bt_value_status values.
1016 @prenotnull{array_obj}
1017 @pre \p array_obj is an array value object.
1019 @postrefcountsame{array_obj}
1021 @sa bt_value_array_append(): Appends a value object to a given
1024 extern enum bt_value_status
bt_value_array_append_empty_array(
1025 struct bt_value
*array_obj
);
1028 @brief Appends an empty map value object to the array value object
1031 This is a convenience function which creates the underlying map value
1032 object before appending it.
1034 @param[in] array_obj Array value object in which to append an empty
1036 @returns One of #bt_value_status values.
1038 @prenotnull{array_obj}
1039 @pre \p array_obj is an array value object.
1041 @postrefcountsame{array_obj}
1043 @sa bt_value_array_append(): Appends a value object to a given
1046 extern enum bt_value_status
bt_value_array_append_empty_map(
1047 struct bt_value
*array_obj
);
1050 @brief Replaces the value object contained in the array value object
1051 \p array_obj at the index \p index by \p element_obj.
1053 @param[in] array_obj Array value object in which to replace
1055 @param[in] index Index of value object to replace in
1057 @param[in] element_obj New value object at position \p index of
1059 @returns One of #bt_value_status values.
1061 @prenotnull{array_obj}
1062 @prenotnull{element_obj}
1063 @pre \p array_obj is an array value object.
1064 @pre \p index is lesser than the size of \p array_obj.
1066 @post <strong>On success, if the replaced value object is not
1067 \ref bt_value_null</strong>, its reference count is decremented.
1068 @post <strong>On success, if \p element_obj is not
1069 \ref bt_value_null</strong>, its reference count is incremented.
1070 @postrefcountsame{array_obj}
1072 extern enum bt_value_status
bt_value_array_set(struct bt_value
*array_obj
,
1073 size_t index
, struct bt_value
*element_obj
);
1078 @name Map value object functions
1083 @brief Creates an empty map value object.
1085 @returns Created map value object on success, or \c NULL on error.
1087 @postsuccessrefcountret1
1089 extern struct bt_value
*bt_value_map_create(void);
1092 @brief Returns the size of the map value object \p map_obj, that is, the
1093 number of entries contained in \p map_obj.
1095 @param[in] map_obj Map value object of which to get the size.
1096 @returns Number of entries contained in \p map_obj if the
1097 return value is 0 (empty) or a positive value,
1098 or one of #bt_value_status negative values
1101 @prenotnull{map_obj}
1102 @pre \p map_obj is a map value object.
1103 @postrefcountsame{map_obj}
1105 @sa bt_value_map_is_empty(): Checks whether or not a given map value
1108 extern int bt_value_map_size(const struct bt_value
*map_obj
);
1111 @brief Checks whether or not the map value object \p map_obj is empty.
1113 @param[in] map_obj Map value object to check.
1114 @returns \c true if \p map_obj is empty.
1116 @prenotnull{map_obj}
1117 @pre \p map_obj is a map value object.
1118 @postrefcountsame{map_obj}
1120 @sa bt_value_map_size(): Returns the size of a given map value object.
1122 extern bool bt_value_map_is_empty(const struct bt_value
*map_obj
);
1125 @brief Returns the value object associated with the key \p key within
1126 the map value object \p map_obj.
1128 @param[in] map_obj Map value object of which to get an entry.
1129 @param[in] key Key of the value object to get.
1130 @returns Value object associated with the key \p key
1131 on success, or \c NULL on error.
1133 @prenotnull{map_obj}
1135 @pre \p map_obj is a map value object.
1136 @postrefcountsame{map_obj}
1138 @post <strong>On success, if the returned value object is not
1139 \ref bt_value_null</strong>, its reference count is incremented.
1141 extern struct bt_value
*bt_value_map_get(const struct bt_value
*map_obj
,
1145 @brief User function type to use with bt_value_map_foreach().
1147 \p object is a <em>weak reference</em>: you \em must pass it to bt_get()
1148 if you need your own reference.
1150 This function \em must return \c true to continue the map value object
1151 traversal, or \c false to break it.
1153 @param[in] key Key of map entry.
1154 @param[in] object Value object of map entry (weak reference).
1155 @param[in] data User data.
1156 @returns \c true to continue the loop, or \c false to break it.
1160 @post The reference count of \p object is not lesser than what it is
1161 when the function is called.
1163 typedef bool (* bt_value_map_foreach_cb
)(const char *key
,
1164 struct bt_value
*object
, void *data
);
1167 @brief Calls a provided user function \p cb for each value object of the
1168 map value object \p map_obj.
1170 The value object passed to the user function is a <b>weak reference</b>:
1171 you \em must pass it to bt_get() if you need your own reference.
1173 The key passed to the user function is only valid in the scope of
1174 this user function call.
1176 The user function \em must return \c true to continue the traversal of
1177 \p map_obj, or \c false to break it.
1179 @param[in] map_obj Map value object on which to iterate.
1180 @param[in] cb User function to call back.
1181 @param[in] data User data passed to the user function.
1182 @returns One of #bt_value_status values. More
1183 specifically, #BT_VALUE_STATUS_CANCELLED is
1184 returned if the loop was cancelled by the user
1187 @prenotnull{map_obj}
1189 @pre \p map_obj is a map value object.
1190 @postrefcountsame{map_obj}
1192 extern enum bt_value_status
bt_value_map_foreach(
1193 const struct bt_value
*map_obj
, bt_value_map_foreach_cb cb
,
1197 @brief Returns whether or not the map value object \p map_obj contains
1198 an entry mapped to the key \p key.
1200 @param[in] map_obj Map value object to check.
1201 @param[in] key Key to check.
1202 @returns \c true if \p map_obj has an entry mapped to the
1203 key \p key, or \c false if it does not or
1206 @prenotnull{map_obj}
1208 @pre \p map_obj is a map value object.
1209 @postrefcountsame{map_obj}
1211 extern bool bt_value_map_has_key(const struct bt_value
*map_obj
,
1215 @brief Inserts the value object \p element_obj mapped to the key
1216 \p key into the map value object \p map_obj.
1218 If a value object is already mapped to \p key in \p map_obj, the
1219 associated value object is first put, and then replaced by
1222 On success, \p key is copied.
1224 @param[in] map_obj Map value object in which to insert
1226 @param[in] key Key (copied on success) to which the
1227 value object to insert is mapped.
1228 @param[in] element_obj Value object to insert, mapped to the
1230 @returns One of #bt_value_status values.
1232 @prenotnull{map_obj}
1234 @prenotnull{element_obj}
1235 @pre \p map_obj is a map value object.
1237 @post <strong>On success, if \p element_obj is not
1238 \ref bt_value_null</strong>, its reference count is incremented.
1239 @postrefcountsame{map_obj}
1241 @sa bt_value_map_insert_bool(): Inserts a boolean raw value into a
1242 given map value object.
1243 @sa bt_value_map_insert_integer(): Inserts an integer raw value into
1244 a given map value object.
1245 @sa bt_value_map_insert_float(): Inserts a floating point number raw
1246 value into a given map value object.
1247 @sa bt_value_map_insert_string(): Inserts a string raw value into a
1248 given map value object.
1249 @sa bt_value_map_insert_empty_array(): Inserts an empty array value
1250 object into a given map value object.
1251 @sa bt_value_map_insert_empty_map(): Inserts an empty map value
1252 object into a given map value object.
1254 extern enum bt_value_status
bt_value_map_insert(
1255 struct bt_value
*map_obj
, const char *key
,
1256 struct bt_value
*element_obj
);
1259 @brief Inserts the boolean raw value \p val mapped to the key \p key
1260 into the map value object \p map_obj.
1262 This is a convenience function which creates the underlying boolean
1263 value object before inserting it.
1265 On success, \p key is copied.
1267 @param[in] map_obj Map value object in which to insert \p val.
1268 @param[in] key Key (copied on success) to which the boolean
1269 value object to insert is mapped.
1270 @param[in] val Boolean raw value to insert, mapped to
1272 @returns One of #bt_value_status values.
1274 @prenotnull{map_obj}
1276 @pre \p map_obj is a map value object.
1278 @postrefcountsame{map_obj}
1280 @sa bt_value_map_insert(): Inserts a value object into a given map
1283 extern enum bt_value_status
bt_value_map_insert_bool(
1284 struct bt_value
*map_obj
, const char *key
, bool val
);
1287 @brief Inserts the integer raw value \p val mapped to the key \p key
1288 into the map value object \p map_obj.
1290 This is a convenience function which creates the underlying integer
1291 value object before inserting it.
1293 On success, \p key is copied.
1295 @param[in] map_obj Map value object in which to insert \p val.
1296 @param[in] key Key (copied on success) to which the integer
1297 value object to insert is mapped.
1298 @param[in] val Integer raw value to insert, mapped to
1300 @returns One of #bt_value_status values.
1302 @prenotnull{map_obj}
1304 @pre \p map_obj is a map value object.
1306 @postrefcountsame{map_obj}
1308 @sa bt_value_map_insert(): Inserts a value object into a given map
1311 extern enum bt_value_status
bt_value_map_insert_integer(
1312 struct bt_value
*map_obj
, const char *key
, int64_t val
);
1315 @brief Inserts the floating point number raw value \p val mapped to
1316 the key \p key into the map value object \p map_obj.
1318 This is a convenience function which creates the underlying floating
1319 point number value object before inserting it.
1321 On success, \p key is copied.
1323 @param[in] map_obj Map value object in which to insert \p val.
1324 @param[in] key Key (copied on success) to which the floating
1325 point number value object to insert is mapped.
1326 @param[in] val Floating point number raw value to insert,
1327 mapped to the key \p key.
1328 @returns One of #bt_value_status values.
1330 @prenotnull{map_obj}
1332 @pre \p map_obj is a map value object.
1334 @postrefcountsame{map_obj}
1336 @sa bt_value_map_insert(): Inserts a value object into a given map
1339 extern enum bt_value_status
bt_value_map_insert_float(
1340 struct bt_value
*map_obj
, const char *key
, double val
);
1343 @brief Inserts the string raw value \p val mapped to the key \p key
1344 into the map value object \p map_obj.
1346 This is a convenience function which creates the underlying string value
1347 object before inserting it.
1349 On success, \p val and \p key are copied.
1351 @param[in] map_obj Map value object in which to insert \p val.
1352 @param[in] key Key (copied on success) to which the string
1353 value object to insert is mapped.
1354 @param[in] val String raw value to insert (copied on success),
1355 mapped to the key \p key.
1356 @returns One of #bt_value_status values.
1358 @prenotnull{map_obj}
1361 @pre \p map_obj is a map value object.
1363 @postrefcountsame{map_obj}
1365 @sa bt_value_map_insert(): Inserts a value object into a given map
1368 extern enum bt_value_status
bt_value_map_insert_string(
1369 struct bt_value
*map_obj
, const char *key
, const char *val
);
1372 @brief Inserts an empty array value object mapped to the key \p key
1373 into the map value object \p map_obj.
1375 This is a convenience function which creates the underlying array value
1376 object before inserting it.
1378 On success, \p key is copied.
1380 @param[in] map_obj Map value object in which to insert an empty
1382 @param[in] key Key (copied on success) to which the empty array
1383 value object to insert is mapped.
1384 @returns One of #bt_value_status values.
1386 @prenotnull{map_obj}
1388 @pre \p map_obj is a map value object.
1390 @postrefcountsame{map_obj}
1392 @sa bt_value_map_insert(): Inserts a value object into a given map
1395 extern enum bt_value_status
bt_value_map_insert_empty_array(
1396 struct bt_value
*map_obj
, const char *key
);
1399 @brief Inserts an empty map value object mapped to the key \p key into
1400 the map value object \p map_obj.
1402 This is a convenience function which creates the underlying map value
1403 object before inserting it.
1405 On success, \p key is copied.
1407 @param[in] map_obj Map value object in which to insert an empty
1409 @param[in] key Key (copied on success) to which the empty map
1410 value object to insert is mapped.
1411 @returns One of #bt_value_status values.
1413 @prenotnull{map_obj}
1415 @pre \p map_obj is a map value object.
1417 @postrefcountsame{map_obj}
1419 @sa bt_value_map_insert(): Inserts a value object into a given map
1422 extern enum bt_value_status
bt_value_map_insert_empty_map(
1423 struct bt_value
*map_obj
, const char *key
);
1426 @brief Creates a copy of the base map value object \p base_map_obj
1427 superficially extended with the entries of the extension map
1428 value object \p extension_map_obj.
1430 This function creates a superficial extension of \p base_map_obj with
1431 \p extension_map_obj by adding new entries to it and replacing the
1432 ones that share the keys in the extension object. The extension is
1433 \em superficial because it does not merge internal array and map
1436 For example, consider the following \p base_map_obj (JSON representation):
1443 "return": [5, 6, null]
1447 and the following \p extension_map_obj (JSON representation):
1457 The extended object is (JSON representation):
1469 @param[in] base_map_obj Base map value object with initial
1471 @param[in] extension_map_obj Extension map value object containing
1472 the entries to add to or replace in
1474 @returns Created extended map value object, or
1477 @prenotnull{base_map_obj}
1478 @prenotnull{extension_map_obj}
1479 @pre \p base_map_obj is a map value object.
1480 @pre \p extension_map_obj is a map value object.
1481 @postrefcountsame{base_map_obj}
1482 @postrefcountsame{extension_map_obj}
1483 @postsuccessrefcountret1
1485 extern struct bt_value
*bt_value_map_extend(struct bt_value
*base_map_obj
,
1486 struct bt_value
*extension_map_obj
);
1496 #endif /* _BABELTRACE_VALUES_H */