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_value_get() and bt_value_put() functions exist to deal with
56 * reference counting. Once you are done with a value object, pass it to
59 * Most functions of this API return a status code, one of the values in
62 * You can create a deep copy of any value object using the
63 * bt_value_copy() function. You can compare two given value objects
64 * using bt_value_compare().
66 * Any value object may be frozen using bt_value_freeze(). You may get
67 * the raw value of a frozen value object, but you cannot modify it.
68 * Reference counting still works on frozen value objects. You may also
69 * copy and compare frozen value objects.
71 * @author Philippe Proulx <pproulx@efficios.com>
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_value_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 * Puts the value object \p _object (calls bt_value_put() on it), and
175 * resets the variable to \c NULL.
177 * This is something that is often done when putting a value object;
178 * resetting the variable to \c NULL makes sure it cannot be put a
181 * @param _object Value object to put
183 * @see BT_VALUE_MOVE() (moves a value object from one variable to the
184 * other without putting it)
186 #define BT_VALUE_PUT(_object) \
188 bt_value_put(_object); \
193 * Moves the value object referenced by the variable \p _src_object to
194 * the \p _dst_object variable, then resets \p _src_object to \c NULL.
196 * The value object's reference count is <b>not changed</b>. Resetting
197 * \p _src_object to \c NULL ensures the value object will not be put
198 * twice later; its ownership is indeed \em moved from the source
199 * variable to the destination variable.
201 * @param _src_object Source value object variable
202 * @param _dst_object Destination value object variable
204 #define BT_VALUE_MOVE(_dst_object, _src_object) \
206 (_dst_object) = (_src_object); \
207 (_src_object) = NULL; \
211 * Increments the reference count of \p object.
213 * @param object Value object of which to increment the reference count
215 * @see bt_value_put()
217 extern void bt_value_get(struct bt_value
*object
);
220 * Decrements the reference count of \p object, destroying it when this
223 * @param object Value object of which to decrement the reference count
225 * @see bt_value_get()
227 extern void bt_value_put(struct bt_value
*object
);
230 * Recursively freezes the value object \p object.
232 * A frozen value object cannot be modified; it is considered immutable.
233 * Reference counting still works on a frozen value object though: you
234 * may pass a frozen value object to bt_value_get() and bt_value_put().
236 * @param object Value object to freeze
237 * @returns One of #bt_value_status values; if \p object
238 * is already frozen, though, #BT_VALUE_STATUS_OK
239 * is returned anyway (i.e. this function never
240 * returns #BT_VALUE_STATUS_FROZEN)
242 * @see bt_value_is_frozen()
244 extern enum bt_value_status
bt_value_freeze(struct bt_value
*object
);
247 * Checks whether \p object is frozen or not.
249 * @param object Value object to check
250 * @returns \c true if \p object is frozen
252 * @see bt_value_freeze()
254 extern bool bt_value_is_frozen(const struct bt_value
*object
);
257 * Returns the type of \p object.
259 * @param object Value object of which to get the type
260 * @returns Value object's type, or #BT_VALUE_TYPE_UNKNOWN
263 * @see #bt_value_type (value object types)
264 * @see bt_value_is_null()
265 * @see bt_value_is_bool()
266 * @see bt_value_is_integer()
267 * @see bt_value_is_float()
268 * @see bt_value_is_string()
269 * @see bt_value_is_array()
270 * @see bt_value_is_map()
272 extern enum bt_value_type
bt_value_get_type(const struct bt_value
*object
);
275 * Checks whether \p object is a null value object. The only valid null
276 * value object is \ref bt_value_null.
278 * @param object Value object to check
279 * @returns \c true if \p object is a null value object
281 * @see bt_value_get_type()
284 bool bt_value_is_null(const struct bt_value
*object
)
286 return bt_value_get_type(object
) == BT_VALUE_TYPE_NULL
;
290 * Checks whether \p object is a boolean value object.
292 * @param object Value object to check
293 * @returns \c true if \p object is a boolean value object
295 * @see bt_value_get_type()
298 bool bt_value_is_bool(const struct bt_value
*object
)
300 return bt_value_get_type(object
) == BT_VALUE_TYPE_BOOL
;
304 * Checks whether \p object is an integer value object.
306 * @param object Value object to check
307 * @returns \c true if \p object is an integer value object
309 * @see bt_value_get_type()
312 bool bt_value_is_integer(const struct bt_value
*object
)
314 return bt_value_get_type(object
) == BT_VALUE_TYPE_INTEGER
;
318 * Checks whether \p object is a floating point number value object.
320 * @param object Value object to check
321 * @returns \c true if \p object is a floating point
322 * number value object
324 * @see bt_value_get_type()
327 bool bt_value_is_float(const struct bt_value
*object
)
329 return bt_value_get_type(object
) == BT_VALUE_TYPE_FLOAT
;
333 * Checks whether \p object is a string value object.
335 * @param object Value object to check
336 * @returns \c true if \p object is a string value object
338 * @see bt_value_get_type()
341 bool bt_value_is_string(const struct bt_value
*object
)
343 return bt_value_get_type(object
) == BT_VALUE_TYPE_STRING
;
347 * Checks whether \p object is an array value object.
349 * @param object Value object to check
350 * @returns \c true if \p object is an array value object
352 * @see bt_value_get_type()
355 bool bt_value_is_array(const struct bt_value
*object
)
357 return bt_value_get_type(object
) == BT_VALUE_TYPE_ARRAY
;
361 * Checks whether \p object is a map value object.
363 * @param object Value object to check
364 * @returns \c true if \p object is a map value object
366 * @see bt_value_get_type()
369 bool bt_value_is_map(const struct bt_value
*object
)
371 return bt_value_get_type(object
) == BT_VALUE_TYPE_MAP
;
375 * Creates a boolean value object. The created boolean value object's
376 * initial raw value is \c false.
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_bool_create_init() (creates an initialized
383 * boolean value object)
385 extern struct bt_value
*bt_value_bool_create(void);
388 * Creates a boolean value object with its initial raw value set to
391 * The created value object's reference count is set to 1.
393 * @param val Initial raw value
394 * @returns Created value object on success, or \c NULL on error
396 extern struct bt_value
*bt_value_bool_create_init(bool val
);
399 * Creates an integer value object. The created integer value object's
400 * initial raw value is 0.
402 * The created value object's reference count is set to 1.
404 * @returns Created value object on success, or \c NULL on error
406 * @see bt_value_integer_create_init() (creates an initialized
407 * integer value object)
409 extern struct bt_value
*bt_value_integer_create(void);
412 * Creates an integer value object with its initial raw value set to
415 * The created value object's reference count is set to 1.
417 * @param val Initial raw value
418 * @returns Created value object on success, or \c NULL on error
420 extern struct bt_value
*bt_value_integer_create_init(int64_t val
);
423 * Creates a floating point number value object. The created floating
424 * point number value object's initial raw value is 0.
426 * The created value object's reference count is set to 1.
428 * @returns Created value object on success, or \c NULL on error
430 * @see bt_value_float_create_init() (creates an initialized floating
431 * point number value object)
433 extern struct bt_value
*bt_value_float_create(void);
436 * Creates a floating point number value object with its initial raw
437 * value set to \p val.
439 * The created value object's reference count is set to 1.
441 * @param val Initial raw value
442 * @returns Created value object on success, or \c NULL on error
444 extern struct bt_value
*bt_value_float_create_init(double val
);
447 * Creates a string value object. The string value object is initially
450 * The created value object's reference count is set to 1.
452 * @returns Created value object on success, or \c NULL on error
454 * @see bt_value_string_create_init() (creates an initialized
455 * string value object)
457 extern struct bt_value
*bt_value_string_create(void);
460 * Creates a string value object with its initial raw value set to
463 * On success, \p val is \em copied.
465 * The created value object's reference count is set to 1.
467 * @param val Initial raw value (copied on success)
468 * @returns Created value object on success, or \c NULL on error
470 extern struct bt_value
*bt_value_string_create_init(const char *val
);
473 * Creates an empty array value object.
475 * The created value object's reference count is set to 1.
477 * @returns Created value object on success, or \c NULL on error
479 extern struct bt_value
*bt_value_array_create(void);
482 * Creates an empty map value object.
484 * The created value object's reference count is set to 1.
486 * @returns Created value object on success, or \c NULL on error
488 extern struct bt_value
*bt_value_map_create(void);
491 * Gets the boolean raw value of the boolean value object \p bool_obj.
493 * @param bool_obj Boolean value object
494 * @param val Returned boolean raw value
495 * @returns One of #bt_value_status values
497 * @see bt_value_bool_set()
499 extern enum bt_value_status
bt_value_bool_get(
500 const struct bt_value
*bool_obj
, bool *val
);
503 * Sets the boolean raw value of the boolean value object \p bool_obj
506 * @param bool_obj Boolean value object
507 * @param val New boolean raw value
508 * @returns One of #bt_value_status values
510 * @see bt_value_bool_get()
512 extern enum bt_value_status
bt_value_bool_set(struct bt_value
*bool_obj
,
516 * Gets the integer raw value of the integer value object
519 * @param integer_obj Integer value object
520 * @param val Returned integer raw value
521 * @returns One of #bt_value_status values
523 * @see bt_value_integer_set()
525 extern enum bt_value_status
bt_value_integer_get(
526 const struct bt_value
*integer_obj
, int64_t *val
);
529 * Sets the integer raw value of the integer value object \p integer_obj
532 * @param integer_obj Integer value object
533 * @param val New integer raw value
534 * @returns One of #bt_value_status values
536 * @see bt_value_integer_get()
538 extern enum bt_value_status
bt_value_integer_set(
539 struct bt_value
*integer_obj
, int64_t val
);
542 * Gets the floating point number raw value of the floating point number
543 * value object \p float_obj.
545 * @param float_obj Floating point number value object
546 * @param val Returned floating point number raw value
547 * @returns One of #bt_value_status values
549 * @see bt_value_float_set()
551 extern enum bt_value_status
bt_value_float_get(
552 const struct bt_value
*float_obj
, double *val
);
555 * Sets the floating point number raw value of the floating point number
556 * value object \p float_obj to \p val.
558 * @param float_obj Floating point number value object
559 * @param val New floating point number raw value
560 * @returns One of #bt_value_status values
562 * @see bt_value_float_get()
564 extern enum bt_value_status
bt_value_float_set(
565 struct bt_value
*float_obj
, double val
);
568 * Gets the string raw value of the string value object \p string_obj.
569 * The returned string is valid as long as this value object exists and
570 * is not modified. The ownership of the returned string is \em not
571 * transferred to the caller.
573 * @param string_obj String value object
574 * @param val Returned string raw value
575 * @returns One of #bt_value_status values
577 * @see bt_value_string_set()
579 extern enum bt_value_status
bt_value_string_get(
580 const struct bt_value
*string_obj
, const char **val
);
583 * Sets the string raw value of the string value object \p string_obj to
586 * On success, \p val is \em copied.
588 * @param string_obj String value object
589 * @param val New string raw value (copied on successf)
590 * @returns One of #bt_value_status values
592 * @see bt_value_string_get()
594 extern enum bt_value_status
bt_value_string_set(struct bt_value
*string_obj
,
598 * Gets the size of the array value object \p array_obj, that is, the
599 * number of value objects contained in \p array_obj.
601 * @param array_obj Array value object
602 * @returns Array size if the return value is 0 (empty) or a
603 * positive value, or one of
604 * #bt_value_status negative values otherwise
606 * @see bt_value_array_is_empty()
608 extern int bt_value_array_size(const struct bt_value
*array_obj
);
611 * Returns \c true if the array value object \p array_obj is empty.
613 * @param array_obj Array value object
614 * @returns \c true if \p array_obj is empty
616 * @see bt_value_array_size()
618 extern bool bt_value_array_is_empty(const struct bt_value
*array_obj
);
621 * Gets the value object of the array value object \p array_obj at the
624 * The returned value object's reference count is incremented, unless
625 * it's a null value object.
627 * @param array_obj Array value object
628 * @param index Index of value object to get
629 * @returns Value object at index \p index on
630 * success, or \c NULL on error
632 extern struct bt_value
*bt_value_array_get(const struct bt_value
*array_obj
,
636 * Appends the value object \p element_obj to the array value
637 * object \p array_obj.
639 * The appended value object's reference count is incremented, unless
640 * it's a null object.
642 * @param array_obj Array value object
643 * @param element_obj Value object to append
644 * @returns One of #bt_value_status values
646 * @see bt_value_array_append_bool()
647 * @see bt_value_array_append_integer()
648 * @see bt_value_array_append_float()
649 * @see bt_value_array_append_string()
650 * @see bt_value_array_append_array()
651 * @see bt_value_array_append_map()
653 extern enum bt_value_status
bt_value_array_append(struct bt_value
*array_obj
,
654 struct bt_value
*element_obj
);
657 * Appends the boolean raw value \p val to the array value object
658 * \p array_obj. This is a convenience function which creates the
659 * underlying boolean value object before appending it.
661 * The created boolean value object's reference count is set to 1.
663 * @param array_obj Array value object
664 * @param val Boolean raw value to append
665 * @returns One of #bt_value_status values
667 * @see bt_value_array_append()
669 extern enum bt_value_status
bt_value_array_append_bool(
670 struct bt_value
*array_obj
, bool val
);
673 * Appends the integer raw value \p val to the array value object
674 * \p array_obj. This is a convenience function which creates the
675 * underlying integer value object before appending it.
677 * The created integer value object's reference count is set to 1.
679 * @param array_obj Array value object
680 * @param val Integer raw value to append
681 * @returns One of #bt_value_status values
683 * @see bt_value_array_append()
685 extern enum bt_value_status
bt_value_array_append_integer(
686 struct bt_value
*array_obj
, int64_t val
);
689 * Appends the floating point number raw value \p val to the array value
690 * object \p array_obj. This is a convenience function which creates the
691 * underlying floating point number value object before appending it.
693 * The created floating point number value object's reference count is
696 * @param array_obj Array value object
697 * @param val Floating point number raw value to append
698 * @returns One of #bt_value_status values
700 * @see bt_value_array_append()
702 extern enum bt_value_status
bt_value_array_append_float(
703 struct bt_value
*array_obj
, double val
);
706 * Appends the string raw value \p val to the array value object
707 * \p array_obj. This is a convenience function which creates the
708 * underlying string value object before appending it.
710 * On success, \p val is \em copied.
712 * The created string value object's reference count is set to 1.
714 * @param array_obj Array value object
715 * @param val String raw value to append (copied on success)
716 * @returns One of #bt_value_status values
718 * @see bt_value_array_append()
720 extern enum bt_value_status
bt_value_array_append_string(
721 struct bt_value
*array_obj
, const char *val
);
724 * Appends an empty array value object to the array value object
725 * \p array_obj. This is a convenience function which creates the
726 * underlying array value object before appending it.
728 * The created array value object's reference count is set to 1.
730 * @param array_obj Array value object
731 * @returns One of #bt_value_status values
733 * @see bt_value_array_append()
735 extern enum bt_value_status
bt_value_array_append_array(
736 struct bt_value
*array_obj
);
739 * Appends an empty map value object to the array value object
740 * \p array_obj. This is a convenience function which creates the
741 * underlying map value object before appending it.
743 * The created map value object's reference count is set to 1.
745 * @param array_obj Array value object
746 * @returns One of #bt_value_status values
748 * @see bt_value_array_append()
750 extern enum bt_value_status
bt_value_array_append_map(
751 struct bt_value
*array_obj
);
754 * Replaces the value object at index \p index of the array
755 * value object \p array_obj by \p element_obj.
757 * The replaced value object's reference count is decremented, unless
758 * it's a null value object. The reference count of \p element_obj is
759 * incremented, unless it's a null value object.
761 * @param array_obj Array value object
762 * @param index Index of value object to replace
763 * @param element_obj New value object at position \p index of
765 * @returns One of #bt_value_status values
767 extern enum bt_value_status
bt_value_array_set(struct bt_value
*array_obj
,
768 size_t index
, struct bt_value
*element_obj
);
771 * Gets the size of a map value object, that is, the number of entries
772 * contained in a map value object.
774 * @param map_obj Map value object
775 * @returns Map size if the return value is 0 (empty) or a
776 * positive value, or one of
777 * #bt_value_status negative values otherwise
779 * @see bt_value_map_is_empty()
781 extern int bt_value_map_size(const struct bt_value
*map_obj
);
784 * Returns \c true if the map value object \p map_obj is empty.
786 * @param map_obj Map value object
787 * @returns \c true if \p map_obj is empty
789 * @see bt_value_map_size()
791 extern bool bt_value_map_is_empty(const struct bt_value
*map_obj
);
794 * Gets the value object associated with the key \p key within the
795 * map value object \p map_obj.
797 * The returned value object's reference count is incremented, unless
798 * it's a null value object.
800 * @param map_obj Map value object
801 * @param key Key of the value object to get
802 * @returns Value object associated with the key \p key
803 * on success, or \c NULL on error
805 extern struct bt_value
*bt_value_map_get(const struct bt_value
*map_obj
,
809 * Calls a provided user function \p cb for each value object of the map
810 * value object \p map_obj.
812 * The value object passed to the user function is a
813 * <b>weak reference</b>: you must call bt_value_get() on it to obtain
814 * your own reference.
816 * The key passed to the user function is only valid in the scope of
817 * this user function call.
819 * The user function must return \c true to continue the loop, or
820 * \c false to break it.
822 * @param map_obj Map value object
823 * @param cb User function to call back
824 * @param data User data passed to the user function
825 * @returns One of #bt_value_status values; more
826 * specifically, #BT_VALUE_STATUS_CANCELLED is
827 * returned if the loop was cancelled by the user
830 extern enum bt_value_status
bt_value_map_foreach(
831 const struct bt_value
*map_obj
, bt_value_map_foreach_cb cb
,
835 * Returns whether or not the map value object \p map_obj contains the
838 * @param map_obj Map value object
839 * @param key Key to check
840 * @returns \c true if \p map_obj contains the key \p key,
841 * or \c false if it doesn't have \p key or
844 extern bool bt_value_map_has_key(const struct bt_value
*map_obj
,
848 * Inserts the value object \p element_obj associated with the key
849 * \p key into the map value object \p map_obj. If \p key exists in
850 * \p map_obj, the associated value object is first put, and then
851 * replaced by \p element_obj.
853 * On success, \p key is \em copied.
855 * The inserted value object's reference count is incremented, unless
856 * it's a null value object.
858 * @param map_obj Map value object
859 * @param key Key (copied on success) of value object to insert
860 * @param element_obj Value object to insert, associated with the
862 * @returns One of #bt_value_status values
864 * @see bt_value_map_insert_bool()
865 * @see bt_value_map_insert_integer()
866 * @see bt_value_map_insert_float()
867 * @see bt_value_map_insert_string()
868 * @see bt_value_map_insert_array()
869 * @see bt_value_map_insert_map()
871 extern enum bt_value_status
bt_value_map_insert(
872 struct bt_value
*map_obj
, const char *key
,
873 struct bt_value
*element_obj
);
876 * Inserts the boolean raw value \p val associated with the key \p key
877 * into the map value object \p map_obj. This is a convenience function
878 * which creates the underlying boolean value object before
881 * On success, \p key is \em copied.
883 * The created boolean value object's reference count is set to 1.
885 * @param map_obj Map value object
886 * @param key Key (copied on success) of boolean value object
888 * @param val Boolean raw value to insert, associated with
890 * @returns One of #bt_value_status values
892 * @see bt_value_map_insert()
894 extern enum bt_value_status
bt_value_map_insert_bool(
895 struct bt_value
*map_obj
, const char *key
, bool val
);
898 * Inserts the integer raw value \p val associated with the key \p key
899 * into the map value object \p map_obj. This is a convenience function
900 * which creates the underlying integer value object before inserting it.
902 * On success, \p key is \em copied.
904 * The created integer value object's reference count is set to 1.
906 * @param map_obj Map value object
907 * @param key Key (copied on success) of integer value object
909 * @param val Integer raw value to insert, associated with
911 * @returns One of #bt_value_status values
913 * @see bt_value_map_insert()
915 extern enum bt_value_status
bt_value_map_insert_integer(
916 struct bt_value
*map_obj
, const char *key
, int64_t val
);
919 * Inserts the floating point number raw value \p val associated with
920 * the key \p key into the map value object \p map_obj. This is a
921 * convenience function which creates the underlying floating point
922 * number value object before inserting it.
924 * On success, \p key is \em copied.
926 * The created floating point number value object's reference count is
929 * @param map_obj Map value object
930 * @param key Key (copied on success) of floating point number
931 * value object to insert
932 * @param val Floating point number raw value to insert,
933 * associated with the key \p key
934 * @returns One of #bt_value_status values
936 * @see bt_value_map_insert()
938 extern enum bt_value_status
bt_value_map_insert_float(
939 struct bt_value
*map_obj
, const char *key
, double val
);
942 * Inserts the string raw value \p val associated with the key \p key
943 * into the map value object \p map_obj. This is a convenience function
944 * which creates the underlying string value object before inserting it.
946 * On success, \p val and \p key are \em copied.
948 * The created string value object's reference count is set to 1.
950 * @param map_obj Map value object
951 * @param key Key (copied on success) of string value object
953 * @param val String raw value to insert (copied on success),
954 * associated with the key \p key
955 * @returns One of #bt_value_status values
957 * @see bt_value_map_insert()
959 extern enum bt_value_status
bt_value_map_insert_string(
960 struct bt_value
*map_obj
, const char *key
, const char *val
);
963 * Inserts an empty array value object associated with the key \p key
964 * into the map value object \p map_obj. This is a convenience function
965 * which creates the underlying array value object before inserting it.
967 * On success, \p key is \em copied.
969 * The created array value object's reference count is set to 1.
971 * @param map_obj Map value object
972 * @param key Key (copied on success) of empty array value
974 * @returns One of #bt_value_status values
976 * @see bt_value_map_insert()
978 extern enum bt_value_status
bt_value_map_insert_array(
979 struct bt_value
*map_obj
, const char *key
);
982 * Inserts an empty map value object associated with the key \p key into
983 * the map value object \p map_obj. This is a convenience function which
984 * creates the underlying map value object before inserting it.
986 * On success, \p key is \em copied.
988 * The created map value object's reference count is set to 1.
990 * @param map_obj Map value object
991 * @param key Key (copied on success) of empty map value
993 * @returns One of #bt_value_status values
995 * @see bt_value_map_insert()
997 extern enum bt_value_status
bt_value_map_insert_map(
998 struct bt_value
*map_obj
, const char *key
);
1001 * Creates a deep copy of the value object \p object.
1003 * The created value object's reference count is set to 1, unless
1004 * \p object is a null value object.
1006 * Copying a frozen value object is allowed: the resulting copy is
1009 * @param object Value object to copy
1010 * @returns Deep copy of \p object on success, or \c NULL
1013 extern struct bt_value
*bt_value_copy(const struct bt_value
*object
);
1016 * Compares the value objects \p object_a and \p object_b and returns
1017 * \c true if they have the same \em content (raw values).
1019 * @param object_a Value object A
1020 * @param object_b Value object B
1021 * @returns \c true if \p object_a and \p object_b have the
1022 * same content, or \c false if they differ or on
1025 extern bool bt_value_compare(const struct bt_value
*object_a
,
1026 const struct bt_value
*object_b
);
1032 #endif /* _BABELTRACE_VALUES_H */