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 EfficiOS Inc. and Linux Foundation
   8  * Copyright (c) 2015 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 /**
  30  * @file values.h
  31  * @brief Value objects
  32  *
  33  * This is a set of value objects. The following functions allow you
  34  * to create, modify, and destroy:
  35  *
  36  *   - \link bt_value_null null value objects\endlink
  37  *   - \link bt_value_bool_create() boolean value objects\endlink
  38  *   - \link bt_value_integer_create() integer value objects\endlink
  39  *   - \link bt_value_float_create() floating point number
  40  *     value objects\endlink
  41  *   - \link bt_value_string_create() string value objects\endlink
  42  *   - \link bt_value_array_create() array value objects\endlink,
  43  *     containing zero or more value objects
  44  *   - \link bt_value_map_create() map value objects\endlink, mapping
  45  *     string keys to value objects
  46  *
  47  * All the value object types above, except for null values (which
  48  * always point to the same \link bt_value_null singleton\endlink), have
  49  * a reference count property. Once a value object is created, its
  50  * reference count is set to 1. When \link bt_value_array_append()
  51  * appending a value to an array value object\endlink, or
  52  * \link bt_value_map_insert() inserting a value object into a map
  53  * value object\endlink, its reference count is incremented, as well as
  54  * when getting a value object back from those structures. The
  55  * bt_get() and bt_put() functions are to be used to handle reference counting
  56  * Once you are done with a value object, pass it to bt_put().
  57  *
  58  * Most functions of this API return a status code, one of the values in
  59  * #bt_value_status.
  60  *
  61  * You can create a deep copy of any value object using the
  62  * bt_value_copy() function. You can compare two given value objects
  63  * using bt_value_compare().
  64  *
  65  * Any value object may be frozen using bt_value_freeze(). You may get
  66  * the raw value of a frozen value object, but you cannot modify it.
  67  * Reference counting still works on frozen value objects. You may also
  68  * copy and compare frozen value objects.
  69  *
  70  * @author      Philippe Proulx <pproulx@efficios.com>
  71  * @bug         No known bugs
  72  */
  73
  74 #include <stdint.h>
  75 #include <stdbool.h>
  76 #include <stddef.h>
  77 #include <babeltrace/ref.h>
  78 #include <babeltrace/babeltrace-internal.h>
  79
  80 #ifdef __cplusplus
  81 extern "C" {
  82 #endif
  83
  84 /**
  85  * Value object type.
  86  */
  87 enum bt_value_type {
  88         /** Unknown value object, used as an error code. */
  89         BT_VALUE_TYPE_UNKNOWN =         -1,
  90
  91         /** Null value object. */
  92         BT_VALUE_TYPE_NULL =            0,
  93
  94         /** Boolean value object (holds \c true or \c false). */
  95         BT_VALUE_TYPE_BOOL =            1,
  96
  97         /** Integer value object (holds a signed 64-bit integer raw value). */
  98         BT_VALUE_TYPE_INTEGER =         2,
  99
 100         /** Floating point number value object (holds a \c double raw value). */
 101         BT_VALUE_TYPE_FLOAT =           3,
 102
 103         /** String value object. */
 104         BT_VALUE_TYPE_STRING =          4,
 105
 106         /** Array value object. */
 107         BT_VALUE_TYPE_ARRAY =           5,
 108
 109         /** Map value object. */
 110         BT_VALUE_TYPE_MAP =             6,
 111 };
 112
 113 /**
 114  * Status codes.
 115  */
 116 enum bt_value_status {
 117         /** Value object cannot be altered because it's frozen. */
 118         BT_VALUE_STATUS_FROZEN =        -4,
 119
 120         /** Operation cancelled. */
 121         BT_VALUE_STATUS_CANCELLED =     -3,
 122
 123         /** Invalid arguments. */
 124         /* -22 for compatibility with -EINVAL */
 125         BT_VALUE_STATUS_INVAL = -22,
 126
 127         /** General error. */
 128         BT_VALUE_STATUS_ERROR = -1,
 129
 130         /** Okay, no error. */
 131         BT_VALUE_STATUS_OK =            0,
 132 };
 133
 134 /**
 135  * Value object.
 136  */
 137 struct bt_value;
 138
 139 /**
 140  * The null value object singleton.
 141  *
 142  * Use this everytime you need a null value object.
 143  *
 144  * The null value object singleton has no reference count; there's only
 145  * one. You may directly compare any value object to the null value
 146  * object singleton to find out if it's a null value object, or
 147  * otherwise use bt_value_is_null().
 148  *
 149  * The null value object singleton is always frozen (see
 150  * bt_value_freeze() and bt_value_is_frozen()).
 151  *
 152  * Functions of this API return this when the value object is actually a
 153  * null value object (of type #BT_VALUE_TYPE_NULL), whereas \c NULL
 154  * means an error of some sort.
 155  */
 156 BT_HIDDEN
 157 struct bt_value *bt_value_null;
 158
 159 /**
 160  * User function type for bt_value_map_foreach().
 161  *
 162  * \p object is a \em weak reference; you must pass it to
 163  * bt_get() to get your own reference.
 164  *
 165  * Return \c true to continue the loop, or \c false to break it.
 166  *
 167  * @param key           Key of map entry
 168  * @param object        Value object of map entry (weak reference)
 169  * @param data          User data
 170  * @returns             \c true to continue the loop
 171  */
 172 typedef bool (* bt_value_map_foreach_cb)(const char *key,
 173         struct bt_value *object, void *data);
 174
 175 /**
 176  * Recursively freezes the value object \p object.
 177  *
 178  * A frozen value object cannot be modified; it is considered immutable.
 179  * Reference counting still works on a frozen value object though: you
 180  * may pass a frozen value object to bt_get() and bt_put().
 181  *
 182  * @param object        Value object to freeze
 183  * @returns             One of #bt_value_status values; if \p object
 184  *                      is already frozen, though, #BT_VALUE_STATUS_OK
 185  *                      is returned anyway (i.e. this function never
 186  *                      returns #BT_VALUE_STATUS_FROZEN)
 187  *
 188  * @see bt_value_is_frozen()
 189  */
 190 BT_HIDDEN
 191 enum bt_value_status bt_value_freeze(struct bt_value *object);
 192
 193 /**
 194  * Checks whether \p object is frozen or not.
 195  *
 196  * @param object        Value object to check
 197  * @returns             \c true if \p object is frozen
 198  *
 199  * @see bt_value_freeze()
 200  */
 201 BT_HIDDEN
 202 bool bt_value_is_frozen(const struct bt_value *object);
 203
 204 /**
 205  * Returns the type of \p object.
 206  *
 207  * @param object        Value object of which to get the type
 208  * @returns             Value object's type, or #BT_VALUE_TYPE_UNKNOWN
 209  *                      on error
 210  *
 211  * @see #bt_value_type (value object types)
 212  * @see bt_value_is_null()
 213  * @see bt_value_is_bool()
 214  * @see bt_value_is_integer()
 215  * @see bt_value_is_float()
 216  * @see bt_value_is_string()
 217  * @see bt_value_is_array()
 218  * @see bt_value_is_map()
 219  */
 220 BT_HIDDEN
 221 enum bt_value_type bt_value_get_type(const struct bt_value *object);
 222
 223 /**
 224  * Checks whether \p object is a null value object. The only valid null
 225  * value object is \ref bt_value_null.
 226  *
 227  * @param object        Value object to check
 228  * @returns             \c true if \p object is a null value object
 229  *
 230  * @see bt_value_get_type()
 231  */
 232 static inline
 233 bool bt_value_is_null(const struct bt_value *object)
 234 {
 235         return bt_value_get_type(object) == BT_VALUE_TYPE_NULL;
 236 }
 237
 238 /**
 239  * Checks whether \p object is a boolean value object.
 240  *
 241  * @param object        Value object to check
 242  * @returns             \c true if \p object is a boolean value object
 243  *
 244  * @see bt_value_get_type()
 245  */
 246 static inline
 247 bool bt_value_is_bool(const struct bt_value *object)
 248 {
 249         return bt_value_get_type(object) == BT_VALUE_TYPE_BOOL;
 250 }
 251
 252 /**
 253  * Checks whether \p object is an integer value object.
 254  *
 255  * @param object        Value object to check
 256  * @returns             \c true if \p object is an integer value object
 257  *
 258  * @see bt_value_get_type()
 259  */
 260 static inline
 261 bool bt_value_is_integer(const struct bt_value *object)
 262 {
 263         return bt_value_get_type(object) == BT_VALUE_TYPE_INTEGER;
 264 }
 265
 266 /**
 267  * Checks whether \p object is a floating point number value object.
 268  *
 269  * @param object        Value object to check
 270  * @returns             \c true if \p object is a floating point
 271  *                      number value object
 272  *
 273  * @see bt_value_get_type()
 274  */
 275 static inline
 276 bool bt_value_is_float(const struct bt_value *object)
 277 {
 278         return bt_value_get_type(object) == BT_VALUE_TYPE_FLOAT;
 279 }
 280
 281 /**
 282  * Checks whether \p object is a string value object.
 283  *
 284  * @param object        Value object to check
 285  * @returns             \c true if \p object is a string value object
 286  *
 287  * @see bt_value_get_type()
 288  */
 289 static inline
 290 bool bt_value_is_string(const struct bt_value *object)
 291 {
 292         return bt_value_get_type(object) == BT_VALUE_TYPE_STRING;
 293 }
 294
 295 /**
 296  * Checks whether \p object is an array value object.
 297  *
 298  * @param object        Value object to check
 299  * @returns             \c true if \p object is an array value object
 300  *
 301  * @see bt_value_get_type()
 302  */
 303 static inline
 304 bool bt_value_is_array(const struct bt_value *object)
 305 {
 306         return bt_value_get_type(object) == BT_VALUE_TYPE_ARRAY;
 307 }
 308
 309 /**
 310  * Checks whether \p object is a map value object.
 311  *
 312  * @param object        Value object to check
 313  * @returns             \c true if \p object is a map value object
 314  *
 315  * @see bt_value_get_type()
 316  */
 317 static inline
 318 bool bt_value_is_map(const struct bt_value *object)
 319 {
 320         return bt_value_get_type(object) == BT_VALUE_TYPE_MAP;
 321 }
 322
 323 /**
 324  * Creates a boolean value object. The created boolean value object's
 325  * initial raw value is \c false.
 326  *
 327  * The created value object's reference count is set to 1.
 328  *
 329  * @returns     Created value object on success, or \c NULL on error
 330  *
 331  * @see bt_value_bool_create_init() (creates an initialized
 332  *                                   boolean value object)
 333  */
 334 BT_HIDDEN
 335 struct bt_value *bt_value_bool_create(void);
 336
 337 /**
 338  * Creates a boolean value object with its initial raw value set to
 339  * \p val.
 340  *
 341  * The created value object's reference count is set to 1.
 342  *
 343  * @param val   Initial raw value
 344  * @returns     Created value object on success, or \c NULL on error
 345  */
 346 BT_HIDDEN
 347 struct bt_value *bt_value_bool_create_init(bool val);
 348
 349 /**
 350  * Creates an integer value object. The created integer value object's
 351  * initial raw value is 0.
 352  *
 353  * The created value object's reference count is set to 1.
 354  *
 355  * @returns     Created value object on success, or \c NULL on error
 356  *
 357  * @see bt_value_integer_create_init() (creates an initialized
 358  *                                      integer value object)
 359  */
 360 BT_HIDDEN
 361 struct bt_value *bt_value_integer_create(void);
 362
 363 /**
 364  * Creates an integer value object with its initial raw value set to
 365  * \p val.
 366  *
 367  * The created value object's reference count is set to 1.
 368  *
 369  * @param val   Initial raw value
 370  * @returns     Created value object on success, or \c NULL on error
 371  */
 372 BT_HIDDEN
 373 struct bt_value *bt_value_integer_create_init(int64_t val);
 374
 375 /**
 376  * Creates a floating point number value object. The created floating
 377  * point number value object's initial raw value is 0.
 378  *
 379  * The created value object's reference count is set to 1.
 380  *
 381  * @returns     Created value object on success, or \c NULL on error
 382  *
 383  * @see bt_value_float_create_init() (creates an initialized floating
 384  *                                    point number value object)
 385  */
 386 BT_HIDDEN
 387 struct bt_value *bt_value_float_create(void);
 388
 389 /**
 390  * Creates a floating point number value object with its initial raw
 391  * value set to \p val.
 392  *
 393  * The created value object's reference count is set to 1.
 394  *
 395  * @param val   Initial raw value
 396  * @returns     Created value object on success, or \c NULL on error
 397  */
 398 BT_HIDDEN
 399 struct bt_value *bt_value_float_create_init(double val);
 400
 401 /**
 402  * Creates a string value object. The string value object is initially
 403  * empty.
 404  *
 405  * The created value object's reference count is set to 1.
 406  *
 407  * @returns     Created value object on success, or \c NULL on error
 408  *
 409  * @see bt_value_string_create_init() (creates an initialized
 410  *                                     string value object)
 411  */
 412 BT_HIDDEN
 413 struct bt_value *bt_value_string_create(void);
 414
 415 /**
 416  * Creates a string value object with its initial raw value set to
 417  * \p val.
 418  *
 419  * On success, \p val is \em copied.
 420  *
 421  * The created value object's reference count is set to 1.
 422  *
 423  * @param val   Initial raw value (copied on success)
 424  * @returns     Created value object on success, or \c NULL on error
 425  */
 426 BT_HIDDEN
 427 struct bt_value *bt_value_string_create_init(const char *val);
 428
 429 /**
 430  * Creates an empty array value object.
 431  *
 432  * The created value object's reference count is set to 1.
 433  *
 434  * @returns     Created value object on success, or \c NULL on error
 435  */
 436 BT_HIDDEN
 437 struct bt_value *bt_value_array_create(void);
 438
 439 /**
 440  * Creates an empty map value object.
 441  *
 442  * The created value object's reference count is set to 1.
 443  *
 444  * @returns     Created value object on success, or \c NULL on error
 445  */
 446 BT_HIDDEN
 447 struct bt_value *bt_value_map_create(void);
 448
 449 /**
 450  * Gets the boolean raw value of the boolean value object \p bool_obj.
 451  *
 452  * @param bool_obj      Boolean value object
 453  * @param val           Returned boolean raw value
 454  * @returns             One of #bt_value_status values
 455  *
 456  * @see bt_value_bool_set()
 457  */
 458 BT_HIDDEN
 459 enum bt_value_status bt_value_bool_get(
 460                 const struct bt_value *bool_obj, bool *val);
 461
 462 /**
 463  * Sets the boolean raw value of the boolean value object \p bool_obj
 464  * to \p val.
 465  *
 466  * @param bool_obj      Boolean value object
 467  * @param val           New boolean raw value
 468  * @returns             One of #bt_value_status values
 469  *
 470  * @see bt_value_bool_get()
 471  */
 472 BT_HIDDEN
 473 enum bt_value_status bt_value_bool_set(struct bt_value *bool_obj,
 474                 bool val);
 475
 476 /**
 477  * Gets the integer raw value of the integer value object
 478  * \p integer_obj.
 479  *
 480  * @param integer_obj   Integer value object
 481  * @param val           Returned integer raw value
 482  * @returns             One of #bt_value_status values
 483  *
 484  * @see bt_value_integer_set()
 485  */
 486 BT_HIDDEN
 487 enum bt_value_status bt_value_integer_get(
 488                 const struct bt_value *integer_obj, int64_t *val);
 489
 490 /**
 491  * Sets the integer raw value of the integer value object \p integer_obj
 492  * to \p val.
 493  *
 494  * @param integer_obj   Integer value object
 495  * @param val           New integer raw value
 496  * @returns             One of #bt_value_status values
 497  *
 498  * @see bt_value_integer_get()
 499  */
 500 BT_HIDDEN
 501 enum bt_value_status bt_value_integer_set(
 502                 struct bt_value *integer_obj, int64_t val);
 503
 504 /**
 505  * Gets the floating point number raw value of the floating point number
 506  * value object \p float_obj.
 507  *
 508  * @param float_obj     Floating point number value object
 509  * @param val           Returned floating point number raw value
 510  * @returns             One of #bt_value_status values
 511  *
 512  * @see bt_value_float_set()
 513  */
 514 BT_HIDDEN
 515 enum bt_value_status bt_value_float_get(
 516                 const struct bt_value *float_obj, double *val);
 517
 518 /**
 519  * Sets the floating point number raw value of the floating point number
 520  * value object \p float_obj to \p val.
 521  *
 522  * @param float_obj     Floating point number value object
 523  * @param val           New floating point number raw value
 524  * @returns             One of #bt_value_status values
 525  *
 526  * @see bt_value_float_get()
 527  */
 528 BT_HIDDEN
 529 enum bt_value_status bt_value_float_set(
 530                 struct bt_value *float_obj, double val);
 531
 532 /**
 533  * Gets the string raw value of the string value object \p string_obj.
 534  * The returned string is valid as long as this value object exists and
 535  * is not modified. The ownership of the returned string is \em not
 536  * transferred to the caller.
 537  *
 538  * @param string_obj    String value object
 539  * @param val           Returned string raw value
 540  * @returns             One of #bt_value_status values
 541  *
 542  * @see bt_value_string_set()
 543  */
 544 BT_HIDDEN
 545 enum bt_value_status bt_value_string_get(
 546                 const struct bt_value *string_obj, const char **val);
 547
 548 /**
 549  * Sets the string raw value of the string value object \p string_obj to
 550  * \p val.
 551  *
 552  * On success, \p val is \em copied.
 553  *
 554  * @param string_obj    String value object
 555  * @param val           New string raw value (copied on successf)
 556  * @returns             One of #bt_value_status values
 557  *
 558  * @see bt_value_string_get()
 559  */
 560 BT_HIDDEN
 561 enum bt_value_status bt_value_string_set(struct bt_value *string_obj,
 562                 const char *val);
 563
 564 /**
 565  * Gets the size of the array value object \p array_obj, that is, the
 566  * number of value objects contained in \p array_obj.
 567  *
 568  * @param array_obj     Array value object
 569  * @returns             Array size if the return value is 0 (empty) or a
 570  *                      positive value, or one of
 571  *                      #bt_value_status negative values otherwise
 572  *
 573  * @see bt_value_array_is_empty()
 574  */
 575 BT_HIDDEN
 576 int bt_value_array_size(const struct bt_value *array_obj);
 577
 578 /**
 579  * Returns \c true if the array value object \p array_obj is empty.
 580  *
 581  * @param array_obj     Array value object
 582  * @returns             \c true if \p array_obj is empty
 583  *
 584  * @see bt_value_array_size()
 585  */
 586 BT_HIDDEN
 587 bool bt_value_array_is_empty(const struct bt_value *array_obj);
 588
 589 /**
 590  * Gets the value object of the array value object \p array_obj at the
 591  * index \p index.
 592  *
 593  * The returned value object's reference count is incremented, unless
 594  * it's a null value object.
 595  *
 596  * @param array_obj     Array value object
 597  * @param index         Index of value object to get
 598  * @returns             Value object at index \p index on
 599  *                      success, or \c NULL on error
 600  */
 601 BT_HIDDEN
 602 struct bt_value *bt_value_array_get(const struct bt_value *array_obj,
 603                 size_t index);
 604
 605 /**
 606  * Appends the value object \p element_obj to the array value
 607  * object \p array_obj.
 608  *
 609  * The appended value object's reference count is incremented, unless
 610  * it's a null object.
 611  *
 612  * @param array_obj     Array value object
 613  * @param element_obj   Value object to append
 614  * @returns             One of #bt_value_status values
 615  *
 616  * @see bt_value_array_append_bool()
 617  * @see bt_value_array_append_integer()
 618  * @see bt_value_array_append_float()
 619  * @see bt_value_array_append_string()
 620  * @see bt_value_array_append_empty_array()
 621  * @see bt_value_array_append_empty_map()
 622  */
 623 BT_HIDDEN
 624 enum bt_value_status bt_value_array_append(struct bt_value *array_obj,
 625                 struct bt_value *element_obj);
 626
 627 /**
 628  * Appends the boolean raw value \p val to the array value object
 629  * \p array_obj. This is a convenience function which creates the
 630  * underlying boolean value object before appending it.
 631  *
 632  * The created boolean value object's reference count is set to 1.
 633  *
 634  * @param array_obj     Array value object
 635  * @param val           Boolean raw value to append
 636  * @returns             One of #bt_value_status values
 637  *
 638  * @see bt_value_array_append()
 639  */
 640 BT_HIDDEN
 641 enum bt_value_status bt_value_array_append_bool(
 642                 struct bt_value *array_obj, bool val);
 643
 644 /**
 645  * Appends the integer raw value \p val to the array value object
 646  * \p array_obj. This is a convenience function which creates the
 647  * underlying integer value object before appending it.
 648  *
 649  * The created integer value object's reference count is set to 1.
 650  *
 651  * @param array_obj     Array value object
 652  * @param val           Integer raw value to append
 653  * @returns             One of #bt_value_status values
 654  *
 655  * @see bt_value_array_append()
 656  */
 657 BT_HIDDEN
 658 enum bt_value_status bt_value_array_append_integer(
 659                 struct bt_value *array_obj, int64_t val);
 660
 661 /**
 662  * Appends the floating point number raw value \p val to the array value
 663  * object \p array_obj. This is a convenience function which creates the
 664  * underlying floating point number value object before appending it.
 665  *
 666  * The created floating point number value object's reference count is
 667  * set to 1.
 668  *
 669  * @param array_obj     Array value object
 670  * @param val           Floating point number raw value to append
 671  * @returns             One of #bt_value_status values
 672  *
 673  * @see bt_value_array_append()
 674  */
 675 BT_HIDDEN
 676 enum bt_value_status bt_value_array_append_float(
 677                 struct bt_value *array_obj, double val);
 678
 679 /**
 680  * Appends the string raw value \p val to the array value object
 681  * \p array_obj. This is a convenience function which creates the
 682  * underlying string value object before appending it.
 683  *
 684  * On success, \p val is \em copied.
 685  *
 686  * The created string value object's reference count is set to 1.
 687  *
 688  * @param array_obj     Array value object
 689  * @param val           String raw value to append (copied on success)
 690  * @returns             One of #bt_value_status values
 691  *
 692  * @see bt_value_array_append()
 693  */
 694 BT_HIDDEN
 695 enum bt_value_status bt_value_array_append_string(
 696                 struct bt_value *array_obj, const char *val);
 697
 698 /**
 699  * Appends an empty array value object to the array value object
 700  * \p array_obj. This is a convenience function which creates the
 701  * underlying array value object before appending it.
 702  *
 703  * The created array value object's reference count is set to 1.
 704  *
 705  * @param array_obj     Array value object
 706  * @returns             One of #bt_value_status values
 707  *
 708  * @see bt_value_array_append()
 709  */
 710 BT_HIDDEN
 711 enum bt_value_status bt_value_array_append_empty_array(
 712                 struct bt_value *array_obj);
 713
 714 /**
 715  * Appends an empty map value object to the array value object
 716  * \p array_obj. This is a convenience function which creates the
 717  * underlying map value object before appending it.
 718  *
 719  * The created map value object's reference count is set to 1.
 720  *
 721  * @param array_obj     Array value object
 722  * @returns             One of #bt_value_status values
 723  *
 724  * @see bt_value_array_append()
 725  */
 726 BT_HIDDEN
 727 enum bt_value_status bt_value_array_append_empty_map(
 728                 struct bt_value *array_obj);
 729
 730 /**
 731  * Replaces the value object at index \p index of the array
 732  * value object \p array_obj by \p element_obj.
 733  *
 734  * The replaced value object's reference count is decremented, unless
 735  * it's a null value object. The reference count of \p element_obj is
 736  * incremented, unless it's a null value object.
 737  *
 738  * @param array_obj     Array value object
 739  * @param index         Index of value object to replace
 740  * @param element_obj   New value object at position \p index of
 741  *                      \p array_obj
 742  * @returns             One of #bt_value_status values
 743  */
 744 BT_HIDDEN
 745 enum bt_value_status bt_value_array_set(struct bt_value *array_obj,
 746                 size_t index, struct bt_value *element_obj);
 747
 748 /**
 749  * Gets the size of a map value object, that is, the number of entries
 750  * contained in a map value object.
 751  *
 752  * @param map_obj       Map value object
 753  * @returns             Map size if the return value is 0 (empty) or a
 754  *                      positive value, or one of
 755  *                      #bt_value_status negative values otherwise
 756  *
 757  * @see bt_value_map_is_empty()
 758  */
 759 BT_HIDDEN
 760 int bt_value_map_size(const struct bt_value *map_obj);
 761
 762 /**
 763  * Returns \c true if the map value object \p map_obj is empty.
 764  *
 765  * @param map_obj       Map value object
 766  * @returns             \c true if \p map_obj is empty
 767  *
 768  * @see bt_value_map_size()
 769  */
 770 BT_HIDDEN
 771 bool bt_value_map_is_empty(const struct bt_value *map_obj);
 772
 773 /**
 774  * Gets the value object associated with the key \p key within the
 775  * map value object \p map_obj.
 776  *
 777  * The returned value object's reference count is incremented, unless
 778  * it's a null value object.
 779  *
 780  * @param map_obj       Map value object
 781  * @param key           Key of the value object to get
 782  * @returns             Value object associated with the key \p key
 783  *                      on success, or \c NULL on error
 784  */
 785 BT_HIDDEN
 786 struct bt_value *bt_value_map_get(const struct bt_value *map_obj,
 787                 const char *key);
 788
 789 /**
 790  * Calls a provided user function \p cb for each value object of the map
 791  * value object \p map_obj.
 792  *
 793  * The value object passed to the user function is a
 794  * <b>weak reference</b>: you must call bt_get() on it to obtain your own
 795  * reference.
 796  *
 797  * The key passed to the user function is only valid in the scope of
 798  * this user function call.
 799  *
 800  * The user function must return \c true to continue the loop, or
 801  * \c false to break it.
 802  *
 803  * @param map_obj       Map value object
 804  * @param cb            User function to call back
 805  * @param data          User data passed to the user function
 806  * @returns             One of #bt_value_status values; more
 807  *                      specifically, #BT_VALUE_STATUS_CANCELLED is
 808  *                      returned if the loop was cancelled by the user
 809  *                      function
 810  */
 811 BT_HIDDEN
 812 enum bt_value_status bt_value_map_foreach(
 813                 const struct bt_value *map_obj, bt_value_map_foreach_cb cb,
 814                 void *data);
 815
 816 /**
 817  * Returns whether or not the map value object \p map_obj contains the
 818  * key \p key.
 819  *
 820  * @param map_obj       Map value object
 821  * @param key           Key to check
 822  * @returns             \c true if \p map_obj contains the key \p key,
 823  *                      or \c false if it doesn't have \p key or
 824  *                      on error
 825  */
 826 BT_HIDDEN
 827 bool bt_value_map_has_key(const struct bt_value *map_obj,
 828                 const char *key);
 829
 830 /**
 831  * Inserts the value object \p element_obj associated with the key
 832  * \p key into the map value object \p map_obj. If \p key exists in
 833  * \p map_obj, the associated value object is first put, and then
 834  * replaced by \p element_obj.
 835  *
 836  * On success, \p key is \em copied.
 837  *
 838  * The inserted value object's reference count is incremented, unless
 839  * it's a null value object.
 840  *
 841  * @param map_obj       Map value object
 842  * @param key           Key (copied on success) of value object to insert
 843  * @param element_obj   Value object to insert, associated with the
 844  *                      key \p key
 845  * @returns             One of #bt_value_status values
 846  *
 847  * @see bt_value_map_insert_bool()
 848  * @see bt_value_map_insert_integer()
 849  * @see bt_value_map_insert_float()
 850  * @see bt_value_map_insert_string()
 851  * @see bt_value_map_insert_empty_array()
 852  * @see bt_value_map_insert_empty_map()
 853  */
 854 BT_HIDDEN
 855 enum bt_value_status bt_value_map_insert(
 856                 struct bt_value *map_obj, const char *key,
 857                 struct bt_value *element_obj);
 858
 859 /**
 860  * Inserts the boolean raw value \p val associated with the key \p key
 861  * into the map value object \p map_obj. This is a convenience function
 862  * which creates the underlying boolean value object before
 863  * inserting it.
 864  *
 865  * On success, \p key is \em copied.
 866  *
 867  * The created boolean value object's reference count is set to 1.
 868  *
 869  * @param map_obj       Map value object
 870  * @param key           Key (copied on success) of boolean value object
 871  *                      to insert
 872  * @param val           Boolean raw value to insert, associated with
 873  *                      the key \p key
 874  * @returns             One of #bt_value_status values
 875  *
 876  * @see bt_value_map_insert()
 877  */
 878 BT_HIDDEN
 879 enum bt_value_status bt_value_map_insert_bool(
 880                 struct bt_value *map_obj, const char *key, bool val);
 881
 882 /**
 883  * Inserts the integer raw value \p val associated with the key \p key
 884  * into the map value object \p map_obj. This is a convenience function
 885  * which creates the underlying integer value object before inserting it.
 886  *
 887  * On success, \p key is \em copied.
 888  *
 889  * The created integer value object's reference count is set to 1.
 890  *
 891  * @param map_obj       Map value object
 892  * @param key           Key (copied on success) of integer value object
 893  *                      to insert
 894  * @param val           Integer raw value to insert, associated with
 895  *                      the key \p key
 896  * @returns             One of #bt_value_status values
 897  *
 898  * @see bt_value_map_insert()
 899  */
 900 BT_HIDDEN
 901 enum bt_value_status bt_value_map_insert_integer(
 902                 struct bt_value *map_obj, const char *key, int64_t val);
 903
 904 /**
 905  * Inserts the floating point number raw value \p val associated with
 906  * the key \p key into the map value object \p map_obj. This is a
 907  * convenience function which creates the underlying floating point
 908  * number value object before inserting it.
 909  *
 910  * On success, \p key is \em copied.
 911  *
 912  * The created floating point number value object's reference count is
 913  * set to 1.
 914  *
 915  * @param map_obj       Map value object
 916  * @param key           Key (copied on success) of floating point number
 917  *                      value object to insert
 918  * @param val           Floating point number raw value to insert,
 919  *                      associated with the key \p key
 920  * @returns             One of #bt_value_status values
 921  *
 922  * @see bt_value_map_insert()
 923  */
 924 BT_HIDDEN
 925 enum bt_value_status bt_value_map_insert_float(
 926                 struct bt_value *map_obj, const char *key, double val);
 927
 928 /**
 929  * Inserts the string raw value \p val associated with the key \p key
 930  * into the map value object \p map_obj. This is a convenience function
 931  * which creates the underlying string value object before inserting it.
 932  *
 933  * On success, \p val and \p key are \em copied.
 934  *
 935  * The created string value object's reference count is set to 1.
 936  *
 937  * @param map_obj       Map value object
 938  * @param key           Key (copied on success) of string value object
 939  *                      to insert
 940  * @param val           String raw value to insert (copied on success),
 941  *                      associated with the key \p key
 942  * @returns             One of #bt_value_status values
 943  *
 944  * @see bt_value_map_insert()
 945  */
 946 BT_HIDDEN
 947 enum bt_value_status bt_value_map_insert_string(
 948                 struct bt_value *map_obj, const char *key, const char *val);
 949
 950 /**
 951  * Inserts an empty array value object associated with the key \p key
 952  * into the map value object \p map_obj. This is a convenience function
 953  * which creates the underlying array value object before inserting it.
 954  *
 955  * On success, \p key is \em copied.
 956  *
 957  * The created array value object's reference count is set to 1.
 958  *
 959  * @param map_obj       Map value object
 960  * @param key           Key (copied on success) of empty array value
 961  *                      object to insert
 962  * @returns             One of #bt_value_status values
 963  *
 964  * @see bt_value_map_insert()
 965  */
 966 BT_HIDDEN
 967 enum bt_value_status bt_value_map_insert_empty_array(
 968                 struct bt_value *map_obj, const char *key);
 969
 970 /**
 971  * Inserts an empty map value object associated with the key \p key into
 972  * the map value object \p map_obj. This is a convenience function which
 973  * creates the underlying map value object before inserting it.
 974  *
 975  * On success, \p key is \em copied.
 976  *
 977  * The created map value object's reference count is set to 1.
 978  *
 979  * @param map_obj       Map value object
 980  * @param key           Key (copied on success) of empty map value
 981  *                      object to insert
 982  * @returns             One of #bt_value_status values
 983  *
 984  * @see bt_value_map_insert()
 985  */
 986 BT_HIDDEN
 987 enum bt_value_status bt_value_map_insert_empty_map(
 988                 struct bt_value *map_obj, const char *key);
 989
 990 /**
 991  * Creates a deep copy of the value object \p object.
 992  *
 993  * The created value object's reference count is set to 1, unless
 994  * \p object is a null value object.
 995  *
 996  * Copying a frozen value object is allowed: the resulting copy is
 997  * \em not frozen.
 998  *
 999  * @param object        Value object to copy
1000  * @returns             Deep copy of \p object on success, or \c NULL
1001  *                      on error
1002  */
1003 BT_HIDDEN
1004 struct bt_value *bt_value_copy(const struct bt_value *object);
1005
1006 /**
1007  * Compares the value objects \p object_a and \p object_b and returns
1008  * \c true if they have the same \em content (raw values).
1009  *
1010  * @param object_a      Value object A
1011  * @param object_b      Value object B
1012  * @returns             \c true if \p object_a and \p object_b have the
1013  *                      same content, or \c false if they differ or on
1014  *                      error
1015  */
1016 BT_HIDDEN
1017 bool bt_value_compare(const struct bt_value *object_a,
1018                 const struct bt_value *object_b);
1019
1020 #ifdef __cplusplus
1021 }
1022 #endif
1023
1024 #endif /* _BABELTRACE_VALUES_H */