1 #ifndef BABELTRACE2_INTEGER_RANGE_SET_H
2 #define BABELTRACE2_INTEGER_RANGE_SET_H
5 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
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:
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
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
26 #ifndef __BT_IN_BABELTRACE_H
27 # error "Please include <babeltrace2/babeltrace.h> instead."
33 #include <babeltrace2/types.h>
40 @defgroup api-int-rs Integer range sets
43 Sets of unsigned and signed 64-bit integer ranges.
45 An <strong><em>integer range set</em></strong>
46 is an \em unordered set of integer ranges.
48 An <strong><em>integer range</em></strong> represents all the
49 integers \b 𝑥 which satisfy
50 (<em>lower value</em> ≤ <strong>𝑥</strong> ≤ <em>upper value</em>).
52 For example, an unsigned integer range set could contain the ranges
53 [5, 14], [199, 2001], and [1976, 3000].
55 This integer range set API offers unsigned and signed 64-bit integer
56 ranges and integer range sets with dedicated C types:
58 - #bt_integer_range_unsigned
59 - #bt_integer_range_signed
60 - #bt_integer_range_set_unsigned
61 - #bt_integer_range_set_signed
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().
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().
77 An integer range is a \ref api-fund-unique-object "unique object": it
78 belongs to the integer range set which contains it.
80 Some library functions \ref api-fund-freezing "freeze" integer range
81 sets on success. The documentation of those functions indicate this
84 Create an empty integer range set with
85 bt_integer_range_set_unsigned_create() or
86 bt_integer_range_set_signed_create().
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.
94 As of \bt_name_version_min_maj, you cannot remove an existing
95 integer range from an integer range set.
97 Check that two integer ranges are equal with
98 bt_integer_range_unsigned_is_equal() or
99 bt_integer_range_signed_is_equal().
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().
112 @typedef struct bt_integer_range_unsigned bt_integer_range_unsigned
115 Unsigned 64-bit integer range.
118 @typedef struct bt_integer_range_signed bt_integer_range_signed
121 Signed 64-bit integer range.
124 @typedef struct bt_integer_range_set bt_integer_range_set
127 Set of 64-bit integer ranges.
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
134 @typedef struct bt_integer_range_set_unsigned bt_integer_range_set_unsigned;
137 Set of unsigned 64-bit integer ranges.
140 @typedef struct bt_integer_range_set_signed bt_integer_range_set_signed;
143 Set of signed 64-bit integer ranges.
149 @name Unsigned integer range
155 Returns the lower value of the unsigned integer range
158 The returned lower value is included in \bt_p{int_range}.
161 Unsigned integer range of which to get the lower value.
164 Lower value of \bt_p{int_range}.
166 @bt_pre_not_null{int_range}
167 @bt_pre_is_bool_val{int_range}
169 extern uint64_t bt_integer_range_unsigned_get_lower(
170 const bt_integer_range_unsigned
*int_range
);
174 Returns the upper value of the unsigned integer range
177 The returned upper value is included in \bt_p{int_range}.
180 Unsigned integer range of which to get the upper value.
183 Upper value of \bt_p{int_range}.
185 @bt_pre_not_null{int_range}
186 @bt_pre_is_bool_val{int_range}
188 extern uint64_t bt_integer_range_unsigned_get_upper(
189 const bt_integer_range_unsigned
*int_range
);
193 Returns whether or not the unsigned integer range
194 \bt_p{a_int_range} is equal to \bt_p{b_int_range}.
196 Two unsigned integer ranges are considered equal if they have the same
197 lower and upper values.
199 @param[in] a_int_range
200 Unsigned integer range A.
201 @param[in] b_int_range
202 Unsigned integer range B.
205 #BT_TRUE if \bt_p{a_int_range} is equal to
208 @bt_pre_not_null{a_int_range}
209 @bt_pre_not_null{b_int_range}
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
);
218 @name Signed integer range
224 Returns the lower value of the signed integer range
227 The returned lower value is included in \bt_p{int_range}.
230 Signed integer range of which to get the lower value.
233 Lower value of \bt_p{int_range}.
235 @bt_pre_not_null{int_range}
236 @bt_pre_is_bool_val{int_range}
238 extern int64_t bt_integer_range_signed_get_lower(
239 const bt_integer_range_signed
*int_range
);
243 Returns the upper value of the signed integer range
246 The returned upper value is included in \bt_p{int_range}.
249 Signed integer range of which to get the upper value.
252 Upper value of \bt_p{int_range}.
254 @bt_pre_not_null{int_range}
255 @bt_pre_is_bool_val{int_range}
257 extern int64_t bt_integer_range_signed_get_upper(
258 const bt_integer_range_signed
*int_range
);
262 Returns whether or not the signed integer range
263 \bt_p{a_int_range} is equal to \bt_p{b_int_range}.
265 Two signed integer ranges are considered equal if they have the same
266 lower and upper values.
268 @param[in] a_int_range
269 Signed integer range A.
270 @param[in] b_int_range
271 Signed integer range B.
274 #BT_TRUE if \bt_p{a_int_range} is equal to
277 @bt_pre_not_null{a_int_range}
278 @bt_pre_not_null{b_int_range}
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
);
287 @name Integer range set: common
293 Status codes for bt_integer_range_set_unsigned_add_range() and
294 bt_integer_range_set_signed_add_range().
296 typedef enum bt_integer_range_set_add_range_status
{
301 BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK
= __BT_FUNC_STATUS_OK
,
307 BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
308 } bt_integer_range_set_add_range_status
;
312 Returns the number of integer ranges contained in the integer
313 range set \bt_p{int_range_set}.
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.
322 @param[in] int_range_set
323 Integer range set of which to get the number of contained integer
327 Number of contained integer ranges in \bt_p{int_range_set}.
329 @bt_pre_not_null{int_range_set}
331 extern uint64_t bt_integer_range_set_get_range_count(
332 const bt_integer_range_set
*int_range_set
);
337 @name Unsigned integer range set
343 Creates and returns an empty set of unsigned 64-bit integer ranges.
346 New unsigned integer range set, or \c NULL on memory error.
348 extern bt_integer_range_set_unsigned
*bt_integer_range_set_unsigned_create(void);
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
355 \bt_p{int_range_set}.
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}.
360 @param[in] int_range_set
361 Unsigned integer range set to which to add an unsigned integer
364 Lower value (included) of the unsigned integer range to add to
365 \bt_p{int_range_set}.
367 Upper value (included) of the unsigned integer range to add to
368 \bt_p{int_range_set}.
370 @retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK
372 @retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR
375 @bt_pre_not_null{int_range_set}
376 @bt_pre_hot{int_range_set}
378 \bt_p{lower} ≤ \bt_p{upper}.
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
);
387 Borrows the unsigned integer range at index \bt_p{index} from the
388 unsigned integer range set \bt_p{int_range_set}.
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}.
394 Index of the unsigned integer range to borrow from
395 \bt_p{int_range_set}.
399 \em Borrowed reference of the unsigned integer range of
400 \bt_p{int_range_set} at index \bt_p{index}.
402 The returned pointer remains valid until \bt_p{int_range_set} is
406 @bt_pre_not_null{int_range_set}
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()).
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
,
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}.
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, 9] and [10, 15]
425 is \em not equal to an unsigned integer range containing [2, 15].
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.
433 #BT_TRUE if \bt_p{int_range_set_a} is equal to
434 \bt_p{int_range_set_b}.
436 @bt_pre_not_null{int_range_set_a}
437 @bt_pre_not_null{int_range_set_b}
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
);
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.
448 @param[in] int_range_set
450 Unsigned integer range set to upcast.
456 \bt_p{int_range_set} as an abstract integer range set.
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
)
462 return __BT_UPCAST_CONST(bt_integer_range_set
, int_range_set
);
467 Increments the \ref api-fund-shared-object "reference count" of
468 the unsigned integer range set \bt_p{int_range_set}.
470 @param[in] int_range_set
472 Unsigned integer range set of which to increment the reference
478 @sa bt_integer_range_set_unsigned_put_ref() —
479 Decrements the reference count of an unsigned integer range set.
481 extern void bt_integer_range_set_unsigned_get_ref(
482 const bt_integer_range_set_unsigned
*int_range_set
);
486 Decrements the \ref api-fund-shared-object "reference count" of
487 the unsigned integer range set \bt_p{int_range_set}.
489 @param[in] int_range_set
491 Unsigned integer range set of which to decrement the reference
497 @sa bt_integer_range_set_unsigned_get_ref() —
498 Increments the reference count of an unsigned integer range set.
500 extern void bt_integer_range_set_unsigned_put_ref(
501 const bt_integer_range_set_unsigned
*int_range_set
);
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
509 @param _int_range_set
511 Unsigned integer range set of which to decrement the reference
517 @bt_pre_assign_expr{_int_range_set}
519 #define BT_INTEGER_RANGE_SET_UNSIGNED_PUT_REF_AND_RESET(_int_range_set) \
521 bt_integer_range_set_unsigned_put_ref(_int_range_set); \
522 (_int_range_set) = NULL; \
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.
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.
537 Destination expression.
548 @bt_pre_assign_expr{_dst}
549 @bt_pre_assign_expr{_src}
551 #define BT_INTEGER_RANGE_SET_UNSIGNED_MOVE_REF(_dst, _src) \
553 bt_integer_range_set_unsigned_put_ref(_dst); \
561 @name Signed integer range set
567 Creates and returns an empty set of signed 64-bit integer ranges.
570 New signed integer range set, or \c NULL on memory error.
572 extern bt_integer_range_set_signed
*bt_integer_range_set_signed_create(void);
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
579 \bt_p{int_range_set}.
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}.
584 @param[in] int_range_set
585 Signed integer range set to which to add a signed integer
588 Lower value (included) of the signed integer range to add to
589 \bt_p{int_range_set}.
591 Upper value (included) of the signed integer range to add to
592 \bt_p{int_range_set}.
594 @retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK
596 @retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR
599 @bt_pre_not_null{int_range_set}
600 @bt_pre_hot{int_range_set}
602 \bt_p{lower} ≤ \bt_p{upper}.
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
);
611 Borrows the signed integer range at index \bt_p{index} from the
612 signed integer range set \bt_p{int_range_set}.
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}.
618 Index of the signed integer range to borrow from
619 \bt_p{int_range_set}.
623 \em Borrowed reference of the signed integer range of
624 \bt_p{int_range_set} at index \bt_p{index}.
626 The returned pointer remains valid until \bt_p{int_range_set} is
630 @bt_pre_not_null{int_range_set}
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()).
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
);
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}.
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, 23] and [24, 42]
648 is \em not equal to a signed integer range containing [-57, 42].
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.
656 #BT_TRUE if \bt_p{int_range_set_a} is equal to
657 \bt_p{int_range_set_b}.
659 @bt_pre_not_null{int_range_set_a}
660 @bt_pre_not_null{int_range_set_b}
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
);
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.
671 @param[in] int_range_set
673 Signed integer range set to upcast.
679 \bt_p{int_range_set} as an abstract integer range set.
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
)
685 return __BT_UPCAST_CONST(bt_integer_range_set
, int_range_set
);
690 Increments the \ref api-fund-shared-object "reference count" of
691 the signed integer range set \bt_p{int_range_set}.
693 @param[in] int_range_set
695 Signed integer range set of which to increment the reference
701 @sa bt_integer_range_set_signed_put_ref() —
702 Decrements the reference count of a signed integer range set.
704 extern void bt_integer_range_set_signed_get_ref(
705 const bt_integer_range_set_signed
*int_range_set
);
709 Decrements the \ref api-fund-shared-object "reference count" of
710 the signed integer range set \bt_p{int_range_set}.
712 @param[in] int_range_set
714 Signed integer range set of which to decrement the reference
720 @sa bt_integer_range_set_signed_get_ref() —
721 Increments the reference count of a signed integer range set.
723 extern void bt_integer_range_set_signed_put_ref(
724 const bt_integer_range_set_signed
*int_range_set
);
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
732 @param _int_range_set
734 Signed integer range set of which to decrement the reference
740 @bt_pre_assign_expr{_int_range_set}
742 #define BT_INTEGER_RANGE_SET_SIGNED_PUT_REF_AND_RESET(_int_range_set) \
744 bt_integer_range_set_signed_put_ref(_int_range_set); \
745 (_int_range_set) = NULL; \
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.
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.
760 Destination expression.
771 @bt_pre_assign_expr{_dst}
772 @bt_pre_assign_expr{_src}
774 #define BT_INTEGER_RANGE_SET_SIGNED_MOVE_REF(_dst, _src) \
776 bt_integer_range_set_signed_put_ref(_dst); \
789 #endif /* BABELTRACE2_INTEGER_RANGE_SET_H */