search

petgraph / fixedbitset

A simple bitset container for Rust
https://docs.rs/fixedbitset/
Apache License 2.0
124 stars 47 forks source link

Provide better API documentation (more examples!) #50

Closed jelemux closed 4 years ago

jelemux commented 4 years ago

Hi,

I'm a newcomer to Rust, who just tried to use your crate in my Conway's Game of Life learning project, as recommended in the "Rust and WebAssembly" book. And although it went mostly fine, I had a hard time understanding what some of the functions do or what kind of arguments they take.

Because of it being recommended in the aforementioned book one can expect more newcomers like me to stumble over your crate, that is why I think it would be very appropriate to update the documentation to be more accessible.

One particular example is the FixedBitSet::with_capacity_and_blocks function. As far as I understand, I give it a length and some data from which it creates a FixedBitSet. That data must implement the IntoIterator trait for u32. Vec<u32> should do that right? So I tried it like this:

let data = vec![
    0, 1, 0, 0, 1,
    1, 0, 0, 0, 0,
    1, 0, 0, 0, 1,
    1, 1, 1, 1, 0,
];

let cells = FixedBitSet::with_capacity_and_blocks(20, data);

Compiler gives no errors, but cells only contains zeros, not to mention the wasted space by representing bit-sized values as u32 if this would work. So do the Integers have to take some other representation? Unfortunately the documentation doesn't say anything about that.

A better API documentation would help here a lot, especially some examples. I would even do it myself if you want me to (And if you give me a hint on how to solve that issue I had ;-P ). There's also some other places where some examples would make it more clear what the code does.

jelemux commented 4 years ago

Hey guys, I figured out my problem with with_capacity_and_blocks.

For anyone else having the same problem: data must implement the IntoIterator trait because in some cases one u32 wouldn't be enough. The binary data is packed tightly into a bunch of u32s. In my case, one u32 is all we need (see the code below), so we're actually not wasting space here, we're saving it! 

let data = vec![0b01001_10000_10001_11110];
let cells = FixedBitSet::with_capacity_and_blocks(length, data);

I honestly can't believe that I didn't think of this earlier!

I still think that some examples would help greatly here, so I'm not closing this ticket and my offer still stands, if you want me to add some examples.