Trait BitStorage

Source

pub unsafe trait BitStorage: Sized {
    const BITS_IN_STORAGE: usize = _;

    // Required methods
    fn empty() -> Self;
    fn is_empty(&self) -> bool;
    unsafe fn get_bit(&self, index: usize) -> bool;
    unsafe fn set_bit(&mut self, index: usize) -> bool;
    unsafe fn clear_bit(&mut self, index: usize) -> bool;
    fn count_ones(&self) -> usize;
    fn first_bit_set(&self) -> Option<usize>;
    fn last_bit_set(&self) -> Option<usize>;

    // Provided method
    fn clear_all(&mut self) { ... }
}

Expand description

Types implementing this trait can be used as storage for a GrowableBitmap.

Only fixed-size types should implement this: see the BITS_IN_STORAGE constant requirement for this trait.

§Safety

This trait exposes several methods that are unsafe to call.

The given index must fit in 0..<Self as BitStorage>::BITS_IN_STORAGE for the behaviour of the unsafe methods to be correct.

Provided Associated Constants§

Source

const BITS_IN_STORAGE: usize = _

Number of bits that can be stored in one instance of Self.

This is a constant and types implementing this trait guarantee this will always be exact.

Required Methods§

Source

fn empty() -> Self

Construct a new, empty instance of a BitStorage type.

§Examples

use growable_bitmap::BitStorage;

let a = u8::empty();
assert_eq!(a, 0);

Source

fn is_empty(&self) -> bool

Returns true is the storage is considered empty (no 1s anywhere).

§Examples

use growable_bitmap::BitStorage;

let a = u16::empty();
assert!(a.is_empty());

let a = 1_u16 << 2;
assert!(!a.is_empty());

Source

unsafe fn get_bit(&self, index: usize) -> bool

Gets the bit at the given index and returns true when it is set to 1, false when it is not.

§Safety

The given index must fit in 0..<Self as BitStorage>::BITS_IN_STORAGE for the behaviour of this method to be correct.

§Examples

use growable_bitmap::BitStorage;

let a = u32::empty();
assert!(unsafe { !a.get_bit(2) });

let a = 1_u32 << 2;
assert!(unsafe { a.get_bit(2) });

Source

unsafe fn set_bit(&mut self, index: usize) -> bool

Sets the bit at the given index and returns true when it is set to 1 by this call, false when it was already 1.

§Safety

The given index must fit in 0..<Self as BitStorage>::BITS_IN_STORAGE for the behaviour of this method to be correct.

§Examples

use growable_bitmap::BitStorage;

let mut a = u64::empty();

assert!(unsafe { a.set_bit(0) });
assert!(unsafe { a.get_bit(0) });

assert!(unsafe { a.set_bit(7) });
assert!(unsafe { a.get_bit(7) });

assert!(unsafe { !a.set_bit(0) });

Source

unsafe fn clear_bit(&mut self, index: usize) -> bool

Clears the bit at the given index and returns true when it is set to 0 by this call, false when it was already 0.

§Safety

The given index must fit in 0..<Self as BitStorage>::BITS_IN_STORAGE for the behaviour of this method to be correct.

§Examples

use growable_bitmap::BitStorage;

let mut a = u64::empty();

assert!(unsafe { !a.clear_bit(56) });

assert!(unsafe { a.set_bit(56) });
assert!(unsafe { a.clear_bit(56) });
assert!(unsafe { !a.get_bit(56) });

Source

fn count_ones(&self) -> usize

Returns the number of bits set to 1 in Self.

§Examples

use growable_bitmap::BitStorage;

let a = u8::empty();
assert_eq!(a.count_ones(), 0);

let mut a = a;
unsafe { a.set_bit(0); }
assert_eq!(a.count_ones(), 1);

unsafe { a.set_bit(3); }
assert_eq!(a.count_ones(), 2);

unsafe { a.set_bit(7); }
assert_eq!(a.count_ones(), 3);

unsafe { a.clear_bit(4); }
assert_eq!(a.count_ones(), 3);

unsafe { a.clear_bit(7); }
assert_eq!(a.count_ones(), 2);

a.clear_all();
assert_eq!(a.count_ones(), 0);

Source

fn first_bit_set(&self) -> Option<usize>

Returns the index of the first bit set in the binary representation of self, if any, else returns None.

§Example

Example on a u8 where the least significant bit is to the right:

0b1100_0100
        ^
        index = 3

use growable_bitmap::BitStorage;

let v = u16::empty();
assert_eq!(v.first_bit_set(), None);

let mut v = v;
unsafe { v.set_bit(3); }
assert_eq!(v.first_bit_set(), Some(3));

unsafe { v.set_bit(7); }
assert_eq!(v.first_bit_set(), Some(3));

unsafe { v.set_bit(1); }
assert_eq!(v.first_bit_set(), Some(1));

Source

fn last_bit_set(&self) -> Option<usize>

Returns the index of the last bit set in the binary representation of self, if any, else returns None.

§Example

Example on a u8 where the least significant bit is to the right:

0b0010_0011
    ^
    index = 5

use growable_bitmap::BitStorage;

let v = u16::empty();
assert_eq!(v.last_bit_set(), None);

let mut v = v;
unsafe { v.set_bit(3); }
assert_eq!(v.last_bit_set(), Some(3));

unsafe { v.set_bit(1); }
assert_eq!(v.last_bit_set(), Some(3));

unsafe { v.set_bit(7); }
assert_eq!(v.last_bit_set(), Some(7));

Provided Methods§

Source

fn clear_all(&mut self)

Clears the whole storage, setting self to the empty value.

The default implementation uses *self = Self::empty().

§Examples

use growable_bitmap::BitStorage;

let mut a = u128::empty();

let mut a: u128 = 42;
a.clear_all();
assert!(a.is_empty());

let mut a: u128 = 1 << 120;
a.clear_all();
assert!(a.is_empty());