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