Struct BooleanBuffer

Source

pub struct BooleanBuffer { /* private fields */ }

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

Implementations§

Source §

impl BooleanBuffer

Source

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

Source

pub fn new_set(length: usize) -> BooleanBuffer

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

Source

pub fn new_unset(length: usize) -> BooleanBuffer

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

Source

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

Source

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 may have non zero offset and/or padding bits outside the logical range.

§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);
// output is 12 bits long starting from bit offset 4
assert_eq!(result.len(), 12);
assert_eq!(result.offset(), 4);
// the expected 12 bits are 0b101110101100 (bits 4..16 of the input)
let expected_bits = [false, false, true, true, false, true, false, true, true, true, false, true];
for (i, v) in expected_bits.into_iter().enumerate() {
   assert_eq!(result.value(i), v);
}
// However, underlying buffer has (ignored) bits set outside the requested range
assert_eq!(result.values(), &[0b11001100u8, 0b10111010, 0, 0, 0, 0, 0, 0]);

Source

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.
op may be called with input bits outside the requested range
Returned BooleanBuffer may have non zero offset
Returned BooleanBuffer may have bits set outside the requested range

§See Also

BooleanBuffer::from_bitwise_binary_op to create a new buffer from a binary operation
apply_bitwise_unary_op for in-place unary bitwise operations

§Example: Create new `BooleanBuffer` from bitwise `NOT`

let input = [0b11001100u8, 0b10111010u8]; // 2 bytes = 16 bits
// NOT of bits 4..16
let result = BooleanBuffer::from_bitwise_unary_op(
 &input, 4, 12, |a| !a
);
// output is 12 bits long starting from bit offset 4
assert_eq!(result.len(), 12);
assert_eq!(result.offset(), 4);
// the expected 12 bits are 0b001100110101, (NOT of the requested bits)
let expected_bits = [true, true, false, false, true, false, true, false, false, false, true, false];
for (i, v) in expected_bits.into_iter().enumerate() {
    assert_eq!(result.value(i), v);
}
// However, underlying buffer has (ignored) bits set outside the requested range
let expected = [0b00110011u8, 0b01000101u8, 255, 255, 255, 255, 255, 255];
assert_eq!(result.values(), &expected);

Source

pub fn from_bitwise_binary_op<F>( left: impl AsRef<[u8]>, left_offset_in_bits: usize, right: impl AsRef<[u8]>, right_offset_in_bits: usize, len_in_bits: usize, op: F, ) -> BooleanBuffer
where F: FnMut(u64, u64) -> u64,

Create a new BooleanBuffer by applying the bitwise operation op to the relevant bits from two input buffers.

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 two u64 inputs and produces one u64 output.
op must only apply bitwise operations on the relevant bits; the input u64 values 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 returned BooleanBuffer always has zero offset.

§See Also

BooleanBuffer::from_bitwise_unary_op for unary operations on a single input buffer.
apply_bitwise_binary_op for in-place binary bitwise operations

§Example: Create new `BooleanBuffer` from bitwise `AND` of two `Buffer`s

let left = Buffer::from(vec![0b11001100u8, 0b10111010u8]); // 2 bytes = 16 bits
let right = Buffer::from(vec![0b10101010u8, 0b11011100u8, 0b11110000u8]); // 3 bytes = 24 bits
// AND of the first 12 bits
let result = BooleanBuffer::from_bitwise_binary_op(
  &left, 0, &right, 0, 12, |a, b| a & b
);
assert_eq!(result.inner().as_slice(), &[0b10001000u8, 0b00001000u8]);

§Example: Create new `BooleanBuffer` from bitwise `OR` of two byte slices

let left = [0b11001100u8, 0b10111010u8];
let right = [0b10101010u8, 0b11011100u8];
// OR of bits 4..16 from left and bits 0..12 from right
let result = BooleanBuffer::from_bitwise_binary_op(
 &left, 4, &right, 0, 12, |a, b| a | b
);
assert_eq!(result.inner().as_slice(), &[0b10101110u8, 0b00001111u8]);

Source

pub fn count_set_bits(&self) -> usize

Returns the number of set bits in this buffer

Source

pub fn find_nth_set_bit_position(&self, start: usize, n: usize) -> usize

Finds the position of the n-th set bit (1-based) starting from start index. If fewer than n set bits are found, returns the length of the 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) -> BooleanBuffer

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: &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

Source