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