pyroaring API documentation

class pyroaring.AbstractBitMap

Bases: object

An efficient and light-weight ordered set of 32 bits integers.

contains_range(range_start, range_end)

Check whether a range of values from range_start (included) to range_end (excluded) is present.

>>> bm = BitMap([5, 6, 7, 8, 9, 10])
>>> bm.contains_range(6, 9)
True
>>> bm.contains_range(8, 12)
False
copy()

Return a copy of a set.

>>> bm = BitMap([3, 12])
>>> bm2 = bm.copy()
>>> bm == bm2
True
>>> bm.add(1)
>>> bm == bm2
False
copy_on_write

True if and only if the bitmap has “copy on write” optimization enabled.

>>> BitMap(copy_on_write=False).copy_on_write
False
>>> BitMap(copy_on_write=True).copy_on_write
True
classmethod deserialize(buff)

Generate a bitmap from the given serialization. See AbstractBitMap.serialize for the reverse operation.

>>> BitMap.deserialize(BitMap([3, 12]).serialize())
BitMap([3, 12])
difference()

Return the difference of two or more sets as a new set.

(i.e. all elements that are in this set but not the others.)

>>> BitMap.difference(BitMap([1, 2, 3]), BitMap([2, 20]), BitMap([3, 30]))
BitMap([1])
difference_cardinality(other)

Return the number of elements in the difference of the two bitmaps.

It is equivalent to len(self - other), but faster.

>>> BitMap([3, 12]).difference_cardinality(BitMap([3, 5, 8]))
1
flip(start, end)

Compute the negation of the bitmap within the specified interval.

Areas outside the range are passed unchanged.

>>> bm = BitMap([3, 12])
>>> bm.flip(10, 15)
BitMap([3, 10, 11, 13, 14])
get_statistics()

Return relevant metrics about the bitmap.

>>> stats = BitMap(range(18, 66000, 2)).get_statistics()
>>> stats['cardinality']
32991
>>> stats['max_value']
65998
>>> stats['min_value']
18
>>> stats['n_array_containers']
1
>>> stats['n_bitset_containers']
1
>>> stats['n_bytes_array_containers']
464
>>> stats['n_bytes_bitset_containers']
8192
>>> stats['n_bytes_run_containers']
0
>>> stats['n_containers']
2
>>> stats['n_run_containers']
0
>>> stats['n_values_array_containers']
232
>>> stats['n_values_bitset_containers']
32759
>>> stats['n_values_run_containers']
0
>>> stats['sum_value'] 
0
intersect(other)

Return True if and only if the two bitmaps have elements in common.

It is equivalent to len(self & other) > 0, but faster.

>>> BitMap([3, 12]).intersect(BitMap([3, 18]))
True
>>> BitMap([3, 12]).intersect(BitMap([5, 18]))
False
intersection()

Return the intersection of the bitmaps.

>>> BitMap.intersection(BitMap(range(0, 15)), BitMap(range(5, 20)), BitMap(range(10, 25)))
BitMap([10, 11, 12, 13, 14])
intersection_cardinality(other)

Return the number of elements in the intersection of the two bitmaps.

It is equivalent to len(self & other), but faster.

>>> BitMap([3, 12]).intersection_cardinality(BitMap([3, 5, 8]))
1
isdisjoint(other)

Return True if two sets have a null intersection.

>>> BitMap([1, 2]).isdisjoint(BitMap([3, 4]))
True

>>> BitMap([1, 2, 3]).isdisjoint(BitMap([3, 4]))
False
issubset(other)

Report whether another set contains this set.

>>> BitMap([1, 2]).issubset(BitMap([1, 2, 3, 4]))
True

>>> BitMap([1, 2]).issubset(BitMap([3, 4]))
False
issuperset(other)

Report whether this set contains another set.

>>> BitMap([1, 2, 3, 4]).issuperset(BitMap([1, 2]))
True

>>> BitMap([1, 2]).issuperset(BitMap([3, 4]))
False
iter_equal_or_larger(val)

Iterate over items in the bitmap equal or larger than a given value.

>>> bm = BitMap([1, 2, 4])
>>> list(bm.iter_equal_or_larger(2))
[2, 4]
jaccard_index(other)

Compute the Jaccard index of the two bitmaps.

It is equivalent to len(self&other)/len(self|other), but faster. See https://en.wikipedia.org/wiki/Jaccard_index

>>> BitMap([3, 10, 12]).jaccard_index(BitMap([3, 18]))
0.25
max()

Return the maximum element of the bitmap.

It is equivalent to max(self), but faster.

>>> BitMap([3, 12]).max()
12
min()

Return the minimum element of the bitmap.

It is equivalent to min(self), but faster.

>>> BitMap([3, 12]).min()
3
next_set_bit(value)

Return the next set bit larger or equal to the given value.

>>> BitMap([1, 2, 4]).next_set_bit(1)
1

>>> BitMap([1, 2, 4]).next_set_bit(3)
4

>>> BitMap([1, 2, 4]).next_set_bit(5)
Traceback (most recent call last):
ValueError: No value larger or equal to specified value.
range_cardinality(range_start, range_end)

Return cardinality from range_start (included) to range_end (excluded).

>>> bm = BitMap(range(10))
>>> bm.range_cardinality(0, 10)
10
>>> bm.range_cardinality(10, 100)
0
rank(value)

Return the rank of the element in the bitmap.

>>> BitMap([3, 12]).rank(12)
2
run_optimize()
serialize()

Return the serialization of the bitmap. See AbstractBitMap.deserialize for the reverse operation.

>>> BitMap.deserialize(BitMap([3, 12]).serialize())
BitMap([3, 12])
shift(offset)

Add the value ‘offset’ to each and every value of the bitmap.

If offset + element is outside of the range [0,2^32), that the element will be dropped.

>>> bm = BitMap([3, 12])
>>> bm.shift(21)
BitMap([24, 33])
shrink_to_fit()
symmetric_difference(other)

Return the symmetric difference of two sets as a new set.

(i.e. all elements that are in exactly one of the sets.)

>>> BitMap([1, 2, 3]).symmetric_difference(BitMap([2, 3, 4]))
BitMap([1, 4])
symmetric_difference_cardinality(other)

Return the number of elements in the symmetric difference of the two bitmaps.

It is equivalent to len(self ^ other), but faster.

>>> BitMap([3, 12]).symmetric_difference_cardinality(BitMap([3, 5, 8]))
3
to_array()

Return an array.array containing the elements of the bitmap, in increasing order.

It is equivalent to array.array(‘I’, self), but more efficient.

>>> BitMap([3, 12]).to_array()
array('I', [3, 12])
union()

Return the union of the bitmaps.

>>> BitMap.union(BitMap([3, 12]), BitMap([5]), BitMap([0, 10, 12]))
BitMap([0, 3, 5, 10, 12])
union_cardinality(other)

Return the number of elements in the union of the two bitmaps.

It is equivalent to len(self | other), but faster.

>>> BitMap([3, 12]).union_cardinality(AbstractBitMap([3, 5, 8]))
4
class pyroaring.AbstractBitMap64

Bases: object

An efficient and light-weight ordered set of 64 bits integers.

contains_range(range_start, range_end)

Check whether a range of values from range_start (included) to range_end (excluded) is present.

>>> bm = BitMap64([5, 6, 7, 8, 9, 10])
>>> bm.contains_range(6, 9)
True
>>> bm.contains_range(8, 12)
False
copy()

Return a copy of a set.

>>> bm = BitMap64([3, 12])
>>> bm2 = bm.copy()
>>> bm == bm2
True
>>> bm.add(1)
>>> bm == bm2
False
copy_on_write

Always False, not implemented for 64 bits roaring bitmaps.

>>> BitMap64(copy_on_write=False).copy_on_write
False
>>> BitMap64(copy_on_write=True).copy_on_write
False
classmethod deserialize(buff)

Generate a bitmap from the given serialization. See AbstractBitMap64.serialize for the reverse operation.

>>> BitMap64.deserialize(BitMap64([3, 12]).serialize())
BitMap64([3, 12])
difference()

Return the difference of two or more sets as a new set.

(i.e. all elements that are in this set but not the others.)

>>> BitMap64.difference(BitMap64([1, 2, 3]), BitMap64([2, 20]), BitMap64([3, 30]))
BitMap64([1])
difference_cardinality(other)

Return the number of elements in the difference of the two bitmaps.

It is equivalent to len(self - other), but faster.

>>> BitMap64([3, 12]).difference_cardinality(BitMap64([3, 5, 8]))
1
flip(start, end)

Compute the negation of the bitmap within the specified interval.

Areas outside the range are passed unchanged.

>>> bm = BitMap64([3, 12])
>>> bm.flip(10, 15)
BitMap64([3, 10, 11, 13, 14])
get_statistics()

Return relevant metrics about the bitmap.

>>> stats = BitMap64(range(18, 66000, 2)).get_statistics()
>>> stats['cardinality']
32991
>>> stats['max_value']
65998
>>> stats['min_value']
18
>>> stats['n_array_containers']
1
>>> stats['n_bitset_containers']
1
>>> stats['n_bytes_array_containers']
464
>>> stats['n_bytes_bitset_containers']
8192
>>> stats['n_bytes_run_containers']
0
>>> stats['n_containers']
2
>>> stats['n_run_containers']
0
>>> stats['n_values_array_containers']
232
>>> stats['n_values_bitset_containers']
32759
>>> stats['n_values_run_containers']
0
intersect(other)

Return True if and only if the two bitmaps have elements in common.

It is equivalent to len(self & other) > 0, but faster.

>>> BitMap64([3, 12]).intersect(BitMap64([3, 18]))
True
>>> BitMap64([3, 12]).intersect(BitMap64([5, 18]))
False
intersection()

Return the intersection of the bitmaps.

>>> BitMap64.intersection(BitMap64(range(0, 15)), BitMap64(range(5, 20)), BitMap64(range(10, 25)))
BitMap64([10, 11, 12, 13, 14])
intersection_cardinality(other)

Return the number of elements in the intersection of the two bitmaps.

It is equivalent to len(self & other), but faster.

>>> BitMap64([3, 12]).intersection_cardinality(BitMap64([3, 5, 8]))
1
isdisjoint(other)

Return True if two sets have a null intersection.

>>> BitMap64([1, 2]).isdisjoint(BitMap64([3, 4]))
True

>>> BitMap64([1, 2, 3]).isdisjoint(BitMap64([3, 4]))
False
issubset(other)

Report whether another set contains this set.

>>> BitMap64([1, 2]).issubset(BitMap64([1, 2, 3, 4]))
True

>>> BitMap64([1, 2]).issubset(BitMap64([3, 4]))
False
issuperset(other)

Report whether this set contains another set.

>>> BitMap64([1, 2, 3, 4]).issuperset(BitMap64([1, 2]))
True

>>> BitMap64([1, 2]).issuperset(BitMap64([3, 4]))
False
iter_equal_or_larger(val)

Iterate over items in the bitmap equal or larger than a given value.

>>> bm = BitMap64([1, 2, 4])
>>> list(bm.iter_equal_or_larger(2))
[2, 4]
jaccard_index(other)

Compute the Jaccard index of the two bitmaps.

It is equivalent to len(self&other)/len(self|other), but faster. See https://en.wikipedia.org/wiki/Jaccard_index

>>> BitMap64([3, 10, 12]).jaccard_index(BitMap64([3, 18]))
0.25
max()

Return the maximum element of the bitmap.

It is equivalent to max(self), but faster.

>>> BitMap64([3, 12]).max()
12
min()

Return the minimum element of the bitmap.

It is equivalent to min(self), but faster.

>>> BitMap64([3, 12]).min()
3
next_set_bit(value)

Return the next set bit larger or equal to the given value.

>>> BitMap64([1, 2, 4]).next_set_bit(1)
1

>>> BitMap64([1, 2, 4]).next_set_bit(3)
4

>>> BitMap64([1, 2, 4]).next_set_bit(5)
Traceback (most recent call last):
ValueError: No value larger or equal to specified value.
range_cardinality(range_start, range_end)

Return cardinality from range_start (included) to range_end (excluded).

>>> bm = BitMap64(range(10))
>>> bm.range_cardinality(0, 10)
10
>>> bm.range_cardinality(10, 100)
0
rank(value)

Return the rank of the element in the bitmap.

>>> BitMap64([3, 12]).rank(12)
2
run_optimize()
serialize()

Return the serialization of the bitmap. See AbstractBitMap64.deserialize for the reverse operation.

>>> BitMap64.deserialize(BitMap64([3, 12]).serialize())
BitMap64([3, 12])
symmetric_difference(other)

Return the symmetric difference of two sets as a new set.

(i.e. all elements that are in exactly one of the sets.)

>>> BitMap64([1, 2, 3]).symmetric_difference(BitMap64([2, 3, 4]))
BitMap64([1, 4])
symmetric_difference_cardinality(other)

Return the number of elements in the symmetric difference of the two bitmaps.

It is equivalent to len(self ^ other), but faster.

>>> BitMap64([3, 12]).symmetric_difference_cardinality(BitMap64([3, 5, 8]))
3
to_array()

Return an array.array containing the elements of the bitmap, in increasing order.

It is equivalent to array.array(‘Q’, self), but more efficient.

>>> BitMap64([3, 12]).to_array()
array('Q', [3, 12])
union()

Return the union of the bitmaps.

>>> BitMap64.union(BitMap64([3, 12]), BitMap64([5]), BitMap64([0, 10, 12]))
BitMap64([0, 3, 5, 10, 12])
union_cardinality(other)

Return the number of elements in the union of the two bitmaps.

It is equivalent to len(self | other), but faster.

>>> BitMap64([3, 12]).union_cardinality(BitMap64([3, 5, 8]))
4
class pyroaring.BitMap

Bases: AbstractBitMap

add(value)

Add an element to the bitmap. This has no effect if the element is already present.

>>> bm = BitMap()
>>> bm.add(42)
>>> bm
BitMap([42])
>>> bm.add(42)
>>> bm
BitMap([42])
add_checked(value)

Add an element to the bitmap. This raises a KeyError exception if the element is already present.

>>> bm = BitMap()
>>> bm.add_checked(42)
>>> bm
BitMap([42])
>>> bm.add_checked(42)
Traceback (most recent call last):
...
KeyError: 42
add_range(range_start, range_end)

Add a range of values from range_start (included) to range_end (excluded).

>>> bm = BitMap([5, 7])
>>> bm.add_range(6, 9)
>>> bm
BitMap([5, 6, 7, 8])
clear()

Remove all elements from this set.

>>> bm = BitMap([1, 2, 3])
>>> bm.clear()
>>> bm
BitMap([])
difference_update(*others)

Remove all elements of another set from this set.

>>> bm = BitMap([1, 2, 3, 4, 5])
>>> bm.difference_update(BitMap([1, 2, 10]), BitMap([3, 4, 20]))
>>> bm
BitMap([5])
discard(value)

Remove an element from the bitmap. This has no effect if the element is not present.

>>> bm = BitMap([3, 12])
>>> bm.discard(3)
>>> bm
BitMap([12])
>>> bm.discard(3)
>>> bm
BitMap([12])
flip_inplace(start, end)

Compute (in place) the negation of the bitmap within the specified interval.

Areas outside the range are passed unchanged.

>>> bm = BitMap([3, 12])
>>> bm.flip_inplace(10, 15)
>>> bm
BitMap([3, 10, 11, 13, 14])
intersection_update(*all_values)

Update the bitmap by taking its intersection with the given values.

>>> bm = BitMap([3, 12])
>>> bm.intersection_update([8, 12, 55, 18])
>>> bm
BitMap([12])
overwrite(other)

Clear the bitmap and overwrite it with another.

>>> bm = BitMap([3, 12])
>>> other = BitMap([4, 14])
>>> bm.overwrite(other)
>>> other.remove(4)
>>> bm
BitMap([4, 14])
>>> other
BitMap([14])
pop()

Remove and return an arbitrary set element. Raises KeyError if the set is empty.

>>> bm = BitMap([1, 2])
>>> a = bm.pop()
>>> b = bm.pop()
>>> bm
BitMap([])
>>> bm.pop()
Traceback (most recent call last):
...
KeyError: 'pop from an empty BitMap'
remove(value)

Remove an element from the bitmap. This raises a KeyError exception if the element does not exist in the bitmap.

>>> bm = BitMap([3, 12])
>>> bm.remove(3)
>>> bm
BitMap([12])
>>> bm.remove(3)
Traceback (most recent call last):
...
KeyError: 3
remove_range(range_start, range_end)

Remove a range of values from range_start (included) to range_end (excluded).

>>> bm = BitMap([5, 6, 7, 8, 9, 10])
>>> bm.remove_range(6, 9)
>>> bm
BitMap([5, 9, 10])
symmetric_difference_update(other)

Update a set with the symmetric difference of itself and another.

>>> bm = BitMap([1, 2, 3, 4])
>>> bm.symmetric_difference_update(BitMap([1, 2, 10]))
>>> bm
BitMap([3, 4, 10])
update(*all_values)

Add all the given values to the bitmap.

>>> bm = BitMap([3, 12])
>>> bm.update([8, 12, 55, 18])
>>> bm
BitMap([3, 8, 12, 18, 55])
class pyroaring.BitMap64

Bases: AbstractBitMap64

add(value)

Add an element to the bitmap. This has no effect if the element is already present.

>>> bm = BitMap64()
>>> bm.add(42)
>>> bm
BitMap64([42])
>>> bm.add(42)
>>> bm
BitMap64([42])
add_checked(value)

Add an element to the bitmap. This raises a KeyError exception if the element is already present.

>>> bm = BitMap64()
>>> bm.add_checked(42)
>>> bm
BitMap64([42])
>>> bm.add_checked(42)
Traceback (most recent call last):
...
KeyError: 42
add_range(range_start, range_end)

Add a range of values from range_start (included) to range_end (excluded).

>>> bm = BitMap64([5, 7])
>>> bm.add_range(6, 9)
>>> bm
BitMap64([5, 6, 7, 8])
clear()

Remove all elements from this set.

>>> bm = BitMap64([1, 2, 3])
>>> bm.clear()
>>> bm
BitMap64([])
difference_update(*others)

Remove all elements of another set from this set.

>>> bm = BitMap64([1, 2, 3, 4, 5])
>>> bm.difference_update(BitMap64([1, 2, 10]), BitMap64([3, 4, 20]))
>>> bm
BitMap64([5])
discard(value)

Remove an element from the bitmap. This has no effect if the element is not present.

>>> bm = BitMap64([3, 12])
>>> bm.discard(3)
>>> bm
BitMap64([12])
>>> bm.discard(3)
>>> bm
BitMap64([12])
flip_inplace(start, end)

Compute (in place) the negation of the bitmap within the specified interval.

Areas outside the range are passed unchanged.

>>> bm = BitMap64([3, 12])
>>> bm.flip_inplace(10, 15)
>>> bm
BitMap64([3, 10, 11, 13, 14])
intersection_update(*all_values)

Update the bitmap by taking its intersection with the given values.

>>> bm = BitMap64([3, 12])
>>> bm.intersection_update([8, 12, 55, 18])
>>> bm
BitMap64([12])
pop()

Remove and return an arbitrary set element. Raises KeyError if the set is empty.

>>> bm = BitMap64([1, 2])
>>> a = bm.pop()
>>> b = bm.pop()
>>> bm
BitMap64([])
>>> bm.pop()
Traceback (most recent call last):
...
KeyError: 'pop from an empty BitMap64'
remove(value)

Remove an element from the bitmap. This raises a KeyError exception if the element does not exist in the bitmap.

>>> bm = BitMap64([3, 12])
>>> bm.remove(3)
>>> bm
BitMap64([12])
>>> bm.remove(3)
Traceback (most recent call last):
...
KeyError: 3
remove_range(range_start, range_end)

Remove a range of values from range_start (included) to range_end (excluded).

>>> bm = BitMap64([5, 6, 7, 8, 9, 10])
>>> bm.remove_range(6, 9)
>>> bm
BitMap64([5, 9, 10])
symmetric_difference_update(other)

Update a set with the symmetric difference of itself and another.

>>> bm = BitMap64([1, 2, 3, 4])
>>> bm.symmetric_difference_update(BitMap64([1, 2, 10]))
>>> bm
BitMap64([3, 4, 10])
update(*all_values)

Add all the given values to the bitmap.

>>> bm = BitMap64([3, 12])
>>> bm.update([8, 12, 55, 18])
>>> bm
BitMap64([3, 8, 12, 18, 55])
class pyroaring.FrozenBitMap

Bases: AbstractBitMap

class pyroaring.FrozenBitMap64

Bases: AbstractBitMap64

Indices and tables