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