Struct BooleanBuffer

pub struct BooleanBuffer {
    buffer: Buffer,
    bit_offset: usize,
    bit_len: usize,
}

Expand description

A slice-able Buffer containing bit-packed booleans

This structure represents a sequence of boolean values packed into a byte-aligned Buffer. Both the offset and length are represented in bits.

§Layout

The values are represented as little endian bit-packed values, where the least significant bit of each byte represents the first boolean value and then proceeding to the most significant bit.

For example, the 10 bit bitmask 0b0111001101 has length 10, and is represented using 2 bytes with offset 0 like this:

       ┌─────────────────────────────────┐    ┌─────────────────────────────────┐
       │┌───┬───┬───┬───┬───┬───┬───┬───┐│    │┌───┬───┬───┬───┬───┬───┬───┬───┐│
       ││ 1 │ 0 │ 1 │ 1 │ 0 │ 0 │ 1 │ 1 ││    ││ 1 │ 0 │ ? │ ? │ ? │ ? │ ? │ ? ││
       │└───┴───┴───┴───┴───┴───┴───┴───┘│    │└───┴───┴───┴───┴───┴───┴───┴───┘│
bit    └─────────────────────────────────┘    └─────────────────────────────────┘
offset  0             Byte 0             7    0              Byte 1            7

        length = 10 bits, offset = 0

The same bitmask with length 10 and offset 3 would be represented using 2 bytes like this:

      ┌─────────────────────────────────┐    ┌─────────────────────────────────┐
      │┌───┬───┬───┬───┬───┬───┬───┬───┐│    │┌───┬───┬───┬───┬───┬───┬───┬───┐│
      ││ ? │ ? │ ? │ 1 │ 0 │ 1 │ 1 │ 0 ││    ││ 0 │ 1 │ 1 │ 1 │ 0 │ ? │ ? │ ? ││
      │└───┴───┴───┴───┴───┴───┴───┴───┘│    │└───┴───┴───┴───┴───┴───┴───┴───┘│
bit   └─────────────────────────────────┘    └─────────────────────────────────┘
offset 0             Byte 0             7    0              Byte 1            7

       length = 10 bits, offset = 3

Note that the bits marked ? are not logically part of the mask and may contain either 0 or 1

§See Also

BooleanBufferBuilder for building BooleanBuffer instances
NullBuffer for representing null values in Arrow arrays

Fields§

§buffer: Buffer§bit_offset: usize§bit_len: usize

Implementations§

§

impl BooleanBuffer

pub fn new(buffer: Buffer, bit_offset: usize, bit_len: usize) -> BooleanBuffer

Create a new BooleanBuffer from a Buffer, bit_offset offset and bit_len length

§Panics

This method will panic if buffer is not large enough

pub fn new_set(length: usize) -> BooleanBuffer

Create a new BooleanBuffer of length bits (not bytes) where all values are true

pub fn new_unset(length: usize) -> BooleanBuffer

Create a new BooleanBuffer of length bits (not bytes) where all values are false

pub fn collect_bool<F>(len: usize, f: F) -> BooleanBuffer
where F: FnMut(usize) -> bool,

Invokes f with indexes 0..len collecting the boolean results into a new BooleanBuffer

pub fn from_bits( src: impl AsRef<[u8]>, offset_in_bits: usize, len_in_bits: usize, ) -> BooleanBuffer

Create a new BooleanBuffer by copying the relevant bits from an input buffer.

§Notes:

The new BooleanBuffer has zero offset, even if offset_in_bits is non-zero

§Example: Create a new `BooleanBuffer` copying a bit slice from in input slice

let input = [0b11001100u8, 0b10111010u8];
// // Copy bits 4..16 from input
let result = BooleanBuffer::from_bits(&input, 4, 12);
assert_eq!(result.values(), &[0b10101100u8, 0b00001011u8]);

pub fn from_bitwise_unary_op<F>( src: impl AsRef<[u8]>, offset_in_bits: usize, len_in_bits: usize, op: F, ) -> BooleanBuffer
where F: FnMut(u64) -> u64,

Create a new BooleanBuffer by applying the bitwise operation to op to an input buffer.

This function is faster than applying the operation bit by bit as it processes input buffers in chunks of 64 bits (8 bytes) at a time

§Notes:

op takes a single u64 inputs and produces one u64 output.
op must only apply bitwise operations on the relevant bits; the input u64 may contain irrelevant bits and may be processed differently on different endian architectures.
The output always has zero offset

§See Also

apply_bitwise_unary_op for in-place unary bitwise operations

§Example: Create new `BooleanBuffer` from bitwise `NOT` of an input `Buffer`

let input = [0b11001100u8, 0b10111010u8]; // 2 bytes = 16 bits
// NOT of the first 12 bits
let result = BooleanBuffer::from_bitwise_unary_op(
 &input, 0, 12, |a| !a
);
assert_eq!(result.values(), &[0b00110011u8, 0b11110101u8]);

pub fn count_set_bits(&self) -> usize

Returns the number of set bits in this buffer

pub fn bit_chunks(&self) -> BitChunks<'_>

Returns a BitChunks instance which can be used to iterate over this buffer’s bits in u64 chunks

pub fn offset(&self) -> usize

Returns the offset of this BooleanBuffer in bits (not bytes)

pub fn len(&self) -> usize

Returns the length of this BooleanBuffer in bits (not bytes)

pub fn is_empty(&self) -> bool

Returns true if this BooleanBuffer is empty

pub fn shrink_to_fit(&mut self)

Free up unused memory.

pub fn value(&self, idx: usize) -> bool

Returns the boolean value at index i.

§Panics

Panics if i >= self.len()

pub unsafe fn value_unchecked(&self, i: usize) -> bool

Returns the boolean value at index i.

§Safety

This doesn’t check bounds, the caller must ensure that index < self.len()

pub fn values(&self) -> &[u8] ⓘ

Returns the packed values of this BooleanBuffer not including any offset

pub fn slice(&self, offset: usize, len: usize) -> BooleanBuffer

Slices this BooleanBuffer by the provided offset and length

pub fn sliced(&self) -> Buffer

Returns a Buffer containing the sliced contents of this BooleanBuffer

Equivalent to self.buffer.bit_slice(self.offset, self.len)

pub fn ptr_eq(&self, other: &BooleanBuffer) -> bool

Returns true if this BooleanBuffer is equal to other, using pointer comparisons to determine buffer equality. This is cheaper than PartialEq::eq but may return false when the arrays are logically equal