pyroaring API documentation

class pyroaring.AbstractBitMap

Bases: object

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

contains_range

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

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

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'] 
1088966928
intersect

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

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

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

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

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

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

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

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

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

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])
shrink_to_fit
symmetric_difference

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

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

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.BitMap

Bases: pyroaring.AbstractBitMap

add

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

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

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

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

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

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

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

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

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

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

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

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.FrozenBitMap

Bases: pyroaring.AbstractBitMap

Indices and tables