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 #ifndef __BT_IN_BABELTRACE_H
11 # error "Please include <babeltrace2/babeltrace.h> instead."
17 #include <babeltrace2/types.h>
24 @defgroup api-val Values
27 Generic, JSON-like basic data containers.
29 <strong><em>Values</em></strong> are generic data containers. Except for
30 the fact that integer values are explicitly unsigned or signed because
31 of typing limitations,
32 \bt_name values are very similar to <a href="https://json.org/">JSON</a>
35 The value API is completely independent from the rest of the
38 \bt_c_comp initialization parameters, \ref bt_query_executor_create()
39 "query" parameters, as well as trace IR user attributes (for example,
40 bt_event_class_set_user_attributes()) use values.
42 The available value types are:
45 <dt>Scalar values</dt>
49 - Unsigned integer (64-bit range)
50 - Signed integer (64-bit range)
51 - Real (\c double range)
55 <dt>Container values</dt>
58 - Map (string to value)
62 Values are \ref api-fund-shared-object "shared objects": get a new
63 reference with bt_value_get_ref() and put an existing reference with
66 Some library functions \ref api-fund-freezing "freeze" values on
67 success. The documentation of those functions indicate this
70 All the value types share the same C type, #bt_value.
72 Get the type enumerator of a value with bt_value_get_type(). Get whether
73 or not a value type conceptually \em is a given type with the inline
74 bt_value_type_is() function. Get whether or not a value has a specific
75 type with one of the <code>bt_value_is_*()</code> inline helpers.
77 The \em null value is special in that it's a singleton variable,
78 #bt_value_null. You can directly compare any value pointer to
79 #bt_value_null to check if it's a null value. Like other types of
80 values, the null value is a shared object: if you get a new null value
81 reference, you must eventually put it.
83 Create a value with one of the <code>bt_value_*_create()</code> or
84 <code>bt_value_*_create_init()</code> functions.
86 This documentation names the actual data that a scalar value wraps the
89 Set and get the raw values of scalar values with functions that are
90 named <code>bt_value_*_set()</code> and <code>bt_value_*_get()</code>.
92 Check that two values are recursively equal with bt_value_is_equal().
94 Deep-copy a value with bt_value_copy().
96 Extend a map value with bt_value_map_extend().
98 The following table shows the available functions and types for each
105 <th>Type query function
106 <th>Creation functions
107 <th>Writing functions
108 <th>Reading functions
111 <td>#BT_VALUE_TYPE_NULL
112 <td>bt_value_is_null()
113 <td>\em N/A (use the #bt_value_null variable directly)
118 <td>#BT_VALUE_TYPE_BOOL
119 <td>bt_value_is_bool()
121 bt_value_bool_create()<br>
122 bt_value_bool_create_init()
123 <td>bt_value_bool_set()
124 <td>bt_value_bool_get()
126 <th><em>Unsigned integer</em>
127 <td>#BT_VALUE_TYPE_UNSIGNED_INTEGER
128 <td>bt_value_is_unsigned_integer()
130 bt_value_integer_unsigned_create()<br>
131 bt_value_integer_unsigned_create_init()
132 <td>bt_value_integer_unsigned_set()
133 <td>bt_value_integer_unsigned_get()
135 <th><em>Signed integer</em>
136 <td>#BT_VALUE_TYPE_SIGNED_INTEGER
137 <td>bt_value_is_signed_integer()
139 bt_value_integer_signed_create()<br>
140 bt_value_integer_signed_create_init()
141 <td>bt_value_integer_signed_set()
142 <td>bt_value_integer_signed_get()
145 <td>#BT_VALUE_TYPE_REAL
146 <td>bt_value_is_real()
148 bt_value_real_create()<br>
149 bt_value_real_create_init()
150 <td>bt_value_real_set()
151 <td>bt_value_real_get()
154 <td>#BT_VALUE_TYPE_STRING
155 <td>bt_value_is_string()
157 bt_value_string_create()<br>
158 bt_value_string_create_init()
159 <td>bt_value_string_set()
160 <td>bt_value_string_get()
163 <td>#BT_VALUE_TYPE_ARRAY
164 <td>bt_value_is_array()
166 bt_value_array_create()
168 bt_value_array_append_element()<br>
169 bt_value_array_append_bool_element()<br>
170 bt_value_array_append_unsigned_integer_element()<br>
171 bt_value_array_append_signed_integer_element()<br>
172 bt_value_array_append_real_element()<br>
173 bt_value_array_append_string_element()<br>
174 bt_value_array_append_empty_array_element()<br>
175 bt_value_array_append_empty_map_element()<br>
176 bt_value_array_set_element_by_index()
178 bt_value_array_get_length()<br>
179 bt_value_array_is_empty()<br>
180 bt_value_array_borrow_element_by_index()<br>
181 bt_value_array_borrow_element_by_index_const()
184 <td>#BT_VALUE_TYPE_MAP
185 <td>bt_value_is_map()
187 bt_value_map_create()
189 bt_value_map_insert_entry()<br>
190 bt_value_map_insert_bool_entry()<br>
191 bt_value_map_insert_unsigned_integer_entry()<br>
192 bt_value_map_insert_signed_integer_entry()<br>
193 bt_value_map_insert_real_entry()<br>
194 bt_value_map_insert_string_entry()<br>
195 bt_value_map_insert_empty_array_entry()<br>
196 bt_value_map_insert_empty_map_entry()<br>
197 bt_value_map_extend()
199 bt_value_map_get_size()<br>
200 bt_value_map_is_empty()<br>
201 bt_value_map_has_entry()<br>
202 bt_value_map_borrow_entry_value()<br>
203 bt_value_map_borrow_entry_value_const()<br>
204 bt_value_map_foreach_entry()<br>
205 bt_value_map_foreach_entry_const()
215 @typedef struct bt_value bt_value;
230 Value type enumerators.
232 typedef enum bt_value_type
{
237 BT_VALUE_TYPE_NULL
= 1 << 0,
243 BT_VALUE_TYPE_BOOL
= 1 << 1,
249 No value has this type: use it with bt_value_type_is().
251 BT_VALUE_TYPE_INTEGER
= 1 << 2,
255 Unsigned integer value.
257 This type conceptually inherits #BT_VALUE_TYPE_INTEGER.
259 BT_VALUE_TYPE_UNSIGNED_INTEGER
= (1 << 3) | BT_VALUE_TYPE_INTEGER
,
263 Signed integer value.
265 This type conceptually inherits #BT_VALUE_TYPE_INTEGER.
267 BT_VALUE_TYPE_SIGNED_INTEGER
= (1 << 4) | BT_VALUE_TYPE_INTEGER
,
273 BT_VALUE_TYPE_REAL
= 1 << 5,
279 BT_VALUE_TYPE_STRING
= 1 << 6,
285 BT_VALUE_TYPE_ARRAY
= 1 << 7,
291 BT_VALUE_TYPE_MAP
= 1 << 8,
296 Returns the type enumerator of the value \bt_p{value}.
299 Value of which to get the type enumerator
302 Type enumerator of \bt_p{value}.
304 @bt_pre_not_null{value}
306 @sa bt_value_type_is() —
307 Returns whether or not the type of a value conceptually is a given
309 @sa bt_value_is_null() —
310 Returns whether or not a value is a null value.
311 @sa bt_value_is_bool() —
312 Returns whether or not a value is a boolean value.
313 @sa bt_value_is_unsigned_integer() —
314 Returns whether or not a value is an unsigned integer value.
315 @sa bt_value_is_signed_integer() —
316 Returns whether or not a value is a signed integer value.
317 @sa bt_value_is_real() —
318 Returns whether or not a value is a real value.
319 @sa bt_value_is_string() —
320 Returns whether or not a value is a string value.
321 @sa bt_value_is_array() —
322 Returns whether or not a value is an array value.
323 @sa bt_value_is_map() —
324 Returns whether or not a value is a map value.
326 extern bt_value_type
bt_value_get_type(const bt_value
*value
);
330 Returns whether or not the value type \bt_p{type} conceptually
331 \em is the value type \bt_p{other_type}.
333 For example, an unsigned integer value conceptually \em is an integer
337 bt_value_type_is(BT_VALUE_TYPE_UNSIGNED_INTEGER, BT_VALUE_TYPE_INTEGER)
343 Value type to check against \bt_p{other_type}.
344 @param[in] other_type
345 Value type against which to check \bt_p{type}.
348 #BT_TRUE if \bt_p{type} conceptually \em is \bt_p{other_type}.
350 @sa bt_value_get_type() —
351 Returns the type enumerator of a value.
352 @sa bt_value_is_null() —
353 Returns whether or not a value is a null value.
354 @sa bt_value_is_bool() —
355 Returns whether or not a value is a boolean value.
356 @sa bt_value_is_unsigned_integer() —
357 Returns whether or not a value is an unsigned integer value.
358 @sa bt_value_is_signed_integer() —
359 Returns whether or not a value is a signed integer value.
360 @sa bt_value_is_real() —
361 Returns whether or not a value is a real value.
362 @sa bt_value_is_string() —
363 Returns whether or not a value is a string value.
364 @sa bt_value_is_array() —
365 Returns whether or not a value is an array value.
366 @sa bt_value_is_map() —
367 Returns whether or not a value is a map value.
370 bt_bool
bt_value_type_is(const bt_value_type type
,
371 const bt_value_type other_type
)
373 return (type
& other_type
) == other_type
;
378 Returns whether or not the value \bt_p{value} is a null value.
381 Because all null values point to the same null value singleton, you
382 can also directly compare \bt_p{value} to the #bt_value_null
389 #BT_TRUE if \bt_p{value} is a null value.
391 @bt_pre_not_null{value}
393 @sa bt_value_get_type() —
394 Returns the type enumerator of a value.
395 @sa bt_value_type_is() —
396 Returns whether or not the type of a value conceptually is a given
398 @sa #bt_value_null —
399 The null value singleton.
402 bt_bool
bt_value_is_null(const bt_value
*value
)
404 return bt_value_get_type(value
) == BT_VALUE_TYPE_NULL
;
409 Returns whether or not the value \bt_p{value} is a boolean value.
415 #BT_TRUE if \bt_p{value} is a boolean value.
417 @bt_pre_not_null{value}
419 @sa bt_value_get_type() —
420 Returns the type enumerator of a value.
421 @sa bt_value_type_is() —
422 Returns whether or not the type of a value conceptually is a given
426 bt_bool
bt_value_is_bool(const bt_value
*value
)
428 return bt_value_get_type(value
) == BT_VALUE_TYPE_BOOL
;
433 Returns whether or not the value \bt_p{value} is an unsigned integer
440 #BT_TRUE if \bt_p{value} is an unsigned integer value.
442 @bt_pre_not_null{value}
444 @sa bt_value_get_type() —
445 Returns the type enumerator of a value.
446 @sa bt_value_type_is() —
447 Returns whether or not the type of a value conceptually is a given
451 bt_bool
bt_value_is_unsigned_integer(const bt_value
*value
)
453 return bt_value_get_type(value
) == BT_VALUE_TYPE_UNSIGNED_INTEGER
;
458 Returns whether or not the value \bt_p{value} is a signed integer
465 #BT_TRUE if \bt_p{value} is a signed integer value.
467 @bt_pre_not_null{value}
469 @sa bt_value_get_type() —
470 Returns the type enumerator of a value.
471 @sa bt_value_type_is() —
472 Returns whether or not the type of a value conceptually is a given
476 bt_bool
bt_value_is_signed_integer(const bt_value
*value
)
478 return bt_value_get_type(value
) == BT_VALUE_TYPE_SIGNED_INTEGER
;
483 Returns whether or not the value \bt_p{value} is a real value.
489 #BT_TRUE if \bt_p{value} is a real value.
491 @bt_pre_not_null{value}
493 @sa bt_value_get_type() —
494 Returns the type enumerator of a value.
495 @sa bt_value_type_is() —
496 Returns whether or not the type of a value conceptually is a given
500 bt_bool
bt_value_is_real(const bt_value
*value
)
502 return bt_value_get_type(value
) == BT_VALUE_TYPE_REAL
;
507 Returns whether or not the value \bt_p{value} is a string value.
513 #BT_TRUE if \bt_p{value} is a string value.
515 @bt_pre_not_null{value}
517 @sa bt_value_get_type() —
518 Returns the type enumerator of a value.
519 @sa bt_value_type_is() —
520 Returns whether or not the type of a value conceptually is a given
524 bt_bool
bt_value_is_string(const bt_value
*value
)
526 return bt_value_get_type(value
) == BT_VALUE_TYPE_STRING
;
531 Returns whether or not the value \bt_p{value} is an array value.
537 #BT_TRUE if \bt_p{value} is an array value.
539 @bt_pre_not_null{value}
541 @sa bt_value_get_type() —
542 Returns the type enumerator of a value.
543 @sa bt_value_type_is() —
544 Returns whether or not the type of a value conceptually is a given
548 bt_bool
bt_value_is_array(const bt_value
*value
)
550 return bt_value_get_type(value
) == BT_VALUE_TYPE_ARRAY
;
555 Returns whether or not the value \bt_p{value} is a map value.
561 #BT_TRUE if \bt_p{value} is a map value.
563 @bt_pre_not_null{value}
565 @sa bt_value_get_type() —
566 Returns the type enumerator of a value.
567 @sa bt_value_type_is() —
568 Returns whether or not the type of a value conceptually is a given
572 bt_bool
bt_value_is_map(const bt_value
*value
)
574 return bt_value_get_type(value
) == BT_VALUE_TYPE_MAP
;
586 The null value singleton.
588 This is the \em only instance of a null value.
590 Like any type of value, the null value is a shared object: if you get a
591 new null value reference with bt_value_get_ref(), you must eventually
592 put it with bt_value_put_ref(). The null value singleton's reference
593 count must never reach 0: libbabeltrace2 logs a warning message when
594 this programming error occurs.
596 Because all null values point to the same null value singleton, you can
597 directly compare a value to the \c bt_value_null variable.
601 \c bt_value_null is different from \c NULL: the former is a true
602 \bt_name value object while the latter is a C definition which
603 usually means "no pointer".
605 For example, bt_value_map_borrow_entry_value() can return
606 \c bt_value_null if the requested key is mapped to a null value, but
607 it can also return \c NULL if the key is not found.
610 @sa bt_value_is_null() —
611 Returns whether or not a value is a null value.
613 extern bt_value
*const bt_value_null
;
624 Creates and returns a boolean value initialized to #BT_FALSE.
626 The returned value has the type #BT_VALUE_TYPE_BOOL.
629 New boolean value reference, or \c NULL on memory error.
631 @sa bt_value_bool_create_init() —
632 Creates a boolean value with a given initial raw value.
634 extern bt_value
*bt_value_bool_create(void);
638 Creates and returns a boolean value initialized to \bt_p{raw_value}.
640 The returned value has the type #BT_VALUE_TYPE_BOOL.
643 Initial raw value of the boolean value to create.
646 New boolean value reference, or \c NULL on memory error.
648 @sa bt_value_bool_create() —
649 Creates a boolean value initialized to #BT_FALSE.
651 extern bt_value
*bt_value_bool_create_init(bt_bool raw_value
);
655 Sets the raw value of the boolean value \bt_p{value} to
659 Boolean value of which to set the raw value to \bt_p{raw_value}.
661 New raw value of \bt_p{value}.
663 @bt_pre_not_null{value}
664 @bt_pre_is_bool_val{value}
667 @sa bt_value_bool_get() —
668 Returns the raw value of a boolean value.
670 extern void bt_value_bool_set(bt_value
*value
, bt_bool raw_value
);
674 Returns the raw value of the boolean value \bt_p{value}.
677 Boolean value of which to get the raw value.
680 Raw value of \bt_p{value}.
682 @bt_pre_not_null{value}
683 @bt_pre_is_bool_val{value}
685 @sa bt_value_bool_set() —
686 Sets the raw value of a boolean value.
688 extern bt_bool
bt_value_bool_get(const bt_value
*value
);
693 @name Unsigned integer value
699 Creates and returns an unsigned integer value initialized to 0.
701 The returned value has the type #BT_VALUE_TYPE_UNSIGNED_INTEGER.
704 New unsigned integer value reference, or \c NULL on memory error.
706 @sa bt_value_integer_unsigned_create_init() —
707 Creates an unsigned integer value with a given initial raw value.
709 extern bt_value
*bt_value_integer_unsigned_create(void);
713 Creates and returns an unsigned integer value initialized to
716 The returned value has the type #BT_VALUE_TYPE_UNSIGNED_INTEGER.
719 Initial raw value of the unsigned integer value to create.
722 New unsigned integer value reference, or \c NULL on memory error.
724 @sa bt_value_bool_create() —
725 Creates an unsigned integer value initialized to 0.
727 extern bt_value
*bt_value_integer_unsigned_create_init(uint64_t raw_value
);
731 Sets the raw value of the unsigned integer value \bt_p{value} to
735 Unsigned integer value of which to set the raw value to
738 New raw value of \bt_p{value}.
740 @bt_pre_not_null{value}
741 @bt_pre_is_uint_val{value}
744 @sa bt_value_integer_unsigned_get() —
745 Returns the raw value of an unsigned integer value.
747 extern void bt_value_integer_unsigned_set(bt_value
*value
,
752 Returns the raw value of the unsigned integer value \bt_p{value}.
755 Unsigned integer value of which to get the raw value.
758 Raw value of \bt_p{value}.
760 @bt_pre_not_null{value}
761 @bt_pre_is_uint_val{value}
763 @sa bt_value_integer_unsigned_set() —
764 Sets the raw value of an unsigned integer value.
766 extern uint64_t bt_value_integer_unsigned_get(const bt_value
*value
);
771 @name Signed integer value
777 Creates and returns a signed integer value initialized to 0.
779 The returned value has the type #BT_VALUE_TYPE_SIGNED_INTEGER.
782 New signed integer value reference, or \c NULL on memory error.
784 @sa bt_value_integer_signed_create_init() —
785 Creates a signed integer value with a given initial raw value.
787 extern bt_value
*bt_value_integer_signed_create(void);
791 Creates and returns a signed integer value initialized to
794 The returned value has the type #BT_VALUE_TYPE_SIGNED_INTEGER.
797 Initial raw value of the signed integer value to create.
800 New signed integer value reference, or \c NULL on memory error.
802 @sa bt_value_bool_create() —
803 Creates a signed integer value initialized to 0.
805 extern bt_value
*bt_value_integer_signed_create_init(int64_t raw_value
);
809 Sets the raw value of the signed integer value \bt_p{value} to
813 Signed integer value of which to set the raw value to
816 New raw value of \bt_p{value}.
818 @bt_pre_not_null{value}
819 @bt_pre_is_sint_val{value}
822 @sa bt_value_integer_signed_get() —
823 Returns the raw value of a signed integer value.
825 extern void bt_value_integer_signed_set(bt_value
*value
, int64_t raw_value
);
829 Returns the raw value of the signed integer value \bt_p{value}.
832 Signed integer value of which to get the raw value.
835 Raw value of \bt_p{value}.
837 @bt_pre_not_null{value}
838 @bt_pre_is_sint_val{value}
840 @sa bt_value_integer_signed_set() —
841 Sets the raw value of a signed integer value.
843 extern int64_t bt_value_integer_signed_get(const bt_value
*value
);
854 Creates and returns a real value initialized to 0.
856 The returned value has the type #BT_VALUE_TYPE_REAL.
859 New real value reference, or \c NULL on memory error.
861 @sa bt_value_real_create_init() —
862 Creates a real value with a given initial raw value.
864 extern bt_value
*bt_value_real_create(void);
868 Creates and returns a real value initialized to \bt_p{raw_value}.
870 The returned value has the type #BT_VALUE_TYPE_REAL.
873 Initial raw value of the real value to create.
876 New real value reference, or \c NULL on memory error.
878 @sa bt_value_real_create() —
879 Creates a real value initialized to 0.
881 extern bt_value
*bt_value_real_create_init(double raw_value
);
885 Sets the raw value of the real value \bt_p{value} to
889 Real value of which to set the raw value to \bt_p{raw_value}.
891 New raw value of \bt_p{value}.
893 @bt_pre_not_null{value}
894 @bt_pre_is_real_val{value}
897 @sa bt_value_real_get() —
898 Returns the raw value of a real value.
900 extern void bt_value_real_set(bt_value
*value
, double raw_value
);
904 Returns the raw value of the real value \bt_p{value}.
907 Real value of which to get the raw value.
910 Raw value of \bt_p{value}.
912 @bt_pre_not_null{value}
913 @bt_pre_is_real_val{value}
915 @sa bt_value_real_set() —
916 Sets the raw value of a real value.
918 extern double bt_value_real_get(const bt_value
*value
);
929 Creates and returns an empty string value.
931 The returned value has the type #BT_VALUE_TYPE_STRING.
934 New string value reference, or \c NULL on memory error.
936 @sa bt_value_string_create_init() —
937 Creates a string value with a given initial raw value.
939 extern bt_value
*bt_value_string_create(void);
943 Creates and returns a string value initialized to a copy of
946 The returned value has the type #BT_VALUE_TYPE_STRING.
949 Initial raw value of the string value to create (copied).
952 New string value reference, or \c NULL on memory error.
954 @bt_pre_not_null{raw_value}
956 @sa bt_value_string_create() —
957 Creates an empty string value.
959 extern bt_value
*bt_value_string_create_init(const char *raw_value
);
963 Status codes for bt_value_string_set().
965 typedef enum bt_value_string_set_status
{
970 BT_VALUE_STRING_SET_STATUS_OK
= __BT_FUNC_STATUS_OK
,
976 BT_VALUE_STRING_SET_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
977 } bt_value_string_set_status
;
981 Sets the raw value of the string value \bt_p{value} to a copy of
985 String value of which to set the raw value to a copy of
988 New raw value of \bt_p{value} (copied).
990 @retval #BT_VALUE_STRING_SET_STATUS_OK
992 @retval #BT_VALUE_STRING_SET_STATUS_MEMORY_ERROR
995 @bt_pre_not_null{value}
996 @bt_pre_is_string_val{value}
998 @bt_pre_not_null{raw_value}
1000 @sa bt_value_string_get() —
1001 Returns the raw value of a string value.
1003 extern bt_value_string_set_status
bt_value_string_set(bt_value
*value
,
1004 const char *raw_value
);
1008 Returns the raw value of the string value \bt_p{value}.
1011 String value of which to get the raw value.
1015 Raw value of \bt_p{value}.
1017 The returned pointer remains valid until \bt_p{value} is modified.
1020 @bt_pre_not_null{value}
1021 @bt_pre_is_string_val{value}
1023 @sa bt_value_string_set() —
1024 Sets the raw value of a string value.
1026 extern const char *bt_value_string_get(const bt_value
*value
);
1037 Creates and returns an empty array value.
1039 The returned value has the type #BT_VALUE_TYPE_ARRAY.
1042 New array value reference, or \c NULL on memory error.
1044 extern bt_value
*bt_value_array_create(void);
1048 Status codes for the <code>bt_value_array_append_*()</code>
1051 typedef enum bt_value_array_append_element_status
{
1056 BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1062 BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1063 } bt_value_array_append_element_status
;
1067 Appends the value \bt_p{element_value} to the array value \bt_p{value}.
1069 To append a null value, pass #bt_value_null as \bt_p{element_value}.
1072 Array value to which to append \bt_p{element_value}.
1073 @param[in] element_value
1074 Value to append to \bt_p{value}.
1076 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1078 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1081 @bt_pre_not_null{value}
1082 @bt_pre_is_array_val{value}
1084 @bt_pre_not_null{element_value}
1086 \bt_p{element_value} does not contain \bt_p{value}, recursively.
1089 <strong>On success</strong>, the length of \bt_p{value} is
1092 @sa bt_value_array_append_bool_element() —
1093 Creates and appends a boolean value to an array value.
1094 @sa bt_value_array_append_unsigned_integer_element() —
1095 Creates and appends an unsigned integer value to an array value.
1096 @sa bt_value_array_append_signed_integer_element() —
1097 Creates and appends a signed integer value to an array value.
1098 @sa bt_value_array_append_real_element() —
1099 Creates and appends a real value to an array value.
1100 @sa bt_value_array_append_string_element() —
1101 Creates and appends a string value to an array value.
1102 @sa bt_value_array_append_empty_array_element() —
1103 Creates and appends an empty array value to an array value.
1104 @sa bt_value_array_append_empty_map_element() —
1105 Creates and appends an empty map value to an array value.
1107 extern bt_value_array_append_element_status
bt_value_array_append_element(
1108 bt_value
*value
, bt_value
*element_value
);
1112 Creates a boolean value initialized to \bt_p{raw_value} and appends
1113 it to the array value \bt_p{value}.
1116 Array value to which to append the created boolean value.
1117 @param[in] raw_value
1118 Raw value of the boolean value to create and append to \bt_p{value}.
1120 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1122 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1125 @bt_pre_not_null{value}
1126 @bt_pre_is_array_val{value}
1130 <strong>On success</strong>, the length of \bt_p{value} is
1133 @sa bt_value_array_append_element() —
1134 Appends an existing value to an array value.
1136 extern bt_value_array_append_element_status
1137 bt_value_array_append_bool_element(bt_value
*value
, bt_bool raw_value
);
1141 Creates an unsigned integer value initialized to \bt_p{raw_value}
1142 and appends it to the array value \bt_p{value}.
1145 Array value to which to append the created unsigned integer value.
1146 @param[in] raw_value
1147 Raw value of the unsigned integer value to create and append to
1150 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1152 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1155 @bt_pre_not_null{value}
1156 @bt_pre_is_array_val{value}
1160 <strong>On success</strong>, the length of \bt_p{value} is
1163 @sa bt_value_array_append_element() —
1164 Appends an existing value to an array value.
1166 extern bt_value_array_append_element_status
1167 bt_value_array_append_unsigned_integer_element(bt_value
*value
,
1168 uint64_t raw_value
);
1172 Creates a signed integer value initialized to \bt_p{raw_value} and
1173 appends it to the array value \bt_p{value}.
1176 Array value to which to append the created signed integer value.
1177 @param[in] raw_value
1178 Raw value of the signed integer value to create and append to
1181 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1183 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1186 @bt_pre_not_null{value}
1187 @bt_pre_is_array_val{value}
1191 <strong>On success</strong>, the length of \bt_p{value} is
1194 @sa bt_value_array_append_element() —
1195 Appends an existing value to an array value.
1197 extern bt_value_array_append_element_status
1198 bt_value_array_append_signed_integer_element(bt_value
*value
,
1203 Creates a real value initialized to \bt_p{raw_value} and appends
1204 it to the array value \bt_p{value}.
1207 Array value to which to append the created real value.
1208 @param[in] raw_value
1209 Raw value of the real value to create and append to \bt_p{value}.
1211 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1213 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1216 @bt_pre_not_null{value}
1217 @bt_pre_is_array_val{value}
1221 <strong>On success</strong>, the length of \bt_p{value} is
1224 @sa bt_value_array_append_element() —
1225 Appends an existing value to an array value.
1227 extern bt_value_array_append_element_status
1228 bt_value_array_append_real_element(bt_value
*value
, double raw_value
);
1232 Creates a string value initialized to a copy of \bt_p{raw_value} and
1233 appends it to the array value \bt_p{value}.
1236 Array value to which to append the created string value.
1237 @param[in] raw_value
1238 Raw value of the string value to create and append to \bt_p{value}
1241 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1243 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1246 @bt_pre_not_null{value}
1247 @bt_pre_is_array_val{value}
1251 <strong>On success</strong>, the length of \bt_p{value} is
1254 @sa bt_value_array_append_element() —
1255 Appends an existing value to an array value.
1257 extern bt_value_array_append_element_status
1258 bt_value_array_append_string_element(bt_value
*value
, const char *raw_value
);
1262 Creates an empty array value and appends it to the array
1265 On success, if \bt_p{element_value} is not \c NULL, this function sets
1266 \bt_p{*element_value} to a \em borrowed reference of the created empty
1270 Array value to which to append the created empty array value.
1271 @param[out] element_value
1272 <strong>On success, if not \c NULL</strong>, \bt_p{*element_value}
1273 is a \em borrowed reference of the created empty array value.
1275 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1277 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1280 @bt_pre_not_null{value}
1281 @bt_pre_is_array_val{value}
1285 <strong>On success</strong>, the length of \bt_p{value} is
1288 @sa bt_value_array_append_element() —
1289 Appends an existing value to an array value.
1291 extern bt_value_array_append_element_status
1292 bt_value_array_append_empty_array_element(bt_value
*value
,
1293 bt_value
**element_value
);
1297 Creates an empty map value and appends it to the array
1300 On success, if \bt_p{element_value} is not \c NULL, this function sets
1301 \bt_p{*element_value} to a \em borrowed reference of the created empty
1305 Array value to which to append the created empty array value.
1306 @param[out] element_value
1307 <strong>On success, if not \c NULL</strong>, \bt_p{*element_value}
1308 is a \em borrowed reference of the created empty map value.
1310 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1312 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1315 @bt_pre_not_null{value}
1316 @bt_pre_is_array_val{value}
1320 <strong>On success</strong>, the length of \bt_p{value} is
1323 @sa bt_value_array_append_element() —
1324 Appends an existing value to an array value.
1326 extern bt_value_array_append_element_status
1327 bt_value_array_append_empty_map_element(bt_value
*value
,
1328 bt_value
**element_value
);
1332 Status codes for bt_value_array_set_element_by_index().
1334 typedef enum bt_value_array_set_element_by_index_status
{
1339 BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1345 BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1346 } bt_value_array_set_element_by_index_status
;
1350 Sets the element of the array value \bt_p{value} at index
1351 \bt_p{index} to the value \bt_p{element_value}.
1353 On success, this function replaces the existing element of \bt_p{value}
1354 at index \bt_p{index}.
1357 Array value of which to set the element at index \bt_p{index}.
1359 Index of the element to set in \bt_p{value}.
1360 @param[in] element_value
1361 Value to set as the element of \bt_p{value} at index \bt_p{index}.
1363 @retval #BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_OK
1365 @retval #BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_MEMORY_ERROR
1368 @bt_pre_not_null{value}
1369 @bt_pre_is_array_val{value}
1372 \bt_p{index} is less than the length of \bt_p{value} (as returned by
1373 bt_value_array_get_length()).
1374 @bt_pre_not_null{element_value}
1376 \bt_p{element_value} does not contain \bt_p{value}, recursively.
1379 <strong>On success</strong>, the length of \bt_p{value} is
1382 @sa bt_value_array_append_element() —
1383 Appends a value to an array value.
1385 extern bt_value_array_set_element_by_index_status
1386 bt_value_array_set_element_by_index(bt_value
*value
, uint64_t index
,
1387 bt_value
*element_value
);
1391 Borrows the element at index \bt_p{index} from the array value
1395 Array value from which to borrow the element at index \bt_p{index}.
1397 Index of the element to borrow from \bt_p{value}.
1401 \em Borrowed reference of the element of \bt_p{value} at index
1404 The returned pointer remains valid until \bt_p{value} is modified.
1407 @bt_pre_not_null{value}
1408 @bt_pre_is_array_val{value}
1410 \bt_p{index} is less than the length of \bt_p{value} (as returned by
1411 bt_value_array_get_length()).
1413 @sa bt_value_array_borrow_element_by_index_const() —
1414 \c const version of this function.
1416 extern bt_value
*bt_value_array_borrow_element_by_index(bt_value
*value
,
1421 Borrows the element at index \bt_p{index} from the array value
1422 \bt_p{value} (\c const version).
1424 See bt_value_array_borrow_element_by_index().
1426 extern const bt_value
*bt_value_array_borrow_element_by_index_const(
1427 const bt_value
*value
, uint64_t index
);
1431 Returns the length of the array value \bt_p{value}.
1434 Array value of which to get the length.
1437 Length (number of contained elements) of \bt_p{value}.
1439 @bt_pre_not_null{value}
1440 @bt_pre_is_array_val{value}
1442 @sa bt_value_array_is_empty() —
1443 Returns whether or not an array value is empty.
1445 extern uint64_t bt_value_array_get_length(const bt_value
*value
);
1449 Returns whether or not the array value \bt_p{value} is empty.
1452 Array value to check.
1455 #BT_TRUE if \bt_p{value} is empty (has the length 0).
1457 @bt_pre_not_null{value}
1458 @bt_pre_is_array_val{value}
1460 @sa bt_value_array_get_length() —
1461 Returns the length of an array value.
1464 bt_bool
bt_value_array_is_empty(const bt_value
*value
)
1466 return bt_value_array_get_length(value
) == 0;
1478 Creates and returns an empty map value.
1480 The returned value has the type #BT_VALUE_TYPE_MAP.
1483 New map value reference, or \c NULL on memory error.
1485 extern bt_value
*bt_value_map_create(void);
1489 Status codes for the <code>bt_value_map_insert_*()</code> functions.
1491 typedef enum bt_value_map_insert_entry_status
{
1496 BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1502 BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1503 } bt_value_map_insert_entry_status
;
1507 Inserts or replaces an entry with the key \bt_p{key} and the value
1508 \bt_p{entry_value} in the map value \bt_p{value}.
1510 To insert an entry having a null value, pass #bt_value_null as
1513 On success, if \bt_p{value} already contains an entry with key
1514 \bt_p{key}, this function replaces the existing entry's value with
1518 Map value in which to insert or replace an entry with key \bt_p{key}
1519 and value \bt_p{entry_value}.
1521 Key of the entry to insert or replace in \bt_p{value} (copied).
1522 @param[in] entry_value
1523 Value of the entry to insert or replace in \bt_p{value}.
1525 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1527 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1530 @bt_pre_not_null{value}
1531 @bt_pre_is_map_val{value}
1533 @bt_pre_not_null{key}
1534 @bt_pre_not_null{entry_value}
1536 \bt_p{entry_value} does not contain \bt_p{value}, recursively.
1538 @sa bt_value_map_insert_bool_entry() —
1539 Creates a boolean value and uses it to insert an entry in a map
1541 @sa bt_value_map_insert_unsigned_integer_entry() —
1542 Creates an unsigned integer value and uses it to insert an entry in
1544 @sa bt_value_map_insert_signed_integer_entry() —
1545 Creates a signed value and uses it to insert an entry in a map
1547 @sa bt_value_map_insert_real_entry() —
1548 Creates a real value and uses it to insert an entry in a map value.
1549 @sa bt_value_map_insert_string_entry() —
1550 Creates a string value and uses it to insert an entry in a map
1552 @sa bt_value_map_insert_empty_array_entry() —
1553 Creates an empty array value and uses it to insert an entry in a map
1555 @sa bt_value_map_insert_empty_map_entry() —
1556 Creates a map value and uses it to insert an entry in a map value.
1558 extern bt_value_map_insert_entry_status
bt_value_map_insert_entry(
1559 bt_value
*value
, const char *key
, bt_value
*entry_value
);
1563 Creates a boolean value initialized to \bt_p{raw_value} and
1564 inserts or replaces an entry with the key \bt_p{key} and this value
1565 in the map value \bt_p{value}.
1567 On success, if \bt_p{value} already contains an entry with key
1568 \bt_p{key}, this function replaces the existing entry's value with the
1569 created boolean value.
1572 Map value in which to insert or replace an entry with key \bt_p{key}
1573 and the created boolean value.
1575 Key of the entry to insert or replace in \bt_p{value} (copied).
1576 @param[in] raw_value
1577 Initial raw value of the boolean value to create.
1579 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1581 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1584 @bt_pre_not_null{value}
1585 @bt_pre_is_map_val{value}
1587 @bt_pre_not_null{key}
1589 @sa bt_value_map_insert_entry() —
1590 Inserts an entry with an existing value in a map value.
1592 extern bt_value_map_insert_entry_status
bt_value_map_insert_bool_entry(
1593 bt_value
*value
, const char *key
, bt_bool raw_value
);
1597 Creates an unsigned integer value initialized to \bt_p{raw_value}
1598 and inserts or replaces an entry with the key \bt_p{key} and this
1599 value in the map value \bt_p{value}.
1601 On success, if \bt_p{value} already contains an entry with key
1602 \bt_p{key}, this function replaces the existing entry's value with the
1603 created unsigned integer value.
1606 Map value in which to insert or replace an entry with key \bt_p{key}
1607 and the created unsigned integer value.
1609 Key of the entry to insert or replace in \bt_p{value} (copied).
1610 @param[in] raw_value
1611 Initial raw value of the unsigned integer value to create.
1613 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1615 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1618 @bt_pre_not_null{value}
1619 @bt_pre_is_map_val{value}
1621 @bt_pre_not_null{key}
1623 @sa bt_value_map_insert_entry() —
1624 Inserts an entry with an existing value in a map value.
1626 extern bt_value_map_insert_entry_status
1627 bt_value_map_insert_unsigned_integer_entry(bt_value
*value
, const char *key
,
1628 uint64_t raw_value
);
1632 Creates a signed integer value initialized to \bt_p{raw_value} and
1633 inserts or replaces an entry with the key \bt_p{key} and this value
1634 in the map value \bt_p{value}.
1636 On success, if \bt_p{value} already contains an entry with key
1637 \bt_p{key}, this function replaces the existing entry's value with the
1638 created signed integer value.
1641 Map value in which to insert or replace an entry with key \bt_p{key}
1642 and the created signed integer value.
1644 Key of the entry to insert or replace in \bt_p{value} (copied).
1645 @param[in] raw_value
1646 Initial raw value of the signed integer value to create.
1648 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1650 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1653 @bt_pre_not_null{value}
1654 @bt_pre_is_map_val{value}
1656 @bt_pre_not_null{key}
1658 @sa bt_value_map_insert_entry() —
1659 Inserts an entry with an existing value in a map value.
1661 extern bt_value_map_insert_entry_status
1662 bt_value_map_insert_signed_integer_entry(bt_value
*value
, const char *key
,
1667 Creates a real value initialized to \bt_p{raw_value} and inserts or
1668 replaces an entry with the key \bt_p{key} and this value in the map
1671 On success, if \bt_p{value} already contains an entry with key
1672 \bt_p{key}, this function replaces the existing entry's value with the
1676 Map value in which to insert or replace an entry with key \bt_p{key}
1677 and the created real value.
1679 Key of the entry to insert or replace in \bt_p{value} (copied).
1680 @param[in] raw_value
1681 Initial raw value of the real value to create.
1683 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1685 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1688 @bt_pre_not_null{value}
1689 @bt_pre_is_map_val{value}
1691 @bt_pre_not_null{key}
1693 @sa bt_value_map_insert_entry() —
1694 Inserts an entry with an existing value in a map value.
1696 extern bt_value_map_insert_entry_status
bt_value_map_insert_real_entry(
1697 bt_value
*value
, const char *key
, double raw_value
);
1701 Creates a string value initialized to a copy of \bt_p{raw_value} and
1702 inserts or replaces an entry with the key \bt_p{key} and this value
1703 in the map value \bt_p{value}.
1705 On success, if \bt_p{value} already contains an entry with key
1706 \bt_p{key}, this function replaces the existing entry's value with the
1707 created string value.
1710 Map value in which to insert or replace an entry with key \bt_p{key}
1711 and the created string value.
1713 Key of the entry to insert or replace in \bt_p{value} (copied).
1714 @param[in] raw_value
1715 Initial raw value of the string value to create (copied).
1717 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1719 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1722 @bt_pre_not_null{value}
1723 @bt_pre_is_map_val{value}
1725 @bt_pre_not_null{key}
1727 @sa bt_value_map_insert_entry() —
1728 Inserts an entry with an existing value in a map value.
1730 extern bt_value_map_insert_entry_status
1731 bt_value_map_insert_string_entry(bt_value
*value
, const char *key
,
1732 const char *raw_value
);
1736 Creates an empty array value and inserts or replaces an entry with
1737 the key \bt_p{key} and this value in the map value \bt_p{value}.
1739 On success, if \bt_p{entry_value} is not \c NULL, this function sets
1740 \bt_p{*entry_value} to a \em borrowed reference of the created empty
1743 On success, if \bt_p{value} already contains an entry with key
1744 \bt_p{key}, this function replaces the existing entry's value with the
1745 created empty array value.
1748 Map value in which to insert or replace an entry with key \bt_p{key}
1749 and the created empty array value.
1751 Key of the entry to insert or replace in \bt_p{value} (copied).
1752 @param[out] entry_value
1753 <strong>On success, if not \c NULL</strong>, \bt_p{*entry_value} is
1754 a \em borrowed reference of the created empty array value.
1756 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1758 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1761 @bt_pre_not_null{value}
1762 @bt_pre_is_map_val{value}
1764 @bt_pre_not_null{key}
1766 @sa bt_value_map_insert_entry() —
1767 Inserts an entry with an existing value in a map value.
1769 extern bt_value_map_insert_entry_status
1770 bt_value_map_insert_empty_array_entry(bt_value
*value
, const char *key
,
1771 bt_value
**entry_value
);
1775 Creates an empty map value and inserts or replaces an entry with
1776 the key \bt_p{key} and this value in the map value \bt_p{value}.
1778 On success, if \bt_p{entry_value} is not \c NULL, this function sets
1779 \bt_p{*entry_value} to a \em borrowed reference of the created empty map
1782 On success, if \bt_p{value} already contains an entry with key
1783 \bt_p{key}, this function replaces the existing entry's value with the
1784 created empty map value.
1787 Map value in which to insert or replace an entry with key \bt_p{key}
1788 and the created empty map value.
1790 Key of the entry to insert or replace in \bt_p{value} (copied).
1791 @param[out] entry_value
1792 <strong>On success, if not \c NULL</strong>, \bt_p{*entry_value} is
1793 a \em borrowed reference of the created empty map value.
1795 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1797 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1800 @bt_pre_not_null{value}
1801 @bt_pre_is_map_val{value}
1803 @bt_pre_not_null{key}
1805 @sa bt_value_map_insert_entry() —
1806 Inserts an entry with an existing value in a map value.
1808 extern bt_value_map_insert_entry_status
1809 bt_value_map_insert_empty_map_entry(bt_value
*value
, const char *key
,
1810 bt_value
**entry_value
);
1814 Borrows the value of the entry with the key \bt_p{key} in the map
1817 If no entry with key \bt_p{key} exists in \bt_p{value}, this function
1821 Map value from which to borrow the value of the entry with the
1824 Key of the entry from which to borrow the value in \bt_p{value}.
1828 \em Borrowed reference of the value of the entry with key \bt_p{key}
1829 in \bt_p{value}, or \c NULL if none.
1831 The returned pointer remains valid until \bt_p{value} is modified.
1834 @bt_pre_not_null{value}
1835 @bt_pre_is_array_val{value}
1836 @bt_pre_not_null{key}
1838 @sa bt_value_map_borrow_entry_value_const() —
1839 \c const version of this function.
1840 @sa bt_value_map_has_entry() —
1841 Returns whether or not a map value has an entry with a given key.
1843 extern bt_value
*bt_value_map_borrow_entry_value(
1844 bt_value
*value
, const char *key
);
1848 Borrows the value of the entry with the key \bt_p{key} in the map
1849 value \bt_p{value} (\c const version).
1851 See bt_value_map_borrow_entry_value().
1853 extern const bt_value
*bt_value_map_borrow_entry_value_const(
1854 const bt_value
*value
, const char *key
);
1858 Status codes for #bt_value_map_foreach_entry_func.
1860 typedef enum bt_value_map_foreach_entry_func_status
{
1865 BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1869 Interrupt the iteration process.
1871 BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_INTERRUPT
= __BT_FUNC_STATUS_INTERRUPTED
,
1877 BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1883 BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
1884 } bt_value_map_foreach_entry_func_status
;
1888 User function for bt_value_map_foreach_entry().
1890 This is the type of the user function that bt_value_map_foreach_entry()
1891 calls for each entry of the map value.
1894 Key of the map value entry.
1896 Value of the map value entry.
1897 @param[in] user_data
1898 User data, as passed as the \bt_p{user_data} parameter of
1899 bt_value_map_foreach_entry().
1901 @retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_OK
1903 @retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_INTERRUPT
1904 Interrupt the iteration process.
1905 @retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_MEMORY_ERROR
1907 @retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_ERROR
1910 @bt_pre_not_null{key}
1911 @bt_pre_not_null{value}
1913 @sa bt_value_map_foreach_entry() —
1914 Iterates the entries of a map value.
1916 typedef bt_value_map_foreach_entry_func_status
1917 (* bt_value_map_foreach_entry_func
)(const char *key
,
1918 bt_value
*value
, void *user_data
);
1922 Status codes for bt_value_map_foreach_entry().
1924 typedef enum bt_value_map_foreach_entry_status
{
1929 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1933 User function interrupted the iteration process.
1935 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_INTERRUPTED
= __BT_FUNC_STATUS_INTERRUPTED
,
1939 User function error.
1941 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_USER_ERROR
= __BT_FUNC_STATUS_USER_ERROR
,
1947 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1953 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
1954 } bt_value_map_foreach_entry_status
;
1958 Iterates the entries of the map value \bt_p{value}, calling
1959 \bt_p{user_func} for each entry.
1961 This function iterates the entries of \bt_p{value} in no particular
1965 You must \em not modify \bt_p{value} during the iteration process.
1967 \bt_p{user_func} receives \bt_p{user_data} as its last parameter.
1969 The iteration process stops when one of:
1971 - \bt_p{user_func} was called for each entry.
1972 - \bt_p{user_func} does not return
1973 #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_OK.
1976 Map value of which to iterate the entries.
1977 @param[in] user_func
1978 User function to call for each entry of \bt_p{value}.
1979 @param[in] user_data
1980 User data to pass as the \bt_p{user_data} parameter of each call to
1983 @retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_OK
1985 @retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_INTERRUPTED
1986 \bt_p{user_func} returned
1987 #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_INTERRUPT to interrupt the
1989 @retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_USER_ERROR
1990 \bt_p{user_func} returned
1991 #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_ERROR.
1992 @retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_MEMORY_ERROR
1994 @retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_ERROR
1995 Other error caused the <code>bt_value_map_foreach_entry()</code>
1998 @bt_pre_not_null{value}
1999 @bt_pre_is_map_val{value}
2000 @bt_pre_not_null{user_func}
2002 @sa bt_value_map_foreach_entry_const() —
2003 \c const version of this function.
2004 @sa bt_value_map_borrow_entry_value() —
2005 Borrows the value of a specific map value entry.
2007 extern bt_value_map_foreach_entry_status
bt_value_map_foreach_entry(
2008 bt_value
*value
, bt_value_map_foreach_entry_func user_func
,
2013 Status codes for #bt_value_map_foreach_entry_const_func.
2015 typedef enum bt_value_map_foreach_entry_const_func_status
{
2020 BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2024 Interrupt the iteration process.
2026 BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_INTERRUPT
= __BT_FUNC_STATUS_INTERRUPTED
,
2032 BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2038 BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
2039 } bt_value_map_foreach_entry_const_func_status
;
2043 User function for bt_value_map_foreach_entry_const_func().
2045 This is the type of the user function that
2046 bt_value_map_foreach_entry_const_func() calls for each entry of the map
2050 Key of the map value entry.
2052 Value of the map value entry.
2053 @param[in] user_data
2056 @retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_OK
2058 @retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_INTERRUPT
2059 Interrupt the iteration process.
2060 @retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_MEMORY_ERROR
2062 @retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_ERROR
2065 @bt_pre_not_null{key}
2066 @bt_pre_not_null{value}
2068 @sa bt_value_map_foreach_entry_const() —
2069 Iterates the entries of a \c const map value.
2071 typedef bt_value_map_foreach_entry_const_func_status
2072 (* bt_value_map_foreach_entry_const_func
)(const char *key
,
2073 const bt_value
*value
, void *user_data
);
2077 Status codes for bt_value_map_foreach_entry_const().
2079 typedef enum bt_value_map_foreach_entry_const_status
{
2084 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2088 User function interrupted the iteration process.
2090 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_INTERRUPTED
= __BT_FUNC_STATUS_INTERRUPTED
,
2094 User function error.
2096 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_USER_ERROR
= __BT_FUNC_STATUS_USER_ERROR
,
2102 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2108 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
2109 } bt_value_map_foreach_entry_const_status
;
2113 Iterates the entries of the map value \bt_p{value}, calling
2114 \bt_p{user_func} for each entry (\c const version).
2116 See bt_value_map_foreach_entry().
2118 @sa bt_value_map_borrow_entry_value_const() —
2119 Borrows the value of a specific map value entry.
2121 extern bt_value_map_foreach_entry_const_status
bt_value_map_foreach_entry_const(
2122 const bt_value
*value
,
2123 bt_value_map_foreach_entry_const_func user_func
,
2128 Returns the size of the map value \bt_p{value}.
2131 Map value of which to get the size.
2134 Size (number of contained entries) of \bt_p{value}.
2136 @bt_pre_not_null{value}
2137 @bt_pre_is_map_val{value}
2139 @sa bt_value_map_is_empty() —
2140 Returns whether or not a map value is empty.
2142 extern uint64_t bt_value_map_get_size(const bt_value
*value
);
2146 Returns whether or not the map value \bt_p{value} is empty.
2152 #BT_TRUE if \bt_p{value} is empty (has the size 0).
2154 @bt_pre_not_null{value}
2155 @bt_pre_is_map_val{value}
2157 @sa bt_value_map_get_size() —
2158 Returns the size of a map value.
2161 bt_bool
bt_value_map_is_empty(const bt_value
*value
)
2163 return bt_value_map_get_size(value
) == 0;
2168 Returns whether or not the map value \bt_p{value} has an entry with
2177 #BT_TRUE if \bt_p{value} has an entry with the key \bt_p{key}.
2179 @bt_pre_not_null{value}
2180 @bt_pre_is_map_val{value}
2181 @bt_pre_not_null{key}
2183 @sa bt_value_map_borrow_entry_value_const() —
2184 Borrows the value of a specific map value entry.
2186 extern bt_bool
bt_value_map_has_entry(const bt_value
*value
,
2191 Status codes for bt_value_map_extend().
2193 typedef enum bt_value_map_extend_status
{
2198 BT_VALUE_MAP_EXTEND_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2204 BT_VALUE_MAP_EXTEND_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2205 } bt_value_map_extend_status
;
2209 Extends the map value \bt_p{value} with the map value
2210 \bt_p{extension_value}.
2212 For each entry in \bt_p{extension_value}, this function calls
2213 bt_value_map_insert_entry() to insert or replace it in the map value
2232 \bt_p{extension_value}
2244 The map value \bt_p{value} becomes:
2255 Map value to extend.
2256 @param[in] extension_value
2257 Extension map value.
2259 @retval #BT_VALUE_MAP_EXTEND_STATUS_OK
2261 @retval #BT_VALUE_MAP_EXTEND_STATUS_MEMORY_ERROR
2264 @bt_pre_not_null{value}
2265 @bt_pre_is_map_val{value}
2266 @bt_pre_not_null{extension_value}
2267 @bt_pre_is_map_val{extension_value}
2269 @sa bt_value_copy() —
2270 Deep-copies a value.
2272 extern bt_value_map_extend_status
bt_value_map_extend(
2273 bt_value
*value
, const bt_value
*extension_value
);
2284 Status codes for bt_value_copy().
2286 typedef enum bt_value_copy_status
{
2291 BT_VALUE_COPY_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2297 BT_VALUE_COPY_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2298 } bt_value_copy_status
;
2302 Deep-copies a value object.
2304 This function deep-copies \bt_p{value} and sets \bt_p{*copy} to the
2307 Because \bt_p{*copy} is a deep copy, it does not contain, recursively,
2308 any reference that \bt_p{value} contains, but the raw values are
2313 @param[in] copy_value
2314 <strong>On success</strong>, \bt_p{*copy_value} is a deep copy of
2317 @retval #BT_VALUE_COPY_STATUS_OK
2319 @retval #BT_VALUE_COPY_STATUS_MEMORY_ERROR
2322 @bt_pre_not_null{value}
2323 @bt_pre_not_null{copy_value}
2325 extern bt_value_copy_status
bt_value_copy(const bt_value
*value
,
2326 bt_value
**copy_value
);
2330 Returns whether or not the value \bt_p{a_value} is equal,
2331 recursively, to \bt_p{b_value}.
2334 If you want to know whether or not a value is a null value, you can
2335 also directly compare its pointer to the #bt_value_null variable.
2343 #BT_TRUE if \bt_p{a_value} is equal, recursively, to \bt_p{b_value}.
2345 @bt_pre_not_null{a_value}
2346 @bt_pre_not_null{b_value}
2348 extern bt_bool
bt_value_is_equal(const bt_value
*a_value
,
2349 const bt_value
*b_value
);
2354 @name Reference count
2360 Increments the \ref api-fund-shared-object "reference count" of
2361 the value \bt_p{value}.
2365 Value of which to increment the reference count.
2370 @sa bt_value_put_ref() —
2371 Decrements the reference count of a value.
2373 extern void bt_value_get_ref(const bt_value
*value
);
2377 Decrements the \ref api-fund-shared-object "reference count" of
2378 the value \bt_p{value}.
2382 Value of which to decrement the reference count.
2387 @sa bt_value_get_ref() —
2388 Increments the reference count of a value.
2390 extern void bt_value_put_ref(const bt_value
*value
);
2394 Decrements the reference count of the value \bt_p{_value}, and then
2395 sets \bt_p{_value} to \c NULL.
2399 Value of which to decrement the reference count.
2401 Can contain \c NULL.
2404 @bt_pre_assign_expr{_value}
2406 #define BT_VALUE_PUT_REF_AND_RESET(_value) \
2408 bt_value_put_ref(_value); \
2414 Decrements the reference count of the value \bt_p{_dst}, sets
2415 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
2417 This macro effectively moves a value reference from the expression
2418 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
2419 \bt_p{_dst} reference.
2423 Destination expression.
2425 Can contain \c NULL.
2431 Can contain \c NULL.
2434 @bt_pre_assign_expr{_dst}
2435 @bt_pre_assign_expr{_src}
2437 #define BT_VALUE_MOVE_REF(_dst, _src) \
2439 bt_value_put_ref(_dst); \
2452 #endif /* BABELTRACE2_VALUE_H */