include/babeltrace/values.h

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