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