Struct ZeroCopyBitSlice

pub struct ZeroCopyBitSlice<'a> { /* private fields */ }

A zero copy container that helps read from and write to the bits in a &[u8].

Implementations

impl<'a> ZeroCopyBitSlice<'a>

pub fn intialize_in<'o>( num_bits: u32, bytes: &'o mut &'a mut [u8], ) -> ZeroCopyBitSlice<'a>

Initializes a ZeroCopyBitSlice with num_bits bits within the buffer provided. Requires space for the bit length in addition to bytes for all bits.

We also update the position of the reference to just after the end of the bitslice.

Panics if buffer is not large enough.

Examples found in repository

examples/minter.rs (line 16)

fn main() {
    use zerocopy_bitslice::ZeroCopyBitSlice;
    const MOCK_OFFSET: usize = 100;
    const MOCK_END_BUFFER: usize = 100;
    const NUM_ITEMS: u32 = 100;

    // Calculate required space for the `ZeroCopyBitSlice`
    let required_space: usize = ZeroCopyBitSlice::required_space(NUM_ITEMS);

    // Initalize some buffer w/ bytes on either end of where the `ZeroCopyBitSlice` will live
    let mut mock_minter: Vec<u8> = vec![0; MOCK_OFFSET + required_space + MOCK_END_BUFFER];

    // Get reference to the bit bytes and build `ZeroCopyBitSlice`
    let mut zcbs_bytes: &mut [u8] = &mut mock_minter[MOCK_OFFSET..];
    let mut zcbs: ZeroCopyBitSlice = ZeroCopyBitSlice::intialize_in(NUM_ITEMS, &mut zcbs_bytes);

    // Build random sequence
    let mut sequence: [u32; NUM_ITEMS as usize] = std::array::from_fn(|_a_new_minter_appears| {
        // Mock seed ingredients
        let mock_time: i64 = 123456890;
        let mock_time_bytes: [u8; 8] = mock_time.to_le_bytes();
        let mock_time_seed: [u8; 32] = core::array::from_fn(|i| mock_time_bytes[i % 8]);
        let mock_slothash: [u8; 32] = core::array::from_fn(|i| i as u8);
        let mock_minter_pubkey: [u8; 32] = core::array::from_fn(|i| i as u8);

        // Build seed
        let seed: [u8; 32] =
            core::array::from_fn(|i| mock_time_seed[i] ^ mock_slothash[i] ^ mock_minter_pubkey[i]);

        // Get element in sequence
        zcbs.choose_random_zero(seed)
            .expect("we are minting exactly the right number of items")
    });

    // Show sequence and sorted sequence
    println!("random sequence is {sequence:?}");
    sequence.sort();
    println!("sorted sequence is {sequence:?}");
}

pub fn from_bytes(bytes: &'a mut [u8]) -> ZeroCopyBitSlice<'a>

Given a pointer to a &mut [u8] with a previously initialized `ZeropCopyBitSlice<’a>, perform zero copy deserialization on the byte array containing the bits.

pub fn from_bytes_update<'o>( bytes: &'o mut &'a mut [u8], ) -> ZeroCopyBitSlice<'a>

Given a pointer to a &mut [u8] with a previously initialized `ZeropCopyBitSlice<’a>, perform zero copy deserialization on the byte array containing the bits.

pub fn bit_len(&self) -> u32

The number of bits contained within this bit slice

pub fn byte_len(&self) -> usize

The number bytes used to store these bits

pub fn set(&mut self, idx: u32, value: bool)

Sets the value of the bit at position idx.

Panics if out of bounds.

pub fn get(&self, idx: u32) -> bool

Retrieves the value of the bit at position idx.

Panics if out of bounds.

pub fn choose_random_zero(&mut self, seed: impl AsRef<[u8]>) -> Option<u32>

Chooses a random zero bit from within the bitslice, setting the bit to 1 and returning the bit’s index.

Returns None if all bits are set to 1.

Examples found in repository

examples/minter.rs (line 32)

fn main() {
    use zerocopy_bitslice::ZeroCopyBitSlice;
    const MOCK_OFFSET: usize = 100;
    const MOCK_END_BUFFER: usize = 100;
    const NUM_ITEMS: u32 = 100;

    // Calculate required space for the `ZeroCopyBitSlice`
    let required_space: usize = ZeroCopyBitSlice::required_space(NUM_ITEMS);

    // Initalize some buffer w/ bytes on either end of where the `ZeroCopyBitSlice` will live
    let mut mock_minter: Vec<u8> = vec![0; MOCK_OFFSET + required_space + MOCK_END_BUFFER];

    // Get reference to the bit bytes and build `ZeroCopyBitSlice`
    let mut zcbs_bytes: &mut [u8] = &mut mock_minter[MOCK_OFFSET..];
    let mut zcbs: ZeroCopyBitSlice = ZeroCopyBitSlice::intialize_in(NUM_ITEMS, &mut zcbs_bytes);

    // Build random sequence
    let mut sequence: [u32; NUM_ITEMS as usize] = std::array::from_fn(|_a_new_minter_appears| {
        // Mock seed ingredients
        let mock_time: i64 = 123456890;
        let mock_time_bytes: [u8; 8] = mock_time.to_le_bytes();
        let mock_time_seed: [u8; 32] = core::array::from_fn(|i| mock_time_bytes[i % 8]);
        let mock_slothash: [u8; 32] = core::array::from_fn(|i| i as u8);
        let mock_minter_pubkey: [u8; 32] = core::array::from_fn(|i| i as u8);

        // Build seed
        let seed: [u8; 32] =
            core::array::from_fn(|i| mock_time_seed[i] ^ mock_slothash[i] ^ mock_minter_pubkey[i]);

        // Get element in sequence
        zcbs.choose_random_zero(seed)
            .expect("we are minting exactly the right number of items")
    });

    // Show sequence and sorted sequence
    println!("random sequence is {sequence:?}");
    sequence.sort();
    println!("sorted sequence is {sequence:?}");
}

pub fn num_zeros(&self) -> u32

Calculates the number of zero bits in the bitslice.

pub const fn required_space(num_bits: u32) -> usize

Calculates the requires number of bytes to initialize a ZeroCopyBitSlice, e.g. via initialize_in.

Examples found in repository

examples/minter.rs (line 9)

fn main() {
    use zerocopy_bitslice::ZeroCopyBitSlice;
    const MOCK_OFFSET: usize = 100;
    const MOCK_END_BUFFER: usize = 100;
    const NUM_ITEMS: u32 = 100;

    // Calculate required space for the `ZeroCopyBitSlice`
    let required_space: usize = ZeroCopyBitSlice::required_space(NUM_ITEMS);

    // Initalize some buffer w/ bytes on either end of where the `ZeroCopyBitSlice` will live
    let mut mock_minter: Vec<u8> = vec![0; MOCK_OFFSET + required_space + MOCK_END_BUFFER];

    // Get reference to the bit bytes and build `ZeroCopyBitSlice`
    let mut zcbs_bytes: &mut [u8] = &mut mock_minter[MOCK_OFFSET..];
    let mut zcbs: ZeroCopyBitSlice = ZeroCopyBitSlice::intialize_in(NUM_ITEMS, &mut zcbs_bytes);

    // Build random sequence
    let mut sequence: [u32; NUM_ITEMS as usize] = std::array::from_fn(|_a_new_minter_appears| {
        // Mock seed ingredients
        let mock_time: i64 = 123456890;
        let mock_time_bytes: [u8; 8] = mock_time.to_le_bytes();
        let mock_time_seed: [u8; 32] = core::array::from_fn(|i| mock_time_bytes[i % 8]);
        let mock_slothash: [u8; 32] = core::array::from_fn(|i| i as u8);
        let mock_minter_pubkey: [u8; 32] = core::array::from_fn(|i| i as u8);

        // Build seed
        let seed: [u8; 32] =
            core::array::from_fn(|i| mock_time_seed[i] ^ mock_slothash[i] ^ mock_minter_pubkey[i]);

        // Get element in sequence
        zcbs.choose_random_zero(seed)
            .expect("we are minting exactly the right number of items")
    });

    // Show sequence and sorted sequence
    println!("random sequence is {sequence:?}");
    sequence.sort();
    println!("sorted sequence is {sequence:?}");
}