IntSet

IntSet is an immutable set of non-negative integers backed by a Roaring bitmap. Union, intersection and difference run in Rust over compressed bitmaps with no per-element Python work. Use it for large sets of integer IDs where an ISet of boxed ints is the bottleneck.

from pyrula import IntSet

s = IntSet([1, 2, 3, 3, 2])   # duplicates dropped
len(s)                         # 3
2 in s                         # True
s.add(4).to_list()             # [1, 2, 3, 4]; s is unchanged
IntSet().is_empty()            # True

Values must fit in an unsigned 64-bit integer; negatives and out-of-range values raise ValueError, non-integers TypeError. Membership and comparison accept any number equal to a member, as frozenset does (1.0, a NumPy integer). contains raises TypeError for a value that equals no integer, where in answers False.

Set algebra

a = IntSet([1, 2, 3, 4])
b = IntSet([3, 4, 5])

a.union(b)                  # IntSet([1, 2, 3, 4, 5])
a.intersection(b)           # IntSet([3, 4])
a.difference(b)             # IntSet([1, 2])
a.symmetric_difference(b)   # IntSet([1, 2, 5])

IntSet([3, 4]).is_subset(a)     # True
IntSet([7, 8]).is_disjoint(a)   # True
a.cardinality()                 # 4

to_list returns a list[int] in ascending order.

Serialization

to_bytes writes the Roaring portable format, readable by other Roaring implementations. This suits durable state such as a persisted “seen” set.

blob = IntSet([1, 5, 9, 2**40]).to_bytes()
IntSet.from_bytes(blob).to_list()   # [1, 5, 9, 1099511627776]

Performance

IntSet pays off for dense or clustered integers (entity IDs, row offsets), where set algebra is far faster than a Python set. For integers spread uniformly across the 64-bit range the bitmap can’t compress, and a plain set or ISet is faster.