Commit | Line | Data |
---|---|---|
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 | |
80 | extern "C" { | |
81 | #endif | |
82 | ||
83 | /** | |
84 | * Value object type. | |
85 | */ | |
86 | enum 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 | */ | |
115 | enum 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 | */ | |
136 | struct 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 | */ | |
155 | extern 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 | */ | |
170 | typedef 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 | */ | |
188 | extern 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 | */ | |
198 | extern 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 | */ | |
216 | extern 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 | */ | |
227 | static inline | |
228 | bool 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 | */ | |
241 | static inline | |
242 | bool 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 | */ | |
255 | static inline | |
256 | bool 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 | */ | |
270 | static inline | |
271 | bool 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 | */ | |
284 | static inline | |
285 | bool 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 | */ | |
298 | static inline | |
299 | bool 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 | */ | |
312 | static inline | |
313 | bool 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 | */ | |
329 | extern 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 | */ | |
340 | extern 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 | */ | |
353 | extern 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 | */ | |
364 | extern 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 | */ | |
377 | extern 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 | */ | |
388 | extern 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 | */ | |
401 | extern 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 | */ | |
414 | extern 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 | */ | |
423 | extern 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 | */ | |
432 | extern 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 | */ | |
443 | extern 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 | */ | |
456 | extern 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 | */ | |
469 | extern 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 | */ | |
482 | extern 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 | */ | |
495 | extern 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 | */ | |
508 | extern 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 | */ | |
523 | extern 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 | */ | |
538 | extern 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 | */ | |
552 | extern 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 | */ | |
562 | extern 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 | */ | |
576 | extern 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() | |
594 | * @see bt_value_array_append_array() | |
595 | * @see bt_value_array_append_map() | |
596 | */ | |
597 | extern 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 | */ | |
613 | extern 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 | */ | |
629 | extern 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 | */ | |
646 | extern 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 | */ | |
664 | extern 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 | */ | |
679 | extern enum bt_value_status bt_value_array_append_array( | |
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 | */ | |
694 | extern enum bt_value_status bt_value_array_append_map( | |
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 | */ | |
711 | extern 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 | */ | |
725 | extern 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 | */ | |
735 | extern 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 | */ | |
749 | extern 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 | */ | |
774 | extern 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 | */ | |
788 | extern 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() | |
812 | * @see bt_value_map_insert_array() | |
813 | * @see bt_value_map_insert_map() | |
814 | */ | |
815 | extern 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 | */ | |
838 | extern 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 | */ | |
859 | extern 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 | */ | |
882 | extern 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 | */ | |
903 | extern 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 | */ | |
922 | extern enum bt_value_status bt_value_map_insert_array( | |
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 | */ | |
941 | extern enum bt_value_status bt_value_map_insert_map( | |
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 | */ | |
957 | extern 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 | */ | |
969 | extern 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 */ |