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