Struct polars::export::arrow::bitmap::MutableBitmap

pub struct MutableBitmap { /* private fields */ }

Expand description

A container of booleans. MutableBitmap is semantically equivalent to Vec<bool>.

The two main differences against Vec<bool> is that each element stored as a single bit, thereby:

it uses 8x less memory
it cannot be represented as &[bool] (i.e. no pointer arithmetics).

A MutableBitmap can be converted to a Bitmap at O(1).

Examples

use arrow2::bitmap::MutableBitmap;

let bitmap = MutableBitmap::from([true, false, true]);
assert_eq!(bitmap.iter().collect::<Vec<_>>(), vec![true, false, true]);

// creation directly from bytes
let mut bitmap = MutableBitmap::try_new(vec![0b00001101], 5).unwrap();
// note: the first bit is the left-most of the first byte
assert_eq!(bitmap.iter().collect::<Vec<_>>(), vec![true, false, true, true, false]);
// we can also get the slice:
assert_eq!(bitmap.as_slice(), [0b00001101u8].as_ref());
// debug helps :)
assert_eq!(format!("{:?}", bitmap), "[0b___01101]".to_string());

// It supports mutation in place
bitmap.set(0, false);
assert_eq!(format!("{:?}", bitmap), "[0b___01100]".to_string());
// and `O(1)` random access
assert_eq!(bitmap.get(0), false);

Implementation

This container is internally a Vec<u8>.

Implementations§

§

impl MutableBitmap

pub fn new() -> MutableBitmap

Initializes an empty MutableBitmap.

pub fn try_new( bytes: Vec<u8, Global>, length: usize ) -> Result<MutableBitmap, Error>

Initializes a new MutableBitmap from a Vec<u8> and a length.

Errors

This function errors iff length > bytes.len() * 8

pub fn from_vec(buffer: Vec<u8, Global>, length: usize) -> MutableBitmap

Initializes a MutableBitmap from a Vec<u8> and a length. This function is O(1).

Panic

Panics iff the length is larger than the length of the buffer times 8.

pub fn with_capacity(capacity: usize) -> MutableBitmap

Initializes a pre-allocated MutableBitmap with capacity for capacity bits.

pub fn push(&mut self, value: bool)

Pushes a new bit to the MutableBitmap, re-sizing it if necessary.

pub fn pop(&mut self) -> Option<bool>

Pop the last bit from the MutableBitmap. Note if the MutableBitmap is empty, this method will return None.

pub fn get(&self, index: usize) -> bool

Returns whether the position index is set.

Panics

Panics iff index >= self.len().

pub fn set(&mut self, index: usize, value: bool)

Sets the position index to value

Panics

Panics iff index >= self.len().

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

constructs a new iterator over the bits of MutableBitmap.

pub fn clear(&mut self)

Empties the MutableBitmap.

pub fn extend_constant(&mut self, additional: usize, value: bool)

Extends MutableBitmap by additional values of constant value.

Implementation

This function is an order of magnitude faster than pushing element by element.

pub fn from_len_zeroed(length: usize) -> MutableBitmap

Initializes a zeroed MutableBitmap.

pub fn from_len_set(length: usize) -> MutableBitmap

Initializes a MutableBitmap with all values set to valid/ true.

pub fn reserve(&mut self, additional: usize)

Reserves additional bits in the MutableBitmap, potentially re-allocating its buffer.

pub fn capacity(&self) -> usize

Returns the capacity of MutableBitmap in number of bits.

pub unsafe fn push_unchecked(&mut self, value: bool)

Pushes a new bit to the MutableBitmap

Safety

The caller must ensure that the MutableBitmap has sufficient capacity.

pub fn unset_bits(&self) -> usize

Returns the number of unset bits on this MutableBitmap.

Guaranted to be <= self.len().

Implementation

This function is O(N)

pub fn null_count(&self) -> usize

👎Deprecated since 0.13.0: use unset_bits instead

Returns the number of unset bits on this MutableBitmap.

pub fn len(&self) -> usize

Returns the length of the MutableBitmap.

pub fn is_empty(&self) -> bool

Returns whether MutableBitmap is empty.

pub unsafe fn set_unchecked(&mut self, index: usize, value: bool)

Sets the position index to value

Safety

Caller must ensure that index < self.len()

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of the MutableBitmap to fit its current length.

§

impl MutableBitmap

pub fn extend_from_trusted_len_iter(&mut self, iterator: I)where I: TrustedLen<Item = bool>,

Extends self from a TrustedLen iterator.

pub unsafe fn extend_from_trusted_len_iter_unchecked(&mut self, iterator: I)where I: Iterator<Item = bool>,

Extends self from an iterator of trusted len.

Safety

The caller must guarantee that the iterator has a trusted len.

pub unsafe fn from_trusted_len_iter_unchecked(iterator: I) -> MutableBitmapwhere I: Iterator<Item = bool>,

Creates a new MutableBitmap from an iterator of booleans.

Safety

The iterator must report an accurate length.

pub fn from_trusted_len_iter(iterator: I) -> MutableBitmapwhere I: TrustedLen<Item = bool>,

Creates a new MutableBitmap from an iterator of booleans.

pub fn try_from_trusted_len_iter<E, I>(iterator: I) -> Result<MutableBitmap, E>where I: TrustedLen<Item = Result<bool, E>>,

Creates a new MutableBitmap from an iterator of booleans.

pub unsafe fn try_from_trusted_len_iter_unchecked<E, I>( iterator: I ) -> Result<MutableBitmap, E>where I: Iterator<Item = Result<bool, E>>,

Creates a new MutableBitmap from an falible iterator of booleans.

Safety

The caller must guarantee that the iterator is TrustedLen.

pub fn extend_from_slice(&mut self, slice: &[u8], offset: usize, length: usize)

Extends the MutableBitmap from a slice of bytes with optional offset. This is the fastest way to extend a MutableBitmap.

Implementation

When both MutableBitmap’s length and offset are both multiples of 8, this function performs a memcopy. Else, it first aligns bit by bit and then performs a memcopy.