:right-sidebar: True Bitset =================================================================== .. currentmodule:: gi.repository.Gtk .. class:: Bitset(*args, **kwargs) :no-contents-entry: A ``GtkBitset`` represents a set of unsigned integers. Another name for this data structure is "bitmap". The current implementation is based on `roaring bitmaps `__\. 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. ``GtkBitset`` 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 :obj:`~gi.repository.Gtk.BitsetIter`\. The main use case for ``GtkBitset`` is implementing complex selections for :obj:`~gi.repository.Gtk.SelectionModel`\. Constructors ------------ .. rst-class:: interim-class .. class:: Bitset :no-index: .. classmethod:: new_empty() -> ~gi.repository.Gtk.Bitset Creates a new empty bitset. .. classmethod:: new_range(start: int, n_items: int) -> ~gi.repository.Gtk.Bitset Creates a bitset with the given range set. :param start: first value to add :param n_items: number of consecutive values to add Methods ------- .. rst-class:: interim-class .. class:: Bitset :no-index: .. method:: add(value: int) -> bool Adds ``value`` to ``self`` if it wasn't part of it before. :param value: value to add .. method:: add_range(start: int, n_items: int) -> None Adds all values from ``start`` (inclusive) to ``start`` + ``n_items`` (exclusive) in ``self``\. :param start: first value to add :param n_items: number of consecutive values to add .. method:: add_range_closed(first: int, last: int) -> None Adds the closed range [``first``\, ``last``\], so ``first``\, ``last`` and all values in between. ``first`` must be smaller than ``last``\. :param first: first value to add :param last: last value to add .. method:: add_rectangle(start: int, width: int, height: int, stride: int) -> None 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``\. :param start: first value to add :param width: width of the rectangle :param height: height of the rectangle :param stride: row stride of the grid .. method:: contains(value: int) -> bool Checks if the given ``value`` has been added to ``self`` :param value: the value to check .. method:: difference(other: ~gi.repository.Gtk.Bitset) -> None 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. :param other: the ``GtkBitset`` to compute the difference from .. method:: equals(other: ~gi.repository.Gtk.Bitset) -> bool Returns :const:`True` if ``self`` and ``other`` contain the same values. :param other: another ``GtkBitset`` .. method:: get_maximum() -> int Returns the largest value in ``self``\. If ``self`` is empty, 0 is returned. .. method:: get_minimum() -> int Returns the smallest value in ``self``\. If ``self`` is empty, ``G_MAXUINT`` is returned. .. method:: get_nth(nth: int) -> int Returns the value of the ``nth`` item in self. If ``nth`` is >= the size of ``self``\, 0 is returned. :param nth: index of the item to get .. method:: get_size() -> int 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 ``GListModel``\), be sure to use a 64bit type. .. method:: get_size_in_range(first: int, last: int) -> int 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 ``GListModel``\), be sure to use a 64bit type. :param first: the first element to include :param last: the last element to include .. method:: intersect(other: ~gi.repository.Gtk.Bitset) -> None 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. :param other: the ``GtkBitset`` to intersect with .. method:: is_empty() -> bool Check if no value is contained in bitset. .. method:: remove(value: int) -> bool Removes ``value`` from ``self`` if it was part of it before. :param value: value to remove .. method:: remove_all() -> None Removes all values from the bitset so that it is empty again. .. method:: remove_range(start: int, n_items: int) -> None Removes all values from ``start`` (inclusive) to ``start`` + ``n_items`` (exclusive) in ``self``\. :param start: first value to remove :param n_items: number of consecutive values to remove .. method:: remove_range_closed(first: int, last: int) -> None Removes the closed range [``first``\, ``last``\], so ``first``\, ``last`` and all values in between. ``first`` must be smaller than ``last``\. :param first: first value to remove :param last: last value to remove .. method:: remove_rectangle(start: int, width: int, height: int, stride: int) -> None 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``\. :param start: first value to remove :param width: width of the rectangle :param height: height of the rectangle :param stride: row stride of the grid .. method:: shift_left(amount: int) -> None Shifts all values in ``self`` to the left by ``amount``\. Values smaller than ``amount`` are discarded. :param amount: amount to shift all values to the left .. method:: shift_right(amount: int) -> None Shifts all values in ``self`` to the right by ``amount``\. Values that end up too large to be held in a :obj:`int` are discarded. :param amount: amount to shift all values to the right .. method:: splice(position: int, removed: int, added: int) -> None This is a support function for ``GListModel`` 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. :param position: position at which to slice :param removed: number of values to remove :param added: number of values to add .. method:: subtract(other: ~gi.repository.Gtk.Bitset) -> None 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. :param other: the ``GtkBitset`` to subtract .. method:: union(other: ~gi.repository.Gtk.Bitset) -> None 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. :param other: the ``GtkBitset`` to union with