Struct BooleanBuffer

Source

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

Underlying buffer (byte aligned)

§bit_offset: usize

Offset in bits (not bytes)

§bit_len: usize

Length in bits (not bytes)

Implementations§

Source §

impl BooleanBuffer

Source

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

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

Source

pub fn new_set(length: usize) -> Self

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

Source

pub fn new_unset(length: usize) -> Self

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

Source

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

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

Source

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

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]);

Source

pub fn from_bitwise_unary_op<F>( src: impl AsRef<[u8]>, offset_in_bits: usize, len_in_bits: usize, op: F, ) -> Self
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.
op may be called with input bits outside the requested range
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]);

Source

fn try_from_aligned_bitwise_unary_op<F>( src: &[u8], len_in_bits: usize, op: &mut F, ) -> Option<Self>
where F: FnMut(u64) -> u64,

Fast path for Self::from_bitwise_unary_op when input is aligned to 8-byte (64-bit) boundaries

Returns None if the fast path cannot be taken

Source

pub fn count_set_bits(&self) -> usize

Returns the number of set bits in this buffer

Source

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

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

Source

pub fn offset(&self) -> usize

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

Source

pub fn len(&self) -> usize

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

Source

pub fn is_empty(&self) -> bool

Returns true if this BooleanBuffer is empty

Source

pub fn shrink_to_fit(&mut self)

Free up unused memory.

Source

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

Returns the boolean value at index i.

§Panics

Panics if i >= self.len()

Source

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()

Source

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

Returns the packed values of this BooleanBuffer not including any offset

Source

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

Slices this BooleanBuffer by the provided offset and length

Source

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)

Source

pub fn ptr_eq(&self, other: &Self) -> 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

Source