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:

bt_integer_range_unsigned
bt_integer_range_signed
bt_integer_range_set_unsigned
bt_integer_range_set_signed

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.1, 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().

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

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

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

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

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

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

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

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.

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

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

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

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.

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

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

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

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

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.

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

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

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

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.

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

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

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

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

Enumeration Type Documentation

◆ bt_integer_range_set_add_range_status

enum 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 )

extern

Returns the lower value of the unsigned integer range int_range.

The returned lower value is included in int_range.

Parameters

[in] int_range Unsigned 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 )

extern

Returns the upper value of the unsigned integer range int_range.

The returned upper value is included in int_range.

Parameters

[in] int_range Unsigned 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
	)

extern

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_range	Unsigned integer range A.
[in]	b_int_range	Unsigned 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 )

extern

Returns the lower value of the signed integer range int_range.

The returned lower value is included in int_range.

Parameters

[in] int_range Signed 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 )

extern

Returns the upper value of the signed integer range int_range.

The returned upper value is included in int_range.

Parameters

[in] int_range Signed 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
	)

extern

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_range	Signed integer range A.
[in]	b_int_range	Signed 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 )

extern

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_set Integer 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 )

extern

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
	)

extern

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_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`.

Return values

BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK	Success.
BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR	Out of memory.

Precondition: int_range_set is not NULL.; int_range_set is not frozen.; lower ≤ upper.

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

extern

Borrows the unsigned integer range at index index from the unsigned integer range set int_range_set.

Parameters

[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`.

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
	)

extern

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_a	Unsigned integer range set A.
[in]	int_range_set_b	Unsigned 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 )

extern

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 )

extern

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 )

extern

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
	)

extern

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_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`.

Return values

BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK	Success.
BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR	Out of memory.

Precondition: int_range_set is not NULL.; int_range_set is not frozen.; lower ≤ upper.

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

extern

Borrows the signed integer range at index index from the signed integer range set int_range_set.

Parameters

[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`.

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
	)

extern

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_a	Signed integer range set A.
[in]	int_range_set_b	Signed 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 )

extern

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 )

extern

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.

Detailed Description

Integer range set: common

Unsigned integer range

Signed integer range

Unsigned integer range set

Signed integer range set

Enumeration Type Documentation

◆ bt_integer_range_set_add_range_status

Macro Definition Documentation

◆ BT_INTEGER_RANGE_SET_UNSIGNED_PUT_REF_AND_RESET

◆ BT_INTEGER_RANGE_SET_UNSIGNED_MOVE_REF

◆ BT_INTEGER_RANGE_SET_SIGNED_PUT_REF_AND_RESET

◆ BT_INTEGER_RANGE_SET_SIGNED_MOVE_REF

Function Documentation

◆ bt_integer_range_unsigned_get_lower()

◆ bt_integer_range_unsigned_get_upper()

◆ bt_integer_range_unsigned_is_equal()

◆ bt_integer_range_signed_get_lower()

◆ bt_integer_range_signed_get_upper()

◆ bt_integer_range_signed_is_equal()

◆ bt_integer_range_set_get_range_count()

◆ bt_integer_range_set_unsigned_create()

◆ bt_integer_range_set_unsigned_add_range()

◆ bt_integer_range_set_unsigned_borrow_range_by_index_const()

◆ bt_integer_range_set_unsigned_is_equal()

◆ bt_integer_range_set_unsigned_as_range_set_const()

◆ bt_integer_range_set_unsigned_get_ref()

◆ bt_integer_range_set_unsigned_put_ref()

◆ bt_integer_range_set_signed_create()

◆ bt_integer_range_set_signed_add_range()

◆ bt_integer_range_set_signed_borrow_range_by_index_const()

◆ bt_integer_range_set_signed_is_equal()

◆ bt_integer_range_set_signed_as_range_set_const()

◆ bt_integer_range_set_signed_get_ref()

◆ bt_integer_range_set_signed_put_ref()