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         /// 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 extern struct bt_value *bt_value_array_borrow(const struct bt_value *array_obj,
 815                 uint64_t index);
 816
 817 /**
 818 @brief  Returns the value object contained in the array value object
 819         \p array_obj at the index \p index.
 820
 821 @param[in] array_obj    Array value object of which to get an element.
 822 @param[in] index        Index of value object to get.
 823 @returns                Value object at index \p index on
 824                         success, or \c NULL on error.
 825
 826 @prenotnull{array_obj}
 827 @pre \p array_obj is an array value object.
 828 @pre \p index is lesser than the size of \p array_obj (see
 829         bt_value_array_size()).
 830 @post <strong>On success, if the returned value object is not
 831         \ref bt_value_null</strong>, its reference count is incremented.
 832 @postrefcountsame{array_obj}
 833 */
 834 static inline
 835 struct bt_value *bt_value_array_get(const struct bt_value *array_obj,
 836                 uint64_t index)
 837 {
 838         return bt_get(bt_value_array_borrow(array_obj, index));
 839 }
 840
 841 /**
 842 @brief  Appends the value object \p element_obj to the array value
 843         object \p array_obj.
 844
 845 @param[in] array_obj    Array value object in which to append
 846                         \p element_obj.
 847 @param[in] element_obj  Value object to append.
 848 @returns                Status code.
 849
 850 @prenotnull{array_obj}
 851 @prenotnull{element_obj}
 852 @pre \p array_obj is an array value object.
 853 @prehot{array_obj}
 854 @post <strong>On success, if \p element_obj is not
 855         \ref bt_value_null</strong>, its reference count is incremented.
 856 @postrefcountsame{array_obj}
 857
 858 @sa bt_value_array_append_bool(): Appends a boolean raw value to a
 859         given array value object.
 860 @sa bt_value_array_append_integer(): Appends an integer raw value
 861         to a given array value object.
 862 @sa bt_value_array_append_float(): Appends a floating point number
 863         raw value to a given array value object.
 864 @sa bt_value_array_append_string(): Appends a string raw value to a
 865         given array value object.
 866 @sa bt_value_array_append_empty_array(): Appends an empty array value
 867         object to a given array value object.
 868 @sa bt_value_array_append_empty_map(): Appends an empty map value
 869         object to a given array value object.
 870 */
 871 extern enum bt_value_status bt_value_array_append(struct bt_value *array_obj,
 872                 struct bt_value *element_obj);
 873
 874 /**
 875 @brief  Appends the boolean raw value \p val to the array value object
 876         \p array_obj.
 877
 878 This is a convenience function which creates the underlying boolean
 879 value object before appending it.
 880
 881 @param[in] array_obj    Array value object in which to append \p val.
 882 @param[in] val          Boolean raw value to append to \p array_obj.
 883 @returns                Status code.
 884
 885 @prenotnull{array_obj}
 886 @pre \p array_obj is an array value object.
 887 @prehot{array_obj}
 888 @postrefcountsame{array_obj}
 889
 890 @sa bt_value_array_append(): Appends a value object to a given
 891         array value object.
 892 */
 893 extern enum bt_value_status bt_value_array_append_bool(
 894                 struct bt_value *array_obj, bt_bool val);
 895
 896 /**
 897 @brief  Appends the integer raw value \p val to the array value object
 898         \p array_obj.
 899
 900 This is a convenience function which creates the underlying integer
 901 value object before appending it.
 902
 903 @param[in] array_obj    Array value object in which to append \p val.
 904 @param[in] val          Integer raw value to append to \p array_obj.
 905 @returns                Status code.
 906
 907 @prenotnull{array_obj}
 908 @pre \p array_obj is an array value object.
 909 @prehot{array_obj}
 910 @postrefcountsame{array_obj}
 911
 912 @sa bt_value_array_append(): Appends a value object to a given
 913         array value object.
 914 */
 915 extern enum bt_value_status bt_value_array_append_integer(
 916                 struct bt_value *array_obj, int64_t val);
 917
 918 /**
 919 @brief  Appends the floating point number raw value \p val to the array
 920         value object \p array_obj.
 921
 922 This is a convenience function which creates the underlying floating
 923 point number value object before appending it.
 924
 925 @param[in] array_obj    Array value object in which to append \p val.
 926 @param[in] val          Floating point number raw value to append
 927                         to \p array_obj.
 928 @returns                Status code.
 929
 930 @prenotnull{array_obj}
 931 @pre \p array_obj is an array value object.
 932 @prehot{array_obj}
 933 @postrefcountsame{array_obj}
 934
 935 @sa bt_value_array_append(): Appends a value object to a given
 936         array value object.
 937 */
 938 extern enum bt_value_status bt_value_array_append_float(
 939                 struct bt_value *array_obj, double val);
 940
 941 /**
 942 @brief  Appends the string raw value \p val to the array value object
 943         \p array_obj.
 944
 945 This is a convenience function which creates the underlying string value
 946 object before appending it.
 947
 948 On success, \p val is copied.
 949
 950 @param[in] array_obj    Array value object in which to append \p val.
 951 @param[in] val          String raw value to append to \p array_obj
 952                         (copied on success).
 953 @returns                Status code.
 954
 955 @prenotnull{array_obj}
 956 @pre \p array_obj is an array value object.
 957 @prenotnull{val}
 958 @prehot{array_obj}
 959 @postrefcountsame{array_obj}
 960
 961 @sa bt_value_array_append(): Appends a value object to a given
 962         array value object.
 963 */
 964 extern enum bt_value_status bt_value_array_append_string(
 965                 struct bt_value *array_obj, const char *val);
 966
 967 /**
 968 @brief  Appends an empty array value object to the array value object
 969         \p array_obj.
 970
 971 This is a convenience function which creates the underlying array value
 972 object before appending it.
 973
 974 @param[in] array_obj    Array value object in which to append an
 975                         empty array value object
 976 @returns                Status code.
 977
 978 @prenotnull{array_obj}
 979 @pre \p array_obj is an array value object.
 980 @prehot{array_obj}
 981 @postrefcountsame{array_obj}
 982
 983 @sa bt_value_array_append(): Appends a value object to a given
 984         array value object.
 985 */
 986 extern enum bt_value_status bt_value_array_append_empty_array(
 987                 struct bt_value *array_obj);
 988
 989 /**
 990 @brief  Appends an empty map value object to the array value object
 991         \p array_obj.
 992
 993 This is a convenience function which creates the underlying map value
 994 object before appending it.
 995
 996 @param[in] array_obj    Array value object in which to append an empty
 997                         map value object.
 998 @returns                Status code.
 999
1000 @prenotnull{array_obj}
1001 @pre \p array_obj is an array value object.
1002 @prehot{array_obj}
1003 @postrefcountsame{array_obj}
1004
1005 @sa bt_value_array_append(): Appends a value object to a given
1006         array value object.
1007 */
1008 extern enum bt_value_status bt_value_array_append_empty_map(
1009                 struct bt_value *array_obj);
1010
1011 /**
1012 @brief  Replaces the value object contained in the array value object
1013         \p array_obj at the index \p index by \p element_obj.
1014
1015 @param[in] array_obj            Array value object in which to replace
1016                                 an element.
1017 @param[in] index                Index of value object to replace in
1018                                 \p array_obj.
1019 @param[in] element_obj          New value object at position \p index of
1020                                 \p array_obj.
1021 @returns                        Status code.
1022
1023 @prenotnull{array_obj}
1024 @prenotnull{element_obj}
1025 @pre \p array_obj is an array value object.
1026 @pre \p index is lesser than the size of \p array_obj (see
1027         bt_value_array_size()).
1028 @prehot{array_obj}
1029 @post <strong>On success, if the replaced value object is not
1030         \ref bt_value_null</strong>, its reference count is decremented.
1031 @post <strong>On success, if \p element_obj is not
1032         \ref bt_value_null</strong>, its reference count is incremented.
1033 @postrefcountsame{array_obj}
1034 */
1035 extern enum bt_value_status bt_value_array_set(struct bt_value *array_obj,
1036                 uint64_t index, struct bt_value *element_obj);
1037
1038 /** @} */
1039
1040 /**
1041 @name Map value object functions
1042 @{
1043 */
1044
1045 /**
1046 @brief  Creates an empty map value object.
1047
1048 @returns        Created map value object on success, or \c NULL on error.
1049
1050 @postsuccessrefcountret1
1051 */
1052 extern struct bt_value *bt_value_map_create(void);
1053
1054 /**
1055 @brief  Returns the size of the map value object \p map_obj, that is, the
1056         number of entries contained in \p map_obj.
1057
1058 @param[in] map_obj      Map value object of which to get the size.
1059 @returns                Number of entries contained in \p map_obj if the
1060                         return value is 0 (empty) or a positive value,
1061                         or one of #bt_value_status negative values
1062                         otherwise.
1063
1064 @prenotnull{map_obj}
1065 @pre \p map_obj is a map value object.
1066 @postrefcountsame{map_obj}
1067
1068 @sa bt_value_map_is_empty(): Checks whether or not a given map value
1069         object is empty.
1070 */
1071 extern int64_t bt_value_map_size(const struct bt_value *map_obj);
1072
1073 /**
1074 @brief  Checks whether or not the map value object \p map_obj is empty.
1075
1076 @param[in] map_obj      Map value object to check.
1077 @returns                #BT_TRUE if \p map_obj is empty.
1078
1079 @prenotnull{map_obj}
1080 @pre \p map_obj is a map value object.
1081 @postrefcountsame{map_obj}
1082
1083 @sa bt_value_map_size(): Returns the size of a given map value object.
1084 */
1085 extern bt_bool bt_value_map_is_empty(const struct bt_value *map_obj);
1086
1087 extern struct bt_value *bt_value_map_borrow(const struct bt_value *map_obj,
1088                 const char *key);
1089
1090 /**
1091 @brief  Returns the value object associated with the key \p key within
1092         the map value object \p map_obj.
1093
1094 @param[in] map_obj      Map value object of which to get an entry.
1095 @param[in] key          Key of the value object to get.
1096 @returns                Value object associated with the key \p key
1097                         on success, or \c NULL on error.
1098
1099 @prenotnull{map_obj}
1100 @prenotnull{key}
1101 @pre \p map_obj is a map value object.
1102 @postrefcountsame{map_obj}
1103 @post <strong>On success, if the returned value object is not
1104         \ref bt_value_null</strong>, its reference count is incremented.
1105 */
1106 static inline
1107 struct bt_value *bt_value_map_get(const struct bt_value *map_obj,
1108                 const char *key)
1109 {
1110         return bt_get(bt_value_map_borrow(map_obj, key));
1111 }
1112
1113 /**
1114 @brief  User function type to use with bt_value_map_foreach().
1115
1116 \p object is a <em>weak reference</em>: you \em must pass it to bt_get()
1117 if you need to keep a reference after this function returns.
1118
1119 This function \em must return #BT_TRUE to continue the map value object
1120 traversal, or #BT_FALSE to break it.
1121
1122 @param[in] key          Key of map entry.
1123 @param[in] object       Value object of map entry (weak reference).
1124 @param[in] data         User data.
1125 @returns                #BT_TRUE to continue the loop, or #BT_FALSE to break it.
1126
1127 @prenotnull{key}
1128 @prenotnull{object}
1129 @post The reference count of \p object is not lesser than what it is
1130         when the function is called.
1131 */
1132 typedef bt_bool (* bt_value_map_foreach_cb)(const char *key,
1133         struct bt_value *object, void *data);
1134
1135 /**
1136 @brief  Calls a provided user function \p cb for each value object of the
1137         map value object \p map_obj.
1138
1139 The value object passed to the user function is a <b>weak reference</b>:
1140 you \em must pass it to bt_get() if you need to keep a persistent
1141 reference after the user function returns.
1142
1143 The key passed to the user function is only valid in the scope of
1144 this user function call.
1145
1146 The user function \em must return #BT_TRUE to continue the traversal of
1147 \p map_obj, or #BT_FALSE to break it.
1148
1149 @param[in] map_obj      Map value object on which to iterate.
1150 @param[in] cb           User function to call back.
1151 @param[in] data         User data passed to the user function.
1152 @returns                Status code. More
1153                         specifically, #BT_VALUE_STATUS_CANCELED is
1154                         returned if the loop was canceled by the user
1155                         function.
1156
1157 @prenotnull{map_obj}
1158 @prenotnull{cb}
1159 @pre \p map_obj is a map value object.
1160 @postrefcountsame{map_obj}
1161 */
1162 extern enum bt_value_status bt_value_map_foreach(
1163                 const struct bt_value *map_obj, bt_value_map_foreach_cb cb,
1164                 void *data);
1165
1166 /**
1167 @brief  Returns whether or not the map value object \p map_obj contains
1168         an entry mapped to the key \p key.
1169
1170 @param[in] map_obj      Map value object to check.
1171 @param[in] key          Key to check.
1172 @returns                #BT_TRUE if \p map_obj has an entry mapped to the
1173                         key \p key, or #BT_FALSE if it does not or
1174                         on error.
1175
1176 @prenotnull{map_obj}
1177 @prenotnull{key}
1178 @pre \p map_obj is a map value object.
1179 @postrefcountsame{map_obj}
1180 */
1181 extern bt_bool bt_value_map_has_key(const struct bt_value *map_obj,
1182                 const char *key);
1183
1184 /**
1185 @brief  Inserts the value object \p element_obj mapped to the key
1186         \p key into the map value object \p map_obj.
1187
1188 If a value object is already mapped to \p key in \p map_obj, the
1189 associated value object is first put, and then replaced by
1190 \p element_obj.
1191
1192 On success, \p key is copied.
1193
1194 @param[in] map_obj      Map value object in which to insert
1195                         \p element_obj.
1196 @param[in] key          Key (copied on success) to which the
1197                         value object to insert is mapped.
1198 @param[in] element_obj  Value object to insert, mapped to the
1199                         key \p key.
1200 @returns                Status code.
1201
1202 @prenotnull{map_obj}
1203 @prenotnull{key}
1204 @prenotnull{element_obj}
1205 @pre \p map_obj is a map value object.
1206 @prehot{map_obj}
1207 @post <strong>On success, if \p element_obj is not
1208         \ref bt_value_null</strong>, its reference count is incremented.
1209 @postrefcountsame{map_obj}
1210
1211 @sa bt_value_map_insert_bool(): Inserts a boolean raw value into a
1212         given map value object.
1213 @sa bt_value_map_insert_integer(): Inserts an integer raw value into
1214         a given map value object.
1215 @sa bt_value_map_insert_float(): Inserts a floating point number raw
1216         value into a given map value object.
1217 @sa bt_value_map_insert_string(): Inserts a string raw value into a
1218         given map value object.
1219 @sa bt_value_map_insert_empty_array(): Inserts an empty array value
1220         object into a given map value object.
1221 @sa bt_value_map_insert_empty_map(): Inserts an empty map value
1222         object into a given map value object.
1223 */
1224 extern enum bt_value_status bt_value_map_insert(
1225                 struct bt_value *map_obj, const char *key,
1226                 struct bt_value *element_obj);
1227
1228 /**
1229 @brief  Inserts the boolean raw value \p val mapped to the key \p key
1230         into the map value object \p map_obj.
1231
1232 This is a convenience function which creates the underlying boolean
1233 value object before inserting it.
1234
1235 On success, \p key is copied.
1236
1237 @param[in] map_obj      Map value object in which to insert \p val.
1238 @param[in] key          Key (copied on success) to which the boolean
1239                         value object to insert is mapped.
1240 @param[in] val          Boolean raw value to insert, mapped to
1241                         the key \p key.
1242 @returns                Status code.
1243
1244 @prenotnull{map_obj}
1245 @prenotnull{key}
1246 @pre \p map_obj is a map value object.
1247 @prehot{map_obj}
1248 @postrefcountsame{map_obj}
1249
1250 @sa bt_value_map_insert(): Inserts a value object into a given map
1251         value object.
1252 */
1253 extern enum bt_value_status bt_value_map_insert_bool(
1254                 struct bt_value *map_obj, const char *key, bt_bool val);
1255
1256 /**
1257 @brief  Inserts the integer raw value \p val mapped to the key \p key
1258         into the map value object \p map_obj.
1259
1260 This is a convenience function which creates the underlying integer
1261 value object before inserting it.
1262
1263 On success, \p key is copied.
1264
1265 @param[in] map_obj      Map value object in which to insert \p val.
1266 @param[in] key          Key (copied on success) to which the integer
1267                         value object to insert is mapped.
1268 @param[in] val          Integer raw value to insert, mapped to
1269                         the key \p key.
1270 @returns                Status code.
1271
1272 @prenotnull{map_obj}
1273 @prenotnull{key}
1274 @pre \p map_obj is a map value object.
1275 @prehot{map_obj}
1276 @postrefcountsame{map_obj}
1277
1278 @sa bt_value_map_insert(): Inserts a value object into a given map
1279         value object.
1280 */
1281 extern enum bt_value_status bt_value_map_insert_integer(
1282                 struct bt_value *map_obj, const char *key, int64_t val);
1283
1284 /**
1285 @brief  Inserts the floating point number raw value \p val mapped to
1286         the key \p key into the map value object \p map_obj.
1287
1288 This is a convenience function which creates the underlying floating
1289 point number value object before inserting it.
1290
1291 On success, \p key is copied.
1292
1293 @param[in] map_obj      Map value object in which to insert \p val.
1294 @param[in] key          Key (copied on success) to which the floating
1295                         point number value object to insert is mapped.
1296 @param[in] val          Floating point number raw value to insert,
1297                         mapped to the key \p key.
1298 @returns                Status code.
1299
1300 @prenotnull{map_obj}
1301 @prenotnull{key}
1302 @pre \p map_obj is a map value object.
1303 @prehot{map_obj}
1304 @postrefcountsame{map_obj}
1305
1306 @sa bt_value_map_insert(): Inserts a value object into a given map
1307         value object.
1308 */
1309 extern enum bt_value_status bt_value_map_insert_float(
1310                 struct bt_value *map_obj, const char *key, double val);
1311
1312 /**
1313 @brief  Inserts the string raw value \p val mapped to the key \p key
1314         into the map value object \p map_obj.
1315
1316 This is a convenience function which creates the underlying string value
1317 object before inserting it.
1318
1319 On success, \p val and \p key are copied.
1320
1321 @param[in] map_obj      Map value object in which to insert \p val.
1322 @param[in] key          Key (copied on success) to which the string
1323                         value object to insert is mapped.
1324 @param[in] val          String raw value to insert (copied on success),
1325                         mapped to the key \p key.
1326 @returns                Status code.
1327
1328 @prenotnull{map_obj}
1329 @prenotnull{key}
1330 @prenotnull{val}
1331 @pre \p map_obj is a map value object.
1332 @prehot{map_obj}
1333 @postrefcountsame{map_obj}
1334
1335 @sa bt_value_map_insert(): Inserts a value object into a given map
1336         value object.
1337 */
1338 extern enum bt_value_status bt_value_map_insert_string(
1339                 struct bt_value *map_obj, const char *key, const char *val);
1340
1341 /**
1342 @brief  Inserts an empty array value object mapped to the key \p key
1343         into the map value object \p map_obj.
1344
1345 This is a convenience function which creates the underlying array value
1346 object before inserting it.
1347
1348 On success, \p key is copied.
1349
1350 @param[in] map_obj      Map value object in which to insert an empty
1351                         array value object.
1352 @param[in] key          Key (copied on success) to which the empty array
1353                         value object to insert is mapped.
1354 @returns                Status code.
1355
1356 @prenotnull{map_obj}
1357 @prenotnull{key}
1358 @pre \p map_obj is a map value object.
1359 @prehot{map_obj}
1360 @postrefcountsame{map_obj}
1361
1362 @sa bt_value_map_insert(): Inserts a value object into a given map
1363         value object.
1364 */
1365 extern enum bt_value_status bt_value_map_insert_empty_array(
1366                 struct bt_value *map_obj, const char *key);
1367
1368 /**
1369 @brief  Inserts an empty map value object mapped to the key \p key into
1370         the map value object \p map_obj.
1371
1372 This is a convenience function which creates the underlying map value
1373 object before inserting it.
1374
1375 On success, \p key is copied.
1376
1377 @param[in] map_obj      Map value object in which to insert an empty
1378                         map object.
1379 @param[in] key          Key (copied on success) to which the empty map
1380                         value object to insert is mapped.
1381 @returns                Status code.
1382
1383 @prenotnull{map_obj}
1384 @prenotnull{key}
1385 @pre \p map_obj is a map value object.
1386 @prehot{map_obj}
1387 @postrefcountsame{map_obj}
1388
1389 @sa bt_value_map_insert(): Inserts a value object into a given map
1390         value object.
1391 */
1392 extern enum bt_value_status bt_value_map_insert_empty_map(
1393                 struct bt_value *map_obj, const char *key);
1394
1395 /**
1396 @brief  Creates a copy of the base map value object \p base_map_obj
1397         superficially extended with the entries of the extension map
1398         value object \p extension_map_obj.
1399
1400 This function creates a superficial extension of \p base_map_obj with
1401 \p extension_map_obj by adding new entries to it and replacing the
1402 ones that share the keys in the extension object. The extension is
1403 \em superficial because it does not merge internal array and map
1404 value objects.
1405
1406 For example, consider the following \p base_map_obj (JSON representation):
1407
1408 @verbatim
1409 {
1410   "hello": 23,
1411   "code": -17,
1412   "em": false,
1413   "return": [5, 6, null]
1414 }
1415 @endverbatim
1416
1417 and the following \p extension_map_obj (JSON representation):
1418
1419 @verbatim
1420 {
1421   "comma": ",",
1422   "code": 22,
1423   "return": 17.88
1424 }
1425 @endverbatim
1426
1427 The extended object is (JSON representation):
1428
1429 @verbatim
1430 {
1431   "hello": 23,
1432   "code": 22,
1433   "em": false,
1434   "return": 17.88,
1435   "comma": ","
1436 }
1437 @endverbatim
1438
1439 @param[in] base_map_obj         Base map value object with initial
1440                                 entries.
1441 @param[in] extension_map_obj    Extension map value object containing
1442                                 the entries to add to or replace in
1443                                 \p base_map_obj.
1444 @returns                        Created extended map value object, or
1445                                 \c NULL on error.
1446
1447 @prenotnull{base_map_obj}
1448 @prenotnull{extension_map_obj}
1449 @pre \p base_map_obj is a map value object.
1450 @pre \p extension_map_obj is a map value object.
1451 @postrefcountsame{base_map_obj}
1452 @postrefcountsame{extension_map_obj}
1453 @postsuccessrefcountret1
1454 */
1455 extern struct bt_value *bt_value_map_extend(struct bt_value *base_map_obj,
1456                 struct bt_value *extension_map_obj);
1457
1458 /** @} */
1459
1460 /** @} */
1461
1462 #ifdef __cplusplus
1463 }
1464 #endif
1465
1466 #endif /* BABELTRACE_VALUES_H */