plugins/ctf/common/notif-iter/notif-iter.c: add logging
[babeltrace.git] / include / babeltrace / values.h
1 #ifndef BABELTRACE_VALUES_H
2 #define BABELTRACE_VALUES_H
3
4 /*
5 * Babeltrace - Value objects
6 *
7 * Copyright (c) 2015-2016 EfficiOS Inc. and Linux Foundation
8 * Copyright (c) 2015-2016 Philippe Proulx <pproulx@efficios.com>
9 *
10 * Permission is hereby granted, free of charge, to any person obtaining a copy
11 * of this software and associated documentation files (the "Software"), to deal
12 * in the Software without restriction, including without limitation the rights
13 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14 * copies of the Software, and to permit persons to whom the Software is
15 * furnished to do so, subject to the following conditions:
16 *
17 * The above copyright notice and this permission notice shall be included in
18 * all copies or substantial portions of the Software.
19 *
20 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26 * SOFTWARE.
27 */
28
29 #include <stdint.h>
30 #include <stddef.h>
31 #include <babeltrace/ref.h>
32 #include <babeltrace/types.h>
33
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37
38 /**
39 @defgroup values Value objects
40 @ingroup apiref
41 @brief Value objects.
42
43 @code
44 #include <babeltrace/values.h>
45 @endcode
46
47 This is a set of <strong><em>value objects</em></strong>. With the
48 functions documented here, you can create and modify:
49
50 - \link bt_value_bool_create() Boolean value objects\endlink.
51 - \link bt_value_integer_create() Integer value objects\endlink.
52 - \link bt_value_float_create() Floating point number
53 value objects\endlink.
54 - \link bt_value_string_create() String value objects\endlink.
55 - \link bt_value_array_create() Array value objects\endlink,
56 containing zero or more value objects.
57 - \link bt_value_map_create() Map value objects\endlink, mapping
58 string keys to value objects.
59
60 As with any Babeltrace object, value objects have
61 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
62 counts</a>. When you \link bt_value_array_append() append a value object
63 to an array value object\endlink, or when you \link bt_value_map_insert()
64 insert a value object into a map value object\endlink, its reference
65 count is incremented, as well as when you get a value object back from
66 those objects. See \ref refs to learn more about the reference counting
67 management of Babeltrace objects.
68
69 Most functions of this API return a <em>status code</em>, one of the
70 values of #bt_value_status.
71
72 You can create a deep copy of any value object with bt_value_copy(). You
73 can compare two value objects with bt_value_compare().
74
75 You can \em freeze a value object with bt_value_freeze(). You can get
76 the raw value of a frozen value object, but you cannot modify it.
77 Reference counting still works on frozen value objects. You can copy
78 a frozen value object: the returned copy is not frozen. You can also
79 compare a frozen value object to another value object (frozen or not).
80 Freezing a value object is typically used to make it immutable after
81 it's built by its initial owner.
82
83 The following matrix shows some categorized value object functions
84 to use for each value object type:
85
86 <table>
87 <tr>
88 <th>Function role &rarr;<br>
89 Value object type &darr;
90 <th>Create
91 <th>Check type
92 <th>Get value
93 <th>Set value
94 </tr>
95 <tr>
96 <th>Null
97 <td>Use the \ref bt_value_null variable
98 <td>bt_value_is_null()
99 <td>N/A
100 <td>N/A
101 </tr>
102 <tr>
103 <th>Boolean
104 <td>bt_value_bool_create()<br>
105 bt_value_bool_create_init()
106 <td>bt_value_is_bool()
107 <td>bt_value_bool_get()
108 <td>bt_value_bool_set()
109 </tr>
110 <tr>
111 <th>Integer
112 <td>bt_value_integer_create()<br>
113 bt_value_integer_create_init()
114 <td>bt_value_is_integer()
115 <td>bt_value_integer_get()
116 <td>bt_value_integer_set()
117 </tr>
118 <tr>
119 <th>Floating point<br>number
120 <td>bt_value_float_create()<br>
121 bt_value_float_create_init()
122 <td>bt_value_is_float()
123 <td>bt_value_float_get()
124 <td>bt_value_float_set()
125 </tr>
126 <tr>
127 <th>String
128 <td>bt_value_string_create()<br>
129 bt_value_string_create_init()
130 <td>bt_value_is_string()
131 <td>bt_value_string_get()
132 <td>bt_value_string_set()
133 </tr>
134 <tr>
135 <th>Array
136 <td>bt_value_array_create()
137 <td>bt_value_is_array()
138 <td>bt_value_array_get()
139 <td>bt_value_array_append()<br>
140 bt_value_array_append_bool()<br>
141 bt_value_array_append_integer()<br>
142 bt_value_array_append_float()<br>
143 bt_value_array_append_string()<br>
144 bt_value_array_append_empty_array()<br>
145 bt_value_array_append_empty_map()<br>
146 bt_value_array_set()
147 </tr>
148 <tr>
149 <th>Map
150 <td>bt_value_map_create()<br>
151 bt_value_map_extend()
152 <td>bt_value_is_map()
153 <td>bt_value_map_get()<br>
154 bt_value_map_foreach()
155 <td>bt_value_map_insert()<br>
156 bt_value_map_insert_bool()<br>
157 bt_value_map_insert_integer()<br>
158 bt_value_map_insert_float()<br>
159 bt_value_map_insert_string()<br>
160 bt_value_map_insert_empty_array()<br>
161 bt_value_map_insert_empty_map()
162 </tr>
163 </table>
164
165 @file
166 @brief Value object types and functions.
167 @sa values
168
169 @addtogroup values
170 @{
171 */
172
173 /**
174 @brief Status codes.
175 */
176 enum bt_value_status {
177 /// Value object cannot be altered because it's frozen.
178 BT_VALUE_STATUS_FROZEN = -4,
179
180 /// Operation cancelled.
181 BT_VALUE_STATUS_CANCELLED = -3,
182
183 /* -22 for compatibility with -EINVAL */
184 /// Invalid argument.
185 BT_VALUE_STATUS_INVAL = -22,
186
187 /// General error.
188 BT_VALUE_STATUS_ERROR = -1,
189
190 /// Okay, no error.
191 BT_VALUE_STATUS_OK = 0,
192 };
193
194 /**
195 @struct bt_value
196 @brief A value object.
197 @sa values
198 */
199 struct bt_value;
200
201 /**
202 @brief The null value object singleton.
203
204 You \em must use this variable when you need the null value object.
205
206 The null value object singleton has no reference count: there is only
207 one. You can compare any value object address to the null value object
208 singleton to check if it's the null value object, or otherwise with
209 bt_value_is_null().
210
211 You can pass \ref bt_value_null to bt_get() or bt_put(): it has
212 <em>no effect</em>.
213
214 The null value object singleton is <em>always frozen</em> (see
215 bt_value_is_frozen()).
216
217 The functions of this API return this variable when the value object
218 is actually the null value object (of type #BT_VALUE_TYPE_NULL),
219 whereas \c NULL means an error of some sort.
220 */
221 extern struct bt_value *bt_value_null;
222
223 /**
224 @name Type information
225 @{
226 */
227
228 /**
229 @brief Value object type.
230 */
231 enum bt_value_type {
232 /// Unknown value object, used as an error code.
233 BT_VALUE_TYPE_UNKNOWN = -1,
234
235 /// Null value object.
236 BT_VALUE_TYPE_NULL = 0,
237
238 /// Boolean value object (holds #BT_TRUE or #BT_FALSE).
239 BT_VALUE_TYPE_BOOL = 1,
240
241 /// Integer value object (holds a signed 64-bit integer raw value).
242 BT_VALUE_TYPE_INTEGER = 2,
243
244 /// Floating point number value object (holds a \c double raw value).
245 BT_VALUE_TYPE_FLOAT = 3,
246
247 /// String value object.
248 BT_VALUE_TYPE_STRING = 4,
249
250 /// Array value object.
251 BT_VALUE_TYPE_ARRAY = 5,
252
253 /// Map value object.
254 BT_VALUE_TYPE_MAP = 6,
255 };
256
257 /**
258 @brief Returns the type of the value object \p object.
259
260 @param[in] object Value object of which to get the type.
261 @returns Type of value object \p object,
262 or #BT_VALUE_TYPE_UNKNOWN on error.
263
264 @prenotnull{object}
265 @postrefcountsame{object}
266
267 @sa #bt_value_type: Value object types.
268 @sa bt_value_is_null(): Returns whether or not a given value object
269 is the null value object.
270 @sa bt_value_is_bool(): Returns whether or not a given value object
271 is a boolean value object.
272 @sa bt_value_is_integer(): Returns whether or not a given value
273 object is an integer value object.
274 @sa bt_value_is_float(): Returns whether or not a given value object
275 is a floating point number value object.
276 @sa bt_value_is_string(): Returns whether or not a given value object
277 is a string value object.
278 @sa bt_value_is_array(): Returns whether or not a given value object
279 is an array value object.
280 @sa bt_value_is_map(): Returns whether or not a given value object
281 is a map value object.
282 */
283 extern enum bt_value_type bt_value_get_type(const struct bt_value *object);
284
285 /**
286 @brief Returns whether or not the value object \p object is the null
287 value object.
288
289 The only valid null value object is \ref bt_value_null.
290
291 An alternative to calling this function is to directly compare the value
292 object pointer to the \ref bt_value_null variable.
293
294 @param[in] object Value object to check.
295 @returns #BT_TRUE if \p object is the null value object.
296
297 @prenotnull{object}
298 @postrefcountsame{object}
299
300 @sa bt_value_get_type(): Returns the type of a given value object.
301 */
302 static inline
303 bt_bool bt_value_is_null(const struct bt_value *object)
304 {
305 return bt_value_get_type(object) == BT_VALUE_TYPE_NULL;
306 }
307
308 /**
309 @brief Returns whether or not the value object \p object is a boolean
310 value object.
311
312 @param[in] object Value object to check.
313 @returns #BT_TRUE if \p object is a boolean value object.
314
315 @prenotnull{object}
316 @postrefcountsame{object}
317
318 @sa bt_value_get_type(): Returns the type of a given value object.
319 */
320 static inline
321 bt_bool bt_value_is_bool(const struct bt_value *object)
322 {
323 return bt_value_get_type(object) == BT_VALUE_TYPE_BOOL;
324 }
325
326 /**
327 @brief Returns whether or not the value object \p object is an integer
328 value object.
329
330 @param[in] object Value object to check.
331 @returns #BT_TRUE if \p object is an integer value object.
332
333 @sa bt_value_get_type(): Returns the type of a given value object.
334 */
335 static inline
336 bt_bool bt_value_is_integer(const struct bt_value *object)
337 {
338 return bt_value_get_type(object) == BT_VALUE_TYPE_INTEGER;
339 }
340
341 /**
342 @brief Returns whether or not the value object \p object is a floating
343 point number value object.
344
345 @param[in] object Value object to check.
346 @returns #BT_TRUE if \p object is a floating point
347 number value object.
348
349 @prenotnull{object}
350 @postrefcountsame{object}
351
352 @sa bt_value_get_type(): Returns the type of a given value object.
353 */
354 static inline
355 bt_bool bt_value_is_float(const struct bt_value *object)
356 {
357 return bt_value_get_type(object) == BT_VALUE_TYPE_FLOAT;
358 }
359
360 /**
361 @brief Returns whether or not the value object \p object is a string
362 value object.
363
364 @param[in] object Value object to check.
365 @returns #BT_TRUE if \p object is a string value object.
366
367 @prenotnull{object}
368 @postrefcountsame{object}
369
370 @sa bt_value_get_type(): Returns the type of a given value object.
371 */
372 static inline
373 bt_bool bt_value_is_string(const struct bt_value *object)
374 {
375 return bt_value_get_type(object) == BT_VALUE_TYPE_STRING;
376 }
377
378 /**
379 @brief Returns whether or not the value object \p object is an array
380 value object.
381
382 @param[in] object Value object to check.
383 @returns #BT_TRUE if \p object is an array value object.
384
385 @prenotnull{object}
386 @postrefcountsame{object}
387
388 @sa bt_value_get_type(): Returns the type of a given value object.
389 */
390 static inline
391 bt_bool bt_value_is_array(const struct bt_value *object)
392 {
393 return bt_value_get_type(object) == BT_VALUE_TYPE_ARRAY;
394 }
395
396 /**
397 @brief Returns whether or not the value object \p object is a map value
398 object.
399
400 @param[in] object Value object to check.
401 @returns #BT_TRUE if \p object is a map value object.
402
403 @prenotnull{object}
404 @postrefcountsame{object}
405
406 @sa bt_value_get_type(): Returns the type of a given value object.
407 */
408 static inline
409 bt_bool bt_value_is_map(const struct bt_value *object)
410 {
411 return bt_value_get_type(object) == BT_VALUE_TYPE_MAP;
412 }
413
414 /** @} */
415
416 /**
417 @name Common value object functions
418 @{
419 */
420
421 /**
422 @brief Recursively freezes the value object \p object.
423
424 You cannot modify a frozen value object: it is considered immutable.
425 Reference counting still works on a frozen value object, however: you
426 can pass a frozen value object to bt_get() and bt_put().
427
428 If \p object is an array value object or a map value object, this
429 function also freezes all its children recursively.
430
431 Freezing a value object is typically used to make it immutable after
432 it's built by its initial owner.
433
434 @param[in] object Value object to freeze.
435 @returns Status code. If \p object
436 is already frozen, however, #BT_VALUE_STATUS_OK
437 is returned anyway (that is, this function never
438 returns #BT_VALUE_STATUS_FROZEN).
439
440 @prenotnull{object}
441 @postrefcountsame{object}
442 @post <strong>On success</strong>, \p object and all its children
443 are frozen.
444
445 @sa bt_value_is_frozen(): Returns whether or not a value object is
446 frozen.
447 */
448 extern enum bt_value_status bt_value_freeze(struct bt_value *object);
449
450 /**
451 @brief Returns whether or not the value object \p object is frozen.
452
453 @param[in] object Value object to check.
454 @returns #BT_TRUE if \p object is frozen.
455
456 @prenotnull{object}
457 @postrefcountsame{object}
458 */
459 extern bt_bool bt_value_is_frozen(const struct bt_value *object);
460
461 /**
462 @brief Creates a \em deep copy of the value object \p object.
463
464 You can copy a frozen value object: the resulting copy is
465 <em>not frozen</em>.
466
467 @param[in] object Value object to copy.
468 @returns Deep copy of \p object on success, or \c NULL
469 on error.
470
471 @prenotnull{object}
472 @post <strong>On success, if the returned value object is not
473 \ref bt_value_null</strong>, its reference count is 1.
474 @postrefcountsame{object}
475 */
476 extern struct bt_value *bt_value_copy(const struct bt_value *object);
477
478 /**
479 @brief Recursively compares the value objects \p object_a and
480 \p object_b and returns #BT_TRUE if they have the same
481 \em content (raw values).
482
483 @param[in] object_a Value object A to compare to \p object_b.
484 @param[in] object_b Value object B to compare to \p object_a.
485 @returns #BT_TRUE if \p object_a and \p object_b have the
486 same \em content, or #BT_FALSE if they differ
487 or on error.
488
489 @postrefcountsame{object_a}
490 @postrefcountsame{object_b}
491 */
492 extern bt_bool bt_value_compare(const struct bt_value *object_a,
493 const struct bt_value *object_b);
494
495 /** @} */
496
497 /**
498 @name Boolean value object functions
499 @{
500 */
501
502 /**
503 @brief Creates a default boolean value object.
504
505 The created boolean value object's initial raw value is #BT_FALSE.
506
507 @returns Created boolean value object on success, or \c NULL
508 on error.
509
510 @postsuccessrefcountret1
511
512 @sa bt_value_bool_create_init(): Creates an initialized boolean
513 value object.
514 */
515 extern struct bt_value *bt_value_bool_create(void);
516
517 /**
518 @brief Creates a boolean value object with its initial raw value set to
519 \p val.
520
521 @param[in] val Initial raw value.
522 @returns Created boolean value object on success, or
523 \c NULL on error.
524
525 @postsuccessrefcountret1
526
527 @sa bt_value_bool_create(): Creates a default boolean value object.
528 */
529 extern struct bt_value *bt_value_bool_create_init(bt_bool val);
530
531 /**
532 @brief Returns the boolean raw value of the boolean value object
533 \p bool_obj.
534
535 @param[in] bool_obj Boolean value object of which to get the
536 raw value.
537 @param[out] val Returned boolean raw value.
538 @returns Status code.
539
540 @prenotnull{bool_obj}
541 @prenotnull{val}
542 @pre \p bool_obj is a boolean value object.
543 @postrefcountsame{bool_obj}
544
545 @sa bt_value_bool_set(): Sets the raw value of a boolean value object.
546 */
547 extern enum bt_value_status bt_value_bool_get(
548 const struct bt_value *bool_obj, bt_bool *val);
549
550 /**
551 @brief Sets the boolean raw value of the boolean value object
552 \p bool_obj to \p val.
553
554 @param[in] bool_obj Boolean value object of which to set
555 the raw value.
556 @param[in] val New boolean raw value.
557 @returns Status code.
558
559 @prenotnull{bool_obj}
560 @pre \p bool_obj is a boolean value object.
561 @prehot{bool_obj}
562 @postrefcountsame{bool_obj}
563
564 @sa bt_value_bool_get(): Returns the raw value of a given boolean
565 value object.
566 */
567 extern enum bt_value_status bt_value_bool_set(struct bt_value *bool_obj,
568 bt_bool val);
569
570 /** @} */
571
572 /**
573 @name Integer value object functions
574 @{
575 */
576
577 /**
578 @brief Creates a default integer value object.
579
580 The created integer value object's initial raw value is 0.
581
582 @returns Created integer value object on success, or \c NULL
583 on error.
584
585 @postsuccessrefcountret1
586
587 @sa bt_value_integer_create_init(): Creates an initialized integer
588 value object.
589 */
590 extern struct bt_value *bt_value_integer_create(void);
591
592 /**
593 @brief Creates an integer value object with its initial raw value set to
594 \p val.
595
596 @param[in] val Initial raw value.
597 @returns Created integer value object on success, or
598 \c NULL on error.
599
600 @postsuccessrefcountret1
601
602 @sa bt_value_integer_create(): Creates a default integer
603 value object.
604 */
605 extern struct bt_value *bt_value_integer_create_init(int64_t val);
606
607 /**
608 @brief Returns the integer raw value of the integer value object
609 \p integer_obj.
610
611 @param[in] integer_obj Integer value object of which to get the
612 raw value.
613 @param[out] val Returned integer raw value.
614 @returns Status code.
615
616 @prenotnull{integer_obj}
617 @prenotnull{val}
618 @pre \p integer_obj is an integer value object.
619 @postrefcountsame{integer_obj}
620
621 @sa bt_value_integer_set(): Sets the raw value of an integer value
622 object.
623 */
624 extern enum bt_value_status bt_value_integer_get(
625 const struct bt_value *integer_obj, int64_t *val);
626
627 /**
628 @brief Sets the integer raw value of the integer value object
629 \p integer_obj to \p val.
630
631 @param[in] integer_obj Integer value object of which to set
632 the raw value.
633 @param[in] val New integer raw value.
634 @returns Status code.
635
636 @prenotnull{integer_obj}
637 @pre \p integer_obj is an integer value object.
638 @prehot{integer_obj}
639 @postrefcountsame{integer_obj}
640
641 @sa bt_value_integer_get(): Returns the raw value of a given integer
642 value object.
643 */
644 extern enum bt_value_status bt_value_integer_set(
645 struct bt_value *integer_obj, int64_t val);
646
647 /** @} */
648
649 /**
650 @name Floating point number value object functions
651 @{
652 */
653
654 /**
655 @brief Creates a default floating point number value object.
656
657 The created floating point number value object's initial raw value is 0.
658
659 @returns Created floating point number value object on success,
660 or \c NULL on error.
661
662 @postsuccessrefcountret1
663
664 @sa bt_value_float_create_init(): Creates an initialized floating
665 point number value object.
666 */
667 extern struct bt_value *bt_value_float_create(void);
668
669 /**
670 @brief Creates a floating point number value object with its initial raw
671 value set to \p val.
672
673 @param[in] val Initial raw value.
674 @returns Created floating point number value object on
675 success, or \c NULL on error.
676
677 @postsuccessrefcountret1
678
679 @sa bt_value_float_create(): Creates a default floating point number
680 value object.
681 */
682 extern struct bt_value *bt_value_float_create_init(double val);
683
684 /**
685 @brief Returns the floating point number raw value of the floating point
686 number value object \p float_obj.
687
688 @param[in] float_obj Floating point number value object of which to
689 get the raw value.
690 @param[out] val Returned floating point number raw value
691 @returns Status code.
692
693 @prenotnull{float_obj}
694 @prenotnull{val}
695 @pre \p float_obj is a floating point number value object.
696 @postrefcountsame{float_obj}
697
698 @sa bt_value_float_set(): Sets the raw value of a given floating
699 point number value object.
700 */
701 extern enum bt_value_status bt_value_float_get(
702 const struct bt_value *float_obj, double *val);
703
704 /**
705 @brief Sets the floating point number raw value of the floating point
706 number value object \p float_obj to \p val.
707
708 @param[in] float_obj Floating point number value object of which to set
709 the raw value.
710 @param[in] val New floating point number raw value.
711 @returns Status code.
712
713 @prenotnull{float_obj}
714 @pre \p float_obj is a floating point number value object.
715 @prehot{float_obj}
716 @postrefcountsame{float_obj}
717
718 @sa bt_value_float_get(): Returns the raw value of a floating point
719 number value object.
720 */
721 extern enum bt_value_status bt_value_float_set(
722 struct bt_value *float_obj, double val);
723
724 /** @} */
725
726 /**
727 @name String value object functions
728 @{
729 */
730
731 /**
732 @brief Creates a default string value object.
733
734 The string value object is initially empty.
735
736 @returns Created string value object on success, or \c NULL
737 on error.
738
739 @postsuccessrefcountret1
740
741 @sa bt_value_string_create_init(): Creates an initialized string
742 value object.
743 */
744 extern struct bt_value *bt_value_string_create(void);
745
746 /**
747 @brief Creates a string value object with its initial raw value set to
748 \p val.
749
750 On success, \p val is copied.
751
752 @param[in] val Initial raw value (copied on success).
753 @returns Created string value object on success, or
754 \c NULL on error.
755
756 @prenotnull{val}
757 @postsuccessrefcountret1
758
759 @sa bt_value_float_create(): Creates a default string value object.
760 */
761 extern struct bt_value *bt_value_string_create_init(const char *val);
762
763 /**
764 @brief Returns the string raw value of the string value object
765 \p string_obj.
766
767 The returned string is placed in \p *val. It is valid as long as this
768 value object exists and is \em not modified. The ownership of the
769 returned string is \em not transferred to the caller.
770
771 @param[in] string_obj String value object of which to get the
772 raw value.
773 @param[out] val Returned string raw value.
774 @returns Status code.
775
776 @prenotnull{string_obj}
777 @prenotnull{val}
778 @pre \p string_obj is a string value object.
779 @postrefcountsame{string_obj}
780
781 @sa bt_value_string_set(): Sets the raw value of a string
782 value object.
783 */
784 extern enum bt_value_status bt_value_string_get(
785 const struct bt_value *string_obj, const char **val);
786
787 /**
788 @brief Sets the string raw value of the string value object
789 \p string_obj to \p val.
790
791 On success, \p val is copied.
792
793 @param[in] string_obj String value object of which to set
794 the raw value.
795 @param[in] val New string raw value (copied on success).
796 @returns Status code.
797
798 @prenotnull{string_obj}
799 @prenotnull{val}
800 @pre \p string_obj is a string value object.
801 @prehot{string_obj}
802 @postrefcountsame{string_obj}
803
804 @sa bt_value_string_get(): Returns the raw value of a given string
805 value object.
806 */
807 extern enum bt_value_status bt_value_string_set(struct bt_value *string_obj,
808 const char *val);
809
810 /**
811 * @}
812 */
813
814 /**
815 * @name Array value object functions
816 * @{
817 */
818
819 /**
820 @brief Creates an empty array value object.
821
822 @returns Created array value object on success, or \c NULL
823 on error.
824
825 @postsuccessrefcountret1
826 */
827 extern struct bt_value *bt_value_array_create(void);
828
829 /**
830 @brief Returns the size of the array value object \p array_obj, that is,
831 the number of value objects contained in \p array_obj.
832
833 @param[in] array_obj Array value object of which to get the size.
834 @returns Number of value objects contained in
835 \p array_obj if the return value is 0 (empty)
836 or a positive value, or one of
837 #bt_value_status negative values otherwise.
838
839 @prenotnull{array_obj}
840 @pre \p array_obj is an array value object.
841 @postrefcountsame{array_obj}
842
843 @sa bt_value_array_is_empty(): Checks whether or not a given array
844 value object is empty.
845 */
846 extern int64_t bt_value_array_size(const struct bt_value *array_obj);
847
848 /**
849 @brief Checks whether or not the array value object \p array_obj
850 is empty.
851
852 @param[in] array_obj Array value object to check.
853 @returns #BT_TRUE if \p array_obj is empty.
854
855 @prenotnull{array_obj}
856 @pre \p array_obj is an array value object.
857 @postrefcountsame{array_obj}
858
859 @sa bt_value_array_size(): Returns the size of a given array value
860 object.
861 */
862 extern bt_bool bt_value_array_is_empty(const struct bt_value *array_obj);
863
864 /**
865 @brief Returns the value object contained in the array value object
866 \p array_obj at the index \p index.
867
868 @param[in] array_obj Array value object of which to get an element.
869 @param[in] index Index of value object to get.
870 @returns Value object at index \p index on
871 success, or \c NULL on error.
872
873 @prenotnull{array_obj}
874 @pre \p array_obj is an array value object.
875 @pre \p index is lesser than the size of \p array_obj (see
876 bt_value_array_size()).
877 @post <strong>On success, if the returned value object is not
878 \ref bt_value_null</strong>, its reference count is incremented.
879 @postrefcountsame{array_obj}
880 */
881 extern struct bt_value *bt_value_array_get(const struct bt_value *array_obj,
882 uint64_t index);
883
884 /**
885 @brief Appends the value object \p element_obj to the array value
886 object \p array_obj.
887
888 @param[in] array_obj Array value object in which to append
889 \p element_obj.
890 @param[in] element_obj Value object to append.
891 @returns Status code.
892
893 @prenotnull{array_obj}
894 @prenotnull{element_obj}
895 @pre \p array_obj is an array value object.
896 @prehot{array_obj}
897 @post <strong>On success, if \p element_obj is not
898 \ref bt_value_null</strong>, its reference count is incremented.
899 @postrefcountsame{array_obj}
900
901 @sa bt_value_array_append_bool(): Appends a boolean raw value to a
902 given array value object.
903 @sa bt_value_array_append_integer(): Appends an integer raw value
904 to a given array value object.
905 @sa bt_value_array_append_float(): Appends a floating point number
906 raw value to a given array value object.
907 @sa bt_value_array_append_string(): Appends a string raw value to a
908 given array value object.
909 @sa bt_value_array_append_empty_array(): Appends an empty array value
910 object to a given array value object.
911 @sa bt_value_array_append_empty_map(): Appends an empty map value
912 object to a given array value object.
913 */
914 extern enum bt_value_status bt_value_array_append(struct bt_value *array_obj,
915 struct bt_value *element_obj);
916
917 /**
918 @brief Appends the boolean raw value \p val to the array value object
919 \p array_obj.
920
921 This is a convenience function which creates the underlying boolean
922 value object before appending it.
923
924 @param[in] array_obj Array value object in which to append \p val.
925 @param[in] val Boolean raw value to append to \p array_obj.
926 @returns Status code.
927
928 @prenotnull{array_obj}
929 @pre \p array_obj is an array value object.
930 @prehot{array_obj}
931 @postrefcountsame{array_obj}
932
933 @sa bt_value_array_append(): Appends a value object to a given
934 array value object.
935 */
936 extern enum bt_value_status bt_value_array_append_bool(
937 struct bt_value *array_obj, bt_bool val);
938
939 /**
940 @brief Appends the integer raw value \p val to the array value object
941 \p array_obj.
942
943 This is a convenience function which creates the underlying integer
944 value object before appending it.
945
946 @param[in] array_obj Array value object in which to append \p val.
947 @param[in] val Integer raw value to append to \p array_obj.
948 @returns Status code.
949
950 @prenotnull{array_obj}
951 @pre \p array_obj is an array value object.
952 @prehot{array_obj}
953 @postrefcountsame{array_obj}
954
955 @sa bt_value_array_append(): Appends a value object to a given
956 array value object.
957 */
958 extern enum bt_value_status bt_value_array_append_integer(
959 struct bt_value *array_obj, int64_t val);
960
961 /**
962 @brief Appends the floating point number raw value \p val to the array
963 value object \p array_obj.
964
965 This is a convenience function which creates the underlying floating
966 point number value object before appending it.
967
968 @param[in] array_obj Array value object in which to append \p val.
969 @param[in] val Floating point number raw value to append
970 to \p array_obj.
971 @returns Status code.
972
973 @prenotnull{array_obj}
974 @pre \p array_obj is an array value object.
975 @prehot{array_obj}
976 @postrefcountsame{array_obj}
977
978 @sa bt_value_array_append(): Appends a value object to a given
979 array value object.
980 */
981 extern enum bt_value_status bt_value_array_append_float(
982 struct bt_value *array_obj, double val);
983
984 /**
985 @brief Appends the string raw value \p val to the array value object
986 \p array_obj.
987
988 This is a convenience function which creates the underlying string value
989 object before appending it.
990
991 On success, \p val is copied.
992
993 @param[in] array_obj Array value object in which to append \p val.
994 @param[in] val String raw value to append to \p array_obj
995 (copied on success).
996 @returns Status code.
997
998 @prenotnull{array_obj}
999 @pre \p array_obj is an array value object.
1000 @prenotnull{val}
1001 @prehot{array_obj}
1002 @postrefcountsame{array_obj}
1003
1004 @sa bt_value_array_append(): Appends a value object to a given
1005 array value object.
1006 */
1007 extern enum bt_value_status bt_value_array_append_string(
1008 struct bt_value *array_obj, const char *val);
1009
1010 /**
1011 @brief Appends an empty array value object to the array value object
1012 \p array_obj.
1013
1014 This is a convenience function which creates the underlying array value
1015 object before appending it.
1016
1017 @param[in] array_obj Array value object in which to append an
1018 empty array value object
1019 @returns Status code.
1020
1021 @prenotnull{array_obj}
1022 @pre \p array_obj is an array value object.
1023 @prehot{array_obj}
1024 @postrefcountsame{array_obj}
1025
1026 @sa bt_value_array_append(): Appends a value object to a given
1027 array value object.
1028 */
1029 extern enum bt_value_status bt_value_array_append_empty_array(
1030 struct bt_value *array_obj);
1031
1032 /**
1033 @brief Appends an empty map value object to the array value object
1034 \p array_obj.
1035
1036 This is a convenience function which creates the underlying map value
1037 object before appending it.
1038
1039 @param[in] array_obj Array value object in which to append an empty
1040 map value object.
1041 @returns Status code.
1042
1043 @prenotnull{array_obj}
1044 @pre \p array_obj is an array value object.
1045 @prehot{array_obj}
1046 @postrefcountsame{array_obj}
1047
1048 @sa bt_value_array_append(): Appends a value object to a given
1049 array value object.
1050 */
1051 extern enum bt_value_status bt_value_array_append_empty_map(
1052 struct bt_value *array_obj);
1053
1054 /**
1055 @brief Replaces the value object contained in the array value object
1056 \p array_obj at the index \p index by \p element_obj.
1057
1058 @param[in] array_obj Array value object in which to replace
1059 an element.
1060 @param[in] index Index of value object to replace in
1061 \p array_obj.
1062 @param[in] element_obj New value object at position \p index of
1063 \p array_obj.
1064 @returns Status code.
1065
1066 @prenotnull{array_obj}
1067 @prenotnull{element_obj}
1068 @pre \p array_obj is an array value object.
1069 @pre \p index is lesser than the size of \p array_obj (see
1070 bt_value_array_size()).
1071 @prehot{array_obj}
1072 @post <strong>On success, if the replaced value object is not
1073 \ref bt_value_null</strong>, its reference count is decremented.
1074 @post <strong>On success, if \p element_obj is not
1075 \ref bt_value_null</strong>, its reference count is incremented.
1076 @postrefcountsame{array_obj}
1077 */
1078 extern enum bt_value_status bt_value_array_set(struct bt_value *array_obj,
1079 uint64_t index, struct bt_value *element_obj);
1080
1081 /** @} */
1082
1083 /**
1084 @name Map value object functions
1085 @{
1086 */
1087
1088 /**
1089 @brief Creates an empty map value object.
1090
1091 @returns Created map value object on success, or \c NULL on error.
1092
1093 @postsuccessrefcountret1
1094 */
1095 extern struct bt_value *bt_value_map_create(void);
1096
1097 /**
1098 @brief Returns the size of the map value object \p map_obj, that is, the
1099 number of entries contained in \p map_obj.
1100
1101 @param[in] map_obj Map value object of which to get the size.
1102 @returns Number of entries contained in \p map_obj if the
1103 return value is 0 (empty) or a positive value,
1104 or one of #bt_value_status negative values
1105 otherwise.
1106
1107 @prenotnull{map_obj}
1108 @pre \p map_obj is a map value object.
1109 @postrefcountsame{map_obj}
1110
1111 @sa bt_value_map_is_empty(): Checks whether or not a given map value
1112 object is empty.
1113 */
1114 extern int64_t bt_value_map_size(const struct bt_value *map_obj);
1115
1116 /**
1117 @brief Checks whether or not the map value object \p map_obj is empty.
1118
1119 @param[in] map_obj Map value object to check.
1120 @returns #BT_TRUE if \p map_obj is empty.
1121
1122 @prenotnull{map_obj}
1123 @pre \p map_obj is a map value object.
1124 @postrefcountsame{map_obj}
1125
1126 @sa bt_value_map_size(): Returns the size of a given map value object.
1127 */
1128 extern bt_bool bt_value_map_is_empty(const struct bt_value *map_obj);
1129
1130 /**
1131 @brief Returns the value object associated with the key \p key within
1132 the map value object \p map_obj.
1133
1134 @param[in] map_obj Map value object of which to get an entry.
1135 @param[in] key Key of the value object to get.
1136 @returns Value object associated with the key \p key
1137 on success, or \c NULL on error.
1138
1139 @prenotnull{map_obj}
1140 @prenotnull{key}
1141 @pre \p map_obj is a map value object.
1142 @postrefcountsame{map_obj}
1143 @post <strong>On success, if the returned value object is not
1144 \ref bt_value_null</strong>, its reference count is incremented.
1145 */
1146 extern struct bt_value *bt_value_map_get(const struct bt_value *map_obj,
1147 const char *key);
1148
1149 /**
1150 @brief User function type to use with bt_value_map_foreach().
1151
1152 \p object is a <em>weak reference</em>: you \em must pass it to bt_get()
1153 if you need to keep a reference after this function returns.
1154
1155 This function \em must return #BT_TRUE to continue the map value object
1156 traversal, or #BT_FALSE to break it.
1157
1158 @param[in] key Key of map entry.
1159 @param[in] object Value object of map entry (weak reference).
1160 @param[in] data User data.
1161 @returns #BT_TRUE to continue the loop, or #BT_FALSE to break it.
1162
1163 @prenotnull{key}
1164 @prenotnull{object}
1165 @post The reference count of \p object is not lesser than what it is
1166 when the function is called.
1167 */
1168 typedef bt_bool (* bt_value_map_foreach_cb)(const char *key,
1169 struct bt_value *object, void *data);
1170
1171 /**
1172 @brief Calls a provided user function \p cb for each value object of the
1173 map value object \p map_obj.
1174
1175 The value object passed to the user function is a <b>weak reference</b>:
1176 you \em must pass it to bt_get() if you need to keep a persistent
1177 reference after the user function returns.
1178
1179 The key passed to the user function is only valid in the scope of
1180 this user function call.
1181
1182 The user function \em must return #BT_TRUE to continue the traversal of
1183 \p map_obj, or #BT_FALSE to break it.
1184
1185 @param[in] map_obj Map value object on which to iterate.
1186 @param[in] cb User function to call back.
1187 @param[in] data User data passed to the user function.
1188 @returns Status code. More
1189 specifically, #BT_VALUE_STATUS_CANCELLED is
1190 returned if the loop was cancelled by the user
1191 function.
1192
1193 @prenotnull{map_obj}
1194 @prenotnull{cb}
1195 @pre \p map_obj is a map value object.
1196 @postrefcountsame{map_obj}
1197 */
1198 extern enum bt_value_status bt_value_map_foreach(
1199 const struct bt_value *map_obj, bt_value_map_foreach_cb cb,
1200 void *data);
1201
1202 /**
1203 @brief Returns whether or not the map value object \p map_obj contains
1204 an entry mapped to the key \p key.
1205
1206 @param[in] map_obj Map value object to check.
1207 @param[in] key Key to check.
1208 @returns #BT_TRUE if \p map_obj has an entry mapped to the
1209 key \p key, or #BT_FALSE if it does not or
1210 on error.
1211
1212 @prenotnull{map_obj}
1213 @prenotnull{key}
1214 @pre \p map_obj is a map value object.
1215 @postrefcountsame{map_obj}
1216 */
1217 extern bt_bool bt_value_map_has_key(const struct bt_value *map_obj,
1218 const char *key);
1219
1220 /**
1221 @brief Inserts the value object \p element_obj mapped to the key
1222 \p key into the map value object \p map_obj.
1223
1224 If a value object is already mapped to \p key in \p map_obj, the
1225 associated value object is first put, and then replaced by
1226 \p element_obj.
1227
1228 On success, \p key is copied.
1229
1230 @param[in] map_obj Map value object in which to insert
1231 \p element_obj.
1232 @param[in] key Key (copied on success) to which the
1233 value object to insert is mapped.
1234 @param[in] element_obj Value object to insert, mapped to the
1235 key \p key.
1236 @returns Status code.
1237
1238 @prenotnull{map_obj}
1239 @prenotnull{key}
1240 @prenotnull{element_obj}
1241 @pre \p map_obj is a map value object.
1242 @prehot{map_obj}
1243 @post <strong>On success, if \p element_obj is not
1244 \ref bt_value_null</strong>, its reference count is incremented.
1245 @postrefcountsame{map_obj}
1246
1247 @sa bt_value_map_insert_bool(): Inserts a boolean raw value into a
1248 given map value object.
1249 @sa bt_value_map_insert_integer(): Inserts an integer raw value into
1250 a given map value object.
1251 @sa bt_value_map_insert_float(): Inserts a floating point number raw
1252 value into a given map value object.
1253 @sa bt_value_map_insert_string(): Inserts a string raw value into a
1254 given map value object.
1255 @sa bt_value_map_insert_empty_array(): Inserts an empty array value
1256 object into a given map value object.
1257 @sa bt_value_map_insert_empty_map(): Inserts an empty map value
1258 object into a given map value object.
1259 */
1260 extern enum bt_value_status bt_value_map_insert(
1261 struct bt_value *map_obj, const char *key,
1262 struct bt_value *element_obj);
1263
1264 /**
1265 @brief Inserts the boolean raw value \p val mapped to the key \p key
1266 into the map value object \p map_obj.
1267
1268 This is a convenience function which creates the underlying boolean
1269 value object before inserting it.
1270
1271 On success, \p key is copied.
1272
1273 @param[in] map_obj Map value object in which to insert \p val.
1274 @param[in] key Key (copied on success) to which the boolean
1275 value object to insert is mapped.
1276 @param[in] val Boolean raw value to insert, mapped to
1277 the key \p key.
1278 @returns Status code.
1279
1280 @prenotnull{map_obj}
1281 @prenotnull{key}
1282 @pre \p map_obj is a map value object.
1283 @prehot{map_obj}
1284 @postrefcountsame{map_obj}
1285
1286 @sa bt_value_map_insert(): Inserts a value object into a given map
1287 value object.
1288 */
1289 extern enum bt_value_status bt_value_map_insert_bool(
1290 struct bt_value *map_obj, const char *key, bt_bool val);
1291
1292 /**
1293 @brief Inserts the integer raw value \p val mapped to the key \p key
1294 into the map value object \p map_obj.
1295
1296 This is a convenience function which creates the underlying integer
1297 value object before inserting it.
1298
1299 On success, \p key is copied.
1300
1301 @param[in] map_obj Map value object in which to insert \p val.
1302 @param[in] key Key (copied on success) to which the integer
1303 value object to insert is mapped.
1304 @param[in] val Integer raw value to insert, mapped to
1305 the key \p key.
1306 @returns Status code.
1307
1308 @prenotnull{map_obj}
1309 @prenotnull{key}
1310 @pre \p map_obj is a map value object.
1311 @prehot{map_obj}
1312 @postrefcountsame{map_obj}
1313
1314 @sa bt_value_map_insert(): Inserts a value object into a given map
1315 value object.
1316 */
1317 extern enum bt_value_status bt_value_map_insert_integer(
1318 struct bt_value *map_obj, const char *key, int64_t val);
1319
1320 /**
1321 @brief Inserts the floating point number raw value \p val mapped to
1322 the key \p key into the map value object \p map_obj.
1323
1324 This is a convenience function which creates the underlying floating
1325 point number value object before inserting it.
1326
1327 On success, \p key is copied.
1328
1329 @param[in] map_obj Map value object in which to insert \p val.
1330 @param[in] key Key (copied on success) to which the floating
1331 point number value object to insert is mapped.
1332 @param[in] val Floating point number raw value to insert,
1333 mapped to the key \p key.
1334 @returns Status code.
1335
1336 @prenotnull{map_obj}
1337 @prenotnull{key}
1338 @pre \p map_obj is a map value object.
1339 @prehot{map_obj}
1340 @postrefcountsame{map_obj}
1341
1342 @sa bt_value_map_insert(): Inserts a value object into a given map
1343 value object.
1344 */
1345 extern enum bt_value_status bt_value_map_insert_float(
1346 struct bt_value *map_obj, const char *key, double val);
1347
1348 /**
1349 @brief Inserts the string raw value \p val mapped to the key \p key
1350 into the map value object \p map_obj.
1351
1352 This is a convenience function which creates the underlying string value
1353 object before inserting it.
1354
1355 On success, \p val and \p key are copied.
1356
1357 @param[in] map_obj Map value object in which to insert \p val.
1358 @param[in] key Key (copied on success) to which the string
1359 value object to insert is mapped.
1360 @param[in] val String raw value to insert (copied on success),
1361 mapped to the key \p key.
1362 @returns Status code.
1363
1364 @prenotnull{map_obj}
1365 @prenotnull{key}
1366 @prenotnull{val}
1367 @pre \p map_obj is a map value object.
1368 @prehot{map_obj}
1369 @postrefcountsame{map_obj}
1370
1371 @sa bt_value_map_insert(): Inserts a value object into a given map
1372 value object.
1373 */
1374 extern enum bt_value_status bt_value_map_insert_string(
1375 struct bt_value *map_obj, const char *key, const char *val);
1376
1377 /**
1378 @brief Inserts an empty array value object mapped to the key \p key
1379 into the map value object \p map_obj.
1380
1381 This is a convenience function which creates the underlying array value
1382 object before inserting it.
1383
1384 On success, \p key is copied.
1385
1386 @param[in] map_obj Map value object in which to insert an empty
1387 array value object.
1388 @param[in] key Key (copied on success) to which the empty array
1389 value object to insert is mapped.
1390 @returns Status code.
1391
1392 @prenotnull{map_obj}
1393 @prenotnull{key}
1394 @pre \p map_obj is a map value object.
1395 @prehot{map_obj}
1396 @postrefcountsame{map_obj}
1397
1398 @sa bt_value_map_insert(): Inserts a value object into a given map
1399 value object.
1400 */
1401 extern enum bt_value_status bt_value_map_insert_empty_array(
1402 struct bt_value *map_obj, const char *key);
1403
1404 /**
1405 @brief Inserts an empty map value object mapped to the key \p key into
1406 the map value object \p map_obj.
1407
1408 This is a convenience function which creates the underlying map value
1409 object before inserting it.
1410
1411 On success, \p key is copied.
1412
1413 @param[in] map_obj Map value object in which to insert an empty
1414 map object.
1415 @param[in] key Key (copied on success) to which the empty map
1416 value object to insert is mapped.
1417 @returns Status code.
1418
1419 @prenotnull{map_obj}
1420 @prenotnull{key}
1421 @pre \p map_obj is a map value object.
1422 @prehot{map_obj}
1423 @postrefcountsame{map_obj}
1424
1425 @sa bt_value_map_insert(): Inserts a value object into a given map
1426 value object.
1427 */
1428 extern enum bt_value_status bt_value_map_insert_empty_map(
1429 struct bt_value *map_obj, const char *key);
1430
1431 /**
1432 @brief Creates a copy of the base map value object \p base_map_obj
1433 superficially extended with the entries of the extension map
1434 value object \p extension_map_obj.
1435
1436 This function creates a superficial extension of \p base_map_obj with
1437 \p extension_map_obj by adding new entries to it and replacing the
1438 ones that share the keys in the extension object. The extension is
1439 \em superficial because it does not merge internal array and map
1440 value objects.
1441
1442 For example, consider the following \p base_map_obj (JSON representation):
1443
1444 @verbatim
1445 {
1446 "hello": 23,
1447 "code": -17,
1448 "em": false,
1449 "return": [5, 6, null]
1450 }
1451 @endverbatim
1452
1453 and the following \p extension_map_obj (JSON representation):
1454
1455 @verbatim
1456 {
1457 "comma": ",",
1458 "code": 22,
1459 "return": 17.88
1460 }
1461 @endverbatim
1462
1463 The extended object is (JSON representation):
1464
1465 @verbatim
1466 {
1467 "hello": 23,
1468 "code": 22,
1469 "em": false,
1470 "return": 17.88,
1471 "comma": ","
1472 }
1473 @endverbatim
1474
1475 @param[in] base_map_obj Base map value object with initial
1476 entries.
1477 @param[in] extension_map_obj Extension map value object containing
1478 the entries to add to or replace in
1479 \p base_map_obj.
1480 @returns Created extended map value object, or
1481 \c NULL on error.
1482
1483 @prenotnull{base_map_obj}
1484 @prenotnull{extension_map_obj}
1485 @pre \p base_map_obj is a map value object.
1486 @pre \p extension_map_obj is a map value object.
1487 @postrefcountsame{base_map_obj}
1488 @postrefcountsame{extension_map_obj}
1489 @postsuccessrefcountret1
1490 */
1491 extern struct bt_value *bt_value_map_extend(struct bt_value *base_map_obj,
1492 struct bt_value *extension_map_obj);
1493
1494 /** @} */
1495
1496 /** @} */
1497
1498 #ifdef __cplusplus
1499 }
1500 #endif
1501
1502 #endif /* BABELTRACE_VALUES_H */
This page took 0.060121 seconds and 4 git commands to generate.