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