2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_VALUE_H
8 #define BABELTRACE2_VALUE_H
10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
19 #include <babeltrace2/types.h>
26 @defgroup api-val Values
29 Generic, JSON-like basic data containers.
31 <strong><em>Values</em></strong> are generic data containers. Except for
32 the fact that integer values are explicitly unsigned or signed because
33 of typing limitations,
34 \bt_name values are very similar to <a href="https://json.org/">JSON</a>
37 The value API is completely independent from the rest of the
40 \bt_c_comp initialization parameters, \ref bt_query_executor_create()
41 "query" parameters, as well as trace IR user attributes (for example,
42 bt_event_class_set_user_attributes()) use values.
44 The available value types are:
47 <dt>Scalar values</dt>
51 - Unsigned integer (64-bit range)
52 - Signed integer (64-bit range)
53 - Real (\c double range)
57 <dt>Container values</dt>
60 - Map (string to value)
64 Values are \ref api-fund-shared-object "shared objects": get a new
65 reference with bt_value_get_ref() and put an existing reference with
68 Some library functions \ref api-fund-freezing "freeze" values on
69 success. The documentation of those functions indicate this
72 All the value types share the same C type, #bt_value.
74 Get the type enumerator of a value with bt_value_get_type(). Get whether
75 or not a value type conceptually \em is a given type with the inline
76 bt_value_type_is() function. Get whether or not a value has a specific
77 type with one of the <code>bt_value_is_*()</code> inline helpers.
79 The \em null value is special in that it's a singleton variable,
80 #bt_value_null. You can directly compare any value pointer to
81 #bt_value_null to check if it's a null value. Like other types of
82 values, the null value is a shared object: if you get a new null value
83 reference, you must eventually put it.
85 Create a value with one of the <code>bt_value_*_create()</code> or
86 <code>bt_value_*_create_init()</code> functions.
88 This documentation names the actual data that a scalar value wraps the
91 Set and get the raw values of scalar values with functions that are
92 named <code>bt_value_*_set()</code> and <code>bt_value_*_get()</code>.
94 Check that two values are recursively equal with bt_value_is_equal().
96 Deep-copy a value with bt_value_copy().
98 Extend a map value with bt_value_map_extend().
100 The following table shows the available functions and types for each
107 <th>Type query function
108 <th>Creation functions
109 <th>Writing functions
110 <th>Reading functions
113 <td>#BT_VALUE_TYPE_NULL
114 <td>bt_value_is_null()
115 <td>\em N/A (use the #bt_value_null variable directly)
120 <td>#BT_VALUE_TYPE_BOOL
121 <td>bt_value_is_bool()
123 bt_value_bool_create()<br>
124 bt_value_bool_create_init()
125 <td>bt_value_bool_set()
126 <td>bt_value_bool_get()
128 <th><em>Unsigned integer</em>
129 <td>#BT_VALUE_TYPE_UNSIGNED_INTEGER
130 <td>bt_value_is_unsigned_integer()
132 bt_value_integer_unsigned_create()<br>
133 bt_value_integer_unsigned_create_init()
134 <td>bt_value_integer_unsigned_set()
135 <td>bt_value_integer_unsigned_get()
137 <th><em>Signed integer</em>
138 <td>#BT_VALUE_TYPE_SIGNED_INTEGER
139 <td>bt_value_is_signed_integer()
141 bt_value_integer_signed_create()<br>
142 bt_value_integer_signed_create_init()
143 <td>bt_value_integer_signed_set()
144 <td>bt_value_integer_signed_get()
147 <td>#BT_VALUE_TYPE_REAL
148 <td>bt_value_is_real()
150 bt_value_real_create()<br>
151 bt_value_real_create_init()
152 <td>bt_value_real_set()
153 <td>bt_value_real_get()
156 <td>#BT_VALUE_TYPE_STRING
157 <td>bt_value_is_string()
159 bt_value_string_create()<br>
160 bt_value_string_create_init()
161 <td>bt_value_string_set()
162 <td>bt_value_string_get()
165 <td>#BT_VALUE_TYPE_ARRAY
166 <td>bt_value_is_array()
168 bt_value_array_create()
170 bt_value_array_append_element()<br>
171 bt_value_array_append_bool_element()<br>
172 bt_value_array_append_unsigned_integer_element()<br>
173 bt_value_array_append_signed_integer_element()<br>
174 bt_value_array_append_real_element()<br>
175 bt_value_array_append_string_element()<br>
176 bt_value_array_append_empty_array_element()<br>
177 bt_value_array_append_empty_map_element()<br>
178 bt_value_array_set_element_by_index()
180 bt_value_array_get_length()<br>
181 bt_value_array_is_empty()<br>
182 bt_value_array_borrow_element_by_index()<br>
183 bt_value_array_borrow_element_by_index_const()
186 <td>#BT_VALUE_TYPE_MAP
187 <td>bt_value_is_map()
189 bt_value_map_create()
191 bt_value_map_insert_entry()<br>
192 bt_value_map_insert_bool_entry()<br>
193 bt_value_map_insert_unsigned_integer_entry()<br>
194 bt_value_map_insert_signed_integer_entry()<br>
195 bt_value_map_insert_real_entry()<br>
196 bt_value_map_insert_string_entry()<br>
197 bt_value_map_insert_empty_array_entry()<br>
198 bt_value_map_insert_empty_map_entry()<br>
199 bt_value_map_extend()
201 bt_value_map_get_size()<br>
202 bt_value_map_is_empty()<br>
203 bt_value_map_has_entry()<br>
204 bt_value_map_borrow_entry_value()<br>
205 bt_value_map_borrow_entry_value_const()<br>
206 bt_value_map_foreach_entry()<br>
207 bt_value_map_foreach_entry_const()
217 @typedef struct bt_value bt_value;
232 Value type enumerators.
234 typedef enum bt_value_type
{
239 BT_VALUE_TYPE_NULL
= 1 << 0,
245 BT_VALUE_TYPE_BOOL
= 1 << 1,
251 No value has this type: use it with bt_value_type_is().
253 BT_VALUE_TYPE_INTEGER
= 1 << 2,
257 Unsigned integer value.
259 This type conceptually inherits #BT_VALUE_TYPE_INTEGER.
261 BT_VALUE_TYPE_UNSIGNED_INTEGER
= (1 << 3) | BT_VALUE_TYPE_INTEGER
,
265 Signed integer value.
267 This type conceptually inherits #BT_VALUE_TYPE_INTEGER.
269 BT_VALUE_TYPE_SIGNED_INTEGER
= (1 << 4) | BT_VALUE_TYPE_INTEGER
,
275 BT_VALUE_TYPE_REAL
= 1 << 5,
281 BT_VALUE_TYPE_STRING
= 1 << 6,
287 BT_VALUE_TYPE_ARRAY
= 1 << 7,
293 BT_VALUE_TYPE_MAP
= 1 << 8,
298 Returns the type enumerator of the value \bt_p{value}.
301 Value of which to get the type enumerator
304 Type enumerator of \bt_p{value}.
306 @bt_pre_not_null{value}
308 @sa bt_value_type_is() —
309 Returns whether or not the type of a value conceptually is a given
311 @sa bt_value_is_null() —
312 Returns whether or not a value is a null value.
313 @sa bt_value_is_bool() —
314 Returns whether or not a value is a boolean value.
315 @sa bt_value_is_unsigned_integer() —
316 Returns whether or not a value is an unsigned integer value.
317 @sa bt_value_is_signed_integer() —
318 Returns whether or not a value is a signed integer value.
319 @sa bt_value_is_real() —
320 Returns whether or not a value is a real value.
321 @sa bt_value_is_string() —
322 Returns whether or not a value is a string value.
323 @sa bt_value_is_array() —
324 Returns whether or not a value is an array value.
325 @sa bt_value_is_map() —
326 Returns whether or not a value is a map value.
328 extern bt_value_type
bt_value_get_type(const bt_value
*value
) __BT_NOEXCEPT
;
332 Returns whether or not the value type \bt_p{type} conceptually
333 \em is the value type \bt_p{other_type}.
335 For example, an unsigned integer value conceptually \em is an integer
339 bt_value_type_is(BT_VALUE_TYPE_UNSIGNED_INTEGER, BT_VALUE_TYPE_INTEGER)
345 Value type to check against \bt_p{other_type}.
346 @param[in] other_type
347 Value type against which to check \bt_p{type}.
350 #BT_TRUE if \bt_p{type} conceptually \em is \bt_p{other_type}.
352 @sa bt_value_get_type() —
353 Returns the type enumerator of a value.
354 @sa bt_value_is_null() —
355 Returns whether or not a value is a null value.
356 @sa bt_value_is_bool() —
357 Returns whether or not a value is a boolean value.
358 @sa bt_value_is_unsigned_integer() —
359 Returns whether or not a value is an unsigned integer value.
360 @sa bt_value_is_signed_integer() —
361 Returns whether or not a value is a signed integer value.
362 @sa bt_value_is_real() —
363 Returns whether or not a value is a real value.
364 @sa bt_value_is_string() —
365 Returns whether or not a value is a string value.
366 @sa bt_value_is_array() —
367 Returns whether or not a value is an array value.
368 @sa bt_value_is_map() —
369 Returns whether or not a value is a map value.
372 bt_bool
bt_value_type_is(const bt_value_type type
,
373 const bt_value_type other_type
) __BT_NOEXCEPT
375 return (type
& other_type
) == other_type
;
380 Returns whether or not the value \bt_p{value} is a null value.
383 Because all null values point to the same null value singleton, you
384 can also directly compare \bt_p{value} to the #bt_value_null
391 #BT_TRUE if \bt_p{value} is a null value.
393 @bt_pre_not_null{value}
395 @sa bt_value_get_type() —
396 Returns the type enumerator of a value.
397 @sa bt_value_type_is() —
398 Returns whether or not the type of a value conceptually is a given
400 @sa #bt_value_null —
401 The null value singleton.
404 bt_bool
bt_value_is_null(const bt_value
*value
) __BT_NOEXCEPT
406 return bt_value_get_type(value
) == BT_VALUE_TYPE_NULL
;
411 Returns whether or not the value \bt_p{value} is a boolean value.
417 #BT_TRUE if \bt_p{value} is a boolean value.
419 @bt_pre_not_null{value}
421 @sa bt_value_get_type() —
422 Returns the type enumerator of a value.
423 @sa bt_value_type_is() —
424 Returns whether or not the type of a value conceptually is a given
428 bt_bool
bt_value_is_bool(const bt_value
*value
) __BT_NOEXCEPT
430 return bt_value_get_type(value
) == BT_VALUE_TYPE_BOOL
;
435 Returns whether or not the value \bt_p{value} is an unsigned integer
442 #BT_TRUE if \bt_p{value} is an unsigned integer value.
444 @bt_pre_not_null{value}
446 @sa bt_value_get_type() —
447 Returns the type enumerator of a value.
448 @sa bt_value_type_is() —
449 Returns whether or not the type of a value conceptually is a given
453 bt_bool
bt_value_is_unsigned_integer(const bt_value
*value
) __BT_NOEXCEPT
455 return bt_value_get_type(value
) == BT_VALUE_TYPE_UNSIGNED_INTEGER
;
460 Returns whether or not the value \bt_p{value} is a signed integer
467 #BT_TRUE if \bt_p{value} is a signed integer value.
469 @bt_pre_not_null{value}
471 @sa bt_value_get_type() —
472 Returns the type enumerator of a value.
473 @sa bt_value_type_is() —
474 Returns whether or not the type of a value conceptually is a given
478 bt_bool
bt_value_is_signed_integer(const bt_value
*value
) __BT_NOEXCEPT
480 return bt_value_get_type(value
) == BT_VALUE_TYPE_SIGNED_INTEGER
;
485 Returns whether or not the value \bt_p{value} is a real value.
491 #BT_TRUE if \bt_p{value} is a real value.
493 @bt_pre_not_null{value}
495 @sa bt_value_get_type() —
496 Returns the type enumerator of a value.
497 @sa bt_value_type_is() —
498 Returns whether or not the type of a value conceptually is a given
502 bt_bool
bt_value_is_real(const bt_value
*value
) __BT_NOEXCEPT
504 return bt_value_get_type(value
) == BT_VALUE_TYPE_REAL
;
509 Returns whether or not the value \bt_p{value} is a string value.
515 #BT_TRUE if \bt_p{value} is a string value.
517 @bt_pre_not_null{value}
519 @sa bt_value_get_type() —
520 Returns the type enumerator of a value.
521 @sa bt_value_type_is() —
522 Returns whether or not the type of a value conceptually is a given
526 bt_bool
bt_value_is_string(const bt_value
*value
) __BT_NOEXCEPT
528 return bt_value_get_type(value
) == BT_VALUE_TYPE_STRING
;
533 Returns whether or not the value \bt_p{value} is an array value.
539 #BT_TRUE if \bt_p{value} is an array value.
541 @bt_pre_not_null{value}
543 @sa bt_value_get_type() —
544 Returns the type enumerator of a value.
545 @sa bt_value_type_is() —
546 Returns whether or not the type of a value conceptually is a given
550 bt_bool
bt_value_is_array(const bt_value
*value
) __BT_NOEXCEPT
552 return bt_value_get_type(value
) == BT_VALUE_TYPE_ARRAY
;
557 Returns whether or not the value \bt_p{value} is a map value.
563 #BT_TRUE if \bt_p{value} is a map value.
565 @bt_pre_not_null{value}
567 @sa bt_value_get_type() —
568 Returns the type enumerator of a value.
569 @sa bt_value_type_is() —
570 Returns whether or not the type of a value conceptually is a given
574 bt_bool
bt_value_is_map(const bt_value
*value
) __BT_NOEXCEPT
576 return bt_value_get_type(value
) == BT_VALUE_TYPE_MAP
;
588 The null value singleton.
590 This is the \em only instance of a null value.
592 Like any type of value, the null value is a shared object: if you get a
593 new null value reference with bt_value_get_ref(), you must eventually
594 put it with bt_value_put_ref(). The null value singleton's reference
595 count must never reach 0: libbabeltrace2 logs a warning message when
596 this programming error occurs.
598 Because all null values point to the same null value singleton, you can
599 directly compare a value to the \c bt_value_null variable.
603 \c bt_value_null is different from \c NULL: the former is a true
604 \bt_name value object while the latter is a C definition which
605 usually means "no pointer".
607 For example, bt_value_map_borrow_entry_value() can return
608 \c bt_value_null if the requested key is mapped to a null value, but
609 it can also return \c NULL if the key is not found.
612 @sa bt_value_is_null() —
613 Returns whether or not a value is a null value.
615 extern bt_value
*const bt_value_null
;
626 Creates and returns a boolean value initialized to #BT_FALSE.
628 The returned value has the type #BT_VALUE_TYPE_BOOL.
631 New boolean value reference, or \c NULL on memory error.
633 @sa bt_value_bool_create_init() —
634 Creates a boolean value with a given initial raw value.
636 extern bt_value
*bt_value_bool_create(void) __BT_NOEXCEPT
;
640 Creates and returns a boolean value initialized to \bt_p{raw_value}.
642 The returned value has the type #BT_VALUE_TYPE_BOOL.
645 Initial raw value of the boolean value to create.
648 New boolean value reference, or \c NULL on memory error.
650 @sa bt_value_bool_create() —
651 Creates a boolean value initialized to #BT_FALSE.
653 extern bt_value
*bt_value_bool_create_init(bt_bool raw_value
) __BT_NOEXCEPT
;
657 Sets the raw value of the boolean value \bt_p{value} to
661 Boolean value of which to set the raw value to \bt_p{raw_value}.
663 New raw value of \bt_p{value}.
665 @bt_pre_not_null{value}
666 @bt_pre_is_bool_val{value}
669 @sa bt_value_bool_get() —
670 Returns the raw value of a boolean value.
672 extern void bt_value_bool_set(bt_value
*value
, bt_bool raw_value
) __BT_NOEXCEPT
;
676 Returns the raw value of the boolean value \bt_p{value}.
679 Boolean value of which to get the raw value.
682 Raw value of \bt_p{value}.
684 @bt_pre_not_null{value}
685 @bt_pre_is_bool_val{value}
687 @sa bt_value_bool_set() —
688 Sets the raw value of a boolean value.
690 extern bt_bool
bt_value_bool_get(const bt_value
*value
) __BT_NOEXCEPT
;
695 @name Unsigned integer value
701 Creates and returns an unsigned integer value initialized to 0.
703 The returned value has the type #BT_VALUE_TYPE_UNSIGNED_INTEGER.
706 New unsigned integer value reference, or \c NULL on memory error.
708 @sa bt_value_integer_unsigned_create_init() —
709 Creates an unsigned integer value with a given initial raw value.
711 extern bt_value
*bt_value_integer_unsigned_create(void) __BT_NOEXCEPT
;
715 Creates and returns an unsigned integer value initialized to
718 The returned value has the type #BT_VALUE_TYPE_UNSIGNED_INTEGER.
721 Initial raw value of the unsigned integer value to create.
724 New unsigned integer value reference, or \c NULL on memory error.
726 @sa bt_value_bool_create() —
727 Creates an unsigned integer value initialized to 0.
729 extern bt_value
*bt_value_integer_unsigned_create_init(uint64_t raw_value
) __BT_NOEXCEPT
;
733 Sets the raw value of the unsigned integer value \bt_p{value} to
737 Unsigned integer value of which to set the raw value to
740 New raw value of \bt_p{value}.
742 @bt_pre_not_null{value}
743 @bt_pre_is_uint_val{value}
746 @sa bt_value_integer_unsigned_get() —
747 Returns the raw value of an unsigned integer value.
749 extern void bt_value_integer_unsigned_set(bt_value
*value
,
750 uint64_t raw_value
) __BT_NOEXCEPT
;
754 Returns the raw value of the unsigned integer value \bt_p{value}.
757 Unsigned integer value of which to get the raw value.
760 Raw value of \bt_p{value}.
762 @bt_pre_not_null{value}
763 @bt_pre_is_uint_val{value}
765 @sa bt_value_integer_unsigned_set() —
766 Sets the raw value of an unsigned integer value.
768 extern uint64_t bt_value_integer_unsigned_get(const bt_value
*value
) __BT_NOEXCEPT
;
773 @name Signed integer value
779 Creates and returns a signed integer value initialized to 0.
781 The returned value has the type #BT_VALUE_TYPE_SIGNED_INTEGER.
784 New signed integer value reference, or \c NULL on memory error.
786 @sa bt_value_integer_signed_create_init() —
787 Creates a signed integer value with a given initial raw value.
789 extern bt_value
*bt_value_integer_signed_create(void) __BT_NOEXCEPT
;
793 Creates and returns a signed integer value initialized to
796 The returned value has the type #BT_VALUE_TYPE_SIGNED_INTEGER.
799 Initial raw value of the signed integer value to create.
802 New signed integer value reference, or \c NULL on memory error.
804 @sa bt_value_bool_create() —
805 Creates a signed integer value initialized to 0.
807 extern bt_value
*bt_value_integer_signed_create_init(int64_t raw_value
) __BT_NOEXCEPT
;
811 Sets the raw value of the signed integer value \bt_p{value} to
815 Signed integer value of which to set the raw value to
818 New raw value of \bt_p{value}.
820 @bt_pre_not_null{value}
821 @bt_pre_is_sint_val{value}
824 @sa bt_value_integer_signed_get() —
825 Returns the raw value of a signed integer value.
827 extern void bt_value_integer_signed_set(bt_value
*value
, int64_t raw_value
) __BT_NOEXCEPT
;
831 Returns the raw value of the signed integer value \bt_p{value}.
834 Signed integer value of which to get the raw value.
837 Raw value of \bt_p{value}.
839 @bt_pre_not_null{value}
840 @bt_pre_is_sint_val{value}
842 @sa bt_value_integer_signed_set() —
843 Sets the raw value of a signed integer value.
845 extern int64_t bt_value_integer_signed_get(const bt_value
*value
) __BT_NOEXCEPT
;
856 Creates and returns a real value initialized to 0.
858 The returned value has the type #BT_VALUE_TYPE_REAL.
861 New real value reference, or \c NULL on memory error.
863 @sa bt_value_real_create_init() —
864 Creates a real value with a given initial raw value.
866 extern bt_value
*bt_value_real_create(void) __BT_NOEXCEPT
;
870 Creates and returns a real value initialized to \bt_p{raw_value}.
872 The returned value has the type #BT_VALUE_TYPE_REAL.
875 Initial raw value of the real value to create.
878 New real value reference, or \c NULL on memory error.
880 @sa bt_value_real_create() —
881 Creates a real value initialized to 0.
883 extern bt_value
*bt_value_real_create_init(double raw_value
) __BT_NOEXCEPT
;
887 Sets the raw value of the real value \bt_p{value} to
891 Real value of which to set the raw value to \bt_p{raw_value}.
893 New raw value of \bt_p{value}.
895 @bt_pre_not_null{value}
896 @bt_pre_is_real_val{value}
899 @sa bt_value_real_get() —
900 Returns the raw value of a real value.
902 extern void bt_value_real_set(bt_value
*value
, double raw_value
) __BT_NOEXCEPT
;
906 Returns the raw value of the real value \bt_p{value}.
909 Real value of which to get the raw value.
912 Raw value of \bt_p{value}.
914 @bt_pre_not_null{value}
915 @bt_pre_is_real_val{value}
917 @sa bt_value_real_set() —
918 Sets the raw value of a real value.
920 extern double bt_value_real_get(const bt_value
*value
) __BT_NOEXCEPT
;
931 Creates and returns an empty string value.
933 The returned value has the type #BT_VALUE_TYPE_STRING.
936 New string value reference, or \c NULL on memory error.
938 @sa bt_value_string_create_init() —
939 Creates a string value with a given initial raw value.
941 extern bt_value
*bt_value_string_create(void) __BT_NOEXCEPT
;
945 Creates and returns a string value initialized to a copy of
948 The returned value has the type #BT_VALUE_TYPE_STRING.
951 Initial raw value of the string value to create (copied).
954 New string value reference, or \c NULL on memory error.
956 @bt_pre_not_null{raw_value}
958 @sa bt_value_string_create() —
959 Creates an empty string value.
961 extern bt_value
*bt_value_string_create_init(const char *raw_value
) __BT_NOEXCEPT
;
965 Status codes for bt_value_string_set().
967 typedef enum bt_value_string_set_status
{
972 BT_VALUE_STRING_SET_STATUS_OK
= __BT_FUNC_STATUS_OK
,
978 BT_VALUE_STRING_SET_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
979 } bt_value_string_set_status
;
983 Sets the raw value of the string value \bt_p{value} to a copy of
987 String value of which to set the raw value to a copy of
990 New raw value of \bt_p{value} (copied).
992 @retval #BT_VALUE_STRING_SET_STATUS_OK
994 @retval #BT_VALUE_STRING_SET_STATUS_MEMORY_ERROR
997 @bt_pre_not_null{value}
998 @bt_pre_is_string_val{value}
1000 @bt_pre_not_null{raw_value}
1002 @sa bt_value_string_get() —
1003 Returns the raw value of a string value.
1005 extern bt_value_string_set_status
bt_value_string_set(bt_value
*value
,
1006 const char *raw_value
) __BT_NOEXCEPT
;
1010 Returns the raw value of the string value \bt_p{value}.
1013 String value of which to get the raw value.
1017 Raw value of \bt_p{value}.
1019 The returned pointer remains valid until \bt_p{value} is modified.
1022 @bt_pre_not_null{value}
1023 @bt_pre_is_string_val{value}
1025 @sa bt_value_string_set() —
1026 Sets the raw value of a string value.
1028 extern const char *bt_value_string_get(const bt_value
*value
) __BT_NOEXCEPT
;
1039 Creates and returns an empty array value.
1041 The returned value has the type #BT_VALUE_TYPE_ARRAY.
1044 New array value reference, or \c NULL on memory error.
1046 extern bt_value
*bt_value_array_create(void) __BT_NOEXCEPT
;
1050 Status codes for the <code>bt_value_array_append_*()</code>
1053 typedef enum bt_value_array_append_element_status
{
1058 BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1064 BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1065 } bt_value_array_append_element_status
;
1069 Appends the value \bt_p{element_value} to the array value \bt_p{value}.
1071 To append a null value, pass #bt_value_null as \bt_p{element_value}.
1074 Array value to which to append \bt_p{element_value}.
1075 @param[in] element_value
1076 Value to append to \bt_p{value}.
1078 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1080 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1083 @bt_pre_not_null{value}
1084 @bt_pre_is_array_val{value}
1086 @bt_pre_not_null{element_value}
1088 \bt_p{element_value} does not contain \bt_p{value}, recursively.
1091 <strong>On success</strong>, the length of \bt_p{value} is
1094 @sa bt_value_array_append_bool_element() —
1095 Creates and appends a boolean value to an array value.
1096 @sa bt_value_array_append_unsigned_integer_element() —
1097 Creates and appends an unsigned integer value to an array value.
1098 @sa bt_value_array_append_signed_integer_element() —
1099 Creates and appends a signed integer value to an array value.
1100 @sa bt_value_array_append_real_element() —
1101 Creates and appends a real value to an array value.
1102 @sa bt_value_array_append_string_element() —
1103 Creates and appends a string value to an array value.
1104 @sa bt_value_array_append_empty_array_element() —
1105 Creates and appends an empty array value to an array value.
1106 @sa bt_value_array_append_empty_map_element() —
1107 Creates and appends an empty map value to an array value.
1109 extern bt_value_array_append_element_status
bt_value_array_append_element(
1110 bt_value
*value
, bt_value
*element_value
) __BT_NOEXCEPT
;
1114 Creates a boolean value initialized to \bt_p{raw_value} and appends
1115 it to the array value \bt_p{value}.
1118 Array value to which to append the created boolean value.
1119 @param[in] raw_value
1120 Raw value of the boolean value to create and append to \bt_p{value}.
1122 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1124 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1127 @bt_pre_not_null{value}
1128 @bt_pre_is_array_val{value}
1132 <strong>On success</strong>, the length of \bt_p{value} is
1135 @sa bt_value_array_append_element() —
1136 Appends an existing value to an array value.
1138 extern bt_value_array_append_element_status
1139 bt_value_array_append_bool_element(bt_value
*value
, bt_bool raw_value
) __BT_NOEXCEPT
;
1143 Creates an unsigned integer value initialized to \bt_p{raw_value}
1144 and appends it to the array value \bt_p{value}.
1147 Array value to which to append the created unsigned integer value.
1148 @param[in] raw_value
1149 Raw value of the unsigned integer value to create and append to
1152 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1154 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1157 @bt_pre_not_null{value}
1158 @bt_pre_is_array_val{value}
1162 <strong>On success</strong>, the length of \bt_p{value} is
1165 @sa bt_value_array_append_element() —
1166 Appends an existing value to an array value.
1168 extern bt_value_array_append_element_status
1169 bt_value_array_append_unsigned_integer_element(bt_value
*value
,
1170 uint64_t raw_value
) __BT_NOEXCEPT
;
1174 Creates a signed integer value initialized to \bt_p{raw_value} and
1175 appends it to the array value \bt_p{value}.
1178 Array value to which to append the created signed integer value.
1179 @param[in] raw_value
1180 Raw value of the signed integer value to create and append to
1183 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1185 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1188 @bt_pre_not_null{value}
1189 @bt_pre_is_array_val{value}
1193 <strong>On success</strong>, the length of \bt_p{value} is
1196 @sa bt_value_array_append_element() —
1197 Appends an existing value to an array value.
1199 extern bt_value_array_append_element_status
1200 bt_value_array_append_signed_integer_element(bt_value
*value
,
1201 int64_t raw_value
) __BT_NOEXCEPT
;
1205 Creates a real value initialized to \bt_p{raw_value} and appends
1206 it to the array value \bt_p{value}.
1209 Array value to which to append the created real value.
1210 @param[in] raw_value
1211 Raw value of the real value to create and append to \bt_p{value}.
1213 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1215 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1218 @bt_pre_not_null{value}
1219 @bt_pre_is_array_val{value}
1223 <strong>On success</strong>, the length of \bt_p{value} is
1226 @sa bt_value_array_append_element() —
1227 Appends an existing value to an array value.
1229 extern bt_value_array_append_element_status
1230 bt_value_array_append_real_element(bt_value
*value
, double raw_value
) __BT_NOEXCEPT
;
1234 Creates a string value initialized to a copy of \bt_p{raw_value} and
1235 appends it to the array value \bt_p{value}.
1238 Array value to which to append the created string value.
1239 @param[in] raw_value
1240 Raw value of the string value to create and append to \bt_p{value}
1243 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1245 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1248 @bt_pre_not_null{value}
1249 @bt_pre_is_array_val{value}
1253 <strong>On success</strong>, the length of \bt_p{value} is
1256 @sa bt_value_array_append_element() —
1257 Appends an existing value to an array value.
1259 extern bt_value_array_append_element_status
1260 bt_value_array_append_string_element(bt_value
*value
, const char *raw_value
) __BT_NOEXCEPT
;
1264 Creates an empty array value and appends it to the array
1267 On success, if \bt_p{element_value} is not \c NULL, this function sets
1268 \bt_p{*element_value} to a \em borrowed reference of the created empty
1272 Array value to which to append the created empty array value.
1273 @param[out] element_value
1274 <strong>On success, if not \c NULL</strong>, \bt_p{*element_value}
1275 is a \em borrowed reference of the created empty array value.
1277 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1279 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1282 @bt_pre_not_null{value}
1283 @bt_pre_is_array_val{value}
1287 <strong>On success</strong>, the length of \bt_p{value} is
1290 @sa bt_value_array_append_element() —
1291 Appends an existing value to an array value.
1293 extern bt_value_array_append_element_status
1294 bt_value_array_append_empty_array_element(bt_value
*value
,
1295 bt_value
**element_value
) __BT_NOEXCEPT
;
1299 Creates an empty map value and appends it to the array
1302 On success, if \bt_p{element_value} is not \c NULL, this function sets
1303 \bt_p{*element_value} to a \em borrowed reference of the created empty
1307 Array value to which to append the created empty array value.
1308 @param[out] element_value
1309 <strong>On success, if not \c NULL</strong>, \bt_p{*element_value}
1310 is a \em borrowed reference of the created empty map value.
1312 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1314 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1317 @bt_pre_not_null{value}
1318 @bt_pre_is_array_val{value}
1322 <strong>On success</strong>, the length of \bt_p{value} is
1325 @sa bt_value_array_append_element() —
1326 Appends an existing value to an array value.
1328 extern bt_value_array_append_element_status
1329 bt_value_array_append_empty_map_element(bt_value
*value
,
1330 bt_value
**element_value
) __BT_NOEXCEPT
;
1334 Status codes for bt_value_array_set_element_by_index().
1336 typedef enum bt_value_array_set_element_by_index_status
{
1341 BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1347 BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1348 } bt_value_array_set_element_by_index_status
;
1352 Sets the element of the array value \bt_p{value} at index
1353 \bt_p{index} to the value \bt_p{element_value}.
1355 On success, this function replaces the existing element of \bt_p{value}
1356 at index \bt_p{index}.
1359 Array value of which to set the element at index \bt_p{index}.
1361 Index of the element to set in \bt_p{value}.
1362 @param[in] element_value
1363 Value to set as the element of \bt_p{value} at index \bt_p{index}.
1365 @retval #BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_OK
1367 @retval #BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_MEMORY_ERROR
1370 @bt_pre_not_null{value}
1371 @bt_pre_is_array_val{value}
1374 \bt_p{index} is less than the length of \bt_p{value} (as returned by
1375 bt_value_array_get_length()).
1376 @bt_pre_not_null{element_value}
1378 \bt_p{element_value} does not contain \bt_p{value}, recursively.
1381 <strong>On success</strong>, the length of \bt_p{value} is
1384 @sa bt_value_array_append_element() —
1385 Appends a value to an array value.
1387 extern bt_value_array_set_element_by_index_status
1388 bt_value_array_set_element_by_index(bt_value
*value
, uint64_t index
,
1389 bt_value
*element_value
) __BT_NOEXCEPT
;
1393 Borrows the element at index \bt_p{index} from the array value
1397 Array value from which to borrow the element at index \bt_p{index}.
1399 Index of the element to borrow from \bt_p{value}.
1403 \em Borrowed reference of the element of \bt_p{value} at index
1406 The returned pointer remains valid until \bt_p{value} is modified.
1409 @bt_pre_not_null{value}
1410 @bt_pre_is_array_val{value}
1412 \bt_p{index} is less than the length of \bt_p{value} (as returned by
1413 bt_value_array_get_length()).
1415 @sa bt_value_array_borrow_element_by_index_const() —
1416 \c const version of this function.
1418 extern bt_value
*bt_value_array_borrow_element_by_index(bt_value
*value
,
1419 uint64_t index
) __BT_NOEXCEPT
;
1423 Borrows the element at index \bt_p{index} from the array value
1424 \bt_p{value} (\c const version).
1426 See bt_value_array_borrow_element_by_index().
1428 extern const bt_value
*bt_value_array_borrow_element_by_index_const(
1429 const bt_value
*value
, uint64_t index
) __BT_NOEXCEPT
;
1433 Returns the length of the array value \bt_p{value}.
1436 Array value of which to get the length.
1439 Length (number of contained elements) of \bt_p{value}.
1441 @bt_pre_not_null{value}
1442 @bt_pre_is_array_val{value}
1444 @sa bt_value_array_is_empty() —
1445 Returns whether or not an array value is empty.
1447 extern uint64_t bt_value_array_get_length(const bt_value
*value
) __BT_NOEXCEPT
;
1451 Returns whether or not the array value \bt_p{value} is empty.
1454 Array value to check.
1457 #BT_TRUE if \bt_p{value} is empty (has the length 0).
1459 @bt_pre_not_null{value}
1460 @bt_pre_is_array_val{value}
1462 @sa bt_value_array_get_length() —
1463 Returns the length of an array value.
1466 bt_bool
bt_value_array_is_empty(const bt_value
*value
) __BT_NOEXCEPT
1468 return bt_value_array_get_length(value
) == 0;
1480 Creates and returns an empty map value.
1482 The returned value has the type #BT_VALUE_TYPE_MAP.
1485 New map value reference, or \c NULL on memory error.
1487 extern bt_value
*bt_value_map_create(void) __BT_NOEXCEPT
;
1491 Status codes for the <code>bt_value_map_insert_*()</code> functions.
1493 typedef enum bt_value_map_insert_entry_status
{
1498 BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1504 BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1505 } bt_value_map_insert_entry_status
;
1509 Inserts or replaces an entry with the key \bt_p{key} and the value
1510 \bt_p{entry_value} in the map value \bt_p{value}.
1512 To insert an entry having a null value, pass #bt_value_null as
1515 On success, if \bt_p{value} already contains an entry with key
1516 \bt_p{key}, this function replaces the existing entry's value with
1520 Map value in which to insert or replace an entry with key \bt_p{key}
1521 and value \bt_p{entry_value}.
1523 Key of the entry to insert or replace in \bt_p{value} (copied).
1524 @param[in] entry_value
1525 Value of the entry to insert or replace in \bt_p{value}.
1527 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1529 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1532 @bt_pre_not_null{value}
1533 @bt_pre_is_map_val{value}
1535 @bt_pre_not_null{key}
1536 @bt_pre_not_null{entry_value}
1538 \bt_p{entry_value} does not contain \bt_p{value}, recursively.
1540 @sa bt_value_map_insert_bool_entry() —
1541 Creates a boolean value and uses it to insert an entry in a map
1543 @sa bt_value_map_insert_unsigned_integer_entry() —
1544 Creates an unsigned integer value and uses it to insert an entry in
1546 @sa bt_value_map_insert_signed_integer_entry() —
1547 Creates a signed value and uses it to insert an entry in a map
1549 @sa bt_value_map_insert_real_entry() —
1550 Creates a real value and uses it to insert an entry in a map value.
1551 @sa bt_value_map_insert_string_entry() —
1552 Creates a string value and uses it to insert an entry in a map
1554 @sa bt_value_map_insert_empty_array_entry() —
1555 Creates an empty array value and uses it to insert an entry in a map
1557 @sa bt_value_map_insert_empty_map_entry() —
1558 Creates a map value and uses it to insert an entry in a map value.
1560 extern bt_value_map_insert_entry_status
bt_value_map_insert_entry(
1561 bt_value
*value
, const char *key
,
1562 bt_value
*entry_value
) __BT_NOEXCEPT
;
1566 Creates a boolean value initialized to \bt_p{raw_value} and
1567 inserts or replaces an entry with the key \bt_p{key} and this value
1568 in the map value \bt_p{value}.
1570 On success, if \bt_p{value} already contains an entry with key
1571 \bt_p{key}, this function replaces the existing entry's value with the
1572 created boolean value.
1575 Map value in which to insert or replace an entry with key \bt_p{key}
1576 and the created boolean value.
1578 Key of the entry to insert or replace in \bt_p{value} (copied).
1579 @param[in] raw_value
1580 Initial raw value of the boolean value to create.
1582 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1584 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1587 @bt_pre_not_null{value}
1588 @bt_pre_is_map_val{value}
1590 @bt_pre_not_null{key}
1592 @sa bt_value_map_insert_entry() —
1593 Inserts an entry with an existing value in a map value.
1595 extern bt_value_map_insert_entry_status
bt_value_map_insert_bool_entry(
1596 bt_value
*value
, const char *key
, bt_bool raw_value
)
1601 Creates an unsigned integer value initialized to \bt_p{raw_value}
1602 and inserts or replaces an entry with the key \bt_p{key} and this
1603 value in the map value \bt_p{value}.
1605 On success, if \bt_p{value} already contains an entry with key
1606 \bt_p{key}, this function replaces the existing entry's value with the
1607 created unsigned integer value.
1610 Map value in which to insert or replace an entry with key \bt_p{key}
1611 and the created unsigned integer value.
1613 Key of the entry to insert or replace in \bt_p{value} (copied).
1614 @param[in] raw_value
1615 Initial raw value of the unsigned integer value to create.
1617 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1619 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1622 @bt_pre_not_null{value}
1623 @bt_pre_is_map_val{value}
1625 @bt_pre_not_null{key}
1627 @sa bt_value_map_insert_entry() —
1628 Inserts an entry with an existing value in a map value.
1630 extern bt_value_map_insert_entry_status
1631 bt_value_map_insert_unsigned_integer_entry(bt_value
*value
, const char *key
,
1632 uint64_t raw_value
) __BT_NOEXCEPT
;
1636 Creates a signed integer value initialized to \bt_p{raw_value} and
1637 inserts or replaces an entry with the key \bt_p{key} and this value
1638 in the map value \bt_p{value}.
1640 On success, if \bt_p{value} already contains an entry with key
1641 \bt_p{key}, this function replaces the existing entry's value with the
1642 created signed integer value.
1645 Map value in which to insert or replace an entry with key \bt_p{key}
1646 and the created signed integer value.
1648 Key of the entry to insert or replace in \bt_p{value} (copied).
1649 @param[in] raw_value
1650 Initial raw value of the signed integer value to create.
1652 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1654 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1657 @bt_pre_not_null{value}
1658 @bt_pre_is_map_val{value}
1660 @bt_pre_not_null{key}
1662 @sa bt_value_map_insert_entry() —
1663 Inserts an entry with an existing value in a map value.
1665 extern bt_value_map_insert_entry_status
1666 bt_value_map_insert_signed_integer_entry(bt_value
*value
, const char *key
,
1667 int64_t raw_value
) __BT_NOEXCEPT
;
1671 Creates a real value initialized to \bt_p{raw_value} and inserts or
1672 replaces an entry with the key \bt_p{key} and this value in the map
1675 On success, if \bt_p{value} already contains an entry with key
1676 \bt_p{key}, this function replaces the existing entry's value with the
1680 Map value in which to insert or replace an entry with key \bt_p{key}
1681 and the created real value.
1683 Key of the entry to insert or replace in \bt_p{value} (copied).
1684 @param[in] raw_value
1685 Initial raw value of the real value to create.
1687 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1689 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1692 @bt_pre_not_null{value}
1693 @bt_pre_is_map_val{value}
1695 @bt_pre_not_null{key}
1697 @sa bt_value_map_insert_entry() —
1698 Inserts an entry with an existing value in a map value.
1700 extern bt_value_map_insert_entry_status
bt_value_map_insert_real_entry(
1701 bt_value
*value
, const char *key
, double raw_value
)
1706 Creates a string value initialized to a copy of \bt_p{raw_value} and
1707 inserts or replaces an entry with the key \bt_p{key} and this value
1708 in the map value \bt_p{value}.
1710 On success, if \bt_p{value} already contains an entry with key
1711 \bt_p{key}, this function replaces the existing entry's value with the
1712 created string value.
1715 Map value in which to insert or replace an entry with key \bt_p{key}
1716 and the created string value.
1718 Key of the entry to insert or replace in \bt_p{value} (copied).
1719 @param[in] raw_value
1720 Initial raw value of the string value to create (copied).
1722 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1724 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1727 @bt_pre_not_null{value}
1728 @bt_pre_is_map_val{value}
1730 @bt_pre_not_null{key}
1732 @sa bt_value_map_insert_entry() —
1733 Inserts an entry with an existing value in a map value.
1735 extern bt_value_map_insert_entry_status
1736 bt_value_map_insert_string_entry(bt_value
*value
, const char *key
,
1737 const char *raw_value
) __BT_NOEXCEPT
;
1741 Creates an empty array value and inserts or replaces an entry with
1742 the key \bt_p{key} and this value in the map value \bt_p{value}.
1744 On success, if \bt_p{entry_value} is not \c NULL, this function sets
1745 \bt_p{*entry_value} to a \em borrowed reference of the created empty
1748 On success, if \bt_p{value} already contains an entry with key
1749 \bt_p{key}, this function replaces the existing entry's value with the
1750 created empty array value.
1753 Map value in which to insert or replace an entry with key \bt_p{key}
1754 and the created empty array value.
1756 Key of the entry to insert or replace in \bt_p{value} (copied).
1757 @param[out] entry_value
1758 <strong>On success, if not \c NULL</strong>, \bt_p{*entry_value} is
1759 a \em borrowed reference of the created empty array value.
1761 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1763 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1766 @bt_pre_not_null{value}
1767 @bt_pre_is_map_val{value}
1769 @bt_pre_not_null{key}
1771 @sa bt_value_map_insert_entry() —
1772 Inserts an entry with an existing value in a map value.
1774 extern bt_value_map_insert_entry_status
1775 bt_value_map_insert_empty_array_entry(bt_value
*value
, const char *key
,
1776 bt_value
**entry_value
) __BT_NOEXCEPT
;
1780 Creates an empty map value and inserts or replaces an entry with
1781 the key \bt_p{key} and this value in the map value \bt_p{value}.
1783 On success, if \bt_p{entry_value} is not \c NULL, this function sets
1784 \bt_p{*entry_value} to a \em borrowed reference of the created empty map
1787 On success, if \bt_p{value} already contains an entry with key
1788 \bt_p{key}, this function replaces the existing entry's value with the
1789 created empty map value.
1792 Map value in which to insert or replace an entry with key \bt_p{key}
1793 and the created empty map value.
1795 Key of the entry to insert or replace in \bt_p{value} (copied).
1796 @param[out] entry_value
1797 <strong>On success, if not \c NULL</strong>, \bt_p{*entry_value} is
1798 a \em borrowed reference of the created empty map value.
1800 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1802 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1805 @bt_pre_not_null{value}
1806 @bt_pre_is_map_val{value}
1808 @bt_pre_not_null{key}
1810 @sa bt_value_map_insert_entry() —
1811 Inserts an entry with an existing value in a map value.
1813 extern bt_value_map_insert_entry_status
1814 bt_value_map_insert_empty_map_entry(bt_value
*value
, const char *key
,
1815 bt_value
**entry_value
) __BT_NOEXCEPT
;
1819 Borrows the value of the entry with the key \bt_p{key} in the map
1822 If no entry with key \bt_p{key} exists in \bt_p{value}, this function
1826 Map value from which to borrow the value of the entry with the
1829 Key of the entry from which to borrow the value in \bt_p{value}.
1833 \em Borrowed reference of the value of the entry with key \bt_p{key}
1834 in \bt_p{value}, or \c NULL if none.
1836 The returned pointer remains valid until \bt_p{value} is modified.
1839 @bt_pre_not_null{value}
1840 @bt_pre_is_array_val{value}
1841 @bt_pre_not_null{key}
1843 @sa bt_value_map_borrow_entry_value_const() —
1844 \c const version of this function.
1845 @sa bt_value_map_has_entry() —
1846 Returns whether or not a map value has an entry with a given key.
1848 extern bt_value
*bt_value_map_borrow_entry_value(
1849 bt_value
*value
, const char *key
) __BT_NOEXCEPT
;
1853 Borrows the value of the entry with the key \bt_p{key} in the map
1854 value \bt_p{value} (\c const version).
1856 See bt_value_map_borrow_entry_value().
1858 extern const bt_value
*bt_value_map_borrow_entry_value_const(
1859 const bt_value
*value
, const char *key
) __BT_NOEXCEPT
;
1863 Status codes for #bt_value_map_foreach_entry_func.
1865 typedef enum bt_value_map_foreach_entry_func_status
{
1870 BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1874 Interrupt the iteration process.
1876 BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_INTERRUPT
= __BT_FUNC_STATUS_INTERRUPTED
,
1882 BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1888 BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
1889 } bt_value_map_foreach_entry_func_status
;
1893 User function for bt_value_map_foreach_entry().
1895 This is the type of the user function that bt_value_map_foreach_entry()
1896 calls for each entry of the map value.
1899 Key of the map value entry.
1901 Value of the map value entry.
1902 @param[in] user_data
1903 User data, as passed as the \bt_p{user_data} parameter of
1904 bt_value_map_foreach_entry().
1906 @retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_OK
1908 @retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_INTERRUPT
1909 Interrupt the iteration process.
1910 @retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_MEMORY_ERROR
1912 @retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_ERROR
1915 @bt_pre_not_null{key}
1916 @bt_pre_not_null{value}
1918 @sa bt_value_map_foreach_entry() —
1919 Iterates the entries of a map value.
1921 typedef bt_value_map_foreach_entry_func_status
1922 (* bt_value_map_foreach_entry_func
)(const char *key
,
1923 bt_value
*value
, void *user_data
);
1927 Status codes for bt_value_map_foreach_entry().
1929 typedef enum bt_value_map_foreach_entry_status
{
1934 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1938 User function interrupted the iteration process.
1940 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_INTERRUPTED
= __BT_FUNC_STATUS_INTERRUPTED
,
1944 User function error.
1946 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_USER_ERROR
= __BT_FUNC_STATUS_USER_ERROR
,
1952 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1958 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
1959 } bt_value_map_foreach_entry_status
;
1963 Iterates the entries of the map value \bt_p{value}, calling
1964 \bt_p{user_func} for each entry.
1966 This function iterates the entries of \bt_p{value} in no particular
1970 You must \em not modify \bt_p{value} during the iteration process.
1972 \bt_p{user_func} receives \bt_p{user_data} as its last parameter.
1974 The iteration process stops when one of:
1976 - \bt_p{user_func} was called for each entry.
1977 - \bt_p{user_func} does not return
1978 #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_OK.
1981 Map value of which to iterate the entries.
1982 @param[in] user_func
1983 User function to call for each entry of \bt_p{value}.
1984 @param[in] user_data
1985 User data to pass as the \bt_p{user_data} parameter of each call to
1988 @retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_OK
1990 @retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_INTERRUPTED
1991 \bt_p{user_func} returned
1992 #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_INTERRUPT to interrupt the
1994 @retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_USER_ERROR
1995 \bt_p{user_func} returned
1996 #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_ERROR.
1997 @retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_MEMORY_ERROR
1999 @retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_ERROR
2000 Other error caused the <code>bt_value_map_foreach_entry()</code>
2003 @bt_pre_not_null{value}
2004 @bt_pre_is_map_val{value}
2005 @bt_pre_not_null{user_func}
2007 @sa bt_value_map_foreach_entry_const() —
2008 \c const version of this function.
2009 @sa bt_value_map_borrow_entry_value() —
2010 Borrows the value of a specific map value entry.
2012 extern bt_value_map_foreach_entry_status
bt_value_map_foreach_entry(
2013 bt_value
*value
, bt_value_map_foreach_entry_func user_func
,
2014 void *user_data
) __BT_NOEXCEPT
;
2018 Status codes for #bt_value_map_foreach_entry_const_func.
2020 typedef enum bt_value_map_foreach_entry_const_func_status
{
2025 BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2029 Interrupt the iteration process.
2031 BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_INTERRUPT
= __BT_FUNC_STATUS_INTERRUPTED
,
2037 BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2043 BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
2044 } bt_value_map_foreach_entry_const_func_status
;
2048 User function for bt_value_map_foreach_entry_const_func().
2050 This is the type of the user function that
2051 bt_value_map_foreach_entry_const_func() calls for each entry of the map
2055 Key of the map value entry.
2057 Value of the map value entry.
2058 @param[in] user_data
2061 @retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_OK
2063 @retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_INTERRUPT
2064 Interrupt the iteration process.
2065 @retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_MEMORY_ERROR
2067 @retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_ERROR
2070 @bt_pre_not_null{key}
2071 @bt_pre_not_null{value}
2073 @sa bt_value_map_foreach_entry_const() —
2074 Iterates the entries of a \c const map value.
2076 typedef bt_value_map_foreach_entry_const_func_status
2077 (* bt_value_map_foreach_entry_const_func
)(const char *key
,
2078 const bt_value
*value
, void *user_data
);
2082 Status codes for bt_value_map_foreach_entry_const().
2084 typedef enum bt_value_map_foreach_entry_const_status
{
2089 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2093 User function interrupted the iteration process.
2095 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_INTERRUPTED
= __BT_FUNC_STATUS_INTERRUPTED
,
2099 User function error.
2101 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_USER_ERROR
= __BT_FUNC_STATUS_USER_ERROR
,
2107 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2113 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
2114 } bt_value_map_foreach_entry_const_status
;
2118 Iterates the entries of the map value \bt_p{value}, calling
2119 \bt_p{user_func} for each entry (\c const version).
2121 See bt_value_map_foreach_entry().
2123 @sa bt_value_map_borrow_entry_value_const() —
2124 Borrows the value of a specific map value entry.
2126 extern bt_value_map_foreach_entry_const_status
bt_value_map_foreach_entry_const(
2127 const bt_value
*value
,
2128 bt_value_map_foreach_entry_const_func user_func
,
2129 void *user_data
) __BT_NOEXCEPT
;
2133 Returns the size of the map value \bt_p{value}.
2136 Map value of which to get the size.
2139 Size (number of contained entries) of \bt_p{value}.
2141 @bt_pre_not_null{value}
2142 @bt_pre_is_map_val{value}
2144 @sa bt_value_map_is_empty() —
2145 Returns whether or not a map value is empty.
2147 extern uint64_t bt_value_map_get_size(const bt_value
*value
) __BT_NOEXCEPT
;
2151 Returns whether or not the map value \bt_p{value} is empty.
2157 #BT_TRUE if \bt_p{value} is empty (has the size 0).
2159 @bt_pre_not_null{value}
2160 @bt_pre_is_map_val{value}
2162 @sa bt_value_map_get_size() —
2163 Returns the size of a map value.
2166 bt_bool
bt_value_map_is_empty(const bt_value
*value
) __BT_NOEXCEPT
2168 return bt_value_map_get_size(value
) == 0;
2173 Returns whether or not the map value \bt_p{value} has an entry with
2182 #BT_TRUE if \bt_p{value} has an entry with the key \bt_p{key}.
2184 @bt_pre_not_null{value}
2185 @bt_pre_is_map_val{value}
2186 @bt_pre_not_null{key}
2188 @sa bt_value_map_borrow_entry_value_const() —
2189 Borrows the value of a specific map value entry.
2191 extern bt_bool
bt_value_map_has_entry(const bt_value
*value
,
2192 const char *key
) __BT_NOEXCEPT
;
2196 Status codes for bt_value_map_extend().
2198 typedef enum bt_value_map_extend_status
{
2203 BT_VALUE_MAP_EXTEND_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2209 BT_VALUE_MAP_EXTEND_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2210 } bt_value_map_extend_status
;
2214 Extends the map value \bt_p{value} with the map value
2215 \bt_p{extension_value}.
2217 For each entry in \bt_p{extension_value}, this function calls
2218 bt_value_map_insert_entry() to insert or replace it in the map value
2237 \bt_p{extension_value}
2249 The map value \bt_p{value} becomes:
2260 Map value to extend.
2261 @param[in] extension_value
2262 Extension map value.
2264 @retval #BT_VALUE_MAP_EXTEND_STATUS_OK
2266 @retval #BT_VALUE_MAP_EXTEND_STATUS_MEMORY_ERROR
2269 @bt_pre_not_null{value}
2270 @bt_pre_is_map_val{value}
2271 @bt_pre_not_null{extension_value}
2272 @bt_pre_is_map_val{extension_value}
2274 @sa bt_value_copy() —
2275 Deep-copies a value.
2277 extern bt_value_map_extend_status
bt_value_map_extend(
2278 bt_value
*value
, const bt_value
*extension_value
) __BT_NOEXCEPT
;
2289 Status codes for bt_value_copy().
2291 typedef enum bt_value_copy_status
{
2296 BT_VALUE_COPY_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2302 BT_VALUE_COPY_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2303 } bt_value_copy_status
;
2307 Deep-copies a value object.
2309 This function deep-copies \bt_p{value} and sets \bt_p{*copy} to the
2312 Because \bt_p{*copy} is a deep copy, it does not contain, recursively,
2313 any reference that \bt_p{value} contains, but the raw values are
2318 @param[in] copy_value
2319 <strong>On success</strong>, \bt_p{*copy_value} is a deep copy of
2322 @retval #BT_VALUE_COPY_STATUS_OK
2324 @retval #BT_VALUE_COPY_STATUS_MEMORY_ERROR
2327 @bt_pre_not_null{value}
2328 @bt_pre_not_null{copy_value}
2330 extern bt_value_copy_status
bt_value_copy(const bt_value
*value
,
2331 bt_value
**copy_value
) __BT_NOEXCEPT
;
2335 Returns whether or not the value \bt_p{a_value} is equal,
2336 recursively, to \bt_p{b_value}.
2339 If you want to know whether or not a value is a null value, you can
2340 also directly compare its pointer to the #bt_value_null variable.
2348 #BT_TRUE if \bt_p{a_value} is equal, recursively, to \bt_p{b_value}.
2350 @bt_pre_not_null{a_value}
2351 @bt_pre_not_null{b_value}
2353 extern bt_bool
bt_value_is_equal(const bt_value
*a_value
,
2354 const bt_value
*b_value
) __BT_NOEXCEPT
;
2359 @name Reference count
2365 Increments the \ref api-fund-shared-object "reference count" of
2366 the value \bt_p{value}.
2370 Value of which to increment the reference count.
2375 @sa bt_value_put_ref() —
2376 Decrements the reference count of a value.
2378 extern void bt_value_get_ref(const bt_value
*value
) __BT_NOEXCEPT
;
2382 Decrements the \ref api-fund-shared-object "reference count" of
2383 the value \bt_p{value}.
2387 Value of which to decrement the reference count.
2392 @sa bt_value_get_ref() —
2393 Increments the reference count of a value.
2395 extern void bt_value_put_ref(const bt_value
*value
) __BT_NOEXCEPT
;
2399 Decrements the reference count of the value \bt_p{_value}, and then
2400 sets \bt_p{_value} to \c NULL.
2404 Value of which to decrement the reference count.
2406 Can contain \c NULL.
2409 @bt_pre_assign_expr{_value}
2411 #define BT_VALUE_PUT_REF_AND_RESET(_value) \
2413 bt_value_put_ref(_value); \
2419 Decrements the reference count of the value \bt_p{_dst}, sets
2420 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
2422 This macro effectively moves a value reference from the expression
2423 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
2424 \bt_p{_dst} reference.
2428 Destination expression.
2430 Can contain \c NULL.
2436 Can contain \c NULL.
2439 @bt_pre_assign_expr{_dst}
2440 @bt_pre_assign_expr{_src}
2442 #define BT_VALUE_MOVE_REF(_dst, _src) \
2444 bt_value_put_ref(_dst); \
2457 #endif /* BABELTRACE2_VALUE_H */