Description

A Gnome::Gtk4::N-Bitset represents a set of unsigned integers.

Another name for this data structure is "bitmap".

The current implementation is based on [roaring bitmaps](https://roaringbitmap.org/).

A bitset allows adding a set of integers and provides support for set operations like unions, intersections and checks for equality or if a value is contained in the set. Gnome::Gtk4::N-Bitset also contains various functions to query metadata about the bitset, such as the minimum or maximum values or its size.

The fastest way to iterate values in a bitset is Gnome::Gtk4::N-BitsetIter .

The main use case for Gnome::Gtk4::N-Bitset is implementing complex selections for Gnome::Gtk4::R-SelectionModel.

Class initialization

new

:native-object

Create an object using a native object from elsewhere. See also Gnome::N::TopLevelSupportClass.

multi method new ( N-Object :$native-object! )

new-empty

Creates a new empty bitset.

method new-empty ( --> Gnome::Gtk4::Bitset \)

new-range

Creates a bitset with the given range set.

method new-range ( UInt() $start, UInt() $n-items --> Gnome::Gtk4::Bitset \)

• $start; first value to add.

• $n-items; number of consecutive values to add.

Methods

add

Adds $value to $self if it wasn't part of it before.

method add ( UInt() $value --> Bool )

• $value; value to add.

Return value; True if $value was not part of $self and $self was changed.

add-range

Adds all values from $start (inclusive) to $start + $n-items (exclusive) in $self.

method add-range ( UInt() $start, UInt() $n-items )

• $start; first value to add.

• $n-items; number of consecutive values to add.

add-range-closed

Adds the closed range [ $first, $last], so $first, $last and all values in between. $first must be smaller than $last.

method add-range-closed ( UInt() $first, UInt() $last )

• $first; first value to add.

• $last; last value to add.

add-rectangle

Interprets the values as a 2-dimensional boolean grid with the given $stride and inside that grid, adds a rectangle with the given $width and $height.

method add-rectangle ( UInt() $start, UInt() $width, UInt() $height, UInt() $stride )

• $start; first value to add.

• $width; width of the rectangle.

• $height; height of the rectangle.

• $stride; row stride of the grid.

contains

Checks if the given $value has been added to $self

method contains ( UInt() $value --> Bool )

• $value; the value to check.

Return value; True if $self contains $value.

copy

Creates a copy of $self.

method copy (--> N-Object )

Return value; A new bitset that contains the same values as $self.

difference

Sets $self to be the symmetric difference of $self and $other.

The symmetric difference is set $self to contain all values that were either contained in $self or in $other, but not in both. This operation is also called an XOR.

It is allowed for $self and $other to be the same bitset. The bitset will be emptied in that case.

method difference ( N-Object $other )

• $other; the Gnome::Gtk4::N-Bitset to compute the difference from

equals

Returns True if $self and $other contain the same values.

method equals ( N-Object $other --> Bool )

• $other; another Gnome::Gtk4::N-Bitset

Return value; True if $self and $other contain the same values.

get-maximum

Returns the largest value in $self.

If $self is empty, 0 is returned.

method get-maximum (--> UInt )

Return value; The largest value in $self.

get-minimum

Returns the smallest value in $self.

If $self is empty, G_MAXUINT is returned.

method get-minimum (--> UInt )

Return value; The smallest value in $self.

get-nth

Returns the value of the $nth item in self.

If $nth is >= the size of $self, 0 is returned.

method get-nth ( UInt() $nth --> UInt )

• $nth; index of the item to get.

Return value; the value of the $nth item in $self.

get-size

Gets the number of values that were added to the set.

For example, if the set is empty, 0 is returned.

Note that this function returns a guint64, because when all values are set, the return value is G_MAXUINT + 1`. Unless you are sure this cannot happen (it can't with Gnome::Gio::R-ListModel), be sure to use a 64bit type.

method get-size (--> UInt )

Return value; The number of values in the set..

get-size-in-range

Gets the number of values that are part of the set from $first to $last (inclusive).

Note that this function returns a guint64, because when all values are set, the return value is G_MAXUINT + 1`. Unless you are sure this cannot happen (it can't with Gnome::Gio::R-ListModel), be sure to use a 64bit type.

method get-size-in-range ( UInt() $first, UInt() $last --> UInt )

• $first; the first element to include.

• $last; the last element to include.

Return value; The number of values in the set from $first to $last..

intersect

Sets $self to be the intersection of $self and $other.

In other words, remove all values from $self that are not part of $other.

It is allowed for $self and $other to be the same bitset. Nothing will happen in that case.

method intersect ( N-Object $other )

• $other; the Gnome::Gtk4::N-Bitset to intersect with

is-empty

Check if no value is contained in bitset.

method is-empty (--> Bool )

Return value; True if $self is empty.

ref

Acquires a reference on the given Gnome::Gtk4::N-Bitset.

method ref (--> N-Object )

Return value; the Gnome::Gtk4::N-Bitset with an additional reference.

remove

Removes $value from $self if it was part of it before.

method remove ( UInt() $value --> Bool )

• $value; value to remove.

Return value; True if $value was part of $self and $self was changed.

remove-all

Removes all values from the bitset so that it is empty again.

method remove-all ( )

remove-range

Removes all values from $start (inclusive) to $start + $n-items (exclusive) in $self.

method remove-range ( UInt() $start, UInt() $n-items )

• $start; first value to remove.

• $n-items; number of consecutive values to remove.

remove-range-closed

Removes the closed range [ $first, $last], so $first, $last and all values in between. $first must be smaller than $last.

method remove-range-closed ( UInt() $first, UInt() $last )

• $first; first value to remove.

• $last; last value to remove.

remove-rectangle

Interprets the values as a 2-dimensional boolean grid with the given $stride and inside that grid, removes a rectangle with the given $width and $height.

method remove-rectangle ( UInt() $start, UInt() $width, UInt() $height, UInt() $stride )

• $start; first value to remove.

• $width; width of the rectangle.

• $height; height of the rectangle.

• $stride; row stride of the grid.

shift-left

Shifts all values in $self to the left by $amount.

Values smaller than $amount are discarded.

method shift-left ( UInt() $amount )

• $amount; amount to shift all values to the left.

shift-right

Shifts all values in $self to the right by $amount.

Values that end up too large to be held in a #guint are discarded.

method shift-right ( UInt() $amount )

• $amount; amount to shift all values to the right.

splice

This is a support function for Gnome::Gio::R-ListModel handling, by mirroring the GlistModel::items-changed` signal.

First, it "cuts" the values from $position to $removed from the bitset. That is, it removes all those values and shifts all larger values to the left by $removed places.

Then, it "pastes" new room into the bitset by shifting all values larger than $position by $added spaces to the right. This frees up space that can then be filled.

method splice ( UInt() $position, UInt() $removed, UInt() $added )

• $position; position at which to slice.

• $removed; number of values to remove.

• $added; number of values to add.

subtract

Sets $self to be the subtraction of $other from $self.

In other words, remove all values from $self that are part of $other.

It is allowed for $self and $other to be the same bitset. The bitset will be emptied in that case.

method subtract ( N-Object $other )

• $other; the Gnome::Gtk4::N-Bitset to subtract

union

Sets $self to be the union of $self and $other.

That is, add all values from $other into $self that weren't part of it.

It is allowed for $self and $other to be the same bitset. Nothing will happen in that case.

method union ( N-Object $other )

• $other; the Gnome::Gtk4::N-Bitset to union with

unref

Releases a reference on the given Gnome::Gtk4::N-Bitset.

If the reference was the last, the resources associated to the $self are freed.

method unref ( )