include/babeltrace2/integer-range-set.h

   1 #ifndef BABELTRACE2_INTEGER_RANGE_SET_H
   2 #define BABELTRACE2_INTEGER_RANGE_SET_H
   3
   4 /*
   5  * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
   6  *
   7  * Permission is hereby granted, free of charge, to any person obtaining a copy
   8  * of this software and associated documentation files (the "Software"), to deal
   9  * in the Software without restriction, including without limitation the rights
  10  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  11  * copies of the Software, and to permit persons to whom the Software is
  12  * furnished to do so, subject to the following conditions:
  13  *
  14  * The above copyright notice and this permission notice shall be included in
  15  * all copies or substantial portions of the Software.
  16  *
  17  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  18  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  20  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  21  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  22  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  23  * SOFTWARE.
  24  */
  25
  26 #ifndef __BT_IN_BABELTRACE_H
  27 # error "Please include <babeltrace2/babeltrace.h> instead."
  28 #endif
  29
  30 #include <stdint.h>
  31 #include <stddef.h>
  32
  33 #include <babeltrace2/types.h>
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif
  38
  39 /*!
  40 @defgroup api-int-rs Integer range sets
  41
  42 @brief
  43     Sets of unsigned and signed 64-bit integer ranges.
  44
  45 An <strong><em>integer range set</em></strong>
  46 is an \em unordered set of integer ranges.
  47
  48 An <strong><em>integer range</em></strong> represents all the
  49 integers \b 𝑥 which satisfy
  50 (<em>lower&nbsp;value</em>&nbsp;≤&nbsp;<strong>𝑥</strong>&nbsp;≤&nbsp;<em>upper&nbsp;value</em>).
  51
  52 For example, an unsigned integer range set could contain the ranges
  53 [5,&nbsp;14], [199,&nbsp;2001], and [1976,&nbsp;3000].
  54
  55 This integer range set API offers unsigned and signed 64-bit integer
  56 ranges and integer range sets with dedicated C&nbsp;types:
  57
  58 - #bt_integer_range_unsigned
  59 - #bt_integer_range_signed
  60 - #bt_integer_range_set_unsigned
  61 - #bt_integer_range_set_signed
  62
  63 This API uses the \em abstract #bt_integer_range_set type for common
  64 properties and operations (for example,
  65 bt_integer_range_set_get_range_count()).
  66 \ref api-fund-c-typing "Upcast" a specific
  67 integer range set to the #bt_integer_range_set type with
  68 bt_integer_range_set_unsigned_as_range_set_const() or
  69 bt_integer_range_set_signed_as_range_set_const().
  70
  71 An integer range set is a \ref api-fund-shared-object "shared object":
  72 get a new reference with bt_integer_range_set_unsigned_get_ref() or
  73 bt_integer_range_set_signed_get_ref() and put an existing reference with
  74 bt_integer_range_set_unsigned_put_ref() or
  75 bt_integer_range_set_signed_put_ref().
  76
  77 An integer range is a \ref api-fund-unique-object "unique object": it
  78 belongs to the integer range set which contains it.
  79
  80 Some library functions \ref api-fund-freezing "freeze" integer range
  81 sets on success. The documentation of those functions indicate this
  82 postcondition.
  83
  84 Create an empty integer range set with
  85 bt_integer_range_set_unsigned_create() or
  86 bt_integer_range_set_signed_create().
  87
  88 Add an integer range to an integer range set with
  89 bt_integer_range_set_unsigned_add_range() or
  90 bt_integer_range_set_signed_add_range(). Although integer ranges can
  91 overlap, specific functions of the \bt_api expect an integer range set
  92 with non-overlapping integer ranges.
  93
  94 As of \bt_name_version_min_maj, you cannot remove an existing
  95 integer range from an integer range set.
  96
  97 Check that two integer ranges are equal with
  98 bt_integer_range_unsigned_is_equal() or
  99 bt_integer_range_signed_is_equal().
 100
 101 Check that two integer range sets are equal with
 102 bt_integer_range_set_unsigned_is_equal() or
 103 bt_integer_range_set_signed_is_equal().
 104 */
 105
 106 /*! @{ */
 107
 108 /*!
 109 @name Types
 110 @{
 111
 112 @typedef struct bt_integer_range_unsigned bt_integer_range_unsigned
 113
 114 @brief
 115     Unsigned 64-bit integer range.
 116
 117
 118 @typedef struct bt_integer_range_signed bt_integer_range_signed
 119
 120 @brief
 121     Signed 64-bit integer range.
 122
 123
 124 @typedef struct bt_integer_range_set bt_integer_range_set
 125
 126 @brief
 127     Set of 64-bit integer ranges.
 128
 129 This is an abstract type for common properties and operations. See \ref
 130 api-fund-c-typing to learn more about conceptual object type
 131 inheritance.
 132
 133
 134 @typedef struct bt_integer_range_set_unsigned bt_integer_range_set_unsigned;
 135
 136 @brief
 137     Set of unsigned 64-bit integer ranges.
 138
 139
 140 @typedef struct bt_integer_range_set_signed bt_integer_range_set_signed;
 141
 142 @brief
 143     Set of signed 64-bit integer ranges.
 144
 145 @}
 146 */
 147
 148 /*!
 149 @name Unsigned integer range
 150 @{
 151 */
 152
 153 /*!
 154 @brief
 155     Returns the lower value of the unsigned integer range
 156     \bt_p{int_range}.
 157
 158 The returned lower value is included in \bt_p{int_range}.
 159
 160 @param[in] int_range
 161     Unsigned integer range of which to get the lower value.
 162
 163 @returns
 164     Lower value of \bt_p{int_range}.
 165
 166 @bt_pre_not_null{int_range}
 167 @bt_pre_is_bool_val{int_range}
 168 */
 169 extern uint64_t bt_integer_range_unsigned_get_lower(
 170                 const bt_integer_range_unsigned *int_range);
 171
 172 /*!
 173 @brief
 174     Returns the upper value of the unsigned integer range
 175     \bt_p{int_range}.
 176
 177 The returned upper value is included in \bt_p{int_range}.
 178
 179 @param[in] int_range
 180     Unsigned integer range of which to get the upper value.
 181
 182 @returns
 183     Upper value of \bt_p{int_range}.
 184
 185 @bt_pre_not_null{int_range}
 186 @bt_pre_is_bool_val{int_range}
 187 */
 188 extern uint64_t bt_integer_range_unsigned_get_upper(
 189                 const bt_integer_range_unsigned *int_range);
 190
 191 /*!
 192 @brief
 193     Returns whether or not the unsigned integer range
 194     \bt_p{a_int_range} is equal to \bt_p{b_int_range}.
 195
 196 Two unsigned integer ranges are considered equal if they have the same
 197 lower and upper values.
 198
 199 @param[in] a_int_range
 200     Unsigned integer range A.
 201 @param[in] b_int_range
 202     Unsigned integer range B.
 203
 204 @returns
 205     #BT_TRUE if \bt_p{a_int_range} is equal to
 206     \bt_p{b_int_range}.
 207
 208 @bt_pre_not_null{a_int_range}
 209 @bt_pre_not_null{b_int_range}
 210 */
 211 extern bt_bool bt_integer_range_unsigned_is_equal(
 212                 const bt_integer_range_unsigned *a_int_range,
 213                 const bt_integer_range_unsigned *b_int_range);
 214
 215 /*! @} */
 216
 217 /*!
 218 @name Signed integer range
 219 @{
 220 */
 221
 222 /*!
 223 @brief
 224     Returns the lower value of the signed integer range
 225     \bt_p{int_range}.
 226
 227 The returned lower value is included in \bt_p{int_range}.
 228
 229 @param[in] int_range
 230     Signed integer range of which to get the lower value.
 231
 232 @returns
 233     Lower value of \bt_p{int_range}.
 234
 235 @bt_pre_not_null{int_range}
 236 @bt_pre_is_bool_val{int_range}
 237 */
 238 extern int64_t bt_integer_range_signed_get_lower(
 239                 const bt_integer_range_signed *int_range);
 240
 241 /*!
 242 @brief
 243     Returns the upper value of the signed integer range
 244     \bt_p{int_range}.
 245
 246 The returned upper value is included in \bt_p{int_range}.
 247
 248 @param[in] int_range
 249     Signed integer range of which to get the upper value.
 250
 251 @returns
 252     Upper value of \bt_p{int_range}.
 253
 254 @bt_pre_not_null{int_range}
 255 @bt_pre_is_bool_val{int_range}
 256 */
 257 extern int64_t bt_integer_range_signed_get_upper(
 258                 const bt_integer_range_signed *int_range);
 259
 260 /*!
 261 @brief
 262     Returns whether or not the signed integer range
 263     \bt_p{a_int_range} is equal to \bt_p{b_int_range}.
 264
 265 Two signed integer ranges are considered equal if they have the same
 266 lower and upper values.
 267
 268 @param[in] a_int_range
 269     Signed integer range A.
 270 @param[in] b_int_range
 271     Signed integer range B.
 272
 273 @returns
 274     #BT_TRUE if \bt_p{a_int_range} is equal to
 275     \bt_p{b_int_range}.
 276
 277 @bt_pre_not_null{a_int_range}
 278 @bt_pre_not_null{b_int_range}
 279 */
 280 extern bt_bool bt_integer_range_signed_is_equal(
 281                 const bt_integer_range_signed *a_int_range,
 282                 const bt_integer_range_signed *b_int_range);
 283
 284 /*! @} */
 285
 286 /*!
 287 @name Integer range set: common
 288 @{
 289 */
 290
 291 /*!
 292 @brief
 293     Status codes for bt_integer_range_set_unsigned_add_range() and
 294     bt_integer_range_set_signed_add_range().
 295 */
 296 typedef enum bt_integer_range_set_add_range_status {
 297         /*!
 298         @brief
 299             Success.
 300         */
 301         BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK                = __BT_FUNC_STATUS_OK,
 302
 303         /*!
 304         @brief
 305             Out of memory.
 306         */
 307         BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
 308 } bt_integer_range_set_add_range_status;
 309
 310 /*!
 311 @brief
 312     Returns the number of integer ranges contained in the integer
 313     range set \bt_p{int_range_set}.
 314
 315 @note
 316     The parameter \bt_p{int_range_set} has the abstract type
 317     #bt_integer_range_set: use
 318     bt_integer_range_set_unsigned_as_range_set_const() or
 319     bt_integer_range_set_signed_as_range_set_const() to upcast a
 320     specific integer range set to this type.
 321
 322 @param[in] int_range_set
 323     Integer range set of which to get the number of contained integer
 324     ranges.
 325
 326 @returns
 327     Number of contained integer ranges in \bt_p{int_range_set}.
 328
 329 @bt_pre_not_null{int_range_set}
 330 */
 331 extern uint64_t bt_integer_range_set_get_range_count(
 332                 const bt_integer_range_set *int_range_set);
 333
 334 /*! @} */
 335
 336 /*!
 337 @name Unsigned integer range set
 338 @{
 339 */
 340
 341 /*!
 342 @brief
 343     Creates and returns an empty set of unsigned 64-bit integer ranges.
 344
 345 @returns
 346     New unsigned integer range set, or \c NULL on memory error.
 347 */
 348 extern bt_integer_range_set_unsigned *bt_integer_range_set_unsigned_create(void);
 349
 350 /*!
 351 @brief
 352     Adds an unsigned 64-bit integer range having the lower value
 353     \bt_p{lower} and the upper value \bt_p{upper} to the unsigned
 354     integer range set
 355     \bt_p{int_range_set}.
 356
 357 The values \bt_p{lower} and \bt_p{upper} are included in the unsigned
 358 integer range to add to \bt_p{int_range_set}.
 359
 360 @param[in] int_range_set
 361     Unsigned integer range set to which to add an unsigned integer
 362     range.
 363 @param[in] lower
 364     Lower value (included) of the unsigned integer range to add to
 365     \bt_p{int_range_set}.
 366 @param[in] upper
 367     Upper value (included) of the unsigned integer range to add to
 368     \bt_p{int_range_set}.
 369
 370 @retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK
 371     Success.
 372 @retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR
 373     Out of memory.
 374
 375 @bt_pre_not_null{int_range_set}
 376 @bt_pre_hot{int_range_set}
 377 @pre
 378     \bt_p{lower} ≤ \bt_p{upper}.
 379 */
 380 extern bt_integer_range_set_add_range_status
 381 bt_integer_range_set_unsigned_add_range(
 382                 bt_integer_range_set_unsigned *int_range_set,
 383                 uint64_t lower, uint64_t upper);
 384
 385 /*!
 386 @brief
 387     Borrows the unsigned integer range at index \bt_p{index} from the
 388     unsigned integer range set \bt_p{int_range_set}.
 389
 390 @param[in] int_range_set
 391     Unsigned integer range set from which to borrow the unsigned integer
 392     range at index \bt_p{index}.
 393 @param[in] index
 394     Index of the unsigned integer range to borrow from
 395     \bt_p{int_range_set}.
 396
 397 @returns
 398     @parblock
 399     \em Borrowed reference of the unsigned integer range of
 400     \bt_p{int_range_set} at index \bt_p{index}.
 401
 402     The returned pointer remains valid until \bt_p{int_range_set} is
 403     modified.
 404     @endparblock
 405
 406 @bt_pre_not_null{int_range_set}
 407 @pre
 408     \bt_p{index} is less than the number of unsigned integer ranges in
 409     \bt_p{int_range_set} (as returned by
 410     bt_integer_range_set_get_range_count()).
 411 */
 412 extern const bt_integer_range_unsigned *
 413 bt_integer_range_set_unsigned_borrow_range_by_index_const(
 414                 const bt_integer_range_set_unsigned *int_range_set,
 415                 uint64_t index);
 416
 417 /*!
 418 @brief
 419     Returns whether or not the unsigned integer range set
 420     \bt_p{int_range_set_a} is equal to \bt_p{int_range_set_b}.
 421
 422 Two unsigned integer range sets are considered equal if they contain the
 423 exact same unsigned integer ranges, whatever the order. In other words,
 424 an unsigned integer range set containing [2,&nbsp;9] and [10,&nbsp;15]
 425 is \em not equal to an unsigned integer range containing [2,&nbsp;15].
 426
 427 @param[in] int_range_set_a
 428     Unsigned integer range set A.
 429 @param[in] int_range_set_b
 430     Unsigned integer range set B.
 431
 432 @returns
 433     #BT_TRUE if \bt_p{int_range_set_a} is equal to
 434     \bt_p{int_range_set_b}.
 435
 436 @bt_pre_not_null{int_range_set_a}
 437 @bt_pre_not_null{int_range_set_b}
 438 */
 439 extern bt_bool bt_integer_range_set_unsigned_is_equal(
 440                 const bt_integer_range_set_unsigned *int_range_set_a,
 441                 const bt_integer_range_set_unsigned *int_range_set_b);
 442
 443 /*!
 444 @brief
 445     \ref api-fund-c-typing "Upcasts" the unsigned integer range set
 446     \bt_p{int_range_set} to the abstract #bt_integer_range_set type.
 447
 448 @param[in] int_range_set
 449     @parblock
 450     Unsigned integer range set to upcast.
 451
 452     Can be \c NULL.
 453     @endparblock
 454
 455 @returns
 456     \bt_p{int_range_set} as an abstract integer range set.
 457 */
 458 static inline
 459 const bt_integer_range_set *bt_integer_range_set_unsigned_as_range_set_const(
 460                 const bt_integer_range_set_unsigned *int_range_set)
 461 {
 462         return __BT_UPCAST_CONST(bt_integer_range_set, int_range_set);
 463 }
 464
 465 /*!
 466 @brief
 467     Increments the \ref api-fund-shared-object "reference count" of
 468     the unsigned integer range set \bt_p{int_range_set}.
 469
 470 @param[in] int_range_set
 471     @parblock
 472     Unsigned integer range set of which to increment the reference
 473     count.
 474
 475     Can be \c NULL.
 476     @endparblock
 477
 478 @sa bt_integer_range_set_unsigned_put_ref() &mdash;
 479     Decrements the reference count of an unsigned integer range set.
 480 */
 481 extern void bt_integer_range_set_unsigned_get_ref(
 482                 const bt_integer_range_set_unsigned *int_range_set);
 483
 484 /*!
 485 @brief
 486     Decrements the \ref api-fund-shared-object "reference count" of
 487     the unsigned integer range set \bt_p{int_range_set}.
 488
 489 @param[in] int_range_set
 490     @parblock
 491     Unsigned integer range set of which to decrement the reference
 492     count.
 493
 494     Can be \c NULL.
 495     @endparblock
 496
 497 @sa bt_integer_range_set_unsigned_get_ref() &mdash;
 498     Increments the reference count of an unsigned integer range set.
 499 */
 500 extern void bt_integer_range_set_unsigned_put_ref(
 501                 const bt_integer_range_set_unsigned *int_range_set);
 502
 503 /*!
 504 @brief
 505     Decrements the reference count of the unsigned integer range set
 506     \bt_p{_int_range_set}, and then sets \bt_p{_int_range_set} to \c
 507     NULL.
 508
 509 @param _int_range_set
 510     @parblock
 511     Unsigned integer range set of which to decrement the reference
 512     count.
 513
 514     Can contain \c NULL.
 515     @endparblock
 516
 517 @bt_pre_assign_expr{_int_range_set}
 518 */
 519 #define BT_INTEGER_RANGE_SET_UNSIGNED_PUT_REF_AND_RESET(_int_range_set) \
 520         do {                                                            \
 521                 bt_integer_range_set_unsigned_put_ref(_int_range_set);  \
 522                 (_int_range_set) = NULL;                                \
 523         } while (0)
 524
 525 /*!
 526 @brief
 527     Decrements the reference count of the unsigned integer range set
 528     \bt_p{_dst}, sets \bt_p{_dst} to \bt_p{_src}, and then sets
 529     \bt_p{_src} to \c NULL.
 530
 531 This macro effectively moves an unsigned integer range set reference
 532 from the expression \bt_p{_src} to the expression \bt_p{_dst}, putting
 533 the existing \bt_p{_dst} reference.
 534
 535 @param _dst
 536     @parblock
 537     Destination expression.
 538
 539     Can contain \c NULL.
 540     @endparblock
 541 @param _src
 542     @parblock
 543     Source expression.
 544
 545     Can contain \c NULL.
 546     @endparblock
 547
 548 @bt_pre_assign_expr{_dst}
 549 @bt_pre_assign_expr{_src}
 550 */
 551 #define BT_INTEGER_RANGE_SET_UNSIGNED_MOVE_REF(_dst, _src)      \
 552         do {                                                    \
 553                 bt_integer_range_set_unsigned_put_ref(_dst);    \
 554                 (_dst) = (_src);                                \
 555                 (_src) = NULL;                                  \
 556         } while (0)
 557
 558 /*! @} */
 559
 560 /*!
 561 @name Signed integer range set
 562 @{
 563 */
 564
 565 /*!
 566 @brief
 567     Creates and returns an empty set of signed 64-bit integer ranges.
 568
 569 @returns
 570     New signed integer range set, or \c NULL on memory error.
 571 */
 572 extern bt_integer_range_set_signed *bt_integer_range_set_signed_create(void);
 573
 574 /*!
 575 @brief
 576     Adds a signed 64-bit integer range having the lower value
 577     \bt_p{lower} and the upper value \bt_p{upper} to the signed
 578     integer range set
 579     \bt_p{int_range_set}.
 580
 581 The values \bt_p{lower} and \bt_p{upper} are included in the signed
 582 integer range to add to \bt_p{int_range_set}.
 583
 584 @param[in] int_range_set
 585     Signed integer range set to which to add a signed integer
 586     range.
 587 @param[in] lower
 588     Lower value (included) of the signed integer range to add to
 589     \bt_p{int_range_set}.
 590 @param[in] upper
 591     Upper value (included) of the signed integer range to add to
 592     \bt_p{int_range_set}.
 593
 594 @retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK
 595     Success.
 596 @retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR
 597     Out of memory.
 598
 599 @bt_pre_not_null{int_range_set}
 600 @bt_pre_hot{int_range_set}
 601 @pre
 602     \bt_p{lower} ≤ \bt_p{upper}.
 603 */
 604 extern bt_integer_range_set_add_range_status
 605 bt_integer_range_set_signed_add_range(
 606                 bt_integer_range_set_signed *int_range_set,
 607                 int64_t lower, int64_t upper);
 608
 609 /*!
 610 @brief
 611     Borrows the signed integer range at index \bt_p{index} from the
 612     signed integer range set \bt_p{int_range_set}.
 613
 614 @param[in] int_range_set
 615     Signed integer range set from which to borrow the signed integer
 616     range at index \bt_p{index}.
 617 @param[in] index
 618     Index of the signed integer range to borrow from
 619     \bt_p{int_range_set}.
 620
 621 @returns
 622     @parblock
 623     \em Borrowed reference of the signed integer range of
 624     \bt_p{int_range_set} at index \bt_p{index}.
 625
 626     The returned pointer remains valid until \bt_p{int_range_set} is
 627     modified.
 628     @endparblock
 629
 630 @bt_pre_not_null{int_range_set}
 631 @pre
 632     \bt_p{index} is less than the number of signed integer ranges in
 633     \bt_p{int_range_set} (as returned by
 634     bt_integer_range_set_get_range_count()).
 635 */
 636 extern const bt_integer_range_signed *
 637 bt_integer_range_set_signed_borrow_range_by_index_const(
 638                 const bt_integer_range_set_signed *int_range_set, uint64_t index);
 639
 640 /*!
 641 @brief
 642     Returns whether or not the signed integer range set
 643     \bt_p{int_range_set_a} is equal to \bt_p{int_range_set_b}.
 644
 645 Two signed integer range sets are considered equal if they contain the
 646 exact same signed integer ranges, whatever the order. In other words,
 647 a signed integer range set containing [-57,&nbsp;23] and [24,&nbsp;42]
 648 is \em not equal to a signed integer range containing [-57,&nbsp;42].
 649
 650 @param[in] int_range_set_a
 651     Signed integer range set A.
 652 @param[in] int_range_set_b
 653     Signed integer range set B.
 654
 655 @returns
 656     #BT_TRUE if \bt_p{int_range_set_a} is equal to
 657     \bt_p{int_range_set_b}.
 658
 659 @bt_pre_not_null{int_range_set_a}
 660 @bt_pre_not_null{int_range_set_b}
 661 */
 662 extern bt_bool bt_integer_range_set_signed_is_equal(
 663                 const bt_integer_range_set_signed *int_range_set_a,
 664                 const bt_integer_range_set_signed *int_range_set_b);
 665
 666 /*!
 667 @brief
 668     \ref api-fund-c-typing "Upcasts" the signed integer range set
 669     \bt_p{int_range_set} to the abstract #bt_integer_range_set type.
 670
 671 @param[in] int_range_set
 672     @parblock
 673     Signed integer range set to upcast.
 674
 675     Can be \c NULL.
 676     @endparblock
 677
 678 @returns
 679     \bt_p{int_range_set} as an abstract integer range set.
 680 */
 681 static inline
 682 const bt_integer_range_set *bt_integer_range_set_signed_as_range_set_const(
 683                 const bt_integer_range_set_signed *int_range_set)
 684 {
 685         return __BT_UPCAST_CONST(bt_integer_range_set, int_range_set);
 686 }
 687
 688 /*!
 689 @brief
 690     Increments the \ref api-fund-shared-object "reference count" of
 691     the signed integer range set \bt_p{int_range_set}.
 692
 693 @param[in] int_range_set
 694     @parblock
 695     Signed integer range set of which to increment the reference
 696     count.
 697
 698     Can be \c NULL.
 699     @endparblock
 700
 701 @sa bt_integer_range_set_signed_put_ref() &mdash;
 702     Decrements the reference count of a signed integer range set.
 703 */
 704 extern void bt_integer_range_set_signed_get_ref(
 705                 const bt_integer_range_set_signed *int_range_set);
 706
 707 /*!
 708 @brief
 709     Decrements the \ref api-fund-shared-object "reference count" of
 710     the signed integer range set \bt_p{int_range_set}.
 711
 712 @param[in] int_range_set
 713     @parblock
 714     Signed integer range set of which to decrement the reference
 715     count.
 716
 717     Can be \c NULL.
 718     @endparblock
 719
 720 @sa bt_integer_range_set_signed_get_ref() &mdash;
 721     Increments the reference count of a signed integer range set.
 722 */
 723 extern void bt_integer_range_set_signed_put_ref(
 724                 const bt_integer_range_set_signed *int_range_set);
 725
 726 /*!
 727 @brief
 728     Decrements the reference count of the signed integer range set
 729     \bt_p{_int_range_set}, and then sets \bt_p{_int_range_set} to \c
 730     NULL.
 731
 732 @param _int_range_set
 733     @parblock
 734     Signed integer range set of which to decrement the reference
 735     count.
 736
 737     Can contain \c NULL.
 738     @endparblock
 739
 740 @bt_pre_assign_expr{_int_range_set}
 741 */
 742 #define BT_INTEGER_RANGE_SET_SIGNED_PUT_REF_AND_RESET(_int_range_set)   \
 743         do {                                                            \
 744                 bt_integer_range_set_signed_put_ref(_int_range_set);    \
 745                 (_int_range_set) = NULL;                                \
 746         } while (0)
 747
 748 /*!
 749 @brief
 750     Decrements the reference count of the signed integer range set
 751     \bt_p{_dst}, sets \bt_p{_dst} to \bt_p{_src}, and then sets
 752     \bt_p{_src} to \c NULL.
 753
 754 This macro effectively moves a signed integer range set reference
 755 from the expression \bt_p{_src} to the expression \bt_p{_dst}, putting
 756 the existing \bt_p{_dst} reference.
 757
 758 @param _dst
 759     @parblock
 760     Destination expression.
 761
 762     Can contain \c NULL.
 763     @endparblock
 764 @param _src
 765     @parblock
 766     Source expression.
 767
 768     Can contain \c NULL.
 769     @endparblock
 770
 771 @bt_pre_assign_expr{_dst}
 772 @bt_pre_assign_expr{_src}
 773 */
 774 #define BT_INTEGER_RANGE_SET_SIGNED_MOVE_REF(_dst, _src)        \
 775         do {                                                    \
 776                 bt_integer_range_set_signed_put_ref(_dst);      \
 777                 (_dst) = (_src);                                \
 778                 (_src) = NULL;                                  \
 779         } while (0)
 780
 781 /*! @} */
 782
 783 /*! @} */
 784
 785 #ifdef __cplusplus
 786 }
 787 #endif
 788
 789 #endif /* BABELTRACE2_INTEGER_RANGE_SET_H */