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
);
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
);
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
);
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
);
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
);
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
);
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
);
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(void);
334 Adds an unsigned 64-bit integer range having the lower value
335 \bt_p{lower} and the upper value \bt_p{upper} to the unsigned
337 \bt_p{int_range_set}.
339 The values \bt_p{lower} and \bt_p{upper} are included in the unsigned
340 integer range to add to \bt_p{int_range_set}.
342 @param[in] int_range_set
343 Unsigned integer range set to which to add an unsigned integer
346 Lower value (included) of the unsigned integer range to add to
347 \bt_p{int_range_set}.
349 Upper value (included) of the unsigned integer range to add to
350 \bt_p{int_range_set}.
352 @retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK
354 @retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR
357 @bt_pre_not_null{int_range_set}
358 @bt_pre_hot{int_range_set}
360 \bt_p{lower} ≤ \bt_p{upper}.
362 extern bt_integer_range_set_add_range_status
363 bt_integer_range_set_unsigned_add_range(
364 bt_integer_range_set_unsigned
*int_range_set
,
365 uint64_t lower
, uint64_t upper
);
369 Borrows the unsigned integer range at index \bt_p{index} from the
370 unsigned integer range set \bt_p{int_range_set}.
372 @param[in] int_range_set
373 Unsigned integer range set from which to borrow the unsigned integer
374 range at index \bt_p{index}.
376 Index of the unsigned integer range to borrow from
377 \bt_p{int_range_set}.
381 \em Borrowed reference of the unsigned integer range of
382 \bt_p{int_range_set} at index \bt_p{index}.
384 The returned pointer remains valid until \bt_p{int_range_set} is
388 @bt_pre_not_null{int_range_set}
390 \bt_p{index} is less than the number of unsigned integer ranges in
391 \bt_p{int_range_set} (as returned by
392 bt_integer_range_set_get_range_count()).
394 extern const bt_integer_range_unsigned
*
395 bt_integer_range_set_unsigned_borrow_range_by_index_const(
396 const bt_integer_range_set_unsigned
*int_range_set
,
401 Returns whether or not the unsigned integer range set
402 \bt_p{int_range_set_a} is equal to \bt_p{int_range_set_b}.
404 Two unsigned integer range sets are considered equal if they contain the
405 exact same unsigned integer ranges, whatever the order. In other words,
406 an unsigned integer range set containing [2, 9] and [10, 15]
407 is \em not equal to an unsigned integer range containing [2, 15].
409 @param[in] int_range_set_a
410 Unsigned integer range set A.
411 @param[in] int_range_set_b
412 Unsigned integer range set B.
415 #BT_TRUE if \bt_p{int_range_set_a} is equal to
416 \bt_p{int_range_set_b}.
418 @bt_pre_not_null{int_range_set_a}
419 @bt_pre_not_null{int_range_set_b}
421 extern bt_bool
bt_integer_range_set_unsigned_is_equal(
422 const bt_integer_range_set_unsigned
*int_range_set_a
,
423 const bt_integer_range_set_unsigned
*int_range_set_b
);
427 \ref api-fund-c-typing "Upcasts" the unsigned integer range set
428 \bt_p{int_range_set} to the abstract #bt_integer_range_set type.
430 @param[in] int_range_set
432 Unsigned integer range set to upcast.
438 \bt_p{int_range_set} as an abstract integer range set.
441 const bt_integer_range_set
*bt_integer_range_set_unsigned_as_range_set_const(
442 const bt_integer_range_set_unsigned
*int_range_set
)
444 return __BT_UPCAST_CONST(bt_integer_range_set
, int_range_set
);
449 Increments the \ref api-fund-shared-object "reference count" of
450 the unsigned integer range set \bt_p{int_range_set}.
452 @param[in] int_range_set
454 Unsigned integer range set of which to increment the reference
460 @sa bt_integer_range_set_unsigned_put_ref() —
461 Decrements the reference count of an unsigned integer range set.
463 extern void bt_integer_range_set_unsigned_get_ref(
464 const bt_integer_range_set_unsigned
*int_range_set
);
468 Decrements the \ref api-fund-shared-object "reference count" of
469 the unsigned integer range set \bt_p{int_range_set}.
471 @param[in] int_range_set
473 Unsigned integer range set of which to decrement the reference
479 @sa bt_integer_range_set_unsigned_get_ref() —
480 Increments the reference count of an unsigned integer range set.
482 extern void bt_integer_range_set_unsigned_put_ref(
483 const bt_integer_range_set_unsigned
*int_range_set
);
487 Decrements the reference count of the unsigned integer range set
488 \bt_p{_int_range_set}, and then sets \bt_p{_int_range_set} to \c
491 @param _int_range_set
493 Unsigned integer range set of which to decrement the reference
499 @bt_pre_assign_expr{_int_range_set}
501 #define BT_INTEGER_RANGE_SET_UNSIGNED_PUT_REF_AND_RESET(_int_range_set) \
503 bt_integer_range_set_unsigned_put_ref(_int_range_set); \
504 (_int_range_set) = NULL; \
509 Decrements the reference count of the unsigned integer range set
510 \bt_p{_dst}, sets \bt_p{_dst} to \bt_p{_src}, and then sets
511 \bt_p{_src} to \c NULL.
513 This macro effectively moves an unsigned integer range set reference
514 from the expression \bt_p{_src} to the expression \bt_p{_dst}, putting
515 the existing \bt_p{_dst} reference.
519 Destination expression.
530 @bt_pre_assign_expr{_dst}
531 @bt_pre_assign_expr{_src}
533 #define BT_INTEGER_RANGE_SET_UNSIGNED_MOVE_REF(_dst, _src) \
535 bt_integer_range_set_unsigned_put_ref(_dst); \
543 @name Signed integer range set
549 Creates and returns an empty set of signed 64-bit integer ranges.
552 New signed integer range set, or \c NULL on memory error.
554 extern bt_integer_range_set_signed
*bt_integer_range_set_signed_create(void);
558 Adds a signed 64-bit integer range having the lower value
559 \bt_p{lower} and the upper value \bt_p{upper} to the signed
561 \bt_p{int_range_set}.
563 The values \bt_p{lower} and \bt_p{upper} are included in the signed
564 integer range to add to \bt_p{int_range_set}.
566 @param[in] int_range_set
567 Signed integer range set to which to add a signed integer
570 Lower value (included) of the signed integer range to add to
571 \bt_p{int_range_set}.
573 Upper value (included) of the signed integer range to add to
574 \bt_p{int_range_set}.
576 @retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK
578 @retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR
581 @bt_pre_not_null{int_range_set}
582 @bt_pre_hot{int_range_set}
584 \bt_p{lower} ≤ \bt_p{upper}.
586 extern bt_integer_range_set_add_range_status
587 bt_integer_range_set_signed_add_range(
588 bt_integer_range_set_signed
*int_range_set
,
589 int64_t lower
, int64_t upper
);
593 Borrows the signed integer range at index \bt_p{index} from the
594 signed integer range set \bt_p{int_range_set}.
596 @param[in] int_range_set
597 Signed integer range set from which to borrow the signed integer
598 range at index \bt_p{index}.
600 Index of the signed integer range to borrow from
601 \bt_p{int_range_set}.
605 \em Borrowed reference of the signed integer range of
606 \bt_p{int_range_set} at index \bt_p{index}.
608 The returned pointer remains valid until \bt_p{int_range_set} is
612 @bt_pre_not_null{int_range_set}
614 \bt_p{index} is less than the number of signed integer ranges in
615 \bt_p{int_range_set} (as returned by
616 bt_integer_range_set_get_range_count()).
618 extern const bt_integer_range_signed
*
619 bt_integer_range_set_signed_borrow_range_by_index_const(
620 const bt_integer_range_set_signed
*int_range_set
, uint64_t index
);
624 Returns whether or not the signed integer range set
625 \bt_p{int_range_set_a} is equal to \bt_p{int_range_set_b}.
627 Two signed integer range sets are considered equal if they contain the
628 exact same signed integer ranges, whatever the order. In other words,
629 a signed integer range set containing [−57, 23] and [24, 42]
630 is \em not equal to a signed integer range containing [−57, 42].
632 @param[in] int_range_set_a
633 Signed integer range set A.
634 @param[in] int_range_set_b
635 Signed integer range set B.
638 #BT_TRUE if \bt_p{int_range_set_a} is equal to
639 \bt_p{int_range_set_b}.
641 @bt_pre_not_null{int_range_set_a}
642 @bt_pre_not_null{int_range_set_b}
644 extern bt_bool
bt_integer_range_set_signed_is_equal(
645 const bt_integer_range_set_signed
*int_range_set_a
,
646 const bt_integer_range_set_signed
*int_range_set_b
);
650 \ref api-fund-c-typing "Upcasts" the signed integer range set
651 \bt_p{int_range_set} to the abstract #bt_integer_range_set type.
653 @param[in] int_range_set
655 Signed integer range set to upcast.
661 \bt_p{int_range_set} as an abstract integer range set.
664 const bt_integer_range_set
*bt_integer_range_set_signed_as_range_set_const(
665 const bt_integer_range_set_signed
*int_range_set
)
667 return __BT_UPCAST_CONST(bt_integer_range_set
, int_range_set
);
672 Increments the \ref api-fund-shared-object "reference count" of
673 the signed integer range set \bt_p{int_range_set}.
675 @param[in] int_range_set
677 Signed integer range set of which to increment the reference
683 @sa bt_integer_range_set_signed_put_ref() —
684 Decrements the reference count of a signed integer range set.
686 extern void bt_integer_range_set_signed_get_ref(
687 const bt_integer_range_set_signed
*int_range_set
);
691 Decrements the \ref api-fund-shared-object "reference count" of
692 the signed integer range set \bt_p{int_range_set}.
694 @param[in] int_range_set
696 Signed integer range set of which to decrement the reference
702 @sa bt_integer_range_set_signed_get_ref() —
703 Increments the reference count of a signed integer range set.
705 extern void bt_integer_range_set_signed_put_ref(
706 const bt_integer_range_set_signed
*int_range_set
);
710 Decrements the reference count of the signed integer range set
711 \bt_p{_int_range_set}, and then sets \bt_p{_int_range_set} to \c
714 @param _int_range_set
716 Signed integer range set of which to decrement the reference
722 @bt_pre_assign_expr{_int_range_set}
724 #define BT_INTEGER_RANGE_SET_SIGNED_PUT_REF_AND_RESET(_int_range_set) \
726 bt_integer_range_set_signed_put_ref(_int_range_set); \
727 (_int_range_set) = NULL; \
732 Decrements the reference count of the signed integer range set
733 \bt_p{_dst}, sets \bt_p{_dst} to \bt_p{_src}, and then sets
734 \bt_p{_src} to \c NULL.
736 This macro effectively moves a signed integer range set reference
737 from the expression \bt_p{_src} to the expression \bt_p{_dst}, putting
738 the existing \bt_p{_dst} reference.
742 Destination expression.
753 @bt_pre_assign_expr{_dst}
754 @bt_pre_assign_expr{_src}
756 #define BT_INTEGER_RANGE_SET_SIGNED_MOVE_REF(_dst, _src) \
758 bt_integer_range_set_signed_put_ref(_dst); \
771 #endif /* BABELTRACE2_INTEGER_RANGE_SET_H */