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