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 PP |
34 | |
35 | #ifdef __cplusplus | |
36 | extern "C" { | |
37 | #endif | |
38 | ||
39 | /** | |
de079588 PP |
40 | @defgroup values Value objects |
41 | @ingroup apiref | |
42 | @brief Value objects. | |
43 | ||
9197569d PP |
44 | @code |
45 | #include <babeltrace/values.h> | |
46 | @endcode | |
47 | ||
de079588 PP |
48 | This is a set of <strong><em>value objects</em></strong>. With the |
49 | functions documented here, you can create and modify: | |
50 | ||
51 | - \link bt_value_bool_create() Boolean value objects\endlink. | |
52 | - \link bt_value_integer_create() Integer value objects\endlink. | |
53 | - \link bt_value_float_create() Floating point number | |
54 | value objects\endlink. | |
55 | - \link bt_value_string_create() String value objects\endlink. | |
56 | - \link bt_value_array_create() Array value objects\endlink, | |
57 | containing zero or more value objects. | |
58 | - \link bt_value_map_create() Map value objects\endlink, mapping | |
59 | string keys to value objects. | |
60 | ||
61 | As with any Babeltrace object, value objects have | |
62 | <a href="https://en.wikipedia.org/wiki/Reference_counting">reference | |
63 | counts</a>. When you \link bt_value_array_append() append a value object | |
64 | to an array value object\endlink, or when you \link bt_value_map_insert() | |
65 | insert a value object into a map value object\endlink, its reference | |
66 | count is incremented, as well as when you get a value object back from | |
67 | those objects. See \ref refs to learn more about the reference counting | |
68 | management of Babeltrace objects. | |
69 | ||
70 | Most functions of this API return a <em>status code</em>, one of the | |
71 | values of #bt_value_status. | |
72 | ||
73 | You can create a deep copy of any value object with bt_value_copy(). You | |
74 | can compare two value objects with bt_value_compare(). | |
75 | ||
de079588 PP |
76 | The following matrix shows some categorized value object functions |
77 | to use for each value object type: | |
78 | ||
79 | <table> | |
80 | <tr> | |
81 | <th>Function role →<br> | |
82 | Value object type ↓ | |
83 | <th>Create | |
84 | <th>Check type | |
85 | <th>Get value | |
86 | <th>Set value | |
87 | </tr> | |
88 | <tr> | |
89 | <th>Null | |
90 | <td>Use the \ref bt_value_null variable | |
91 | <td>bt_value_is_null() | |
92 | <td>N/A | |
93 | <td>N/A | |
94 | </tr> | |
95 | <tr> | |
96 | <th>Boolean | |
97 | <td>bt_value_bool_create()<br> | |
98 | bt_value_bool_create_init() | |
99 | <td>bt_value_is_bool() | |
100 | <td>bt_value_bool_get() | |
101 | <td>bt_value_bool_set() | |
102 | </tr> | |
103 | <tr> | |
104 | <th>Integer | |
105 | <td>bt_value_integer_create()<br> | |
106 | bt_value_integer_create_init() | |
107 | <td>bt_value_is_integer() | |
108 | <td>bt_value_integer_get() | |
109 | <td>bt_value_integer_set() | |
110 | </tr> | |
111 | <tr> | |
112 | <th>Floating point<br>number | |
113 | <td>bt_value_float_create()<br> | |
114 | bt_value_float_create_init() | |
115 | <td>bt_value_is_float() | |
116 | <td>bt_value_float_get() | |
117 | <td>bt_value_float_set() | |
118 | </tr> | |
119 | <tr> | |
120 | <th>String | |
121 | <td>bt_value_string_create()<br> | |
122 | bt_value_string_create_init() | |
123 | <td>bt_value_is_string() | |
124 | <td>bt_value_string_get() | |
125 | <td>bt_value_string_set() | |
126 | </tr> | |
127 | <tr> | |
128 | <th>Array | |
129 | <td>bt_value_array_create() | |
130 | <td>bt_value_is_array() | |
131 | <td>bt_value_array_get() | |
132 | <td>bt_value_array_append()<br> | |
133 | bt_value_array_append_bool()<br> | |
134 | bt_value_array_append_integer()<br> | |
135 | bt_value_array_append_float()<br> | |
136 | bt_value_array_append_string()<br> | |
137 | bt_value_array_append_empty_array()<br> | |
138 | bt_value_array_append_empty_map()<br> | |
139 | bt_value_array_set() | |
140 | </tr> | |
141 | <tr> | |
142 | <th>Map | |
c6b7b6e3 PP |
143 | <td>bt_value_map_create()<br> |
144 | bt_value_map_extend() | |
de079588 PP |
145 | <td>bt_value_is_map() |
146 | <td>bt_value_map_get()<br> | |
147 | bt_value_map_foreach() | |
148 | <td>bt_value_map_insert()<br> | |
149 | bt_value_map_insert_bool()<br> | |
150 | bt_value_map_insert_integer()<br> | |
151 | bt_value_map_insert_float()<br> | |
152 | bt_value_map_insert_string()<br> | |
153 | bt_value_map_insert_empty_array()<br> | |
154 | bt_value_map_insert_empty_map() | |
155 | </tr> | |
156 | </table> | |
157 | ||
158 | @file | |
159 | @brief Value object types and functions. | |
160 | @sa values | |
161 | ||
162 | @addtogroup values | |
163 | @{ | |
164 | */ | |
dac5c838 PP |
165 | |
166 | /** | |
de079588 PP |
167 | @brief Status codes. |
168 | */ | |
dac5c838 | 169 | enum bt_value_status { |
f6ccaed9 PP |
170 | /// Operation canceled. |
171 | BT_VALUE_STATUS_CANCELED = -3, | |
dac5c838 | 172 | |
dac5c838 | 173 | /* -22 for compatibility with -EINVAL */ |
544d0515 | 174 | /// Invalid argument. |
de079588 | 175 | BT_VALUE_STATUS_INVAL = -22, |
dac5c838 | 176 | |
de079588 PP |
177 | /// General error. |
178 | BT_VALUE_STATUS_ERROR = -1, | |
dac5c838 | 179 | |
de079588 | 180 | /// Okay, no error. |
dac5c838 PP |
181 | BT_VALUE_STATUS_OK = 0, |
182 | }; | |
183 | ||
184 | /** | |
de079588 PP |
185 | @struct bt_value |
186 | @brief A value object. | |
187 | @sa values | |
188 | */ | |
dac5c838 PP |
189 | struct bt_value; |
190 | ||
191 | /** | |
de079588 PP |
192 | @brief The null value object singleton. |
193 | ||
194 | You \em must use this variable when you need the null value object. | |
195 | ||
196 | The null value object singleton has no reference count: there is only | |
197 | one. You can compare any value object address to the null value object | |
198 | singleton to check if it's the null value object, or otherwise with | |
199 | bt_value_is_null(). | |
200 | ||
201 | You can pass \ref bt_value_null to bt_get() or bt_put(): it has | |
202 | <em>no effect</em>. | |
203 | ||
204 | The null value object singleton is <em>always frozen</em> (see | |
205 | bt_value_is_frozen()). | |
206 | ||
207 | The functions of this API return this variable when the value object | |
208 | is actually the null value object (of type #BT_VALUE_TYPE_NULL), | |
209 | whereas \c NULL means an error of some sort. | |
210 | */ | |
dac5c838 PP |
211 | extern struct bt_value *bt_value_null; |
212 | ||
213 | /** | |
de079588 PP |
214 | @name Type information |
215 | @{ | |
216 | */ | |
dac5c838 | 217 | |
dac5c838 | 218 | /** |
de079588 PP |
219 | @brief Value object type. |
220 | */ | |
221 | enum bt_value_type { | |
222 | /// Unknown value object, used as an error code. | |
223 | BT_VALUE_TYPE_UNKNOWN = -1, | |
dac5c838 | 224 | |
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). | |
235 | BT_VALUE_TYPE_FLOAT = 3, | |
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 |
c55a9f58 | 345 | bt_bool bt_value_is_float(const struct bt_value *object) |
dac5c838 PP |
346 | { |
347 | return bt_value_get_type(object) == BT_VALUE_TYPE_FLOAT; | |
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 | */ | |
617 | extern struct bt_value *bt_value_float_create(void); | |
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 | */ | |
632 | extern struct bt_value *bt_value_float_create_init(double val); | |
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 | */ | |
dac5c838 | 651 | extern enum bt_value_status bt_value_float_get( |
364747d6 | 652 | const struct bt_value *float_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 | */ | |
dac5c838 | 671 | extern enum bt_value_status bt_value_float_set( |
364747d6 | 672 | struct bt_value *float_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 PP |
813 | |
814 | /** | |
de079588 PP |
815 | @brief Returns the value object contained in the array value object |
816 | \p array_obj at the index \p index. | |
817 | ||
818 | @param[in] array_obj Array value object of which to get an element. | |
819 | @param[in] index Index of value object to get. | |
820 | @returns Value object at index \p index on | |
821 | success, or \c NULL on error. | |
822 | ||
823 | @prenotnull{array_obj} | |
824 | @pre \p array_obj is an array value object. | |
c6b7b6e3 PP |
825 | @pre \p index is lesser than the size of \p array_obj (see |
826 | bt_value_array_size()). | |
de079588 PP |
827 | @post <strong>On success, if the returned value object is not |
828 | \ref bt_value_null</strong>, its reference count is incremented. | |
829 | @postrefcountsame{array_obj} | |
830 | */ | |
dac5c838 | 831 | extern struct bt_value *bt_value_array_get(const struct bt_value *array_obj, |
544d0515 | 832 | uint64_t index); |
dac5c838 PP |
833 | |
834 | /** | |
de079588 PP |
835 | @brief Appends the value object \p element_obj to the array value |
836 | object \p array_obj. | |
837 | ||
838 | @param[in] array_obj Array value object in which to append | |
839 | \p element_obj. | |
840 | @param[in] element_obj Value object to append. | |
c6b7b6e3 | 841 | @returns Status code. |
de079588 PP |
842 | |
843 | @prenotnull{array_obj} | |
844 | @prenotnull{element_obj} | |
845 | @pre \p array_obj is an array value object. | |
846 | @prehot{array_obj} | |
847 | @post <strong>On success, if \p element_obj is not | |
848 | \ref bt_value_null</strong>, its reference count is incremented. | |
849 | @postrefcountsame{array_obj} | |
850 | ||
851 | @sa bt_value_array_append_bool(): Appends a boolean raw value to a | |
852 | given array value object. | |
853 | @sa bt_value_array_append_integer(): Appends an integer raw value | |
854 | to a given array value object. | |
855 | @sa bt_value_array_append_float(): Appends a floating point number | |
856 | raw value to a given array value object. | |
857 | @sa bt_value_array_append_string(): Appends a string raw value to a | |
858 | given array value object. | |
859 | @sa bt_value_array_append_empty_array(): Appends an empty array value | |
860 | object to a given array value object. | |
861 | @sa bt_value_array_append_empty_map(): Appends an empty map value | |
862 | object to a given array value object. | |
863 | */ | |
dac5c838 | 864 | extern enum bt_value_status bt_value_array_append(struct bt_value *array_obj, |
364747d6 | 865 | struct bt_value *element_obj); |
dac5c838 PP |
866 | |
867 | /** | |
de079588 PP |
868 | @brief Appends the boolean raw value \p val to the array value object |
869 | \p array_obj. | |
870 | ||
871 | This is a convenience function which creates the underlying boolean | |
872 | value object before appending it. | |
873 | ||
874 | @param[in] array_obj Array value object in which to append \p val. | |
875 | @param[in] val Boolean raw value to append to \p array_obj. | |
c6b7b6e3 | 876 | @returns Status code. |
de079588 PP |
877 | |
878 | @prenotnull{array_obj} | |
879 | @pre \p array_obj is an array value object. | |
880 | @prehot{array_obj} | |
881 | @postrefcountsame{array_obj} | |
882 | ||
883 | @sa bt_value_array_append(): Appends a value object to a given | |
884 | array value object. | |
885 | */ | |
dac5c838 | 886 | extern enum bt_value_status bt_value_array_append_bool( |
c55a9f58 | 887 | struct bt_value *array_obj, bt_bool val); |
dac5c838 PP |
888 | |
889 | /** | |
de079588 PP |
890 | @brief Appends the integer raw value \p val to the array value object |
891 | \p array_obj. | |
892 | ||
893 | This is a convenience function which creates the underlying integer | |
894 | value object before appending it. | |
895 | ||
896 | @param[in] array_obj Array value object in which to append \p val. | |
897 | @param[in] val Integer raw value to append to \p array_obj. | |
c6b7b6e3 | 898 | @returns Status code. |
de079588 PP |
899 | |
900 | @prenotnull{array_obj} | |
901 | @pre \p array_obj is an array value object. | |
902 | @prehot{array_obj} | |
903 | @postrefcountsame{array_obj} | |
904 | ||
905 | @sa bt_value_array_append(): Appends a value object to a given | |
906 | array value object. | |
907 | */ | |
dac5c838 | 908 | extern enum bt_value_status bt_value_array_append_integer( |
364747d6 | 909 | struct bt_value *array_obj, int64_t val); |
dac5c838 PP |
910 | |
911 | /** | |
de079588 PP |
912 | @brief Appends the floating point number raw value \p val to the array |
913 | value object \p array_obj. | |
914 | ||
915 | This is a convenience function which creates the underlying floating | |
916 | point number value object before appending it. | |
917 | ||
918 | @param[in] array_obj Array value object in which to append \p val. | |
919 | @param[in] val Floating point number raw value to append | |
920 | to \p array_obj. | |
c6b7b6e3 | 921 | @returns Status code. |
de079588 PP |
922 | |
923 | @prenotnull{array_obj} | |
924 | @pre \p array_obj is an array value object. | |
925 | @prehot{array_obj} | |
926 | @postrefcountsame{array_obj} | |
927 | ||
928 | @sa bt_value_array_append(): Appends a value object to a given | |
929 | array value object. | |
930 | */ | |
dac5c838 | 931 | extern enum bt_value_status bt_value_array_append_float( |
364747d6 | 932 | struct bt_value *array_obj, double val); |
dac5c838 PP |
933 | |
934 | /** | |
de079588 PP |
935 | @brief Appends the string raw value \p val to the array value object |
936 | \p array_obj. | |
937 | ||
938 | This is a convenience function which creates the underlying string value | |
939 | object before appending it. | |
940 | ||
941 | On success, \p val is copied. | |
942 | ||
943 | @param[in] array_obj Array value object in which to append \p val. | |
944 | @param[in] val String raw value to append to \p array_obj | |
945 | (copied on success). | |
c6b7b6e3 | 946 | @returns Status code. |
de079588 PP |
947 | |
948 | @prenotnull{array_obj} | |
949 | @pre \p array_obj is an array value object. | |
950 | @prenotnull{val} | |
951 | @prehot{array_obj} | |
952 | @postrefcountsame{array_obj} | |
953 | ||
954 | @sa bt_value_array_append(): Appends a value object to a given | |
955 | array value object. | |
956 | */ | |
dac5c838 | 957 | extern enum bt_value_status bt_value_array_append_string( |
364747d6 | 958 | struct bt_value *array_obj, const char *val); |
dac5c838 PP |
959 | |
960 | /** | |
de079588 PP |
961 | @brief Appends an empty array value object to the array value object |
962 | \p array_obj. | |
963 | ||
964 | This is a convenience function which creates the underlying array value | |
965 | object before appending it. | |
966 | ||
967 | @param[in] array_obj Array value object in which to append an | |
968 | empty array value object | |
c6b7b6e3 | 969 | @returns Status code. |
de079588 PP |
970 | |
971 | @prenotnull{array_obj} | |
972 | @pre \p array_obj is an array value object. | |
973 | @prehot{array_obj} | |
974 | @postrefcountsame{array_obj} | |
975 | ||
976 | @sa bt_value_array_append(): Appends a value object to a given | |
977 | array value object. | |
978 | */ | |
5b79e8bf | 979 | extern enum bt_value_status bt_value_array_append_empty_array( |
364747d6 | 980 | struct bt_value *array_obj); |
dac5c838 PP |
981 | |
982 | /** | |
de079588 PP |
983 | @brief Appends an empty map value object to the array value object |
984 | \p array_obj. | |
985 | ||
986 | This is a convenience function which creates the underlying map value | |
987 | object before appending it. | |
988 | ||
989 | @param[in] array_obj Array value object in which to append an empty | |
990 | map value object. | |
c6b7b6e3 | 991 | @returns Status code. |
de079588 PP |
992 | |
993 | @prenotnull{array_obj} | |
994 | @pre \p array_obj is an array value object. | |
995 | @prehot{array_obj} | |
996 | @postrefcountsame{array_obj} | |
997 | ||
998 | @sa bt_value_array_append(): Appends a value object to a given | |
999 | array value object. | |
1000 | */ | |
5b79e8bf | 1001 | extern enum bt_value_status bt_value_array_append_empty_map( |
364747d6 | 1002 | struct bt_value *array_obj); |
dac5c838 PP |
1003 | |
1004 | /** | |
de079588 PP |
1005 | @brief Replaces the value object contained in the array value object |
1006 | \p array_obj at the index \p index by \p element_obj. | |
1007 | ||
1008 | @param[in] array_obj Array value object in which to replace | |
1009 | an element. | |
1010 | @param[in] index Index of value object to replace in | |
1011 | \p array_obj. | |
1012 | @param[in] element_obj New value object at position \p index of | |
1013 | \p array_obj. | |
c6b7b6e3 | 1014 | @returns Status code. |
de079588 PP |
1015 | |
1016 | @prenotnull{array_obj} | |
1017 | @prenotnull{element_obj} | |
1018 | @pre \p array_obj is an array value object. | |
c6b7b6e3 PP |
1019 | @pre \p index is lesser than the size of \p array_obj (see |
1020 | bt_value_array_size()). | |
de079588 PP |
1021 | @prehot{array_obj} |
1022 | @post <strong>On success, if the replaced value object is not | |
1023 | \ref bt_value_null</strong>, its reference count is decremented. | |
1024 | @post <strong>On success, if \p element_obj is not | |
1025 | \ref bt_value_null</strong>, its reference count is incremented. | |
1026 | @postrefcountsame{array_obj} | |
1027 | */ | |
dac5c838 | 1028 | extern enum bt_value_status bt_value_array_set(struct bt_value *array_obj, |
544d0515 | 1029 | uint64_t index, struct bt_value *element_obj); |
dac5c838 | 1030 | |
de079588 PP |
1031 | /** @} */ |
1032 | ||
dac5c838 | 1033 | /** |
de079588 PP |
1034 | @name Map value object functions |
1035 | @{ | |
1036 | */ | |
1037 | ||
1038 | /** | |
1039 | @brief Creates an empty map value object. | |
1040 | ||
1041 | @returns Created map value object on success, or \c NULL on error. | |
1042 | ||
1043 | @postsuccessrefcountret1 | |
1044 | */ | |
1045 | extern struct bt_value *bt_value_map_create(void); | |
1046 | ||
1047 | /** | |
1048 | @brief Returns the size of the map value object \p map_obj, that is, the | |
1049 | number of entries contained in \p map_obj. | |
1050 | ||
1051 | @param[in] map_obj Map value object of which to get the size. | |
1052 | @returns Number of entries contained in \p map_obj if the | |
1053 | return value is 0 (empty) or a positive value, | |
1054 | or one of #bt_value_status negative values | |
1055 | otherwise. | |
1056 | ||
1057 | @prenotnull{map_obj} | |
1058 | @pre \p map_obj is a map value object. | |
1059 | @postrefcountsame{map_obj} | |
1060 | ||
1061 | @sa bt_value_map_is_empty(): Checks whether or not a given map value | |
1062 | object is empty. | |
1063 | */ | |
544d0515 | 1064 | extern int64_t bt_value_map_size(const struct bt_value *map_obj); |
dac5c838 PP |
1065 | |
1066 | /** | |
de079588 PP |
1067 | @brief Checks whether or not the map value object \p map_obj is empty. |
1068 | ||
1069 | @param[in] map_obj Map value object to check. | |
c55a9f58 | 1070 | @returns #BT_TRUE if \p map_obj is empty. |
de079588 PP |
1071 | |
1072 | @prenotnull{map_obj} | |
1073 | @pre \p map_obj is a map value object. | |
1074 | @postrefcountsame{map_obj} | |
1075 | ||
1076 | @sa bt_value_map_size(): Returns the size of a given map value object. | |
1077 | */ | |
c55a9f58 | 1078 | extern bt_bool bt_value_map_is_empty(const struct bt_value *map_obj); |
dac5c838 PP |
1079 | |
1080 | /** | |
de079588 PP |
1081 | @brief Returns the value object associated with the key \p key within |
1082 | the map value object \p map_obj. | |
1083 | ||
1084 | @param[in] map_obj Map value object of which to get an entry. | |
1085 | @param[in] key Key of the value object to get. | |
1086 | @returns Value object associated with the key \p key | |
1087 | on success, or \c NULL on error. | |
1088 | ||
1089 | @prenotnull{map_obj} | |
1090 | @prenotnull{key} | |
1091 | @pre \p map_obj is a map value object. | |
1092 | @postrefcountsame{map_obj} | |
de079588 PP |
1093 | @post <strong>On success, if the returned value object is not |
1094 | \ref bt_value_null</strong>, its reference count is incremented. | |
1095 | */ | |
dac5c838 | 1096 | extern struct bt_value *bt_value_map_get(const struct bt_value *map_obj, |
364747d6 | 1097 | const char *key); |
dac5c838 PP |
1098 | |
1099 | /** | |
de079588 PP |
1100 | @brief User function type to use with bt_value_map_foreach(). |
1101 | ||
1102 | \p object is a <em>weak reference</em>: you \em must pass it to bt_get() | |
cbcfcefc | 1103 | if you need to keep a reference after this function returns. |
de079588 | 1104 | |
c55a9f58 PP |
1105 | This function \em must return #BT_TRUE to continue the map value object |
1106 | traversal, or #BT_FALSE to break it. | |
de079588 PP |
1107 | |
1108 | @param[in] key Key of map entry. | |
1109 | @param[in] object Value object of map entry (weak reference). | |
1110 | @param[in] data User data. | |
c55a9f58 | 1111 | @returns #BT_TRUE to continue the loop, or #BT_FALSE to break it. |
de079588 PP |
1112 | |
1113 | @prenotnull{key} | |
1114 | @prenotnull{object} | |
1115 | @post The reference count of \p object is not lesser than what it is | |
1116 | when the function is called. | |
1117 | */ | |
c55a9f58 | 1118 | typedef bt_bool (* bt_value_map_foreach_cb)(const char *key, |
de079588 PP |
1119 | struct bt_value *object, void *data); |
1120 | ||
1121 | /** | |
1122 | @brief Calls a provided user function \p cb for each value object of the | |
1123 | map value object \p map_obj. | |
1124 | ||
1125 | The value object passed to the user function is a <b>weak reference</b>: | |
cbcfcefc PP |
1126 | you \em must pass it to bt_get() if you need to keep a persistent |
1127 | reference after the user function returns. | |
de079588 PP |
1128 | |
1129 | The key passed to the user function is only valid in the scope of | |
1130 | this user function call. | |
1131 | ||
c55a9f58 PP |
1132 | The user function \em must return #BT_TRUE to continue the traversal of |
1133 | \p map_obj, or #BT_FALSE to break it. | |
de079588 PP |
1134 | |
1135 | @param[in] map_obj Map value object on which to iterate. | |
1136 | @param[in] cb User function to call back. | |
1137 | @param[in] data User data passed to the user function. | |
c6b7b6e3 | 1138 | @returns Status code. More |
f6ccaed9 PP |
1139 | specifically, #BT_VALUE_STATUS_CANCELED is |
1140 | returned if the loop was canceled by the user | |
de079588 PP |
1141 | function. |
1142 | ||
1143 | @prenotnull{map_obj} | |
1144 | @prenotnull{cb} | |
1145 | @pre \p map_obj is a map value object. | |
1146 | @postrefcountsame{map_obj} | |
1147 | */ | |
dac5c838 | 1148 | extern enum bt_value_status bt_value_map_foreach( |
364747d6 PP |
1149 | const struct bt_value *map_obj, bt_value_map_foreach_cb cb, |
1150 | void *data); | |
dac5c838 PP |
1151 | |
1152 | /** | |
de079588 PP |
1153 | @brief Returns whether or not the map value object \p map_obj contains |
1154 | an entry mapped to the key \p key. | |
1155 | ||
1156 | @param[in] map_obj Map value object to check. | |
1157 | @param[in] key Key to check. | |
c55a9f58 PP |
1158 | @returns #BT_TRUE if \p map_obj has an entry mapped to the |
1159 | key \p key, or #BT_FALSE if it does not or | |
de079588 PP |
1160 | on error. |
1161 | ||
1162 | @prenotnull{map_obj} | |
1163 | @prenotnull{key} | |
1164 | @pre \p map_obj is a map value object. | |
1165 | @postrefcountsame{map_obj} | |
1166 | */ | |
c55a9f58 | 1167 | extern bt_bool bt_value_map_has_key(const struct bt_value *map_obj, |
364747d6 | 1168 | const char *key); |
dac5c838 PP |
1169 | |
1170 | /** | |
de079588 PP |
1171 | @brief Inserts the value object \p element_obj mapped to the key |
1172 | \p key into the map value object \p map_obj. | |
1173 | ||
1174 | If a value object is already mapped to \p key in \p map_obj, the | |
1175 | associated value object is first put, and then replaced by | |
1176 | \p element_obj. | |
1177 | ||
1178 | On success, \p key is copied. | |
1179 | ||
1180 | @param[in] map_obj Map value object in which to insert | |
1181 | \p element_obj. | |
1182 | @param[in] key Key (copied on success) to which the | |
1183 | value object to insert is mapped. | |
1184 | @param[in] element_obj Value object to insert, mapped to the | |
1185 | key \p key. | |
c6b7b6e3 | 1186 | @returns Status code. |
de079588 PP |
1187 | |
1188 | @prenotnull{map_obj} | |
1189 | @prenotnull{key} | |
1190 | @prenotnull{element_obj} | |
1191 | @pre \p map_obj is a map value object. | |
1192 | @prehot{map_obj} | |
1193 | @post <strong>On success, if \p element_obj is not | |
1194 | \ref bt_value_null</strong>, its reference count is incremented. | |
1195 | @postrefcountsame{map_obj} | |
1196 | ||
1197 | @sa bt_value_map_insert_bool(): Inserts a boolean raw value into a | |
1198 | given map value object. | |
1199 | @sa bt_value_map_insert_integer(): Inserts an integer raw value into | |
1200 | a given map value object. | |
1201 | @sa bt_value_map_insert_float(): Inserts a floating point number raw | |
1202 | value into a given map value object. | |
1203 | @sa bt_value_map_insert_string(): Inserts a string raw value into a | |
1204 | given map value object. | |
1205 | @sa bt_value_map_insert_empty_array(): Inserts an empty array value | |
1206 | object into a given map value object. | |
1207 | @sa bt_value_map_insert_empty_map(): Inserts an empty map value | |
1208 | object into a given map value object. | |
1209 | */ | |
dac5c838 | 1210 | extern enum bt_value_status bt_value_map_insert( |
364747d6 PP |
1211 | struct bt_value *map_obj, const char *key, |
1212 | struct bt_value *element_obj); | |
dac5c838 PP |
1213 | |
1214 | /** | |
de079588 PP |
1215 | @brief Inserts the boolean raw value \p val mapped to the key \p key |
1216 | into the map value object \p map_obj. | |
1217 | ||
1218 | This is a convenience function which creates the underlying boolean | |
1219 | value object before inserting it. | |
1220 | ||
1221 | On success, \p key is copied. | |
1222 | ||
1223 | @param[in] map_obj Map value object in which to insert \p val. | |
1224 | @param[in] key Key (copied on success) to which the boolean | |
1225 | value object to insert is mapped. | |
1226 | @param[in] val Boolean raw value to insert, mapped to | |
1227 | the key \p key. | |
c6b7b6e3 | 1228 | @returns Status code. |
de079588 PP |
1229 | |
1230 | @prenotnull{map_obj} | |
1231 | @prenotnull{key} | |
1232 | @pre \p map_obj is a map value object. | |
1233 | @prehot{map_obj} | |
1234 | @postrefcountsame{map_obj} | |
1235 | ||
1236 | @sa bt_value_map_insert(): Inserts a value object into a given map | |
1237 | value object. | |
1238 | */ | |
dac5c838 | 1239 | extern enum bt_value_status bt_value_map_insert_bool( |
c55a9f58 | 1240 | struct bt_value *map_obj, const char *key, bt_bool val); |
dac5c838 PP |
1241 | |
1242 | /** | |
de079588 PP |
1243 | @brief Inserts the integer raw value \p val mapped to the key \p key |
1244 | into the map value object \p map_obj. | |
1245 | ||
1246 | This is a convenience function which creates the underlying integer | |
1247 | value object before inserting it. | |
1248 | ||
1249 | On success, \p key is copied. | |
1250 | ||
1251 | @param[in] map_obj Map value object in which to insert \p val. | |
1252 | @param[in] key Key (copied on success) to which the integer | |
1253 | value object to insert is mapped. | |
1254 | @param[in] val Integer raw value to insert, mapped to | |
1255 | the key \p key. | |
c6b7b6e3 | 1256 | @returns Status code. |
de079588 PP |
1257 | |
1258 | @prenotnull{map_obj} | |
1259 | @prenotnull{key} | |
1260 | @pre \p map_obj is a map value object. | |
1261 | @prehot{map_obj} | |
1262 | @postrefcountsame{map_obj} | |
1263 | ||
1264 | @sa bt_value_map_insert(): Inserts a value object into a given map | |
1265 | value object. | |
1266 | */ | |
dac5c838 | 1267 | extern enum bt_value_status bt_value_map_insert_integer( |
364747d6 | 1268 | struct bt_value *map_obj, const char *key, int64_t val); |
dac5c838 PP |
1269 | |
1270 | /** | |
de079588 PP |
1271 | @brief Inserts the floating point number raw value \p val mapped to |
1272 | the key \p key into the map value object \p map_obj. | |
1273 | ||
1274 | This is a convenience function which creates the underlying floating | |
1275 | point number value object before inserting it. | |
1276 | ||
1277 | On success, \p key is copied. | |
1278 | ||
1279 | @param[in] map_obj Map value object in which to insert \p val. | |
1280 | @param[in] key Key (copied on success) to which the floating | |
1281 | point number value object to insert is mapped. | |
1282 | @param[in] val Floating point number raw value to insert, | |
1283 | mapped to the key \p key. | |
c6b7b6e3 | 1284 | @returns Status code. |
de079588 PP |
1285 | |
1286 | @prenotnull{map_obj} | |
1287 | @prenotnull{key} | |
1288 | @pre \p map_obj is a map value object. | |
1289 | @prehot{map_obj} | |
1290 | @postrefcountsame{map_obj} | |
1291 | ||
1292 | @sa bt_value_map_insert(): Inserts a value object into a given map | |
1293 | value object. | |
1294 | */ | |
dac5c838 | 1295 | extern enum bt_value_status bt_value_map_insert_float( |
364747d6 | 1296 | struct bt_value *map_obj, const char *key, double val); |
dac5c838 PP |
1297 | |
1298 | /** | |
de079588 PP |
1299 | @brief Inserts the string raw value \p val mapped to the key \p key |
1300 | into the map value object \p map_obj. | |
1301 | ||
1302 | This is a convenience function which creates the underlying string value | |
1303 | object before inserting it. | |
1304 | ||
1305 | On success, \p val and \p key are copied. | |
1306 | ||
1307 | @param[in] map_obj Map value object in which to insert \p val. | |
1308 | @param[in] key Key (copied on success) to which the string | |
1309 | value object to insert is mapped. | |
1310 | @param[in] val String raw value to insert (copied on success), | |
1311 | mapped to the key \p key. | |
c6b7b6e3 | 1312 | @returns Status code. |
de079588 PP |
1313 | |
1314 | @prenotnull{map_obj} | |
1315 | @prenotnull{key} | |
1316 | @prenotnull{val} | |
1317 | @pre \p map_obj is a map value object. | |
1318 | @prehot{map_obj} | |
1319 | @postrefcountsame{map_obj} | |
1320 | ||
1321 | @sa bt_value_map_insert(): Inserts a value object into a given map | |
1322 | value object. | |
1323 | */ | |
dac5c838 | 1324 | extern enum bt_value_status bt_value_map_insert_string( |
364747d6 | 1325 | struct bt_value *map_obj, const char *key, const char *val); |
dac5c838 PP |
1326 | |
1327 | /** | |
de079588 PP |
1328 | @brief Inserts an empty array value object mapped to the key \p key |
1329 | into the map value object \p map_obj. | |
1330 | ||
1331 | This is a convenience function which creates the underlying array value | |
1332 | object before inserting it. | |
1333 | ||
1334 | On success, \p key is copied. | |
1335 | ||
1336 | @param[in] map_obj Map value object in which to insert an empty | |
1337 | array value object. | |
1338 | @param[in] key Key (copied on success) to which the empty array | |
1339 | value object to insert is mapped. | |
c6b7b6e3 | 1340 | @returns Status code. |
de079588 PP |
1341 | |
1342 | @prenotnull{map_obj} | |
1343 | @prenotnull{key} | |
1344 | @pre \p map_obj is a map value object. | |
1345 | @prehot{map_obj} | |
1346 | @postrefcountsame{map_obj} | |
1347 | ||
1348 | @sa bt_value_map_insert(): Inserts a value object into a given map | |
1349 | value object. | |
1350 | */ | |
5b79e8bf | 1351 | extern enum bt_value_status bt_value_map_insert_empty_array( |
364747d6 | 1352 | struct bt_value *map_obj, const char *key); |
dac5c838 PP |
1353 | |
1354 | /** | |
de079588 PP |
1355 | @brief Inserts an empty map value object mapped to the key \p key into |
1356 | the map value object \p map_obj. | |
1357 | ||
1358 | This is a convenience function which creates the underlying map value | |
1359 | object before inserting it. | |
1360 | ||
1361 | On success, \p key is copied. | |
1362 | ||
1363 | @param[in] map_obj Map value object in which to insert an empty | |
1364 | map object. | |
1365 | @param[in] key Key (copied on success) to which the empty map | |
1366 | value object to insert is mapped. | |
c6b7b6e3 | 1367 | @returns Status code. |
de079588 PP |
1368 | |
1369 | @prenotnull{map_obj} | |
1370 | @prenotnull{key} | |
1371 | @pre \p map_obj is a map value object. | |
1372 | @prehot{map_obj} | |
1373 | @postrefcountsame{map_obj} | |
1374 | ||
1375 | @sa bt_value_map_insert(): Inserts a value object into a given map | |
1376 | value object. | |
1377 | */ | |
5b79e8bf | 1378 | extern enum bt_value_status bt_value_map_insert_empty_map( |
364747d6 | 1379 | struct bt_value *map_obj, const char *key); |
dac5c838 | 1380 | |
770750d3 PP |
1381 | /** |
1382 | @brief Creates a copy of the base map value object \p base_map_obj | |
1383 | superficially extended with the entries of the extension map | |
1384 | value object \p extension_map_obj. | |
1385 | ||
1386 | This function creates a superficial extension of \p base_map_obj with | |
1387 | \p extension_map_obj by adding new entries to it and replacing the | |
1388 | ones that share the keys in the extension object. The extension is | |
1389 | \em superficial because it does not merge internal array and map | |
1390 | value objects. | |
1391 | ||
1392 | For example, consider the following \p base_map_obj (JSON representation): | |
1393 | ||
c6b7b6e3 | 1394 | @verbatim |
770750d3 PP |
1395 | { |
1396 | "hello": 23, | |
1397 | "code": -17, | |
1398 | "em": false, | |
1399 | "return": [5, 6, null] | |
1400 | } | |
c6b7b6e3 | 1401 | @endverbatim |
770750d3 PP |
1402 | |
1403 | and the following \p extension_map_obj (JSON representation): | |
1404 | ||
c6b7b6e3 | 1405 | @verbatim |
770750d3 PP |
1406 | { |
1407 | "comma": ",", | |
1408 | "code": 22, | |
1409 | "return": 17.88 | |
1410 | } | |
c6b7b6e3 | 1411 | @endverbatim |
770750d3 PP |
1412 | |
1413 | The extended object is (JSON representation): | |
1414 | ||
c6b7b6e3 | 1415 | @verbatim |
770750d3 PP |
1416 | { |
1417 | "hello": 23, | |
1418 | "code": 22, | |
1419 | "em": false, | |
1420 | "return": 17.88, | |
1421 | "comma": "," | |
1422 | } | |
c6b7b6e3 | 1423 | @endverbatim |
770750d3 PP |
1424 | |
1425 | @param[in] base_map_obj Base map value object with initial | |
1426 | entries. | |
1427 | @param[in] extension_map_obj Extension map value object containing | |
1428 | the entries to add to or replace in | |
1429 | \p base_map_obj. | |
1430 | @returns Created extended map value object, or | |
1431 | \c NULL on error. | |
1432 | ||
1433 | @prenotnull{base_map_obj} | |
1434 | @prenotnull{extension_map_obj} | |
1435 | @pre \p base_map_obj is a map value object. | |
1436 | @pre \p extension_map_obj is a map value object. | |
1437 | @postrefcountsame{base_map_obj} | |
1438 | @postrefcountsame{extension_map_obj} | |
1439 | @postsuccessrefcountret1 | |
1440 | */ | |
1441 | extern struct bt_value *bt_value_map_extend(struct bt_value *base_map_obj, | |
1442 | struct bt_value *extension_map_obj); | |
1443 | ||
de079588 | 1444 | /** @} */ |
dac5c838 | 1445 | |
de079588 | 1446 | /** @} */ |
dac5c838 PP |
1447 | |
1448 | #ifdef __cplusplus | |
1449 | } | |
1450 | #endif | |
1451 | ||
1ca80abd | 1452 | #endif /* BABELTRACE_VALUES_H */ |