Babeltrace 2 C API  2.0.0
Open-source trace manipulation framework
Integer range sets

Detailed Description

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_unsignedbt_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_unsignedbt_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_setbt_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_signedbt_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_signedbt_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_setbt_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...
 

Typedef Documentation

◆ bt_integer_range_set

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.

Enumeration Type Documentation

◆ 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().

Enumerator
BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK 

Success.

BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR 

Out of memory.

Macro Definition Documentation

◆ BT_INTEGER_RANGE_SET_UNSIGNED_PUT_REF_AND_RESET

#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.

Parameters
_int_range_set

Unsigned integer range set of which to decrement the reference count.

Can contain NULL.

Precondition
_int_range_set is an assignable expression.

◆ BT_INTEGER_RANGE_SET_UNSIGNED_MOVE_REF

#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.

Parameters
_dst

Destination expression.

Can contain NULL.

_src

Source expression.

Can contain NULL.

Precondition
_dst is an assignable expression.
_src is an assignable expression.

◆ BT_INTEGER_RANGE_SET_SIGNED_PUT_REF_AND_RESET

#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.

Parameters
_int_range_set

Signed integer range set of which to decrement the reference count.

Can contain NULL.

Precondition
_int_range_set is an assignable expression.

◆ BT_INTEGER_RANGE_SET_SIGNED_MOVE_REF

#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.

Parameters
_dst

Destination expression.

Can contain NULL.

_src

Source expression.

Can contain NULL.

Precondition
_dst is an assignable expression.
_src is an assignable expression.

Function Documentation

◆ bt_integer_range_unsigned_get_lower()

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.

Parameters
[in]int_rangeUnsigned integer range of which to get the lower value.
Returns
Lower value of int_range.
Precondition
int_range is not NULL.
int_range is a boolean value (bt_value_is_bool() returns BT_TRUE).

◆ bt_integer_range_unsigned_get_upper()

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.

Parameters
[in]int_rangeUnsigned integer range of which to get the upper value.
Returns
Upper value of int_range.
Precondition
int_range is not NULL.
int_range is a boolean value (bt_value_is_bool() returns BT_TRUE).

◆ bt_integer_range_unsigned_is_equal()

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.

Parameters
[in]a_int_rangeUnsigned integer range A.
[in]b_int_rangeUnsigned integer range B.
Returns
BT_TRUE if a_int_range is equal to b_int_range.
Precondition
a_int_range is not NULL.
b_int_range is not NULL.

◆ bt_integer_range_signed_get_lower()

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.

Parameters
[in]int_rangeSigned integer range of which to get the lower value.
Returns
Lower value of int_range.
Precondition
int_range is not NULL.
int_range is a boolean value (bt_value_is_bool() returns BT_TRUE).

◆ bt_integer_range_signed_get_upper()

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.

Parameters
[in]int_rangeSigned integer range of which to get the upper value.
Returns
Upper value of int_range.
Precondition
int_range is not NULL.
int_range is a boolean value (bt_value_is_bool() returns BT_TRUE).

◆ bt_integer_range_signed_is_equal()

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.

Parameters
[in]a_int_rangeSigned integer range A.
[in]b_int_rangeSigned integer range B.
Returns
BT_TRUE if a_int_range is equal to b_int_range.
Precondition
a_int_range is not NULL.
b_int_range is not NULL.

◆ bt_integer_range_set_get_range_count()

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.

Note
The parameter int_range_set has the abstract type bt_integer_range_set: use bt_integer_range_set_unsigned_as_range_set_const() or bt_integer_range_set_signed_as_range_set_const() to upcast a specific integer range set to this type.
Parameters
[in]int_range_setInteger range set of which to get the number of contained integer ranges.
Returns
Number of contained integer ranges in int_range_set.
Precondition
int_range_set is not NULL.

◆ bt_integer_range_set_unsigned_create()

bt_integer_range_set_unsigned* bt_integer_range_set_unsigned_create ( void  )

Creates and returns an empty set of unsigned 64-bit integer ranges.

Returns
New unsigned integer range set, or NULL on memory error.

◆ bt_integer_range_set_unsigned_add_range()

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.

Parameters
[in]int_range_setUnsigned integer range set to which to add an unsigned integer range.
[in]lowerLower value (included) of the unsigned integer range to add to int_range_set.
[in]upperUpper value (included) of the unsigned integer range to add to int_range_set.
Return values
BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OKSuccess.
BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROROut of memory.
Precondition
int_range_set is not NULL.
int_range_set is not frozen.
lowerupper.

◆ bt_integer_range_set_unsigned_borrow_range_by_index_const()

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.

Parameters
[in]int_range_setUnsigned integer range set from which to borrow the unsigned integer range at index index.
[in]indexIndex of the unsigned integer range to borrow from int_range_set.
Returns

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.

Precondition
int_range_set is not NULL.
index is less than the number of unsigned integer ranges in int_range_set (as returned by bt_integer_range_set_get_range_count()).

◆ bt_integer_range_set_unsigned_is_equal()

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].

Parameters
[in]int_range_set_aUnsigned integer range set A.
[in]int_range_set_bUnsigned integer range set B.
Returns
BT_TRUE if int_range_set_a is equal to int_range_set_b.
Precondition
int_range_set_a is not NULL.
int_range_set_b is not NULL.

◆ bt_integer_range_set_unsigned_as_range_set_const()

static const bt_integer_range_set* bt_integer_range_set_unsigned_as_range_set_const ( const bt_integer_range_set_unsigned int_range_set)
inlinestatic

Upcasts the unsigned integer range set int_range_set to the abstract bt_integer_range_set type.

Parameters
[in]int_range_set

Unsigned integer range set to upcast.

Can be NULL.

Returns
int_range_set as an abstract integer range set.

◆ bt_integer_range_set_unsigned_get_ref()

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.

Parameters
[in]int_range_set

Unsigned integer range set of which to increment the reference count.

Can be NULL.

See also
bt_integer_range_set_unsigned_put_ref() — Decrements the reference count of an unsigned integer range set.

◆ bt_integer_range_set_unsigned_put_ref()

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.

Parameters
[in]int_range_set

Unsigned integer range set of which to decrement the reference count.

Can be NULL.

See also
bt_integer_range_set_unsigned_get_ref() — Increments the reference count of an unsigned integer range set.

◆ bt_integer_range_set_signed_create()

bt_integer_range_set_signed* bt_integer_range_set_signed_create ( void  )

Creates and returns an empty set of signed 64-bit integer ranges.

Returns
New signed integer range set, or NULL on memory error.

◆ bt_integer_range_set_signed_add_range()

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.

Parameters
[in]int_range_setSigned integer range set to which to add a signed integer range.
[in]lowerLower value (included) of the signed integer range to add to int_range_set.
[in]upperUpper value (included) of the signed integer range to add to int_range_set.
Return values
BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OKSuccess.
BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROROut of memory.
Precondition
int_range_set is not NULL.
int_range_set is not frozen.
lowerupper.

◆ bt_integer_range_set_signed_borrow_range_by_index_const()

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.

Parameters
[in]int_range_setSigned integer range set from which to borrow the signed integer range at index index.
[in]indexIndex of the signed integer range to borrow from int_range_set.
Returns

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.

Precondition
int_range_set is not NULL.
index is less than the number of signed integer ranges in int_range_set (as returned by bt_integer_range_set_get_range_count()).

◆ bt_integer_range_set_signed_is_equal()

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].

Parameters
[in]int_range_set_aSigned integer range set A.
[in]int_range_set_bSigned integer range set B.
Returns
BT_TRUE if int_range_set_a is equal to int_range_set_b.
Precondition
int_range_set_a is not NULL.
int_range_set_b is not NULL.

◆ bt_integer_range_set_signed_as_range_set_const()

static const bt_integer_range_set* bt_integer_range_set_signed_as_range_set_const ( const bt_integer_range_set_signed int_range_set)
inlinestatic

Upcasts the signed integer range set int_range_set to the abstract bt_integer_range_set type.

Parameters
[in]int_range_set

Signed integer range set to upcast.

Can be NULL.

Returns
int_range_set as an abstract integer range set.

◆ bt_integer_range_set_signed_get_ref()

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.

Parameters
[in]int_range_set

Signed integer range set of which to increment the reference count.

Can be NULL.

See also
bt_integer_range_set_signed_put_ref() — Decrements the reference count of a signed integer range set.

◆ bt_integer_range_set_signed_put_ref()

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.

Parameters
[in]int_range_set

Signed integer range set of which to decrement the reference count.

Can be NULL.

See also
bt_integer_range_set_signed_get_ref() — Increments the reference count of a signed integer range set.