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.
157 struct bt_value
*bt_value_null
;
160 * User function type for bt_value_map_foreach().
162 * \p object is a \em weak reference; you must pass it to
163 * bt_get() to get your own reference.
165 * Return \c true to continue the loop, or \c false to break it.
167 * @param key Key of map entry
168 * @param object Value object of map entry (weak reference)
169 * @param data User data
170 * @returns \c true to continue the loop
172 typedef bool (* bt_value_map_foreach_cb
)(const char *key
,
173 struct bt_value
*object
, void *data
);
176 * Recursively freezes the value object \p object.
178 * A frozen value object cannot be modified; it is considered immutable.
179 * Reference counting still works on a frozen value object though: you
180 * may pass a frozen value object to bt_get() and bt_put().
182 * @param object Value object to freeze
183 * @returns One of #bt_value_status values; if \p object
184 * is already frozen, though, #BT_VALUE_STATUS_OK
185 * is returned anyway (i.e. this function never
186 * returns #BT_VALUE_STATUS_FROZEN)
188 * @see bt_value_is_frozen()
191 enum bt_value_status
bt_value_freeze(struct bt_value
*object
);
194 * Checks whether \p object is frozen or not.
196 * @param object Value object to check
197 * @returns \c true if \p object is frozen
199 * @see bt_value_freeze()
202 bool bt_value_is_frozen(const struct bt_value
*object
);
205 * Returns the type of \p object.
207 * @param object Value object of which to get the type
208 * @returns Value object's type, or #BT_VALUE_TYPE_UNKNOWN
211 * @see #bt_value_type (value object types)
212 * @see bt_value_is_null()
213 * @see bt_value_is_bool()
214 * @see bt_value_is_integer()
215 * @see bt_value_is_float()
216 * @see bt_value_is_string()
217 * @see bt_value_is_array()
218 * @see bt_value_is_map()
221 enum bt_value_type
bt_value_get_type(const struct bt_value
*object
);
224 * Checks whether \p object is a null value object. The only valid null
225 * value object is \ref bt_value_null.
227 * @param object Value object to check
228 * @returns \c true if \p object is a null value object
230 * @see bt_value_get_type()
233 bool bt_value_is_null(const struct bt_value
*object
)
235 return bt_value_get_type(object
) == BT_VALUE_TYPE_NULL
;
239 * Checks whether \p object is a boolean value object.
241 * @param object Value object to check
242 * @returns \c true if \p object is a boolean value object
244 * @see bt_value_get_type()
247 bool bt_value_is_bool(const struct bt_value
*object
)
249 return bt_value_get_type(object
) == BT_VALUE_TYPE_BOOL
;
253 * Checks whether \p object is an integer value object.
255 * @param object Value object to check
256 * @returns \c true if \p object is an integer value object
258 * @see bt_value_get_type()
261 bool bt_value_is_integer(const struct bt_value
*object
)
263 return bt_value_get_type(object
) == BT_VALUE_TYPE_INTEGER
;
267 * Checks whether \p object is a floating point number value object.
269 * @param object Value object to check
270 * @returns \c true if \p object is a floating point
271 * number value object
273 * @see bt_value_get_type()
276 bool bt_value_is_float(const struct bt_value
*object
)
278 return bt_value_get_type(object
) == BT_VALUE_TYPE_FLOAT
;
282 * Checks whether \p object is a string value object.
284 * @param object Value object to check
285 * @returns \c true if \p object is a string value object
287 * @see bt_value_get_type()
290 bool bt_value_is_string(const struct bt_value
*object
)
292 return bt_value_get_type(object
) == BT_VALUE_TYPE_STRING
;
296 * Checks whether \p object is an array value object.
298 * @param object Value object to check
299 * @returns \c true if \p object is an array value object
301 * @see bt_value_get_type()
304 bool bt_value_is_array(const struct bt_value
*object
)
306 return bt_value_get_type(object
) == BT_VALUE_TYPE_ARRAY
;
310 * Checks whether \p object is a map value object.
312 * @param object Value object to check
313 * @returns \c true if \p object is a map value object
315 * @see bt_value_get_type()
318 bool bt_value_is_map(const struct bt_value
*object
)
320 return bt_value_get_type(object
) == BT_VALUE_TYPE_MAP
;
324 * Creates a boolean value object. The created boolean value object's
325 * initial raw value is \c false.
327 * The created value object's reference count is set to 1.
329 * @returns Created value object on success, or \c NULL on error
331 * @see bt_value_bool_create_init() (creates an initialized
332 * boolean value object)
335 struct bt_value
*bt_value_bool_create(void);
338 * Creates a boolean value object with its initial raw value set to
341 * The created value object's reference count is set to 1.
343 * @param val Initial raw value
344 * @returns Created value object on success, or \c NULL on error
347 struct bt_value
*bt_value_bool_create_init(bool val
);
350 * Creates an integer value object. The created integer value object's
351 * initial raw value is 0.
353 * The created value object's reference count is set to 1.
355 * @returns Created value object on success, or \c NULL on error
357 * @see bt_value_integer_create_init() (creates an initialized
358 * integer value object)
361 struct bt_value
*bt_value_integer_create(void);
364 * Creates an integer value object with its initial raw value set to
367 * The created value object's reference count is set to 1.
369 * @param val Initial raw value
370 * @returns Created value object on success, or \c NULL on error
373 struct bt_value
*bt_value_integer_create_init(int64_t val
);
376 * Creates a floating point number value object. The created floating
377 * point number value object's initial raw value is 0.
379 * The created value object's reference count is set to 1.
381 * @returns Created value object on success, or \c NULL on error
383 * @see bt_value_float_create_init() (creates an initialized floating
384 * point number value object)
387 struct bt_value
*bt_value_float_create(void);
390 * Creates a floating point number value object with its initial raw
391 * value set to \p val.
393 * The created value object's reference count is set to 1.
395 * @param val Initial raw value
396 * @returns Created value object on success, or \c NULL on error
399 struct bt_value
*bt_value_float_create_init(double val
);
402 * Creates a string value object. The string value object is initially
405 * The created value object's reference count is set to 1.
407 * @returns Created value object on success, or \c NULL on error
409 * @see bt_value_string_create_init() (creates an initialized
410 * string value object)
413 struct bt_value
*bt_value_string_create(void);
416 * Creates a string value object with its initial raw value set to
419 * On success, \p val is \em copied.
421 * The created value object's reference count is set to 1.
423 * @param val Initial raw value (copied on success)
424 * @returns Created value object on success, or \c NULL on error
427 struct bt_value
*bt_value_string_create_init(const char *val
);
430 * Creates an empty array value object.
432 * The created value object's reference count is set to 1.
434 * @returns Created value object on success, or \c NULL on error
437 struct bt_value
*bt_value_array_create(void);
440 * Creates an empty map value object.
442 * The created value object's reference count is set to 1.
444 * @returns Created value object on success, or \c NULL on error
447 struct bt_value
*bt_value_map_create(void);
450 * Gets the boolean raw value of the boolean value object \p bool_obj.
452 * @param bool_obj Boolean value object
453 * @param val Returned boolean raw value
454 * @returns One of #bt_value_status values
456 * @see bt_value_bool_set()
459 enum bt_value_status
bt_value_bool_get(
460 const struct bt_value
*bool_obj
, bool *val
);
463 * Sets the boolean raw value of the boolean value object \p bool_obj
466 * @param bool_obj Boolean value object
467 * @param val New boolean raw value
468 * @returns One of #bt_value_status values
470 * @see bt_value_bool_get()
473 enum bt_value_status
bt_value_bool_set(struct bt_value
*bool_obj
,
477 * Gets the integer raw value of the integer value object
480 * @param integer_obj Integer value object
481 * @param val Returned integer raw value
482 * @returns One of #bt_value_status values
484 * @see bt_value_integer_set()
487 enum bt_value_status
bt_value_integer_get(
488 const struct bt_value
*integer_obj
, int64_t *val
);
491 * Sets the integer raw value of the integer value object \p integer_obj
494 * @param integer_obj Integer value object
495 * @param val New integer raw value
496 * @returns One of #bt_value_status values
498 * @see bt_value_integer_get()
501 enum bt_value_status
bt_value_integer_set(
502 struct bt_value
*integer_obj
, int64_t val
);
505 * Gets the floating point number raw value of the floating point number
506 * value object \p float_obj.
508 * @param float_obj Floating point number value object
509 * @param val Returned floating point number raw value
510 * @returns One of #bt_value_status values
512 * @see bt_value_float_set()
515 enum bt_value_status
bt_value_float_get(
516 const struct bt_value
*float_obj
, double *val
);
519 * Sets the floating point number raw value of the floating point number
520 * value object \p float_obj to \p val.
522 * @param float_obj Floating point number value object
523 * @param val New floating point number raw value
524 * @returns One of #bt_value_status values
526 * @see bt_value_float_get()
529 enum bt_value_status
bt_value_float_set(
530 struct bt_value
*float_obj
, double val
);
533 * Gets the string raw value of the string value object \p string_obj.
534 * The returned string is valid as long as this value object exists and
535 * is not modified. The ownership of the returned string is \em not
536 * transferred to the caller.
538 * @param string_obj String value object
539 * @param val Returned string raw value
540 * @returns One of #bt_value_status values
542 * @see bt_value_string_set()
545 enum bt_value_status
bt_value_string_get(
546 const struct bt_value
*string_obj
, const char **val
);
549 * Sets the string raw value of the string value object \p string_obj to
552 * On success, \p val is \em copied.
554 * @param string_obj String value object
555 * @param val New string raw value (copied on successf)
556 * @returns One of #bt_value_status values
558 * @see bt_value_string_get()
561 enum bt_value_status
bt_value_string_set(struct bt_value
*string_obj
,
565 * Gets the size of the array value object \p array_obj, that is, the
566 * number of value objects contained in \p array_obj.
568 * @param array_obj Array value object
569 * @returns Array size if the return value is 0 (empty) or a
570 * positive value, or one of
571 * #bt_value_status negative values otherwise
573 * @see bt_value_array_is_empty()
576 int bt_value_array_size(const struct bt_value
*array_obj
);
579 * Returns \c true if the array value object \p array_obj is empty.
581 * @param array_obj Array value object
582 * @returns \c true if \p array_obj is empty
584 * @see bt_value_array_size()
587 bool bt_value_array_is_empty(const struct bt_value
*array_obj
);
590 * Gets the value object of the array value object \p array_obj at the
593 * The returned value object's reference count is incremented, unless
594 * it's a null value object.
596 * @param array_obj Array value object
597 * @param index Index of value object to get
598 * @returns Value object at index \p index on
599 * success, or \c NULL on error
602 struct bt_value
*bt_value_array_get(const struct bt_value
*array_obj
,
606 * Appends the value object \p element_obj to the array value
607 * object \p array_obj.
609 * The appended value object's reference count is incremented, unless
610 * it's a null object.
612 * @param array_obj Array value object
613 * @param element_obj Value object to append
614 * @returns One of #bt_value_status values
616 * @see bt_value_array_append_bool()
617 * @see bt_value_array_append_integer()
618 * @see bt_value_array_append_float()
619 * @see bt_value_array_append_string()
620 * @see bt_value_array_append_empty_array()
621 * @see bt_value_array_append_empty_map()
624 enum bt_value_status
bt_value_array_append(struct bt_value
*array_obj
,
625 struct bt_value
*element_obj
);
628 * Appends the boolean raw value \p val to the array value object
629 * \p array_obj. This is a convenience function which creates the
630 * underlying boolean value object before appending it.
632 * The created boolean value object's reference count is set to 1.
634 * @param array_obj Array value object
635 * @param val Boolean raw value to append
636 * @returns One of #bt_value_status values
638 * @see bt_value_array_append()
641 enum bt_value_status
bt_value_array_append_bool(
642 struct bt_value
*array_obj
, bool val
);
645 * Appends the integer raw value \p val to the array value object
646 * \p array_obj. This is a convenience function which creates the
647 * underlying integer value object before appending it.
649 * The created integer value object's reference count is set to 1.
651 * @param array_obj Array value object
652 * @param val Integer raw value to append
653 * @returns One of #bt_value_status values
655 * @see bt_value_array_append()
658 enum bt_value_status
bt_value_array_append_integer(
659 struct bt_value
*array_obj
, int64_t val
);
662 * Appends the floating point number raw value \p val to the array value
663 * object \p array_obj. This is a convenience function which creates the
664 * underlying floating point number value object before appending it.
666 * The created floating point number value object's reference count is
669 * @param array_obj Array value object
670 * @param val Floating point number raw value to append
671 * @returns One of #bt_value_status values
673 * @see bt_value_array_append()
676 enum bt_value_status
bt_value_array_append_float(
677 struct bt_value
*array_obj
, double val
);
680 * Appends the string raw value \p val to the array value object
681 * \p array_obj. This is a convenience function which creates the
682 * underlying string value object before appending it.
684 * On success, \p val is \em copied.
686 * The created string value object's reference count is set to 1.
688 * @param array_obj Array value object
689 * @param val String raw value to append (copied on success)
690 * @returns One of #bt_value_status values
692 * @see bt_value_array_append()
695 enum bt_value_status
bt_value_array_append_string(
696 struct bt_value
*array_obj
, const char *val
);
699 * Appends an empty array value object to the array value object
700 * \p array_obj. This is a convenience function which creates the
701 * underlying array value object before appending it.
703 * The created array value object's reference count is set to 1.
705 * @param array_obj Array value object
706 * @returns One of #bt_value_status values
708 * @see bt_value_array_append()
711 enum bt_value_status
bt_value_array_append_empty_array(
712 struct bt_value
*array_obj
);
715 * Appends an empty map value object to the array value object
716 * \p array_obj. This is a convenience function which creates the
717 * underlying map value object before appending it.
719 * The created map value object's reference count is set to 1.
721 * @param array_obj Array value object
722 * @returns One of #bt_value_status values
724 * @see bt_value_array_append()
727 enum bt_value_status
bt_value_array_append_empty_map(
728 struct bt_value
*array_obj
);
731 * Replaces the value object at index \p index of the array
732 * value object \p array_obj by \p element_obj.
734 * The replaced value object's reference count is decremented, unless
735 * it's a null value object. The reference count of \p element_obj is
736 * incremented, unless it's a null value object.
738 * @param array_obj Array value object
739 * @param index Index of value object to replace
740 * @param element_obj New value object at position \p index of
742 * @returns One of #bt_value_status values
745 enum bt_value_status
bt_value_array_set(struct bt_value
*array_obj
,
746 size_t index
, struct bt_value
*element_obj
);
749 * Gets the size of a map value object, that is, the number of entries
750 * contained in a map value object.
752 * @param map_obj Map value object
753 * @returns Map size if the return value is 0 (empty) or a
754 * positive value, or one of
755 * #bt_value_status negative values otherwise
757 * @see bt_value_map_is_empty()
760 int bt_value_map_size(const struct bt_value
*map_obj
);
763 * Returns \c true if the map value object \p map_obj is empty.
765 * @param map_obj Map value object
766 * @returns \c true if \p map_obj is empty
768 * @see bt_value_map_size()
771 bool bt_value_map_is_empty(const struct bt_value
*map_obj
);
774 * Gets the value object associated with the key \p key within the
775 * map value object \p map_obj.
777 * The returned value object's reference count is incremented, unless
778 * it's a null value object.
780 * @param map_obj Map value object
781 * @param key Key of the value object to get
782 * @returns Value object associated with the key \p key
783 * on success, or \c NULL on error
786 struct bt_value
*bt_value_map_get(const struct bt_value
*map_obj
,
790 * Calls a provided user function \p cb for each value object of the map
791 * value object \p map_obj.
793 * The value object passed to the user function is a
794 * <b>weak reference</b>: you must call bt_get() on it to obtain your own
797 * The key passed to the user function is only valid in the scope of
798 * this user function call.
800 * The user function must return \c true to continue the loop, or
801 * \c false to break it.
803 * @param map_obj Map value object
804 * @param cb User function to call back
805 * @param data User data passed to the user function
806 * @returns One of #bt_value_status values; more
807 * specifically, #BT_VALUE_STATUS_CANCELLED is
808 * returned if the loop was cancelled by the user
812 enum bt_value_status
bt_value_map_foreach(
813 const struct bt_value
*map_obj
, bt_value_map_foreach_cb cb
,
817 * Returns whether or not the map value object \p map_obj contains the
820 * @param map_obj Map value object
821 * @param key Key to check
822 * @returns \c true if \p map_obj contains the key \p key,
823 * or \c false if it doesn't have \p key or
827 bool bt_value_map_has_key(const struct bt_value
*map_obj
,
831 * Inserts the value object \p element_obj associated with the key
832 * \p key into the map value object \p map_obj. If \p key exists in
833 * \p map_obj, the associated value object is first put, and then
834 * replaced by \p element_obj.
836 * On success, \p key is \em copied.
838 * The inserted value object's reference count is incremented, unless
839 * it's a null value object.
841 * @param map_obj Map value object
842 * @param key Key (copied on success) of value object to insert
843 * @param element_obj Value object to insert, associated with the
845 * @returns One of #bt_value_status values
847 * @see bt_value_map_insert_bool()
848 * @see bt_value_map_insert_integer()
849 * @see bt_value_map_insert_float()
850 * @see bt_value_map_insert_string()
851 * @see bt_value_map_insert_empty_array()
852 * @see bt_value_map_insert_empty_map()
855 enum bt_value_status
bt_value_map_insert(
856 struct bt_value
*map_obj
, const char *key
,
857 struct bt_value
*element_obj
);
860 * Inserts the boolean raw value \p val associated with the key \p key
861 * into the map value object \p map_obj. This is a convenience function
862 * which creates the underlying boolean value object before
865 * On success, \p key is \em copied.
867 * The created boolean value object's reference count is set to 1.
869 * @param map_obj Map value object
870 * @param key Key (copied on success) of boolean value object
872 * @param val Boolean raw value to insert, associated with
874 * @returns One of #bt_value_status values
876 * @see bt_value_map_insert()
879 enum bt_value_status
bt_value_map_insert_bool(
880 struct bt_value
*map_obj
, const char *key
, bool val
);
883 * Inserts the integer raw value \p val associated with the key \p key
884 * into the map value object \p map_obj. This is a convenience function
885 * which creates the underlying integer value object before inserting it.
887 * On success, \p key is \em copied.
889 * The created integer value object's reference count is set to 1.
891 * @param map_obj Map value object
892 * @param key Key (copied on success) of integer value object
894 * @param val Integer raw value to insert, associated with
896 * @returns One of #bt_value_status values
898 * @see bt_value_map_insert()
901 enum bt_value_status
bt_value_map_insert_integer(
902 struct bt_value
*map_obj
, const char *key
, int64_t val
);
905 * Inserts the floating point number raw value \p val associated with
906 * the key \p key into the map value object \p map_obj. This is a
907 * convenience function which creates the underlying floating point
908 * number value object before inserting it.
910 * On success, \p key is \em copied.
912 * The created floating point number value object's reference count is
915 * @param map_obj Map value object
916 * @param key Key (copied on success) of floating point number
917 * value object to insert
918 * @param val Floating point number raw value to insert,
919 * associated with the key \p key
920 * @returns One of #bt_value_status values
922 * @see bt_value_map_insert()
925 enum bt_value_status
bt_value_map_insert_float(
926 struct bt_value
*map_obj
, const char *key
, double val
);
929 * Inserts the string raw value \p val associated with the key \p key
930 * into the map value object \p map_obj. This is a convenience function
931 * which creates the underlying string value object before inserting it.
933 * On success, \p val and \p key are \em copied.
935 * The created string value object's reference count is set to 1.
937 * @param map_obj Map value object
938 * @param key Key (copied on success) of string value object
940 * @param val String raw value to insert (copied on success),
941 * associated with the key \p key
942 * @returns One of #bt_value_status values
944 * @see bt_value_map_insert()
947 enum bt_value_status
bt_value_map_insert_string(
948 struct bt_value
*map_obj
, const char *key
, const char *val
);
951 * Inserts an empty array value object associated with the key \p key
952 * into the map value object \p map_obj. This is a convenience function
953 * which creates the underlying array value object before inserting it.
955 * On success, \p key is \em copied.
957 * The created array value object's reference count is set to 1.
959 * @param map_obj Map value object
960 * @param key Key (copied on success) of empty array value
962 * @returns One of #bt_value_status values
964 * @see bt_value_map_insert()
967 enum bt_value_status
bt_value_map_insert_empty_array(
968 struct bt_value
*map_obj
, const char *key
);
971 * Inserts an empty map value object associated with the key \p key into
972 * the map value object \p map_obj. This is a convenience function which
973 * creates the underlying map value object before inserting it.
975 * On success, \p key is \em copied.
977 * The created map value object's reference count is set to 1.
979 * @param map_obj Map value object
980 * @param key Key (copied on success) of empty map value
982 * @returns One of #bt_value_status values
984 * @see bt_value_map_insert()
987 enum bt_value_status
bt_value_map_insert_empty_map(
988 struct bt_value
*map_obj
, const char *key
);
991 * Creates a deep copy of the value object \p object.
993 * The created value object's reference count is set to 1, unless
994 * \p object is a null value object.
996 * Copying a frozen value object is allowed: the resulting copy is
999 * @param object Value object to copy
1000 * @returns Deep copy of \p object on success, or \c NULL
1004 struct bt_value
*bt_value_copy(const struct bt_value
*object
);
1007 * Compares the value objects \p object_a and \p object_b and returns
1008 * \c true if they have the same \em content (raw values).
1010 * @param object_a Value object A
1011 * @param object_b Value object B
1012 * @returns \c true if \p object_a and \p object_b have the
1013 * same content, or \c false if they differ or on
1017 bool bt_value_compare(const struct bt_value
*object_a
,
1018 const struct bt_value
*object_b
);
1024 #endif /* _BABELTRACE_VALUES_H */