include/babeltrace/values.h

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