Babeltrace 2 C API
2.0.0
Open-source trace manipulation framework
|
Sets of unsigned and signed 64-bit integer ranges.
An integer range set is an unordered set of integer ranges.
An integer range represents all the integers 𝑥 which satisfy (lower value ≤ 𝑥 ≤ upper value).
For example, an unsigned integer range set could contain the ranges [5, 14], [199, 2001], and [1976, 3000].
This integer range set API offers unsigned and signed 64-bit integer ranges and integer range sets with dedicated C types:
This API uses the abstract bt_integer_range_set type for common properties and operations (for example, bt_integer_range_set_get_range_count()). Upcast a specific integer range set to the bt_integer_range_set type with bt_integer_range_set_unsigned_as_range_set_const() or bt_integer_range_set_signed_as_range_set_const().
An integer range set is a shared object: get a new reference with bt_integer_range_set_unsigned_get_ref() or bt_integer_range_set_signed_get_ref() and put an existing reference with bt_integer_range_set_unsigned_put_ref() or bt_integer_range_set_signed_put_ref().
An integer range is a unique object: it belongs to the integer range set which contains it.
Some library functions freeze integer range sets on success. The documentation of those functions indicate this postcondition.
Create an empty integer range set with bt_integer_range_set_unsigned_create() or bt_integer_range_set_signed_create().
Add an integer range to an integer range set with bt_integer_range_set_unsigned_add_range() or bt_integer_range_set_signed_add_range(). Although integer ranges can overlap, specific functions of the Babeltrace 2 C API expect an integer range set with non-overlapping integer ranges.
As of Babeltrace 2.0, you cannot remove an existing integer range from an integer range set.
Check that two integer ranges are equal with bt_integer_range_unsigned_is_equal() or bt_integer_range_signed_is_equal().
Check that two integer range sets are equal with bt_integer_range_set_unsigned_is_equal() or bt_integer_range_set_signed_is_equal().
Types | |
typedef struct bt_integer_range_unsigned | bt_integer_range_unsigned |
Unsigned 64-bit integer range. | |
typedef struct bt_integer_range_signed | bt_integer_range_signed |
Signed 64-bit integer range. | |
typedef struct bt_integer_range_set | bt_integer_range_set |
Set of 64-bit integer ranges. More... | |
typedef struct bt_integer_range_set_unsigned | bt_integer_range_set_unsigned |
Set of unsigned 64-bit integer ranges. | |
typedef struct bt_integer_range_set_signed | bt_integer_range_set_signed |
Set of signed 64-bit integer ranges. | |
Unsigned integer range | |
uint64_t | bt_integer_range_unsigned_get_lower (const bt_integer_range_unsigned *int_range) |
Returns the lower value of the unsigned integer range int_range. More... | |
uint64_t | bt_integer_range_unsigned_get_upper (const bt_integer_range_unsigned *int_range) |
Returns the upper value of the unsigned integer range int_range. More... | |
bt_bool | bt_integer_range_unsigned_is_equal (const bt_integer_range_unsigned *a_int_range, const bt_integer_range_unsigned *b_int_range) |
Returns whether or not the unsigned integer range a_int_range is equal to b_int_range. More... | |
Signed integer range | |
int64_t | bt_integer_range_signed_get_lower (const bt_integer_range_signed *int_range) |
Returns the lower value of the signed integer range int_range. More... | |
int64_t | bt_integer_range_signed_get_upper (const bt_integer_range_signed *int_range) |
Returns the upper value of the signed integer range int_range. More... | |
bt_bool | bt_integer_range_signed_is_equal (const bt_integer_range_signed *a_int_range, const bt_integer_range_signed *b_int_range) |
Returns whether or not the signed integer range a_int_range is equal to b_int_range. More... | |
Integer range set: common | |
enum | bt_integer_range_set_add_range_status { BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK, BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR } |
Status codes for bt_integer_range_set_unsigned_add_range() and bt_integer_range_set_signed_add_range(). More... | |
typedef enum bt_integer_range_set_add_range_status | bt_integer_range_set_add_range_status |
Status codes for bt_integer_range_set_unsigned_add_range() and bt_integer_range_set_signed_add_range(). | |
uint64_t | bt_integer_range_set_get_range_count (const bt_integer_range_set *int_range_set) |
Returns the number of integer ranges contained in the integer range set int_range_set. More... | |
Unsigned integer range set | |
bt_integer_range_set_unsigned * | bt_integer_range_set_unsigned_create (void) |
Creates and returns an empty set of unsigned 64-bit integer ranges. More... | |
bt_integer_range_set_add_range_status | bt_integer_range_set_unsigned_add_range (bt_integer_range_set_unsigned *int_range_set, uint64_t lower, uint64_t upper) |
Adds an unsigned 64-bit integer range having the lower value lower and the upper value upper to the unsigned integer range set int_range_set. More... | |
const bt_integer_range_unsigned * | bt_integer_range_set_unsigned_borrow_range_by_index_const (const bt_integer_range_set_unsigned *int_range_set, uint64_t index) |
Borrows the unsigned integer range at index index from the unsigned integer range set int_range_set. More... | |
bt_bool | bt_integer_range_set_unsigned_is_equal (const bt_integer_range_set_unsigned *int_range_set_a, const bt_integer_range_set_unsigned *int_range_set_b) |
Returns whether or not the unsigned integer range set int_range_set_a is equal to int_range_set_b. More... | |
static const bt_integer_range_set * | bt_integer_range_set_unsigned_as_range_set_const (const bt_integer_range_set_unsigned *int_range_set) |
Upcasts the unsigned integer range set int_range_set to the abstract bt_integer_range_set type. More... | |
void | bt_integer_range_set_unsigned_get_ref (const bt_integer_range_set_unsigned *int_range_set) |
Increments the reference count of the unsigned integer range set int_range_set. More... | |
void | bt_integer_range_set_unsigned_put_ref (const bt_integer_range_set_unsigned *int_range_set) |
Decrements the reference count of the unsigned integer range set int_range_set. More... | |
#define | BT_INTEGER_RANGE_SET_UNSIGNED_PUT_REF_AND_RESET(_int_range_set) |
Decrements the reference count of the unsigned integer range set _int_range_set, and then sets _int_range_set to NULL . More... | |
#define | BT_INTEGER_RANGE_SET_UNSIGNED_MOVE_REF(_dst, _src) |
Decrements the reference count of the unsigned integer range set _dst, sets _dst to _src, and then sets _src to NULL . More... | |
Signed integer range set | |
bt_integer_range_set_signed * | bt_integer_range_set_signed_create (void) |
Creates and returns an empty set of signed 64-bit integer ranges. More... | |
bt_integer_range_set_add_range_status | bt_integer_range_set_signed_add_range (bt_integer_range_set_signed *int_range_set, int64_t lower, int64_t upper) |
Adds a signed 64-bit integer range having the lower value lower and the upper value upper to the signed integer range set int_range_set. More... | |
const bt_integer_range_signed * | bt_integer_range_set_signed_borrow_range_by_index_const (const bt_integer_range_set_signed *int_range_set, uint64_t index) |
Borrows the signed integer range at index index from the signed integer range set int_range_set. More... | |
bt_bool | bt_integer_range_set_signed_is_equal (const bt_integer_range_set_signed *int_range_set_a, const bt_integer_range_set_signed *int_range_set_b) |
Returns whether or not the signed integer range set int_range_set_a is equal to int_range_set_b. More... | |
static const bt_integer_range_set * | bt_integer_range_set_signed_as_range_set_const (const bt_integer_range_set_signed *int_range_set) |
Upcasts the signed integer range set int_range_set to the abstract bt_integer_range_set type. More... | |
void | bt_integer_range_set_signed_get_ref (const bt_integer_range_set_signed *int_range_set) |
Increments the reference count of the signed integer range set int_range_set. More... | |
void | bt_integer_range_set_signed_put_ref (const bt_integer_range_set_signed *int_range_set) |
Decrements the reference count of the signed integer range set int_range_set. More... | |
#define | BT_INTEGER_RANGE_SET_SIGNED_PUT_REF_AND_RESET(_int_range_set) |
Decrements the reference count of the signed integer range set _int_range_set, and then sets _int_range_set to NULL . More... | |
#define | BT_INTEGER_RANGE_SET_SIGNED_MOVE_REF(_dst, _src) |
Decrements the reference count of the signed integer range set _dst, sets _dst to _src, and then sets _src to NULL . More... | |
Set of 64-bit integer ranges.
This is an abstract type for common properties and operations. See C typing to learn more about conceptual object type inheritance.
Status codes for bt_integer_range_set_unsigned_add_range() and bt_integer_range_set_signed_add_range().
Enumerator | |
---|---|
BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK | Success. |
BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR | Out of memory. |
#define BT_INTEGER_RANGE_SET_UNSIGNED_PUT_REF_AND_RESET | ( | _int_range_set | ) |
Decrements the reference count of the unsigned integer range set _int_range_set, and then sets _int_range_set to NULL
.
_int_range_set | Unsigned integer range set of which to decrement the reference count. Can contain |
#define BT_INTEGER_RANGE_SET_UNSIGNED_MOVE_REF | ( | _dst, | |
_src | |||
) |
Decrements the reference count of the unsigned integer range set _dst, sets _dst to _src, and then sets _src to NULL
.
This macro effectively moves an unsigned integer range set reference from the expression _src to the expression _dst, putting the existing _dst reference.
_dst | Destination expression. Can contain |
_src | Source expression. Can contain |
#define BT_INTEGER_RANGE_SET_SIGNED_PUT_REF_AND_RESET | ( | _int_range_set | ) |
Decrements the reference count of the signed integer range set _int_range_set, and then sets _int_range_set to NULL
.
_int_range_set | Signed integer range set of which to decrement the reference count. Can contain |
#define BT_INTEGER_RANGE_SET_SIGNED_MOVE_REF | ( | _dst, | |
_src | |||
) |
Decrements the reference count of the signed integer range set _dst, sets _dst to _src, and then sets _src to NULL
.
This macro effectively moves a signed integer range set reference from the expression _src to the expression _dst, putting the existing _dst reference.
_dst | Destination expression. Can contain |
_src | Source expression. Can contain |
uint64_t bt_integer_range_unsigned_get_lower | ( | const bt_integer_range_unsigned * | int_range | ) |
Returns the lower value of the unsigned integer range int_range.
The returned lower value is included in int_range.
[in] | int_range | Unsigned integer range of which to get the lower value. |
NULL
. uint64_t bt_integer_range_unsigned_get_upper | ( | const bt_integer_range_unsigned * | int_range | ) |
Returns the upper value of the unsigned integer range int_range.
The returned upper value is included in int_range.
[in] | int_range | Unsigned integer range of which to get the upper value. |
NULL
. bt_bool bt_integer_range_unsigned_is_equal | ( | const bt_integer_range_unsigned * | a_int_range, |
const bt_integer_range_unsigned * | b_int_range | ||
) |
Returns whether or not the unsigned integer range a_int_range is equal to b_int_range.
Two unsigned integer ranges are considered equal if they have the same lower and upper values.
[in] | a_int_range | Unsigned integer range A. |
[in] | b_int_range | Unsigned integer range B. |
NULL
. NULL
. int64_t bt_integer_range_signed_get_lower | ( | const bt_integer_range_signed * | int_range | ) |
Returns the lower value of the signed integer range int_range.
The returned lower value is included in int_range.
[in] | int_range | Signed integer range of which to get the lower value. |
NULL
. int64_t bt_integer_range_signed_get_upper | ( | const bt_integer_range_signed * | int_range | ) |
Returns the upper value of the signed integer range int_range.
The returned upper value is included in int_range.
[in] | int_range | Signed integer range of which to get the upper value. |
NULL
. bt_bool bt_integer_range_signed_is_equal | ( | const bt_integer_range_signed * | a_int_range, |
const bt_integer_range_signed * | b_int_range | ||
) |
Returns whether or not the signed integer range a_int_range is equal to b_int_range.
Two signed integer ranges are considered equal if they have the same lower and upper values.
[in] | a_int_range | Signed integer range A. |
[in] | b_int_range | Signed integer range B. |
NULL
. NULL
. uint64_t bt_integer_range_set_get_range_count | ( | const bt_integer_range_set * | int_range_set | ) |
Returns the number of integer ranges contained in the integer range set int_range_set.
[in] | int_range_set | Integer range set of which to get the number of contained integer ranges. |
NULL
. bt_integer_range_set_unsigned* bt_integer_range_set_unsigned_create | ( | void | ) |
Creates and returns an empty set of unsigned 64-bit integer ranges.
NULL
on memory error. bt_integer_range_set_add_range_status bt_integer_range_set_unsigned_add_range | ( | bt_integer_range_set_unsigned * | int_range_set, |
uint64_t | lower, | ||
uint64_t | upper | ||
) |
Adds an unsigned 64-bit integer range having the lower value lower and the upper value upper to the unsigned integer range set int_range_set.
The values lower and upper are included in the unsigned integer range to add to int_range_set.
[in] | int_range_set | Unsigned integer range set to which to add an unsigned integer range. |
[in] | lower | Lower value (included) of the unsigned integer range to add to int_range_set. |
[in] | upper | Upper value (included) of the unsigned integer range to add to int_range_set. |
BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK | Success. |
BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR | Out of memory. |
NULL
. const bt_integer_range_unsigned* bt_integer_range_set_unsigned_borrow_range_by_index_const | ( | const bt_integer_range_set_unsigned * | int_range_set, |
uint64_t | index | ||
) |
Borrows the unsigned integer range at index index from the unsigned integer range set int_range_set.
[in] | int_range_set | Unsigned integer range set from which to borrow the unsigned integer range at index index. |
[in] | index | Index of the unsigned integer range to borrow from int_range_set. |
Borrowed reference of the unsigned integer range of int_range_set at index index.
The returned pointer remains valid until int_range_set is modified.
NULL
. bt_bool bt_integer_range_set_unsigned_is_equal | ( | const bt_integer_range_set_unsigned * | int_range_set_a, |
const bt_integer_range_set_unsigned * | int_range_set_b | ||
) |
Returns whether or not the unsigned integer range set int_range_set_a is equal to int_range_set_b.
Two unsigned integer range sets are considered equal if they contain the exact same unsigned integer ranges, whatever the order. In other words, an unsigned integer range set containing [2, 9] and [10, 15] is not equal to an unsigned integer range containing [2, 15].
[in] | int_range_set_a | Unsigned integer range set A. |
[in] | int_range_set_b | Unsigned integer range set B. |
NULL
. NULL
.
|
inlinestatic |
Upcasts the unsigned integer range set int_range_set to the abstract bt_integer_range_set type.
[in] | int_range_set | Unsigned integer range set to upcast. Can be |
void bt_integer_range_set_unsigned_get_ref | ( | const bt_integer_range_set_unsigned * | int_range_set | ) |
Increments the reference count of the unsigned integer range set int_range_set.
[in] | int_range_set | Unsigned integer range set of which to increment the reference count. Can be |
void bt_integer_range_set_unsigned_put_ref | ( | const bt_integer_range_set_unsigned * | int_range_set | ) |
Decrements the reference count of the unsigned integer range set int_range_set.
[in] | int_range_set | Unsigned integer range set of which to decrement the reference count. Can be |
bt_integer_range_set_signed* bt_integer_range_set_signed_create | ( | void | ) |
Creates and returns an empty set of signed 64-bit integer ranges.
NULL
on memory error. bt_integer_range_set_add_range_status bt_integer_range_set_signed_add_range | ( | bt_integer_range_set_signed * | int_range_set, |
int64_t | lower, | ||
int64_t | upper | ||
) |
Adds a signed 64-bit integer range having the lower value lower and the upper value upper to the signed integer range set int_range_set.
The values lower and upper are included in the signed integer range to add to int_range_set.
[in] | int_range_set | Signed integer range set to which to add a signed integer range. |
[in] | lower | Lower value (included) of the signed integer range to add to int_range_set. |
[in] | upper | Upper value (included) of the signed integer range to add to int_range_set. |
BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK | Success. |
BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR | Out of memory. |
NULL
. const bt_integer_range_signed* bt_integer_range_set_signed_borrow_range_by_index_const | ( | const bt_integer_range_set_signed * | int_range_set, |
uint64_t | index | ||
) |
Borrows the signed integer range at index index from the signed integer range set int_range_set.
[in] | int_range_set | Signed integer range set from which to borrow the signed integer range at index index. |
[in] | index | Index of the signed integer range to borrow from int_range_set. |
Borrowed reference of the signed integer range of int_range_set at index index.
The returned pointer remains valid until int_range_set is modified.
NULL
. bt_bool bt_integer_range_set_signed_is_equal | ( | const bt_integer_range_set_signed * | int_range_set_a, |
const bt_integer_range_set_signed * | int_range_set_b | ||
) |
Returns whether or not the signed integer range set int_range_set_a is equal to int_range_set_b.
Two signed integer range sets are considered equal if they contain the exact same signed integer ranges, whatever the order. In other words, a signed integer range set containing [-57, 23] and [24, 42] is not equal to a signed integer range containing [-57, 42].
[in] | int_range_set_a | Signed integer range set A. |
[in] | int_range_set_b | Signed integer range set B. |
NULL
. NULL
.
|
inlinestatic |
Upcasts the signed integer range set int_range_set to the abstract bt_integer_range_set type.
[in] | int_range_set | Signed integer range set to upcast. Can be |
void bt_integer_range_set_signed_get_ref | ( | const bt_integer_range_set_signed * | int_range_set | ) |
Increments the reference count of the signed integer range set int_range_set.
[in] | int_range_set | Signed integer range set of which to increment the reference count. Can be |
void bt_integer_range_set_signed_put_ref | ( | const bt_integer_range_set_signed * | int_range_set | ) |
Decrements the reference count of the signed integer range set int_range_set.
[in] | int_range_set | Signed integer range set of which to decrement the reference count. Can be |