1 #ifndef BABELTRACE2_VALUE_H
2 #define BABELTRACE2_VALUE_H
5 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
7 * Permission is hereby granted, free of charge, to any person obtaining a copy
8 * of this software and associated documentation files (the "Software"), to deal
9 * in the Software without restriction, including without limitation the rights
10 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11 * copies of the Software, and to permit persons to whom the Software is
12 * furnished to do so, subject to the following conditions:
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26 #ifndef __BT_IN_BABELTRACE_H
27 # error "Please include <babeltrace2/babeltrace.h> instead."
33 #include <babeltrace2/types.h>
40 @defgroup api-val Values
43 Generic, JSON-like basic data containers.
45 <strong><em>Values</em></strong> are generic data containers. Except for
46 the fact that integer values are explicitly unsigned or signed because
47 of typing limitations,
48 \bt_name values are very similar to <a href="https://json.org/">JSON</a>
51 The value API is completely independent from the rest of the
54 \bt_c_comp initialization parameters, \ref bt_query_executor_create()
55 "query" parameters, as well as trace IR user attributes (for example,
56 bt_event_class_set_user_attributes()) use values.
58 The available value types are:
61 <dt>Scalar values</dt>
65 - Unsigned integer (64-bit range)
66 - Signed integer (64-bit range)
67 - Real (\c double range)
71 <dt>Container values</dt>
74 - Map (string to value)
78 Values are \ref api-fund-shared-object "shared objects": get a new
79 reference with bt_value_get_ref() and put an existing reference with
82 Some library functions \ref api-fund-freezing "freeze" values on
83 success. The documentation of those functions indicate this
86 All the value types share the same C type, #bt_value.
88 Get the type enumerator of a value with bt_value_get_type(). Get whether
89 or not a value type conceptually \em is a given type with the inline
90 bt_value_type_is() function. Get whether or not a value has a specific
91 type with one of the <code>bt_value_is_*()</code> inline helpers.
93 The \em null value is special in that it's a singleton variable,
94 #bt_value_null. You can directly compare any value pointer to
95 #bt_value_null to check if it's a null value. Like other types of
96 values, the null value is a shared object: if you get a new null value
97 reference, you must eventually put it.
99 Create a value with one of the <code>bt_value_*_create()</code> or
100 <code>bt_value_*_create_init()</code> functions.
102 This documentation names the actual data that a scalar value wraps the
105 Set and get the raw values of scalar values with functions that are
106 named <code>bt_value_*_set()</code> and <code>bt_value_*_get()</code>.
108 Check that two values are recursively equal with bt_value_is_equal().
110 Deep-copy a value with bt_value_copy().
112 Extend a map value with bt_value_map_extend().
114 The following table shows the available functions and types for each
121 <th>Type query function
122 <th>Creation functions
123 <th>Writing functions
124 <th>Reading functions
127 <td>#BT_VALUE_TYPE_NULL
128 <td>bt_value_is_null()
129 <td>\em N/A (use the #bt_value_null variable directly)
134 <td>#BT_VALUE_TYPE_BOOL
135 <td>bt_value_is_bool()
137 bt_value_bool_create()<br>
138 bt_value_bool_create_init()
139 <td>bt_value_bool_set()
140 <td>bt_value_bool_get()
142 <th><em>Unsigned integer</em>
143 <td>#BT_VALUE_TYPE_UNSIGNED_INTEGER
144 <td>bt_value_is_unsigned_integer()
146 bt_value_integer_unsigned_create()<br>
147 bt_value_integer_unsigned_create_init()
148 <td>bt_value_integer_unsigned_set()
149 <td>bt_value_integer_unsigned_get()
151 <th><em>Signed integer</em>
152 <td>#BT_VALUE_TYPE_SIGNED_INTEGER
153 <td>bt_value_is_signed_integer()
155 bt_value_integer_signed_create()<br>
156 bt_value_integer_signed_create_init()
157 <td>bt_value_integer_signed_set()
158 <td>bt_value_integer_signed_get()
161 <td>#BT_VALUE_TYPE_REAL
162 <td>bt_value_is_real()
164 bt_value_real_create()<br>
165 bt_value_real_create_init()
166 <td>bt_value_real_set()
167 <td>bt_value_real_get()
170 <td>#BT_VALUE_TYPE_STRING
171 <td>bt_value_is_string()
173 bt_value_string_create()<br>
174 bt_value_string_create_init()
175 <td>bt_value_string_set()
176 <td>bt_value_string_get()
179 <td>#BT_VALUE_TYPE_ARRAY
180 <td>bt_value_is_array()
182 bt_value_array_create()
184 bt_value_array_append_element()<br>
185 bt_value_array_append_bool_element()<br>
186 bt_value_array_append_unsigned_integer_element()<br>
187 bt_value_array_append_signed_integer_element()<br>
188 bt_value_array_append_real_element()<br>
189 bt_value_array_append_string_element()<br>
190 bt_value_array_append_empty_array_element()<br>
191 bt_value_array_append_empty_map_element()<br>
192 bt_value_array_set_element_by_index()
194 bt_value_array_get_length()<br>
195 bt_value_array_is_empty()<br>
196 bt_value_array_borrow_element_by_index()<br>
197 bt_value_array_borrow_element_by_index_const()
200 <td>#BT_VALUE_TYPE_MAP
201 <td>bt_value_is_map()
203 bt_value_map_create()
205 bt_value_map_insert_entry()<br>
206 bt_value_map_insert_bool_entry()<br>
207 bt_value_map_insert_unsigned_integer_entry()<br>
208 bt_value_map_insert_signed_integer_entry()<br>
209 bt_value_map_insert_real_entry()<br>
210 bt_value_map_insert_string_entry()<br>
211 bt_value_map_insert_empty_array_entry()<br>
212 bt_value_map_insert_empty_map_entry()<br>
213 bt_value_map_extend()
215 bt_value_map_get_size()<br>
216 bt_value_map_is_empty()<br>
217 bt_value_map_has_entry()<br>
218 bt_value_map_borrow_entry_value()<br>
219 bt_value_map_borrow_entry_value_const()<br>
220 bt_value_map_foreach_entry()<br>
221 bt_value_map_foreach_entry_const()
231 @typedef struct bt_value bt_value;
246 Value type enumerators.
248 typedef enum bt_value_type
{
253 BT_VALUE_TYPE_NULL
= 1 << 0,
259 BT_VALUE_TYPE_BOOL
= 1 << 1,
265 No value has this type: use it with bt_value_type_is().
267 BT_VALUE_TYPE_INTEGER
= 1 << 2,
271 Unsigned integer value.
273 This type conceptually inherits #BT_VALUE_TYPE_INTEGER.
275 BT_VALUE_TYPE_UNSIGNED_INTEGER
= (1 << 3) | BT_VALUE_TYPE_INTEGER
,
279 Signed integer value.
281 This type conceptually inherits #BT_VALUE_TYPE_INTEGER.
283 BT_VALUE_TYPE_SIGNED_INTEGER
= (1 << 4) | BT_VALUE_TYPE_INTEGER
,
289 BT_VALUE_TYPE_REAL
= 1 << 5,
295 BT_VALUE_TYPE_STRING
= 1 << 6,
301 BT_VALUE_TYPE_ARRAY
= 1 << 7,
307 BT_VALUE_TYPE_MAP
= 1 << 8,
312 Returns the type enumerator of the value \bt_p{value}.
315 Value of which to get the type enumerator
318 Type enumerator of \bt_p{value}.
320 @bt_pre_not_null{value}
322 @sa bt_value_type_is() —
323 Returns whether or not the type of a value conceptually is a given
325 @sa bt_value_is_null() —
326 Returns whether or not a value is a null value.
327 @sa bt_value_is_bool() —
328 Returns whether or not a value is a boolean value.
329 @sa bt_value_is_unsigned_integer() —
330 Returns whether or not a value is an unsigned integer value.
331 @sa bt_value_is_signed_integer() —
332 Returns whether or not a value is a signed integer value.
333 @sa bt_value_is_real() —
334 Returns whether or not a value is a real value.
335 @sa bt_value_is_string() —
336 Returns whether or not a value is a string value.
337 @sa bt_value_is_array() —
338 Returns whether or not a value is an array value.
339 @sa bt_value_is_map() —
340 Returns whether or not a value is a map value.
342 extern bt_value_type
bt_value_get_type(const bt_value
*value
);
346 Returns whether or not the value type \bt_p{type} conceptually
347 \em is the value type \bt_p{other_type}.
349 For example, an unsigned integer value conceptually \em is an integer
353 bt_value_type_is(BT_VALUE_TYPE_UNSIGNED_INTEGER, BT_VALUE_TYPE_INTEGER)
359 Value type to check against \bt_p{other_type}.
360 @param[in] other_type
361 Value type against which to check \bt_p{type}.
364 #BT_TRUE if \bt_p{type} conceptually \em is \bt_p{other_type}.
366 @sa bt_value_get_type() —
367 Returns the type enumerator of a value.
368 @sa bt_value_is_null() —
369 Returns whether or not a value is a null value.
370 @sa bt_value_is_bool() —
371 Returns whether or not a value is a boolean value.
372 @sa bt_value_is_unsigned_integer() —
373 Returns whether or not a value is an unsigned integer value.
374 @sa bt_value_is_signed_integer() —
375 Returns whether or not a value is a signed integer value.
376 @sa bt_value_is_real() —
377 Returns whether or not a value is a real value.
378 @sa bt_value_is_string() —
379 Returns whether or not a value is a string value.
380 @sa bt_value_is_array() —
381 Returns whether or not a value is an array value.
382 @sa bt_value_is_map() —
383 Returns whether or not a value is a map value.
386 bt_bool
bt_value_type_is(const bt_value_type type
,
387 const bt_value_type other_type
)
389 return (type
& other_type
) == other_type
;
394 Returns whether or not the value \bt_p{value} is a null value.
397 Because all null values point to the same null value singleton, you
398 can also directly compare \bt_p{value} to the #bt_value_null
405 #BT_TRUE if \bt_p{value} is a null value.
407 @bt_pre_not_null{value}
409 @sa bt_value_get_type() —
410 Returns the type enumerator of a value.
411 @sa bt_value_type_is() —
412 Returns whether or not the type of a value conceptually is a given
414 @sa #bt_value_null —
415 The null value singleton.
418 bt_bool
bt_value_is_null(const bt_value
*value
)
420 return bt_value_get_type(value
) == BT_VALUE_TYPE_NULL
;
425 Returns whether or not the value \bt_p{value} is a boolean value.
431 #BT_TRUE if \bt_p{value} is a boolean value.
433 @bt_pre_not_null{value}
435 @sa bt_value_get_type() —
436 Returns the type enumerator of a value.
437 @sa bt_value_type_is() —
438 Returns whether or not the type of a value conceptually is a given
442 bt_bool
bt_value_is_bool(const bt_value
*value
)
444 return bt_value_get_type(value
) == BT_VALUE_TYPE_BOOL
;
449 Returns whether or not the value \bt_p{value} is an unsigned integer
456 #BT_TRUE if \bt_p{value} is an unsigned integer value.
458 @bt_pre_not_null{value}
460 @sa bt_value_get_type() —
461 Returns the type enumerator of a value.
462 @sa bt_value_type_is() —
463 Returns whether or not the type of a value conceptually is a given
467 bt_bool
bt_value_is_unsigned_integer(const bt_value
*value
)
469 return bt_value_get_type(value
) == BT_VALUE_TYPE_UNSIGNED_INTEGER
;
474 Returns whether or not the value \bt_p{value} is a signed integer
481 #BT_TRUE if \bt_p{value} is a signed integer value.
483 @bt_pre_not_null{value}
485 @sa bt_value_get_type() —
486 Returns the type enumerator of a value.
487 @sa bt_value_type_is() —
488 Returns whether or not the type of a value conceptually is a given
492 bt_bool
bt_value_is_signed_integer(const bt_value
*value
)
494 return bt_value_get_type(value
) == BT_VALUE_TYPE_SIGNED_INTEGER
;
499 Returns whether or not the value \bt_p{value} is a real value.
505 #BT_TRUE if \bt_p{value} is a real value.
507 @bt_pre_not_null{value}
509 @sa bt_value_get_type() —
510 Returns the type enumerator of a value.
511 @sa bt_value_type_is() —
512 Returns whether or not the type of a value conceptually is a given
516 bt_bool
bt_value_is_real(const bt_value
*value
)
518 return bt_value_get_type(value
) == BT_VALUE_TYPE_REAL
;
523 Returns whether or not the value \bt_p{value} is a string value.
529 #BT_TRUE if \bt_p{value} is a string value.
531 @bt_pre_not_null{value}
533 @sa bt_value_get_type() —
534 Returns the type enumerator of a value.
535 @sa bt_value_type_is() —
536 Returns whether or not the type of a value conceptually is a given
540 bt_bool
bt_value_is_string(const bt_value
*value
)
542 return bt_value_get_type(value
) == BT_VALUE_TYPE_STRING
;
547 Returns whether or not the value \bt_p{value} is an array value.
553 #BT_TRUE if \bt_p{value} is an array value.
555 @bt_pre_not_null{value}
557 @sa bt_value_get_type() —
558 Returns the type enumerator of a value.
559 @sa bt_value_type_is() —
560 Returns whether or not the type of a value conceptually is a given
564 bt_bool
bt_value_is_array(const bt_value
*value
)
566 return bt_value_get_type(value
) == BT_VALUE_TYPE_ARRAY
;
571 Returns whether or not the value \bt_p{value} is a map value.
577 #BT_TRUE if \bt_p{value} is a map value.
579 @bt_pre_not_null{value}
581 @sa bt_value_get_type() —
582 Returns the type enumerator of a value.
583 @sa bt_value_type_is() —
584 Returns whether or not the type of a value conceptually is a given
588 bt_bool
bt_value_is_map(const bt_value
*value
)
590 return bt_value_get_type(value
) == BT_VALUE_TYPE_MAP
;
602 The null value singleton.
604 This is the \em only instance of a null value.
606 Like any type of value, the null value is a shared object: if you get a
607 new null value reference with bt_value_get_ref(), you must eventually
608 put it with bt_value_put_ref(). The null value singleton's reference
609 count must never reach 0: libbabeltrace2 logs a warning message when
610 this programming error occurs.
612 Because all null values point to the same null value singleton, you can
613 directly compare a value to the \c bt_value_null variable.
617 \c bt_value_null is different from \c NULL: the former is a true
618 \bt_name value object while the latter is a C definition which
619 usually means "no pointer".
621 For example, bt_value_map_borrow_entry_value() can return
622 \c bt_value_null if the requested key is mapped to a null value, but
623 it can also return \c NULL if the key is not found.
626 @sa bt_value_is_null() —
627 Returns whether or not a value is a null value.
629 extern bt_value
*const bt_value_null
;
640 Creates and returns a boolean value initialized to #BT_FALSE.
642 The returned value has the type #BT_VALUE_TYPE_BOOL.
645 New boolean value reference, or \c NULL on memory error.
647 @sa bt_value_bool_create_init() —
648 Creates a boolean value with a given initial raw value.
650 extern bt_value
*bt_value_bool_create(void);
654 Creates and returns a boolean value initialized to \bt_p{raw_value}.
656 The returned value has the type #BT_VALUE_TYPE_BOOL.
659 Initial raw value of the boolean value to create.
662 New boolean value reference, or \c NULL on memory error.
664 @sa bt_value_bool_create() —
665 Creates a boolean value initialized to #BT_FALSE.
667 extern bt_value
*bt_value_bool_create_init(bt_bool raw_value
);
671 Sets the raw value of the boolean value \bt_p{value} to
675 Boolean value of which to set the raw value to \bt_p{raw_value}.
677 New raw value of \bt_p{value}.
679 @bt_pre_not_null{value}
680 @bt_pre_is_bool_val{value}
683 @sa bt_value_bool_get() —
684 Returns the raw value of a boolean value.
686 extern void bt_value_bool_set(bt_value
*value
, bt_bool raw_value
);
690 Returns the raw value of the boolean value \bt_p{value}.
693 Boolean value of which to get the raw value.
696 Raw value of \bt_p{value}.
698 @bt_pre_not_null{value}
699 @bt_pre_is_bool_val{value}
701 @sa bt_value_bool_set() —
702 Sets the raw value of a boolean value.
704 extern bt_bool
bt_value_bool_get(const bt_value
*value
);
709 @name Unsigned integer value
715 Creates and returns an unsigned integer value initialized to 0.
717 The returned value has the type #BT_VALUE_TYPE_UNSIGNED_INTEGER.
720 New unsigned integer value reference, or \c NULL on memory error.
722 @sa bt_value_integer_unsigned_create_init() —
723 Creates an unsigned integer value with a given initial raw value.
725 extern bt_value
*bt_value_integer_unsigned_create(void);
729 Creates and returns an unsigned integer value initialized to
732 The returned value has the type #BT_VALUE_TYPE_UNSIGNED_INTEGER.
735 Initial raw value of the unsigned integer value to create.
738 New unsigned integer value reference, or \c NULL on memory error.
740 @sa bt_value_bool_create() —
741 Creates an unsigned integer value initialized to 0.
743 extern bt_value
*bt_value_integer_unsigned_create_init(uint64_t raw_value
);
747 Sets the raw value of the unsigned integer value \bt_p{value} to
751 Unsigned integer value of which to set the raw value to
754 New raw value of \bt_p{value}.
756 @bt_pre_not_null{value}
757 @bt_pre_is_uint_val{value}
760 @sa bt_value_integer_unsigned_get() —
761 Returns the raw value of an unsigned integer value.
763 extern void bt_value_integer_unsigned_set(bt_value
*value
,
768 Returns the raw value of the unsigned integer value \bt_p{value}.
771 Unsigned integer value of which to get the raw value.
774 Raw value of \bt_p{value}.
776 @bt_pre_not_null{value}
777 @bt_pre_is_uint_val{value}
779 @sa bt_value_integer_unsigned_set() —
780 Sets the raw value of an unsigned integer value.
782 extern uint64_t bt_value_integer_unsigned_get(const bt_value
*value
);
787 @name Signed integer value
793 Creates and returns a signed integer value initialized to 0.
795 The returned value has the type #BT_VALUE_TYPE_SIGNED_INTEGER.
798 New signed integer value reference, or \c NULL on memory error.
800 @sa bt_value_integer_signed_create_init() —
801 Creates a signed integer value with a given initial raw value.
803 extern bt_value
*bt_value_integer_signed_create(void);
807 Creates and returns a signed integer value initialized to
810 The returned value has the type #BT_VALUE_TYPE_SIGNED_INTEGER.
813 Initial raw value of the signed integer value to create.
816 New signed integer value reference, or \c NULL on memory error.
818 @sa bt_value_bool_create() —
819 Creates a signed integer value initialized to 0.
821 extern bt_value
*bt_value_integer_signed_create_init(int64_t raw_value
);
825 Sets the raw value of the signed integer value \bt_p{value} to
829 Signed integer value of which to set the raw value to
832 New raw value of \bt_p{value}.
834 @bt_pre_not_null{value}
835 @bt_pre_is_sint_val{value}
838 @sa bt_value_integer_signed_get() —
839 Returns the raw value of a signed integer value.
841 extern void bt_value_integer_signed_set(bt_value
*value
, int64_t raw_value
);
845 Returns the raw value of the signed integer value \bt_p{value}.
848 Signed integer value of which to get the raw value.
851 Raw value of \bt_p{value}.
853 @bt_pre_not_null{value}
854 @bt_pre_is_sint_val{value}
856 @sa bt_value_integer_signed_set() —
857 Sets the raw value of a signed integer value.
859 extern int64_t bt_value_integer_signed_get(const bt_value
*value
);
870 Creates and returns a real value initialized to 0.
872 The returned value has the type #BT_VALUE_TYPE_REAL.
875 New real value reference, or \c NULL on memory error.
877 @sa bt_value_real_create_init() —
878 Creates a real value with a given initial raw value.
880 extern bt_value
*bt_value_real_create(void);
884 Creates and returns a real value initialized to \bt_p{raw_value}.
886 The returned value has the type #BT_VALUE_TYPE_REAL.
889 Initial raw value of the real value to create.
892 New real value reference, or \c NULL on memory error.
894 @sa bt_value_real_create() —
895 Creates a real value initialized to 0.
897 extern bt_value
*bt_value_real_create_init(double raw_value
);
901 Sets the raw value of the real value \bt_p{value} to
905 Real value of which to set the raw value to \bt_p{raw_value}.
907 New raw value of \bt_p{value}.
909 @bt_pre_not_null{value}
910 @bt_pre_is_real_val{value}
913 @sa bt_value_real_get() —
914 Returns the raw value of a real value.
916 extern void bt_value_real_set(bt_value
*value
, double raw_value
);
920 Returns the raw value of the real value \bt_p{value}.
923 Real value of which to get the raw value.
926 Raw value of \bt_p{value}.
928 @bt_pre_not_null{value}
929 @bt_pre_is_real_val{value}
931 @sa bt_value_real_set() —
932 Sets the raw value of a real value.
934 extern double bt_value_real_get(const bt_value
*value
);
945 Creates and returns an empty string value.
947 The returned value has the type #BT_VALUE_TYPE_STRING.
950 New string value reference, or \c NULL on memory error.
952 @sa bt_value_string_create_init() —
953 Creates a string value with a given initial raw value.
955 extern bt_value
*bt_value_string_create(void);
959 Creates and returns a string value initialized to a copy of
962 The returned value has the type #BT_VALUE_TYPE_STRING.
965 Initial raw value of the string value to create (copied).
968 New string value reference, or \c NULL on memory error.
970 @bt_pre_not_null{raw_value}
972 @sa bt_value_string_create() —
973 Creates an empty string value.
975 extern bt_value
*bt_value_string_create_init(const char *raw_value
);
979 Status codes for bt_value_string_set().
981 typedef enum bt_value_string_set_status
{
986 BT_VALUE_STRING_SET_STATUS_OK
= __BT_FUNC_STATUS_OK
,
992 BT_VALUE_STRING_SET_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
993 } bt_value_string_set_status
;
997 Sets the raw value of the string value \bt_p{value} to a copy of
1001 String value of which to set the raw value to a copy of
1003 @param[in] raw_value
1004 New raw value of \bt_p{value} (copied).
1006 @retval #BT_VALUE_STRING_SET_STATUS_OK
1008 @retval #BT_VALUE_STRING_SET_STATUS_MEMORY_ERROR
1011 @bt_pre_not_null{value}
1012 @bt_pre_is_string_val{value}
1014 @bt_pre_not_null{raw_value}
1016 @sa bt_value_string_get() —
1017 Returns the raw value of a string value.
1019 extern bt_value_string_set_status
bt_value_string_set(bt_value
*value
,
1020 const char *raw_value
);
1024 Returns the raw value of the string value \bt_p{value}.
1027 String value of which to get the raw value.
1031 Raw value of \bt_p{value}.
1033 The returned pointer remains valid until \bt_p{value} is modified.
1036 @bt_pre_not_null{value}
1037 @bt_pre_is_string_val{value}
1039 @sa bt_value_string_set() —
1040 Sets the raw value of a string value.
1042 extern const char *bt_value_string_get(const bt_value
*value
);
1053 Creates and returns an empty array value.
1055 The returned value has the type #BT_VALUE_TYPE_ARRAY.
1058 New array value reference, or \c NULL on memory error.
1060 extern bt_value
*bt_value_array_create(void);
1064 Status codes for the <code>bt_value_array_append_*()</code>
1067 typedef enum bt_value_array_append_element_status
{
1072 BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1078 BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1079 } bt_value_array_append_element_status
;
1083 Appends the value \bt_p{element_value} to the array value \bt_p{value}.
1085 To append a null value, pass #bt_value_null as \bt_p{element_value}.
1088 Array value to which to append \bt_p{element_value}.
1089 @param[in] element_value
1090 Value to append to \bt_p{value}.
1092 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1094 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1097 @bt_pre_not_null{value}
1098 @bt_pre_is_array_val{value}
1100 @bt_pre_not_null{element_value}
1102 \bt_p{element_value} does not contain \bt_p{value}, recursively.
1105 <strong>On success</strong>, the length of \bt_p{value} is
1108 @sa bt_value_array_append_bool_element() —
1109 Creates and appends a boolean value to an array value.
1110 @sa bt_value_array_append_unsigned_integer_element() —
1111 Creates and appends an unsigned integer value to an array value.
1112 @sa bt_value_array_append_signed_integer_element() —
1113 Creates and appends a signed integer value to an array value.
1114 @sa bt_value_array_append_real_element() —
1115 Creates and appends a real value to an array value.
1116 @sa bt_value_array_append_string_element() —
1117 Creates and appends a string value to an array value.
1118 @sa bt_value_array_append_empty_array_element() —
1119 Creates and appends an empty array value to an array value.
1120 @sa bt_value_array_append_empty_map_element() —
1121 Creates and appends an empty map value to an array value.
1123 extern bt_value_array_append_element_status
bt_value_array_append_element(
1124 bt_value
*value
, bt_value
*element_value
);
1128 Creates a boolean value initialized to \bt_p{raw_value} and appends
1129 it to the array value \bt_p{value}.
1132 Array value to which to append the created boolean value.
1133 @param[in] raw_value
1134 Raw value of the boolean value to create and append to \bt_p{value}.
1136 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1138 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1141 @bt_pre_not_null{value}
1142 @bt_pre_is_array_val{value}
1146 <strong>On success</strong>, the length of \bt_p{value} is
1149 @sa bt_value_array_append_element() —
1150 Appends an existing value to an array value.
1152 extern bt_value_array_append_element_status
1153 bt_value_array_append_bool_element(bt_value
*value
, bt_bool raw_value
);
1157 Creates an unsigned integer value initialized to \bt_p{raw_value}
1158 and appends it to the array value \bt_p{value}.
1161 Array value to which to append the created unsigned integer value.
1162 @param[in] raw_value
1163 Raw value of the unsigned integer value to create and append to
1166 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1168 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1171 @bt_pre_not_null{value}
1172 @bt_pre_is_array_val{value}
1176 <strong>On success</strong>, the length of \bt_p{value} is
1179 @sa bt_value_array_append_element() —
1180 Appends an existing value to an array value.
1182 extern bt_value_array_append_element_status
1183 bt_value_array_append_unsigned_integer_element(bt_value
*value
,
1184 uint64_t raw_value
);
1188 Creates a signed integer value initialized to \bt_p{raw_value} and
1189 appends it to the array value \bt_p{value}.
1192 Array value to which to append the created signed integer value.
1193 @param[in] raw_value
1194 Raw value of the signed integer value to create and append to
1197 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1199 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1202 @bt_pre_not_null{value}
1203 @bt_pre_is_array_val{value}
1207 <strong>On success</strong>, the length of \bt_p{value} is
1210 @sa bt_value_array_append_element() —
1211 Appends an existing value to an array value.
1213 extern bt_value_array_append_element_status
1214 bt_value_array_append_signed_integer_element(bt_value
*value
,
1219 Creates a real value initialized to \bt_p{raw_value} and appends
1220 it to the array value \bt_p{value}.
1223 Array value to which to append the created real value.
1224 @param[in] raw_value
1225 Raw value of the real value to create and append to \bt_p{value}.
1227 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1229 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1232 @bt_pre_not_null{value}
1233 @bt_pre_is_array_val{value}
1237 <strong>On success</strong>, the length of \bt_p{value} is
1240 @sa bt_value_array_append_element() —
1241 Appends an existing value to an array value.
1243 extern bt_value_array_append_element_status
1244 bt_value_array_append_real_element(bt_value
*value
, double raw_value
);
1248 Creates a string value initialized to a copy of \bt_p{raw_value} and
1249 appends it to the array value \bt_p{value}.
1252 Array value to which to append the created string value.
1253 @param[in] raw_value
1254 Raw value of the string value to create and append to \bt_p{value}
1257 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1259 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1262 @bt_pre_not_null{value}
1263 @bt_pre_is_array_val{value}
1267 <strong>On success</strong>, the length of \bt_p{value} is
1270 @sa bt_value_array_append_element() —
1271 Appends an existing value to an array value.
1273 extern bt_value_array_append_element_status
1274 bt_value_array_append_string_element(bt_value
*value
, const char *raw_value
);
1278 Creates an empty array value and appends it to the array
1281 On success, if \bt_p{element_value} is not \c NULL, this function sets
1282 \bt_p{*element_value} to a \em borrowed reference of the created empty
1286 Array value to which to append the created empty array value.
1287 @param[out] element_value
1288 <strong>On success, if not \c NULL</strong>, \bt_p{*element_value}
1289 is a \em borrowed reference of the created empty array value.
1291 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1293 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1296 @bt_pre_not_null{value}
1297 @bt_pre_is_array_val{value}
1301 <strong>On success</strong>, the length of \bt_p{value} is
1304 @sa bt_value_array_append_element() —
1305 Appends an existing value to an array value.
1307 extern bt_value_array_append_element_status
1308 bt_value_array_append_empty_array_element(bt_value
*value
,
1309 bt_value
**element_value
);
1313 Creates an empty map value and appends it to the array
1316 On success, if \bt_p{element_value} is not \c NULL, this function sets
1317 \bt_p{*element_value} to a \em borrowed reference of the created empty
1321 Array value to which to append the created empty array value.
1322 @param[out] element_value
1323 <strong>On success, if not \c NULL</strong>, \bt_p{*element_value}
1324 is a \em borrowed reference of the created empty map value.
1326 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1328 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1331 @bt_pre_not_null{value}
1332 @bt_pre_is_array_val{value}
1336 <strong>On success</strong>, the length of \bt_p{value} is
1339 @sa bt_value_array_append_element() —
1340 Appends an existing value to an array value.
1342 extern bt_value_array_append_element_status
1343 bt_value_array_append_empty_map_element(bt_value
*value
,
1344 bt_value
**element_value
);
1348 Status codes for bt_value_array_set_element_by_index().
1350 typedef enum bt_value_array_set_element_by_index_status
{
1355 BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1361 BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1362 } bt_value_array_set_element_by_index_status
;
1366 Sets the element of the array value \bt_p{value} at index
1367 \bt_p{index} to the value \bt_p{element_value}.
1369 On success, this function replaces the existing element of \bt_p{value}
1370 at index \bt_p{index}.
1373 Array value of which to set the element at index \bt_p{index}.
1375 Index of the element to set in \bt_p{value}.
1376 @param[in] element_value
1377 Value to set as the element of \bt_p{value} at index \bt_p{index}.
1379 @retval #BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_OK
1381 @retval #BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_MEMORY_ERROR
1384 @bt_pre_not_null{value}
1385 @bt_pre_is_array_val{value}
1388 \bt_p{index} is less than the length of \bt_p{value} (as returned by
1389 bt_value_array_get_length()).
1390 @bt_pre_not_null{element_value}
1392 \bt_p{element_value} does not contain \bt_p{value}, recursively.
1395 <strong>On success</strong>, the length of \bt_p{value} is
1398 @sa bt_value_array_append_element() —
1399 Appends a value to an array value.
1401 extern bt_value_array_set_element_by_index_status
1402 bt_value_array_set_element_by_index(bt_value
*value
, uint64_t index
,
1403 bt_value
*element_value
);
1407 Borrows the element at index \bt_p{index} from the array value
1411 Array value from which to borrow the element at index \bt_p{index}.
1413 Index of the element to borrow from \bt_p{value}.
1417 \em Borrowed reference of the element of \bt_p{value} at index
1420 The returned pointer remains valid until \bt_p{value} is modified.
1423 @bt_pre_not_null{value}
1424 @bt_pre_is_array_val{value}
1426 \bt_p{index} is less than the length of \bt_p{value} (as returned by
1427 bt_value_array_get_length()).
1429 @sa bt_value_array_borrow_element_by_index_const() —
1430 \c const version of this function.
1432 extern bt_value
*bt_value_array_borrow_element_by_index(bt_value
*value
,
1437 Borrows the element at index \bt_p{index} from the array value
1438 \bt_p{value} (\c const version).
1440 See bt_value_array_borrow_element_by_index().
1442 extern const bt_value
*bt_value_array_borrow_element_by_index_const(
1443 const bt_value
*value
, uint64_t index
);
1447 Returns the length of the array value \bt_p{value}.
1450 Array value of which to get the length.
1453 Length (number of contained elements) of \bt_p{value}.
1455 @bt_pre_not_null{value}
1456 @bt_pre_is_array_val{value}
1458 @sa bt_value_array_is_empty() —
1459 Returns whether or not an array value is empty.
1461 extern uint64_t bt_value_array_get_length(const bt_value
*value
);
1465 Returns whether or not the array value \bt_p{value} is empty.
1468 Array value to check.
1471 #BT_TRUE if \bt_p{value} is empty (has the length 0).
1473 @bt_pre_not_null{value}
1474 @bt_pre_is_array_val{value}
1476 @sa bt_value_array_get_length() —
1477 Returns the length of an array value.
1480 bt_bool
bt_value_array_is_empty(const bt_value
*value
)
1482 return bt_value_array_get_length(value
) == 0;
1494 Creates and returns an empty map value.
1496 The returned value has the type #BT_VALUE_TYPE_MAP.
1499 New map value reference, or \c NULL on memory error.
1501 extern bt_value
*bt_value_map_create(void);
1505 Status codes for the <code>bt_value_map_insert_*()</code> functions.
1507 typedef enum bt_value_map_insert_entry_status
{
1512 BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1518 BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1519 } bt_value_map_insert_entry_status
;
1523 Inserts or replaces an entry with the key \bt_p{key} and the value
1524 \bt_p{entry_value} in the map value \bt_p{value}.
1526 To insert an entry having a null value, pass #bt_value_null as
1529 On success, if \bt_p{value} already contains an entry with key
1530 \bt_p{key}, this function replaces the existing entry's value with
1534 Map value in which to insert or replace an entry with key \bt_p{key}
1535 and value \bt_p{entry_value}.
1537 Key of the entry to insert or replace in \bt_p{value} (copied).
1538 @param[in] entry_value
1539 Value of the entry to insert or replace in \bt_p{value}.
1541 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1543 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1546 @bt_pre_not_null{value}
1547 @bt_pre_is_map_val{value}
1549 @bt_pre_not_null{key}
1550 @bt_pre_not_null{entry_value}
1552 \bt_p{entry_value} does not contain \bt_p{value}, recursively.
1554 @sa bt_value_map_insert_bool_entry() —
1555 Creates a boolean value and uses it to insert an entry in a map
1557 @sa bt_value_map_insert_unsigned_integer_entry() —
1558 Creates an unsigned integer value and uses it to insert an entry in
1560 @sa bt_value_map_insert_signed_integer_entry() —
1561 Creates a signed value and uses it to insert an entry in a map
1563 @sa bt_value_map_insert_real_entry() —
1564 Creates a real value and uses it to insert an entry in a map value.
1565 @sa bt_value_map_insert_string_entry() —
1566 Creates a string value and uses it to insert an entry in a map
1568 @sa bt_value_map_insert_empty_array_entry() —
1569 Creates an empty array value and uses it to insert an entry in a map
1571 @sa bt_value_map_insert_empty_map_entry() —
1572 Creates a map value and uses it to insert an entry in a map value.
1574 extern bt_value_map_insert_entry_status
bt_value_map_insert_entry(
1575 bt_value
*value
, const char *key
, bt_value
*entry_value
);
1579 Creates a boolean value initialized to \bt_p{raw_value} and
1580 inserts or replaces an entry with the key \bt_p{key} and this value
1581 in the map value \bt_p{value}.
1583 On success, if \bt_p{value} already contains an entry with key
1584 \bt_p{key}, this function replaces the existing entry's value with the
1585 created boolean value.
1588 Map value in which to insert or replace an entry with key \bt_p{key}
1589 and the created boolean value.
1591 Key of the entry to insert or replace in \bt_p{value} (copied).
1592 @param[in] raw_value
1593 Initial raw value of the boolean value to create.
1595 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1597 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1600 @bt_pre_not_null{value}
1601 @bt_pre_is_map_val{value}
1603 @bt_pre_not_null{key}
1605 @sa bt_value_map_insert_entry() —
1606 Inserts an entry with an existing value in a map value.
1608 extern bt_value_map_insert_entry_status
bt_value_map_insert_bool_entry(
1609 bt_value
*value
, const char *key
, bt_bool raw_value
);
1613 Creates an unsigned integer value initialized to \bt_p{raw_value}
1614 and inserts or replaces an entry with the key \bt_p{key} and this
1615 value in the map value \bt_p{value}.
1617 On success, if \bt_p{value} already contains an entry with key
1618 \bt_p{key}, this function replaces the existing entry's value with the
1619 created unsigned integer value.
1622 Map value in which to insert or replace an entry with key \bt_p{key}
1623 and the created unsigned integer value.
1625 Key of the entry to insert or replace in \bt_p{value} (copied).
1626 @param[in] raw_value
1627 Initial raw value of the unsigned integer value to create.
1629 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1631 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1634 @bt_pre_not_null{value}
1635 @bt_pre_is_map_val{value}
1637 @bt_pre_not_null{key}
1639 @sa bt_value_map_insert_entry() —
1640 Inserts an entry with an existing value in a map value.
1642 extern bt_value_map_insert_entry_status
1643 bt_value_map_insert_unsigned_integer_entry(bt_value
*value
, const char *key
,
1644 uint64_t raw_value
);
1648 Creates a signed integer value initialized to \bt_p{raw_value} and
1649 inserts or replaces an entry with the key \bt_p{key} and this value
1650 in the map value \bt_p{value}.
1652 On success, if \bt_p{value} already contains an entry with key
1653 \bt_p{key}, this function replaces the existing entry's value with the
1654 created signed integer value.
1657 Map value in which to insert or replace an entry with key \bt_p{key}
1658 and the created signed integer value.
1660 Key of the entry to insert or replace in \bt_p{value} (copied).
1661 @param[in] raw_value
1662 Initial raw value of the signed integer value to create.
1664 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1666 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1669 @bt_pre_not_null{value}
1670 @bt_pre_is_map_val{value}
1672 @bt_pre_not_null{key}
1674 @sa bt_value_map_insert_entry() —
1675 Inserts an entry with an existing value in a map value.
1677 extern bt_value_map_insert_entry_status
1678 bt_value_map_insert_signed_integer_entry(bt_value
*value
, const char *key
,
1683 Creates a real value initialized to \bt_p{raw_value} and inserts or
1684 replaces an entry with the key \bt_p{key} and this value in the map
1687 On success, if \bt_p{value} already contains an entry with key
1688 \bt_p{key}, this function replaces the existing entry's value with the
1692 Map value in which to insert or replace an entry with key \bt_p{key}
1693 and the created real value.
1695 Key of the entry to insert or replace in \bt_p{value} (copied).
1696 @param[in] raw_value
1697 Initial raw value of the real value to create.
1699 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1701 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1704 @bt_pre_not_null{value}
1705 @bt_pre_is_map_val{value}
1707 @bt_pre_not_null{key}
1709 @sa bt_value_map_insert_entry() —
1710 Inserts an entry with an existing value in a map value.
1712 extern bt_value_map_insert_entry_status
bt_value_map_insert_real_entry(
1713 bt_value
*value
, const char *key
, double raw_value
);
1717 Creates a string value initialized to a copy of \bt_p{raw_value} and
1718 inserts or replaces an entry with the key \bt_p{key} and this value
1719 in the map value \bt_p{value}.
1721 On success, if \bt_p{value} already contains an entry with key
1722 \bt_p{key}, this function replaces the existing entry's value with the
1723 created string value.
1726 Map value in which to insert or replace an entry with key \bt_p{key}
1727 and the created string value.
1729 Key of the entry to insert or replace in \bt_p{value} (copied).
1730 @param[in] raw_value
1731 Initial raw value of the string value to create (copied).
1733 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1735 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1738 @bt_pre_not_null{value}
1739 @bt_pre_is_map_val{value}
1741 @bt_pre_not_null{key}
1743 @sa bt_value_map_insert_entry() —
1744 Inserts an entry with an existing value in a map value.
1746 extern bt_value_map_insert_entry_status
1747 bt_value_map_insert_string_entry(bt_value
*value
, const char *key
,
1748 const char *raw_value
);
1752 Creates an empty array value and inserts or replaces an entry with
1753 the key \bt_p{key} and this value in the map value \bt_p{value}.
1755 On success, if \bt_p{entry_value} is not \c NULL, this function sets
1756 \bt_p{*entry_value} to a \em borrowed reference of the created empty
1759 On success, if \bt_p{value} already contains an entry with key
1760 \bt_p{key}, this function replaces the existing entry's value with the
1761 created empty array value.
1764 Map value in which to insert or replace an entry with key \bt_p{key}
1765 and the created empty array value.
1767 Key of the entry to insert or replace in \bt_p{value} (copied).
1768 @param[out] entry_value
1769 <strong>On success, if not \c NULL</strong>, \bt_p{*entry_value} is
1770 a \em borrowed reference of the created empty array value.
1772 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1774 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1777 @bt_pre_not_null{value}
1778 @bt_pre_is_map_val{value}
1780 @bt_pre_not_null{key}
1782 @sa bt_value_map_insert_entry() —
1783 Inserts an entry with an existing value in a map value.
1785 extern bt_value_map_insert_entry_status
1786 bt_value_map_insert_empty_array_entry(bt_value
*value
, const char *key
,
1787 bt_value
**entry_value
);
1791 Creates an empty map value and inserts or replaces an entry with
1792 the key \bt_p{key} and this value in the map value \bt_p{value}.
1794 On success, if \bt_p{entry_value} is not \c NULL, this function sets
1795 \bt_p{*entry_value} to a \em borrowed reference of the created empty map
1798 On success, if \bt_p{value} already contains an entry with key
1799 \bt_p{key}, this function replaces the existing entry's value with the
1800 created empty map value.
1803 Map value in which to insert or replace an entry with key \bt_p{key}
1804 and the created empty map value.
1806 Key of the entry to insert or replace in \bt_p{value} (copied).
1807 @param[out] entry_value
1808 <strong>On success, if not \c NULL</strong>, \bt_p{*entry_value} is
1809 a \em borrowed reference of the created empty map value.
1811 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1813 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1816 @bt_pre_not_null{value}
1817 @bt_pre_is_map_val{value}
1819 @bt_pre_not_null{key}
1821 @sa bt_value_map_insert_entry() —
1822 Inserts an entry with an existing value in a map value.
1824 extern bt_value_map_insert_entry_status
1825 bt_value_map_insert_empty_map_entry(bt_value
*value
, const char *key
,
1826 bt_value
**entry_value
);
1830 Borrows the value of the entry with the key \bt_p{key} in the map
1833 If no entry with key \bt_p{key} exists in \bt_p{value}, this function
1837 Map value from which to borrow the value of the entry with the
1840 Key of the entry from which to borrow the value in \bt_p{value}.
1844 \em Borrowed reference of the value of the entry with key \bt_p{key}
1845 in \bt_p{value}, or \c NULL if none.
1847 The returned pointer remains valid until \bt_p{value} is modified.
1850 @bt_pre_not_null{value}
1851 @bt_pre_is_array_val{value}
1852 @bt_pre_not_null{key}
1854 @sa bt_value_map_borrow_entry_value_const() —
1855 \c const version of this function.
1856 @sa bt_value_map_has_entry() —
1857 Returns whether or not a map value has an entry with a given key.
1859 extern bt_value
*bt_value_map_borrow_entry_value(
1860 bt_value
*value
, const char *key
);
1864 Borrows the value of the entry with the key \bt_p{key} in the map
1865 value \bt_p{value} (\c const version).
1867 See bt_value_map_borrow_entry_value().
1869 extern const bt_value
*bt_value_map_borrow_entry_value_const(
1870 const bt_value
*value
, const char *key
);
1874 Status codes for #bt_value_map_foreach_entry_func.
1876 typedef enum bt_value_map_foreach_entry_func_status
{
1881 BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1885 Interrupt the iteration process.
1887 BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_INTERRUPT
= __BT_FUNC_STATUS_INTERRUPTED
,
1893 BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1899 BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
1900 } bt_value_map_foreach_entry_func_status
;
1904 User function for bt_value_map_foreach_entry().
1906 This is the type of the user function that bt_value_map_foreach_entry()
1907 calls for each entry of the map value.
1910 Key of the map value entry.
1912 Value of the map value entry.
1913 @param[in] user_data
1914 User data, as passed as the \bt_p{user_data} parameter of
1915 bt_value_map_foreach_entry().
1917 @retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_OK
1919 @retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_INTERRUPT
1920 Interrupt the iteration process.
1921 @retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_MEMORY_ERROR
1923 @retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_ERROR
1926 @bt_pre_not_null{key}
1927 @bt_pre_not_null{value}
1929 @sa bt_value_map_foreach_entry() —
1930 Iterates the entries of a map value.
1932 typedef bt_value_map_foreach_entry_func_status
1933 (* bt_value_map_foreach_entry_func
)(const char *key
,
1934 bt_value
*value
, void *user_data
);
1938 Status codes for bt_value_map_foreach_entry().
1940 typedef enum bt_value_map_foreach_entry_status
{
1945 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1949 User function interrupted the iteration process.
1951 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_INTERRUPTED
= __BT_FUNC_STATUS_INTERRUPTED
,
1955 User function error.
1957 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_USER_ERROR
= __BT_FUNC_STATUS_USER_ERROR
,
1963 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1969 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
1970 } bt_value_map_foreach_entry_status
;
1974 Iterates the entries of the map value \bt_p{value}, calling
1975 \bt_p{user_func} for each entry.
1977 This function iterates the entries of \bt_p{value} in no particular
1981 You must \em not modify \bt_p{value} during the iteration process.
1983 \bt_p{user_func} receives \bt_p{user_data} as its last parameter.
1985 The iteration process stops when one of:
1987 - \bt_p{user_func} was called for each entry.
1988 - \bt_p{user_func} does not return
1989 #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_OK.
1992 Map value of which to iterate the entries.
1993 @param[in] user_func
1994 User function to call for each entry of \bt_p{value}.
1995 @param[in] user_data
1996 User data to pass as the \bt_p{user_data} parameter of each call to
1999 @retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_OK
2001 @retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_INTERRUPTED
2002 \bt_p{user_func} returned
2003 #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_INTERRUPT to interrupt the
2005 @retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_USER_ERROR
2006 \bt_p{user_func} returned
2007 #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_ERROR.
2008 @retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_MEMORY_ERROR
2010 @retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_ERROR
2011 Other error caused the <code>bt_value_map_foreach_entry()</code>
2014 @bt_pre_not_null{value}
2015 @bt_pre_is_map_val{value}
2016 @bt_pre_not_null{user_func}
2018 @sa bt_value_map_foreach_entry_const() —
2019 \c const version of this function.
2020 @sa bt_value_map_borrow_entry_value() —
2021 Borrows the value of a specific map value entry.
2023 extern bt_value_map_foreach_entry_status
bt_value_map_foreach_entry(
2024 bt_value
*value
, bt_value_map_foreach_entry_func user_func
,
2029 Status codes for #bt_value_map_foreach_entry_const_func.
2031 typedef enum bt_value_map_foreach_entry_const_func_status
{
2036 BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2040 Interrupt the iteration process.
2042 BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_INTERRUPT
= __BT_FUNC_STATUS_INTERRUPTED
,
2048 BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2054 BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
2055 } bt_value_map_foreach_entry_const_func_status
;
2059 User function for bt_value_map_foreach_entry_const_func().
2061 This is the type of the user function that
2062 bt_value_map_foreach_entry_const_func() calls for each entry of the map
2066 Key of the map value entry.
2068 Value of the map value entry.
2069 @param[in] user_data
2072 @retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_OK
2074 @retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_INTERRUPT
2075 Interrupt the iteration process.
2076 @retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_MEMORY_ERROR
2078 @retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_ERROR
2081 @bt_pre_not_null{key}
2082 @bt_pre_not_null{value}
2084 @sa bt_value_map_foreach_entry_const() —
2085 Iterates the entries of a \c const map value.
2087 typedef bt_value_map_foreach_entry_const_func_status
2088 (* bt_value_map_foreach_entry_const_func
)(const char *key
,
2089 const bt_value
*value
, void *user_data
);
2093 Status codes for bt_value_map_foreach_entry_const().
2095 typedef enum bt_value_map_foreach_entry_const_status
{
2100 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2104 User function interrupted the iteration process.
2106 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_INTERRUPTED
= __BT_FUNC_STATUS_INTERRUPTED
,
2110 User function error.
2112 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_USER_ERROR
= __BT_FUNC_STATUS_USER_ERROR
,
2118 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2124 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
2125 } bt_value_map_foreach_entry_const_status
;
2129 Iterates the entries of the map value \bt_p{value}, calling
2130 \bt_p{user_func} for each entry (\c const version).
2132 See bt_value_map_foreach_entry().
2134 @sa bt_value_map_borrow_entry_value_const() —
2135 Borrows the value of a specific map value entry.
2137 extern bt_value_map_foreach_entry_const_status
bt_value_map_foreach_entry_const(
2138 const bt_value
*value
,
2139 bt_value_map_foreach_entry_const_func user_func
,
2144 Returns the size of the map value \bt_p{value}.
2147 Map value of which to get the size.
2150 Size (number of contained entries) of \bt_p{value}.
2152 @bt_pre_not_null{value}
2153 @bt_pre_is_map_val{value}
2155 @sa bt_value_map_is_empty() —
2156 Returns whether or not a map value is empty.
2158 extern uint64_t bt_value_map_get_size(const bt_value
*value
);
2162 Returns whether or not the map value \bt_p{value} is empty.
2168 #BT_TRUE if \bt_p{value} is empty (has the size 0).
2170 @bt_pre_not_null{value}
2171 @bt_pre_is_map_val{value}
2173 @sa bt_value_map_get_size() —
2174 Returns the size of a map value.
2177 bt_bool
bt_value_map_is_empty(const bt_value
*value
)
2179 return bt_value_map_get_size(value
) == 0;
2184 Returns whether or not the map value \bt_p{value} has an entry with
2193 #BT_TRUE if \bt_p{value} has an entry with the key \bt_p{key}.
2195 @bt_pre_not_null{value}
2196 @bt_pre_is_map_val{value}
2197 @bt_pre_not_null{key}
2199 @sa bt_value_map_borrow_entry_value_const() —
2200 Borrows the value of a specific map value entry.
2202 extern bt_bool
bt_value_map_has_entry(const bt_value
*value
,
2207 Status codes for bt_value_map_extend().
2209 typedef enum bt_value_map_extend_status
{
2214 BT_VALUE_MAP_EXTEND_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2220 BT_VALUE_MAP_EXTEND_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2221 } bt_value_map_extend_status
;
2225 Extends the map value \bt_p{value} with the map value
2226 \bt_p{extension_value}.
2228 For each entry in \bt_p{extension_value}, this function calls
2229 bt_value_map_insert_entry() to insert or replace it in the map value
2248 \bt_p{extension_value}
2260 The map value \bt_p{value} becomes:
2271 Map value to extend.
2272 @param[in] extension_value
2273 Extension map value.
2275 @retval #BT_VALUE_MAP_EXTEND_STATUS_OK
2277 @retval #BT_VALUE_MAP_EXTEND_STATUS_MEMORY_ERROR
2280 @bt_pre_not_null{value}
2281 @bt_pre_is_map_val{value}
2282 @bt_pre_not_null{extension_value}
2283 @bt_pre_is_map_val{extension_value}
2285 @sa bt_value_copy() —
2286 Deep-copies a value.
2288 extern bt_value_map_extend_status
bt_value_map_extend(
2289 bt_value
*value
, const bt_value
*extension_value
);
2300 Status codes for bt_value_copy().
2302 typedef enum bt_value_copy_status
{
2307 BT_VALUE_COPY_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2313 BT_VALUE_COPY_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2314 } bt_value_copy_status
;
2318 Deep-copies a value object.
2320 This function deep-copies \bt_p{value} and sets \bt_p{*copy} to the
2323 Because \bt_p{*copy} is a deep copy, it does not contain, recursively,
2324 any reference that \bt_p{value} contains, but the raw values are
2329 @param[in] copy_value
2330 <strong>On success</strong>, \bt_p{*copy_value} is a deep copy of
2333 @retval #BT_VALUE_COPY_STATUS_OK
2335 @retval #BT_VALUE_COPY_STATUS_MEMORY_ERROR
2338 @bt_pre_not_null{value}
2339 @bt_pre_not_null{copy_value}
2341 extern bt_value_copy_status
bt_value_copy(const bt_value
*value
,
2342 bt_value
**copy_value
);
2346 Returns whether or not the value \bt_p{a_value} is equal,
2347 recursively, to \bt_p{b_value}.
2350 If you want to know whether or not a value is a null value, you can
2351 also directly compare its pointer to the #bt_value_null variable.
2359 #BT_TRUE if \bt_p{a_value} is equal, recursively, to \bt_p{b_value}.
2361 @bt_pre_not_null{a_value}
2362 @bt_pre_not_null{b_value}
2364 extern bt_bool
bt_value_is_equal(const bt_value
*a_value
,
2365 const bt_value
*b_value
);
2370 @name Reference count
2376 Increments the \ref api-fund-shared-object "reference count" of
2377 the value \bt_p{value}.
2381 Value of which to increment the reference count.
2386 @sa bt_value_put_ref() —
2387 Decrements the reference count of a value.
2389 extern void bt_value_get_ref(const bt_value
*value
);
2393 Decrements the \ref api-fund-shared-object "reference count" of
2394 the value \bt_p{value}.
2398 Value of which to decrement the reference count.
2403 @sa bt_value_get_ref() —
2404 Increments the reference count of a value.
2406 extern void bt_value_put_ref(const bt_value
*value
);
2410 Decrements the reference count of the value \bt_p{_value}, and then
2411 sets \bt_p{_value} to \c NULL.
2415 Value of which to decrement the reference count.
2417 Can contain \c NULL.
2420 @bt_pre_assign_expr{_value}
2422 #define BT_VALUE_PUT_REF_AND_RESET(_value) \
2424 bt_value_put_ref(_value); \
2430 Decrements the reference count of the value \bt_p{_dst}, sets
2431 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
2433 This macro effectively moves a value reference from the expression
2434 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
2435 \bt_p{_dst} reference.
2439 Destination expression.
2441 Can contain \c NULL.
2447 Can contain \c NULL.
2450 @bt_pre_assign_expr{_dst}
2451 @bt_pre_assign_expr{_src}
2453 #define BT_VALUE_MOVE_REF(_dst, _src) \
2455 bt_value_put_ref(_dst); \
2468 #endif /* BABELTRACE2_VALUE_H */