include: add IWYU pragmas in private header files
[babeltrace.git] / include / babeltrace2 / value.h
CommitLineData
dac5c838 1/*
0235b0db 2 * SPDX-License-Identifier: MIT
dac5c838 3 *
0235b0db 4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
dac5c838
PP
5 */
6
0235b0db
MJ
7#ifndef BABELTRACE2_VALUE_H
8#define BABELTRACE2_VALUE_H
9
f38da6ca
SM
10/* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
11
4fa90f32
PP
12#ifndef __BT_IN_BABELTRACE_H
13# error "Please include <babeltrace2/babeltrace.h> instead."
14#endif
15
dac5c838 16#include <stdint.h>
dac5c838 17#include <stddef.h>
9d408fca 18
3fadfbc0 19#include <babeltrace2/types.h>
40f4ba76 20
dac5c838
PP
21#ifdef __cplusplus
22extern "C" {
23#endif
24
43c59509
PP
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
32the fact that integer values are explicitly unsigned or signed because
33of typing limitations,
34\bt_name values are very similar to <a href="https://json.org/">JSON</a>
35values.
36
37The 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,
42bt_event_class_set_user_attributes()) use values.
43
44The 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
64Values are \ref api-fund-shared-object "shared objects": get a new
65reference with bt_value_get_ref() and put an existing reference with
66bt_value_put_ref().
67
68Some library functions \ref api-fund-freezing "freeze" values on
69success. The documentation of those functions indicate this
70postcondition.
71
72All the value types share the same C type, #bt_value.
73
74Get the type enumerator of a value with bt_value_get_type(). Get whether
75or not a value type conceptually \em is a given type with the inline
76bt_value_type_is() function. Get whether or not a value has a specific
77type with one of the <code>bt_value_is_*()</code> inline helpers.
78
79The \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
82values, the null value is a shared object: if you get a new null value
83reference, you must eventually put it.
84
85Create a value with one of the <code>bt_value_*_create()</code> or
86<code>bt_value_*_create_init()</code> functions.
87
88This documentation names the actual data that a scalar value wraps the
89<em>raw value</em>.
90
91Set and get the raw values of scalar values with functions that are
92named <code>bt_value_*_set()</code> and <code>bt_value_*_get()</code>.
93
94Check that two values are recursively equal with bt_value_is_equal().
95
96Deep-copy a value with bt_value_copy().
97
98Extend a map value with bt_value_map_extend().
99
100The following table shows the available functions and types for each
101type 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*/
234typedef 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*/
328extern bt_value_type bt_value_get_type(const bt_value *value);
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
335For example, an unsigned integer value conceptually \em is an integer
336value, so
337
338@code
339bt_value_type_is(BT_VALUE_TYPE_UNSIGNED_INTEGER, BT_VALUE_TYPE_INTEGER)
340@endcode
341
342returns #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*/
371static inline
372bt_bool bt_value_type_is(const bt_value_type type,
373 const bt_value_type other_type)
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*/
403static inline
404bt_bool bt_value_is_null(const bt_value *value)
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*/
427static inline
428bt_bool bt_value_is_bool(const bt_value *value)
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*/
452static inline
453bt_bool bt_value_is_unsigned_integer(const bt_value *value)
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*/
477static inline
478bt_bool bt_value_is_signed_integer(const bt_value *value)
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*/
501static inline
502bt_bool bt_value_is_real(const bt_value *value)
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*/
525static inline
526bt_bool bt_value_is_string(const bt_value *value)
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*/
549static inline
550bt_bool bt_value_is_array(const bt_value *value)
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*/
573static inline
574bt_bool bt_value_is_map(const bt_value *value)
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
590This is the \em only instance of a null value.
591
592Like any type of value, the null value is a shared object: if you get a
593new null value reference with bt_value_get_ref(), you must eventually
594put it with bt_value_put_ref(). The null value singleton's reference
595count must never reach 0: libbabeltrace2 logs a warning message when
596this programming error occurs.
597
598Because all null values point to the same null value singleton, you can
599directly 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*/
211796dc 615extern bt_value *const bt_value_null;
dac5c838 616
43c59509
PP
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
628The 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*/
b19ff26f 636extern bt_value *bt_value_bool_create(void);
dac5c838 637
43c59509
PP
638/*!
639@brief
640 Creates and returns a boolean value initialized to \bt_p{raw_value}.
641
642The 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*/
653extern bt_value *bt_value_bool_create_init(bt_bool raw_value);
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}.
dac5c838 664
43c59509
PP
665@bt_pre_not_null{value}
666@bt_pre_is_bool_val{value}
667@bt_pre_hot{value}
dac5c838 668
43c59509
PP
669@sa bt_value_bool_get() &mdash;
670 Returns the raw value of a boolean value.
671*/
672extern void bt_value_bool_set(bt_value *value, bt_bool raw_value);
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*/
690extern bt_bool bt_value_bool_get(const bt_value *value);
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
703The 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*/
9c08c816 711extern bt_value *bt_value_integer_unsigned_create(void);
dac5c838 712
43c59509
PP
713/*!
714@brief
715 Creates and returns an unsigned integer value initialized to
716 \bt_p{raw_value}.
717
718The 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*/
729extern bt_value *bt_value_integer_unsigned_create_init(uint64_t raw_value);
dac5c838 730
43c59509
PP
731/*!
732@brief
733 Sets the raw value of the unsigned integer value \bt_p{value} to
734 \bt_p{raw_value}.
fdd3a2da 735
43c59509
PP
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*/
749extern void bt_value_integer_unsigned_set(bt_value *value,
750 uint64_t raw_value);
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*/
768extern uint64_t bt_value_integer_unsigned_get(const bt_value *value);
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
781The 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*/
9c08c816 789extern bt_value *bt_value_integer_signed_create(void);
fdd3a2da 790
43c59509
PP
791/*!
792@brief
793 Creates and returns a signed integer value initialized to
794 \bt_p{raw_value}.
795
796The 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.
fdd3a2da 800
43c59509
PP
801@returns
802 New signed integer value reference, or \c NULL on memory error.
de079588 803
43c59509
PP
804@sa bt_value_bool_create() &mdash;
805 Creates a signed integer value initialized to 0.
806*/
807extern bt_value *bt_value_integer_signed_create_init(int64_t raw_value);
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*/
827extern void bt_value_integer_signed_set(bt_value *value, int64_t raw_value);
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*/
845extern int64_t bt_value_integer_signed_get(const bt_value *value);
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
858The 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*/
b19ff26f 866extern bt_value *bt_value_real_create(void);
de079588 867
43c59509
PP
868/*!
869@brief
870 Creates and returns a real value initialized to \bt_p{raw_value}.
871
872The 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*/
883extern bt_value *bt_value_real_create_init(double raw_value);
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*/
902extern void bt_value_real_set(bt_value *value, double raw_value);
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*/
920extern double bt_value_real_get(const bt_value *value);
921
922/*! @} */
923
924/*!
925@name String value
926@{
927*/
dac5c838 928
43c59509
PP
929/*!
930@brief
931 Creates and returns an empty string value.
dac5c838 932
43c59509
PP
933The 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*/
b19ff26f 941extern bt_value *bt_value_string_create(void);
dac5c838 942
43c59509
PP
943/*!
944@brief
945 Creates and returns a string value initialized to a copy of
946 \bt_p{raw_value}.
947
948The 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).
dac5c838 952
43c59509
PP
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*/
961extern bt_value *bt_value_string_create_init(const char *raw_value);
962
963/*!
964@brief
965 Status codes for bt_value_string_set().
966*/
d24d5663 967typedef enum bt_value_string_set_status {
43c59509
PP
968 /*!
969 @brief
970 Success.
971 */
d24d5663 972 BT_VALUE_STRING_SET_STATUS_OK = __BT_FUNC_STATUS_OK,
43c59509
PP
973
974 /*!
975 @brief
976 Out of memory.
977 */
978 BT_VALUE_STRING_SET_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
d24d5663
PP
979} bt_value_string_set_status;
980
43c59509
PP
981/*!
982@brief
983 Sets the raw value of the string value \bt_p{value} to a copy of
984 \bt_p{raw_value}.
de079588 985
43c59509
PP
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).
dac5c838 991
43c59509
PP
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*/
1005extern bt_value_string_set_status bt_value_string_set(bt_value *value,
1006 const char *raw_value);
1007
1008/*!
1009@brief
1010 Returns the raw value of the string value \bt_p{value}.
dac5c838 1011
43c59509
PP
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*/
1028extern const char *bt_value_string_get(const bt_value *value);
1029
1030/*! @} */
1031
1032/*!
1033@name Array value
1034@{
1035*/
1036
1037/*!
1038@brief
1039 Creates and returns an empty array value.
1040
1041The returned value has the type #BT_VALUE_TYPE_ARRAY.
1042
1043@returns
1044 New array value reference, or \c NULL on memory error.
1045*/
1046extern bt_value *bt_value_array_create(void);
1047
1048/*!
1049@brief
1050 Status codes for the <code>bt_value_array_append_*()</code>
1051 functions.
1052*/
d24d5663 1053typedef enum bt_value_array_append_element_status {
43c59509
PP
1054 /*!
1055 @brief
1056 Success.
1057 */
d24d5663 1058 BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK = __BT_FUNC_STATUS_OK,
43c59509
PP
1059
1060 /*!
1061 @brief
1062 Out of memory.
1063 */
1064 BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
d24d5663 1065} bt_value_array_append_element_status;
dac5c838 1066
43c59509
PP
1067/*!
1068@brief
1069 Appends the value \bt_p{element_value} to the array value \bt_p{value}.
1070
1071To 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*/
d24d5663 1109extern bt_value_array_append_element_status bt_value_array_append_element(
43c59509
PP
1110 bt_value *value, bt_value *element_value);
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.
05e21286 1126
43c59509
PP
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*/
d24d5663 1138extern bt_value_array_append_element_status
43c59509
PP
1139bt_value_array_append_bool_element(bt_value *value, bt_bool raw_value);
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.
fdd3a2da 1164
43c59509
PP
1165@sa bt_value_array_append_element() &mdash;
1166 Appends an existing value to an array value.
1167*/
d24d5663 1168extern bt_value_array_append_element_status
43c59509
PP
1169bt_value_array_append_unsigned_integer_element(bt_value *value,
1170 uint64_t raw_value);
05e21286 1171
43c59509
PP
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*/
d24d5663 1199extern bt_value_array_append_element_status
43c59509
PP
1200bt_value_array_append_signed_integer_element(bt_value *value,
1201 int64_t raw_value);
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}.
05e21286 1212
43c59509
PP
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*/
d24d5663 1229extern bt_value_array_append_element_status
43c59509
PP
1230bt_value_array_append_real_element(bt_value *value, double raw_value);
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}
05e21286 1251
43c59509
PP
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*/
d24d5663 1259extern bt_value_array_append_element_status
43c59509
PP
1260bt_value_array_append_string_element(bt_value *value, const char *raw_value);
1261
1262/*!
1263@brief
1264 Creates an empty array value and appends it to the array
1265 value \bt_p{value}.
1266
1267On 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
1269array 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.
05e21286 1276
43c59509
PP
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*/
d24d5663 1293extern bt_value_array_append_element_status
43c59509
PP
1294bt_value_array_append_empty_array_element(bt_value *value,
1295 bt_value **element_value);
1296
1297/*!
1298@brief
1299 Creates an empty map value and appends it to the array
1300 value \bt_p{value}.
05e21286 1301
43c59509
PP
1302On 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
1304map 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*/
d24d5663 1328extern bt_value_array_append_element_status
43c59509
PP
1329bt_value_array_append_empty_map_element(bt_value *value,
1330 bt_value **element_value);
d24d5663 1331
43c59509
PP
1332/*!
1333@brief
1334 Status codes for bt_value_array_set_element_by_index().
1335*/
d24d5663 1336typedef enum bt_value_array_set_element_by_index_status {
43c59509
PP
1337 /*!
1338 @brief
1339 Success.
1340 */
d24d5663 1341 BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_OK = __BT_FUNC_STATUS_OK,
43c59509
PP
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,
d24d5663
PP
1348} bt_value_array_set_element_by_index_status;
1349
43c59509
PP
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
1355On success, this function replaces the existing element of \bt_p{value}
1356at 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*/
d24d5663 1387extern bt_value_array_set_element_by_index_status
43c59509
PP
1388bt_value_array_set_element_by_index(bt_value *value, uint64_t index,
1389 bt_value *element_value);
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*/
1418extern bt_value *bt_value_array_borrow_element_by_index(bt_value *value,
1419 uint64_t index);
1420
1421/*!
1422@brief
1423 Borrows the element at index \bt_p{index} from the array value
1424 \bt_p{value} (\c const version).
05e21286 1425
43c59509
PP
1426See bt_value_array_borrow_element_by_index().
1427*/
1428extern const bt_value *bt_value_array_borrow_element_by_index_const(
1429 const bt_value *value, uint64_t index);
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*/
1447extern uint64_t bt_value_array_get_length(const bt_value *value);
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*/
1465static inline
1466bt_bool bt_value_array_is_empty(const bt_value *value)
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
1482The returned value has the type #BT_VALUE_TYPE_MAP.
1483
1484@returns
1485 New map value reference, or \c NULL on memory error.
1486*/
b19ff26f 1487extern bt_value *bt_value_map_create(void);
dac5c838 1488
43c59509
PP
1489/*!
1490@brief
1491 Status codes for the <code>bt_value_map_insert_*()</code> functions.
1492*/
1493typedef 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
1512To insert an entry having a null value, pass #bt_value_null as
1513\bt_p{entry_value}.
1514
1515On 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*/
1560extern bt_value_map_insert_entry_status bt_value_map_insert_entry(
1561 bt_value *value, const char *key, bt_value *entry_value);
1562
1563/*!
1564@brief
1565 Creates a boolean value initialized to \bt_p{raw_value} and
1566 inserts or replaces an entry with the key \bt_p{key} and this value
1567 in the map value \bt_p{value}.
1568
1569On success, if \bt_p{value} already contains an entry with key
1570\bt_p{key}, this function replaces the existing entry's value with the
1571created boolean value.
1572
1573@param[in] value
1574 Map value in which to insert or replace an entry with key \bt_p{key}
1575 and the created boolean value.
1576@param[in] key
1577 Key of the entry to insert or replace in \bt_p{value} (copied).
1578@param[in] raw_value
1579 Initial raw value of the boolean value to create.
1580
1581@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1582 Success.
1583@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1584 Out of memory.
1585
1586@bt_pre_not_null{value}
1587@bt_pre_is_map_val{value}
1588@bt_pre_hot{value}
1589@bt_pre_not_null{key}
1590
1591@sa bt_value_map_insert_entry() &mdash;
1592 Inserts an entry with an existing value in a map value.
1593*/
1594extern bt_value_map_insert_entry_status bt_value_map_insert_bool_entry(
1595 bt_value *value, const char *key, bt_bool raw_value);
1596
1597/*!
1598@brief
1599 Creates an unsigned integer value initialized to \bt_p{raw_value}
1600 and inserts or replaces an entry with the key \bt_p{key} and this
1601 value in the map value \bt_p{value}.
1602
1603On success, if \bt_p{value} already contains an entry with key
1604\bt_p{key}, this function replaces the existing entry's value with the
1605created unsigned integer value.
1606
1607@param[in] value
1608 Map value in which to insert or replace an entry with key \bt_p{key}
1609 and the created unsigned integer value.
1610@param[in] key
1611 Key of the entry to insert or replace in \bt_p{value} (copied).
1612@param[in] raw_value
1613 Initial raw value of the unsigned integer value to create.
1614
1615@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1616 Success.
1617@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1618 Out of memory.
1619
1620@bt_pre_not_null{value}
1621@bt_pre_is_map_val{value}
1622@bt_pre_hot{value}
1623@bt_pre_not_null{key}
1624
1625@sa bt_value_map_insert_entry() &mdash;
1626 Inserts an entry with an existing value in a map value.
1627*/
1628extern bt_value_map_insert_entry_status
1629bt_value_map_insert_unsigned_integer_entry(bt_value *value, const char *key,
1630 uint64_t raw_value);
1631
1632/*!
1633@brief
1634 Creates a signed integer value initialized to \bt_p{raw_value} and
1635 inserts or replaces an entry with the key \bt_p{key} and this value
1636 in the map value \bt_p{value}.
1637
1638On success, if \bt_p{value} already contains an entry with key
1639\bt_p{key}, this function replaces the existing entry's value with the
1640created signed integer value.
1641
1642@param[in] value
1643 Map value in which to insert or replace an entry with key \bt_p{key}
1644 and the created signed integer value.
1645@param[in] key
1646 Key of the entry to insert or replace in \bt_p{value} (copied).
1647@param[in] raw_value
1648 Initial raw value of the signed integer value to create.
1649
1650@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1651 Success.
1652@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1653 Out of memory.
1654
1655@bt_pre_not_null{value}
1656@bt_pre_is_map_val{value}
1657@bt_pre_hot{value}
1658@bt_pre_not_null{key}
1659
1660@sa bt_value_map_insert_entry() &mdash;
1661 Inserts an entry with an existing value in a map value.
1662*/
1663extern bt_value_map_insert_entry_status
1664bt_value_map_insert_signed_integer_entry(bt_value *value, const char *key,
1665 int64_t raw_value);
1666
1667/*!
1668@brief
1669 Creates a real value initialized to \bt_p{raw_value} and inserts or
1670 replaces an entry with the key \bt_p{key} and this value in the map
1671 value \bt_p{value}.
1672
1673On success, if \bt_p{value} already contains an entry with key
1674\bt_p{key}, this function replaces the existing entry's value with the
1675created real value.
1676
1677@param[in] value
1678 Map value in which to insert or replace an entry with key \bt_p{key}
1679 and the created real value.
1680@param[in] key
1681 Key of the entry to insert or replace in \bt_p{value} (copied).
1682@param[in] raw_value
1683 Initial raw value of the real value to create.
1684
1685@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1686 Success.
1687@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1688 Out of memory.
1689
1690@bt_pre_not_null{value}
1691@bt_pre_is_map_val{value}
1692@bt_pre_hot{value}
1693@bt_pre_not_null{key}
1694
1695@sa bt_value_map_insert_entry() &mdash;
1696 Inserts an entry with an existing value in a map value.
1697*/
1698extern bt_value_map_insert_entry_status bt_value_map_insert_real_entry(
1699 bt_value *value, const char *key, double raw_value);
1700
1701/*!
1702@brief
1703 Creates a string value initialized to a copy of \bt_p{raw_value} and
1704 inserts or replaces an entry with the key \bt_p{key} and this value
1705 in the map value \bt_p{value}.
1706
1707On success, if \bt_p{value} already contains an entry with key
1708\bt_p{key}, this function replaces the existing entry's value with the
1709created string value.
1710
1711@param[in] value
1712 Map value in which to insert or replace an entry with key \bt_p{key}
1713 and the created string value.
1714@param[in] key
1715 Key of the entry to insert or replace in \bt_p{value} (copied).
1716@param[in] raw_value
1717 Initial raw value of the string value to create (copied).
1718
1719@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1720 Success.
1721@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1722 Out of memory.
1723
1724@bt_pre_not_null{value}
1725@bt_pre_is_map_val{value}
1726@bt_pre_hot{value}
1727@bt_pre_not_null{key}
1728
1729@sa bt_value_map_insert_entry() &mdash;
1730 Inserts an entry with an existing value in a map value.
1731*/
1732extern bt_value_map_insert_entry_status
1733bt_value_map_insert_string_entry(bt_value *value, const char *key,
1734 const char *raw_value);
1735
1736/*!
1737@brief
1738 Creates an empty array value and inserts or replaces an entry with
1739 the key \bt_p{key} and this value in the map value \bt_p{value}.
1740
1741On success, if \bt_p{entry_value} is not \c NULL, this function sets
1742\bt_p{*entry_value} to a \em borrowed reference of the created empty
1743array value.
1744
1745On success, if \bt_p{value} already contains an entry with key
1746\bt_p{key}, this function replaces the existing entry's value with the
1747created empty array value.
1748
1749@param[in] value
1750 Map value in which to insert or replace an entry with key \bt_p{key}
1751 and the created empty array value.
1752@param[in] key
1753 Key of the entry to insert or replace in \bt_p{value} (copied).
1754@param[out] entry_value
1755 <strong>On success, if not \c NULL</strong>, \bt_p{*entry_value} is
1756 a \em borrowed reference of the created empty array value.
1757
1758@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1759 Success.
1760@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1761 Out of memory.
1762
1763@bt_pre_not_null{value}
1764@bt_pre_is_map_val{value}
1765@bt_pre_hot{value}
1766@bt_pre_not_null{key}
1767
1768@sa bt_value_map_insert_entry() &mdash;
1769 Inserts an entry with an existing value in a map value.
1770*/
1771extern bt_value_map_insert_entry_status
1772bt_value_map_insert_empty_array_entry(bt_value *value, const char *key,
1773 bt_value **entry_value);
1774
1775/*!
1776@brief
1777 Creates an empty map value and inserts or replaces an entry with
1778 the key \bt_p{key} and this value in the map value \bt_p{value}.
1779
1780On success, if \bt_p{entry_value} is not \c NULL, this function sets
1781\bt_p{*entry_value} to a \em borrowed reference of the created empty map
1782value.
1783
1784On success, if \bt_p{value} already contains an entry with key
1785\bt_p{key}, this function replaces the existing entry's value with the
1786created empty map value.
1787
1788@param[in] value
1789 Map value in which to insert or replace an entry with key \bt_p{key}
1790 and the created empty map value.
1791@param[in] key
1792 Key of the entry to insert or replace in \bt_p{value} (copied).
1793@param[out] entry_value
1794 <strong>On success, if not \c NULL</strong>, \bt_p{*entry_value} is
1795 a \em borrowed reference of the created empty map value.
1796
1797@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
1798 Success.
1799@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
1800 Out of memory.
1801
1802@bt_pre_not_null{value}
1803@bt_pre_is_map_val{value}
1804@bt_pre_hot{value}
1805@bt_pre_not_null{key}
1806
1807@sa bt_value_map_insert_entry() &mdash;
1808 Inserts an entry with an existing value in a map value.
1809*/
1810extern bt_value_map_insert_entry_status
1811bt_value_map_insert_empty_map_entry(bt_value *value, const char *key,
1812 bt_value **entry_value);
1813
1814/*!
1815@brief
1816 Borrows the value of the entry with the key \bt_p{key} in the map
1817 value \bt_p{value}.
1818
1819If no entry with key \bt_p{key} exists in \bt_p{value}, this function
1820returns \c NULL.
1821
1822@param[in] value
1823 Map value from which to borrow the value of the entry with the
1824 key \bt_p{key}.
1825@param[in] key
1826 Key of the entry from which to borrow the value in \bt_p{value}.
1827
1828@returns
1829 @parblock
1830 \em Borrowed reference of the value of the entry with key \bt_p{key}
1831 in \bt_p{value}, or \c NULL if none.
1832
1833 The returned pointer remains valid until \bt_p{value} is modified.
1834 @endparblock
1835
1836@bt_pre_not_null{value}
1837@bt_pre_is_array_val{value}
1838@bt_pre_not_null{key}
1839
1840@sa bt_value_map_borrow_entry_value_const() &mdash;
1841 \c const version of this function.
1842@sa bt_value_map_has_entry() &mdash;
1843 Returns whether or not a map value has an entry with a given key.
1844*/
b19ff26f 1845extern bt_value *bt_value_map_borrow_entry_value(
43c59509
PP
1846 bt_value *value, const char *key);
1847
1848/*!
1849@brief
1850 Borrows the value of the entry with the key \bt_p{key} in the map
1851 value \bt_p{value} (\c const version).
1852
1853See bt_value_map_borrow_entry_value().
1854*/
1855extern const bt_value *bt_value_map_borrow_entry_value_const(
1856 const bt_value *value, const char *key);
dac5c838 1857
43c59509
PP
1858/*!
1859@brief
1860 Status codes for #bt_value_map_foreach_entry_func.
1861*/
27c61ce8 1862typedef enum bt_value_map_foreach_entry_func_status {
43c59509
PP
1863 /*!
1864 @brief
1865 Success.
1866 */
27c61ce8 1867 BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_OK = __BT_FUNC_STATUS_OK,
43c59509
PP
1868
1869 /*!
1870 @brief
1871 Interrupt the iteration process.
1872 */
27c61ce8 1873 BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_INTERRUPT = __BT_FUNC_STATUS_INTERRUPTED,
43c59509
PP
1874
1875 /*!
1876 @brief
1877 Out of memory.
1878 */
1879 BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
1880
1881 /*!
1882 @brief
1883 User error.
1884 */
1885 BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
27c61ce8
PP
1886} bt_value_map_foreach_entry_func_status;
1887
43c59509
PP
1888/*!
1889@brief
1890 User function for bt_value_map_foreach_entry().
1891
1892This is the type of the user function that bt_value_map_foreach_entry()
1893calls for each entry of the map value.
1894
1895@param[in] key
1896 Key of the map value entry.
1897@param[in] value
1898 Value of the map value entry.
1899@param[in] user_data
1900 User data, as passed as the \bt_p{user_data} parameter of
1901 bt_value_map_foreach_entry().
1902
1903@retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_OK
1904 Success.
1905@retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_INTERRUPT
1906 Interrupt the iteration process.
1907@retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_MEMORY_ERROR
1908 Out of memory.
1909@retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_ERROR
1910 User error.
1911
1912@bt_pre_not_null{key}
1913@bt_pre_not_null{value}
1914
1915@sa bt_value_map_foreach_entry() &mdash;
1916 Iterates the entries of a map value.
1917*/
27c61ce8
PP
1918typedef bt_value_map_foreach_entry_func_status
1919 (* bt_value_map_foreach_entry_func)(const char *key,
43c59509 1920 bt_value *value, void *user_data);
de079588 1921
43c59509
PP
1922/*!
1923@brief
1924 Status codes for bt_value_map_foreach_entry().
1925*/
d24d5663 1926typedef enum bt_value_map_foreach_entry_status {
43c59509
PP
1927 /*!
1928 @brief
1929 Success.
1930 */
d24d5663 1931 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_OK = __BT_FUNC_STATUS_OK,
43c59509
PP
1932
1933 /*!
1934 @brief
1935 User function interrupted the iteration process.
1936 */
9b4f9b42 1937 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_INTERRUPTED = __BT_FUNC_STATUS_INTERRUPTED,
43c59509
PP
1938
1939 /*!
1940 @brief
1941 User function error.
1942 */
1943 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_USER_ERROR = __BT_FUNC_STATUS_USER_ERROR,
1944
1945 /*!
1946 @brief
1947 Out of memory.
1948 */
1949 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
1950
1951 /*!
1952 @brief
1953 Other error.
1954 */
1955 BT_VALUE_MAP_FOREACH_ENTRY_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
d24d5663 1956} bt_value_map_foreach_entry_status;
dac5c838 1957
43c59509
PP
1958/*!
1959@brief
1960 Iterates the entries of the map value \bt_p{value}, calling
1961 \bt_p{user_func} for each entry.
1962
1963This function iterates the entries of \bt_p{value} in no particular
1964order.
1965
1966@attention
1967 You must \em not modify \bt_p{value} during the iteration process.
1968
1969\bt_p{user_func} receives \bt_p{user_data} as its last parameter.
1970
1971The iteration process stops when one of:
1972
1973- \bt_p{user_func} was called for each entry.
1974- \bt_p{user_func} does not return
1975 #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_OK.
1976
1977@param[in] value
1978 Map value of which to iterate the entries.
1979@param[in] user_func
1980 User function to call for each entry of \bt_p{value}.
1981@param[in] user_data
1982 User data to pass as the \bt_p{user_data} parameter of each call to
1983 \bt_p{user_func}.
1984
1985@retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_OK
1986 Success.
1987@retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_INTERRUPTED
1988 \bt_p{user_func} returned
1989 #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_INTERRUPT to interrupt the
1990 iteration process.
1991@retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_USER_ERROR
1992 \bt_p{user_func} returned
1993 #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_ERROR.
1994@retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_MEMORY_ERROR
1995 Out of memory.
1996@retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_ERROR
1997 Other error caused the <code>bt_value_map_foreach_entry()</code>
1998 function itself.
1999
2000@bt_pre_not_null{value}
2001@bt_pre_is_map_val{value}
2002@bt_pre_not_null{user_func}
2003
2004@sa bt_value_map_foreach_entry_const() &mdash;
2005 \c const version of this function.
2006@sa bt_value_map_borrow_entry_value() &mdash;
2007 Borrows the value of a specific map value entry.
2008*/
d24d5663 2009extern bt_value_map_foreach_entry_status bt_value_map_foreach_entry(
43c59509
PP
2010 bt_value *value, bt_value_map_foreach_entry_func user_func,
2011 void *user_data);
05e21286 2012
43c59509
PP
2013/*!
2014@brief
2015 Status codes for #bt_value_map_foreach_entry_const_func.
2016*/
2017typedef enum bt_value_map_foreach_entry_const_func_status {
2018 /*!
2019 @brief
2020 Success.
2021 */
2022 BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_OK = __BT_FUNC_STATUS_OK,
d24d5663 2023
43c59509
PP
2024 /*!
2025 @brief
2026 Interrupt the iteration process.
2027 */
2028 BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_INTERRUPT = __BT_FUNC_STATUS_INTERRUPTED,
d24d5663 2029
43c59509
PP
2030 /*!
2031 @brief
2032 Out of memory.
2033 */
2034 BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
05e21286 2035
43c59509
PP
2036 /*!
2037 @brief
2038 User error.
2039 */
2040 BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
2041} bt_value_map_foreach_entry_const_func_status;
fdd3a2da 2042
43c59509
PP
2043/*!
2044@brief
2045 User function for bt_value_map_foreach_entry_const_func().
05e21286 2046
43c59509
PP
2047This is the type of the user function that
2048bt_value_map_foreach_entry_const_func() calls for each entry of the map
2049value.
05e21286 2050
43c59509
PP
2051@param[in] key
2052 Key of the map value entry.
2053@param[in] value
2054 Value of the map value entry.
2055@param[in] user_data
2056 User data.
05e21286 2057
43c59509
PP
2058@retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_OK
2059 Success.
2060@retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_INTERRUPT
2061 Interrupt the iteration process.
2062@retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_MEMORY_ERROR
2063 Out of memory.
2064@retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_ERROR
2065 User error.
dac5c838 2066
43c59509
PP
2067@bt_pre_not_null{key}
2068@bt_pre_not_null{value}
2069
2070@sa bt_value_map_foreach_entry_const() &mdash;
2071 Iterates the entries of a \c const map value.
2072*/
2073typedef bt_value_map_foreach_entry_const_func_status
2074 (* bt_value_map_foreach_entry_const_func)(const char *key,
2075 const bt_value *value, void *user_data);
2076
2077/*!
2078@brief
2079 Status codes for bt_value_map_foreach_entry_const().
2080*/
2081typedef enum bt_value_map_foreach_entry_const_status {
2082 /*!
2083 @brief
2084 Success.
2085 */
2086 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_OK = __BT_FUNC_STATUS_OK,
2087
2088 /*!
2089 @brief
2090 User function interrupted the iteration process.
2091 */
2092 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_INTERRUPTED = __BT_FUNC_STATUS_INTERRUPTED,
2093
2094 /*!
2095 @brief
2096 User function error.
2097 */
2098 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_USER_ERROR = __BT_FUNC_STATUS_USER_ERROR,
2099
2100 /*!
2101 @brief
2102 Out of memory.
2103 */
2104 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
2105
2106 /*!
2107 @brief
2108 Other error.
2109 */
2110 BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
2111} bt_value_map_foreach_entry_const_status;
2112
2113/*!
2114@brief
2115 Iterates the entries of the map value \bt_p{value}, calling
2116 \bt_p{user_func} for each entry (\c const version).
2117
2118See bt_value_map_foreach_entry().
2119
2120@sa bt_value_map_borrow_entry_value_const() &mdash;
2121 Borrows the value of a specific map value entry.
2122*/
2123extern bt_value_map_foreach_entry_const_status bt_value_map_foreach_entry_const(
2124 const bt_value *value,
2125 bt_value_map_foreach_entry_const_func user_func,
2126 void *user_data);
2127
2128/*!
2129@brief
2130 Returns the size of the map value \bt_p{value}.
2131
2132@param[in] value
2133 Map value of which to get the size.
2134
2135@returns
2136 Size (number of contained entries) of \bt_p{value}.
2137
2138@bt_pre_not_null{value}
2139@bt_pre_is_map_val{value}
2140
2141@sa bt_value_map_is_empty() &mdash;
2142 Returns whether or not a map value is empty.
2143*/
2144extern uint64_t bt_value_map_get_size(const bt_value *value);
2145
2146/*!
2147@brief
2148 Returns whether or not the map value \bt_p{value} is empty.
2149
2150@param[in] value
2151 Map value to check.
2152
2153@returns
2154 #BT_TRUE if \bt_p{value} is empty (has the size&nbsp;0).
770750d3 2155
43c59509
PP
2156@bt_pre_not_null{value}
2157@bt_pre_is_map_val{value}
2158
2159@sa bt_value_map_get_size() &mdash;
2160 Returns the size of a map value.
2161*/
2162static inline
2163bt_bool bt_value_map_is_empty(const bt_value *value)
2164{
2165 return bt_value_map_get_size(value) == 0;
2166}
2167
2168/*!
2169@brief
2170 Returns whether or not the map value \bt_p{value} has an entry with
2171 the key \bt_p{key}.
2172
2173@param[in] value
2174 Map value to check.
2175@param[in] key
2176 Key to check.
2177
2178@returns
2179 #BT_TRUE if \bt_p{value} has an entry with the key \bt_p{key}.
2180
2181@bt_pre_not_null{value}
2182@bt_pre_is_map_val{value}
2183@bt_pre_not_null{key}
2184
2185@sa bt_value_map_borrow_entry_value_const() &mdash;
2186 Borrows the value of a specific map value entry.
2187*/
2188extern bt_bool bt_value_map_has_entry(const bt_value *value,
2189 const char *key);
2190
2191/*!
2192@brief
2193 Status codes for bt_value_map_extend().
2194*/
ab26240f 2195typedef enum bt_value_map_extend_status {
43c59509
PP
2196 /*!
2197 @brief
2198 Success.
2199 */
ab26240f 2200 BT_VALUE_MAP_EXTEND_STATUS_OK = __BT_FUNC_STATUS_OK,
43c59509
PP
2201
2202 /*!
2203 @brief
2204 Out of memory.
2205 */
2206 BT_VALUE_MAP_EXTEND_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
ab26240f
FD
2207} bt_value_map_extend_status;
2208
43c59509
PP
2209/*!
2210@brief
2211 Extends the map value \bt_p{value} with the map value
2212 \bt_p{extension_value}.
2213
2214For each entry in \bt_p{extension_value}, this function calls
2215bt_value_map_insert_entry() to insert or replace it in the map value
2216\bt_p{value}.
2217
2218For example, with:
2219
2220<dl>
2221 <dt>
2222 \bt_p{value}
2223 </dt>
2224 <dd>
2225 @code{.json}
2226 {
2227 "man": "giant",
2228 "strange": 23
2229 }
2230 @endcode
2231 </dd>
2232
2233 <dt>
2234 \bt_p{extension_value}
2235 </dt>
2236 <dd>
2237 @code{.json}
2238 {
2239 "balance": -17
2240 "strange": false
2241 }
2242 @endcode
2243 </dd>
2244</dl>
2245
2246The map value \bt_p{value} becomes:
2247
2248@code{.json}
2249{
2250 "man": "giant",
2251 "strange": false,
2252 "balance": -17
2253}
2254@endcode
2255
2256@param[in] value
2257 Map value to extend.
2258@param[in] extension_value
2259 Extension map value.
2260
2261@retval #BT_VALUE_MAP_EXTEND_STATUS_OK
2262 Success.
2263@retval #BT_VALUE_MAP_EXTEND_STATUS_MEMORY_ERROR
2264 Out of memory.
2265
2266@bt_pre_not_null{value}
2267@bt_pre_is_map_val{value}
2268@bt_pre_not_null{extension_value}
2269@bt_pre_is_map_val{extension_value}
2270
2271@sa bt_value_copy() &mdash;
2272 Deep-copies a value.
2273*/
ab26240f 2274extern bt_value_map_extend_status bt_value_map_extend(
43c59509
PP
2275 bt_value *value, const bt_value *extension_value);
2276
2277/*! @} */
2278
2279/*!
2280@name General
2281@{
2282*/
2283
2284/*!
2285@brief
2286 Status codes for bt_value_copy().
2287*/
2288typedef enum bt_value_copy_status {
2289 /*!
2290 @brief
2291 Success.
2292 */
2293 BT_VALUE_COPY_STATUS_OK = __BT_FUNC_STATUS_OK,
2294
2295 /*!
2296 @brief
2297 Out of memory.
2298 */
2299 BT_VALUE_COPY_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
2300} bt_value_copy_status;
2301
2302/*!
2303@brief
2304 Deep-copies a value object.
2305
2306This function deep-copies \bt_p{value} and sets \bt_p{*copy} to the
2307result.
2308
2309Because \bt_p{*copy} is a deep copy, it does not contain, recursively,
2310any reference that \bt_p{value} contains, but the raw values are
2311identical.
2312
2313@param[in] value
2314 Value to deep-copy.
2315@param[in] copy_value
2316 <strong>On success</strong>, \bt_p{*copy_value} is a deep copy of
2317 \bt_p{value}.
2318
2319@retval #BT_VALUE_COPY_STATUS_OK
2320 Success.
2321@retval #BT_VALUE_COPY_STATUS_MEMORY_ERROR
2322 Out of memory.
2323
2324@bt_pre_not_null{value}
2325@bt_pre_not_null{copy_value}
2326*/
2327extern bt_value_copy_status bt_value_copy(const bt_value *value,
2328 bt_value **copy_value);
2329
2330/*!
2331@brief
2332 Returns whether or not the value \bt_p{a_value} is equal,
2333 recursively, to \bt_p{b_value}.
2334
2335@note
2336 If you want to know whether or not a value is a null value, you can
2337 also directly compare its pointer to the #bt_value_null variable.
2338
2339@param[in] a_value
2340 Value A.
2341@param[in] b_value
2342 Value B.
2343
2344@returns
2345 #BT_TRUE if \bt_p{a_value} is equal, recursively, to \bt_p{b_value}.
2346
2347@bt_pre_not_null{a_value}
2348@bt_pre_not_null{b_value}
2349*/
2350extern bt_bool bt_value_is_equal(const bt_value *a_value,
2351 const bt_value *b_value);
2352
2353/*! @} */
2354
2355/*!
2356@name Reference count
2357@{
2358*/
2359
2360/*!
2361@brief
2362 Increments the \ref api-fund-shared-object "reference count" of
2363 the value \bt_p{value}.
2364
2365@param[in] value
2366 @parblock
2367 Value of which to increment the reference count.
2368
2369 Can be \c NULL.
2370 @endparblock
2371
2372@sa bt_value_put_ref() &mdash;
2373 Decrements the reference count of a value.
2374*/
2375extern void bt_value_get_ref(const bt_value *value);
2376
2377/*!
2378@brief
2379 Decrements the \ref api-fund-shared-object "reference count" of
2380 the value \bt_p{value}.
2381
2382@param[in] value
2383 @parblock
2384 Value of which to decrement the reference count.
2385
2386 Can be \c NULL.
2387 @endparblock
2388
2389@sa bt_value_get_ref() &mdash;
2390 Increments the reference count of a value.
2391*/
2392extern void bt_value_put_ref(const bt_value *value);
2393
2394/*!
2395@brief
2396 Decrements the reference count of the value \bt_p{_value}, and then
2397 sets \bt_p{_value} to \c NULL.
2398
2399@param _value
2400 @parblock
2401 Value of which to decrement the reference count.
2402
2403 Can contain \c NULL.
2404 @endparblock
2405
2406@bt_pre_assign_expr{_value}
2407*/
2408#define BT_VALUE_PUT_REF_AND_RESET(_value) \
2409 do { \
2410 bt_value_put_ref(_value); \
2411 (_value) = NULL; \
2412 } while (0)
2413
2414/*!
2415@brief
2416 Decrements the reference count of the value \bt_p{_dst}, sets
2417 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
2418
2419This macro effectively moves a value reference from the expression
2420\bt_p{_src} to the expression \bt_p{_dst}, putting the existing
2421\bt_p{_dst} reference.
2422
2423@param _dst
2424 @parblock
2425 Destination expression.
2426
2427 Can contain \c NULL.
2428 @endparblock
2429@param _src
2430 @parblock
2431 Source expression.
2432
2433 Can contain \c NULL.
2434 @endparblock
2435
2436@bt_pre_assign_expr{_dst}
2437@bt_pre_assign_expr{_src}
2438*/
2439#define BT_VALUE_MOVE_REF(_dst, _src) \
2440 do { \
2441 bt_value_put_ref(_dst); \
2442 (_dst) = (_src); \
2443 (_src) = NULL; \
2444 } while (0)
2445
2446/*! @} */
2447
2448/*! @} */
ab26240f 2449
dac5c838
PP
2450#ifdef __cplusplus
2451}
2452#endif
2453
924dc299 2454#endif /* BABELTRACE2_VALUE_H */
This page took 0.202775 seconds and 4 git commands to generate.