3.3.1 GtkBitset
3.3.1 GtkBitset
GtkBitset — 整数集合。
函数
| GtkBitset * | gtk_bitset_ref () | void | gtk_bitset_unref () |
| GtkBitset * | gtk_bitset_new_empty () | GtkBitset * | gtk_bitset_new_range () |
| GtkBitset * | gtk_bitset_copy () | gboolean | gtk_bitset_contains () |
| gboolean | gtk_bitset_is_empty () | gboolean | gtk_bitset_equals () |
| guint | gtk_bitset_get_minimum () | guint | gtk_bitset_get_maximum () |
| guint64 | gtk_bitset_get_size () | guint64 | gtk_bitset_get_size_in_range () |
| guint | gtk_bitset_get_nth () | void | gtk_bitset_remove_all () |
| gboolean | gtk_bitset_add () | gboolean | gtk_bitset_remove () |
| void | gtk_bitset_add_range () | void | gtk_bitset_remove_range () |
| void | gtk_bitset_add_range_closed () | void | gtk_bitset_remove_range_closed () |
| void | gtk_bitset_add_rectangle () | void | gtk_bitset_remove_rectangle () |
| void | gtk_bitset_union () | void | gtk_bitset_intersect () |
| void | gtk_bitset_subtract () | void | gtk_bitset_difference () |
| void | gtk_bitset_shift_left () | void | gtk_bitset_shift_right () |
| void | gtk_bitset_splice () | gboolean | gtk_bitset_iter_init_first () |
| gboolean | gtk_bitset_iter_init_last () | gboolean | gtk_bitset_iter_init_at () |
| gboolean | gtk_bitset_iter_next () | gboolean | gtk_bitset_iter_previous () |
| guint | gtk_bitset_iter_get_value () | gboolean | gtk_bitset_iter_is_valid () |
类型与值
| GtkBitset | |
| struct | GtkBitsetIter |
对象层次结构
GBoxed
╰── GtkBitset
头文件
#include <gtk/gtk.h>
概述
GtkBitset 是一种用于表示无符号整数集合的数据结构，也称为“位图（bitmap）”。
当前实现基于 roaring bitmaps（一种高效的压缩位图算法）。
位图支持添加整数集合并提供集合操作，如并集、交集，以及检查相等性或值是否包含在集合中。GtkBitset 还包含各种函数用于查询位图的元数据，例如最小值、最大值或其大小。
遍历位图中值的最快方式是使用 GtkBitsetIter。
GtkBitset 的主要用例是为 GtkSelectionModel 实现复杂的选择功能。
函数详解
gtk_bitset_ref ()
GtkBitset *
gtk_bitset_ref (GtkBitset *self);
获取给定 GtkBitset 的引用。
参数
self 一个 GtkBitset 实例（instance）。 [允许为 NULL]
返回值
有额外引用的 GtkBitset。
[所有权不转移]
gtk_bitset_unref ()
void
gtk_bitset_unref (GtkBitset *self);
释放给定 GtkBitset 的一个引用。
如果该引用是最后一个，与 self 关联的资源将被释放。
参数
self 一个 GtkBitset 实例。 [允许为 NULL]
gtk_bitset_new_empty ()
GtkBitset *
gtk_bitset_new_empty (void);
创建一个新的空bitset。
返回值
一个新的空bitset。
gtk_bitset_new_range ()
GtkBitset *
gtk_bitset_new_range (guint start,
guint n_items);
创建一个包含指定范围的 bitset。
参数
start 要添加的第一个值。
n_items 要添加的连续值数量。
返回值
一个新的 bitset。
gtk_bitset_copy ()
GtkBitset *
gtk_bitset_copy (const GtkBitset *self);
创建 self 的副本。
参数
self 一个 GtkBitset 实例。
返回值
一个新的 bitset，包含与 self 相同的值。
[所有权转移]
gtk_bitset_contains ()
gboolean
gtk_bitset_contains (const GtkBitset *self,
guint value);
检查指定值是否已添加到 self 中。
参数
self 一个 GtkBitset 实例。
value 要检查的值。
返回值
如果 self 包含该值，则返回 TRUE。
gtk_bitset_is_empty ()
gboolean
gtk_bitset_is_empty (const GtkBitset *self);
检查 bitset 中是否不包含任何值。
参数
self 一个 GtkBitset 实例。
返回值
如果 self 为空，则返回 TRUE。
gtk_bitset_equals ()
gboolean
gtk_bitset_equals (const GtkBitset *self,
const GtkBitset *other);
如果 self 和 other 包含相同的值，则返回 TRUE。
参数
self 一个 GtkBitset 实例。
other 另一个 GtkBitset 实例。
返回值
如果 self 和 other 包含相同的值，则返回 TRUE。
gtk_bitset_get_minimum ()
guint
gtk_bitset_get_minimum (const GtkBitset *self);
返回 self 中的最小值。如果 self 为空，则返回 G_MAXUINT。
参数
self 一个 GtkBitset 实例。
返回值
self 中的最小值。
gtk_bitset_get_maximum ()
guint
gtk_bitset_get_maximum (const GtkBitset *self);
返回 self 中的最大值。如果 self 为空，则返回 0。
参数
self 一个 GtkBitset 实例。
返回值
self 中的最大值。
gtk_bitset_get_size ()
guint64
gtk_bitset_get_size (const GtkBitset *self);
获取已添加到集合中的值的数量。例如，如果集合为空，则返回 0。
注意：此函数返回 guint64 类型，因为当所有值都被设置时，返回值为 G_MAXUINT + 1。除非确定这种情况不会发生（对于 GListModel 而言不会发生），否则请确保使用 64 位类型。
参数
self 一个 GtkBitset 实例。
返回值
集合中的值的数量。
gtk_bitset_get_size_in_range ()
guint64
gtk_bitset_get_size_in_range (const GtkBitset *self,
guint first,
guint last);
获取集合中从 first 到 last（包含首尾）范围内的值的数量。
注意：此函数返回 guint64 类型，因为当所有值都被设置时，返回值为 G_MAXUINT + 1。除非确定这种情况不会发生（对于 GListModel 而言不会发生），否则请确保使用 64 位类型。
参数
self 一个 GtkBitset 实例。
first 要包含的第一个元素。
last 要包含的最后一个元素。
返回值
集合中从 first 到 last 范围内的值的数量。
gtk_bitset_get_nth ()
guint
gtk_bitset_get_nth (const GtkBitset *self,
guint nth);
返回 self 中第 nth 个项的值。
如果 nth 大于或等于 self 的大小，则返回 0。
参数
self 一个 GtkBitset 实例。
nth 要获取的项的索引。
返回值
self 中第 nth 个项的值。
gtk_bitset_remove_all ()
void
gtk_bitset_remove_all (GtkBitset *self);
从 bitset 中移除所有值，使其重新变为空。
参数
self 一个 GtkBitset 实例。
gtk_bitset_add ()
gboolean
gtk_bitset_add (GtkBitset *self,
guint value);
若 value 之前未包含在 self 中，则将其添加到 self。
参数
self 一个 GtkBitset 实例。
value 要添加的值。
返回值
如果 value 原本不在 self 中且 self 已被修改，则返回 TRUE。
gtk_bitset_remove ()
gboolean
gtk_bitset_remove (GtkBitset *self,
guint value);
若 value 之前包含在 self 中，则将其从 self 中移除。
参数
self 一个 GtkBitset 实例。
value 要移除的值。
返回值
如果 value 原本在 self 中且 self 已被修改，则返回 TRUE。
gtk_bitset_add_range ()
void
gtk_bitset_add_range (GtkBitset *self,
guint start,
guint n_items);
将从 start（包含）到 start + n_items（不包含）的所有值添加到 self 中。
参数
self 一个 GtkBitset 实例。
start 要添加的第一个值。
n_items 要添加的连续值数量。
gtk_bitset_remove_range ()
void
gtk_bitset_remove_range (GtkBitset *self,
guint start,
guint n_items);
将从 start（包含）到 start + n_items（不包含）的所有值从 self 中移除。
参数
self 一个 GtkBitset 实例。
start 要移除的第一个值。
n_items 要移除的连续值数量。
gtk_bitset_add_range_closed ()
void
gtk_bitset_add_range_closed (GtkBitset *self,
guint first,
guint last);
添加闭合范围 [first, last] 内的所有值，即包含 first、last 以及两者之间的所有值。first 必须小于 last。
参数
self 一个 GtkBitset 实例。
first 要添加的第一个值。
last 要添加的最后一个值。
gtk_bitset_remove_range_closed
void
gtk_bitset_remove_range_closed (GtkBitset *self,
guint first,
guint last);
移除闭合范围 [first, last] 内的所有值，即包含 first、last 以及两者之间的所有值。first 必须小于 last。
参数
self 一个 GtkBitset 实例。
first 要移除的第一个值。
last 要移除的最后一个值。
gtk_bitset_add_rectangle ()
void
gtk_bitset_add_rectangle (GtkBitset *self,
guint start,
guint width,
guint height,
guint stride);
将值解释为具有指定步长（stride）的二维布尔网格，并在该网格中添加一个具有指定宽度和高度的矩形区域所对应的所有值。
参数
self 一个 GtkBitset 实例。
start 要添加的第一个值。
width 矩形的宽度。
height 矩形的高度。
stride 网格的行步长。
gtk_bitset_remove_rectangle ()
void
gtk_bitset_remove_rectangle (GtkBitset *self,
guint start,
guint width,
guint height,
guint stride);
将值解释为具有指定步长（stride）的二维布尔网格，并在该网格中移除一个具有指定宽度和高度的矩形区域所对应的所有值。
参数
self 一个 GtkBitset 实例。
start 要移除的第一个值。
width 矩形的宽度。
height 矩形的高度。
stride 网格的行步长。
gtk_bitset_union ()
void
gtk_bitset_union (GtkBitset *self,
const GtkBitset *other);
将 self 设置为 self 和 other 的并集，即把 other 中所有原本不在包含在 self 中的值添加到 self 中。
允许 self 和 other 是同一个 bitset，这种情况下不会有任何操作。
参数
self 一个 GtkBitset 实例。
other 要进行并集操作的 GtkBitset 实例。
gtk_bitset_intersect ()
void
gtk_bitset_intersect (GtkBitset *self,
const GtkBitset *other);
将 self 设置为 self 和 other 的交集，即从 self 中移除所有不在 other 中的值。
允许 self 和 other 是同一个 bitset，这种情况下不会有任何操作。
参数
self 一个 GtkBitset 实例。
other 要进行交集操作的 GtkBitset 实例。
gtk_bitset_subtract ()
void
gtk_bitset_subtract (GtkBitset *self,
const GtkBitset *other);
将 self 设置为 self 减去 other 后的结果，即从 self 中移除所有同时存在于 other 中的值。
允许 self 和 other 是同一个 bitset，这种情况下该 bitset 会被清空。
参数
self 一个 GtkBitset 实例。
other 要从中减去的 GtkBitset 实例。
gtk_bitset_difference ()
void
gtk_bitset_difference (GtkBitset *self,
const GtkBitset *other);
将 self 设置为 self 和 other 的对称差集，即 self 中将包含所有仅存在于 self 中或仅存在于 other 中，但不同时存在于两者中的值。此操作也称为异或（XOR）。
允许 self 和 other 是同一个 bitset，这种情况下该 bitset 会被清空。
参数
self 一个 GtkBitset 实例。
other 用于计算对称差集的 GtkBitset 实例。
gtk_bitset_shift_left ()
void
gtk_bitset_shift_left (GtkBitset *self,
guint amount);
将 self 中的所有值向左移动指定的数量（amount）。小于该数量的值将被丢弃。
参数
self 一个 GtkBitset 实例。
amount 所有值向左移动的数量。
gtk_bitset_shift_right ()
void
gtk_bitset_shift_right (GtkBitset *self,
guint amount);
将 self 中的所有值向右移动指定的数量（amount）。移动后的值若大到无法用 guint 类型存储，则会被丢弃。
参数
self 一个 GtkBitset 实例。
amount 所有值向右移动的数量。
gtk_bitset_splice ()
void
gtk_bitset_splice (GtkBitset *self,
guint position,
guint removed,
guint added);
这是一个用于 GListModel 处理的支持函数，通过模拟“items-changed”信号实现功能。
首先，它从 bitset 中“剪切”从 position 开始的 removed 个值。也就是说，它会移除所有这些值，并将所有更大的值向左移动 removed 个位置。
然后，它通过将所有大于 position 的值向右移动 added 个位置，在 bitset 中“粘贴”出新的空间。这样就释放出可以填充的空间。
参数
self 一个 GtkBitset 实例。
position 进行切割的位置。
removed 要移除的值的数量。
added 要添加的空间数量。
gtk_bitset_iter_init_first ()
gboolean
gtk_bitset_iter_init_first (GtkBitsetIter *iter,
const GtkBitset *set,
guint *value);
初始化 set 的迭代器，并将其指向 set 中的第一个值。如果 set 为空，则返回 FALSE，且 value 会被设为 G_MAXUINT。
参数
iter 指向未初始化的GtkBitsetIter 的指针。 [输出参数]
set 一个 GtkBitset 实例。
value 被设置为 set 中的第一个值。 [输出参数][可选]
返回值
如果 set 不为空，则返回 TRUE。
gtk_bitset_iter_init_last ()
gboolean
gtk_bitset_iter_init_last (GtkBitsetIter *iter,
const GtkBitset *set,
guint *value);
初始化 set 的迭代器，并将其指向 set 中的最后一个值。如果 set 为空，则返回 FALSE。
参数
iter 指向未初始化的 GtkBitsetIter的指针。 [输出参数]
set 一个 GtkBitset 实例。
value 被设置为 set 中的最后一个值。 [输出参数][可选]
返回值
如果 set 不为空，则返回 TRUE。
gtk_bitset_iter_init_at ()
gboolean
gtk_bitset_iter_init_at (GtkBitsetIter *iter,
const GtkBitset *set,
guint target,
guint *value);
初始化迭代器 iter 以指向 target 值。如果未找到 target，则指向其之后的下一个值。如果 set 中不存在大于或等于 target 的值，此函数返回 FALSE。
参数
iter 指向未初始化的 GtkBitsetIter的指针。 [输出参数]
set 一个 GtkBitset 实例。
target 开始迭代的目标值。
value 被设置为在 set 中找到的值。 [输出参数][可选]
返回值
如果找到值，则返回 TRUE。
gtk_bitset_iter_next ()
gboolean
gtk_bitset_iter_next (GtkBitsetIter *iter,
guint *value);
将迭代器 iter 移动到集合中的下一个值。如果迭代器已经指向集合中的最后一个值，则返回 FALSE，且迭代器会变为无效。
参数
iter 指向有效的 GtkBitsetIter 的指针。
value 被设置为下一个值。 [输出参数][可选]
返回值
如果存在下一个值，则返回 TRUE。
gtk_bitset_iter_previous ()
gboolean
gtk_bitset_iter_previous (GtkBitsetIter *iter,
guint *value);
将迭代器 iter 移动到集合中的前一个值。如果迭代器已经指向集合中的第一个值，则返回 FALSE，且迭代器会变为无效。
参数
iter 指向有效的 GtkBitsetIter 的指针。
value 被设置为前一个值。 [输出参数][可选]
返回值
如果存在前一个值，则返回 TRUE。
gtk_bitset_iter_get_value ()
guint
gtk_bitset_iter_get_value (const GtkBitsetIter *iter);
获取迭代器 iter 当前指向的值。
如果迭代器无效（即 gtk_bitset_iter_is_valid() 返回 FALSE），此函数将返回 0。
参数
iter 一个 GtkBitsetIter 实例。
返回值
迭代器 iter 当前指向的值。
gtk_bitset_iter_is_valid ()
gboolean
gtk_bitset_iter_is_valid (const GtkBitsetIter *iter);
检查迭代器 iter 是否指向一个有效的值。
参数
iter 一个 GtkBitsetIter 实例。
返回值
如果 iter 指向一个有效的值，则返回 TRUE。
类型与值详解
GtkBitset
typedef struct _GtkBitset GtkBitset;
GtkBitset 结构体仅包含私有数据（外部不可直接访问）。
struct GtkBitsetIter
struct GtkBitsetIter {
};
用于遍历 GtkBitset 元素的不透明栈分配结构体。在使用 GtkBitsetIter 之前，必须通过以下函数对其进行初始化：gtk_bitset_iter_init_first()、gtk_bitset_iter_init_last()、gtk_bitset_iter_init_at()。
另参阅
GtkSelectionModel。
通过网盘分享的知识：GTK 4 Reference Manual
链接: https://pan.baidu.com/s/57mKoejMZPrxs_wh3a7Kj9g
--来自百度网盘超级会员v7的分享
浙公网安备 33010602011771号