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