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>
87 /** Unknown value object, used as an error code. */
88 BT_VALUE_TYPE_UNKNOWN
= -1,
90 /** Null value object. */
91 BT_VALUE_TYPE_NULL
= 0,
93 /** Boolean value object (holds \c true or \c false). */
94 BT_VALUE_TYPE_BOOL
= 1,
96 /** Integer value object (holds a signed 64-bit integer raw value). */
97 BT_VALUE_TYPE_INTEGER
= 2,
99 /** Floating point number value object (holds a \c double raw value). */
100 BT_VALUE_TYPE_FLOAT
= 3,
102 /** String value object. */
103 BT_VALUE_TYPE_STRING
= 4,
105 /** Array value object. */
106 BT_VALUE_TYPE_ARRAY
= 5,
108 /** Map value object. */
109 BT_VALUE_TYPE_MAP
= 6,
115 enum bt_value_status
{
116 /** Value object cannot be altered because it's frozen. */
117 BT_VALUE_STATUS_FROZEN
= -4,
119 /** Operation cancelled. */
120 BT_VALUE_STATUS_CANCELLED
= -3,
122 /** Invalid arguments. */
123 /* -22 for compatibility with -EINVAL */
124 BT_VALUE_STATUS_INVAL
= -22,
126 /** General error. */
127 BT_VALUE_STATUS_ERROR
= -1,
129 /** Okay, no error. */
130 BT_VALUE_STATUS_OK
= 0,
139 * The null value object singleton.
141 * Use this everytime you need a null value object.
143 * The null value object singleton has no reference count; there's only
144 * one. You may directly compare any value object to the null value
145 * object singleton to find out if it's a null value object, or
146 * otherwise use bt_value_is_null().
148 * The null value object singleton is always frozen (see
149 * bt_value_freeze() and bt_value_is_frozen()).
151 * Functions of this API return this when the value object is actually a
152 * null value object (of type #BT_VALUE_TYPE_NULL), whereas \c NULL
153 * means an error of some sort.
155 extern struct bt_value
*bt_value_null
;
158 * User function type for bt_value_map_foreach().
160 * \p object is a \em weak reference; you must pass it to
161 * bt_get() to get your own reference.
163 * Return \c true to continue the loop, or \c false to break it.
165 * @param key Key of map entry
166 * @param object Value object of map entry (weak reference)
167 * @param data User data
168 * @returns \c true to continue the loop
170 typedef bool (* bt_value_map_foreach_cb
)(const char *key
,
171 struct bt_value
*object
, void *data
);
174 * Recursively freezes the value object \p object.
176 * A frozen value object cannot be modified; it is considered immutable.
177 * Reference counting still works on a frozen value object though: you
178 * may pass a frozen value object to bt_get() and bt_put().
180 * @param object Value object to freeze
181 * @returns One of #bt_value_status values; if \p object
182 * is already frozen, though, #BT_VALUE_STATUS_OK
183 * is returned anyway (i.e. this function never
184 * returns #BT_VALUE_STATUS_FROZEN)
186 * @see bt_value_is_frozen()
188 extern enum bt_value_status
bt_value_freeze(struct bt_value
*object
);
191 * Checks whether \p object is frozen or not.
193 * @param object Value object to check
194 * @returns \c true if \p object is frozen
196 * @see bt_value_freeze()
198 extern bool bt_value_is_frozen(const struct bt_value
*object
);
201 * Returns the type of \p object.
203 * @param object Value object of which to get the type
204 * @returns Value object's type, or #BT_VALUE_TYPE_UNKNOWN
207 * @see #bt_value_type (value object types)
208 * @see bt_value_is_null()
209 * @see bt_value_is_bool()
210 * @see bt_value_is_integer()
211 * @see bt_value_is_float()
212 * @see bt_value_is_string()
213 * @see bt_value_is_array()
214 * @see bt_value_is_map()
216 extern enum bt_value_type
bt_value_get_type(const struct bt_value
*object
);
219 * Checks whether \p object is a null value object. The only valid null
220 * value object is \ref bt_value_null.
222 * @param object Value object to check
223 * @returns \c true if \p object is a null value object
225 * @see bt_value_get_type()
228 bool bt_value_is_null(const struct bt_value
*object
)
230 return bt_value_get_type(object
) == BT_VALUE_TYPE_NULL
;
234 * Checks whether \p object is a boolean value object.
236 * @param object Value object to check
237 * @returns \c true if \p object is a boolean value object
239 * @see bt_value_get_type()
242 bool bt_value_is_bool(const struct bt_value
*object
)
244 return bt_value_get_type(object
) == BT_VALUE_TYPE_BOOL
;
248 * Checks whether \p object is an integer value object.
250 * @param object Value object to check
251 * @returns \c true if \p object is an integer value object
253 * @see bt_value_get_type()
256 bool bt_value_is_integer(const struct bt_value
*object
)
258 return bt_value_get_type(object
) == BT_VALUE_TYPE_INTEGER
;
262 * Checks whether \p object is a floating point number value object.
264 * @param object Value object to check
265 * @returns \c true if \p object is a floating point
266 * number value object
268 * @see bt_value_get_type()
271 bool bt_value_is_float(const struct bt_value
*object
)
273 return bt_value_get_type(object
) == BT_VALUE_TYPE_FLOAT
;
277 * Checks whether \p object is a string value object.
279 * @param object Value object to check
280 * @returns \c true if \p object is a string value object
282 * @see bt_value_get_type()
285 bool bt_value_is_string(const struct bt_value
*object
)
287 return bt_value_get_type(object
) == BT_VALUE_TYPE_STRING
;
291 * Checks whether \p object is an array value object.
293 * @param object Value object to check
294 * @returns \c true if \p object is an array value object
296 * @see bt_value_get_type()
299 bool bt_value_is_array(const struct bt_value
*object
)
301 return bt_value_get_type(object
) == BT_VALUE_TYPE_ARRAY
;
305 * Checks whether \p object is a map value object.
307 * @param object Value object to check
308 * @returns \c true if \p object is a map value object
310 * @see bt_value_get_type()
313 bool bt_value_is_map(const struct bt_value
*object
)
315 return bt_value_get_type(object
) == BT_VALUE_TYPE_MAP
;
319 * Creates a boolean value object. The created boolean value object's
320 * initial raw value is \c false.
322 * The created value object's reference count is set to 1.
324 * @returns Created value object on success, or \c NULL on error
326 * @see bt_value_bool_create_init() (creates an initialized
327 * boolean value object)
329 extern struct bt_value
*bt_value_bool_create(void);
332 * Creates a boolean value object with its initial raw value set to
335 * The created value object's reference count is set to 1.
337 * @param val Initial raw value
338 * @returns Created value object on success, or \c NULL on error
340 extern struct bt_value
*bt_value_bool_create_init(bool val
);
343 * Creates an integer value object. The created integer value object's
344 * initial raw value is 0.
346 * The created value object's reference count is set to 1.
348 * @returns Created value object on success, or \c NULL on error
350 * @see bt_value_integer_create_init() (creates an initialized
351 * integer value object)
353 extern struct bt_value
*bt_value_integer_create(void);
356 * Creates an integer value object with its initial raw value set to
359 * The created value object's reference count is set to 1.
361 * @param val Initial raw value
362 * @returns Created value object on success, or \c NULL on error
364 extern struct bt_value
*bt_value_integer_create_init(int64_t val
);
367 * Creates a floating point number value object. The created floating
368 * point number value object's initial raw value is 0.
370 * The created value object's reference count is set to 1.
372 * @returns Created value object on success, or \c NULL on error
374 * @see bt_value_float_create_init() (creates an initialized floating
375 * point number value object)
377 extern struct bt_value
*bt_value_float_create(void);
380 * Creates a floating point number value object with its initial raw
381 * value set to \p val.
383 * The created value object's reference count is set to 1.
385 * @param val Initial raw value
386 * @returns Created value object on success, or \c NULL on error
388 extern struct bt_value
*bt_value_float_create_init(double val
);
391 * Creates a string value object. The string value object is initially
394 * The created value object's reference count is set to 1.
396 * @returns Created value object on success, or \c NULL on error
398 * @see bt_value_string_create_init() (creates an initialized
399 * string value object)
401 extern struct bt_value
*bt_value_string_create(void);
404 * Creates a string value object with its initial raw value set to
407 * On success, \p val is \em copied.
409 * The created value object's reference count is set to 1.
411 * @param val Initial raw value (copied on success)
412 * @returns Created value object on success, or \c NULL on error
414 extern struct bt_value
*bt_value_string_create_init(const char *val
);
417 * Creates an empty array value object.
419 * The created value object's reference count is set to 1.
421 * @returns Created value object on success, or \c NULL on error
423 extern struct bt_value
*bt_value_array_create(void);
426 * Creates an empty map value object.
428 * The created value object's reference count is set to 1.
430 * @returns Created value object on success, or \c NULL on error
432 extern struct bt_value
*bt_value_map_create(void);
435 * Gets the boolean raw value of the boolean value object \p bool_obj.
437 * @param bool_obj Boolean value object
438 * @param val Returned boolean raw value
439 * @returns One of #bt_value_status values
441 * @see bt_value_bool_set()
443 extern enum bt_value_status
bt_value_bool_get(
444 const struct bt_value
*bool_obj
, bool *val
);
447 * Sets the boolean raw value of the boolean value object \p bool_obj
450 * @param bool_obj Boolean value object
451 * @param val New boolean raw value
452 * @returns One of #bt_value_status values
454 * @see bt_value_bool_get()
456 extern enum bt_value_status
bt_value_bool_set(struct bt_value
*bool_obj
,
460 * Gets the integer raw value of the integer value object
463 * @param integer_obj Integer value object
464 * @param val Returned integer raw value
465 * @returns One of #bt_value_status values
467 * @see bt_value_integer_set()
469 extern enum bt_value_status
bt_value_integer_get(
470 const struct bt_value
*integer_obj
, int64_t *val
);
473 * Sets the integer raw value of the integer value object \p integer_obj
476 * @param integer_obj Integer value object
477 * @param val New integer raw value
478 * @returns One of #bt_value_status values
480 * @see bt_value_integer_get()
482 extern enum bt_value_status
bt_value_integer_set(
483 struct bt_value
*integer_obj
, int64_t val
);
486 * Gets the floating point number raw value of the floating point number
487 * value object \p float_obj.
489 * @param float_obj Floating point number value object
490 * @param val Returned floating point number raw value
491 * @returns One of #bt_value_status values
493 * @see bt_value_float_set()
495 extern enum bt_value_status
bt_value_float_get(
496 const struct bt_value
*float_obj
, double *val
);
499 * Sets the floating point number raw value of the floating point number
500 * value object \p float_obj to \p val.
502 * @param float_obj Floating point number value object
503 * @param val New floating point number raw value
504 * @returns One of #bt_value_status values
506 * @see bt_value_float_get()
508 extern enum bt_value_status
bt_value_float_set(
509 struct bt_value
*float_obj
, double val
);
512 * Gets the string raw value of the string value object \p string_obj.
513 * The returned string is valid as long as this value object exists and
514 * is not modified. The ownership of the returned string is \em not
515 * transferred to the caller.
517 * @param string_obj String value object
518 * @param val Returned string raw value
519 * @returns One of #bt_value_status values
521 * @see bt_value_string_set()
523 extern enum bt_value_status
bt_value_string_get(
524 const struct bt_value
*string_obj
, const char **val
);
527 * Sets the string raw value of the string value object \p string_obj to
530 * On success, \p val is \em copied.
532 * @param string_obj String value object
533 * @param val New string raw value (copied on successf)
534 * @returns One of #bt_value_status values
536 * @see bt_value_string_get()
538 extern enum bt_value_status
bt_value_string_set(struct bt_value
*string_obj
,
542 * Gets the size of the array value object \p array_obj, that is, the
543 * number of value objects contained in \p array_obj.
545 * @param array_obj Array value object
546 * @returns Array size if the return value is 0 (empty) or a
547 * positive value, or one of
548 * #bt_value_status negative values otherwise
550 * @see bt_value_array_is_empty()
552 extern int bt_value_array_size(const struct bt_value
*array_obj
);
555 * Returns \c true if the array value object \p array_obj is empty.
557 * @param array_obj Array value object
558 * @returns \c true if \p array_obj is empty
560 * @see bt_value_array_size()
562 extern bool bt_value_array_is_empty(const struct bt_value
*array_obj
);
565 * Gets the value object of the array value object \p array_obj at the
568 * The returned value object's reference count is incremented, unless
569 * it's a null value object.
571 * @param array_obj Array value object
572 * @param index Index of value object to get
573 * @returns Value object at index \p index on
574 * success, or \c NULL on error
576 extern struct bt_value
*bt_value_array_get(const struct bt_value
*array_obj
,
580 * Appends the value object \p element_obj to the array value
581 * object \p array_obj.
583 * The appended value object's reference count is incremented, unless
584 * it's a null object.
586 * @param array_obj Array value object
587 * @param element_obj Value object to append
588 * @returns One of #bt_value_status values
590 * @see bt_value_array_append_bool()
591 * @see bt_value_array_append_integer()
592 * @see bt_value_array_append_float()
593 * @see bt_value_array_append_string()
594 * @see bt_value_array_append_empty_array()
595 * @see bt_value_array_append_empty_map()
597 extern enum bt_value_status
bt_value_array_append(struct bt_value
*array_obj
,
598 struct bt_value
*element_obj
);
601 * Appends the boolean raw value \p val to the array value object
602 * \p array_obj. This is a convenience function which creates the
603 * underlying boolean value object before appending it.
605 * The created boolean value object's reference count is set to 1.
607 * @param array_obj Array value object
608 * @param val Boolean raw value to append
609 * @returns One of #bt_value_status values
611 * @see bt_value_array_append()
613 extern enum bt_value_status
bt_value_array_append_bool(
614 struct bt_value
*array_obj
, bool val
);
617 * Appends the integer raw value \p val to the array value object
618 * \p array_obj. This is a convenience function which creates the
619 * underlying integer value object before appending it.
621 * The created integer value object's reference count is set to 1.
623 * @param array_obj Array value object
624 * @param val Integer raw value to append
625 * @returns One of #bt_value_status values
627 * @see bt_value_array_append()
629 extern enum bt_value_status
bt_value_array_append_integer(
630 struct bt_value
*array_obj
, int64_t val
);
633 * Appends the floating point number raw value \p val to the array value
634 * object \p array_obj. This is a convenience function which creates the
635 * underlying floating point number value object before appending it.
637 * The created floating point number value object's reference count is
640 * @param array_obj Array value object
641 * @param val Floating point number raw value to append
642 * @returns One of #bt_value_status values
644 * @see bt_value_array_append()
646 extern enum bt_value_status
bt_value_array_append_float(
647 struct bt_value
*array_obj
, double val
);
650 * Appends the string raw value \p val to the array value object
651 * \p array_obj. This is a convenience function which creates the
652 * underlying string value object before appending it.
654 * On success, \p val is \em copied.
656 * The created string value object's reference count is set to 1.
658 * @param array_obj Array value object
659 * @param val String raw value to append (copied on success)
660 * @returns One of #bt_value_status values
662 * @see bt_value_array_append()
664 extern enum bt_value_status
bt_value_array_append_string(
665 struct bt_value
*array_obj
, const char *val
);
668 * Appends an empty array value object to the array value object
669 * \p array_obj. This is a convenience function which creates the
670 * underlying array value object before appending it.
672 * The created array value object's reference count is set to 1.
674 * @param array_obj Array value object
675 * @returns One of #bt_value_status values
677 * @see bt_value_array_append()
679 extern enum bt_value_status
bt_value_array_append_empty_array(
680 struct bt_value
*array_obj
);
683 * Appends an empty map value object to the array value object
684 * \p array_obj. This is a convenience function which creates the
685 * underlying map value object before appending it.
687 * The created map value object's reference count is set to 1.
689 * @param array_obj Array value object
690 * @returns One of #bt_value_status values
692 * @see bt_value_array_append()
694 extern enum bt_value_status
bt_value_array_append_empty_map(
695 struct bt_value
*array_obj
);
698 * Replaces the value object at index \p index of the array
699 * value object \p array_obj by \p element_obj.
701 * The replaced value object's reference count is decremented, unless
702 * it's a null value object. The reference count of \p element_obj is
703 * incremented, unless it's a null value object.
705 * @param array_obj Array value object
706 * @param index Index of value object to replace
707 * @param element_obj New value object at position \p index of
709 * @returns One of #bt_value_status values
711 extern enum bt_value_status
bt_value_array_set(struct bt_value
*array_obj
,
712 size_t index
, struct bt_value
*element_obj
);
715 * Gets the size of a map value object, that is, the number of entries
716 * contained in a map value object.
718 * @param map_obj Map value object
719 * @returns Map size if the return value is 0 (empty) or a
720 * positive value, or one of
721 * #bt_value_status negative values otherwise
723 * @see bt_value_map_is_empty()
725 extern int bt_value_map_size(const struct bt_value
*map_obj
);
728 * Returns \c true if the map value object \p map_obj is empty.
730 * @param map_obj Map value object
731 * @returns \c true if \p map_obj is empty
733 * @see bt_value_map_size()
735 extern bool bt_value_map_is_empty(const struct bt_value
*map_obj
);
738 * Gets the value object associated with the key \p key within the
739 * map value object \p map_obj.
741 * The returned value object's reference count is incremented, unless
742 * it's a null value object.
744 * @param map_obj Map value object
745 * @param key Key of the value object to get
746 * @returns Value object associated with the key \p key
747 * on success, or \c NULL on error
749 extern struct bt_value
*bt_value_map_get(const struct bt_value
*map_obj
,
753 * Calls a provided user function \p cb for each value object of the map
754 * value object \p map_obj.
756 * The value object passed to the user function is a
757 * <b>weak reference</b>: you must call bt_get() on it to obtain your own
760 * The key passed to the user function is only valid in the scope of
761 * this user function call.
763 * The user function must return \c true to continue the loop, or
764 * \c false to break it.
766 * @param map_obj Map value object
767 * @param cb User function to call back
768 * @param data User data passed to the user function
769 * @returns One of #bt_value_status values; more
770 * specifically, #BT_VALUE_STATUS_CANCELLED is
771 * returned if the loop was cancelled by the user
774 extern enum bt_value_status
bt_value_map_foreach(
775 const struct bt_value
*map_obj
, bt_value_map_foreach_cb cb
,
779 * Returns whether or not the map value object \p map_obj contains the
782 * @param map_obj Map value object
783 * @param key Key to check
784 * @returns \c true if \p map_obj contains the key \p key,
785 * or \c false if it doesn't have \p key or
788 extern bool bt_value_map_has_key(const struct bt_value
*map_obj
,
792 * Inserts the value object \p element_obj associated with the key
793 * \p key into the map value object \p map_obj. If \p key exists in
794 * \p map_obj, the associated value object is first put, and then
795 * replaced by \p element_obj.
797 * On success, \p key is \em copied.
799 * The inserted value object's reference count is incremented, unless
800 * it's a null value object.
802 * @param map_obj Map value object
803 * @param key Key (copied on success) of value object to insert
804 * @param element_obj Value object to insert, associated with the
806 * @returns One of #bt_value_status values
808 * @see bt_value_map_insert_bool()
809 * @see bt_value_map_insert_integer()
810 * @see bt_value_map_insert_float()
811 * @see bt_value_map_insert_string()
812 * @see bt_value_map_insert_empty_array()
813 * @see bt_value_map_insert_empty_map()
815 extern enum bt_value_status
bt_value_map_insert(
816 struct bt_value
*map_obj
, const char *key
,
817 struct bt_value
*element_obj
);
820 * Inserts the boolean raw value \p val associated with the key \p key
821 * into the map value object \p map_obj. This is a convenience function
822 * which creates the underlying boolean value object before
825 * On success, \p key is \em copied.
827 * The created boolean value object's reference count is set to 1.
829 * @param map_obj Map value object
830 * @param key Key (copied on success) of boolean value object
832 * @param val Boolean raw value to insert, associated with
834 * @returns One of #bt_value_status values
836 * @see bt_value_map_insert()
838 extern enum bt_value_status
bt_value_map_insert_bool(
839 struct bt_value
*map_obj
, const char *key
, bool val
);
842 * Inserts the integer raw value \p val associated with the key \p key
843 * into the map value object \p map_obj. This is a convenience function
844 * which creates the underlying integer value object before inserting it.
846 * On success, \p key is \em copied.
848 * The created integer value object's reference count is set to 1.
850 * @param map_obj Map value object
851 * @param key Key (copied on success) of integer value object
853 * @param val Integer raw value to insert, associated with
855 * @returns One of #bt_value_status values
857 * @see bt_value_map_insert()
859 extern enum bt_value_status
bt_value_map_insert_integer(
860 struct bt_value
*map_obj
, const char *key
, int64_t val
);
863 * Inserts the floating point number raw value \p val associated with
864 * the key \p key into the map value object \p map_obj. This is a
865 * convenience function which creates the underlying floating point
866 * number value object before inserting it.
868 * On success, \p key is \em copied.
870 * The created floating point number value object's reference count is
873 * @param map_obj Map value object
874 * @param key Key (copied on success) of floating point number
875 * value object to insert
876 * @param val Floating point number raw value to insert,
877 * associated with the key \p key
878 * @returns One of #bt_value_status values
880 * @see bt_value_map_insert()
882 extern enum bt_value_status
bt_value_map_insert_float(
883 struct bt_value
*map_obj
, const char *key
, double val
);
886 * Inserts the string raw value \p val associated with the key \p key
887 * into the map value object \p map_obj. This is a convenience function
888 * which creates the underlying string value object before inserting it.
890 * On success, \p val and \p key are \em copied.
892 * The created string value object's reference count is set to 1.
894 * @param map_obj Map value object
895 * @param key Key (copied on success) of string value object
897 * @param val String raw value to insert (copied on success),
898 * associated with the key \p key
899 * @returns One of #bt_value_status values
901 * @see bt_value_map_insert()
903 extern enum bt_value_status
bt_value_map_insert_string(
904 struct bt_value
*map_obj
, const char *key
, const char *val
);
907 * Inserts an empty array value object associated with the key \p key
908 * into the map value object \p map_obj. This is a convenience function
909 * which creates the underlying array value object before inserting it.
911 * On success, \p key is \em copied.
913 * The created array value object's reference count is set to 1.
915 * @param map_obj Map value object
916 * @param key Key (copied on success) of empty array value
918 * @returns One of #bt_value_status values
920 * @see bt_value_map_insert()
922 extern enum bt_value_status
bt_value_map_insert_empty_array(
923 struct bt_value
*map_obj
, const char *key
);
926 * Inserts an empty map value object associated with the key \p key into
927 * the map value object \p map_obj. This is a convenience function which
928 * creates the underlying map value object before inserting it.
930 * On success, \p key is \em copied.
932 * The created map value object's reference count is set to 1.
934 * @param map_obj Map value object
935 * @param key Key (copied on success) of empty map value
937 * @returns One of #bt_value_status values
939 * @see bt_value_map_insert()
941 extern enum bt_value_status
bt_value_map_insert_empty_map(
942 struct bt_value
*map_obj
, const char *key
);
945 * Creates a deep copy of the value object \p object.
947 * The created value object's reference count is set to 1, unless
948 * \p object is a null value object.
950 * Copying a frozen value object is allowed: the resulting copy is
953 * @param object Value object to copy
954 * @returns Deep copy of \p object on success, or \c NULL
957 extern struct bt_value
*bt_value_copy(const struct bt_value
*object
);
960 * Compares the value objects \p object_a and \p object_b and returns
961 * \c true if they have the same \em content (raw values).
963 * @param object_a Value object A
964 * @param object_b Value object B
965 * @returns \c true if \p object_a and \p object_b have the
966 * same content, or \c false if they differ or on
969 extern bool bt_value_compare(const struct bt_value
*object_a
,
970 const struct bt_value
*object_b
);
976 #endif /* _BABELTRACE_VALUES_H */