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