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