### 19 unstable releases (4 breaking)

0.5.6 | Mar 22, 2023 |
---|---|

0.5.4 | Jan 18, 2023 |

0.4.3 | Dec 7, 2022 |

0.2.2 | Oct 25, 2022 |

0.1.1 | Mar 31, 2021 |

#**314** in Data structures

**218** downloads per month

Used in **2** crates

**MIT/Apache**

130KB

2K
SLoC

# bittle

Zero-cost bitsets over native Rust types.

The name

comes from `bittle`

and `bit`

. Small bitsets!`little`

## Usage

Add

as a dependency in your `bittle`

:`Cargo .toml`

`[``dependencies``]`
`bittle ``=` `"`0.5.5`"`

## Guide

A bit is always identified by a

by its index, and the exact location
for a bit in a primitive numbers is defined by its endianness, which is
`u32`

by default.`BigEndian`

indexing grows from right to left, such as the following
`BigEndian`

literal:`u8`

`0b0010_0010u8
^ ^- index 1
'------ index 5
`

To interact with these bits we define the

, `Bits`

, and
`BitsMut`

traits. These traits are implemented for primitive types such
as `BitsOwned`

, `u32`

, or `[``u32``;` `4``]`

:`&``[``u32``]`

`use` `bittle``::`Bits`;`
`let` array`:` `[``u32``;` `4``]` `=` `[``0``,` `1``,` `2``,` `3``]``;`
`assert!``(`array`.``iter_ones``(``)``.``eq``(``[``32``,` `65``,` `96``,` `97``]``)``)``;`
`let` n `=` `0b00000000_00000000_00000000_00010001``u32``;`
`assert!``(`n`.``iter_ones``(``)``.``eq``(``[``0``,` `4``]``)``)``;`
`let` array_of_arrays`:` `[``[``u8``;` `4``]``;` `2``]` `=` `[``[``16``,` `0``,` `0``,` `0``]``,` `[``0``,` `0``,` `1``,` `0``]``]``;`
`assert!``(`array_of_arrays`.``iter_ones``(``)``.``eq``(``[``4``,` `48``]``)``)``;`
`let` `mut` vec`:` `Vec``<``u32``>` `=` `vec!``[``0``,` `1``,` `2``,` `3``]``;`
`assert!``(`vec`.``iter_ones``(``)``.``eq``(``[``32``,` `65``,` `96``,` `97``]``)``)``;`

We also provide the

macro, which is a zero-cost convenience method
for constructing primitive forms of bit sets:`set!`

`use` `bittle``::`Bits`;`
`let` array`:` `[``u32``;` `4``]` `=` `bittle``::`set`!``[``32``,` `65``,` `96``,` `97``]``;`
`assert!``(`array`.``iter_ones``(``)``.``eq``(``[``32``,` `65``,` `96``,` `97``]``)``)``;`
`let` n`:` `u32` `=` `bittle``::`set`!``[``0``,` `4``]``;`
`assert!``(`n`.``iter_ones``(``)``.``eq``(``[``0``,` `4``]``)``)``;`
`let` array_of_arrays`:` `[``[``u8``;` `4``]``;` `2``]` `=` `bittle``::`set`!``[``4``,` `48``]``;`
`assert!``(`array_of_arrays`.``iter_ones``(``)``.``eq``(``[``4``,` `48``]``)``)``;`

Since a vector is not a primitive bit set, it could instead make use of

directly:`BitsMut`

`use` `bittle``::``{`Bits`,` BitsMut`}``;`
`let` `mut` vec`:` `Vec``<``u32``>` `=` `vec!``[``0``u32``;` `4``]``;`
vec`.``set_bit``(``32``)``;`
vec`.``set_bit``(``65``)``;`
vec`.``set_bit``(``96``)``;`
vec`.``set_bit``(``97``)``;`
`assert!``(`vec`.``iter_ones``(``)``.``eq``(``[``32``,` `65``,` `96``,` `97``]``)``)``;`
`assert_eq!``(`vec`,` `[``0``,` `1``,` `2``,` `3``]``)``;`

Due to how broadly these traits are implemented, we also try to avoid using names which are commonly used in other APIs, instead opt for bit-specific terminology such as:

- Something like

becomes`is_empty`

- since with bits you're thinking about "ones and zeros".`all_zeros` - Testing if a bit is set is

, or in general adding the`test_bit`

suffix to operations over individual bits.`*`_bit - Clearing all bits becomes

, or in general adding the`clear_bits`

suffix when operating over`*`_bits*all*bits.

`use` `bittle``::``{`Bits`,` BitsMut`}``;`
`let` `mut` set `=` `[``0``u16``;` `2``]``;`
set`.``set_bit``(``15``)``;`
`assert!``(`set`.``test_bit``(``15``)``)``;`
set`.``union_assign``(``&``bittle``::`set`!``[``31``,` `7``]``)``;`
`assert!``(`set`.``test_bit``(``31``)` `&&` set`.``test_bit``(``7``)``)``;`
set`.``clear_bit``(``31``)``;`
`assert!``(``!`set`.``test_bit``(``31``)``)``;`
set`.``clear_bits``(``)``;`
`assert!``(`set`.``all_zeros``(``)``)``;`

Some other interesting operations, such as

are available,
allowing bitsets to act like masks over other iterators:`Bits ::`join_ones

`use` `bittle``::``{`Bits`,` BitsMut`}``;`
`let` elements `=` `vec!``[``10``,` `48``,` `101``]``;`
`let` `mut` m `=` `0``u128``;`
m`.``set_bit``(``0``)``;`
`assert!``(`m`.``join_ones``(``&`elements`)``.``eq``(``[``&``10``]``)``)``;`
m`.``set_bit``(``2``)``;`
`assert!``(`m`.``join_ones``(``&`elements`)``.``eq``(``[``&``10``,` `&``101``]``)``)``;`