2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_INTEGER_RANGE_SET_H
8 #define BABELTRACE2_INTEGER_RANGE_SET_H
10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
19 #include <babeltrace2/types.h>
26 @defgroup api-int-rs Integer range sets
29 Sets of unsigned and signed 64-bit integer ranges.
31 An <strong><em>integer range set</em></strong>
32 is an \em unordered set of integer ranges.
34 An <strong><em>integer range</em></strong> represents all the
35 integers \b 𝑥 which satisfy
36 (<em>lower value</em> ≤ <strong>𝑥</strong> ≤ <em>upper value</em>).
38 For example, an unsigned integer range set could contain the ranges
39 [5, 14], [199, 2001], and [1976, 3000].
41 This integer range set API offers unsigned and signed 64-bit integer
42 ranges and integer range sets with dedicated C types:
44 - #bt_integer_range_unsigned
45 - #bt_integer_range_signed
46 - #bt_integer_range_set_unsigned
47 - #bt_integer_range_set_signed
49 This API uses the \em abstract #bt_integer_range_set type for common
50 properties and operations (for example,
51 bt_integer_range_set_get_range_count()).
52 \ref api-fund-c-typing "Upcast" a specific
53 integer range set to the #bt_integer_range_set type with
54 bt_integer_range_set_unsigned_as_range_set_const() or
55 bt_integer_range_set_signed_as_range_set_const().
57 An integer range set is a \ref api-fund-shared-object "shared object":
58 get a new reference with bt_integer_range_set_unsigned_get_ref() or
59 bt_integer_range_set_signed_get_ref() and put an existing reference with
60 bt_integer_range_set_unsigned_put_ref() or
61 bt_integer_range_set_signed_put_ref().
63 An integer range is a \ref api-fund-unique-object "unique object": it
64 belongs to the integer range set which contains it.
66 Some library functions \ref api-fund-freezing "freeze" integer range
67 sets on success. The documentation of those functions indicate this
70 Create an empty integer range set with
71 bt_integer_range_set_unsigned_create() or
72 bt_integer_range_set_signed_create().
74 Add an integer range to an integer range set with
75 bt_integer_range_set_unsigned_add_range() or
76 bt_integer_range_set_signed_add_range(). Although integer ranges can
77 overlap, specific functions of the \bt_api expect an integer range set
78 with non-overlapping integer ranges.
80 As of \bt_name_version_min_maj, you cannot remove an existing
81 integer range from an integer range set.
83 Check that two integer ranges are equal with
84 bt_integer_range_unsigned_is_equal() or
85 bt_integer_range_signed_is_equal().
87 Check that two integer range sets are equal with
88 bt_integer_range_set_unsigned_is_equal() or
89 bt_integer_range_set_signed_is_equal().
98 @typedef struct bt_integer_range_unsigned bt_integer_range_unsigned
101 Unsigned 64-bit integer range.
103 @typedef struct bt_integer_range_signed bt_integer_range_signed
106 Signed 64-bit integer range.
108 @typedef struct bt_integer_range_set bt_integer_range_set
111 Set of 64-bit integer ranges.
113 This is an abstract type for common properties and operations. See \ref
114 api-fund-c-typing to learn more about conceptual object type
117 @typedef struct bt_integer_range_set_unsigned bt_integer_range_set_unsigned;
120 Set of unsigned 64-bit integer ranges.
122 @typedef struct bt_integer_range_set_signed bt_integer_range_set_signed;
125 Set of signed 64-bit integer ranges.
131 @name Unsigned integer range
137 Returns the lower value of the unsigned integer range
140 The returned lower value is included in \bt_p{int_range}.
143 Unsigned integer range of which to get the lower value.
146 Lower value of \bt_p{int_range}.
148 @bt_pre_not_null{int_range}
149 @bt_pre_is_bool_val{int_range}
151 extern uint64_t bt_integer_range_unsigned_get_lower(
152 const bt_integer_range_unsigned
*int_range
) __BT_NOEXCEPT
;
156 Returns the upper value of the unsigned integer range
159 The returned upper value is included in \bt_p{int_range}.
162 Unsigned integer range of which to get the upper value.
165 Upper value of \bt_p{int_range}.
167 @bt_pre_not_null{int_range}
168 @bt_pre_is_bool_val{int_range}
170 extern uint64_t bt_integer_range_unsigned_get_upper(
171 const bt_integer_range_unsigned
*int_range
) __BT_NOEXCEPT
;
175 Returns whether or not the unsigned integer range
176 \bt_p{a_int_range} is equal to \bt_p{b_int_range}.
178 Two unsigned integer ranges are considered equal if they have the same
179 lower and upper values.
181 @param[in] a_int_range
182 Unsigned integer range A.
183 @param[in] b_int_range
184 Unsigned integer range B.
187 #BT_TRUE if \bt_p{a_int_range} is equal to
190 @bt_pre_not_null{a_int_range}
191 @bt_pre_not_null{b_int_range}
193 extern bt_bool
bt_integer_range_unsigned_is_equal(
194 const bt_integer_range_unsigned
*a_int_range
,
195 const bt_integer_range_unsigned
*b_int_range
) __BT_NOEXCEPT
;
200 @name Signed integer range
206 Returns the lower value of the signed integer range
209 The returned lower value is included in \bt_p{int_range}.
212 Signed integer range of which to get the lower value.
215 Lower value of \bt_p{int_range}.
217 @bt_pre_not_null{int_range}
218 @bt_pre_is_bool_val{int_range}
220 extern int64_t bt_integer_range_signed_get_lower(
221 const bt_integer_range_signed
*int_range
) __BT_NOEXCEPT
;
225 Returns the upper value of the signed integer range
228 The returned upper value is included in \bt_p{int_range}.
231 Signed integer range of which to get the upper value.
234 Upper value of \bt_p{int_range}.
236 @bt_pre_not_null{int_range}
237 @bt_pre_is_bool_val{int_range}
239 extern int64_t bt_integer_range_signed_get_upper(
240 const bt_integer_range_signed
*int_range
) __BT_NOEXCEPT
;
244 Returns whether or not the signed integer range
245 \bt_p{a_int_range} is equal to \bt_p{b_int_range}.
247 Two signed integer ranges are considered equal if they have the same
248 lower and upper values.
250 @param[in] a_int_range
251 Signed integer range A.
252 @param[in] b_int_range
253 Signed integer range B.
256 #BT_TRUE if \bt_p{a_int_range} is equal to
259 @bt_pre_not_null{a_int_range}
260 @bt_pre_not_null{b_int_range}
262 extern bt_bool
bt_integer_range_signed_is_equal(
263 const bt_integer_range_signed
*a_int_range
,
264 const bt_integer_range_signed
*b_int_range
) __BT_NOEXCEPT
;
269 @name Integer range set: common
275 Status codes for bt_integer_range_set_unsigned_add_range() and
276 bt_integer_range_set_signed_add_range().
278 typedef enum bt_integer_range_set_add_range_status
{
283 BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK
= __BT_FUNC_STATUS_OK
,
289 BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
290 } bt_integer_range_set_add_range_status
;
294 Returns the number of integer ranges contained in the integer
295 range set \bt_p{int_range_set}.
298 The parameter \bt_p{int_range_set} has the abstract type
299 #bt_integer_range_set: use
300 bt_integer_range_set_unsigned_as_range_set_const() or
301 bt_integer_range_set_signed_as_range_set_const() to upcast a
302 specific integer range set to this type.
304 @param[in] int_range_set
305 Integer range set of which to get the number of contained integer
309 Number of contained integer ranges in \bt_p{int_range_set}.
311 @bt_pre_not_null{int_range_set}
313 extern uint64_t bt_integer_range_set_get_range_count(
314 const bt_integer_range_set
*int_range_set
) __BT_NOEXCEPT
;
319 @name Unsigned integer range set
325 Creates and returns an empty set of unsigned 64-bit integer ranges.
328 New unsigned integer range set, or \c NULL on memory error.
330 extern bt_integer_range_set_unsigned
*bt_integer_range_set_unsigned_create(
335 Adds an unsigned 64-bit integer range having the lower value
336 \bt_p{lower} and the upper value \bt_p{upper} to the unsigned
338 \bt_p{int_range_set}.
340 The values \bt_p{lower} and \bt_p{upper} are included in the unsigned
341 integer range to add to \bt_p{int_range_set}.
343 @param[in] int_range_set
344 Unsigned integer range set to which to add an unsigned integer
347 Lower value (included) of the unsigned integer range to add to
348 \bt_p{int_range_set}.
350 Upper value (included) of the unsigned integer range to add to
351 \bt_p{int_range_set}.
353 @retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK
355 @retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR
358 @bt_pre_not_null{int_range_set}
359 @bt_pre_hot{int_range_set}
361 \bt_p{lower} ≤ \bt_p{upper}.
363 extern bt_integer_range_set_add_range_status
364 bt_integer_range_set_unsigned_add_range(
365 bt_integer_range_set_unsigned
*int_range_set
,
366 uint64_t lower
, uint64_t upper
) __BT_NOEXCEPT
;
370 Borrows the unsigned integer range at index \bt_p{index} from the
371 unsigned integer range set \bt_p{int_range_set}.
373 @param[in] int_range_set
374 Unsigned integer range set from which to borrow the unsigned integer
375 range at index \bt_p{index}.
377 Index of the unsigned integer range to borrow from
378 \bt_p{int_range_set}.
382 \em Borrowed reference of the unsigned integer range of
383 \bt_p{int_range_set} at index \bt_p{index}.
385 The returned pointer remains valid until \bt_p{int_range_set} is
389 @bt_pre_not_null{int_range_set}
391 \bt_p{index} is less than the number of unsigned integer ranges in
392 \bt_p{int_range_set} (as returned by
393 bt_integer_range_set_get_range_count()).
395 extern const bt_integer_range_unsigned
*
396 bt_integer_range_set_unsigned_borrow_range_by_index_const(
397 const bt_integer_range_set_unsigned
*int_range_set
,
398 uint64_t index
) __BT_NOEXCEPT
;
402 Returns whether or not the unsigned integer range set
403 \bt_p{int_range_set_a} is equal to \bt_p{int_range_set_b}.
405 Two unsigned integer range sets are considered equal if they contain the
406 exact same unsigned integer ranges, whatever the order. In other words,
407 an unsigned integer range set containing [2, 9] and [10, 15]
408 is \em not equal to an unsigned integer range containing [2, 15].
410 @param[in] int_range_set_a
411 Unsigned integer range set A.
412 @param[in] int_range_set_b
413 Unsigned integer range set B.
416 #BT_TRUE if \bt_p{int_range_set_a} is equal to
417 \bt_p{int_range_set_b}.
419 @bt_pre_not_null{int_range_set_a}
420 @bt_pre_not_null{int_range_set_b}
422 extern bt_bool
bt_integer_range_set_unsigned_is_equal(
423 const bt_integer_range_set_unsigned
*int_range_set_a
,
424 const bt_integer_range_set_unsigned
*int_range_set_b
)
429 \ref api-fund-c-typing "Upcasts" the unsigned integer range set
430 \bt_p{int_range_set} to the abstract #bt_integer_range_set type.
432 @param[in] int_range_set
434 Unsigned integer range set to upcast.
440 \bt_p{int_range_set} as an abstract integer range set.
443 const bt_integer_range_set
*bt_integer_range_set_unsigned_as_range_set_const(
444 const bt_integer_range_set_unsigned
*int_range_set
)
447 return __BT_UPCAST_CONST(bt_integer_range_set
, int_range_set
);
452 Increments the \ref api-fund-shared-object "reference count" of
453 the unsigned integer range set \bt_p{int_range_set}.
455 @param[in] int_range_set
457 Unsigned integer range set of which to increment the reference
463 @sa bt_integer_range_set_unsigned_put_ref() —
464 Decrements the reference count of an unsigned integer range set.
466 extern void bt_integer_range_set_unsigned_get_ref(
467 const bt_integer_range_set_unsigned
*int_range_set
)
472 Decrements the \ref api-fund-shared-object "reference count" of
473 the unsigned integer range set \bt_p{int_range_set}.
475 @param[in] int_range_set
477 Unsigned integer range set of which to decrement the reference
483 @sa bt_integer_range_set_unsigned_get_ref() —
484 Increments the reference count of an unsigned integer range set.
486 extern void bt_integer_range_set_unsigned_put_ref(
487 const bt_integer_range_set_unsigned
*int_range_set
)
492 Decrements the reference count of the unsigned integer range set
493 \bt_p{_int_range_set}, and then sets \bt_p{_int_range_set} to \c
496 @param _int_range_set
498 Unsigned integer range set of which to decrement the reference
504 @bt_pre_assign_expr{_int_range_set}
506 #define BT_INTEGER_RANGE_SET_UNSIGNED_PUT_REF_AND_RESET(_int_range_set) \
508 bt_integer_range_set_unsigned_put_ref(_int_range_set); \
509 (_int_range_set) = NULL; \
514 Decrements the reference count of the unsigned integer range set
515 \bt_p{_dst}, sets \bt_p{_dst} to \bt_p{_src}, and then sets
516 \bt_p{_src} to \c NULL.
518 This macro effectively moves an unsigned integer range set reference
519 from the expression \bt_p{_src} to the expression \bt_p{_dst}, putting
520 the existing \bt_p{_dst} reference.
524 Destination expression.
535 @bt_pre_assign_expr{_dst}
536 @bt_pre_assign_expr{_src}
538 #define BT_INTEGER_RANGE_SET_UNSIGNED_MOVE_REF(_dst, _src) \
540 bt_integer_range_set_unsigned_put_ref(_dst); \
548 @name Signed integer range set
554 Creates and returns an empty set of signed 64-bit integer ranges.
557 New signed integer range set, or \c NULL on memory error.
559 extern bt_integer_range_set_signed
*bt_integer_range_set_signed_create(
564 Adds a signed 64-bit integer range having the lower value
565 \bt_p{lower} and the upper value \bt_p{upper} to the signed
567 \bt_p{int_range_set}.
569 The values \bt_p{lower} and \bt_p{upper} are included in the signed
570 integer range to add to \bt_p{int_range_set}.
572 @param[in] int_range_set
573 Signed integer range set to which to add a signed integer
576 Lower value (included) of the signed integer range to add to
577 \bt_p{int_range_set}.
579 Upper value (included) of the signed integer range to add to
580 \bt_p{int_range_set}.
582 @retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK
584 @retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR
587 @bt_pre_not_null{int_range_set}
588 @bt_pre_hot{int_range_set}
590 \bt_p{lower} ≤ \bt_p{upper}.
592 extern bt_integer_range_set_add_range_status
593 bt_integer_range_set_signed_add_range(
594 bt_integer_range_set_signed
*int_range_set
,
595 int64_t lower
, int64_t upper
) __BT_NOEXCEPT
;
599 Borrows the signed integer range at index \bt_p{index} from the
600 signed integer range set \bt_p{int_range_set}.
602 @param[in] int_range_set
603 Signed integer range set from which to borrow the signed integer
604 range at index \bt_p{index}.
606 Index of the signed integer range to borrow from
607 \bt_p{int_range_set}.
611 \em Borrowed reference of the signed integer range of
612 \bt_p{int_range_set} at index \bt_p{index}.
614 The returned pointer remains valid until \bt_p{int_range_set} is
618 @bt_pre_not_null{int_range_set}
620 \bt_p{index} is less than the number of signed integer ranges in
621 \bt_p{int_range_set} (as returned by
622 bt_integer_range_set_get_range_count()).
624 extern const bt_integer_range_signed
*
625 bt_integer_range_set_signed_borrow_range_by_index_const(
626 const bt_integer_range_set_signed
*int_range_set
,
627 uint64_t index
) __BT_NOEXCEPT
;
631 Returns whether or not the signed integer range set
632 \bt_p{int_range_set_a} is equal to \bt_p{int_range_set_b}.
634 Two signed integer range sets are considered equal if they contain the
635 exact same signed integer ranges, whatever the order. In other words,
636 a signed integer range set containing [−57, 23] and [24, 42]
637 is \em not equal to a signed integer range containing [−57, 42].
639 @param[in] int_range_set_a
640 Signed integer range set A.
641 @param[in] int_range_set_b
642 Signed integer range set B.
645 #BT_TRUE if \bt_p{int_range_set_a} is equal to
646 \bt_p{int_range_set_b}.
648 @bt_pre_not_null{int_range_set_a}
649 @bt_pre_not_null{int_range_set_b}
651 extern bt_bool
bt_integer_range_set_signed_is_equal(
652 const bt_integer_range_set_signed
*int_range_set_a
,
653 const bt_integer_range_set_signed
*int_range_set_b
)
658 \ref api-fund-c-typing "Upcasts" the signed integer range set
659 \bt_p{int_range_set} to the abstract #bt_integer_range_set type.
661 @param[in] int_range_set
663 Signed integer range set to upcast.
669 \bt_p{int_range_set} as an abstract integer range set.
672 const bt_integer_range_set
*bt_integer_range_set_signed_as_range_set_const(
673 const bt_integer_range_set_signed
*int_range_set
)
676 return __BT_UPCAST_CONST(bt_integer_range_set
, int_range_set
);
681 Increments the \ref api-fund-shared-object "reference count" of
682 the signed integer range set \bt_p{int_range_set}.
684 @param[in] int_range_set
686 Signed integer range set of which to increment the reference
692 @sa bt_integer_range_set_signed_put_ref() —
693 Decrements the reference count of a signed integer range set.
695 extern void bt_integer_range_set_signed_get_ref(
696 const bt_integer_range_set_signed
*int_range_set
) __BT_NOEXCEPT
;
700 Decrements the \ref api-fund-shared-object "reference count" of
701 the signed integer range set \bt_p{int_range_set}.
703 @param[in] int_range_set
705 Signed integer range set of which to decrement the reference
711 @sa bt_integer_range_set_signed_get_ref() —
712 Increments the reference count of a signed integer range set.
714 extern void bt_integer_range_set_signed_put_ref(
715 const bt_integer_range_set_signed
*int_range_set
) __BT_NOEXCEPT
;
719 Decrements the reference count of the signed integer range set
720 \bt_p{_int_range_set}, and then sets \bt_p{_int_range_set} to \c
723 @param _int_range_set
725 Signed integer range set of which to decrement the reference
731 @bt_pre_assign_expr{_int_range_set}
733 #define BT_INTEGER_RANGE_SET_SIGNED_PUT_REF_AND_RESET(_int_range_set) \
735 bt_integer_range_set_signed_put_ref(_int_range_set); \
736 (_int_range_set) = NULL; \
741 Decrements the reference count of the signed integer range set
742 \bt_p{_dst}, sets \bt_p{_dst} to \bt_p{_src}, and then sets
743 \bt_p{_src} to \c NULL.
745 This macro effectively moves a signed integer range set reference
746 from the expression \bt_p{_src} to the expression \bt_p{_dst}, putting
747 the existing \bt_p{_dst} reference.
751 Destination expression.
762 @bt_pre_assign_expr{_dst}
763 @bt_pre_assign_expr{_src}
765 #define BT_INTEGER_RANGE_SET_SIGNED_MOVE_REF(_dst, _src) \
767 bt_integer_range_set_signed_put_ref(_dst); \
780 #endif /* BABELTRACE2_INTEGER_RANGE_SET_H */