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