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 (Roaring bitmaps are compressed bitmaps. They can be hundreds of times faster).

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 using the R-SelectionModel.

Example

An example use of module bitset is to show a selection of listview entries. @pos is an array of unsigned integers representing the item positions in the listview to select.

  my Gnome::Gtk4::StringList $list-objects;
  $list-objects .= new-stringlist(CArray[Str].new(Str));
  $list-objects.append('foo');
  $list-objects.append('foo');
  $list-objects.append('baz');

  my Gnome::Gtk4::MultiSelection $selection-type;
  $selection-type .= new-multiselection($list-objects);

  my Gnome::Gtk4::N-Bitset $bitset .= new-empty;
  for ( 0, 2) -> $p {
    $bitset.add($p);
  }

  my Gnome::Gtk4::ListView $list-view;
  with $list-view .= new-listview( N-Object, N-Object) {
    .set-orientation(GTK_ORIENTATION_VERTICAL);
    .set-model($selection-type);
    .set-enable-rubberband(True);
    .set-show-separators(True);
  }

  # Set the selection with the same mask as its selected items.
  $selection-type.set-selection( $bitset, $bitset);

Class initialization

new

:native-object

Create an object using a native object from an object of the same type found 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 ( )