/* * Copyright © 2020 Benjamin Otte * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library. If not, see . * * Authors: Benjamin Otte */ #include "config.h" #include "gtkbitset.h" #include "roaring/roaring.c" /** * SECTION:gtkbitset * @title: GtkBitset * @short_description: Sets of integers * @see_also: #GtkSelectionModel * * #GtkBitset is a data structure for representing 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. #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 #GtkBitsetIter. * * The main use case for #GtkBitset is implementing complex selections for * #GtkSelectionModel. */ /** * GtkBitset: (ref-func gtk_bitset_ref) (unref-func gtk_bitset_unref) * * The `GtkBitset` structure contains only private data. */ struct _GtkBitset { int ref_count; roaring_bitmap_t roaring; }; G_DEFINE_BOXED_TYPE (GtkBitset, gtk_bitset, gtk_bitset_ref, gtk_bitset_unref) /** * gtk_bitset_ref: * @self: (allow-none): a #GtkBitset * * Acquires a reference on the given #GtkBitset. * * Returns: (transfer none): the #GtkBitset with an additional reference */ GtkBitset * gtk_bitset_ref (GtkBitset *self) { g_return_val_if_fail (self != NULL, NULL); self->ref_count += 1; return self; } /** * gtk_bitset_unref: * @self: (allow-none): a #GtkBitset * * Releases a reference on the given #GtkBitset. * * If the reference was the last, the resources associated to the @self are * freed. */ void gtk_bitset_unref (GtkBitset *self) { g_return_if_fail (self != NULL); g_return_if_fail (self->ref_count > 0); self->ref_count -= 1; if (self->ref_count > 0) return; ra_clear (&self->roaring.high_low_container); g_slice_free (GtkBitset, self); } /** * gtk_bitset_contains: * @self: a #GtkBitset * @value: the value to check * * Checks if the given @value has been added to @bitset * * Returns: %TRUE if @self contains @value **/ gboolean gtk_bitset_contains (const GtkBitset *self, guint value) { g_return_val_if_fail (self != NULL, FALSE); return roaring_bitmap_contains (&self->roaring, value); } /** * gtk_bitset_is_empty: * @self: a #GtkBitset * * Check if no value is contained in bitset. * * Returns: %TRUE if @self is empty **/ gboolean gtk_bitset_is_empty (const GtkBitset *self) { g_return_val_if_fail (self != NULL, TRUE); return roaring_bitmap_is_empty (&self->roaring); } /** * gtk_bitset_equals: * @self: a #GtkBitset * @other: another #GtkBitset * * Returns %TRUE if @self and @other contain the same values. * * Returns: %TRUE if @self and @other contain the same values **/ gboolean gtk_bitset_equals (const GtkBitset *self, const GtkBitset *other) { g_return_val_if_fail (self != NULL, other == NULL); g_return_val_if_fail (other != NULL, FALSE); if (self == other) return TRUE; return roaring_bitmap_equals (&self->roaring, &other->roaring); } /** * gtk_bitset_get_minimum: * @self: a #GtkBitset * * Returns the smallest value in @self. If @self is empty, * G_MAXUINT is returned. * * Returns: The smallest value in @self **/ guint gtk_bitset_get_minimum (const GtkBitset *self) { g_return_val_if_fail (self != NULL, G_MAXUINT); return roaring_bitmap_minimum (&self->roaring); } /** * gtk_bitset_get_maximum: * @self: a #GtkBitset * * Returns the largest value in @self. If @self is empty, * 0 is returned. * * Returns: The largest value in @self **/ guint gtk_bitset_get_maximum (const GtkBitset *self) { g_return_val_if_fail (self != NULL, 0); return roaring_bitmap_maximum (&self->roaring); } /** * gtk_bitset_get_size: * @self: a #GtkBitset * * 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. * * Returns: The number of values in the set. **/ guint64 gtk_bitset_get_size (const GtkBitset *self) { g_return_val_if_fail (self != NULL, 0); return roaring_bitmap_get_cardinality (&self->roaring); } /** * gtk_bitset_get_size_in_range: * @self: a #GtkBitset * @first: the first element to include * @last: the last element to include * * 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. * * Returns: The number of values in the set from @first to @last. **/ guint64 gtk_bitset_get_size_in_range (const GtkBitset *self, guint first, guint last) { g_return_val_if_fail (self != NULL, 0); g_return_val_if_fail (last >= first, 0); return roaring_bitmap_range_cardinality (&self->roaring, first, ((uint64_t) last) + 1); } /** * gtk_bitset_get_nth: * @self: a #GtkBitset * @nth: index of the item to get * * Returns the value of the @nth item in self. * * If @nth is >= the size of @self, 0 is returned. * * Returns: the value of the @nth item in @self **/ guint gtk_bitset_get_nth (const GtkBitset *self, guint nth) { uint32_t result; if (!roaring_bitmap_select (&self->roaring, nth, &result)) return 0; return result; } /** * gtk_bitset_new_empty: * * Creates a new empty bitset. * * Returns: A new empty bitset **/ GtkBitset * gtk_bitset_new_empty (void) { GtkBitset *self; self = g_slice_new0 (GtkBitset); self->ref_count = 1; ra_init (&self->roaring.high_low_container); return self; } /** * gtk_bitset_new_range: * @start: first value to add * @n_items: number of consecutive values to add * * Creates a bitset with the given range set. * * Returns: A new bitset **/ GtkBitset * gtk_bitset_new_range (guint start, guint n_items) { GtkBitset *self; self = gtk_bitset_new_empty (); gtk_bitset_add_range (self, start, n_items); return self; } /** * gtk_bitset_copy: * @self: a #GtkBitset * * Creates a copy of @self. * * Returns: (transfer full): A new bitset that contains the same * values as @self **/ GtkBitset * gtk_bitset_copy (const GtkBitset *self) { GtkBitset *copy; g_return_val_if_fail (self != NULL, NULL); copy = gtk_bitset_new_empty (); roaring_bitmap_overwrite (©->roaring, &self->roaring); return copy; } /** * gtk_bitset_remove_all: * @self: a #GtkBitset * * Removes all values from the bitset so that it is empty again. **/ void gtk_bitset_remove_all (GtkBitset *self) { g_return_if_fail (self != NULL); roaring_bitmap_clear (&self->roaring); } /** * gtk_bitset_add: * @self: a #GtkBitset * @value: value to add * * Adds @value to @self if it wasn't part of it before. * * Returns: %TRUE if @value was not part of @self and @self * was changed. **/ gboolean gtk_bitset_add (GtkBitset *self, guint value) { g_return_val_if_fail (self != NULL, FALSE); return roaring_bitmap_add_checked (&self->roaring, value); } /** * gtk_bitset_remove: * @self: a #GtkBitset * @value: value to add * * Removes @value from @self if it was part of it before. * * Returns: %TRUE if @value was part of @self and @self * was changed. **/ gboolean gtk_bitset_remove (GtkBitset *self, guint value) { g_return_val_if_fail (self != NULL, FALSE); return roaring_bitmap_remove_checked (&self->roaring, value); } /** * gtk_bitset_add_range: * @self: a #GtkBitset * @start: first value to add * @n_items: number of consecutive values to add * * Adds all values from @start (inclusive) to @start + @n_items * (exclusive) in @self. **/ void gtk_bitset_add_range (GtkBitset *self, guint start, guint n_items) { g_return_if_fail (self != NULL); if (n_items == 0) return; /* overflow check, the == 0 is to allow add_range(G_MAXUINT, 1); */ g_return_if_fail (start + n_items == 0 || start + n_items > start); roaring_bitmap_add_range_closed (&self->roaring, start, start + n_items - 1); } /** * gtk_bitset_remove_range: * @self: a #GtkBitset * @start: first value to remove * @n_items: number of consecutive values to remove * * Removes all values from @start (inclusive) to @start + @n_items (exclusive) * in @self. **/ void gtk_bitset_remove_range (GtkBitset *self, guint start, guint n_items) { g_return_if_fail (self != NULL); if (n_items == 0) return; /* overflow check, the == 0 is to allow add_range(G_MAXUINT, 1); */ g_return_if_fail (start + n_items == 0 || start + n_items > start); roaring_bitmap_remove_range_closed (&self->roaring, start, start + n_items - 1); } /** * gtk_bitset_add_range_closed: * @self: a #GtkBitset * @first: first value to add * @last: last value to add * * Adds the closed range [@first, @last], so @first, @last and all * values inbetween. @first must be smaller than @last. **/ void gtk_bitset_add_range_closed (GtkBitset *self, guint first, guint last) { g_return_if_fail (self != NULL); g_return_if_fail (first <= last); roaring_bitmap_add_range_closed (&self->roaring, first, last); } /** * gtk_bitset_remove_range_closed: * @self: a #GtkBitset * @first: first value to remove * @last: last value to remove * * Removes the closed range [@first, @last], so @first, @last and all * values inbetween. @first must be smaller than @last. **/ void gtk_bitset_remove_range_closed (GtkBitset *self, guint first, guint last) { g_return_if_fail (self != NULL); g_return_if_fail (first <= last); roaring_bitmap_remove_range_closed (&self->roaring, first, last); } /** * gtk_bitset_add_rectangle: * @self: a #GtkBitset * @start: first value to add * @width: width of the rectangle * @height: height of the rectangle * @stride: row stride of the grid * * 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. **/ void gtk_bitset_add_rectangle (GtkBitset *self, guint start, guint width, guint height, guint stride) { guint i; g_return_if_fail (self != NULL); g_return_if_fail ((start % stride) + width <= stride); g_return_if_fail (G_MAXUINT - start >= height * stride); if (width == 0 || height == 0) return; for (i = 0; i < height; i++) gtk_bitset_add_range (self, i * stride + start, width); } /** * gtk_bitset_remove_rectangle: * @self: a #GtkBitset * @start: first value to remove * @width: width of the rectangle * @height: height of the rectangle * @stride: row stride of the grid * * 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. **/ void gtk_bitset_remove_rectangle (GtkBitset *self, guint start, guint width, guint height, guint stride) { guint i; g_return_if_fail (self != NULL); g_return_if_fail (width <= stride); g_return_if_fail (G_MAXUINT - start >= height * stride); if (width == 0 || height == 0) return; for (i = 0; i < height; i++) gtk_bitset_remove_range (self, i * stride + start, width); } /** * gtk_bitset_union: * @self: a #GtkBitset * @other: the #GtkBitset to union with * * 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. **/ void gtk_bitset_union (GtkBitset *self, const GtkBitset *other) { g_return_if_fail (self != NULL); g_return_if_fail (other != NULL); if (self == other) return; roaring_bitmap_or_inplace (&self->roaring, &other->roaring); } /** * gtk_bitset_intersect: * @self: a #GtkBitset * @other: the #GtkBitset to intersect with * * Sets @self to be the intersection of @self and @other, that is 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. **/ void gtk_bitset_intersect (GtkBitset *self, const GtkBitset *other) { g_return_if_fail (self != NULL); g_return_if_fail (other != NULL); if (self == other) return; roaring_bitmap_and_inplace (&self->roaring, &other->roaring); } /** * gtk_bitset_subtract: * @self: a #GtkBitset * @other: the #GtkBitset to subtract * * Sets @self to be the subtraction of @other from @self, that is 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. **/ void gtk_bitset_subtract (GtkBitset *self, const GtkBitset *other) { g_return_if_fail (self != NULL); g_return_if_fail (other != NULL); if (self == other) { roaring_bitmap_clear (&self->roaring); return; } roaring_bitmap_andnot_inplace (&self->roaring, &other->roaring); } /** * gtk_bitset_difference: * @self: a #GtkBitset * @other: the #GtkBitset to compute the difference from * * Sets @self to be the symmetric difference of @self and @other, that * 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. **/ void gtk_bitset_difference (GtkBitset *self, const GtkBitset *other) { g_return_if_fail (self != NULL); g_return_if_fail (other != NULL); if (self == other) { roaring_bitmap_clear (&self->roaring); return; } roaring_bitmap_xor_inplace (&self->roaring, &other->roaring); } /** * gtk_bitset_shift_left: * @self: a $GtkBitset * @amount: amount to shift all values to the left * * Shifts all values in @self to the left by @amount. Values * smaller than @amount are discarded. **/ void gtk_bitset_shift_left (GtkBitset *self, guint amount) { GtkBitset *original; GtkBitsetIter iter; guint value; gboolean loop; g_return_if_fail (self != NULL); if (amount == 0) return; original = gtk_bitset_copy (self); gtk_bitset_remove_all (self); for (loop = gtk_bitset_iter_init_at (&iter, original, amount, &value); loop; loop = gtk_bitset_iter_next (&iter, &value)) { gtk_bitset_add (self, value - amount); } gtk_bitset_unref (original); } /** * gtk_bitset_shift_right: * @self: a $GtkBitset * @amount: amount to shift all values to the 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. **/ void gtk_bitset_shift_right (GtkBitset *self, guint amount) { GtkBitset *original; GtkBitsetIter iter; guint value; gboolean loop; g_return_if_fail (self != NULL); if (amount == 0) return; original = gtk_bitset_copy (self); gtk_bitset_remove_all (self); for (loop = gtk_bitset_iter_init_first (&iter, original, &value); loop && value <= G_MAXUINT - amount; loop = gtk_bitset_iter_next (&iter, &value)) { gtk_bitset_add (self, value + amount); } gtk_bitset_unref (original); } /** * gtk_bitset_splice: * @self: a #GtkBitset * @position: position at which to slice * @removed: number of values to remove * @added: number of values to add * * 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. **/ void gtk_bitset_splice (GtkBitset *self, guint position, guint removed, guint added) { g_return_if_fail (self != NULL); /* overflow */ g_return_if_fail (position + removed >= position); g_return_if_fail (position + added >= position); gtk_bitset_remove_range (self, position, removed); if (removed != added) { GtkBitset *shift = gtk_bitset_copy (self); gtk_bitset_remove_range (shift, 0, position); gtk_bitset_remove_range_closed (self, position, G_MAXUINT); if (added > removed) gtk_bitset_shift_right (shift, added - removed); else gtk_bitset_shift_left (shift, removed - added); gtk_bitset_union (self, shift); gtk_bitset_unref (shift); } } G_STATIC_ASSERT (sizeof (GtkBitsetIter) >= sizeof (roaring_uint32_iterator_t)); /** * gtk_bitset_iter_init_first: * @iter: (out): a pointer to an uninitialized #GtkBitsetIter * @set: a #GtkBitset * @value: (out) (optional): Set to the first value in @set * * Initializes an iterator for @set and points it to the first * value in @set. If @set is empty, %FALSE is returned and @value * is set to %G_MAXUINT. * * Returns: %TRUE if @set isn't empty. **/ gboolean gtk_bitset_iter_init_first (GtkBitsetIter *iter, const GtkBitset *set, guint *value) { roaring_uint32_iterator_t *riter = (roaring_uint32_iterator_t *) iter; g_return_val_if_fail (iter != NULL, FALSE); g_return_val_if_fail (set != NULL, FALSE); roaring_init_iterator (&set->roaring, riter); if (value) *value = riter->has_value ? riter->current_value : 0; return riter->has_value; } /** * gtk_bitset_iter_init_last: * @iter: (out): a pointer to an uninitialized #GtkBitsetIter * @set: a #GtkBitset * @value: (out) (optional): Set to the last value in @set * * Initializes an iterator for @set and points it to the last * value in @set. If @set is empty, %FALSE is returned. * * Returns: %TRUE if @set isn't empty. **/ gboolean gtk_bitset_iter_init_last (GtkBitsetIter *iter, const GtkBitset *set, guint *value) { roaring_uint32_iterator_t *riter = (roaring_uint32_iterator_t *) iter; g_return_val_if_fail (iter != NULL, FALSE); g_return_val_if_fail (set != NULL, FALSE); roaring_init_iterator_last (&set->roaring, riter); if (value) *value = riter->has_value ? riter->current_value : 0; return riter->has_value; } /** * gtk_bitset_iter_init_at: * @iter: (out): a pointer to an uninitialized #GtkBitsetIter * @set: a #GtkBitset * @target: target value to start iterating at * @value: (out) (optional): Set to the found value in @set * * Initializes @iter to point to @target. If @target is not found, finds * the next value after it. If no value >= @target exists in @set, this * function returns %FALSE. * * Returns: %TRUE if a value was found. **/ gboolean gtk_bitset_iter_init_at (GtkBitsetIter *iter, const GtkBitset *set, guint target, guint *value) { roaring_uint32_iterator_t *riter = (roaring_uint32_iterator_t *) iter; g_return_val_if_fail (iter != NULL, FALSE); g_return_val_if_fail (set != NULL, FALSE); roaring_init_iterator (&set->roaring, riter); if (!roaring_move_uint32_iterator_equalorlarger (riter, target)) { if (value) *value = 0; return FALSE; } if (value) *value = riter->current_value; return TRUE; } /** * gtk_bitset_iter_next: * @iter: a pointer to a valid #GtkBitsetIter * @value: (out) (optional): Set to the next value * * Moves @iter to the next value in the set. If it was already * pointing to the last value in the set, %FALSE is returned and * @iter is invalidated. * * Returns: %TRUE if a next value existed **/ gboolean gtk_bitset_iter_next (GtkBitsetIter *iter, guint *value) { roaring_uint32_iterator_t *riter = (roaring_uint32_iterator_t *) iter; g_return_val_if_fail (iter != NULL, FALSE); if (!roaring_advance_uint32_iterator (riter)) { if (value) *value = 0; return FALSE; } if (value) *value = riter->current_value; return TRUE; } /** * gtk_bitset_iter_previous: * @iter: a pointer to a valid #GtkBitsetIter * @value: (out) (optional): Set to the previous value * * Moves @iter to the previous value in the set. If it was already * pointing to the first value in the set, %FALSE is returned and * @iter is invalidated. * * Returns: %TRUE if a previous value existed **/ gboolean gtk_bitset_iter_previous (GtkBitsetIter *iter, guint *value) { roaring_uint32_iterator_t *riter = (roaring_uint32_iterator_t *) iter; g_return_val_if_fail (iter != NULL, FALSE); if (!roaring_previous_uint32_iterator (riter)) { if (value) *value = 0; return FALSE; } if (value) *value = riter->current_value; return TRUE; } /** * gtk_bitset_iter_get_value: * @iter: a #GtkBitsetIter * * Gets the current value that @iter points to. * * If @iter is not valid and gtk_bitset_iter_is_valid() returns * %FALSE, this function returns 0. * * Returns: The current value pointer to by @iter **/ guint gtk_bitset_iter_get_value (const GtkBitsetIter *iter) { roaring_uint32_iterator_t *riter = (roaring_uint32_iterator_t *) iter; g_return_val_if_fail (iter != NULL, 0); if (!riter->has_value) return 0; return riter->current_value; } /** * gtk_bitset_iter_is_valid: * @iter: a #GtkBitsetIter * * Checks if @iter points to a valid value. * * Returns: %TRUE if @iter points to a valid value **/ gboolean gtk_bitset_iter_is_valid (const GtkBitsetIter *iter) { roaring_uint32_iterator_t *riter = (roaring_uint32_iterator_t *) iter; g_return_val_if_fail (iter != NULL, FALSE); return riter->has_value; }