1 #ifndef _BABELTRACE_VALUES_H
2 #define _BABELTRACE_VALUES_H
5 * Babeltrace - Value objects
7 * Copyright (c) 2015 EfficiOS Inc. and Linux Foundation
8 * Copyright (c) 2015 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
31 * @brief Value objects
33 * This is a set of value objects. The following functions allow you
34 * to create, modify, and destroy:
36 * - \link bt_value_null null value objects\endlink
37 * - \link bt_value_bool_create() boolean value objects\endlink
38 * - \link bt_value_integer_create() integer value objects\endlink
39 * - \link bt_value_float_create() floating point number
40 * value objects\endlink
41 * - \link bt_value_string_create() string value objects\endlink
42 * - \link bt_value_array_create() array value objects\endlink,
43 * containing zero or more value objects
44 * - \link bt_value_map_create() map value objects\endlink, mapping
45 * string keys to value objects
47 * All the value object types above, except for null values (which
48 * always point to the same \link bt_value_null singleton\endlink), have
49 * a reference count property. Once a value object is created, its
50 * reference count is set to 1. When \link bt_value_array_append()
51 * appending a value to an array value object\endlink, or
52 * \link bt_value_map_insert() inserting a value object into a map
53 * value object\endlink, its reference count is incremented, as well as
54 * when getting a value object back from those structures. The
55 * bt_get() and bt_put() functions are to be used to handle reference counting
56 * Once you are done with a value object, pass it to bt_put().
58 * Most functions of this API return a status code, one of the values in
61 * You can create a deep copy of any value object using the
62 * bt_value_copy() function. You can compare two given value objects
63 * using bt_value_compare().
65 * Any value object may be frozen using bt_value_freeze(). You may get
66 * the raw value of a frozen value object, but you cannot modify it.
67 * Reference counting still works on frozen value objects. You may also
68 * copy and compare frozen value objects.
70 * @author Philippe Proulx <pproulx@efficios.com>
77 #include <babeltrace/ref.h>
78 #include <babeltrace/babeltrace-internal.h>
88 /** Unknown value object, used as an error code. */
89 BT_VALUE_TYPE_UNKNOWN
= -1,
91 /** Null value object. */
92 BT_VALUE_TYPE_NULL
= 0,
94 /** Boolean value object (holds \c true or \c false). */
95 BT_VALUE_TYPE_BOOL
= 1,
97 /** Integer value object (holds a signed 64-bit integer raw value). */
98 BT_VALUE_TYPE_INTEGER
= 2,
100 /** Floating point number value object (holds a \c double raw value). */
101 BT_VALUE_TYPE_FLOAT
= 3,
103 /** String value object. */
104 BT_VALUE_TYPE_STRING
= 4,
106 /** Array value object. */
107 BT_VALUE_TYPE_ARRAY
= 5,
109 /** Map value object. */
110 BT_VALUE_TYPE_MAP
= 6,
116 enum bt_value_status
{
117 /** Value object cannot be altered because it's frozen. */
118 BT_VALUE_STATUS_FROZEN
= -4,
120 /** Operation cancelled. */
121 BT_VALUE_STATUS_CANCELLED
= -3,
123 /** Invalid arguments. */
124 /* -22 for compatibility with -EINVAL */
125 BT_VALUE_STATUS_INVAL
= -22,
127 /** General error. */
128 BT_VALUE_STATUS_ERROR
= -1,
130 /** Okay, no error. */
131 BT_VALUE_STATUS_OK
= 0,
140 * The null value object singleton.
142 * Use this everytime you need a null value object.
144 * The null value object singleton has no reference count; there's only
145 * one. You may directly compare any value object to the null value
146 * object singleton to find out if it's a null value object, or
147 * otherwise use bt_value_is_null().
149 * The null value object singleton is always frozen (see
150 * bt_value_freeze() and bt_value_is_frozen()).
152 * Functions of this API return this when the value object is actually a
153 * null value object (of type #BT_VALUE_TYPE_NULL), whereas \c NULL
154 * means an error of some sort.
156 extern struct bt_value
*bt_value_null
;
159 * User function type for bt_value_map_foreach().
161 * \p object is a \em weak reference; you must pass it to
162 * bt_get() to get your own reference.
164 * Return \c true to continue the loop, or \c false to break it.
166 * @param key Key of map entry
167 * @param object Value object of map entry (weak reference)
168 * @param data User data
169 * @returns \c true to continue the loop
171 typedef bool (* bt_value_map_foreach_cb
)(const char *key
,
172 struct bt_value
*object
, void *data
);
175 * Recursively freezes the value object \p object.
177 * A frozen value object cannot be modified; it is considered immutable.
178 * Reference counting still works on a frozen value object though: you
179 * may pass a frozen value object to bt_get() and bt_put().
181 * @param object Value object to freeze
182 * @returns One of #bt_value_status values; if \p object
183 * is already frozen, though, #BT_VALUE_STATUS_OK
184 * is returned anyway (i.e. this function never
185 * returns #BT_VALUE_STATUS_FROZEN)
187 * @see bt_value_is_frozen()
190 enum bt_value_status
bt_value_freeze(struct bt_value
*object
);
193 * Checks whether \p object is frozen or not.
195 * @param object Value object to check
196 * @returns \c true if \p object is frozen
198 * @see bt_value_freeze()
201 bool bt_value_is_frozen(const struct bt_value
*object
);
204 * Returns the type of \p object.
206 * @param object Value object of which to get the type
207 * @returns Value object's type, or #BT_VALUE_TYPE_UNKNOWN
210 * @see #bt_value_type (value object types)
211 * @see bt_value_is_null()
212 * @see bt_value_is_bool()
213 * @see bt_value_is_integer()
214 * @see bt_value_is_float()
215 * @see bt_value_is_string()
216 * @see bt_value_is_array()
217 * @see bt_value_is_map()
220 enum bt_value_type
bt_value_get_type(const struct bt_value
*object
);
223 * Checks whether \p object is a null value object. The only valid null
224 * value object is \ref bt_value_null.
226 * @param object Value object to check
227 * @returns \c true if \p object is a null value object
229 * @see bt_value_get_type()
232 bool bt_value_is_null(const struct bt_value
*object
)
234 return bt_value_get_type(object
) == BT_VALUE_TYPE_NULL
;
238 * Checks whether \p object is a boolean value object.
240 * @param object Value object to check
241 * @returns \c true if \p object is a boolean value object
243 * @see bt_value_get_type()
246 bool bt_value_is_bool(const struct bt_value
*object
)
248 return bt_value_get_type(object
) == BT_VALUE_TYPE_BOOL
;
252 * Checks whether \p object is an integer value object.
254 * @param object Value object to check
255 * @returns \c true if \p object is an integer value object
257 * @see bt_value_get_type()
260 bool bt_value_is_integer(const struct bt_value
*object
)
262 return bt_value_get_type(object
) == BT_VALUE_TYPE_INTEGER
;
266 * Checks whether \p object is a floating point number value object.
268 * @param object Value object to check
269 * @returns \c true if \p object is a floating point
270 * number value object
272 * @see bt_value_get_type()
275 bool bt_value_is_float(const struct bt_value
*object
)
277 return bt_value_get_type(object
) == BT_VALUE_TYPE_FLOAT
;
281 * Checks whether \p object is a string value object.
283 * @param object Value object to check
284 * @returns \c true if \p object is a string value object
286 * @see bt_value_get_type()
289 bool bt_value_is_string(const struct bt_value
*object
)
291 return bt_value_get_type(object
) == BT_VALUE_TYPE_STRING
;
295 * Checks whether \p object is an array value object.
297 * @param object Value object to check
298 * @returns \c true if \p object is an array value object
300 * @see bt_value_get_type()
303 bool bt_value_is_array(const struct bt_value
*object
)
305 return bt_value_get_type(object
) == BT_VALUE_TYPE_ARRAY
;
309 * Checks whether \p object is a map value object.
311 * @param object Value object to check
312 * @returns \c true if \p object is a map value object
314 * @see bt_value_get_type()
317 bool bt_value_is_map(const struct bt_value
*object
)
319 return bt_value_get_type(object
) == BT_VALUE_TYPE_MAP
;
323 * Creates a boolean value object. The created boolean value object's
324 * initial raw value is \c false.
326 * The created value object's reference count is set to 1.
328 * @returns Created value object on success, or \c NULL on error
330 * @see bt_value_bool_create_init() (creates an initialized
331 * boolean value object)
334 struct bt_value
*bt_value_bool_create(void);
337 * Creates a boolean value object with its initial raw value set to
340 * The created value object's reference count is set to 1.
342 * @param val Initial raw value
343 * @returns Created value object on success, or \c NULL on error
346 struct bt_value
*bt_value_bool_create_init(bool val
);
349 * Creates an integer value object. The created integer value object's
350 * initial raw value is 0.
352 * The created value object's reference count is set to 1.
354 * @returns Created value object on success, or \c NULL on error
356 * @see bt_value_integer_create_init() (creates an initialized
357 * integer value object)
360 struct bt_value
*bt_value_integer_create(void);
363 * Creates an integer value object with its initial raw value set to
366 * The created value object's reference count is set to 1.
368 * @param val Initial raw value
369 * @returns Created value object on success, or \c NULL on error
372 struct bt_value
*bt_value_integer_create_init(int64_t val
);
375 * Creates a floating point number value object. The created floating
376 * point number value object's initial raw value is 0.
378 * The created value object's reference count is set to 1.
380 * @returns Created value object on success, or \c NULL on error
382 * @see bt_value_float_create_init() (creates an initialized floating
383 * point number value object)
386 struct bt_value
*bt_value_float_create(void);
389 * Creates a floating point number value object with its initial raw
390 * value set to \p val.
392 * The created value object's reference count is set to 1.
394 * @param val Initial raw value
395 * @returns Created value object on success, or \c NULL on error
398 struct bt_value
*bt_value_float_create_init(double val
);
401 * Creates a string value object. The string value object is initially
404 * The created value object's reference count is set to 1.
406 * @returns Created value object on success, or \c NULL on error
408 * @see bt_value_string_create_init() (creates an initialized
409 * string value object)
412 struct bt_value
*bt_value_string_create(void);
415 * Creates a string value object with its initial raw value set to
418 * On success, \p val is \em copied.
420 * The created value object's reference count is set to 1.
422 * @param val Initial raw value (copied on success)
423 * @returns Created value object on success, or \c NULL on error
426 struct bt_value
*bt_value_string_create_init(const char *val
);
429 * Creates an empty array value object.
431 * The created value object's reference count is set to 1.
433 * @returns Created value object on success, or \c NULL on error
436 struct bt_value
*bt_value_array_create(void);
439 * Creates an empty map value object.
441 * The created value object's reference count is set to 1.
443 * @returns Created value object on success, or \c NULL on error
446 struct bt_value
*bt_value_map_create(void);
449 * Gets the boolean raw value of the boolean value object \p bool_obj.
451 * @param bool_obj Boolean value object
452 * @param val Returned boolean raw value
453 * @returns One of #bt_value_status values
455 * @see bt_value_bool_set()
458 enum bt_value_status
bt_value_bool_get(
459 const struct bt_value
*bool_obj
, bool *val
);
462 * Sets the boolean raw value of the boolean value object \p bool_obj
465 * @param bool_obj Boolean value object
466 * @param val New boolean raw value
467 * @returns One of #bt_value_status values
469 * @see bt_value_bool_get()
472 enum bt_value_status
bt_value_bool_set(struct bt_value
*bool_obj
,
476 * Gets the integer raw value of the integer value object
479 * @param integer_obj Integer value object
480 * @param val Returned integer raw value
481 * @returns One of #bt_value_status values
483 * @see bt_value_integer_set()
486 enum bt_value_status
bt_value_integer_get(
487 const struct bt_value
*integer_obj
, int64_t *val
);
490 * Sets the integer raw value of the integer value object \p integer_obj
493 * @param integer_obj Integer value object
494 * @param val New integer raw value
495 * @returns One of #bt_value_status values
497 * @see bt_value_integer_get()
500 enum bt_value_status
bt_value_integer_set(
501 struct bt_value
*integer_obj
, int64_t val
);
504 * Gets the floating point number raw value of the floating point number
505 * value object \p float_obj.
507 * @param float_obj Floating point number value object
508 * @param val Returned floating point number raw value
509 * @returns One of #bt_value_status values
511 * @see bt_value_float_set()
514 enum bt_value_status
bt_value_float_get(
515 const struct bt_value
*float_obj
, double *val
);
518 * Sets the floating point number raw value of the floating point number
519 * value object \p float_obj to \p val.
521 * @param float_obj Floating point number value object
522 * @param val New floating point number raw value
523 * @returns One of #bt_value_status values
525 * @see bt_value_float_get()
528 enum bt_value_status
bt_value_float_set(
529 struct bt_value
*float_obj
, double val
);
532 * Gets the string raw value of the string value object \p string_obj.
533 * The returned string is valid as long as this value object exists and
534 * is not modified. The ownership of the returned string is \em not
535 * transferred to the caller.
537 * @param string_obj String value object
538 * @param val Returned string raw value
539 * @returns One of #bt_value_status values
541 * @see bt_value_string_set()
544 enum bt_value_status
bt_value_string_get(
545 const struct bt_value
*string_obj
, const char **val
);
548 * Sets the string raw value of the string value object \p string_obj to
551 * On success, \p val is \em copied.
553 * @param string_obj String value object
554 * @param val New string raw value (copied on successf)
555 * @returns One of #bt_value_status values
557 * @see bt_value_string_get()
560 enum bt_value_status
bt_value_string_set(struct bt_value
*string_obj
,
564 * Gets the size of the array value object \p array_obj, that is, the
565 * number of value objects contained in \p array_obj.
567 * @param array_obj Array value object
568 * @returns Array size if the return value is 0 (empty) or a
569 * positive value, or one of
570 * #bt_value_status negative values otherwise
572 * @see bt_value_array_is_empty()
575 int bt_value_array_size(const struct bt_value
*array_obj
);
578 * Returns \c true if the array value object \p array_obj is empty.
580 * @param array_obj Array value object
581 * @returns \c true if \p array_obj is empty
583 * @see bt_value_array_size()
586 bool bt_value_array_is_empty(const struct bt_value
*array_obj
);
589 * Gets the value object of the array value object \p array_obj at the
592 * The returned value object's reference count is incremented, unless
593 * it's a null value object.
595 * @param array_obj Array value object
596 * @param index Index of value object to get
597 * @returns Value object at index \p index on
598 * success, or \c NULL on error
601 struct bt_value
*bt_value_array_get(const struct bt_value
*array_obj
,
605 * Appends the value object \p element_obj to the array value
606 * object \p array_obj.
608 * The appended value object's reference count is incremented, unless
609 * it's a null object.
611 * @param array_obj Array value object
612 * @param element_obj Value object to append
613 * @returns One of #bt_value_status values
615 * @see bt_value_array_append_bool()
616 * @see bt_value_array_append_integer()
617 * @see bt_value_array_append_float()
618 * @see bt_value_array_append_string()
619 * @see bt_value_array_append_empty_array()
620 * @see bt_value_array_append_empty_map()
623 enum bt_value_status
bt_value_array_append(struct bt_value
*array_obj
,
624 struct bt_value
*element_obj
);
627 * Appends the boolean raw value \p val to the array value object
628 * \p array_obj. This is a convenience function which creates the
629 * underlying boolean value object before appending it.
631 * The created boolean value object's reference count is set to 1.
633 * @param array_obj Array value object
634 * @param val Boolean raw value to append
635 * @returns One of #bt_value_status values
637 * @see bt_value_array_append()
640 enum bt_value_status
bt_value_array_append_bool(
641 struct bt_value
*array_obj
, bool val
);
644 * Appends the integer raw value \p val to the array value object
645 * \p array_obj. This is a convenience function which creates the
646 * underlying integer value object before appending it.
648 * The created integer value object's reference count is set to 1.
650 * @param array_obj Array value object
651 * @param val Integer raw value to append
652 * @returns One of #bt_value_status values
654 * @see bt_value_array_append()
657 enum bt_value_status
bt_value_array_append_integer(
658 struct bt_value
*array_obj
, int64_t val
);
661 * Appends the floating point number raw value \p val to the array value
662 * object \p array_obj. This is a convenience function which creates the
663 * underlying floating point number value object before appending it.
665 * The created floating point number value object's reference count is
668 * @param array_obj Array value object
669 * @param val Floating point number raw value to append
670 * @returns One of #bt_value_status values
672 * @see bt_value_array_append()
675 enum bt_value_status
bt_value_array_append_float(
676 struct bt_value
*array_obj
, double val
);
679 * Appends the string raw value \p val to the array value object
680 * \p array_obj. This is a convenience function which creates the
681 * underlying string value object before appending it.
683 * On success, \p val is \em copied.
685 * The created string value object's reference count is set to 1.
687 * @param array_obj Array value object
688 * @param val String raw value to append (copied on success)
689 * @returns One of #bt_value_status values
691 * @see bt_value_array_append()
694 enum bt_value_status
bt_value_array_append_string(
695 struct bt_value
*array_obj
, const char *val
);
698 * Appends an empty array value object to the array value object
699 * \p array_obj. This is a convenience function which creates the
700 * underlying array value object before appending it.
702 * The created array value object's reference count is set to 1.
704 * @param array_obj Array value object
705 * @returns One of #bt_value_status values
707 * @see bt_value_array_append()
710 enum bt_value_status
bt_value_array_append_empty_array(
711 struct bt_value
*array_obj
);
714 * Appends an empty map value object to the array value object
715 * \p array_obj. This is a convenience function which creates the
716 * underlying map value object before appending it.
718 * The created map value object's reference count is set to 1.
720 * @param array_obj Array value object
721 * @returns One of #bt_value_status values
723 * @see bt_value_array_append()
726 enum bt_value_status
bt_value_array_append_empty_map(
727 struct bt_value
*array_obj
);
730 * Replaces the value object at index \p index of the array
731 * value object \p array_obj by \p element_obj.
733 * The replaced value object's reference count is decremented, unless
734 * it's a null value object. The reference count of \p element_obj is
735 * incremented, unless it's a null value object.
737 * @param array_obj Array value object
738 * @param index Index of value object to replace
739 * @param element_obj New value object at position \p index of
741 * @returns One of #bt_value_status values
744 enum bt_value_status
bt_value_array_set(struct bt_value
*array_obj
,
745 size_t index
, struct bt_value
*element_obj
);
748 * Gets the size of a map value object, that is, the number of entries
749 * contained in a map value object.
751 * @param map_obj Map value object
752 * @returns Map size if the return value is 0 (empty) or a
753 * positive value, or one of
754 * #bt_value_status negative values otherwise
756 * @see bt_value_map_is_empty()
759 int bt_value_map_size(const struct bt_value
*map_obj
);
762 * Returns \c true if the map value object \p map_obj is empty.
764 * @param map_obj Map value object
765 * @returns \c true if \p map_obj is empty
767 * @see bt_value_map_size()
770 bool bt_value_map_is_empty(const struct bt_value
*map_obj
);
773 * Gets the value object associated with the key \p key within the
774 * map value object \p map_obj.
776 * The returned value object's reference count is incremented, unless
777 * it's a null value object.
779 * @param map_obj Map value object
780 * @param key Key of the value object to get
781 * @returns Value object associated with the key \p key
782 * on success, or \c NULL on error
785 struct bt_value
*bt_value_map_get(const struct bt_value
*map_obj
,
789 * Calls a provided user function \p cb for each value object of the map
790 * value object \p map_obj.
792 * The value object passed to the user function is a
793 * <b>weak reference</b>: you must call bt_get() on it to obtain your own
796 * The key passed to the user function is only valid in the scope of
797 * this user function call.
799 * The user function must return \c true to continue the loop, or
800 * \c false to break it.
802 * @param map_obj Map value object
803 * @param cb User function to call back
804 * @param data User data passed to the user function
805 * @returns One of #bt_value_status values; more
806 * specifically, #BT_VALUE_STATUS_CANCELLED is
807 * returned if the loop was cancelled by the user
811 enum bt_value_status
bt_value_map_foreach(
812 const struct bt_value
*map_obj
, bt_value_map_foreach_cb cb
,
816 * Returns whether or not the map value object \p map_obj contains the
819 * @param map_obj Map value object
820 * @param key Key to check
821 * @returns \c true if \p map_obj contains the key \p key,
822 * or \c false if it doesn't have \p key or
826 bool bt_value_map_has_key(const struct bt_value
*map_obj
,
830 * Inserts the value object \p element_obj associated with the key
831 * \p key into the map value object \p map_obj. If \p key exists in
832 * \p map_obj, the associated value object is first put, and then
833 * replaced by \p element_obj.
835 * On success, \p key is \em copied.
837 * The inserted value object's reference count is incremented, unless
838 * it's a null value object.
840 * @param map_obj Map value object
841 * @param key Key (copied on success) of value object to insert
842 * @param element_obj Value object to insert, associated with the
844 * @returns One of #bt_value_status values
846 * @see bt_value_map_insert_bool()
847 * @see bt_value_map_insert_integer()
848 * @see bt_value_map_insert_float()
849 * @see bt_value_map_insert_string()
850 * @see bt_value_map_insert_empty_array()
851 * @see bt_value_map_insert_empty_map()
854 enum bt_value_status
bt_value_map_insert(
855 struct bt_value
*map_obj
, const char *key
,
856 struct bt_value
*element_obj
);
859 * Inserts the boolean raw value \p val associated with the key \p key
860 * into the map value object \p map_obj. This is a convenience function
861 * which creates the underlying boolean value object before
864 * On success, \p key is \em copied.
866 * The created boolean value object's reference count is set to 1.
868 * @param map_obj Map value object
869 * @param key Key (copied on success) of boolean value object
871 * @param val Boolean raw value to insert, associated with
873 * @returns One of #bt_value_status values
875 * @see bt_value_map_insert()
878 enum bt_value_status
bt_value_map_insert_bool(
879 struct bt_value
*map_obj
, const char *key
, bool val
);
882 * Inserts the integer raw value \p val associated with the key \p key
883 * into the map value object \p map_obj. This is a convenience function
884 * which creates the underlying integer value object before inserting it.
886 * On success, \p key is \em copied.
888 * The created integer value object's reference count is set to 1.
890 * @param map_obj Map value object
891 * @param key Key (copied on success) of integer value object
893 * @param val Integer raw value to insert, associated with
895 * @returns One of #bt_value_status values
897 * @see bt_value_map_insert()
900 enum bt_value_status
bt_value_map_insert_integer(
901 struct bt_value
*map_obj
, const char *key
, int64_t val
);
904 * Inserts the floating point number raw value \p val associated with
905 * the key \p key into the map value object \p map_obj. This is a
906 * convenience function which creates the underlying floating point
907 * number value object before inserting it.
909 * On success, \p key is \em copied.
911 * The created floating point number value object's reference count is
914 * @param map_obj Map value object
915 * @param key Key (copied on success) of floating point number
916 * value object to insert
917 * @param val Floating point number raw value to insert,
918 * associated with the key \p key
919 * @returns One of #bt_value_status values
921 * @see bt_value_map_insert()
924 enum bt_value_status
bt_value_map_insert_float(
925 struct bt_value
*map_obj
, const char *key
, double val
);
928 * Inserts the string raw value \p val associated with the key \p key
929 * into the map value object \p map_obj. This is a convenience function
930 * which creates the underlying string value object before inserting it.
932 * On success, \p val and \p key are \em copied.
934 * The created string value object's reference count is set to 1.
936 * @param map_obj Map value object
937 * @param key Key (copied on success) of string value object
939 * @param val String raw value to insert (copied on success),
940 * associated with the key \p key
941 * @returns One of #bt_value_status values
943 * @see bt_value_map_insert()
946 enum bt_value_status
bt_value_map_insert_string(
947 struct bt_value
*map_obj
, const char *key
, const char *val
);
950 * Inserts an empty array value object associated with the key \p key
951 * into the map value object \p map_obj. This is a convenience function
952 * which creates the underlying array value object before inserting it.
954 * On success, \p key is \em copied.
956 * The created array value object's reference count is set to 1.
958 * @param map_obj Map value object
959 * @param key Key (copied on success) of empty array value
961 * @returns One of #bt_value_status values
963 * @see bt_value_map_insert()
966 enum bt_value_status
bt_value_map_insert_empty_array(
967 struct bt_value
*map_obj
, const char *key
);
970 * Inserts an empty map value object associated with the key \p key into
971 * the map value object \p map_obj. This is a convenience function which
972 * creates the underlying map value object before inserting it.
974 * On success, \p key is \em copied.
976 * The created map value object's reference count is set to 1.
978 * @param map_obj Map value object
979 * @param key Key (copied on success) of empty map value
981 * @returns One of #bt_value_status values
983 * @see bt_value_map_insert()
986 enum bt_value_status
bt_value_map_insert_empty_map(
987 struct bt_value
*map_obj
, const char *key
);
990 * Creates a deep copy of the value object \p object.
992 * The created value object's reference count is set to 1, unless
993 * \p object is a null value object.
995 * Copying a frozen value object is allowed: the resulting copy is
998 * @param object Value object to copy
999 * @returns Deep copy of \p object on success, or \c NULL
1003 struct bt_value
*bt_value_copy(const struct bt_value
*object
);
1006 * Compares the value objects \p object_a and \p object_b and returns
1007 * \c true if they have the same \em content (raw values).
1009 * @param object_a Value object A
1010 * @param object_b Value object B
1011 * @returns \c true if \p object_a and \p object_b have the
1012 * same content, or \c false if they differ or on
1016 bool bt_value_compare(const struct bt_value
*object_a
,
1017 const struct bt_value
*object_b
);
1023 #endif /* _BABELTRACE_VALUES_H */