Fix: bt_value_map_borrow_entry_value(): use `@bt_pre_is_map_val`
[babeltrace.git] / include / babeltrace2 / value.h
1 /*
2 * SPDX-License-Identifier: MIT
3 *
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
5 */
6
7 #ifndef BABELTRACE2_VALUE_H
8 #define BABELTRACE2_VALUE_H
9
10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
11
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
14 #endif
15
16 #include <stdint.h>
17 #include <stddef.h>
18
19 #include <babeltrace2/types.h>
20
21 #ifdef __cplusplus
22 extern "C" {
23 #endif
24
25 /*!
26 @defgroup api-val Values
27
28 @brief
29 Generic, JSON-like basic data containers.
30
31 <strong><em>Values</em></strong> are generic data containers. Except for
32 the fact that integer values are explicitly unsigned or signed because
33 of typing limitations,
34 \bt_name values are very similar to <a href="https://json.org/">JSON</a>
35 values.
36
37 The value API is completely independent from the rest of the
38 \bt_api.
39
40 \bt_c_comp initialization parameters, \ref bt_query_executor_create()
41 "query" parameters, as well as trace IR user attributes (for example,
42 bt_event_class_set_user_attributes()) use values.
43
44 The available value types are:
45
46 <dl>
47 <dt>Scalar values</dt>
48 <dd>
49 - Null
50 - Boolean
51 - Unsigned integer (64-bit range)
52 - Signed integer (64-bit range)
53 - Real (\c double range)
54 - String
55 </dd>
56
57 <dt>Container values</dt>
58 <dd>
59 - Array
60 - Map (string to value)
61 </dd>
62 </dl>
63
64 Values are \ref api-fund-shared-object "shared objects": get a new
65 reference with bt_value_get_ref() and put an existing reference with
66 bt_value_put_ref().
67
68 Some library functions \ref api-fund-freezing "freeze" values on
69 success. The documentation of those functions indicate this
70 postcondition.
71
72 All the value types share the same C type, #bt_value.
73
74 Get the type enumerator of a value with bt_value_get_type(). Get whether
75 or not a value type conceptually \em is a given type with the inline
76 bt_value_type_is() function. Get whether or not a value has a specific
77 type with one of the <code>bt_value_is_*()</code> inline helpers.
78
79 The \em null value is special in that it's a singleton variable,
80 #bt_value_null. You can directly compare any value pointer to
81 #bt_value_null to check if it's a null value. Like other types of
82 values, the null value is a shared object: if you get a new null value
83 reference, you must eventually put it.
84
85 Create a value with one of the <code>bt_value_*_create()</code> or
86 <code>bt_value_*_create_init()</code> functions.
87
88 This documentation names the actual data that a scalar value wraps the
89 <em>raw value</em>.
90
91 Set and get the raw values of scalar values with functions that are
92 named <code>bt_value_*_set()</code> and <code>bt_value_*_get()</code>.
93
94 Check that two values are recursively equal with bt_value_is_equal().
95
96 Deep-copy a value with bt_value_copy().
97
98 Extend a map value with bt_value_map_extend().
99
100 The following table shows the available functions and types for each
101 type of value:
102
103 <table>
104 <tr>
105 <th>Name
106 <th>Type enumerator
107 <th>Type query function
108 <th>Creation functions
109 <th>Writing functions
110 <th>Reading functions
111 <tr>
112 <th>\em Null
113 <td>#BT_VALUE_TYPE_NULL
114 <td>bt_value_is_null()
115 <td>\em N/A (use the #bt_value_null variable directly)
116 <td>\em N/A
117 <td>\em N/A
118 <tr>
119 <th>\em Boolean
120 <td>#BT_VALUE_TYPE_BOOL
121 <td>bt_value_is_bool()
122 <td>
123 bt_value_bool_create()<br>
124 bt_value_bool_create_init()
125 <td>bt_value_bool_set()
126 <td>bt_value_bool_get()
127 <tr>
128 <th><em>Unsigned integer</em>
129 <td>#BT_VALUE_TYPE_UNSIGNED_INTEGER
130 <td>bt_value_is_unsigned_integer()
131 <td>
132 bt_value_integer_unsigned_create()<br>
133 bt_value_integer_unsigned_create_init()
134 <td>bt_value_integer_unsigned_set()
135 <td>bt_value_integer_unsigned_get()
136 <tr>
137 <th><em>Signed integer</em>
138 <td>#BT_VALUE_TYPE_SIGNED_INTEGER
139 <td>bt_value_is_signed_integer()
140 <td>
141 bt_value_integer_signed_create()<br>
142 bt_value_integer_signed_create_init()
143 <td>bt_value_integer_signed_set()
144 <td>bt_value_integer_signed_get()
145 <tr>
146 <th>\em Real
147 <td>#BT_VALUE_TYPE_REAL
148 <td>bt_value_is_real()
149 <td>
150 bt_value_real_create()<br>
151 bt_value_real_create_init()
152 <td>bt_value_real_set()
153 <td>bt_value_real_get()
154 <tr>
155 <th>\em String
156 <td>#BT_VALUE_TYPE_STRING
157 <td>bt_value_is_string()
158 <td>
159 bt_value_string_create()<br>
160 bt_value_string_create_init()
161 <td>bt_value_string_set()
162 <td>bt_value_string_get()
163 <tr>
164 <th>\em Array
165 <td>#BT_VALUE_TYPE_ARRAY
166 <td>bt_value_is_array()
167 <td>
168 bt_value_array_create()
169 <td>
170 bt_value_array_append_element()<br>
171 bt_value_array_append_bool_element()<br>
172 bt_value_array_append_unsigned_integer_element()<br>
173 bt_value_array_append_signed_integer_element()<br>
174 bt_value_array_append_real_element()<br>
175 bt_value_array_append_string_element()<br>
176 bt_value_array_append_empty_array_element()<br>
177 bt_value_array_append_empty_map_element()<br>
178 bt_value_array_set_element_by_index()
179 <td>
180 bt_value_array_get_length()<br>
181 bt_value_array_is_empty()<br>
182 bt_value_array_borrow_element_by_index()<br>
183 bt_value_array_borrow_element_by_index_const()
184 <tr>
185 <th>\em Map
186 <td>#BT_VALUE_TYPE_MAP
187 <td>bt_value_is_map()
188 <td>
189 bt_value_map_create()
190 <td>
191 bt_value_map_insert_entry()<br>
192 bt_value_map_insert_bool_entry()<br>
193 bt_value_map_insert_unsigned_integer_entry()<br>
194 bt_value_map_insert_signed_integer_entry()<br>
195 bt_value_map_insert_real_entry()<br>
196 bt_value_map_insert_string_entry()<br>
197 bt_value_map_insert_empty_array_entry()<br>
198 bt_value_map_insert_empty_map_entry()<br>
199 bt_value_map_extend()
200 <td>
201 bt_value_map_get_size()<br>
202 bt_value_map_is_empty()<br>
203 bt_value_map_has_entry()<br>
204 bt_value_map_borrow_entry_value()<br>
205 bt_value_map_borrow_entry_value_const()<br>
206 bt_value_map_foreach_entry()<br>
207 bt_value_map_foreach_entry_const()
208 </table>
209 */
210
211 /*! @{ */
212
213 /*!
214 @name Type
215 @{
216
217 @typedef struct bt_value bt_value;
218
219 @brief
220 Value.
221
222 @}
223 */
224
225 /*!
226 @name Type query
227 @{
228 */
229
230 /*!
231 @brief
232 Value type enumerators.
233 */
234 typedef enum bt_value_type {
235 /*!
236 @brief
237 Null value.
238 */
239 BT_VALUE_TYPE_NULL = 1 << 0,
240
241 /*!
242 @brief
243 Boolean value.
244 */
245 BT_VALUE_TYPE_BOOL = 1 << 1,
246
247 /*!
248 @brief
249 Integer value.
250
251 No value has this type: use it with bt_value_type_is().
252 */
253 BT_VALUE_TYPE_INTEGER = 1 << 2,
254
255 /*!
256 @brief
257 Unsigned integer value.
258
259 This type conceptually inherits #BT_VALUE_TYPE_INTEGER.
260 */
261 BT_VALUE_TYPE_UNSIGNED_INTEGER = (1 << 3) | BT_VALUE_TYPE_INTEGER,
262
263 /*!
264 @brief
265 Signed integer value.
266
267 This type conceptually inherits #BT_VALUE_TYPE_INTEGER.
268 */
269 BT_VALUE_TYPE_SIGNED_INTEGER = (1 << 4) | BT_VALUE_TYPE_INTEGER,
270
271 /*!
272 @brief
273 Real value.
274 */
275 BT_VALUE_TYPE_REAL = 1 << 5,
276
277 /*!
278 @brief
279 String value.
280 */
281 BT_VALUE_TYPE_STRING = 1 << 6,
282
283 /*!
284 @brief
285 Array value.
286 */
287 BT_VALUE_TYPE_ARRAY = 1 << 7,
288
289 /*!
290 @brief
291 Map value.
292 */
293 BT_VALUE_TYPE_MAP = 1 << 8,
294 } bt_value_type;
295
296 /*!
297 @brief
298 Returns the type enumerator of the value \bt_p{value}.
299
300 @param[in] value
301 Value of which to get the type enumerator
302
303 @returns
304 Type enumerator of \bt_p{value}.
305
306 @bt_pre_not_null{value}
307
308 @sa bt_value_type_is() &mdash;
309 Returns whether or not the type of a value conceptually is a given
310 type.
311 @sa bt_value_is_null() &mdash;
312 Returns whether or not a value is a null value.
313 @sa bt_value_is_bool() &mdash;
314 Returns whether or not a value is a boolean value.
315 @sa bt_value_is_unsigned_integer() &mdash;
316 Returns whether or not a value is an unsigned integer value.
317 @sa bt_value_is_signed_integer() &mdash;
318 Returns whether or not a value is a signed integer value.
319 @sa bt_value_is_real() &mdash;
320 Returns whether or not a value is a real value.
321 @sa bt_value_is_string() &mdash;
322 Returns whether or not a value is a string value.
323 @sa bt_value_is_array() &mdash;
324 Returns whether or not a value is an array value.
325 @sa bt_value_is_map() &mdash;
326 Returns whether or not a value is a map value.
327 */
328 extern bt_value_type bt_value_get_type(const bt_value *value) __BT_NOEXCEPT;
329
330 /*!
331 @brief
332 Returns whether or not the value type \bt_p{type} conceptually
333 \em is the value type \bt_p{other_type}.
334
335 For example, an unsigned integer value conceptually \em is an integer
336 value, so
337
338 @code
339 bt_value_type_is(BT_VALUE_TYPE_UNSIGNED_INTEGER, BT_VALUE_TYPE_INTEGER)
340 @endcode
341
342 returns #BT_TRUE.
343
344 @param[in] type
345 Value type to check against \bt_p{other_type}.
346 @param[in] other_type
347 Value type against which to check \bt_p{type}.
348
349 @returns
350 #BT_TRUE if \bt_p{type} conceptually \em is \bt_p{other_type}.
351
352 @sa bt_value_get_type() &mdash;
353 Returns the type enumerator of a value.
354 @sa bt_value_is_null() &mdash;
355 Returns whether or not a value is a null value.
356 @sa bt_value_is_bool() &mdash;
357 Returns whether or not a value is a boolean value.
358 @sa bt_value_is_unsigned_integer() &mdash;
359 Returns whether or not a value is an unsigned integer value.
360 @sa bt_value_is_signed_integer() &mdash;
361 Returns whether or not a value is a signed integer value.
362 @sa bt_value_is_real() &mdash;
363 Returns whether or not a value is a real value.
364 @sa bt_value_is_string() &mdash;
365 Returns whether or not a value is a string value.
366 @sa bt_value_is_array() &mdash;
367 Returns whether or not a value is an array value.
368 @sa bt_value_is_map() &mdash;
369 Returns whether or not a value is a map value.
370 */
371 static inline
372 bt_bool bt_value_type_is(const bt_value_type type,
373 const bt_value_type other_type) __BT_NOEXCEPT
374 {
375 return (type & other_type) == other_type;
376 }
377
378 /*!
379 @brief
380 Returns whether or not the value \bt_p{value} is a null value.
381
382 @note
383 Because all null values point to the same null value singleton, you
384 can also directly compare \bt_p{value} to the #bt_value_null
385 variable.
386
387 @param[in] value
388 Value to check.
389
390 @returns
391 #BT_TRUE if \bt_p{value} is a null value.
392
393 @bt_pre_not_null{value}
394
395 @sa bt_value_get_type() &mdash;
396 Returns the type enumerator of a value.
397 @sa bt_value_type_is() &mdash;
398 Returns whether or not the type of a value conceptually is a given
399 type.
400 @sa #bt_value_null &mdash;
401 The null value singleton.
402 */
403 static inline
404 bt_bool bt_value_is_null(const bt_value *value) __BT_NOEXCEPT
405 {
406 return bt_value_get_type(value) == BT_VALUE_TYPE_NULL;
407 }
408
409 /*!
410 @brief
411 Returns whether or not the value \bt_p{value} is a boolean value.
412
413 @param[in] value
414 Value to check.
415
416 @returns
417 #BT_TRUE if \bt_p{value} is a boolean value.
418
419 @bt_pre_not_null{value}
420
421 @sa bt_value_get_type() &mdash;
422 Returns the type enumerator of a value.
423 @sa bt_value_type_is() &mdash;
424 Returns whether or not the type of a value conceptually is a given
425 type.
426 */
427 static inline
428 bt_bool bt_value_is_bool(const bt_value *value) __BT_NOEXCEPT
429 {
430 return bt_value_get_type(value) == BT_VALUE_TYPE_BOOL;
431 }
432
433 /*!
434 @brief
435 Returns whether or not the value \bt_p{value} is an unsigned integer
436 value.
437
438 @param[in] value
439 Value to check.
440
441 @returns
442 #BT_TRUE if \bt_p{value} is an unsigned integer value.
443
444 @bt_pre_not_null{value}
445
446 @sa bt_value_get_type() &mdash;
447 Returns the type enumerator of a value.
448 @sa bt_value_type_is() &mdash;
449 Returns whether or not the type of a value conceptually is a given
450 type.
451 */
452 static inline
453 bt_bool bt_value_is_unsigned_integer(const bt_value *value) __BT_NOEXCEPT
454 {
455 return bt_value_get_type(value) == BT_VALUE_TYPE_UNSIGNED_INTEGER;
456 }
457
458 /*!
459 @brief
460 Returns whether or not the value \bt_p{value} is a signed integer
461 value.
462
463 @param[in] value
464 Value to check.
465
466 @returns
467 #BT_TRUE if \bt_p{value} is a signed integer value.
468
469 @bt_pre_not_null{value}
470
471 @sa bt_value_get_type() &mdash;
472 Returns the type enumerator of a value.
473 @sa bt_value_type_is() &mdash;
474 Returns whether or not the type of a value conceptually is a given
475 type.
476 */
477 static inline
478 bt_bool bt_value_is_signed_integer(const bt_value *value) __BT_NOEXCEPT
479 {
480 return bt_value_get_type(value) == BT_VALUE_TYPE_SIGNED_INTEGER;
481 }
482
483 /*!
484 @brief
485 Returns whether or not the value \bt_p{value} is a real value.
486
487 @param[in] value
488 Value to check.
489
490 @returns
491 #BT_TRUE if \bt_p{value} is a real value.
492
493 @bt_pre_not_null{value}
494
495 @sa bt_value_get_type() &mdash;
496 Returns the type enumerator of a value.
497 @sa bt_value_type_is() &mdash;
498 Returns whether or not the type of a value conceptually is a given
499 type.
500 */
501 static inline
502 bt_bool bt_value_is_real(const bt_value *value) __BT_NOEXCEPT
503 {
504 return bt_value_get_type(value) == BT_VALUE_TYPE_REAL;
505 }
506
507 /*!
508 @brief
509 Returns whether or not the value \bt_p{value} is a string value.
510
511 @param[in] value
512 Value to check.
513
514 @returns
515 #BT_TRUE if \bt_p{value} is a string value.
516
517 @bt_pre_not_null{value}
518
519 @sa bt_value_get_type() &mdash;
520 Returns the type enumerator of a value.
521 @sa bt_value_type_is() &mdash;
522 Returns whether or not the type of a value conceptually is a given
523 type.
524 */
525 static inline
526 bt_bool bt_value_is_string(const bt_value *value) __BT_NOEXCEPT
527 {
528 return bt_value_get_type(value) == BT_VALUE_TYPE_STRING;
529 }
530
531 /*!
532 @brief
533 Returns whether or not the value \bt_p{value} is an array value.
534
535 @param[in] value
536 Value to check.
537
538 @returns
539 #BT_TRUE if \bt_p{value} is an array value.
540
541 @bt_pre_not_null{value}
542
543 @sa bt_value_get_type() &mdash;
544 Returns the type enumerator of a value.
545 @sa bt_value_type_is() &mdash;
546 Returns whether or not the type of a value conceptually is a given
547 type.
548 */
549 static inline
550 bt_bool bt_value_is_array(const bt_value *value) __BT_NOEXCEPT
551 {
552 return bt_value_get_type(value) == BT_VALUE_TYPE_ARRAY;
553 }
554
555 /*!
556 @brief
557 Returns whether or not the value \bt_p{value} is a map value.
558
559 @param[in] value
560 Value to check.
561
562 @returns
563 #BT_TRUE if \bt_p{value} is a map value.
564
565 @bt_pre_not_null{value}
566
567 @sa bt_value_get_type() &mdash;
568 Returns the type enumerator of a value.
569 @sa bt_value_type_is() &mdash;
570 Returns whether or not the type of a value conceptually is a given
571 type.
572 */
573 static inline
574 bt_bool bt_value_is_map(const bt_value *value) __BT_NOEXCEPT
575 {
576 return bt_value_get_type(value) == BT_VALUE_TYPE_MAP;
577 }
578
579 /*! @} */
580
581 /*!
582 @name Null value
583 @{
584 */
585
586 /*!
587 @brief
588 The null value singleton.
589
590 This is the \em only instance of a null value.
591
592 Like any type of value, the null value is a shared object: if you get a
593 new null value reference with bt_value_get_ref(), you must eventually
594 put it with bt_value_put_ref(). The null value singleton's reference
595 count must never reach 0: libbabeltrace2 logs a warning message when
596 this programming error occurs.
597
598 Because all null values point to the same null value singleton, you can
599 directly compare a value to the \c bt_value_null variable.
600
601 @attention
602 @parblock
603 \c bt_value_null is different from \c NULL: the former is a true
604 \bt_name value object while the latter is a C definition which
605 usually means "no pointer".
606
607 For example, bt_value_map_borrow_entry_value() can return
608 \c bt_value_null if the requested key is mapped to a null value, but
609 it can also return \c NULL if the key is not found.
610 @endparblock
611
612 @sa bt_value_is_null() &mdash;
613 Returns whether or not a value is a null value.
614 */
615 extern bt_value *const bt_value_null;
616
617 /*! @} */
618
619 /*!
620 @name Boolean value
621 @{
622 */
623
624 /*!
625 @brief
626 Creates and returns a boolean value initialized to #BT_FALSE.
627
628 The returned value has the type #BT_VALUE_TYPE_BOOL.
629
630 @returns
631 New boolean value reference, or \c NULL on memory error.
632
633 @sa bt_value_bool_create_init() &mdash;
634 Creates a boolean value with a given initial raw value.
635 */
636 extern bt_value *bt_value_bool_create(void) __BT_NOEXCEPT;
637
638 /*!
639 @brief
640 Creates and returns a boolean value initialized to \bt_p{raw_value}.
641
642 The returned value has the type #BT_VALUE_TYPE_BOOL.
643
644 @param[in] raw_value
645 Initial raw value of the boolean value to create.
646
647 @returns
648 New boolean value reference, or \c NULL on memory error.
649
650 @sa bt_value_bool_create() &mdash;
651 Creates a boolean value initialized to #BT_FALSE.
652 */
653 extern bt_value *bt_value_bool_create_init(bt_bool raw_value) __BT_NOEXCEPT;
654
655 /*!
656 @brief
657 Sets the raw value of the boolean value \bt_p{value} to
658 \bt_p{raw_value}.
659
660 @param[in] value
661 Boolean value of which to set the raw value to \bt_p{raw_value}.
662 @param[in] raw_value
663 New raw value of \bt_p{value}.
664
665 @bt_pre_not_null{value}
666 @bt_pre_is_bool_val{value}
667 @bt_pre_hot{value}
668
669 @sa bt_value_bool_get() &mdash;
670 Returns the raw value of a boolean value.
671 */
672 extern void bt_value_bool_set(bt_value *value, bt_bool raw_value) __BT_NOEXCEPT;
673
674 /*!
675 @brief
676 Returns the raw value of the boolean value \bt_p{value}.
677
678 @param[in] value
679 Boolean value of which to get the raw value.
680
681 @returns
682 Raw value of \bt_p{value}.
683
684 @bt_pre_not_null{value}
685 @bt_pre_is_bool_val{value}
686
687 @sa bt_value_bool_set() &mdash;
688 Sets the raw value of a boolean value.
689 */
690 extern bt_bool bt_value_bool_get(const bt_value *value) __BT_NOEXCEPT;
691
692 /*! @} */
693
694 /*!
695 @name Unsigned integer value
696 @{
697 */
698
699 /*!
700 @brief
701 Creates and returns an unsigned integer value initialized to 0.
702
703 The returned value has the type #BT_VALUE_TYPE_UNSIGNED_INTEGER.
704
705 @returns
706 New unsigned integer value reference, or \c NULL on memory error.
707
708 @sa bt_value_integer_unsigned_create_init() &mdash;
709 Creates an unsigned integer value with a given initial raw value.
710 */
711 extern bt_value *bt_value_integer_unsigned_create(void) __BT_NOEXCEPT;
712
713 /*!
714 @brief
715 Creates and returns an unsigned integer value initialized to
716 \bt_p{raw_value}.
717
718 The returned value has the type #BT_VALUE_TYPE_UNSIGNED_INTEGER.
719
720 @param[in] raw_value
721 Initial raw value of the unsigned integer value to create.
722
723 @returns
724 New unsigned integer value reference, or \c NULL on memory error.
725
726 @sa bt_value_bool_create() &mdash;
727 Creates an unsigned integer value initialized to 0.
728 */
729 extern bt_value *bt_value_integer_unsigned_create_init(uint64_t raw_value) __BT_NOEXCEPT;
730
731 /*!
732 @brief
733 Sets the raw value of the unsigned integer value \bt_p{value} to
734 \bt_p{raw_value}.
735
736 @param[in] value
737 Unsigned integer value of which to set the raw value to
738 \bt_p{raw_value}.
739 @param[in] raw_value
740 New raw value of \bt_p{value}.
741
742 @bt_pre_not_null{value}
743 @bt_pre_is_uint_val{value}
744 @bt_pre_hot{value}
745
746 @sa bt_value_integer_unsigned_get() &mdash;
747 Returns the raw value of an unsigned integer value.
748 */
749 extern void bt_value_integer_unsigned_set(bt_value *value,
750 uint64_t raw_value) __BT_NOEXCEPT;
751
752 /*!
753 @brief
754 Returns the raw value of the unsigned integer value \bt_p{value}.
755
756 @param[in] value
757 Unsigned integer value of which to get the raw value.
758
759 @returns
760 Raw value of \bt_p{value}.
761
762 @bt_pre_not_null{value}
763 @bt_pre_is_uint_val{value}
764
765 @sa bt_value_integer_unsigned_set() &mdash;
766 Sets the raw value of an unsigned integer value.
767 */
768 extern uint64_t bt_value_integer_unsigned_get(const bt_value *value) __BT_NOEXCEPT;
769
770 /*! @} */
771
772 /*!
773 @name Signed integer value
774 @{
775 */
776
777 /*!
778 @brief
779 Creates and returns a signed integer value initialized to 0.
780
781 The returned value has the type #BT_VALUE_TYPE_SIGNED_INTEGER.
782
783 @returns
784 New signed integer value reference, or \c NULL on memory error.
785
786 @sa bt_value_integer_signed_create_init() &mdash;
787 Creates a signed integer value with a given initial raw value.
788 */
789 extern bt_value *bt_value_integer_signed_create(void) __BT_NOEXCEPT;
790
791 /*!
792 @brief
793 Creates and returns a signed integer value initialized to
794 \bt_p{raw_value}.
795
796 The returned value has the type #BT_VALUE_TYPE_SIGNED_INTEGER.
797
798 @param[in] raw_value
799 Initial raw value of the signed integer value to create.
800
801 @returns
802 New signed integer value reference, or \c NULL on memory error.
803
804 @sa bt_value_bool_create() &mdash;
805 Creates a signed integer value initialized to 0.
806 */
807 extern bt_value *bt_value_integer_signed_create_init(int64_t raw_value) __BT_NOEXCEPT;
808
809 /*!
810 @brief
811 Sets the raw value of the signed integer value \bt_p{value} to
812 \bt_p{raw_value}.
813
814 @param[in] value
815 Signed integer value of which to set the raw value to
816 \bt_p{raw_value}.
817 @param[in] raw_value
818 New raw value of \bt_p{value}.
819
820 @bt_pre_not_null{value}
821 @bt_pre_is_sint_val{value}
822 @bt_pre_hot{value}
823
824 @sa bt_value_integer_signed_get() &mdash;
825 Returns the raw value of a signed integer value.
826 */
827 extern void bt_value_integer_signed_set(bt_value *value, int64_t raw_value) __BT_NOEXCEPT;
828
829 /*!
830 @brief
831 Returns the raw value of the signed integer value \bt_p{value}.
832
833 @param[in] value
834 Signed integer value of which to get the raw value.
835
836 @returns
837 Raw value of \bt_p{value}.
838
839 @bt_pre_not_null{value}
840 @bt_pre_is_sint_val{value}
841
842 @sa bt_value_integer_signed_set() &mdash;
843 Sets the raw value of a signed integer value.
844 */
845 extern int64_t bt_value_integer_signed_get(const bt_value *value) __BT_NOEXCEPT;
846
847 /*! @} */
848
849 /*!
850 @name Real value
851 @{
852 */
853
854 /*!
855 @brief
856 Creates and returns a real value initialized to 0.
857
858 The returned value has the type #BT_VALUE_TYPE_REAL.
859
860 @returns
861 New real value reference, or \c NULL on memory error.
862
863 @sa bt_value_real_create_init() &mdash;
864 Creates a real value with a given initial raw value.
865 */
866 extern bt_value *bt_value_real_create(void) __BT_NOEXCEPT;
867
868 /*!
869 @brief
870 Creates and returns a real value initialized to \bt_p{raw_value}.
871
872 The returned value has the type #BT_VALUE_TYPE_REAL.
873
874 @param[in] raw_value
875 Initial raw value of the real value to create.
876
877 @returns
878 New real value reference, or \c NULL on memory error.
879
880 @sa bt_value_real_create() &mdash;
881 Creates a real value initialized to 0.
882 */
883 extern bt_value *bt_value_real_create_init(double raw_value) __BT_NOEXCEPT;
884
885 /*!
886 @brief
887 Sets the raw value of the real value \bt_p{value} to
888 \bt_p{raw_value}.
889
890 @param[in] value
891 Real value of which to set the raw value to \bt_p{raw_value}.
892 @param[in] raw_value
893 New raw value of \bt_p{value}.
894
895 @bt_pre_not_null{value}
896 @bt_pre_is_real_val{value}
897 @bt_pre_hot{value}
898
899 @sa bt_value_real_get() &mdash;
900 Returns the raw value of a real value.
901 */
902 extern void bt_value_real_set(bt_value *value, double raw_value) __BT_NOEXCEPT;
903
904 /*!
905 @brief
906 Returns the raw value of the real value \bt_p{value}.
907
908 @param[in] value
909 Real value of which to get the raw value.
910
911 @returns
912 Raw value of \bt_p{value}.
913
914 @bt_pre_not_null{value}
915 @bt_pre_is_real_val{value}
916
917 @sa bt_value_real_set() &mdash;
918 Sets the raw value of a real value.
919 */
920 extern double bt_value_real_get(const bt_value *value) __BT_NOEXCEPT;
921
922 /*! @} */
923
924 /*!
925 @name String value
926 @{
927 */
928
929 /*!
930 @brief
931 Creates and returns an empty string value.
932
933 The returned value has the type #BT_VALUE_TYPE_STRING.
934
935 @returns
936 New string value reference, or \c NULL on memory error.
937
938 @sa bt_value_string_create_init() &mdash;
939 Creates a string value with a given initial raw value.
940 */
941 extern bt_value *bt_value_string_create(void) __BT_NOEXCEPT;
942
943 /*!
944 @brief
945 Creates and returns a string value initialized to a copy of
946 \bt_p{raw_value}.
947
948 The returned value has the type #BT_VALUE_TYPE_STRING.
949
950 @param[in] raw_value
951 Initial raw value of the string value to create (copied).
952
953 @returns
954 New string value reference, or \c NULL on memory error.
955
956 @bt_pre_not_null{raw_value}
957
958 @sa bt_value_string_create() &mdash;
959 Creates an empty string value.
960 */
961 extern bt_value *bt_value_string_create_init(const char *raw_value) __BT_NOEXCEPT;
962
963 /*!
964 @brief
965 Status codes for bt_value_string_set().
966 */
967 typedef enum bt_value_string_set_status {
968 /*!
969 @brief
970 Success.
971 */
972 BT_VALUE_STRING_SET_STATUS_OK = __BT_FUNC_STATUS_OK,
973
974 /*!
975 @brief
976 Out of memory.
977 */
978 BT_VALUE_STRING_SET_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
979 } bt_value_string_set_status;
980
981 /*!
982 @brief
983 Sets the raw value of the string value \bt_p{value} to a copy of
984 \bt_p{raw_value}.
985
986 @param[in] value
987 String value of which to set the raw value to a copy of
988 \bt_p{raw_value}.
989 @param[in] raw_value
990 New raw value of \bt_p{value} (copied).
991
992 @retval #BT_VALUE_STRING_SET_STATUS_OK
993 Success.
994 @retval #BT_VALUE_STRING_SET_STATUS_MEMORY_ERROR
995 Out of memory.
996
997 @bt_pre_not_null{value}
998 @bt_pre_is_string_val{value}
999 @bt_pre_hot{value}
1000 @bt_pre_not_null{raw_value}
1001
1002 @sa bt_value_string_get() &mdash;
1003 Returns the raw value of a string value.
1004 */
1005 extern bt_value_string_set_status bt_value_string_set(bt_value *value,
1006 const char *raw_value) __BT_NOEXCEPT;
1007
1008 /*!
1009 @brief
1010 Returns the raw value of the string value \bt_p{value}.
1011
1012 @param[in] value
1013 String value of which to get the raw value.
1014
1015 @returns
1016 @parblock
1017 Raw value of \bt_p{value}.
1018
1019 The returned pointer remains valid until \bt_p{value} is modified.
1020 @endparblock
1021
1022 @bt_pre_not_null{value}
1023 @bt_pre_is_string_val{value}
1024
1025 @sa bt_value_string_set() &mdash;
1026 Sets the raw value of a string value.
1027 */
1028 extern const char *bt_value_string_get(const bt_value *value) __BT_NOEXCEPT;
1029
1030 /*! @} */
1031
1032 /*!
1033 @name Array value
1034 @{
1035 */
1036
1037 /*!
1038 @brief
1039 Creates and returns an empty array value.
1040
1041 The returned value has the type #BT_VALUE_TYPE_ARRAY.
1042
1043 @returns
1044 New array value reference, or \c NULL on memory error.
1045 */
1046 extern bt_value *bt_value_array_create(void) __BT_NOEXCEPT;
1047
1048 /*!
1049 @brief
1050 Status codes for the <code>bt_value_array_append_*()</code>
1051 functions.
1052 */
1053 typedef enum bt_value_array_append_element_status {
1054 /*!
1055 @brief
1056 Success.
1057 */
1058 BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK = __BT_FUNC_STATUS_OK,
1059
1060 /*!
1061 @brief
1062 Out of memory.
1063 */
1064 BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
1065 } bt_value_array_append_element_status;
1066
1067 /*!
1068 @brief
1069 Appends the value \bt_p{element_value} to the array value \bt_p{value}.
1070
1071 To append a null value, pass #bt_value_null as \bt_p{element_value}.
1072
1073 @param[in] value
1074 Array value to which to append \bt_p{element_value}.
1075 @param[in] element_value
1076 Value to append to \bt_p{value}.
1077
1078 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1079 Success.
1080 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1081 Out of memory.
1082
1083 @bt_pre_not_null{value}
1084 @bt_pre_is_array_val{value}
1085 @bt_pre_hot{value}
1086 @bt_pre_not_null{element_value}
1087 @pre
1088 \bt_p{element_value} does not contain \bt_p{value}, recursively.
1089
1090 @post
1091 <strong>On success</strong>, the length of \bt_p{value} is
1092 incremented.
1093
1094 @sa bt_value_array_append_bool_element() &mdash;
1095 Creates and appends a boolean value to an array value.
1096 @sa bt_value_array_append_unsigned_integer_element() &mdash;
1097 Creates and appends an unsigned integer value to an array value.
1098 @sa bt_value_array_append_signed_integer_element() &mdash;
1099 Creates and appends a signed integer value to an array value.
1100 @sa bt_value_array_append_real_element() &mdash;
1101 Creates and appends a real value to an array value.
1102 @sa bt_value_array_append_string_element() &mdash;
1103 Creates and appends a string value to an array value.
1104 @sa bt_value_array_append_empty_array_element() &mdash;
1105 Creates and appends an empty array value to an array value.
1106 @sa bt_value_array_append_empty_map_element() &mdash;
1107 Creates and appends an empty map value to an array value.
1108 */
1109 extern bt_value_array_append_element_status bt_value_array_append_element(
1110 bt_value *value, bt_value *element_value) __BT_NOEXCEPT;
1111
1112 /*!
1113 @brief
1114 Creates a boolean value initialized to \bt_p{raw_value} and appends
1115 it to the array value \bt_p{value}.
1116
1117 @param[in] value
1118 Array value to which to append the created boolean value.
1119 @param[in] raw_value
1120 Raw value of the boolean value to create and append to \bt_p{value}.
1121
1122 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1123 Success.
1124 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1125 Out of memory.
1126
1127 @bt_pre_not_null{value}
1128 @bt_pre_is_array_val{value}
1129 @bt_pre_hot{value}
1130
1131 @post
1132 <strong>On success</strong>, the length of \bt_p{value} is
1133 incremented.
1134
1135 @sa bt_value_array_append_element() &mdash;
1136 Appends an existing value to an array value.
1137 */
1138 extern bt_value_array_append_element_status
1139 bt_value_array_append_bool_element(bt_value *value, bt_bool raw_value) __BT_NOEXCEPT;
1140
1141 /*!
1142 @brief
1143 Creates an unsigned integer value initialized to \bt_p{raw_value}
1144 and appends it to the array value \bt_p{value}.
1145
1146 @param[in] value
1147 Array value to which to append the created unsigned integer value.
1148 @param[in] raw_value
1149 Raw value of the unsigned integer value to create and append to
1150 \bt_p{value}.
1151
1152 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1153 Success.
1154 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1155 Out of memory.
1156
1157 @bt_pre_not_null{value}
1158 @bt_pre_is_array_val{value}
1159 @bt_pre_hot{value}
1160
1161 @post
1162 <strong>On success</strong>, the length of \bt_p{value} is
1163 incremented.
1164
1165 @sa bt_value_array_append_element() &mdash;
1166 Appends an existing value to an array value.
1167 */
1168 extern bt_value_array_append_element_status
1169 bt_value_array_append_unsigned_integer_element(bt_value *value,
1170 uint64_t raw_value) __BT_NOEXCEPT;
1171
1172 /*!
1173 @brief
1174 Creates a signed integer value initialized to \bt_p{raw_value} and
1175 appends it to the array value \bt_p{value}.
1176
1177 @param[in] value
1178 Array value to which to append the created signed integer value.
1179 @param[in] raw_value
1180 Raw value of the signed integer value to create and append to
1181 \bt_p{value}.
1182
1183 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1184 Success.
1185 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1186 Out of memory.
1187
1188 @bt_pre_not_null{value}
1189 @bt_pre_is_array_val{value}
1190 @bt_pre_hot{value}
1191
1192 @post
1193 <strong>On success</strong>, the length of \bt_p{value} is
1194 incremented.
1195
1196 @sa bt_value_array_append_element() &mdash;
1197 Appends an existing value to an array value.
1198 */
1199 extern bt_value_array_append_element_status
1200 bt_value_array_append_signed_integer_element(bt_value *value,
1201 int64_t raw_value) __BT_NOEXCEPT;
1202
1203 /*!
1204 @brief
1205 Creates a real value initialized to \bt_p{raw_value} and appends
1206 it to the array value \bt_p{value}.
1207
1208 @param[in] value
1209 Array value to which to append the created real value.
1210 @param[in] raw_value
1211 Raw value of the real value to create and append to \bt_p{value}.
1212
1213 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1214 Success.
1215 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1216 Out of memory.
1217
1218 @bt_pre_not_null{value}
1219 @bt_pre_is_array_val{value}
1220 @bt_pre_hot{value}
1221
1222 @post
1223 <strong>On success</strong>, the length of \bt_p{value} is
1224 incremented.
1225
1226 @sa bt_value_array_append_element() &mdash;
1227 Appends an existing value to an array value.
1228 */
1229 extern bt_value_array_append_element_status
1230 bt_value_array_append_real_element(bt_value *value, double raw_value) __BT_NOEXCEPT;
1231
1232 /*!
1233 @brief
1234 Creates a string value initialized to a copy of \bt_p{raw_value} and
1235 appends it to the array value \bt_p{value}.
1236
1237 @param[in] value
1238 Array value to which to append the created string value.
1239 @param[in] raw_value
1240 Raw value of the string value to create and append to \bt_p{value}
1241 (copied).
1242
1243 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1244 Success.
1245 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1246 Out of memory.
1247
1248 @bt_pre_not_null{value}
1249 @bt_pre_is_array_val{value}
1250 @bt_pre_hot{value}
1251
1252 @post
1253 <strong>On success</strong>, the length of \bt_p{value} is
1254 incremented.
1255
1256 @sa bt_value_array_append_element() &mdash;
1257 Appends an existing value to an array value.
1258 */
1259 extern bt_value_array_append_element_status
1260 bt_value_array_append_string_element(bt_value *value, const char *raw_value) __BT_NOEXCEPT;
1261
1262 /*!
1263 @brief
1264 Creates an empty array value and appends it to the array
1265 value \bt_p{value}.
1266
1267 On success, if \bt_p{element_value} is not \c NULL, this function sets
1268 \bt_p{*element_value} to a \em borrowed reference of the created empty
1269 array value.
1270
1271 @param[in] value
1272 Array value to which to append the created empty array value.
1273 @param[out] element_value
1274 <strong>On success, if not \c NULL</strong>, \bt_p{*element_value}
1275 is a \em borrowed reference of the created empty array value.
1276
1277 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1278 Success.
1279 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1280 Out of memory.
1281
1282 @bt_pre_not_null{value}
1283 @bt_pre_is_array_val{value}
1284 @bt_pre_hot{value}
1285
1286 @post
1287 <strong>On success</strong>, the length of \bt_p{value} is
1288 incremented.
1289
1290 @sa bt_value_array_append_element() &mdash;
1291 Appends an existing value to an array value.
1292 */
1293 extern bt_value_array_append_element_status
1294 bt_value_array_append_empty_array_element(bt_value *value,
1295 bt_value **element_value) __BT_NOEXCEPT;
1296
1297 /*!
1298 @brief
1299 Creates an empty map value and appends it to the array
1300 value \bt_p{value}.
1301
1302 On success, if \bt_p{element_value} is not \c NULL, this function sets
1303 \bt_p{*element_value} to a \em borrowed reference of the created empty
1304 map value.
1305
1306 @param[in] value
1307 Array value to which to append the created empty array value.
1308 @param[out] element_value
1309 <strong>On success, if not \c NULL</strong>, \bt_p{*element_value}
1310 is a \em borrowed reference of the created empty map value.
1311
1312 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
1313 Success.
1314 @retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
1315 Out of memory.
1316
1317 @bt_pre_not_null{value}
1318 @bt_pre_is_array_val{value}
1319 @bt_pre_hot{value}
1320
1321 @post
1322 <strong>On success</strong>, the length of \bt_p{value} is
1323 incremented.
1324
1325 @sa bt_value_array_append_element() &mdash;
1326 Appends an existing value to an array value.
1327 */
1328 extern bt_value_array_append_element_status
1329 bt_value_array_append_empty_map_element(bt_value *value,
1330 bt_value **element_value) __BT_NOEXCEPT;
1331
1332 /*!
1333 @brief
1334 Status codes for bt_value_array_set_element_by_index().
1335 */
1336 typedef enum bt_value_array_set_element_by_index_status {
1337 /*!
1338 @brief
1339 Success.
1340 */
1341 BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_OK = __BT_FUNC_STATUS_OK,
1342
1343 /*!
1344 @brief
1345 Out of memory.
1346 */
1347 BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
1348 } bt_value_array_set_element_by_index_status;
1349
1350 /*!
1351 @brief
1352 Sets the element of the array value \bt_p{value} at index
1353 \bt_p{index} to the value \bt_p{element_value}.
1354
1355 On success, this function replaces the existing element of \bt_p{value}
1356 at index \bt_p{index}.
1357
1358 @param[in] value
1359 Array value of which to set the element at index \bt_p{index}.
1360 @param[in] index
1361 Index of the element to set in \bt_p{value}.
1362 @param[in] element_value
1363 Value to set as the element of \bt_p{value} at index \bt_p{index}.
1364
1365 @retval #BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_OK
1366 Success.
1367 @retval #BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_MEMORY_ERROR
1368 Out of memory.
1369
1370 @bt_pre_not_null{value}
1371 @bt_pre_is_array_val{value}
1372 @bt_pre_hot{value}
1373 @pre
1374 \bt_p{index} is less than the length of \bt_p{value} (as returned by
1375 bt_value_array_get_length()).
1376 @bt_pre_not_null{element_value}
1377 @pre
1378 \bt_p{element_value} does not contain \bt_p{value}, recursively.
1379
1380 @post
1381 <strong>On success</strong>, the length of \bt_p{value} is
1382 incremented.
1383
1384 @sa bt_value_array_append_element() &mdash;
1385 Appends a value to an array value.
1386 */
1387 extern bt_value_array_set_element_by_index_status
1388 bt_value_array_set_element_by_index(bt_value *value, uint64_t index,
1389 bt_value *element_value) __BT_NOEXCEPT;
1390
1391 /*!
1392 @brief
1393 Borrows the element at index \bt_p{index} from the array value
1394 \bt_p{value}.
1395
1396 @param[in] value
1397 Array value from which to borrow the element at index \bt_p{index}.
1398 @param[in] index
1399 Index of the element to borrow from \bt_p{value}.
1400
1401 @returns
1402 @parblock
1403 \em Borrowed reference of the element of \bt_p{value} at index
1404 \bt_p{index}.
1405
1406 The returned pointer remains valid until \bt_p{value} is modified.
1407 @endparblock
1408
1409 @bt_pre_not_null{value}
1410 @bt_pre_is_array_val{value}
1411 @pre
1412 \bt_p{index} is less than the length of \bt_p{value} (as returned by
1413 bt_value_array_get_length()).
1414
1415 @sa bt_value_array_borrow_element_by_index_const() &mdash;
1416 \c const version of this function.
1417 */
1418 extern bt_value *bt_value_array_borrow_element_by_index(bt_value *value,
1419 uint64_t index) __BT_NOEXCEPT;
1420
1421 /*!
1422 @brief
1423 Borrows the element at index \bt_p{index} from the array value
1424 \bt_p{value} (\c const version).
1425
1426 See bt_value_array_borrow_element_by_index().
1427 */
1428 extern const bt_value *bt_value_array_borrow_element_by_index_const(
1429 const bt_value *value, uint64_t index) __BT_NOEXCEPT;
1430
1431 /*!
1432 @brief
1433 Returns the length of the array value \bt_p{value}.
1434
1435 @param[in] value
1436 Array value of which to get the length.
1437
1438 @returns
1439 Length (number of contained elements) of \bt_p{value}.
1440
1441 @bt_pre_not_null{value}
1442 @bt_pre_is_array_val{value}
1443
1444 @sa bt_value_array_is_empty() &mdash;
1445 Returns whether or not an array value is empty.
1446 */
1447 extern uint64_t bt_value_array_get_length(const bt_value *value) __BT_NOEXCEPT;
1448
1449 /*!
1450 @brief
1451 Returns whether or not the array value \bt_p{value} is empty.
1452
1453 @param[in] value
1454 Array value to check.
1455
1456 @returns
1457 #BT_TRUE if \bt_p{value} is empty (has the length&nbsp;0).
1458
1459 @bt_pre_not_null{value}
1460 @bt_pre_is_array_val{value}
1461
1462 @sa bt_value_array_get_length() &mdash;
1463 Returns the length of an array value.
1464 */
1465 static inline
1466 bt_bool bt_value_array_is_empty(const bt_value *value) __BT_NOEXCEPT
1467 {
1468 return bt_value_array_get_length(value) == 0;
1469 }
1470
1471 /*! @} */
1472
1473 /*!
1474 @name Map value
1475 @{
1476 */
1477
1478 /*!
1479 @brief
1480 Creates and returns an empty map value.
1481
1482 The returned value has the type #BT_VALUE_TYPE_MAP.
1483
1484 @returns
1485 New map value reference, or \c NULL on memory error.
1486 */
1487 extern bt_value *bt_value_map_create(void) __BT_NOEXCEPT;
1488
1489 /*!
1490 @brief
1491 Status codes for the <code>bt_value_map_insert_*()</code> functions.
1492 */
1493 typedef enum bt_value_map_insert_entry_status {
1494 /*!
1495 @brief
1496 Success.
1497 */
1498 BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK = __BT_FUNC_STATUS_OK,
1499
1500 /*!
1501 @brief
1502 Out of memory.
1503 */
1504 BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
1505 } bt_value_map_insert_entry_status;
1506
1507 /*!
1508 @brief
1509 Inserts or replaces an entry with the key \bt_p{key} and the value
1510 \bt_p{entry_value} in the map value \bt_p{value}.
1511
1512 To insert an entry having a null value, pass #bt_value_null as
1513 \bt_p{entry_value}.
1514
1515 On success, if \bt_p{value} already contains an entry with key
1516 \bt_p{key}, this function replaces the existing entry's value with
1517 \bt_p{entry_value}.
1518
1519 @param[in] value
1520 Map value in which to insert or replace an entry with key \bt_p{key}
1521 and value \bt_p{entry_value}.
1522 @param[in] key
1523 Key of the entry to insert or replace in \bt_p{value} (copied).
1524 @param[in] entry_value
1525 Value of the entry to insert or replace in \bt_p{value}.
1526
1527 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1528 Success.
1529 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1530 Out of memory.
1531
1532 @bt_pre_not_null{value}
1533 @bt_pre_is_map_val{value}
1534 @bt_pre_hot{value}
1535 @bt_pre_not_null{key}
1536 @bt_pre_not_null{entry_value}
1537 @pre
1538 \bt_p{entry_value} does not contain \bt_p{value}, recursively.
1539
1540 @sa bt_value_map_insert_bool_entry() &mdash;
1541 Creates a boolean value and uses it to insert an entry in a map
1542 value.
1543 @sa bt_value_map_insert_unsigned_integer_entry() &mdash;
1544 Creates an unsigned integer value and uses it to insert an entry in
1545 a map value.
1546 @sa bt_value_map_insert_signed_integer_entry() &mdash;
1547 Creates a signed value and uses it to insert an entry in a map
1548 value.
1549 @sa bt_value_map_insert_real_entry() &mdash;
1550 Creates a real value and uses it to insert an entry in a map value.
1551 @sa bt_value_map_insert_string_entry() &mdash;
1552 Creates a string value and uses it to insert an entry in a map
1553 value.
1554 @sa bt_value_map_insert_empty_array_entry() &mdash;
1555 Creates an empty array value and uses it to insert an entry in a map
1556 value.
1557 @sa bt_value_map_insert_empty_map_entry() &mdash;
1558 Creates a map value and uses it to insert an entry in a map value.
1559 */
1560 extern bt_value_map_insert_entry_status bt_value_map_insert_entry(
1561 bt_value *value, const char *key,
1562 bt_value *entry_value) __BT_NOEXCEPT;
1563
1564 /*!
1565 @brief
1566 Creates a boolean value initialized to \bt_p{raw_value} and
1567 inserts or replaces an entry with the key \bt_p{key} and this value
1568 in the map value \bt_p{value}.
1569
1570 On success, if \bt_p{value} already contains an entry with key
1571 \bt_p{key}, this function replaces the existing entry's value with the
1572 created boolean value.
1573
1574 @param[in] value
1575 Map value in which to insert or replace an entry with key \bt_p{key}
1576 and the created boolean value.
1577 @param[in] key
1578 Key of the entry to insert or replace in \bt_p{value} (copied).
1579 @param[in] raw_value
1580 Initial raw value of the boolean value to create.
1581
1582 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1583 Success.
1584 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1585 Out of memory.
1586
1587 @bt_pre_not_null{value}
1588 @bt_pre_is_map_val{value}
1589 @bt_pre_hot{value}
1590 @bt_pre_not_null{key}
1591
1592 @sa bt_value_map_insert_entry() &mdash;
1593 Inserts an entry with an existing value in a map value.
1594 */
1595 extern bt_value_map_insert_entry_status bt_value_map_insert_bool_entry(
1596 bt_value *value, const char *key, bt_bool raw_value)
1597 __BT_NOEXCEPT;
1598
1599 /*!
1600 @brief
1601 Creates an unsigned integer value initialized to \bt_p{raw_value}
1602 and inserts or replaces an entry with the key \bt_p{key} and this
1603 value in the map value \bt_p{value}.
1604
1605 On success, if \bt_p{value} already contains an entry with key
1606 \bt_p{key}, this function replaces the existing entry's value with the
1607 created unsigned integer value.
1608
1609 @param[in] value
1610 Map value in which to insert or replace an entry with key \bt_p{key}
1611 and the created unsigned integer value.
1612 @param[in] key
1613 Key of the entry to insert or replace in \bt_p{value} (copied).
1614 @param[in] raw_value
1615 Initial raw value of the unsigned integer value to create.
1616
1617 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1618 Success.
1619 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1620 Out of memory.
1621
1622 @bt_pre_not_null{value}
1623 @bt_pre_is_map_val{value}
1624 @bt_pre_hot{value}
1625 @bt_pre_not_null{key}
1626
1627 @sa bt_value_map_insert_entry() &mdash;
1628 Inserts an entry with an existing value in a map value.
1629 */
1630 extern bt_value_map_insert_entry_status
1631 bt_value_map_insert_unsigned_integer_entry(bt_value *value, const char *key,
1632 uint64_t raw_value) __BT_NOEXCEPT;
1633
1634 /*!
1635 @brief
1636 Creates a signed integer value initialized to \bt_p{raw_value} and
1637 inserts or replaces an entry with the key \bt_p{key} and this value
1638 in the map value \bt_p{value}.
1639
1640 On success, if \bt_p{value} already contains an entry with key
1641 \bt_p{key}, this function replaces the existing entry's value with the
1642 created signed integer value.
1643
1644 @param[in] value
1645 Map value in which to insert or replace an entry with key \bt_p{key}
1646 and the created signed integer value.
1647 @param[in] key
1648 Key of the entry to insert or replace in \bt_p{value} (copied).
1649 @param[in] raw_value
1650 Initial raw value of the signed integer value to create.
1651
1652 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1653 Success.
1654 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1655 Out of memory.
1656
1657 @bt_pre_not_null{value}
1658 @bt_pre_is_map_val{value}
1659 @bt_pre_hot{value}
1660 @bt_pre_not_null{key}
1661
1662 @sa bt_value_map_insert_entry() &mdash;
1663 Inserts an entry with an existing value in a map value.
1664 */
1665 extern bt_value_map_insert_entry_status
1666 bt_value_map_insert_signed_integer_entry(bt_value *value, const char *key,
1667 int64_t raw_value) __BT_NOEXCEPT;
1668
1669 /*!
1670 @brief
1671 Creates a real value initialized to \bt_p{raw_value} and inserts or
1672 replaces an entry with the key \bt_p{key} and this value in the map
1673 value \bt_p{value}.
1674
1675 On success, if \bt_p{value} already contains an entry with key
1676 \bt_p{key}, this function replaces the existing entry's value with the
1677 created real value.
1678
1679 @param[in] value
1680 Map value in which to insert or replace an entry with key \bt_p{key}
1681 and the created real value.
1682 @param[in] key
1683 Key of the entry to insert or replace in \bt_p{value} (copied).
1684 @param[in] raw_value
1685 Initial raw value of the real value to create.
1686
1687 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1688 Success.
1689 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1690 Out of memory.
1691
1692 @bt_pre_not_null{value}
1693 @bt_pre_is_map_val{value}
1694 @bt_pre_hot{value}
1695 @bt_pre_not_null{key}
1696
1697 @sa bt_value_map_insert_entry() &mdash;
1698 Inserts an entry with an existing value in a map value.
1699 */
1700 extern bt_value_map_insert_entry_status bt_value_map_insert_real_entry(
1701 bt_value *value, const char *key, double raw_value)
1702 __BT_NOEXCEPT;
1703
1704 /*!
1705 @brief
1706 Creates a string value initialized to a copy of \bt_p{raw_value} and
1707 inserts or replaces an entry with the key \bt_p{key} and this value
1708 in the map value \bt_p{value}.
1709
1710 On success, if \bt_p{value} already contains an entry with key
1711 \bt_p{key}, this function replaces the existing entry's value with the
1712 created string value.
1713
1714 @param[in] value
1715 Map value in which to insert or replace an entry with key \bt_p{key}
1716 and the created string value.
1717 @param[in] key
1718 Key of the entry to insert or replace in \bt_p{value} (copied).
1719 @param[in] raw_value
1720 Initial raw value of the string value to create (copied).
1721
1722 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1723 Success.
1724 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1725 Out of memory.
1726
1727 @bt_pre_not_null{value}
1728 @bt_pre_is_map_val{value}
1729 @bt_pre_hot{value}
1730 @bt_pre_not_null{key}
1731
1732 @sa bt_value_map_insert_entry() &mdash;
1733 Inserts an entry with an existing value in a map value.
1734 */
1735 extern bt_value_map_insert_entry_status
1736 bt_value_map_insert_string_entry(bt_value *value, const char *key,
1737 const char *raw_value) __BT_NOEXCEPT;
1738
1739 /*!
1740 @brief
1741 Creates an empty array value and inserts or replaces an entry with
1742 the key \bt_p{key} and this value in the map value \bt_p{value}.
1743
1744 On success, if \bt_p{entry_value} is not \c NULL, this function sets
1745 \bt_p{*entry_value} to a \em borrowed reference of the created empty
1746 array value.
1747
1748 On success, if \bt_p{value} already contains an entry with key
1749 \bt_p{key}, this function replaces the existing entry's value with the
1750 created empty array value.
1751
1752 @param[in] value
1753 Map value in which to insert or replace an entry with key \bt_p{key}
1754 and the created empty array value.
1755 @param[in] key
1756 Key of the entry to insert or replace in \bt_p{value} (copied).
1757 @param[out] entry_value
1758 <strong>On success, if not \c NULL</strong>, \bt_p{*entry_value} is
1759 a \em borrowed reference of the created empty array value.
1760
1761 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1762 Success.
1763 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1764 Out of memory.
1765
1766 @bt_pre_not_null{value}
1767 @bt_pre_is_map_val{value}
1768 @bt_pre_hot{value}
1769 @bt_pre_not_null{key}
1770
1771 @sa bt_value_map_insert_entry() &mdash;
1772 Inserts an entry with an existing value in a map value.
1773 */
1774 extern bt_value_map_insert_entry_status
1775 bt_value_map_insert_empty_array_entry(bt_value *value, const char *key,
1776 bt_value **entry_value) __BT_NOEXCEPT;
1777
1778 /*!
1779 @brief
1780 Creates an empty map value and inserts or replaces an entry with
1781 the key \bt_p{key} and this value in the map value \bt_p{value}.
1782
1783 On success, if \bt_p{entry_value} is not \c NULL, this function sets
1784 \bt_p{*entry_value} to a \em borrowed reference of the created empty map
1785 value.
1786
1787 On success, if \bt_p{value} already contains an entry with key
1788 \bt_p{key}, this function replaces the existing entry's value with the
1789 created empty map value.
1790
1791 @param[in] value
1792 Map value in which to insert or replace an entry with key \bt_p{key}
1793 and the created empty map value.
1794 @param[in] key
1795 Key of the entry to insert or replace in \bt_p{value} (copied).
1796 @param[out] entry_value
1797 <strong>On success, if not \c NULL</strong>, \bt_p{*entry_value} is
1798 a \em borrowed reference of the created empty map value.
1799
1800 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1801 Success.
1802 @retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1803 Out of memory.
1804
1805 @bt_pre_not_null{value}
1806 @bt_pre_is_map_val{value}
1807 @bt_pre_hot{value}
1808 @bt_pre_not_null{key}
1809
1810 @sa bt_value_map_insert_entry() &mdash;
1811 Inserts an entry with an existing value in a map value.
1812 */
1813 extern bt_value_map_insert_entry_status
1814 bt_value_map_insert_empty_map_entry(bt_value *value, const char *key,
1815 bt_value **entry_value) __BT_NOEXCEPT;
1816
1817 /*!
1818 @brief
1819 Borrows the value of the entry with the key \bt_p{key} in the map
1820 value \bt_p{value}.
1821
1822 If no entry with key \bt_p{key} exists in \bt_p{value}, this function
1823 returns \c NULL.
1824
1825 @param[in] value
1826 Map value from which to borrow the value of the entry with the
1827 key \bt_p{key}.
1828 @param[in] key
1829 Key of the entry from which to borrow the value in \bt_p{value}.
1830
1831 @returns
1832 @parblock
1833 \em Borrowed reference of the value of the entry with key \bt_p{key}
1834 in \bt_p{value}, or \c NULL if none.
1835
1836 The returned pointer remains valid until \bt_p{value} is modified.
1837 @endparblock
1838
1839 @bt_pre_not_null{value}
1840 @bt_pre_is_map_val{value}
1841 @bt_pre_not_null{key}
1842
1843 @sa bt_value_map_borrow_entry_value_const() &mdash;
1844 \c const version of this function.
1845 @sa bt_value_map_has_entry() &mdash;
1846 Returns whether or not a map value has an entry with a given key.
1847 */
1848 extern bt_value *bt_value_map_borrow_entry_value(
1849 bt_value *value, const char *key) __BT_NOEXCEPT;
1850
1851 /*!
1852 @brief
1853 Borrows the value of the entry with the key \bt_p{key} in the map
1854 value \bt_p{value} (\c const version).
1855
1856 See bt_value_map_borrow_entry_value().
1857 */
1858 extern const bt_value *bt_value_map_borrow_entry_value_const(
1859 const bt_value *value, const char *key) __BT_NOEXCEPT;
1860
1861 /*!
1862 @brief
1863 Status codes for #bt_value_map_foreach_entry_func.
1864 */
1865 typedef enum bt_value_map_foreach_entry_func_status {
1866 /*!
1867 @brief
1868 Success.
1869 */
1870 BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_OK = __BT_FUNC_STATUS_OK,
1871
1872 /*!
1873 @brief
1874 Interrupt the iteration process.
1875 */
1876 BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_INTERRUPT = __BT_FUNC_STATUS_INTERRUPTED,
1877
1878 /*!
1879 @brief
1880 Out of memory.
1881 */
1882 BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
1883
1884 /*!
1885 @brief
1886 User error.
1887 */
1888 BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
1889 } bt_value_map_foreach_entry_func_status;
1890
1891 /*!
1892 @brief
1893 User function for bt_value_map_foreach_entry().
1894
1895 This is the type of the user function that bt_value_map_foreach_entry()
1896 calls for each entry of the map value.
1897
1898 @param[in] key
1899 Key of the map value entry.
1900 @param[in] value
1901 Value of the map value entry.
1902 @param[in] user_data
1903 User data, as passed as the \bt_p{user_data} parameter of
1904 bt_value_map_foreach_entry().
1905
1906 @retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_OK
1907 Success.
1908 @retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_INTERRUPT
1909 Interrupt the iteration process.
1910 @retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_MEMORY_ERROR
1911 Out of memory.
1912 @retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_ERROR
1913 User error.
1914
1915 @bt_pre_not_null{key}
1916 @bt_pre_not_null{value}
1917
1918 @sa bt_value_map_foreach_entry() &mdash;
1919 Iterates the entries of a map value.
1920 */
1921 typedef bt_value_map_foreach_entry_func_status
1922 (* bt_value_map_foreach_entry_func)(const char *key,
1923 bt_value *value, void *user_data);
1924
1925 /*!
1926 @brief
1927 Status codes for bt_value_map_foreach_entry().
1928 */
1929 typedef enum bt_value_map_foreach_entry_status {
1930 /*!
1931 @brief
1932 Success.
1933 */
1934 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_OK = __BT_FUNC_STATUS_OK,
1935
1936 /*!
1937 @brief
1938 User function interrupted the iteration process.
1939 */
1940 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_INTERRUPTED = __BT_FUNC_STATUS_INTERRUPTED,
1941
1942 /*!
1943 @brief
1944 User function error.
1945 */
1946 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_USER_ERROR = __BT_FUNC_STATUS_USER_ERROR,
1947
1948 /*!
1949 @brief
1950 Out of memory.
1951 */
1952 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
1953
1954 /*!
1955 @brief
1956 Other error.
1957 */
1958 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
1959 } bt_value_map_foreach_entry_status;
1960
1961 /*!
1962 @brief
1963 Iterates the entries of the map value \bt_p{value}, calling
1964 \bt_p{user_func} for each entry.
1965
1966 This function iterates the entries of \bt_p{value} in no particular
1967 order.
1968
1969 @attention
1970 You must \em not modify \bt_p{value} during the iteration process.
1971
1972 \bt_p{user_func} receives \bt_p{user_data} as its last parameter.
1973
1974 The iteration process stops when one of:
1975
1976 - \bt_p{user_func} was called for each entry.
1977 - \bt_p{user_func} does not return
1978 #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_OK.
1979
1980 @param[in] value
1981 Map value of which to iterate the entries.
1982 @param[in] user_func
1983 User function to call for each entry of \bt_p{value}.
1984 @param[in] user_data
1985 User data to pass as the \bt_p{user_data} parameter of each call to
1986 \bt_p{user_func}.
1987
1988 @retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_OK
1989 Success.
1990 @retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_INTERRUPTED
1991 \bt_p{user_func} returned
1992 #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_INTERRUPT to interrupt the
1993 iteration process.
1994 @retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_USER_ERROR
1995 \bt_p{user_func} returned
1996 #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_ERROR.
1997 @retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_MEMORY_ERROR
1998 Out of memory.
1999 @retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_ERROR
2000 Other error caused the <code>bt_value_map_foreach_entry()</code>
2001 function itself.
2002
2003 @bt_pre_not_null{value}
2004 @bt_pre_is_map_val{value}
2005 @bt_pre_not_null{user_func}
2006
2007 @sa bt_value_map_foreach_entry_const() &mdash;
2008 \c const version of this function.
2009 @sa bt_value_map_borrow_entry_value() &mdash;
2010 Borrows the value of a specific map value entry.
2011 */
2012 extern bt_value_map_foreach_entry_status bt_value_map_foreach_entry(
2013 bt_value *value, bt_value_map_foreach_entry_func user_func,
2014 void *user_data) __BT_NOEXCEPT;
2015
2016 /*!
2017 @brief
2018 Status codes for #bt_value_map_foreach_entry_const_func.
2019 */
2020 typedef enum bt_value_map_foreach_entry_const_func_status {
2021 /*!
2022 @brief
2023 Success.
2024 */
2025 BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_OK = __BT_FUNC_STATUS_OK,
2026
2027 /*!
2028 @brief
2029 Interrupt the iteration process.
2030 */
2031 BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_INTERRUPT = __BT_FUNC_STATUS_INTERRUPTED,
2032
2033 /*!
2034 @brief
2035 Out of memory.
2036 */
2037 BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
2038
2039 /*!
2040 @brief
2041 User error.
2042 */
2043 BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
2044 } bt_value_map_foreach_entry_const_func_status;
2045
2046 /*!
2047 @brief
2048 User function for bt_value_map_foreach_entry_const_func().
2049
2050 This is the type of the user function that
2051 bt_value_map_foreach_entry_const_func() calls for each entry of the map
2052 value.
2053
2054 @param[in] key
2055 Key of the map value entry.
2056 @param[in] value
2057 Value of the map value entry.
2058 @param[in] user_data
2059 User data.
2060
2061 @retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_OK
2062 Success.
2063 @retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_INTERRUPT
2064 Interrupt the iteration process.
2065 @retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_MEMORY_ERROR
2066 Out of memory.
2067 @retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_ERROR
2068 User error.
2069
2070 @bt_pre_not_null{key}
2071 @bt_pre_not_null{value}
2072
2073 @sa bt_value_map_foreach_entry_const() &mdash;
2074 Iterates the entries of a \c const map value.
2075 */
2076 typedef bt_value_map_foreach_entry_const_func_status
2077 (* bt_value_map_foreach_entry_const_func)(const char *key,
2078 const bt_value *value, void *user_data);
2079
2080 /*!
2081 @brief
2082 Status codes for bt_value_map_foreach_entry_const().
2083 */
2084 typedef enum bt_value_map_foreach_entry_const_status {
2085 /*!
2086 @brief
2087 Success.
2088 */
2089 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_OK = __BT_FUNC_STATUS_OK,
2090
2091 /*!
2092 @brief
2093 User function interrupted the iteration process.
2094 */
2095 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_INTERRUPTED = __BT_FUNC_STATUS_INTERRUPTED,
2096
2097 /*!
2098 @brief
2099 User function error.
2100 */
2101 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_USER_ERROR = __BT_FUNC_STATUS_USER_ERROR,
2102
2103 /*!
2104 @brief
2105 Out of memory.
2106 */
2107 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
2108
2109 /*!
2110 @brief
2111 Other error.
2112 */
2113 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
2114 } bt_value_map_foreach_entry_const_status;
2115
2116 /*!
2117 @brief
2118 Iterates the entries of the map value \bt_p{value}, calling
2119 \bt_p{user_func} for each entry (\c const version).
2120
2121 See bt_value_map_foreach_entry().
2122
2123 @sa bt_value_map_borrow_entry_value_const() &mdash;
2124 Borrows the value of a specific map value entry.
2125 */
2126 extern bt_value_map_foreach_entry_const_status bt_value_map_foreach_entry_const(
2127 const bt_value *value,
2128 bt_value_map_foreach_entry_const_func user_func,
2129 void *user_data) __BT_NOEXCEPT;
2130
2131 /*!
2132 @brief
2133 Returns the size of the map value \bt_p{value}.
2134
2135 @param[in] value
2136 Map value of which to get the size.
2137
2138 @returns
2139 Size (number of contained entries) of \bt_p{value}.
2140
2141 @bt_pre_not_null{value}
2142 @bt_pre_is_map_val{value}
2143
2144 @sa bt_value_map_is_empty() &mdash;
2145 Returns whether or not a map value is empty.
2146 */
2147 extern uint64_t bt_value_map_get_size(const bt_value *value) __BT_NOEXCEPT;
2148
2149 /*!
2150 @brief
2151 Returns whether or not the map value \bt_p{value} is empty.
2152
2153 @param[in] value
2154 Map value to check.
2155
2156 @returns
2157 #BT_TRUE if \bt_p{value} is empty (has the size&nbsp;0).
2158
2159 @bt_pre_not_null{value}
2160 @bt_pre_is_map_val{value}
2161
2162 @sa bt_value_map_get_size() &mdash;
2163 Returns the size of a map value.
2164 */
2165 static inline
2166 bt_bool bt_value_map_is_empty(const bt_value *value) __BT_NOEXCEPT
2167 {
2168 return bt_value_map_get_size(value) == 0;
2169 }
2170
2171 /*!
2172 @brief
2173 Returns whether or not the map value \bt_p{value} has an entry with
2174 the key \bt_p{key}.
2175
2176 @param[in] value
2177 Map value to check.
2178 @param[in] key
2179 Key to check.
2180
2181 @returns
2182 #BT_TRUE if \bt_p{value} has an entry with the key \bt_p{key}.
2183
2184 @bt_pre_not_null{value}
2185 @bt_pre_is_map_val{value}
2186 @bt_pre_not_null{key}
2187
2188 @sa bt_value_map_borrow_entry_value_const() &mdash;
2189 Borrows the value of a specific map value entry.
2190 */
2191 extern bt_bool bt_value_map_has_entry(const bt_value *value,
2192 const char *key) __BT_NOEXCEPT;
2193
2194 /*!
2195 @brief
2196 Status codes for bt_value_map_extend().
2197 */
2198 typedef enum bt_value_map_extend_status {
2199 /*!
2200 @brief
2201 Success.
2202 */
2203 BT_VALUE_MAP_EXTEND_STATUS_OK = __BT_FUNC_STATUS_OK,
2204
2205 /*!
2206 @brief
2207 Out of memory.
2208 */
2209 BT_VALUE_MAP_EXTEND_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
2210 } bt_value_map_extend_status;
2211
2212 /*!
2213 @brief
2214 Extends the map value \bt_p{value} with the map value
2215 \bt_p{extension_value}.
2216
2217 For each entry in \bt_p{extension_value}, this function calls
2218 bt_value_map_insert_entry() to insert or replace it in the map value
2219 \bt_p{value}.
2220
2221 For example, with:
2222
2223 <dl>
2224 <dt>
2225 \bt_p{value}
2226 </dt>
2227 <dd>
2228 @code{.json}
2229 {
2230 "man": "giant",
2231 "strange": 23
2232 }
2233 @endcode
2234 </dd>
2235
2236 <dt>
2237 \bt_p{extension_value}
2238 </dt>
2239 <dd>
2240 @code{.json}
2241 {
2242 "balance": -17
2243 "strange": false
2244 }
2245 @endcode
2246 </dd>
2247 </dl>
2248
2249 The map value \bt_p{value} becomes:
2250
2251 @code{.json}
2252 {
2253 "man": "giant",
2254 "strange": false,
2255 "balance": -17
2256 }
2257 @endcode
2258
2259 @param[in] value
2260 Map value to extend.
2261 @param[in] extension_value
2262 Extension map value.
2263
2264 @retval #BT_VALUE_MAP_EXTEND_STATUS_OK
2265 Success.
2266 @retval #BT_VALUE_MAP_EXTEND_STATUS_MEMORY_ERROR
2267 Out of memory.
2268
2269 @bt_pre_not_null{value}
2270 @bt_pre_is_map_val{value}
2271 @bt_pre_not_null{extension_value}
2272 @bt_pre_is_map_val{extension_value}
2273
2274 @sa bt_value_copy() &mdash;
2275 Deep-copies a value.
2276 */
2277 extern bt_value_map_extend_status bt_value_map_extend(
2278 bt_value *value, const bt_value *extension_value) __BT_NOEXCEPT;
2279
2280 /*! @} */
2281
2282 /*!
2283 @name General
2284 @{
2285 */
2286
2287 /*!
2288 @brief
2289 Status codes for bt_value_copy().
2290 */
2291 typedef enum bt_value_copy_status {
2292 /*!
2293 @brief
2294 Success.
2295 */
2296 BT_VALUE_COPY_STATUS_OK = __BT_FUNC_STATUS_OK,
2297
2298 /*!
2299 @brief
2300 Out of memory.
2301 */
2302 BT_VALUE_COPY_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
2303 } bt_value_copy_status;
2304
2305 /*!
2306 @brief
2307 Deep-copies a value object.
2308
2309 This function deep-copies \bt_p{value} and sets \bt_p{*copy} to the
2310 result.
2311
2312 Because \bt_p{*copy} is a deep copy, it does not contain, recursively,
2313 any reference that \bt_p{value} contains, but the raw values are
2314 identical.
2315
2316 @param[in] value
2317 Value to deep-copy.
2318 @param[in] copy_value
2319 <strong>On success</strong>, \bt_p{*copy_value} is a deep copy of
2320 \bt_p{value}.
2321
2322 @retval #BT_VALUE_COPY_STATUS_OK
2323 Success.
2324 @retval #BT_VALUE_COPY_STATUS_MEMORY_ERROR
2325 Out of memory.
2326
2327 @bt_pre_not_null{value}
2328 @bt_pre_not_null{copy_value}
2329 */
2330 extern bt_value_copy_status bt_value_copy(const bt_value *value,
2331 bt_value **copy_value) __BT_NOEXCEPT;
2332
2333 /*!
2334 @brief
2335 Returns whether or not the value \bt_p{a_value} is equal,
2336 recursively, to \bt_p{b_value}.
2337
2338 @note
2339 If you want to know whether or not a value is a null value, you can
2340 also directly compare its pointer to the #bt_value_null variable.
2341
2342 @param[in] a_value
2343 Value A.
2344 @param[in] b_value
2345 Value B.
2346
2347 @returns
2348 #BT_TRUE if \bt_p{a_value} is equal, recursively, to \bt_p{b_value}.
2349
2350 @bt_pre_not_null{a_value}
2351 @bt_pre_not_null{b_value}
2352 */
2353 extern bt_bool bt_value_is_equal(const bt_value *a_value,
2354 const bt_value *b_value) __BT_NOEXCEPT;
2355
2356 /*! @} */
2357
2358 /*!
2359 @name Reference count
2360 @{
2361 */
2362
2363 /*!
2364 @brief
2365 Increments the \ref api-fund-shared-object "reference count" of
2366 the value \bt_p{value}.
2367
2368 @param[in] value
2369 @parblock
2370 Value of which to increment the reference count.
2371
2372 Can be \c NULL.
2373 @endparblock
2374
2375 @sa bt_value_put_ref() &mdash;
2376 Decrements the reference count of a value.
2377 */
2378 extern void bt_value_get_ref(const bt_value *value) __BT_NOEXCEPT;
2379
2380 /*!
2381 @brief
2382 Decrements the \ref api-fund-shared-object "reference count" of
2383 the value \bt_p{value}.
2384
2385 @param[in] value
2386 @parblock
2387 Value of which to decrement the reference count.
2388
2389 Can be \c NULL.
2390 @endparblock
2391
2392 @sa bt_value_get_ref() &mdash;
2393 Increments the reference count of a value.
2394 */
2395 extern void bt_value_put_ref(const bt_value *value) __BT_NOEXCEPT;
2396
2397 /*!
2398 @brief
2399 Decrements the reference count of the value \bt_p{_value}, and then
2400 sets \bt_p{_value} to \c NULL.
2401
2402 @param _value
2403 @parblock
2404 Value of which to decrement the reference count.
2405
2406 Can contain \c NULL.
2407 @endparblock
2408
2409 @bt_pre_assign_expr{_value}
2410 */
2411 #define BT_VALUE_PUT_REF_AND_RESET(_value) \
2412 do { \
2413 bt_value_put_ref(_value); \
2414 (_value) = NULL; \
2415 } while (0)
2416
2417 /*!
2418 @brief
2419 Decrements the reference count of the value \bt_p{_dst}, sets
2420 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
2421
2422 This macro effectively moves a value reference from the expression
2423 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
2424 \bt_p{_dst} reference.
2425
2426 @param _dst
2427 @parblock
2428 Destination expression.
2429
2430 Can contain \c NULL.
2431 @endparblock
2432 @param _src
2433 @parblock
2434 Source expression.
2435
2436 Can contain \c NULL.
2437 @endparblock
2438
2439 @bt_pre_assign_expr{_dst}
2440 @bt_pre_assign_expr{_src}
2441 */
2442 #define BT_VALUE_MOVE_REF(_dst, _src) \
2443 do { \
2444 bt_value_put_ref(_dst); \
2445 (_dst) = (_src); \
2446 (_src) = NULL; \
2447 } while (0)
2448
2449 /*! @} */
2450
2451 /*! @} */
2452
2453 #ifdef __cplusplus
2454 }
2455 #endif
2456
2457 #endif /* BABELTRACE2_VALUE_H */
This page took 0.077105 seconds and 5 git commands to generate.