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