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 #ifndef __BT_IN_BABELTRACE_H
11 # error "Please include <babeltrace2/babeltrace.h> instead."
17 #include <babeltrace2/types.h>
24 @defgroup api-int-rs Integer range sets
27 Sets of unsigned and signed 64-bit integer ranges.
29 An <strong><em>integer range set</em></strong>
30 is an \em unordered set of integer ranges.
32 An <strong><em>integer range</em></strong> represents all the
33 integers \b 𝑥 which satisfy
34 (<em>lower value</em> ≤ <strong>𝑥</strong> ≤ <em>upper value</em>).
36 For example, an unsigned integer range set could contain the ranges
37 [5, 14], [199, 2001], and [1976, 3000].
39 This integer range set API offers unsigned and signed 64-bit integer
40 ranges and integer range sets with dedicated C types:
42 - #bt_integer_range_unsigned
43 - #bt_integer_range_signed
44 - #bt_integer_range_set_unsigned
45 - #bt_integer_range_set_signed
47 This API uses the \em abstract #bt_integer_range_set type for common
48 properties and operations (for example,
49 bt_integer_range_set_get_range_count()).
50 \ref api-fund-c-typing "Upcast" a specific
51 integer range set to the #bt_integer_range_set type with
52 bt_integer_range_set_unsigned_as_range_set_const() or
53 bt_integer_range_set_signed_as_range_set_const().
55 An integer range set is a \ref api-fund-shared-object "shared object":
56 get a new reference with bt_integer_range_set_unsigned_get_ref() or
57 bt_integer_range_set_signed_get_ref() and put an existing reference with
58 bt_integer_range_set_unsigned_put_ref() or
59 bt_integer_range_set_signed_put_ref().
61 An integer range is a \ref api-fund-unique-object "unique object": it
62 belongs to the integer range set which contains it.
64 Some library functions \ref api-fund-freezing "freeze" integer range
65 sets on success. The documentation of those functions indicate this
68 Create an empty integer range set with
69 bt_integer_range_set_unsigned_create() or
70 bt_integer_range_set_signed_create().
72 Add an integer range to an integer range set with
73 bt_integer_range_set_unsigned_add_range() or
74 bt_integer_range_set_signed_add_range(). Although integer ranges can
75 overlap, specific functions of the \bt_api expect an integer range set
76 with non-overlapping integer ranges.
78 As of \bt_name_version_min_maj, you cannot remove an existing
79 integer range from an integer range set.
81 Check that two integer ranges are equal with
82 bt_integer_range_unsigned_is_equal() or
83 bt_integer_range_signed_is_equal().
85 Check that two integer range sets are equal with
86 bt_integer_range_set_unsigned_is_equal() or
87 bt_integer_range_set_signed_is_equal().
96 @typedef struct bt_integer_range_unsigned bt_integer_range_unsigned
99 Unsigned 64-bit integer range.
101 @typedef struct bt_integer_range_signed bt_integer_range_signed
104 Signed 64-bit integer range.
106 @typedef struct bt_integer_range_set bt_integer_range_set
109 Set of 64-bit integer ranges.
111 This is an abstract type for common properties and operations. See \ref
112 api-fund-c-typing to learn more about conceptual object type
115 @typedef struct bt_integer_range_set_unsigned bt_integer_range_set_unsigned;
118 Set of unsigned 64-bit integer ranges.
120 @typedef struct bt_integer_range_set_signed bt_integer_range_set_signed;
123 Set of signed 64-bit integer ranges.
129 @name Unsigned integer range
135 Returns the lower value of the unsigned integer range
138 The returned lower value is included in \bt_p{int_range}.
141 Unsigned integer range of which to get the lower value.
144 Lower value of \bt_p{int_range}.
146 @bt_pre_not_null{int_range}
147 @bt_pre_is_bool_val{int_range}
149 extern uint64_t bt_integer_range_unsigned_get_lower(
150 const bt_integer_range_unsigned
*int_range
);
154 Returns the upper value of the unsigned integer range
157 The returned upper value is included in \bt_p{int_range}.
160 Unsigned integer range of which to get the upper value.
163 Upper value of \bt_p{int_range}.
165 @bt_pre_not_null{int_range}
166 @bt_pre_is_bool_val{int_range}
168 extern uint64_t bt_integer_range_unsigned_get_upper(
169 const bt_integer_range_unsigned
*int_range
);
173 Returns whether or not the unsigned integer range
174 \bt_p{a_int_range} is equal to \bt_p{b_int_range}.
176 Two unsigned integer ranges are considered equal if they have the same
177 lower and upper values.
179 @param[in] a_int_range
180 Unsigned integer range A.
181 @param[in] b_int_range
182 Unsigned integer range B.
185 #BT_TRUE if \bt_p{a_int_range} is equal to
188 @bt_pre_not_null{a_int_range}
189 @bt_pre_not_null{b_int_range}
191 extern bt_bool
bt_integer_range_unsigned_is_equal(
192 const bt_integer_range_unsigned
*a_int_range
,
193 const bt_integer_range_unsigned
*b_int_range
);
198 @name Signed integer range
204 Returns the lower value of the signed integer range
207 The returned lower value is included in \bt_p{int_range}.
210 Signed integer range of which to get the lower value.
213 Lower value of \bt_p{int_range}.
215 @bt_pre_not_null{int_range}
216 @bt_pre_is_bool_val{int_range}
218 extern int64_t bt_integer_range_signed_get_lower(
219 const bt_integer_range_signed
*int_range
);
223 Returns the upper value of the signed integer range
226 The returned upper value is included in \bt_p{int_range}.
229 Signed integer range of which to get the upper value.
232 Upper value of \bt_p{int_range}.
234 @bt_pre_not_null{int_range}
235 @bt_pre_is_bool_val{int_range}
237 extern int64_t bt_integer_range_signed_get_upper(
238 const bt_integer_range_signed
*int_range
);
242 Returns whether or not the signed integer range
243 \bt_p{a_int_range} is equal to \bt_p{b_int_range}.
245 Two signed integer ranges are considered equal if they have the same
246 lower and upper values.
248 @param[in] a_int_range
249 Signed integer range A.
250 @param[in] b_int_range
251 Signed integer range B.
254 #BT_TRUE if \bt_p{a_int_range} is equal to
257 @bt_pre_not_null{a_int_range}
258 @bt_pre_not_null{b_int_range}
260 extern bt_bool
bt_integer_range_signed_is_equal(
261 const bt_integer_range_signed
*a_int_range
,
262 const bt_integer_range_signed
*b_int_range
);
267 @name Integer range set: common
273 Status codes for bt_integer_range_set_unsigned_add_range() and
274 bt_integer_range_set_signed_add_range().
276 typedef enum bt_integer_range_set_add_range_status
{
281 BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK
= __BT_FUNC_STATUS_OK
,
287 BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
288 } bt_integer_range_set_add_range_status
;
292 Returns the number of integer ranges contained in the integer
293 range set \bt_p{int_range_set}.
296 The parameter \bt_p{int_range_set} has the abstract type
297 #bt_integer_range_set: use
298 bt_integer_range_set_unsigned_as_range_set_const() or
299 bt_integer_range_set_signed_as_range_set_const() to upcast a
300 specific integer range set to this type.
302 @param[in] int_range_set
303 Integer range set of which to get the number of contained integer
307 Number of contained integer ranges in \bt_p{int_range_set}.
309 @bt_pre_not_null{int_range_set}
311 extern uint64_t bt_integer_range_set_get_range_count(
312 const bt_integer_range_set
*int_range_set
);
317 @name Unsigned integer range set
323 Creates and returns an empty set of unsigned 64-bit integer ranges.
326 New unsigned integer range set, or \c NULL on memory error.
328 extern bt_integer_range_set_unsigned
*bt_integer_range_set_unsigned_create(void);
332 Adds an unsigned 64-bit integer range having the lower value
333 \bt_p{lower} and the upper value \bt_p{upper} to the unsigned
335 \bt_p{int_range_set}.
337 The values \bt_p{lower} and \bt_p{upper} are included in the unsigned
338 integer range to add to \bt_p{int_range_set}.
340 @param[in] int_range_set
341 Unsigned integer range set to which to add an unsigned integer
344 Lower value (included) of the unsigned integer range to add to
345 \bt_p{int_range_set}.
347 Upper value (included) of the unsigned integer range to add to
348 \bt_p{int_range_set}.
350 @retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK
352 @retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR
355 @bt_pre_not_null{int_range_set}
356 @bt_pre_hot{int_range_set}
358 \bt_p{lower} ≤ \bt_p{upper}.
360 extern bt_integer_range_set_add_range_status
361 bt_integer_range_set_unsigned_add_range(
362 bt_integer_range_set_unsigned
*int_range_set
,
363 uint64_t lower
, uint64_t upper
);
367 Borrows the unsigned integer range at index \bt_p{index} from the
368 unsigned integer range set \bt_p{int_range_set}.
370 @param[in] int_range_set
371 Unsigned integer range set from which to borrow the unsigned integer
372 range at index \bt_p{index}.
374 Index of the unsigned integer range to borrow from
375 \bt_p{int_range_set}.
379 \em Borrowed reference of the unsigned integer range of
380 \bt_p{int_range_set} at index \bt_p{index}.
382 The returned pointer remains valid until \bt_p{int_range_set} is
386 @bt_pre_not_null{int_range_set}
388 \bt_p{index} is less than the number of unsigned integer ranges in
389 \bt_p{int_range_set} (as returned by
390 bt_integer_range_set_get_range_count()).
392 extern const bt_integer_range_unsigned
*
393 bt_integer_range_set_unsigned_borrow_range_by_index_const(
394 const bt_integer_range_set_unsigned
*int_range_set
,
399 Returns whether or not the unsigned integer range set
400 \bt_p{int_range_set_a} is equal to \bt_p{int_range_set_b}.
402 Two unsigned integer range sets are considered equal if they contain the
403 exact same unsigned integer ranges, whatever the order. In other words,
404 an unsigned integer range set containing [2, 9] and [10, 15]
405 is \em not equal to an unsigned integer range containing [2, 15].
407 @param[in] int_range_set_a
408 Unsigned integer range set A.
409 @param[in] int_range_set_b
410 Unsigned integer range set B.
413 #BT_TRUE if \bt_p{int_range_set_a} is equal to
414 \bt_p{int_range_set_b}.
416 @bt_pre_not_null{int_range_set_a}
417 @bt_pre_not_null{int_range_set_b}
419 extern bt_bool
bt_integer_range_set_unsigned_is_equal(
420 const bt_integer_range_set_unsigned
*int_range_set_a
,
421 const bt_integer_range_set_unsigned
*int_range_set_b
);
425 \ref api-fund-c-typing "Upcasts" the unsigned integer range set
426 \bt_p{int_range_set} to the abstract #bt_integer_range_set type.
428 @param[in] int_range_set
430 Unsigned integer range set to upcast.
436 \bt_p{int_range_set} as an abstract integer range set.
439 const bt_integer_range_set
*bt_integer_range_set_unsigned_as_range_set_const(
440 const bt_integer_range_set_unsigned
*int_range_set
)
442 return __BT_UPCAST_CONST(bt_integer_range_set
, int_range_set
);
447 Increments the \ref api-fund-shared-object "reference count" of
448 the unsigned integer range set \bt_p{int_range_set}.
450 @param[in] int_range_set
452 Unsigned integer range set of which to increment the reference
458 @sa bt_integer_range_set_unsigned_put_ref() —
459 Decrements the reference count of an unsigned integer range set.
461 extern void bt_integer_range_set_unsigned_get_ref(
462 const bt_integer_range_set_unsigned
*int_range_set
);
466 Decrements the \ref api-fund-shared-object "reference count" of
467 the unsigned integer range set \bt_p{int_range_set}.
469 @param[in] int_range_set
471 Unsigned integer range set of which to decrement the reference
477 @sa bt_integer_range_set_unsigned_get_ref() —
478 Increments the reference count of an unsigned integer range set.
480 extern void bt_integer_range_set_unsigned_put_ref(
481 const bt_integer_range_set_unsigned
*int_range_set
);
485 Decrements the reference count of the unsigned integer range set
486 \bt_p{_int_range_set}, and then sets \bt_p{_int_range_set} to \c
489 @param _int_range_set
491 Unsigned integer range set of which to decrement the reference
497 @bt_pre_assign_expr{_int_range_set}
499 #define BT_INTEGER_RANGE_SET_UNSIGNED_PUT_REF_AND_RESET(_int_range_set) \
501 bt_integer_range_set_unsigned_put_ref(_int_range_set); \
502 (_int_range_set) = NULL; \
507 Decrements the reference count of the unsigned integer range set
508 \bt_p{_dst}, sets \bt_p{_dst} to \bt_p{_src}, and then sets
509 \bt_p{_src} to \c NULL.
511 This macro effectively moves an unsigned integer range set reference
512 from the expression \bt_p{_src} to the expression \bt_p{_dst}, putting
513 the existing \bt_p{_dst} reference.
517 Destination expression.
528 @bt_pre_assign_expr{_dst}
529 @bt_pre_assign_expr{_src}
531 #define BT_INTEGER_RANGE_SET_UNSIGNED_MOVE_REF(_dst, _src) \
533 bt_integer_range_set_unsigned_put_ref(_dst); \
541 @name Signed integer range set
547 Creates and returns an empty set of signed 64-bit integer ranges.
550 New signed integer range set, or \c NULL on memory error.
552 extern bt_integer_range_set_signed
*bt_integer_range_set_signed_create(void);
556 Adds a signed 64-bit integer range having the lower value
557 \bt_p{lower} and the upper value \bt_p{upper} to the signed
559 \bt_p{int_range_set}.
561 The values \bt_p{lower} and \bt_p{upper} are included in the signed
562 integer range to add to \bt_p{int_range_set}.
564 @param[in] int_range_set
565 Signed integer range set to which to add a signed integer
568 Lower value (included) of the signed integer range to add to
569 \bt_p{int_range_set}.
571 Upper value (included) of the signed integer range to add to
572 \bt_p{int_range_set}.
574 @retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK
576 @retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR
579 @bt_pre_not_null{int_range_set}
580 @bt_pre_hot{int_range_set}
582 \bt_p{lower} ≤ \bt_p{upper}.
584 extern bt_integer_range_set_add_range_status
585 bt_integer_range_set_signed_add_range(
586 bt_integer_range_set_signed
*int_range_set
,
587 int64_t lower
, int64_t upper
);
591 Borrows the signed integer range at index \bt_p{index} from the
592 signed integer range set \bt_p{int_range_set}.
594 @param[in] int_range_set
595 Signed integer range set from which to borrow the signed integer
596 range at index \bt_p{index}.
598 Index of the signed integer range to borrow from
599 \bt_p{int_range_set}.
603 \em Borrowed reference of the signed integer range of
604 \bt_p{int_range_set} at index \bt_p{index}.
606 The returned pointer remains valid until \bt_p{int_range_set} is
610 @bt_pre_not_null{int_range_set}
612 \bt_p{index} is less than the number of signed integer ranges in
613 \bt_p{int_range_set} (as returned by
614 bt_integer_range_set_get_range_count()).
616 extern const bt_integer_range_signed
*
617 bt_integer_range_set_signed_borrow_range_by_index_const(
618 const bt_integer_range_set_signed
*int_range_set
, uint64_t index
);
622 Returns whether or not the signed integer range set
623 \bt_p{int_range_set_a} is equal to \bt_p{int_range_set_b}.
625 Two signed integer range sets are considered equal if they contain the
626 exact same signed integer ranges, whatever the order. In other words,
627 a signed integer range set containing [−57, 23] and [24, 42]
628 is \em not equal to a signed integer range containing [−57, 42].
630 @param[in] int_range_set_a
631 Signed integer range set A.
632 @param[in] int_range_set_b
633 Signed integer range set B.
636 #BT_TRUE if \bt_p{int_range_set_a} is equal to
637 \bt_p{int_range_set_b}.
639 @bt_pre_not_null{int_range_set_a}
640 @bt_pre_not_null{int_range_set_b}
642 extern bt_bool
bt_integer_range_set_signed_is_equal(
643 const bt_integer_range_set_signed
*int_range_set_a
,
644 const bt_integer_range_set_signed
*int_range_set_b
);
648 \ref api-fund-c-typing "Upcasts" the signed integer range set
649 \bt_p{int_range_set} to the abstract #bt_integer_range_set type.
651 @param[in] int_range_set
653 Signed integer range set to upcast.
659 \bt_p{int_range_set} as an abstract integer range set.
662 const bt_integer_range_set
*bt_integer_range_set_signed_as_range_set_const(
663 const bt_integer_range_set_signed
*int_range_set
)
665 return __BT_UPCAST_CONST(bt_integer_range_set
, int_range_set
);
670 Increments the \ref api-fund-shared-object "reference count" of
671 the signed integer range set \bt_p{int_range_set}.
673 @param[in] int_range_set
675 Signed integer range set of which to increment the reference
681 @sa bt_integer_range_set_signed_put_ref() —
682 Decrements the reference count of a signed integer range set.
684 extern void bt_integer_range_set_signed_get_ref(
685 const bt_integer_range_set_signed
*int_range_set
);
689 Decrements the \ref api-fund-shared-object "reference count" of
690 the signed integer range set \bt_p{int_range_set}.
692 @param[in] int_range_set
694 Signed integer range set of which to decrement the reference
700 @sa bt_integer_range_set_signed_get_ref() —
701 Increments the reference count of a signed integer range set.
703 extern void bt_integer_range_set_signed_put_ref(
704 const bt_integer_range_set_signed
*int_range_set
);
708 Decrements the reference count of the signed integer range set
709 \bt_p{_int_range_set}, and then sets \bt_p{_int_range_set} to \c
712 @param _int_range_set
714 Signed integer range set of which to decrement the reference
720 @bt_pre_assign_expr{_int_range_set}
722 #define BT_INTEGER_RANGE_SET_SIGNED_PUT_REF_AND_RESET(_int_range_set) \
724 bt_integer_range_set_signed_put_ref(_int_range_set); \
725 (_int_range_set) = NULL; \
730 Decrements the reference count of the signed integer range set
731 \bt_p{_dst}, sets \bt_p{_dst} to \bt_p{_src}, and then sets
732 \bt_p{_src} to \c NULL.
734 This macro effectively moves a signed integer range set reference
735 from the expression \bt_p{_src} to the expression \bt_p{_dst}, putting
736 the existing \bt_p{_dst} reference.
740 Destination expression.
751 @bt_pre_assign_expr{_dst}
752 @bt_pre_assign_expr{_src}
754 #define BT_INTEGER_RANGE_SET_SIGNED_MOVE_REF(_dst, _src) \
756 bt_integer_range_set_signed_put_ref(_dst); \
769 #endif /* BABELTRACE2_INTEGER_RANGE_SET_H */