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