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
);
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
)
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
)
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
)
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
)
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
)
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
)
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
)
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
)
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
)
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);
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
);
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
);
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
);
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);
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
);
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
,
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
);
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);
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
);
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
);
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
);
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);
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
);
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
);
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
);
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);
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
);
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
);
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
);
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);
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
);
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
);
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
);
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
,
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
);
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
);
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
);
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
);
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
);
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
,
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
);
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
);
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
)
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);
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
, bt_value
*entry_value
);
1565 Creates a boolean value initialized to \bt_p{raw_value} and
1566 inserts or replaces an entry with the key \bt_p{key} and this value
1567 in the map value \bt_p{value}.
1569 On success, if \bt_p{value} already contains an entry with key
1570 \bt_p{key}, this function replaces the existing entry's value with the
1571 created boolean value.
1574 Map value in which to insert or replace an entry with key \bt_p{key}
1575 and the created boolean value.
1577 Key of the entry to insert or replace in \bt_p{value} (copied).
1578 @param[in] raw_value
1579 Initial raw value of the boolean value to create.
1581 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1583 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1586 @bt_pre_not_null{value}
1587 @bt_pre_is_map_val{value}
1589 @bt_pre_not_null{key}
1591 @sa bt_value_map_insert_entry() —
1592 Inserts an entry with an existing value in a map value.
1594 extern bt_value_map_insert_entry_status
bt_value_map_insert_bool_entry(
1595 bt_value
*value
, const char *key
, bt_bool raw_value
);
1599 Creates an unsigned integer value initialized to \bt_p{raw_value}
1600 and inserts or replaces an entry with the key \bt_p{key} and this
1601 value in the map value \bt_p{value}.
1603 On success, if \bt_p{value} already contains an entry with key
1604 \bt_p{key}, this function replaces the existing entry's value with the
1605 created unsigned integer value.
1608 Map value in which to insert or replace an entry with key \bt_p{key}
1609 and the created unsigned integer value.
1611 Key of the entry to insert or replace in \bt_p{value} (copied).
1612 @param[in] raw_value
1613 Initial raw value of the unsigned integer value to create.
1615 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1617 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1620 @bt_pre_not_null{value}
1621 @bt_pre_is_map_val{value}
1623 @bt_pre_not_null{key}
1625 @sa bt_value_map_insert_entry() —
1626 Inserts an entry with an existing value in a map value.
1628 extern bt_value_map_insert_entry_status
1629 bt_value_map_insert_unsigned_integer_entry(bt_value
*value
, const char *key
,
1630 uint64_t raw_value
);
1634 Creates a signed integer value initialized to \bt_p{raw_value} and
1635 inserts or replaces an entry with the key \bt_p{key} and this value
1636 in the map value \bt_p{value}.
1638 On success, if \bt_p{value} already contains an entry with key
1639 \bt_p{key}, this function replaces the existing entry's value with the
1640 created signed integer value.
1643 Map value in which to insert or replace an entry with key \bt_p{key}
1644 and the created signed integer value.
1646 Key of the entry to insert or replace in \bt_p{value} (copied).
1647 @param[in] raw_value
1648 Initial raw value of the signed integer value to create.
1650 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1652 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1655 @bt_pre_not_null{value}
1656 @bt_pre_is_map_val{value}
1658 @bt_pre_not_null{key}
1660 @sa bt_value_map_insert_entry() —
1661 Inserts an entry with an existing value in a map value.
1663 extern bt_value_map_insert_entry_status
1664 bt_value_map_insert_signed_integer_entry(bt_value
*value
, const char *key
,
1669 Creates a real value initialized to \bt_p{raw_value} and inserts or
1670 replaces an entry with the key \bt_p{key} and this value in the map
1673 On success, if \bt_p{value} already contains an entry with key
1674 \bt_p{key}, this function replaces the existing entry's value with the
1678 Map value in which to insert or replace an entry with key \bt_p{key}
1679 and the created real value.
1681 Key of the entry to insert or replace in \bt_p{value} (copied).
1682 @param[in] raw_value
1683 Initial raw value of the real value to create.
1685 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1687 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1690 @bt_pre_not_null{value}
1691 @bt_pre_is_map_val{value}
1693 @bt_pre_not_null{key}
1695 @sa bt_value_map_insert_entry() —
1696 Inserts an entry with an existing value in a map value.
1698 extern bt_value_map_insert_entry_status
bt_value_map_insert_real_entry(
1699 bt_value
*value
, const char *key
, double raw_value
);
1703 Creates a string value initialized to a copy of \bt_p{raw_value} and
1704 inserts or replaces an entry with the key \bt_p{key} and this value
1705 in the map value \bt_p{value}.
1707 On success, if \bt_p{value} already contains an entry with key
1708 \bt_p{key}, this function replaces the existing entry's value with the
1709 created string value.
1712 Map value in which to insert or replace an entry with key \bt_p{key}
1713 and the created string value.
1715 Key of the entry to insert or replace in \bt_p{value} (copied).
1716 @param[in] raw_value
1717 Initial raw value of the string value to create (copied).
1719 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1721 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1724 @bt_pre_not_null{value}
1725 @bt_pre_is_map_val{value}
1727 @bt_pre_not_null{key}
1729 @sa bt_value_map_insert_entry() —
1730 Inserts an entry with an existing value in a map value.
1732 extern bt_value_map_insert_entry_status
1733 bt_value_map_insert_string_entry(bt_value
*value
, const char *key
,
1734 const char *raw_value
);
1738 Creates an empty array value and inserts or replaces an entry with
1739 the key \bt_p{key} and this value in the map value \bt_p{value}.
1741 On success, if \bt_p{entry_value} is not \c NULL, this function sets
1742 \bt_p{*entry_value} to a \em borrowed reference of the created empty
1745 On success, if \bt_p{value} already contains an entry with key
1746 \bt_p{key}, this function replaces the existing entry's value with the
1747 created empty array value.
1750 Map value in which to insert or replace an entry with key \bt_p{key}
1751 and the created empty array value.
1753 Key of the entry to insert or replace in \bt_p{value} (copied).
1754 @param[out] entry_value
1755 <strong>On success, if not \c NULL</strong>, \bt_p{*entry_value} is
1756 a \em borrowed reference of the created empty array value.
1758 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1760 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1763 @bt_pre_not_null{value}
1764 @bt_pre_is_map_val{value}
1766 @bt_pre_not_null{key}
1768 @sa bt_value_map_insert_entry() —
1769 Inserts an entry with an existing value in a map value.
1771 extern bt_value_map_insert_entry_status
1772 bt_value_map_insert_empty_array_entry(bt_value
*value
, const char *key
,
1773 bt_value
**entry_value
);
1777 Creates an empty map value and inserts or replaces an entry with
1778 the key \bt_p{key} and this value in the map value \bt_p{value}.
1780 On success, if \bt_p{entry_value} is not \c NULL, this function sets
1781 \bt_p{*entry_value} to a \em borrowed reference of the created empty map
1784 On success, if \bt_p{value} already contains an entry with key
1785 \bt_p{key}, this function replaces the existing entry's value with the
1786 created empty map value.
1789 Map value in which to insert or replace an entry with key \bt_p{key}
1790 and the created empty map value.
1792 Key of the entry to insert or replace in \bt_p{value} (copied).
1793 @param[out] entry_value
1794 <strong>On success, if not \c NULL</strong>, \bt_p{*entry_value} is
1795 a \em borrowed reference of the created empty map value.
1797 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1799 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1802 @bt_pre_not_null{value}
1803 @bt_pre_is_map_val{value}
1805 @bt_pre_not_null{key}
1807 @sa bt_value_map_insert_entry() —
1808 Inserts an entry with an existing value in a map value.
1810 extern bt_value_map_insert_entry_status
1811 bt_value_map_insert_empty_map_entry(bt_value
*value
, const char *key
,
1812 bt_value
**entry_value
);
1816 Borrows the value of the entry with the key \bt_p{key} in the map
1819 If no entry with key \bt_p{key} exists in \bt_p{value}, this function
1823 Map value from which to borrow the value of the entry with the
1826 Key of the entry from which to borrow the value in \bt_p{value}.
1830 \em Borrowed reference of the value of the entry with key \bt_p{key}
1831 in \bt_p{value}, or \c NULL if none.
1833 The returned pointer remains valid until \bt_p{value} is modified.
1836 @bt_pre_not_null{value}
1837 @bt_pre_is_array_val{value}
1838 @bt_pre_not_null{key}
1840 @sa bt_value_map_borrow_entry_value_const() —
1841 \c const version of this function.
1842 @sa bt_value_map_has_entry() —
1843 Returns whether or not a map value has an entry with a given key.
1845 extern bt_value
*bt_value_map_borrow_entry_value(
1846 bt_value
*value
, const char *key
);
1850 Borrows the value of the entry with the key \bt_p{key} in the map
1851 value \bt_p{value} (\c const version).
1853 See bt_value_map_borrow_entry_value().
1855 extern const bt_value
*bt_value_map_borrow_entry_value_const(
1856 const bt_value
*value
, const char *key
);
1860 Status codes for #bt_value_map_foreach_entry_func.
1862 typedef enum bt_value_map_foreach_entry_func_status
{
1867 BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1871 Interrupt the iteration process.
1873 BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_INTERRUPT
= __BT_FUNC_STATUS_INTERRUPTED
,
1879 BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1885 BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
1886 } bt_value_map_foreach_entry_func_status
;
1890 User function for bt_value_map_foreach_entry().
1892 This is the type of the user function that bt_value_map_foreach_entry()
1893 calls for each entry of the map value.
1896 Key of the map value entry.
1898 Value of the map value entry.
1899 @param[in] user_data
1900 User data, as passed as the \bt_p{user_data} parameter of
1901 bt_value_map_foreach_entry().
1903 @retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_OK
1905 @retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_INTERRUPT
1906 Interrupt the iteration process.
1907 @retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_MEMORY_ERROR
1909 @retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_ERROR
1912 @bt_pre_not_null{key}
1913 @bt_pre_not_null{value}
1915 @sa bt_value_map_foreach_entry() —
1916 Iterates the entries of a map value.
1918 typedef bt_value_map_foreach_entry_func_status
1919 (* bt_value_map_foreach_entry_func
)(const char *key
,
1920 bt_value
*value
, void *user_data
);
1924 Status codes for bt_value_map_foreach_entry().
1926 typedef enum bt_value_map_foreach_entry_status
{
1931 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1935 User function interrupted the iteration process.
1937 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_INTERRUPTED
= __BT_FUNC_STATUS_INTERRUPTED
,
1941 User function error.
1943 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_USER_ERROR
= __BT_FUNC_STATUS_USER_ERROR
,
1949 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1955 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
1956 } bt_value_map_foreach_entry_status
;
1960 Iterates the entries of the map value \bt_p{value}, calling
1961 \bt_p{user_func} for each entry.
1963 This function iterates the entries of \bt_p{value} in no particular
1967 You must \em not modify \bt_p{value} during the iteration process.
1969 \bt_p{user_func} receives \bt_p{user_data} as its last parameter.
1971 The iteration process stops when one of:
1973 - \bt_p{user_func} was called for each entry.
1974 - \bt_p{user_func} does not return
1975 #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_OK.
1978 Map value of which to iterate the entries.
1979 @param[in] user_func
1980 User function to call for each entry of \bt_p{value}.
1981 @param[in] user_data
1982 User data to pass as the \bt_p{user_data} parameter of each call to
1985 @retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_OK
1987 @retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_INTERRUPTED
1988 \bt_p{user_func} returned
1989 #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_INTERRUPT to interrupt the
1991 @retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_USER_ERROR
1992 \bt_p{user_func} returned
1993 #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_ERROR.
1994 @retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_MEMORY_ERROR
1996 @retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_ERROR
1997 Other error caused the <code>bt_value_map_foreach_entry()</code>
2000 @bt_pre_not_null{value}
2001 @bt_pre_is_map_val{value}
2002 @bt_pre_not_null{user_func}
2004 @sa bt_value_map_foreach_entry_const() —
2005 \c const version of this function.
2006 @sa bt_value_map_borrow_entry_value() —
2007 Borrows the value of a specific map value entry.
2009 extern bt_value_map_foreach_entry_status
bt_value_map_foreach_entry(
2010 bt_value
*value
, bt_value_map_foreach_entry_func user_func
,
2015 Status codes for #bt_value_map_foreach_entry_const_func.
2017 typedef enum bt_value_map_foreach_entry_const_func_status
{
2022 BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2026 Interrupt the iteration process.
2028 BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_INTERRUPT
= __BT_FUNC_STATUS_INTERRUPTED
,
2034 BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2040 BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
2041 } bt_value_map_foreach_entry_const_func_status
;
2045 User function for bt_value_map_foreach_entry_const_func().
2047 This is the type of the user function that
2048 bt_value_map_foreach_entry_const_func() calls for each entry of the map
2052 Key of the map value entry.
2054 Value of the map value entry.
2055 @param[in] user_data
2058 @retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_OK
2060 @retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_INTERRUPT
2061 Interrupt the iteration process.
2062 @retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_MEMORY_ERROR
2064 @retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_ERROR
2067 @bt_pre_not_null{key}
2068 @bt_pre_not_null{value}
2070 @sa bt_value_map_foreach_entry_const() —
2071 Iterates the entries of a \c const map value.
2073 typedef bt_value_map_foreach_entry_const_func_status
2074 (* bt_value_map_foreach_entry_const_func
)(const char *key
,
2075 const bt_value
*value
, void *user_data
);
2079 Status codes for bt_value_map_foreach_entry_const().
2081 typedef enum bt_value_map_foreach_entry_const_status
{
2086 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2090 User function interrupted the iteration process.
2092 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_INTERRUPTED
= __BT_FUNC_STATUS_INTERRUPTED
,
2096 User function error.
2098 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_USER_ERROR
= __BT_FUNC_STATUS_USER_ERROR
,
2104 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2110 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
2111 } bt_value_map_foreach_entry_const_status
;
2115 Iterates the entries of the map value \bt_p{value}, calling
2116 \bt_p{user_func} for each entry (\c const version).
2118 See bt_value_map_foreach_entry().
2120 @sa bt_value_map_borrow_entry_value_const() —
2121 Borrows the value of a specific map value entry.
2123 extern bt_value_map_foreach_entry_const_status
bt_value_map_foreach_entry_const(
2124 const bt_value
*value
,
2125 bt_value_map_foreach_entry_const_func user_func
,
2130 Returns the size of the map value \bt_p{value}.
2133 Map value of which to get the size.
2136 Size (number of contained entries) of \bt_p{value}.
2138 @bt_pre_not_null{value}
2139 @bt_pre_is_map_val{value}
2141 @sa bt_value_map_is_empty() —
2142 Returns whether or not a map value is empty.
2144 extern uint64_t bt_value_map_get_size(const bt_value
*value
);
2148 Returns whether or not the map value \bt_p{value} is empty.
2154 #BT_TRUE if \bt_p{value} is empty (has the size 0).
2156 @bt_pre_not_null{value}
2157 @bt_pre_is_map_val{value}
2159 @sa bt_value_map_get_size() —
2160 Returns the size of a map value.
2163 bt_bool
bt_value_map_is_empty(const bt_value
*value
)
2165 return bt_value_map_get_size(value
) == 0;
2170 Returns whether or not the map value \bt_p{value} has an entry with
2179 #BT_TRUE if \bt_p{value} has an entry with the key \bt_p{key}.
2181 @bt_pre_not_null{value}
2182 @bt_pre_is_map_val{value}
2183 @bt_pre_not_null{key}
2185 @sa bt_value_map_borrow_entry_value_const() —
2186 Borrows the value of a specific map value entry.
2188 extern bt_bool
bt_value_map_has_entry(const bt_value
*value
,
2193 Status codes for bt_value_map_extend().
2195 typedef enum bt_value_map_extend_status
{
2200 BT_VALUE_MAP_EXTEND_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2206 BT_VALUE_MAP_EXTEND_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2207 } bt_value_map_extend_status
;
2211 Extends the map value \bt_p{value} with the map value
2212 \bt_p{extension_value}.
2214 For each entry in \bt_p{extension_value}, this function calls
2215 bt_value_map_insert_entry() to insert or replace it in the map value
2234 \bt_p{extension_value}
2246 The map value \bt_p{value} becomes:
2257 Map value to extend.
2258 @param[in] extension_value
2259 Extension map value.
2261 @retval #BT_VALUE_MAP_EXTEND_STATUS_OK
2263 @retval #BT_VALUE_MAP_EXTEND_STATUS_MEMORY_ERROR
2266 @bt_pre_not_null{value}
2267 @bt_pre_is_map_val{value}
2268 @bt_pre_not_null{extension_value}
2269 @bt_pre_is_map_val{extension_value}
2271 @sa bt_value_copy() —
2272 Deep-copies a value.
2274 extern bt_value_map_extend_status
bt_value_map_extend(
2275 bt_value
*value
, const bt_value
*extension_value
);
2286 Status codes for bt_value_copy().
2288 typedef enum bt_value_copy_status
{
2293 BT_VALUE_COPY_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2299 BT_VALUE_COPY_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2300 } bt_value_copy_status
;
2304 Deep-copies a value object.
2306 This function deep-copies \bt_p{value} and sets \bt_p{*copy} to the
2309 Because \bt_p{*copy} is a deep copy, it does not contain, recursively,
2310 any reference that \bt_p{value} contains, but the raw values are
2315 @param[in] copy_value
2316 <strong>On success</strong>, \bt_p{*copy_value} is a deep copy of
2319 @retval #BT_VALUE_COPY_STATUS_OK
2321 @retval #BT_VALUE_COPY_STATUS_MEMORY_ERROR
2324 @bt_pre_not_null{value}
2325 @bt_pre_not_null{copy_value}
2327 extern bt_value_copy_status
bt_value_copy(const bt_value
*value
,
2328 bt_value
**copy_value
);
2332 Returns whether or not the value \bt_p{a_value} is equal,
2333 recursively, to \bt_p{b_value}.
2336 If you want to know whether or not a value is a null value, you can
2337 also directly compare its pointer to the #bt_value_null variable.
2345 #BT_TRUE if \bt_p{a_value} is equal, recursively, to \bt_p{b_value}.
2347 @bt_pre_not_null{a_value}
2348 @bt_pre_not_null{b_value}
2350 extern bt_bool
bt_value_is_equal(const bt_value
*a_value
,
2351 const bt_value
*b_value
);
2356 @name Reference count
2362 Increments the \ref api-fund-shared-object "reference count" of
2363 the value \bt_p{value}.
2367 Value of which to increment the reference count.
2372 @sa bt_value_put_ref() —
2373 Decrements the reference count of a value.
2375 extern void bt_value_get_ref(const bt_value
*value
);
2379 Decrements the \ref api-fund-shared-object "reference count" of
2380 the value \bt_p{value}.
2384 Value of which to decrement the reference count.
2389 @sa bt_value_get_ref() —
2390 Increments the reference count of a value.
2392 extern void bt_value_put_ref(const bt_value
*value
);
2396 Decrements the reference count of the value \bt_p{_value}, and then
2397 sets \bt_p{_value} to \c NULL.
2401 Value of which to decrement the reference count.
2403 Can contain \c NULL.
2406 @bt_pre_assign_expr{_value}
2408 #define BT_VALUE_PUT_REF_AND_RESET(_value) \
2410 bt_value_put_ref(_value); \
2416 Decrements the reference count of the value \bt_p{_dst}, sets
2417 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
2419 This macro effectively moves a value reference from the expression
2420 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
2421 \bt_p{_dst} reference.
2425 Destination expression.
2427 Can contain \c NULL.
2433 Can contain \c NULL.
2436 @bt_pre_assign_expr{_dst}
2437 @bt_pre_assign_expr{_src}
2439 #define BT_VALUE_MOVE_REF(_dst, _src) \
2441 bt_value_put_ref(_dst); \
2454 #endif /* BABELTRACE2_VALUE_H */