ref.h: fix doc
[babeltrace.git] / include / babeltrace / values.h
CommitLineData
dac5c838
PP
1#ifndef _BABELTRACE_VALUES_H
2#define _BABELTRACE_VALUES_H
3
4/*
5 * Babeltrace - Value objects
6 *
7 * Copyright (c) 2015 EfficiOS Inc. and Linux Foundation
8 * Copyright (c) 2015 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/**
30 * @file values.h
31 * @brief Value objects
32 *
33 * This is a set of value objects. The following functions allow you
34 * to create, modify, and destroy:
35 *
36 * - \link bt_value_null null value objects\endlink
37 * - \link bt_value_bool_create() boolean value objects\endlink
38 * - \link bt_value_integer_create() integer value objects\endlink
39 * - \link bt_value_float_create() floating point number
40 * value objects\endlink
41 * - \link bt_value_string_create() string value objects\endlink
42 * - \link bt_value_array_create() array value objects\endlink,
43 * containing zero or more value objects
44 * - \link bt_value_map_create() map value objects\endlink, mapping
45 * string keys to value objects
46 *
47 * All the value object types above, except for null values (which
48 * always point to the same \link bt_value_null singleton\endlink), have
49 * a reference count property. Once a value object is created, its
50 * reference count is set to 1. When \link bt_value_array_append()
51 * appending a value to an array value object\endlink, or
52 * \link bt_value_map_insert() inserting a value object into a map
53 * value object\endlink, its reference count is incremented, as well as
54 * when getting a value object back from those structures. The
83509119
JG
55 * bt_get() and bt_put() functions are to be used to handle reference counting
56 * Once you are done with a value object, pass it to bt_put().
dac5c838
PP
57 *
58 * Most functions of this API return a status code, one of the values in
59 * #bt_value_status.
60 *
61 * You can create a deep copy of any value object using the
62 * bt_value_copy() function. You can compare two given value objects
63 * using bt_value_compare().
64 *
65 * Any value object may be frozen using bt_value_freeze(). You may get
66 * the raw value of a frozen value object, but you cannot modify it.
67 * Reference counting still works on frozen value objects. You may also
68 * copy and compare frozen value objects.
69 *
70 * @author Philippe Proulx <pproulx@efficios.com>
71 * @bug No known bugs
72 */
73
74#include <stdint.h>
75#include <stdbool.h>
76#include <stddef.h>
83509119 77#include <babeltrace/ref.h>
dac5c838
PP
78
79#ifdef __cplusplus
80extern "C" {
81#endif
82
83/**
84 * Value object type.
85 */
86enum bt_value_type {
87 /** Unknown value object, used as an error code. */
88 BT_VALUE_TYPE_UNKNOWN = -1,
89
90 /** Null value object. */
91 BT_VALUE_TYPE_NULL = 0,
92
93 /** Boolean value object (holds \c true or \c false). */
94 BT_VALUE_TYPE_BOOL = 1,
95
96 /** Integer value object (holds a signed 64-bit integer raw value). */
97 BT_VALUE_TYPE_INTEGER = 2,
98
99 /** Floating point number value object (holds a \c double raw value). */
100 BT_VALUE_TYPE_FLOAT = 3,
101
102 /** String value object. */
103 BT_VALUE_TYPE_STRING = 4,
104
105 /** Array value object. */
106 BT_VALUE_TYPE_ARRAY = 5,
107
108 /** Map value object. */
109 BT_VALUE_TYPE_MAP = 6,
110};
111
112/**
113 * Status codes.
114 */
115enum bt_value_status {
116 /** Value object cannot be altered because it's frozen. */
117 BT_VALUE_STATUS_FROZEN = -4,
118
119 /** Operation cancelled. */
120 BT_VALUE_STATUS_CANCELLED = -3,
121
122 /** Invalid arguments. */
123 /* -22 for compatibility with -EINVAL */
124 BT_VALUE_STATUS_INVAL = -22,
125
126 /** General error. */
127 BT_VALUE_STATUS_ERROR = -1,
128
129 /** Okay, no error. */
130 BT_VALUE_STATUS_OK = 0,
131};
132
133/**
134 * Value object.
135 */
136struct bt_value;
137
138/**
139 * The null value object singleton.
140 *
141 * Use this everytime you need a null value object.
142 *
143 * The null value object singleton has no reference count; there's only
144 * one. You may directly compare any value object to the null value
145 * object singleton to find out if it's a null value object, or
146 * otherwise use bt_value_is_null().
147 *
148 * The null value object singleton is always frozen (see
149 * bt_value_freeze() and bt_value_is_frozen()).
150 *
151 * Functions of this API return this when the value object is actually a
152 * null value object (of type #BT_VALUE_TYPE_NULL), whereas \c NULL
153 * means an error of some sort.
154 */
155extern struct bt_value *bt_value_null;
156
157/**
158 * User function type for bt_value_map_foreach().
159 *
160 * \p object is a \em weak reference; you must pass it to
83509119 161 * bt_get() to get your own reference.
dac5c838
PP
162 *
163 * Return \c true to continue the loop, or \c false to break it.
164 *
165 * @param key Key of map entry
166 * @param object Value object of map entry (weak reference)
167 * @param data User data
168 * @returns \c true to continue the loop
169 */
170typedef bool (* bt_value_map_foreach_cb)(const char *key,
171 struct bt_value *object, void *data);
172
dac5c838
PP
173/**
174 * Recursively freezes the value object \p object.
175 *
176 * A frozen value object cannot be modified; it is considered immutable.
177 * Reference counting still works on a frozen value object though: you
83509119 178 * may pass a frozen value object to bt_get() and bt_put().
dac5c838
PP
179 *
180 * @param object Value object to freeze
181 * @returns One of #bt_value_status values; if \p object
182 * is already frozen, though, #BT_VALUE_STATUS_OK
183 * is returned anyway (i.e. this function never
184 * returns #BT_VALUE_STATUS_FROZEN)
185 *
186 * @see bt_value_is_frozen()
187 */
188extern enum bt_value_status bt_value_freeze(struct bt_value *object);
189
190/**
191 * Checks whether \p object is frozen or not.
192 *
193 * @param object Value object to check
194 * @returns \c true if \p object is frozen
195 *
196 * @see bt_value_freeze()
197 */
198extern bool bt_value_is_frozen(const struct bt_value *object);
199
200/**
201 * Returns the type of \p object.
202 *
203 * @param object Value object of which to get the type
204 * @returns Value object's type, or #BT_VALUE_TYPE_UNKNOWN
205 * on error
206 *
207 * @see #bt_value_type (value object types)
208 * @see bt_value_is_null()
209 * @see bt_value_is_bool()
210 * @see bt_value_is_integer()
211 * @see bt_value_is_float()
212 * @see bt_value_is_string()
213 * @see bt_value_is_array()
214 * @see bt_value_is_map()
215 */
216extern enum bt_value_type bt_value_get_type(const struct bt_value *object);
217
218/**
219 * Checks whether \p object is a null value object. The only valid null
220 * value object is \ref bt_value_null.
221 *
222 * @param object Value object to check
223 * @returns \c true if \p object is a null value object
224 *
225 * @see bt_value_get_type()
226 */
227static inline
228bool bt_value_is_null(const struct bt_value *object)
229{
230 return bt_value_get_type(object) == BT_VALUE_TYPE_NULL;
231}
232
233/**
234 * Checks whether \p object is a boolean value object.
235 *
236 * @param object Value object to check
237 * @returns \c true if \p object is a boolean value object
238 *
239 * @see bt_value_get_type()
240 */
241static inline
242bool bt_value_is_bool(const struct bt_value *object)
243{
244 return bt_value_get_type(object) == BT_VALUE_TYPE_BOOL;
245}
246
247/**
248 * Checks whether \p object is an integer value object.
249 *
250 * @param object Value object to check
251 * @returns \c true if \p object is an integer value object
252 *
253 * @see bt_value_get_type()
254 */
255static inline
256bool bt_value_is_integer(const struct bt_value *object)
257{
258 return bt_value_get_type(object) == BT_VALUE_TYPE_INTEGER;
259}
260
261/**
262 * Checks whether \p object is a floating point number value object.
263 *
264 * @param object Value object to check
265 * @returns \c true if \p object is a floating point
266 * number value object
267 *
268 * @see bt_value_get_type()
269 */
270static inline
271bool bt_value_is_float(const struct bt_value *object)
272{
273 return bt_value_get_type(object) == BT_VALUE_TYPE_FLOAT;
274}
275
276/**
277 * Checks whether \p object is a string value object.
278 *
279 * @param object Value object to check
280 * @returns \c true if \p object is a string value object
281 *
282 * @see bt_value_get_type()
283 */
284static inline
285bool bt_value_is_string(const struct bt_value *object)
286{
287 return bt_value_get_type(object) == BT_VALUE_TYPE_STRING;
288}
289
290/**
291 * Checks whether \p object is an array value object.
292 *
293 * @param object Value object to check
294 * @returns \c true if \p object is an array value object
295 *
296 * @see bt_value_get_type()
297 */
298static inline
299bool bt_value_is_array(const struct bt_value *object)
300{
301 return bt_value_get_type(object) == BT_VALUE_TYPE_ARRAY;
302}
303
304/**
305 * Checks whether \p object is a map value object.
306 *
307 * @param object Value object to check
308 * @returns \c true if \p object is a map value object
309 *
310 * @see bt_value_get_type()
311 */
312static inline
313bool bt_value_is_map(const struct bt_value *object)
314{
315 return bt_value_get_type(object) == BT_VALUE_TYPE_MAP;
316}
317
318/**
319 * Creates a boolean value object. The created boolean value object's
320 * initial raw value is \c false.
321 *
322 * The created value object's reference count is set to 1.
323 *
324 * @returns Created value object on success, or \c NULL on error
325 *
326 * @see bt_value_bool_create_init() (creates an initialized
327 * boolean value object)
328 */
329extern struct bt_value *bt_value_bool_create(void);
330
331/**
332 * Creates a boolean value object with its initial raw value set to
333 * \p val.
334 *
335 * The created value object's reference count is set to 1.
336 *
337 * @param val Initial raw value
338 * @returns Created value object on success, or \c NULL on error
339 */
340extern struct bt_value *bt_value_bool_create_init(bool val);
341
342/**
343 * Creates an integer value object. The created integer value object's
344 * initial raw value is 0.
345 *
346 * The created value object's reference count is set to 1.
347 *
348 * @returns Created value object on success, or \c NULL on error
349 *
350 * @see bt_value_integer_create_init() (creates an initialized
351 * integer value object)
352 */
353extern struct bt_value *bt_value_integer_create(void);
354
355/**
356 * Creates an integer value object with its initial raw value set to
357 * \p val.
358 *
359 * The created value object's reference count is set to 1.
360 *
361 * @param val Initial raw value
362 * @returns Created value object on success, or \c NULL on error
363 */
364extern struct bt_value *bt_value_integer_create_init(int64_t val);
365
366/**
367 * Creates a floating point number value object. The created floating
368 * point number value object's initial raw value is 0.
369 *
370 * The created value object's reference count is set to 1.
371 *
372 * @returns Created value object on success, or \c NULL on error
373 *
374 * @see bt_value_float_create_init() (creates an initialized floating
375 * point number value object)
376 */
377extern struct bt_value *bt_value_float_create(void);
378
379/**
380 * Creates a floating point number value object with its initial raw
381 * value set to \p val.
382 *
383 * The created value object's reference count is set to 1.
384 *
385 * @param val Initial raw value
386 * @returns Created value object on success, or \c NULL on error
387 */
388extern struct bt_value *bt_value_float_create_init(double val);
389
390/**
391 * Creates a string value object. The string value object is initially
392 * empty.
393 *
394 * The created value object's reference count is set to 1.
395 *
396 * @returns Created value object on success, or \c NULL on error
397 *
398 * @see bt_value_string_create_init() (creates an initialized
399 * string value object)
400 */
401extern struct bt_value *bt_value_string_create(void);
402
403/**
404 * Creates a string value object with its initial raw value set to
405 * \p val.
406 *
407 * On success, \p val is \em copied.
408 *
409 * The created value object's reference count is set to 1.
410 *
411 * @param val Initial raw value (copied on success)
412 * @returns Created value object on success, or \c NULL on error
413 */
414extern struct bt_value *bt_value_string_create_init(const char *val);
415
416/**
417 * Creates an empty array value object.
418 *
419 * The created value object's reference count is set to 1.
420 *
421 * @returns Created value object on success, or \c NULL on error
422 */
423extern struct bt_value *bt_value_array_create(void);
424
425/**
426 * Creates an empty map value object.
427 *
428 * The created value object's reference count is set to 1.
429 *
430 * @returns Created value object on success, or \c NULL on error
431 */
432extern struct bt_value *bt_value_map_create(void);
433
434/**
435 * Gets the boolean raw value of the boolean value object \p bool_obj.
436 *
437 * @param bool_obj Boolean value object
438 * @param val Returned boolean raw value
439 * @returns One of #bt_value_status values
440 *
441 * @see bt_value_bool_set()
442 */
443extern enum bt_value_status bt_value_bool_get(
444 const struct bt_value *bool_obj, bool *val);
445
446/**
447 * Sets the boolean raw value of the boolean value object \p bool_obj
448 * to \p val.
449 *
450 * @param bool_obj Boolean value object
451 * @param val New boolean raw value
452 * @returns One of #bt_value_status values
453 *
454 * @see bt_value_bool_get()
455 */
456extern enum bt_value_status bt_value_bool_set(struct bt_value *bool_obj,
457 bool val);
458
459/**
460 * Gets the integer raw value of the integer value object
461 * \p integer_obj.
462 *
463 * @param integer_obj Integer value object
464 * @param val Returned integer raw value
465 * @returns One of #bt_value_status values
466 *
467 * @see bt_value_integer_set()
468 */
469extern enum bt_value_status bt_value_integer_get(
470 const struct bt_value *integer_obj, int64_t *val);
471
472/**
473 * Sets the integer raw value of the integer value object \p integer_obj
474 * to \p val.
475 *
476 * @param integer_obj Integer value object
477 * @param val New integer raw value
478 * @returns One of #bt_value_status values
479 *
480 * @see bt_value_integer_get()
481 */
482extern enum bt_value_status bt_value_integer_set(
483 struct bt_value *integer_obj, int64_t val);
484
485/**
486 * Gets the floating point number raw value of the floating point number
487 * value object \p float_obj.
488 *
489 * @param float_obj Floating point number value object
490 * @param val Returned floating point number raw value
491 * @returns One of #bt_value_status values
492 *
493 * @see bt_value_float_set()
494 */
495extern enum bt_value_status bt_value_float_get(
496 const struct bt_value *float_obj, double *val);
497
498/**
499 * Sets the floating point number raw value of the floating point number
500 * value object \p float_obj to \p val.
501 *
502 * @param float_obj Floating point number value object
503 * @param val New floating point number raw value
504 * @returns One of #bt_value_status values
505 *
506 * @see bt_value_float_get()
507 */
508extern enum bt_value_status bt_value_float_set(
509 struct bt_value *float_obj, double val);
510
511/**
512 * Gets the string raw value of the string value object \p string_obj.
513 * The returned string is valid as long as this value object exists and
514 * is not modified. The ownership of the returned string is \em not
515 * transferred to the caller.
516 *
517 * @param string_obj String value object
518 * @param val Returned string raw value
519 * @returns One of #bt_value_status values
520 *
521 * @see bt_value_string_set()
522 */
523extern enum bt_value_status bt_value_string_get(
524 const struct bt_value *string_obj, const char **val);
525
526/**
527 * Sets the string raw value of the string value object \p string_obj to
528 * \p val.
529 *
530 * On success, \p val is \em copied.
531 *
532 * @param string_obj String value object
533 * @param val New string raw value (copied on successf)
534 * @returns One of #bt_value_status values
535 *
536 * @see bt_value_string_get()
537 */
538extern enum bt_value_status bt_value_string_set(struct bt_value *string_obj,
539 const char *val);
540
541/**
542 * Gets the size of the array value object \p array_obj, that is, the
543 * number of value objects contained in \p array_obj.
544 *
545 * @param array_obj Array value object
546 * @returns Array size if the return value is 0 (empty) or a
547 * positive value, or one of
548 * #bt_value_status negative values otherwise
549 *
550 * @see bt_value_array_is_empty()
551 */
552extern int bt_value_array_size(const struct bt_value *array_obj);
553
554/**
555 * Returns \c true if the array value object \p array_obj is empty.
556 *
557 * @param array_obj Array value object
558 * @returns \c true if \p array_obj is empty
559 *
560 * @see bt_value_array_size()
561 */
562extern bool bt_value_array_is_empty(const struct bt_value *array_obj);
563
564/**
565 * Gets the value object of the array value object \p array_obj at the
566 * index \p index.
567 *
568 * The returned value object's reference count is incremented, unless
569 * it's a null value object.
570 *
571 * @param array_obj Array value object
572 * @param index Index of value object to get
573 * @returns Value object at index \p index on
574 * success, or \c NULL on error
575 */
576extern struct bt_value *bt_value_array_get(const struct bt_value *array_obj,
577 size_t index);
578
579/**
580 * Appends the value object \p element_obj to the array value
581 * object \p array_obj.
582 *
583 * The appended value object's reference count is incremented, unless
584 * it's a null object.
585 *
586 * @param array_obj Array value object
587 * @param element_obj Value object to append
588 * @returns One of #bt_value_status values
589 *
590 * @see bt_value_array_append_bool()
591 * @see bt_value_array_append_integer()
592 * @see bt_value_array_append_float()
593 * @see bt_value_array_append_string()
5b79e8bf
PP
594 * @see bt_value_array_append_empty_array()
595 * @see bt_value_array_append_empty_map()
dac5c838
PP
596 */
597extern enum bt_value_status bt_value_array_append(struct bt_value *array_obj,
598 struct bt_value *element_obj);
599
600/**
601 * Appends the boolean raw value \p val to the array value object
602 * \p array_obj. This is a convenience function which creates the
603 * underlying boolean value object before appending it.
604 *
605 * The created boolean value object's reference count is set to 1.
606 *
607 * @param array_obj Array value object
608 * @param val Boolean raw value to append
609 * @returns One of #bt_value_status values
610 *
611 * @see bt_value_array_append()
612 */
613extern enum bt_value_status bt_value_array_append_bool(
614 struct bt_value *array_obj, bool val);
615
616/**
617 * Appends the integer raw value \p val to the array value object
618 * \p array_obj. This is a convenience function which creates the
619 * underlying integer value object before appending it.
620 *
621 * The created integer value object's reference count is set to 1.
622 *
623 * @param array_obj Array value object
624 * @param val Integer raw value to append
625 * @returns One of #bt_value_status values
626 *
627 * @see bt_value_array_append()
628 */
629extern enum bt_value_status bt_value_array_append_integer(
630 struct bt_value *array_obj, int64_t val);
631
632/**
633 * Appends the floating point number raw value \p val to the array value
634 * object \p array_obj. This is a convenience function which creates the
635 * underlying floating point number value object before appending it.
636 *
637 * The created floating point number value object's reference count is
638 * set to 1.
639 *
640 * @param array_obj Array value object
641 * @param val Floating point number raw value to append
642 * @returns One of #bt_value_status values
643 *
644 * @see bt_value_array_append()
645 */
646extern enum bt_value_status bt_value_array_append_float(
647 struct bt_value *array_obj, double val);
648
649/**
650 * Appends the string raw value \p val to the array value object
651 * \p array_obj. This is a convenience function which creates the
652 * underlying string value object before appending it.
653 *
654 * On success, \p val is \em copied.
655 *
656 * The created string value object's reference count is set to 1.
657 *
658 * @param array_obj Array value object
659 * @param val String raw value to append (copied on success)
660 * @returns One of #bt_value_status values
661 *
662 * @see bt_value_array_append()
663 */
664extern enum bt_value_status bt_value_array_append_string(
665 struct bt_value *array_obj, const char *val);
666
667/**
668 * Appends an empty array value object to the array value object
669 * \p array_obj. This is a convenience function which creates the
670 * underlying array value object before appending it.
671 *
672 * The created array value object's reference count is set to 1.
673 *
674 * @param array_obj Array value object
675 * @returns One of #bt_value_status values
676 *
677 * @see bt_value_array_append()
678 */
5b79e8bf 679extern enum bt_value_status bt_value_array_append_empty_array(
dac5c838
PP
680 struct bt_value *array_obj);
681
682/**
683 * Appends an empty map value object to the array value object
684 * \p array_obj. This is a convenience function which creates the
685 * underlying map value object before appending it.
686 *
687 * The created map value object's reference count is set to 1.
688 *
689 * @param array_obj Array value object
690 * @returns One of #bt_value_status values
691 *
692 * @see bt_value_array_append()
693 */
5b79e8bf 694extern enum bt_value_status bt_value_array_append_empty_map(
dac5c838
PP
695 struct bt_value *array_obj);
696
697/**
698 * Replaces the value object at index \p index of the array
699 * value object \p array_obj by \p element_obj.
700 *
701 * The replaced value object's reference count is decremented, unless
702 * it's a null value object. The reference count of \p element_obj is
703 * incremented, unless it's a null value object.
704 *
705 * @param array_obj Array value object
706 * @param index Index of value object to replace
707 * @param element_obj New value object at position \p index of
708 * \p array_obj
709 * @returns One of #bt_value_status values
710 */
711extern enum bt_value_status bt_value_array_set(struct bt_value *array_obj,
712 size_t index, struct bt_value *element_obj);
713
714/**
715 * Gets the size of a map value object, that is, the number of entries
716 * contained in a map value object.
717 *
718 * @param map_obj Map value object
719 * @returns Map size if the return value is 0 (empty) or a
720 * positive value, or one of
721 * #bt_value_status negative values otherwise
722 *
723 * @see bt_value_map_is_empty()
724 */
725extern int bt_value_map_size(const struct bt_value *map_obj);
726
727/**
728 * Returns \c true if the map value object \p map_obj is empty.
729 *
730 * @param map_obj Map value object
731 * @returns \c true if \p map_obj is empty
732 *
733 * @see bt_value_map_size()
734 */
735extern bool bt_value_map_is_empty(const struct bt_value *map_obj);
736
737/**
738 * Gets the value object associated with the key \p key within the
739 * map value object \p map_obj.
740 *
741 * The returned value object's reference count is incremented, unless
742 * it's a null value object.
743 *
744 * @param map_obj Map value object
745 * @param key Key of the value object to get
746 * @returns Value object associated with the key \p key
747 * on success, or \c NULL on error
748 */
749extern struct bt_value *bt_value_map_get(const struct bt_value *map_obj,
750 const char *key);
751
752/**
753 * Calls a provided user function \p cb for each value object of the map
754 * value object \p map_obj.
755 *
756 * The value object passed to the user function is a
83509119
JG
757 * <b>weak reference</b>: you must call bt_get() on it to obtain your own
758 * reference.
dac5c838
PP
759 *
760 * The key passed to the user function is only valid in the scope of
761 * this user function call.
762 *
763 * The user function must return \c true to continue the loop, or
764 * \c false to break it.
765 *
766 * @param map_obj Map value object
767 * @param cb User function to call back
768 * @param data User data passed to the user function
769 * @returns One of #bt_value_status values; more
770 * specifically, #BT_VALUE_STATUS_CANCELLED is
771 * returned if the loop was cancelled by the user
772 * function
773 */
774extern enum bt_value_status bt_value_map_foreach(
775 const struct bt_value *map_obj, bt_value_map_foreach_cb cb,
776 void *data);
777
778/**
779 * Returns whether or not the map value object \p map_obj contains the
780 * key \p key.
781 *
782 * @param map_obj Map value object
783 * @param key Key to check
784 * @returns \c true if \p map_obj contains the key \p key,
785 * or \c false if it doesn't have \p key or
786 * on error
787 */
788extern bool bt_value_map_has_key(const struct bt_value *map_obj,
789 const char *key);
790
791/**
792 * Inserts the value object \p element_obj associated with the key
793 * \p key into the map value object \p map_obj. If \p key exists in
794 * \p map_obj, the associated value object is first put, and then
795 * replaced by \p element_obj.
796 *
797 * On success, \p key is \em copied.
798 *
799 * The inserted value object's reference count is incremented, unless
800 * it's a null value object.
801 *
802 * @param map_obj Map value object
803 * @param key Key (copied on success) of value object to insert
804 * @param element_obj Value object to insert, associated with the
805 * key \p key
806 * @returns One of #bt_value_status values
807 *
808 * @see bt_value_map_insert_bool()
809 * @see bt_value_map_insert_integer()
810 * @see bt_value_map_insert_float()
811 * @see bt_value_map_insert_string()
5b79e8bf
PP
812 * @see bt_value_map_insert_empty_array()
813 * @see bt_value_map_insert_empty_map()
dac5c838
PP
814 */
815extern enum bt_value_status bt_value_map_insert(
816 struct bt_value *map_obj, const char *key,
817 struct bt_value *element_obj);
818
819/**
820 * Inserts the boolean raw value \p val associated with the key \p key
821 * into the map value object \p map_obj. This is a convenience function
822 * which creates the underlying boolean value object before
823 * inserting it.
824 *
825 * On success, \p key is \em copied.
826 *
827 * The created boolean value object's reference count is set to 1.
828 *
829 * @param map_obj Map value object
830 * @param key Key (copied on success) of boolean value object
831 * to insert
832 * @param val Boolean raw value to insert, associated with
833 * the key \p key
834 * @returns One of #bt_value_status values
835 *
836 * @see bt_value_map_insert()
837 */
838extern enum bt_value_status bt_value_map_insert_bool(
839 struct bt_value *map_obj, const char *key, bool val);
840
841/**
842 * Inserts the integer raw value \p val associated with the key \p key
843 * into the map value object \p map_obj. This is a convenience function
844 * which creates the underlying integer value object before inserting it.
845 *
846 * On success, \p key is \em copied.
847 *
848 * The created integer value object's reference count is set to 1.
849 *
850 * @param map_obj Map value object
851 * @param key Key (copied on success) of integer value object
852 * to insert
853 * @param val Integer raw value to insert, associated with
854 * the key \p key
855 * @returns One of #bt_value_status values
856 *
857 * @see bt_value_map_insert()
858 */
859extern enum bt_value_status bt_value_map_insert_integer(
860 struct bt_value *map_obj, const char *key, int64_t val);
861
862/**
863 * Inserts the floating point number raw value \p val associated with
864 * the key \p key into the map value object \p map_obj. This is a
865 * convenience function which creates the underlying floating point
866 * number value object before inserting it.
867 *
868 * On success, \p key is \em copied.
869 *
870 * The created floating point number value object's reference count is
871 * set to 1.
872 *
873 * @param map_obj Map value object
874 * @param key Key (copied on success) of floating point number
875 * value object to insert
876 * @param val Floating point number raw value to insert,
877 * associated with the key \p key
878 * @returns One of #bt_value_status values
879 *
880 * @see bt_value_map_insert()
881 */
882extern enum bt_value_status bt_value_map_insert_float(
883 struct bt_value *map_obj, const char *key, double val);
884
885/**
886 * Inserts the string raw value \p val associated with the key \p key
887 * into the map value object \p map_obj. This is a convenience function
888 * which creates the underlying string value object before inserting it.
889 *
890 * On success, \p val and \p key are \em copied.
891 *
892 * The created string value object's reference count is set to 1.
893 *
894 * @param map_obj Map value object
895 * @param key Key (copied on success) of string value object
896 * to insert
897 * @param val String raw value to insert (copied on success),
898 * associated with the key \p key
899 * @returns One of #bt_value_status values
900 *
901 * @see bt_value_map_insert()
902 */
903extern enum bt_value_status bt_value_map_insert_string(
904 struct bt_value *map_obj, const char *key, const char *val);
905
906/**
907 * Inserts an empty array value object associated with the key \p key
908 * into the map value object \p map_obj. This is a convenience function
909 * which creates the underlying array value object before inserting it.
910 *
911 * On success, \p key is \em copied.
912 *
913 * The created array value object's reference count is set to 1.
914 *
915 * @param map_obj Map value object
916 * @param key Key (copied on success) of empty array value
917 * object to insert
918 * @returns One of #bt_value_status values
919 *
920 * @see bt_value_map_insert()
921 */
5b79e8bf 922extern enum bt_value_status bt_value_map_insert_empty_array(
dac5c838
PP
923 struct bt_value *map_obj, const char *key);
924
925/**
926 * Inserts an empty map value object associated with the key \p key into
927 * the map value object \p map_obj. This is a convenience function which
928 * creates the underlying map value object before inserting it.
929 *
930 * On success, \p key is \em copied.
931 *
932 * The created map value object's reference count is set to 1.
933 *
934 * @param map_obj Map value object
935 * @param key Key (copied on success) of empty map value
936 * object to insert
937 * @returns One of #bt_value_status values
938 *
939 * @see bt_value_map_insert()
940 */
5b79e8bf 941extern enum bt_value_status bt_value_map_insert_empty_map(
dac5c838
PP
942 struct bt_value *map_obj, const char *key);
943
944/**
945 * Creates a deep copy of the value object \p object.
946 *
947 * The created value object's reference count is set to 1, unless
948 * \p object is a null value object.
949 *
950 * Copying a frozen value object is allowed: the resulting copy is
951 * \em not frozen.
952 *
953 * @param object Value object to copy
954 * @returns Deep copy of \p object on success, or \c NULL
955 * on error
956 */
957extern struct bt_value *bt_value_copy(const struct bt_value *object);
958
959/**
960 * Compares the value objects \p object_a and \p object_b and returns
961 * \c true if they have the same \em content (raw values).
962 *
963 * @param object_a Value object A
964 * @param object_b Value object B
965 * @returns \c true if \p object_a and \p object_b have the
966 * same content, or \c false if they differ or on
967 * error
968 */
969extern bool bt_value_compare(const struct bt_value *object_a,
970 const struct bt_value *object_b);
971
972#ifdef __cplusplus
973}
974#endif
975
976#endif /* _BABELTRACE_VALUES_H */
This page took 0.078762 seconds and 4 git commands to generate.