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