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