Struct croaring::bitmap::Bitmap

pub struct Bitmap { /* private fields */ }

Implementations

impl Bitmap

pub fn create() -> Self

Creates a new bitmap (initially empty)

Examples

use croaring::Bitmap;

let bitmap = Bitmap::create();

assert!(bitmap.is_empty());

pub fn create_with_capacity(capacity: u32) -> Self

Creates a new bitmap (initially empty) with a provided container-storage capacity (it is a performance hint).

Examples

use croaring::Bitmap;

let bitmap = Bitmap::create_with_capacity(100_000);

assert!(bitmap.is_empty());

pub fn add_many(&mut self, elements: &[u32])

Add the integer element to the bitmap

Examples

use croaring::Bitmap;

let mut bitmap = Bitmap::create();
bitmap.add_many(&[1, 2, 3]);

assert!(!bitmap.is_empty());
assert!(bitmap.contains(1));
assert!(bitmap.contains(2));
assert!(bitmap.contains(3));

pub fn add(&mut self, element: u32)

Add the integer element to the bitmap

Examples

use croaring::Bitmap;

let mut bitmap = Bitmap::create();
assert!(bitmap.is_empty());
bitmap.add(1);
assert!(!bitmap.is_empty());

pub fn add_checked(&mut self, element: u32) -> bool

Add the integer element to the bitmap. Returns true if the value was added, false if the value was already in the bitmap.

Examples

use croaring::Bitmap;

let mut bitmap = Bitmap::create();
assert!(bitmap.add_checked(1));
assert!(!bitmap.add_checked(1));

pub fn add_range<R: RangeBounds<u32>>(&mut self, range: R)

Add all values in range

Examples

use croaring::Bitmap;

let mut bitmap1 = Bitmap::create();
bitmap1.add_range((1..3));

assert!(!bitmap1.is_empty());
assert!(bitmap1.contains(1));
assert!(bitmap1.contains(2));
assert!(!bitmap1.contains(3));

let mut bitmap2 = Bitmap::create();
bitmap2.add_range((3..1));
assert!(bitmap2.is_empty());

let mut bitmap3 = Bitmap::create();
bitmap3.add_range((3..3));
assert!(bitmap3.is_empty());

let mut bitmap4 = Bitmap::create();
bitmap4.add_range(..=2);
bitmap4.add_range(u32::MAX..=u32::MAX);
assert!(bitmap4.contains(0));
assert!(bitmap4.contains(1));
assert!(bitmap4.contains(2));
assert!(bitmap4.contains(u32::MAX));
assert_eq!(bitmap4.cardinality(), 4);

pub fn remove_range<R: RangeBounds<u32>>(&mut self, range: R)

Remove all values in range

Examples

use croaring::Bitmap;

let mut bitmap = Bitmap::create();
bitmap.add_range((1..4));
assert!(!bitmap.is_empty());

bitmap.remove_range((1..3));

assert!(!bitmap.contains(1));
assert!(!bitmap.contains(2));
assert!(bitmap.contains(3));

bitmap.add_range(u32::MAX..=u32::MAX);
assert!(bitmap.contains(u32::MAX));

pub fn contains_range<R: RangeBounds<u32>>(&self, range: R) -> bool

Check whether a range of values of range are present

Examples

use croaring::Bitmap;

let bitmap = Bitmap::of(&[1, 2]);
assert!(bitmap.contains_range((1..3)));

let mut bitmap = bitmap.clone();
bitmap.add(u32::MAX - 1);
bitmap.add(u32::MAX);
assert!(bitmap.contains_range((u32::MAX - 1)..=u32::MAX))

pub fn clear(&mut self)

Empties the bitmap

Examples

use croaring::Bitmap;

let mut bitmap = Bitmap::create();
bitmap.add(1);
bitmap.add(2);
bitmap.clear();

assert!(bitmap.is_empty());

pub fn remove(&mut self, element: u32)

Clear the integer element from the bitmap

Examples

use croaring::Bitmap;

let mut bitmap = Bitmap::create();
bitmap.add(1);
bitmap.remove(1);

assert!(bitmap.is_empty());

pub fn remove_checked(&mut self, element: u32) -> bool

Remove the integer element from the bitmap. Returns true if a the value was removed, false if the value was present in the bitmap.

Examples

use croaring::Bitmap;

let mut bitmap = Bitmap::create();
bitmap.add(1);
assert!(bitmap.remove_checked(1));
assert!(!bitmap.remove_checked(1));

pub fn contains(&self, element: u32) -> bool

Contains returns true if the integer element is contained in the bitmap

Examples

use croaring::Bitmap;

let bitmap = Bitmap::of(&[1]);

assert!(bitmap.contains(1));
assert!(!bitmap.contains(2));

pub fn add_offset(&self, offset: i64) -> Self

Compute a new bitmap, which contains all values from this bitmap, but shifted by offset

Any values which would be < 0, or > u32::MAX are dropped.

Examples

use croaring::Bitmap;

let bitmap1 = Bitmap::of(&[0, 1, 1000, u32::MAX]);
let shifted_down = bitmap1.add_offset(-1);
assert_eq!(shifted_down.to_vec(), [0, 999, u32::MAX - 1]);
let shifted_up = bitmap1.add_offset(1);
assert_eq!(shifted_up.to_vec(), [1, 2, 1001]);
let big_shifted = bitmap1.add_offset(i64::from(u32::MAX) + 1);
assert_eq!(big_shifted.to_vec(), []);

pub fn range_cardinality<R: RangeBounds<u32>>(&self, range: R) -> u64

Returns number of elements in range

Examples

use croaring::Bitmap;

let bitmap = Bitmap::of(&[1, 3, 4]);

assert_eq!(bitmap.range_cardinality((..1)), 0);
assert_eq!(bitmap.range_cardinality((..2)), 1);
assert_eq!(bitmap.range_cardinality((2..5)), 2);
assert_eq!(bitmap.range_cardinality((..5)), 3);
assert_eq!(bitmap.range_cardinality((1..=4)), 3);

pub fn cardinality(&self) -> u64

Returns the number of integers contained in the bitmap

Examples

use croaring::Bitmap;

let bitmap = Bitmap::of(&[1]);

assert_eq!(bitmap.cardinality(), 1);

let mut bitmap = bitmap.clone();

bitmap.add(2);

assert_eq!(bitmap.cardinality(), 2);

pub fn and(&self, other: &Self) -> Self

And computes the intersection between two bitmaps and returns the result as a new bitmap

Examples

use croaring::Bitmap;

let bitmap1 = Bitmap::of(&[1]);
let bitmap2 = Bitmap::of(&[1, 2]);

let bitmap3 = bitmap1.and(&bitmap2);

assert!(bitmap3.contains(1));
assert!(!bitmap3.contains(2));

pub fn and_inplace(&mut self, other: &Self)

Computes the intersection between two bitmaps and stores the result in the current bitmap

Examples

use croaring::Bitmap;

let mut bitmap1 = Bitmap::of(&[15]);
let bitmap2 = Bitmap::of(&[25]);
let mut bitmap3 = Bitmap::of(&[15]);
let bitmap4 = Bitmap::of(&[15, 25]);

bitmap1.and_inplace(&bitmap2);

assert_eq!(bitmap1.cardinality(), 0);
assert!(!bitmap1.contains(15));
assert!(!bitmap1.contains(25));

bitmap3.and_inplace(&bitmap4);

assert_eq!(bitmap3.cardinality(), 1);
assert!(bitmap3.contains(15));
assert!(!bitmap3.contains(25));

pub fn or(&self, other: &Self) -> Self

Or computes the union between two bitmaps and returns the result as a new bitmap

Examples

use croaring::Bitmap;

let bitmap1 = Bitmap::of(&[15]);
let bitmap2 = Bitmap::of(&[25]);

let bitmap3 = bitmap1.or(&bitmap2);

assert_eq!(bitmap3.cardinality(), 2);
assert!(bitmap3.contains(15));
assert!(bitmap3.contains(25));

pub fn or_inplace(&mut self, other: &Self)

Computes the union between two bitmaps and stores the result in the current bitmap.

Examples

use croaring::Bitmap;

let mut bitmap1 = Bitmap::of(&[15]);
let bitmap2 = Bitmap::of(&[25]);

bitmap1.or_inplace(&bitmap2);

assert_eq!(bitmap1.cardinality(), 2);
assert!(bitmap1.contains(15));
assert!(bitmap1.contains(25));

pub fn fast_or(bitmaps: &[&Bitmap]) -> Self

Computes the union between many bitmaps quickly, as opposed to having to call or() repeatedly. Returns the result as a new bitmap.

Examples

use croaring::Bitmap;

let bitmap1 = Bitmap::of(&[15]);
let bitmap2 = Bitmap::of(&[25]);
let bitmap3 = Bitmap::of(&[35]);

let bitmap4 = Bitmap::fast_or(&[&bitmap1, &bitmap2, &bitmap3]);

assert_eq!(bitmap4.cardinality(), 3);
assert!(bitmap4.contains(15));
assert!(bitmap4.contains(25));
assert!(bitmap4.contains(25));

pub fn fast_or_heap(bitmaps: &[&Bitmap]) -> Self

Compute the union of ‘number’ bitmaps using a heap. This can sometimes be faster than Bitmap::fast_or.

Examples

use croaring::Bitmap;

let bitmap1 = Bitmap::of(&[15]);
let bitmap2 = Bitmap::of(&[25]);
let bitmap3 = Bitmap::of(&[35]);

let bitmap4 = Bitmap::fast_or_heap(&[&bitmap1, &bitmap2, &bitmap3]);

assert_eq!(bitmap4.cardinality(), 3);
assert!(bitmap4.contains(15));
assert!(bitmap4.contains(25));
assert!(bitmap4.contains(25));

pub fn xor(&self, other: &Self) -> Self

Computes the symmetric difference (xor) between two bitmaps and returns new bitmap.

Examples

use croaring::Bitmap;

let bitmap1 = Bitmap::of(&[15, 25]);
let bitmap2 = Bitmap::of(&[25, 35]);

let bitmap3 = bitmap1.xor(&bitmap2);

assert_eq!(bitmap3.cardinality(), 2);
assert!(bitmap3.contains(15));
assert!(!bitmap3.contains(25));
assert!(bitmap3.contains(35));

pub fn xor_inplace(&mut self, other: &Self)

Inplace version of roaring_bitmap_xor, stores result in current bitmap.

Examples

use croaring::Bitmap;

let mut bitmap1 = Bitmap::of(&[15, 25]);
let bitmap2 = Bitmap::of(&[25, 35]);

bitmap1.xor_inplace(&bitmap2);

assert_eq!(bitmap1.cardinality(), 2);
assert!(bitmap1.contains(15));
assert!(!bitmap1.contains(25));
assert!(bitmap1.contains(35));

pub fn fast_xor(bitmaps: &[&Bitmap]) -> Self

Computes the symmetric difference (xor) between multiple bitmaps and returns new bitmap as a result.

Examples

use croaring::Bitmap;

let bitmap1 = Bitmap::of(&[15, 25]);
let bitmap2 = Bitmap::of(&[25, 35]);

let bitmap3 = Bitmap::fast_xor(&[&bitmap1, &bitmap2]);

assert_eq!(bitmap3.cardinality(), 2);
assert!(bitmap3.contains(15));
assert!(!bitmap3.contains(25));
assert!(bitmap3.contains(35));

pub fn andnot(&self, other: &Self) -> Self

Computes the difference between two bitmaps and returns the result.

Examples

use croaring::Bitmap;

let bitmap1 = Bitmap::of(&[15, 25]);
let bitmap2 = Bitmap::of(&[25, 35]);

let bitmap3 = bitmap1.andnot(&bitmap2);

assert_eq!(bitmap3.cardinality(), 1);
assert!(bitmap3.contains(15));
assert!(!bitmap3.contains(25));
assert!(!bitmap3.contains(35));

pub fn andnot_inplace(&mut self, other: &Self)

Computes the difference between two bitmaps and stores the result in the current bitmap.

Examples

use croaring::Bitmap;

let mut bitmap1 = Bitmap::of(&[15, 25]);
let bitmap2 = Bitmap::of(&[25, 35]);

bitmap1.andnot_inplace(&bitmap2);

assert_eq!(bitmap1.cardinality(), 1);
assert!(bitmap1.contains(15));
assert!(!bitmap1.contains(25));
assert!(!bitmap1.contains(35));

let mut bitmap3 = Bitmap::of(&[15]);
let bitmap4 = Bitmap::create();
bitmap3.andnot_inplace(&bitmap4);
assert_eq!(bitmap3.cardinality(), 1);
assert!(bitmap3.contains(15));

pub fn flip<R: RangeBounds<u32>>(&self, range: R) -> Self

Negates the bits in the given range any integer present in this range and in the bitmap is removed. Returns result as a new bitmap.

Examples

use croaring::Bitmap;

let bitmap1 = Bitmap::of(&[4]);

let bitmap2 = bitmap1.flip(1..3);

assert_eq!(bitmap2.cardinality(), 3);
assert!(bitmap2.contains(1));
assert!(bitmap2.contains(2));
assert!(!bitmap2.contains(3));
assert!(bitmap2.contains(4));

let bitmap3 = bitmap1.flip(1..=5);
assert_eq!(bitmap3.to_vec(), [1, 2, 3, 5])

pub fn flip_inplace<R: RangeBounds<u32>>(&mut self, range: R)

Negates the bits in the given range any integer present in this range and in the bitmap is removed. Stores the result in the current bitmap.

Examples

use croaring::Bitmap;

let mut bitmap1 = Bitmap::of(&[4]);
bitmap1.flip_inplace(1..3);

assert_eq!(bitmap1.cardinality(), 3);
assert!(bitmap1.contains(1));
assert!(bitmap1.contains(2));
assert!(!bitmap1.contains(3));
assert!(bitmap1.contains(4));
bitmap1.flip_inplace(4..=4);
assert_eq!(bitmap1.to_vec(), [1, 2]);

pub fn to_vec(&self) -> Vec<u32>

Returns a vector containing all of the integers stored in the Bitmap in sorted order.

use croaring::Bitmap;

let bitmap = Bitmap::of(&[15, 25]);

assert_eq!(bitmap.to_vec(), [15, 25]);

pub fn get_serialized_size_in_bytes(&self) -> usize

Computes the serialized size in bytes of the Bitmap.

pub fn serialize(&self) -> Vec<u8>

Serializes a bitmap to a slice of bytes.

Examples

use croaring::Bitmap;

let original_bitmap: Bitmap = (1..5).collect();

let serialized_buffer = original_bitmap.serialize();

let deserialized_bitmap = Bitmap::deserialize(&serialized_buffer);

assert_eq!(original_bitmap, deserialized_bitmap);

pub fn try_deserialize(buffer: &[u8]) -> Option<Self>

Given a serialized bitmap as slice of bytes returns a bitmap instance. See example of #serialize function.

On invalid input returns None.

Examples

use croaring::Bitmap;

let original_bitmap: Bitmap = (1..5).collect();
let serialized_buffer = original_bitmap.serialize();

let deserialized_bitmap = Bitmap::try_deserialize(&serialized_buffer);
assert_eq!(original_bitmap, deserialized_bitmap.unwrap());

let invalid_buffer: Vec<u8> = vec![3];
let deserialized_bitmap = Bitmap::try_deserialize(&invalid_buffer);
assert!(deserialized_bitmap.is_none());

pub fn deserialize(buffer: &[u8]) -> Self

Given a serialized bitmap as slice of bytes returns a bitmap instance. See example of #serialize function.

On invalid input returns empty bitmap.

pub fn of(elements: &[u32]) -> Self

Creates a new bitmap from a slice of u32 integers

Examples

use croaring::Bitmap;

let elements = vec![1, 2];

let bitmap = Bitmap::of(&elements);

let mut bitmap2 = Bitmap::create();

for element in &elements {
    bitmap2.add(*element);
}

assert!(bitmap.contains(1));
assert!(bitmap.contains(2));
assert!(!bitmap.contains(3));
assert_eq!(bitmap, bitmap2);

pub fn from_range<R: RangeBounds<u32>>(range: R) -> Self

Create a new bitmap with all values in range

Examples

use std::ops::Bound;
use croaring::Bitmap;

let bitmap1 = Bitmap::from_range(5..10);
assert_eq!(bitmap1.to_vec(), [5, 6, 7, 8, 9]);

let bitmap2 = Bitmap::from_range(5..=7);
assert_eq!(bitmap2.to_vec(), [5, 6, 7]);

let bitmap3 = Bitmap::from_range((Bound::Excluded(2), Bound::Excluded(6)));
assert_eq!(bitmap3.to_vec(), [3, 4, 5]);

pub fn from_range_with_step<R: RangeBounds<u32>>(range: R, step: u32) -> Self

Create a new bitmap with all values in range which are a multiple of step away from the lower bound

If step is zero or there are no values which are a multiple of step away from the lower bound within range, an empty bitmap is returned.

Examples

use std::ops::Bound;
use croaring::Bitmap;

let bitmap = Bitmap::from_range_with_step(0..10, 3);
assert_eq!(bitmap.to_vec(), [0, 3, 6, 9]);

// empty ranges
assert_eq!(Bitmap::from_range_with_step(0..0, 1), Bitmap::create());
assert_eq!(Bitmap::from_range_with_step(100..=0, 1), Bitmap::create());

// Step of zero
assert_eq!(Bitmap::from_range_with_step(0..100, 0), Bitmap::create());

// No values of step in range
let bitmap = Bitmap::from_range_with_step((Bound::Excluded(0), Bound::Included(10)), 100);
assert_eq!(bitmap, Bitmap::create());
let bitmap = Bitmap::from_range_with_step((Bound::Excluded(u32::MAX), Bound::Included(u32::MAX)), 1);
assert_eq!(bitmap, Bitmap::create());

// Exclusive ranges still step from the start, but do not include it
let bitmap = Bitmap::from_range_with_step((Bound::Excluded(10), Bound::Included(30)), 10);
assert_eq!(bitmap.to_vec(), [20, 30]);

pub fn shrink_to_fit(&mut self) -> usize

Shrink the memory allocation of the bitmap if needed

Returns the number of bytes saved

Examples

use croaring::Bitmap;

let mut bitmap = Bitmap::create_with_capacity(10);
let saved_bytes = bitmap.shrink_to_fit();
assert!(saved_bytes > 0);
let more_saved_bytes = bitmap.shrink_to_fit();
assert_eq!(more_saved_bytes, 0);

pub fn run_optimize(&mut self) -> bool

Compresses of the bitmap. Returns true if the bitmap was modified.

Examples

use croaring::Bitmap;

let mut bitmap: Bitmap = (100..1000).collect();

assert_eq!(bitmap.cardinality(), 900);
let old_size = bitmap.get_serialized_size_in_bytes();
assert!(bitmap.run_optimize());
let new_size = bitmap.get_serialized_size_in_bytes();
assert!(new_size < old_size);

pub fn remove_run_compression(&mut self) -> bool

Removes run-length encoding even when it is more space efficient. Returns true if a change was applied.

Examples

use croaring::Bitmap;

let mut bitmap: Bitmap = (100..1000).collect();

assert_eq!(bitmap.cardinality(), 900);

bitmap.run_optimize();

assert!(bitmap.remove_run_compression());
assert!(!bitmap.remove_run_compression());

pub fn is_empty(&self) -> bool

Returns true if the Bitmap is empty. Faster than doing: bitmap.cardinality() == 0)

Examples

use croaring::Bitmap;

let mut bitmap = Bitmap::create();

assert!(bitmap.is_empty());

bitmap.add(1);

assert!(!bitmap.is_empty());

pub fn is_subset(&self, other: &Self) -> bool

Return true if all the elements of Self are in &other.

Examples

use croaring::Bitmap;

let bitmap1: Bitmap = (5..10).collect();
let bitmap2: Bitmap = (5..8).collect();
let bitmap3: Bitmap = (5..10).collect();
let bitmap4: Bitmap = (9..11).collect();

assert!(bitmap2.is_subset(&bitmap1));
assert!(bitmap3.is_subset(&bitmap1));
assert!(!bitmap4.is_subset(&bitmap1));

pub fn is_strict_subset(&self, other: &Self) -> bool

Return true if all the elements of Self are in &other and &other is strictly greater than Self.

Examples

use croaring::Bitmap;

let bitmap1: Bitmap = (5..9).collect();
let bitmap2: Bitmap = (5..8).collect();
let bitmap3: Bitmap = (5..10).collect();
let bitmap4: Bitmap = (9..11).collect();

assert!(bitmap2.is_subset(&bitmap1));
assert!(!bitmap3.is_subset(&bitmap1));
assert!(!bitmap4.is_subset(&bitmap1));

pub fn intersect(&self, other: &Self) -> bool

Return true if Self and &other intersect

Examples

use croaring::Bitmap;

let bitmap1: Bitmap = (1..5).collect();
let bitmap2: Bitmap = (5..9).collect();
let bitmap3: Bitmap = (3..7).collect();

assert_eq!(bitmap1.intersect(&bitmap2), false);
assert_eq!(bitmap1.intersect(&bitmap3), true);
assert_eq!(bitmap2.intersect(&bitmap3), true);

pub fn intersect_with_range<R: RangeBounds<u32>>(&self, range: R) -> bool

Check if a bitmap has any values set in range

Examples

use croaring::Bitmap;

let bitmap = Bitmap::of(&[1, 100, 101, u32::MAX]);

assert!(bitmap.intersect_with_range(0..10));
assert!(!bitmap.intersect_with_range(2..100));
assert!(bitmap.intersect_with_range(999..=u32::MAX));

// Empty ranges
assert!(!bitmap.intersect_with_range(100..100));
assert!(!bitmap.intersect_with_range(100..0));

pub fn jaccard_index(&self, other: &Self) -> f64

Return the Jaccard index between Self and &other

use croaring::Bitmap;

let bitmap1: Bitmap = (1..5).collect();
let bitmap2: Bitmap = (5..9).collect();
let bitmap3: Bitmap = (3..9).collect();

assert_eq!(bitmap1.jaccard_index(&bitmap2), 0.0);
assert_eq!(bitmap1.jaccard_index(&bitmap3), 0.25);
assert_eq!(bitmap2.jaccard_index(&bitmap3), 0.6666666666666666);

pub fn and_cardinality(&self, other: &Self) -> u64

Return the size of the intersection between Self and &other

Examples

use croaring::Bitmap;

let bitmap1 = Bitmap::of(&[1]);
let bitmap2 = Bitmap::of(&[1, 2]);

assert_eq!(bitmap1.and_cardinality(&bitmap2), 1);

pub fn or_cardinality(&self, other: &Self) -> u64

Return the size of the union between Self and &other

Examples

use croaring::Bitmap;

let bitmap1 = Bitmap::of(&[15]);
let bitmap2 = Bitmap::of(&[25]);

assert_eq!(bitmap1.or_cardinality(&bitmap2), 2);

pub fn andnot_cardinality(&self, other: &Self) -> u64

Return the size of the difference between Self and &other

Examples

use croaring::Bitmap;

let bitmap1 = Bitmap::of(&[15, 25]);
let bitmap2 = Bitmap::of(&[25, 35]);

assert_eq!(bitmap1.andnot_cardinality(&bitmap2), 1);

pub fn xor_cardinality(&self, other: &Self) -> u64

Return the size of the symmetric difference between Self and &other

Examples

use croaring::Bitmap;

let bitmap1 = Bitmap::of(&[15, 25]);
let bitmap2 = Bitmap::of(&[25, 35]);

assert_eq!(bitmap1.xor_cardinality(&bitmap2), 2);

pub fn minimum(&self) -> Option<u32>

Returns the smallest value in the set.

Returns None if the set is empty.

Examples

use croaring::Bitmap;

let mut bitmap: Bitmap = (5..10).collect();
let empty_bitmap: Bitmap = Bitmap::create();

assert_eq!(bitmap.minimum(), Some(5));
assert_eq!(empty_bitmap.minimum(), None);

bitmap.add(3);

assert_eq!(bitmap.minimum(), Some(3));

pub fn maximum(&self) -> Option<u32>

Returns the greatest value in the set.

Returns None if the set is empty.

Examples

use croaring::Bitmap;

let mut bitmap: Bitmap = (5..10).collect();
let empty_bitmap: Bitmap = Bitmap::create();

assert_eq!(bitmap.maximum(), Some(9));
assert_eq!(empty_bitmap.maximum(), None);

bitmap.add(15);

assert_eq!(bitmap.maximum(), Some(15));

pub fn rank(&self, x: u32) -> u64

Rank returns the number of values smaller or equal to x.

Examples

use croaring::Bitmap;

let mut bitmap: Bitmap = (5..10).collect();

assert_eq!(bitmap.rank(8), 4);

bitmap.add(15);

assert_eq!(bitmap.rank(11), 5);
assert_eq!(bitmap.rank(15), 6);

pub fn select(&self, rank: u32) -> Option<u32>

Select returns the element having the designated rank, if it exists If the size of the roaring bitmap is strictly greater than rank, then this function returns element of given rank wrapped in Some. Otherwise, it returns None.

Examples

use croaring::Bitmap;

let bitmap: Bitmap = (5..10).collect();

assert_eq!(bitmap.select(0), Some(5));
assert_eq!(bitmap.select(1), Some(6));
assert_eq!(bitmap.select(2), Some(7));
assert_eq!(bitmap.select(3), Some(8));
assert_eq!(bitmap.select(4), Some(9));
assert_eq!(bitmap.select(5), None);

pub fn statistics(&self) -> Statistics

Returns statistics about the composition of a roaring bitmap.

Examples

use croaring::Bitmap;

let mut bitmap: Bitmap = (1..100).collect();
let statistics = bitmap.statistics();

assert_eq!(statistics.n_containers, 1);
assert_eq!(statistics.n_array_containers, 1);
assert_eq!(statistics.n_run_containers, 0);
assert_eq!(statistics.n_bitset_containers, 0);
assert_eq!(statistics.n_values_array_containers, 99);
assert_eq!(statistics.n_values_run_containers, 0);
assert_eq!(statistics.n_values_bitset_containers, 0);
assert_eq!(statistics.n_bytes_array_containers, 198);
assert_eq!(statistics.n_bytes_run_containers, 0);
assert_eq!(statistics.n_bytes_bitset_containers, 0);
assert_eq!(statistics.max_value, 99);
assert_eq!(statistics.min_value, 1);
assert_eq!(statistics.sum_value, 4950);
assert_eq!(statistics.cardinality, 99);

bitmap.run_optimize();
let statistics = bitmap.statistics();

assert_eq!(statistics.n_containers, 1);
assert_eq!(statistics.n_array_containers, 0);
assert_eq!(statistics.n_run_containers, 1);
assert_eq!(statistics.n_bitset_containers, 0);
assert_eq!(statistics.n_values_array_containers, 0);
assert_eq!(statistics.n_values_run_containers, 99);
assert_eq!(statistics.n_values_bitset_containers, 0);
assert_eq!(statistics.n_bytes_array_containers, 0);
assert_eq!(statistics.n_bytes_run_containers, 6);
assert_eq!(statistics.n_bytes_bitset_containers, 0);
assert_eq!(statistics.max_value, 99);
assert_eq!(statistics.min_value, 1);
assert_eq!(statistics.sum_value, 4950);
assert_eq!(statistics.cardinality, 99);

impl Bitmap

pub fn iter(&self) -> BitmapIterator<'_>

Returns an iterator over each value stored in the bitmap. Returned values are ordered in ascending order.

Examples

use croaring::Bitmap;

let mut bitmap = Bitmap::create();
bitmap.add(4);
bitmap.add(3);
bitmap.add(2);
let mut iterator = bitmap.iter();

assert_eq!(iterator.next(), Some(2));
assert_eq!(iterator.next(), Some(3));
assert_eq!(iterator.next(), Some(4));
assert_eq!(iterator.next(), None);

impl Bitmap

pub fn lazy_batch<F, O>(&mut self, f: F) -> Owhere
    F: FnOnce(&mut LazyBitmap<'_>) -> O,

Perform multiple bitwise operations on a bitmap.

The passed closure will be passed a handle which can be used to perform bitwise operations on the bitmap lazily.

The result will be equivalent to doing the same operations on this bitmap directly, but because of reduced bookkeeping in between operations, it should be faster

Examples

use croaring::Bitmap;

// Perform a series of bitwise operations on a bitmap:
let mut bitmap = Bitmap::of(&[99]);
let bitmaps_to_or = [Bitmap::of(&[1, 2, 5, 10]), Bitmap::of(&[1, 30, 100])];
let bitmaps_to_xor = [Bitmap::of(&[5]), Bitmap::of(&[1, 1000, 1001])];

bitmap.lazy_batch(|lazy| {
    for b in &bitmaps_to_or {
        *lazy |= b;
    }
    for b in &bitmaps_to_xor {
        *lazy ^= b;
    }
});
let mut bitmap2 = Bitmap::of(&[99]);
for b in &bitmaps_to_or {
    bitmap2 |= b;
}
for b in &bitmaps_to_xor {
    bitmap2 ^= b;
}
assert_eq!(bitmap, bitmap2);
assert_eq!(bitmap.to_vec(), [2, 10, 30, 99, 100, 1000, 1001]);

The result the passed closure is returned from lazy_batch

use croaring::Bitmap;

let mut bitmap = Bitmap::create();
let bitmaps_to_or = [Bitmap::of(&[1, 2, 5, 10]), Bitmap::of(&[1, 30, 100])];
let total_added = bitmap.lazy_batch(|lazy| {
    let mut total = 0;
    for b in &bitmaps_to_or {
        lazy.or_inplace(b, true);
        total += b.cardinality();
    }
    total
});
assert_eq!(total_added, 7);

Trait Implementations

impl<'a, 'b> BitAnd<&'a Bitmap> for &'b Bitmap

fn bitand(self, other: &'a Bitmap) -> Bitmap

Syntactic sugar for .and

Examples

use croaring::Bitmap;

let bitmap1 = Bitmap::of(&[1]);
let bitmap2 = Bitmap::of(&[1, 2]);

let bitmap3 = &bitmap1 & &bitmap2;

assert!(bitmap3.contains(1));
assert!(!bitmap3.contains(2));

type Output = Bitmap

The resulting type after applying the & operator.

impl<'a> BitAnd<&'a Bitmap> for Bitmap

fn bitand(self, other: &'a Bitmap) -> Bitmap

Syntactic sugar for .and

Examples

use croaring::Bitmap;

let bitmap1 = Bitmap::of(&[1]);
let bitmap2 = Bitmap::of(&[1, 2]);

let bitmap3 = bitmap1 & &bitmap2;

assert!(bitmap3.contains(1));
assert!(!bitmap3.contains(2));

type Output = Bitmap

The resulting type after applying the & operator.

impl BitAnd<Bitmap> for Bitmap

fn bitand(self, other: Bitmap) -> Bitmap

Syntactic sugar for .and

Examples

use croaring::Bitmap;

let mut bitmap1 = Bitmap::create();
bitmap1.add(1);

let mut bitmap2 = Bitmap::create();
bitmap2.add(1);
bitmap2.add(2);

let bitmap3 = bitmap1 & bitmap2;

assert!(bitmap3.contains(1));
assert!(!bitmap3.contains(2));

type Output = Bitmap

The resulting type after applying the & operator.

impl BitAndAssign<&Bitmap> for Bitmap

fn bitand_assign(&mut self, other: &Bitmap)

Syntactic sugar for .and_inplace

Examples

use croaring::Bitmap;

let mut bitmap1 = Bitmap::of(&[15]);
let bitmap2 = Bitmap::of(&[25]);
let mut bitmap3 = Bitmap::of(&[15]);
let bitmap4 = Bitmap::of(&[15, 25]);

bitmap1 &= &bitmap2;

assert!(bitmap1.cardinality() == 0);
assert!(!bitmap1.contains(15));
assert!(!bitmap1.contains(25));

bitmap3 &= &bitmap4;

assert!(bitmap3.cardinality() == 1);
assert!(bitmap3.contains(15));
assert!(!bitmap3.contains(25));

impl BitAndAssign<Bitmap> for Bitmap

fn bitand_assign(&mut self, other: Bitmap)

Syntactic sugar for .and_inplace

Examples

use croaring::Bitmap;

let mut bitmap1 = Bitmap::of(&[15]);
let bitmap2 = Bitmap::of(&[25]);
let mut bitmap3 = Bitmap::of(&[15]);
let bitmap4 = Bitmap::of(&[15, 25]);

bitmap1 &= bitmap2;

assert!(bitmap1.cardinality() == 0);
assert!(!bitmap1.contains(15));
assert!(!bitmap1.contains(25));

bitmap3 &= bitmap4;

assert!(bitmap3.cardinality() == 1);
assert!(bitmap3.contains(15));
assert!(!bitmap3.contains(25));

impl<'a, 'b> BitOr<&'a Bitmap> for &'b Bitmap

fn bitor(self, other: &'a Bitmap) -> Bitmap

Syntatic sugar for .or

Examples

use croaring::Bitmap;

let mut bitmap1 = Bitmap::create();
bitmap1.add(15);

let mut bitmap2 = Bitmap::create();
bitmap2.add(25);

let bitmap3 = &bitmap1 | &bitmap2;

assert!(bitmap3.cardinality() == 2);
assert!(bitmap3.contains(15));
assert!(bitmap3.contains(25));

type Output = Bitmap

The resulting type after applying the | operator.

impl<'a> BitOr<&'a Bitmap> for Bitmap

fn bitor(self, other: &'a Bitmap) -> Bitmap

Syntatic sugar for .or

Examples

use croaring::Bitmap;

let bitmap1 = Bitmap::of(&[15]);
let bitmap2 = Bitmap::of(&[25]);

let bitmap3 = bitmap1 | &bitmap2;

assert!(bitmap3.cardinality() == 2);
assert!(bitmap3.contains(15));
assert!(bitmap3.contains(25));

type Output = Bitmap

The resulting type after applying the | operator.

impl BitOr<Bitmap> for Bitmap

fn bitor(self, other: Bitmap) -> Bitmap

Syntatic sugar for .or

Examples

use croaring::Bitmap;

let bitmap1 = Bitmap::of(&[15]);
let bitmap2 = Bitmap::of(&[25]);

let bitmap3 = bitmap1 | bitmap2;

assert!(bitmap3.cardinality() == 2);
assert!(bitmap3.contains(15));
assert!(bitmap3.contains(25));

type Output = Bitmap

The resulting type after applying the | operator.

impl BitOrAssign<&Bitmap> for Bitmap

fn bitor_assign(&mut self, other: &Bitmap)

Syntatic sugar for .or_inplace

Examples

use croaring::Bitmap;

let mut bitmap1 = Bitmap::of(&[15]);
let bitmap2 = Bitmap::of(&[25]);

bitmap1 |= &bitmap2;

assert!(bitmap1.cardinality() == 2);
assert!(bitmap1.contains(15));
assert!(bitmap1.contains(25));

impl<'a> BitOrAssign<&Bitmap> for LazyBitmap<'a>

fn bitor_assign(&mut self, other: &Bitmap)

Performs the |= operation.

impl BitOrAssign<Bitmap> for Bitmap

fn bitor_assign(&mut self, other: Bitmap)

Syntatic sugar for .or_inplace

Examples

use croaring::Bitmap;

let mut bitmap1 = Bitmap::of(&[15]);
let bitmap2 = Bitmap::of(&[25]);

bitmap1 |= bitmap2;

assert!(bitmap1.cardinality() == 2);
assert!(bitmap1.contains(15));
assert!(bitmap1.contains(25));

impl<'a, 'b> BitXor<&'a Bitmap> for &'b Bitmap

fn bitxor(self, other: &'a Bitmap) -> Bitmap

Syntatic sugar for .xor

Examples

use croaring::Bitmap;

let bitmap1 = Bitmap::of(&[15, 25]);
let bitmap2 = Bitmap::of(&[25, 35]);

let bitmap3 = &bitmap1 ^ &bitmap2;

assert!(bitmap3.cardinality() == 2);
assert!(bitmap3.contains(15));
assert!(!bitmap3.contains(25));
assert!(bitmap3.contains(35));

type Output = Bitmap

The resulting type after applying the ^ operator.

impl<'a> BitXor<&'a Bitmap> for Bitmap

fn bitxor(self, other: &'a Bitmap) -> Bitmap

Syntatic sugar for .xor

Examples

use croaring::Bitmap;

let bitmap1 = Bitmap::of(&[15, 25]);
let bitmap2 = Bitmap::of(&[25, 35]);

let bitmap3 = bitmap1 ^ &bitmap2;

assert!(bitmap3.cardinality() == 2);
assert!(bitmap3.contains(15));
assert!(!bitmap3.contains(25));
assert!(bitmap3.contains(35));

type Output = Bitmap

The resulting type after applying the ^ operator.

impl BitXor<Bitmap> for Bitmap

fn bitxor(self, other: Bitmap) -> Bitmap

Syntatic sugar for .xor

Examples

use croaring::Bitmap;

let bitmap1 = Bitmap::of(&[15, 25]);
let bitmap2 = Bitmap::of(&[25, 35]);

let bitmap3 = bitmap1 ^ bitmap2;

assert!(bitmap3.cardinality() == 2);
assert!(bitmap3.contains(15));
assert!(!bitmap3.contains(25));
assert!(bitmap3.contains(35));

type Output = Bitmap

The resulting type after applying the ^ operator.

impl BitXorAssign<&Bitmap> for Bitmap

fn bitxor_assign(&mut self, other: &Bitmap)

Syntatic sugar for .xor_inplace

Examples

use croaring::Bitmap;

let mut bitmap1 = Bitmap::of(&[15, 25]);
let bitmap2 = Bitmap::of(&[25, 35]);

bitmap1 ^= &bitmap2;

assert!(bitmap1.cardinality() == 2);
assert!(bitmap1.contains(15));
assert!(!bitmap1.contains(25));
assert!(bitmap1.contains(35));

impl<'a> BitXorAssign<&Bitmap> for LazyBitmap<'a>

fn bitxor_assign(&mut self, other: &Bitmap)

Performs the ^= operation.

impl BitXorAssign<Bitmap> for Bitmap

fn bitxor_assign(&mut self, other: Bitmap)

Syntatic sugar for .xor_inplace

Examples

use croaring::Bitmap;

let mut bitmap1 = Bitmap::of(&[15, 25]);
let bitmap2 = Bitmap::of(&[25, 35]);

bitmap1 ^= bitmap2;

assert!(bitmap1.cardinality() == 2);
assert!(bitmap1.contains(15));
assert!(!bitmap1.contains(25));
assert!(bitmap1.contains(35));

impl Clone for Bitmap

fn clone(&self) -> Self

Create a copy of a Bitmap

Examples

use croaring::Bitmap;

let mut bitmap1 = Bitmap::create();
bitmap1.add(11);

let bitmap2 = bitmap1.clone();

assert_eq!(bitmap1, bitmap2);

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Bitmap

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Bitmap

fn default() -> Self

Returns the “default value” for a type.

impl Drop for Bitmap

fn drop(&mut self)

Executes the destructor for this type.

impl Extend<u32> for Bitmap

fn extend<T: IntoIterator<Item = u32>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl FromIterator<u32> for Bitmap

fn from_iter<I: IntoIterator<Item = u32>>(iter: I) -> Self

Convenience method for creating bitmap from iterator.

Examples

use croaring::Bitmap;

let bitmap: Bitmap = (1..3).collect();

assert!(!bitmap.is_empty());
assert!(bitmap.contains(1));
assert!(bitmap.contains(2));
assert_eq!(bitmap.cardinality(), 2);

impl PartialEq<Bitmap> for Bitmap

fn eq(&self, other: &Bitmap) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, 'b> Sub<&'a Bitmap> for &'b Bitmap

fn sub(self, other: &'a Bitmap) -> Bitmap

Syntatic sugar for .andnot

Examples

use croaring::Bitmap;

let bitmap1 = Bitmap::of(&[15, 25]);
let bitmap2 = Bitmap::of(&[25, 35]);

let bitmap3 = &bitmap1 - &bitmap2;

assert_eq!(bitmap3.cardinality(), 1);
assert!(bitmap3.contains(15));
assert!(!bitmap3.contains(25));
assert!(!bitmap3.contains(35));

type Output = Bitmap

The resulting type after applying the - operator.

impl<'a> Sub<&'a Bitmap> for Bitmap

fn sub(self, other: &'a Bitmap) -> Bitmap

Syntatic sugar for .andnot

Examples

use croaring::Bitmap;

let bitmap1 = Bitmap::of(&[15, 25]);
let bitmap2 = Bitmap::of(&[25, 35]);

let bitmap3 = bitmap1 - &bitmap2;

assert_eq!(bitmap3.cardinality(), 1);
assert!(bitmap3.contains(15));
assert!(!bitmap3.contains(25));
assert!(!bitmap3.contains(35));

type Output = Bitmap

The resulting type after applying the - operator.

impl Sub<Bitmap> for Bitmap

fn sub(self, other: Bitmap) -> Bitmap

Syntatic sugar for .andnot

Examples

use croaring::Bitmap;

let bitmap1 = Bitmap::of(&[15, 25]);
let bitmap2 = Bitmap::of(&[25, 35]);

let bitmap3 = bitmap1 - bitmap2;

assert_eq!(bitmap3.cardinality(), 1);
assert!(bitmap3.contains(15));
assert!(!bitmap3.contains(25));
assert!(!bitmap3.contains(35));

type Output = Bitmap

The resulting type after applying the - operator.

impl SubAssign<&Bitmap> for Bitmap

fn sub_assign(&mut self, other: &Bitmap)

Syntatic sugar for .andnot_inplace

Examples

use croaring::Bitmap;

let mut bitmap1 = Bitmap::of(&[15, 25]);
let bitmap2 = Bitmap::of(&[25, 35]);

bitmap1 -= &bitmap2;

assert_eq!(bitmap1.cardinality(), 1);
assert!(bitmap1.contains(15));
assert!(!bitmap1.contains(25));
assert!(!bitmap1.contains(35));

impl SubAssign<Bitmap> for Bitmap

fn sub_assign(&mut self, other: Bitmap)

Syntatic sugar for .andnot_inplace

Examples

use croaring::Bitmap;

let mut bitmap1 = Bitmap::of(&[15, 25]);
let bitmap2 = Bitmap::of(&[25, 35]);

bitmap1 -= bitmap2;

assert_eq!(bitmap1.cardinality(), 1);
assert!(bitmap1.contains(15));
assert!(!bitmap1.contains(25));
assert!(!bitmap1.contains(35));

impl Send for Bitmap

impl Sync for Bitmap