# FastBit API Reference
This document provides an overview of the main types and traits in the FastBit library.
## Core Types
### BitVec
`BitVec<W>` is a growable bit vector, similar to `Vec<bool>` but much more memory-efficient. It provides dynamic resizing capabilities and is suitable for cases where the number of bits may change.
[See detailed BitVec documentation](https://docs.rs/fastbit/latest/fastbit/struct.BitVec.html)
### BitFixed
`BitFixed<W>` is a fixed-size bitset that provides efficient storage and manipulation of a fixed number of bits. It's more memory-efficient than `BitVec` for cases where the size is known in advance.
[See detailed BitFixed documentation](BitFixed.md)
### BitGrid
`BitGrid<W>` is a 2D grid of bits, useful for representing matrices, graphs, and other 2D data structures.
### BitSpan and BitSpanMut
`BitSpan<W>` and `BitSpanMut<W>` provide read-only and mutable views into a slice of bits, respectively.
### BitView and BitViewMut
`BitView<W>` and `BitViewMut<W>` provide read-only and mutable views into a bitset, respectively.
## Core Traits
### BitRead
The `BitRead` trait provides methods for reading bits from a bitset:
```rust
pub trait BitRead {
type Iter<'a>: Iterator<Item = usize>
where
Self: 'a;
// Returns the number of bits in the bitset
fn len(&self) -> usize;
// Returns true if the bitset contains no set bits
fn is_empty(&self) -> bool;
// Returns true if the bit at position `idx` is set
fn test(&self, idx: usize) -> bool;
// Returns the number of set bits
fn count_ones(&self) -> usize;
// Returns true if all bits are set
fn all(&self) -> bool;
// Returns true if any bit is set
fn any(&self) -> bool;
// Returns true if no bit is set
fn none(&self) -> bool;
// Returns an iterator over the set bits
fn iter(&self) -> Self::Iter<'_>;
}
```
### BitWrite
The `BitWrite` trait extends `BitRead` with methods for modifying bits:
```rust
pub trait BitWrite: BitRead {
// Sets the bit at position `idx`
fn set(&mut self, idx: usize);
// Clears the bit at position `idx`
fn reset(&mut self, idx: usize);
// Flips the bit at position `idx`
fn flip(&mut self, idx: usize);
// Returns and clears the bit at position `idx`
fn take(&mut self, idx: usize) -> bool;
// Sets the bit at position `idx` to `value` and returns the previous value
fn replace(&mut self, idx: usize, value: bool) -> bool;
// Sets the bit at position `idx` and returns the previous value
fn test_and_set(&mut self, idx: usize) -> bool;
// Sets all bits to 1
fn fill(&mut self);
// Clears all bits to 0
fn clear(&mut self);
}
```
### BitWord
The `BitWord` trait is implemented by word types used for storage in bitsets:
```rust
pub trait BitWord:
Debug
+ Copy
+ Hash
+ From<u8>
+ BitOr<Output = Self>
+ BitOrAssign
+ BitXor<Output = Self>
+ BitXorAssign
+ BitAnd<Output = Self>
+ BitAndAssign
+ Not<Output = Self>
+ Shr<usize, Output = Self>
+ Shl<usize, Output = Self>
+ Sub<Output = Self>
+ PartialEq
{
const BITS: usize;
const MAX: Self;
fn count_ones(self) -> usize;
fn trailing_zeros(self) -> usize;
}
```
This trait is implemented for `u8`, `u16`, `u32`, `u64`, `u128`, and `usize`.
## Examples
### Basic Usage
```rust
use fastbit::{BitVec, BitRead, BitWrite};
let mut bv: BitVec<u8> = BitVec::new(128);
bv.set(5);
assert!(bv.test(5));
bv.reset(5);
assert!(!bv.test(5));
```
### Iterating Over Set Bits
```rust
use fastbit::{BitFixed, BitRead, BitWrite};
let mut bf: BitFixed<u16> = BitFixed::new(32);
bf.set(10);
bf.set(20);
bf.set(30);
for idx in bf.iter() {
println!("Bit {} is set", idx);
}
```
### Bitwise Operations
```rust
use fastbit::{BitFixed, BitRead, BitWrite};
use std::ops::{BitAnd, BitOr, BitXor, Not};
let mut bf1: BitFixed<usize> = BitFixed::new(8);
let mut bf2: BitFixed<usize> = BitFixed::new(8);
bf1.set(1);
bf1.set(3);
bf1.set(5);
bf2.set(3);
bf2.set(4);
bf2.set(5);
// Bitwise AND
let bf_and = &bf1 & &bf2;
// Bitwise OR
let bf_or = &bf1 | &bf2;
// Bitwise XOR
let bf_xor = bf1.bitxor(&bf2);
// Bitwise NOT
let bf_not = !&bf1;
```
For more detailed documentation on specific types, please refer to the individual documentation pages.