intbitset

https://intbitset.readthedocs.io/en/latest/
Admin
The intbitset project provides a Python C extension for an `intbitset` data object, efficiently...
Tokens:6,870
Snippets:91
Trust Score:9.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### __getitem__ (Get Item)

Source: https://intbitset.readthedocs.io/en/latest/index.html

Retrieves an element from the intbitset by its index or key.

```APIDOC
## __getitem__(self, y)

### Description
Retrieves the element at index/key `y` from the intbitset `x`.

### Syntax
x.__getitem__(y) <==> x[y]
```

--------------------------------

### Create and Operate on intbitsets

Source: https://intbitset.readthedocs.io/en/latest/index.html

Demonstrates the creation of intbitset objects and basic set operations like intersection and union. Ensure the intbitset library is imported.

```python
>>> from intbitset import intbitset
>>> x = intbitset([1,2,3])
>>> y = intbitset([3,4,5])
>>> x & y
intbitset([3])
>>> x | y
intbitset([1, 2, 3, 4, 5])
```

--------------------------------

### Preparation for Performance Tests

Source: https://intbitset.readthedocs.io/en/latest/index.html

Sets up sparse and dense integer populations using both Python's built-in `set` and `intbitset` for performance comparisons. This includes defining sample populations and key values for testing.

```python
## preparation
from intbitset import intbitset
from random import sample
sparse_population1 = sample(range(1000000), 10000)
sparse_population2 = sample(range(1000000), 10000)
dense_population1 = sample(range(1000000), 900000)
dense_population2 = sample(range(1000000), 900000)
sparse_set1 = set(sparse_population1)
sparse_set2 = set(sparse_population2)
sparse_intbitset1 = intbitset(sparse_population1)
sparse_intbitset2 = intbitset(sparse_population2)
dense_set1 = set(dense_population1)
dense_set2 = set(dense_population2)
dense_intbitset1 = intbitset(dense_population1)
dense_intbitset2 = intbitset(dense_population2)
sorted(sparse_population1)[5000:5002]
in_sparse = 500095
not_in_sparse = 500096
sorted(dense_population1)[500000:500002]
in_dense = 555705
not_in_dense = 555706
```

--------------------------------

### copy

Source: https://intbitset.readthedocs.io/en/latest/index.html

Returns a shallow copy of the intbitset.

```APIDOC
## copy(self)

### Description
Return a shallow copy of the intbitset.
```

--------------------------------

### fastload

Source: https://intbitset.readthedocs.io/en/latest/index.html

Loads a compressed string representation into the current intbitset, replacing its content.

```APIDOC
## fastload()

### Description
Load a compressed string representation produced by a previous call to the fastdump method into the current intbitset. The previous content will be replaced.

### Method
N/A (Method call)

### Endpoint
N/A (Method call)
```

--------------------------------

### intbitset Constructor

Source: https://intbitset.readthedocs.io/en/latest/index.html

Initializes an intbitset object. It can be created from various types including integers, other intbitsets, byte strings, arrays, sequences of integers, or sequences of tuples.

```APIDOC
## intbitset(rhs=0, int preallocate=-1, int trailing_bits=0, bint sanity_checks=CFG_INTBITSET_ENABLE_SANITY_CHECKS, int no_allocate=0)

### Description
Initializes an intbitset object. The `rhs` parameter can be an integer, another `intbitset`, a byte string, an array, a sequence of integers, or a sequence of tuples.

### Parameters
- **rhs**: Can be `int/long`, `intbitset`, `bytes`, `array`, a sequence of integers, or a sequence of tuples.
- **preallocate** (int): Suggested initial upper bound on numbers to be stored.
- **trailing_bits** (int): If 1, the set will contain all positive integers.
- **sanity_checks** (bint): Used internally, typically enabled by default.
- **no_allocate** (int): Used internally.
```

--------------------------------

### add

Source: https://intbitset.readthedocs.io/en/latest/index.html

Adds a single element to the intbitset. If the element already exists, the set remains unchanged.

```APIDOC
## add(self, element)

### Description
Add an element to a set. This has no effect if the element is already present.

### Parameters
- **element**: The element to add to the set.
```

--------------------------------

### __eq__ (Equality)

Source: https://intbitset.readthedocs.io/en/latest/index.html

Compares two intbitsets for equality.

```APIDOC
## __eq__(self, y)

### Description
Compares intbitset `x` with `y` for equality.

### Syntax
x.__eq__(y) <==> x==y
```

--------------------------------

### Membership Test Performance

Source: https://intbitset.readthedocs.io/en/latest/index.html

Compares the speed of membership testing (`in`) for elements within `set` and `intbitset` for both sparse and dense collections. `intbitset` generally offers slightly better performance.

```python
## Membership tests
%timeit in_sparse in sparse_set1
%timeit in_sparse in sparse_intbitset1 ## 1.5 times faster
%timeit not_in_sparse in sparse_set1
%timeit not_in_sparse in sparse_intbitset1 ## 1.6 times faster
%timeit in_dense in dense_set1
%timeit in_dense in dense_intbitset1 ## 1.3 times faster
%timeit not_in_dense in dense_set1
%timeit not_in_dense in dense_intbitset1 ## similar speed
```

--------------------------------

### __le__ (Less Than or Equal)

Source: https://intbitset.readthedocs.io/en/latest/index.html

Compares if one intbitset is less than or equal to another.

```APIDOC
## __le__(self, y)

### Description
Compares if intbitset `x` is less than or equal to `y`.

### Syntax
x.__le__(y) <==> x<=y
```

--------------------------------

### tolist

Source: https://intbitset.readthedocs.io/en/latest/index.html

Legacy method to retrieve a list of all elements contained within the intbitset.

```APIDOC
## tolist()

### Description
Legacy method to retrieve a list of all the elements inside an intbitset.

### Method
N/A (Method call)

### Endpoint
N/A (Method call)
```

--------------------------------

### __iadd__ (In-place Add)

Source: https://intbitset.readthedocs.io/en/latest/index.html

Adds elements to the intbitset in-place.

```APIDOC
## __iadd__(self, y)

### Description
Adds elements from `y` to the intbitset `x` in-place.

### Syntax
x.__iadd__(y) <==> x+=y
```

--------------------------------

### Sparse Set Operations Performance

Source: https://intbitset.readthedocs.io/en/latest/index.html

Compares the performance of bitwise AND, OR, XOR, and subtraction operations between `set` and `intbitset` for sparse integer collections. `intbitset` demonstrates significantly faster execution times.

```python
## Sparse sets operations
%timeit sparse_set1 & sparse_set2
%timeit sparse_intbitset1 & sparse_intbitset2 ## more than 20 times faster
%timeit sparse_set1 | sparse_set2
%timeit sparse_intbitset1 | sparse_intbitset2 ## almost 70 times faster
%timeit sparse_set1 ^ sparse_set2
%timeit sparse_intbitset1 ^ sparse_intbitset2 ## more than 80 times faster
%timeit sparse_set1 - sparse_set2
%timeit sparse_intbitset1 - sparse_intbitset2 ## almost 60 times faster
```

--------------------------------

### Serialized Footprint Comparison

Source: https://intbitset.readthedocs.io/en/latest/index.html

Compares the size of serialized sparse and dense integer collections. `intbitset.fastdump()` produces significantly smaller serialized data compared to compressing the `set` representation.

```python
len(compress(dumps(sparse_set1)))
len(sparse_intbitset1.fastdump()) ## almost half the space
len(compress(dumps(dense_set1)))
len(dense_intbitset1.fastdump()) ## 5% of the space for dense set
```

--------------------------------

### __lt__ (Less Than)

Source: https://intbitset.readthedocs.io/en/latest/index.html

Compares if one intbitset is strictly less than another.

```APIDOC
## __lt__(self, y)

### Description
Compares if intbitset `x` is strictly less than `y`.

### Syntax
x.__lt__(y) <==> x<y
```

--------------------------------

### Serialization Speed Comparison

Source: https://intbitset.readthedocs.io/en/latest/index.html

Measures the time taken to serialize and deserialize sparse and dense integer collections using `marshal` and `zlib` compression versus `intbitset`'s `fastdump()` method. `intbitset.fastdump()` is notably faster.

```python
## serialization speed
## note: internally intbitset compress using zlib so we are
## going to also compress the equivalent set
from zlib import compress, decompress
from marshal import dumps, loads
%timeit loads(decompress(compress(dumps(sparse_set1))))
%timeit intbitset(sparse_intbitset1.fastdump()) ## 15% faster
%timeit loads(decompress(compress(dumps(dense_set1))))
%timeit intbitset(dense_intbitset1.fastdump()) ## almost 30 times faster for dense sets
```

--------------------------------

### __ior__ (In-place Union)

Source: https://intbitset.readthedocs.io/en/latest/index.html

Updates the intbitset with the union of itself and another set.

```APIDOC
## __ior__(self, other)

### Description
Updates a intbitset with the union of itself and another.

### Syntax
x.__ior__(y) <==> x|=y
```

--------------------------------

### fastdump

Source: https://intbitset.readthedocs.io/en/latest/index.html

Generates a compressed string representation of the intbitset, suitable for saving.

```APIDOC
## fastdump()

### Description
Return a compressed string representation suitable to be saved somewhere.

### Method
N/A (Method call)

### Endpoint
N/A (Method call)
```

--------------------------------

### __ixor__ (In-place Symmetric Difference)

Source: https://intbitset.readthedocs.io/en/latest/index.html

Updates the intbitset with the symmetric difference of itself and another set.

```APIDOC
## __ixor__(self, other)

### Description
Updates an intbitset with the symmetric difference of itself and another.

### Syntax
x.__ixor__(y) <==> x^=y
```

--------------------------------

### update

Source: https://intbitset.readthedocs.io/en/latest/index.html

Updates the intbitset by adding elements from all other specified intbitsets.

```APIDOC
## update()

### Description
Update the intbitset, adding elements from all others.

### Method
N/A (Method call)

### Endpoint
N/A (Method call)
```

--------------------------------

### union

Source: https://intbitset.readthedocs.io/en/latest/index.html

Returns a new intbitset containing elements from this intbitset and others.

```APIDOC
## union()

### Description
Return a new intbitset with elements from the intbitset and all others.

### Method
N/A (Method call)

### Endpoint
N/A (Method call)
```

--------------------------------

### __ge__ (Greater Than or Equal)

Source: https://intbitset.readthedocs.io/en/latest/index.html

Compares if one intbitset is greater than or equal to another.

```APIDOC
## __ge__(self, y)

### Description
Compares if intbitset `x` is greater than or equal to `y`.

### Syntax
x.__ge__(y) <==> x>=y
```

--------------------------------

### clear

Source: https://intbitset.readthedocs.io/en/latest/index.html

Removes all elements from the intbitset, making it empty.

```APIDOC
## clear(self)

### Description
Removes all elements from the intbitset.
```

--------------------------------

### __ne__ (Not Equal)

Source: https://intbitset.readthedocs.io/en/latest/index.html

Compares two intbitsets for inequality.

```APIDOC
## __ne__(self, y)

### Description
Compares intbitset `x` with `y` for inequality.

### Syntax
x.__ne__(y) <==> x!=y
```

--------------------------------

### Dense Set Operations Performance

Source: https://intbitset.readthedocs.io/en/latest/index.html

Compares the performance of bitwise AND, OR, XOR, and subtraction operations between `set` and `intbitset` for dense integer collections. `intbitset` shows a dramatic speed improvement, often thousands of times faster.

```python
## Dense sets operations
%timeit dense_set1 & dense_set2
%timeit dense_intbitset1 & dense_intbitset2 ## more than 5000 times faster
%timeit dense_set1 | dense_set2
%timeit dense_intbitset1 | dense_intbitset2 ## more than 6000 times faster
%timeit dense_set1 ^ dense_set2
%timeit dense_intbitset1 ^ dense_intbitset2 ## more than 5000 times faster
%timeit dense_set1 - dense_set2
timeit dense_intbitset1 - dense_intbitset2 ## more than 3000 times faster
```

--------------------------------

### update_with_signs

Source: https://intbitset.readthedocs.io/en/latest/index.html

Updates the intbitset based on a dictionary of integers, adding non-negative values and removing negative values.

```APIDOC
## update_with_signs()

### Description
Given a dictionary rhs whose keys are integers, remove all the integers whose value are less than 0 and add every integer whose value is 0 or more

### Method
N/A (Method call)

### Endpoint
N/A (Method call)
```

--------------------------------

### get_size

Source: https://intbitset.readthedocs.io/en/latest/index.html

Returns the number of elements currently stored in the intbitset.

```APIDOC
## get_size()

### Description
Returns the number of elements currently stored in the intbitset.

### Method
N/A (Method call)

### Endpoint
N/A (Method call)
```

--------------------------------

### __or__ (Union)

Source: https://intbitset.readthedocs.io/en/latest/index.html

Returns the union of two intbitsets as a new set, containing elements from either set.

```APIDOC
## __or__(self, other)

### Description
Return the union of two intbitsets as a new set. (i.e. all elements that are in either intbitsets.)

### Syntax
x.__or__(y) <==> x|y
```

--------------------------------

### __gt__ (Greater Than)

Source: https://intbitset.readthedocs.io/en/latest/index.html

Compares if one intbitset is strictly greater than another.

```APIDOC
## __gt__(self, y)

### Description
Compares if intbitset `x` is strictly greater than `y`.

### Syntax
x.__gt__(y) <==> x>y
```

--------------------------------

### __setitem__ (Set Item)

Source: https://intbitset.readthedocs.io/en/latest/index.html

Assigns a value to an element in the intbitset by its index or key.

```APIDOC
## __setitem__(self, i, y)

### Description
Assigns value `y` to the element at index/key `i` in the intbitset `x`.

### Syntax
x.__setitem__(i, y) <==> x[i]=y
```

--------------------------------

### difference

Source: https://intbitset.readthedocs.io/en/latest/index.html

Returns a new intbitset containing elements that are in the current set but not in the specified other sets.

```APIDOC
## difference(self, *others)

### Description
Return a new intbitset with elements from the intbitset that are not in the others.

### Parameters
- **others**: One or more intbitsets to compare against.
```

--------------------------------

### get_wordbitsize

Source: https://intbitset.readthedocs.io/en/latest/index.html

Returns the size of a word in bits used by the intbitset.

```APIDOC
## get_wordbitsize()

### Description
Returns the size of a word in bits used by the intbitset.

### Method
N/A (Method call)

### Endpoint
N/A (Method call)
```

--------------------------------

### __xor__ (Symmetric Difference)

Source: https://intbitset.readthedocs.io/en/latest/index.html

Returns the symmetric difference between two intbitsets as a new set, containing elements present in exactly one of the sets.

```APIDOC
## __xor__(self, other)

### Description
Return the symmetric difference of two sets as a new set. (i.e. all elements that are in exactly one of the sets.)

### Syntax
x.__xor__(y) <==> x^y
```

--------------------------------

### strbits

Source: https://intbitset.readthedocs.io/en/latest/index.html

Returns a string of 0s and 1s representing the internal memory content of the intbitset.

```APIDOC
## strbits()

### Description
Return a string of 0s and 1s representing the content in memory of the intbitset.

### Method
N/A (Method call)

### Endpoint
N/A (Method call)
```

--------------------------------

### get_allocated

Source: https://intbitset.readthedocs.io/en/latest/index.html

Retrieves information about the allocated memory for the intbitset.

```APIDOC
## get_allocated()

### Description
Returns information about the allocated memory for the intbitset.

### Method
N/A (Method call)

### Endpoint
N/A (Method call)
```

--------------------------------

### __delitem__ (Delete Item)

Source: https://intbitset.readthedocs.io/en/latest/index.html

Removes an element from the intbitset.

```APIDOC
## __delitem__(self, y)

### Description
Removes element `y` from the intbitset `x`.

### Syntax
x.__delitem__(y) <==> del x[y]
```

--------------------------------

### __iand__ (In-place Intersection)

Source: https://intbitset.readthedocs.io/en/latest/index.html

Updates the intbitset with the intersection of itself and another set.

```APIDOC
## __iand__(self, other)

### Description
Updates a intbitset with the intersection of itself and another.

### Syntax
x.__iand__(y) <==> x&=y
```

--------------------------------

### remove

Source: https://intbitset.readthedocs.io/en/latest/index.html

Removes an element from the intbitset. Raises KeyError if the element is not present.

```APIDOC
## remove()

### Description
Remove an element from a set; it must be a member. If the element is not a member, raise a KeyError.

### Method
N/A (Method call)

### Endpoint
N/A (Method call)
```

--------------------------------

### __sub__ (Difference)

Source: https://intbitset.readthedocs.io/en/latest/index.html

Returns the difference between two intbitsets as a new set, containing elements present in the first set but not in the second.

```APIDOC
## __sub__(self, other)

### Description
Return the difference of two intbitsets as a new set. (i.e. all elements that are in this intbitset but not the other.)

### Syntax
x.__sub__(y) <==> x-y
```

--------------------------------

### is_infinite

Source: https://intbitset.readthedocs.io/en/latest/index.html

Checks if the intbitset is infinite (i.e., was constructed with trailing_bits=True).

```APIDOC
## is_infinite()

### Description
Return True if the intbitset is infinite. (i.e. trailing_bits=True was used in the constructor.)

### Method
N/A (Method call)

### Endpoint
N/A (Method call)
```

--------------------------------

### __rxor__ (Reverse Symmetric Difference)

Source: https://intbitset.readthedocs.io/en/latest/index.html

Performs a symmetric difference operation where the intbitset is the right operand.

```APIDOC
## __rxor__(self, y)

### Description
Performs a symmetric difference operation between `y` and `x`.

### Syntax
x.__rxor__(y) <==> y^x
```

--------------------------------

### __ror__ (Reverse Or)

Source: https://intbitset.readthedocs.io/en/latest/index.html

Performs a bitwise OR operation with another integer or set, returning the result.

```APIDOC
## __ror__(self, y)

### Description
Performs a bitwise OR operation between `y` and `x`.

### Syntax
x.__ror__(y) <==> y|x
```

--------------------------------

### __and__ (Intersection)

Source: https://intbitset.readthedocs.io/en/latest/index.html

Returns the intersection of two intbitsets as a new set, containing elements present in both sets.

```APIDOC
## __and__(self, other)

### Description
Return the intersection of two intbitsets as a new set. (i.e. all elements that are in both intbitsets.)

### Method
`__and__`
```

--------------------------------

### get_wordbytsize

Source: https://intbitset.readthedocs.io/en/latest/index.html

Returns the size of a word in bytes used by the intbitset.

```APIDOC
## get_wordbytsize()

### Description
Returns the size of a word in bytes used by the intbitset.

### Method
N/A (Method call)

### Endpoint
N/A (Method call)
```

--------------------------------

### __rsub__ (Reverse Subtract)

Source: https://intbitset.readthedocs.io/en/latest/index.html

Performs a subtraction operation where the intbitset is the right operand.

```APIDOC
## __rsub__(self, y)

### Description
Performs a subtraction operation where `y` is the left operand and `x` is the right operand.

### Syntax
x.__rsub__(y) <==> y-x
```

--------------------------------

### extract_finite_list

Source: https://intbitset.readthedocs.io/en/latest/index.html

Returns a finite list of elements sufficient to reconstruct the intbitset, considering elements up to a certain integer value.

```APIDOC
## extract_finite_list()

### Description
Return a finite list of elements sufficient to be passed to intbitset constructor toghether with the proper value of trailing_bits in order to reproduce this intbitset. At least up_to integer are looked for when they are inside the intbitset but not necessarily needed to build the intbitset

### Method
N/A (Method call)

### Endpoint
N/A (Method call)
```

--------------------------------

### __rand__ (Reverse And)

Source: https://intbitset.readthedocs.io/en/latest/index.html

Performs a bitwise AND operation with another integer or set, returning the result.

```APIDOC
## __rand__(self, y)

### Description
Performs a bitwise AND operation between `y` and `x`.

### Syntax
x.__rand__(y) <==> y&x
```

--------------------------------

### __isub__ (In-place Subtract)

Source: https://intbitset.readthedocs.io/en/latest/index.html

Removes elements from the intbitset that are also present in another set.

```APIDOC
## __isub__(self, other)

### Description
Removes all elements of another set from this set in-place.

### Syntax
x.__isub__(y) <==> x-=y
```

--------------------------------

### pop

Source: https://intbitset.readthedocs.io/en/latest/index.html

Removes and returns the largest element from the intbitset.

```APIDOC
## pop()

### Description
Remove and return an arbitrary set element.
Note: intbitset implementation of .pop() differs from the native `set` implementation by guaranteeing returning always the largest element.

### Method
N/A (Method call)

### Endpoint
N/A (Method call)
```

--------------------------------

### discard

Source: https://intbitset.readthedocs.io/en/latest/index.html

Removes an element from the intbitset if it is present. If the element is not found, this method does nothing.

```APIDOC
## discard(self, element)

### Description
Remove an element from a intbitset if it is a member. If the element is not a member, do nothing.

### Parameters
- **element**: The element to remove from the set.
```

--------------------------------

### __contains__ (Membership)

Source: https://intbitset.readthedocs.io/en/latest/index.html

Checks if an element is present in the intbitset.

```APIDOC
## __contains__(self, y)

### Description
Checks if element `y` is present in the intbitset `x`.

### Syntax
x.__contains__(y) <==> y in x
```

--------------------------------

### issubset

Source: https://intbitset.readthedocs.io/en/latest/index.html

Checks if this intbitset is a subset of another set.

```APIDOC
## issubset()

### Description
Report whether another set contains this set.

### Method
N/A (Method call)

### Endpoint
N/A (Method call)
```

--------------------------------

### union_update

Source: https://intbitset.readthedocs.io/en/latest/index.html

Updates the intbitset by adding elements from all other specified intbitsets.

```APIDOC
## union_update()

### Description
Update the intbitset, adding elements from all others.

### Method
N/A (Method call)

### Endpoint
N/A (Method call)
```

--------------------------------

### difference_update

Source: https://intbitset.readthedocs.io/en/latest/index.html

Updates the current intbitset by removing elements found in the specified other sets.

```APIDOC
## difference_update(self, *others)

### Description
Update the intbitset, removing elements found in others.

### Parameters
- **others**: One or more intbitsets whose elements will be removed from this set.
```

--------------------------------

### intersection

Source: https://intbitset.readthedocs.io/en/latest/index.html

Returns a new intbitset containing elements common to this intbitset and others.

```APIDOC
## intersection()

### Description
Return a new intbitset with elements common to the intbitset and all others.

### Method
N/A (Method call)

### Endpoint
N/A (Method call)
```

--------------------------------

### issuperset

Source: https://intbitset.readthedocs.io/en/latest/index.html

Checks if this intbitset is a superset of another set.

```APIDOC
## issuperset()

### Description
Report whether this set contains another set.

### Method
N/A (Method call)

### Endpoint
N/A (Method call)
```

--------------------------------

### symmetric_difference_update

Source: https://intbitset.readthedocs.io/en/latest/index.html

Updates the intbitset with the symmetric difference between itself and another intbitset.

```APIDOC
## symmetric_difference_update()

### Description
Update an intbitset with the symmetric difference of itself and another.

### Method
N/A (Method call)

### Endpoint
N/A (Method call)
```

--------------------------------

### isdisjoint

Source: https://intbitset.readthedocs.io/en/latest/index.html

Determines if two intbitsets have no elements in common.

```APIDOC
## isdisjoint()

### Description
Return True if two intbitsets have a null intersection.

### Method
N/A (Method call)

### Endpoint
N/A (Method call)
```

--------------------------------

### symmetric_difference

Source: https://intbitset.readthedocs.io/en/latest/index.html

Returns a new intbitset with elements that are in exactly one of the two sets.

```APIDOC
## symmetric_difference

### Description
Return the symmetric difference of two sets as a new set. (i.e. all elements that are in exactly one of the sets.)

### Method
N/A (Attribute/Property access)

### Endpoint
N/A (Attribute/Property access)
```

--------------------------------

### intersection_update

Source: https://intbitset.readthedocs.io/en/latest/index.html

Updates the intbitset to keep only elements present in itself and all other specified intbitsets.

```APIDOC
## intersection_update()

### Description
Update the intbitset, keeping only elements found in it and all others.

### Method
N/A (Method call)

### Endpoint
N/A (Method call)
```
Tokens:
Raw