# Rust implementation of a standard Bitstream

With _meepmorp_ you can read and write on streams very efficiently. This lib
attempt to be parralell with all previous standard implementation you can often
see in _C_ or _C++_, simple to use, reinterpreted with some cool _Rust_ tools.

## Write

Before reading whatever you want, someone had too write the data, like that:

```rust
// This create you a stream with a `usize` a
// temporary register
let mut e_stream = BitEstream::new(len).unwrap();

// Add N bits in temp register
// ( You can go up to 64 bits on x64
//   and obviously to 32 bits if x86 )
e_stream.add_bits(usized, 3).unwrap();
e_stream.add_bits(usized, 1).unwrap();
e_stream.add_bits(usized, 5).unwrap();
e_stream.add_bits(usized, 5).unwrap();

// Flush temp register, store bits into the final stream
e_stream.flush_bits();

// Close the stream and you're done (that put an endMark
// and flush the latest remainings bits from the temp
// container )
e_stream.close_stream().unwrap();

let vec: Vec<u8> = e_stream.into();
```

## Read
Read is also easy to do.

```rust
// This create you a stream with a `usize` a
// temporary register
let vec: Vec<u8> = /* eluded */
let mut d_stream = Bitdstream::try_from(vec).unwrap();

// Or even from a closed (or not) encoder stream
let mut d_stream = Bitdstream::try_from(e_stream).unwrap();

// Add N bits in temp register
// ( You can go up to 64 bits on x64
//   and obviously to 32 bits if x86 )
d_stream.read_bits(3).unwrap();
d_stream.read_bits(1).unwrap();
d_stream.read_bits(5).unwrap();
d_stream.read_bits(5).unwrap();

// Flush temp register, store bits into the final stream
d_stream.reload_container();
```

## Benchmark
Speed, speed, speed.

In the unit tests you can see that kind of code:
```rust
let buffer = Vec::with_capacity(len);
// this is randomly filled as used in tests
let mut e_stream = BitEstream::new(len + 1).unwrap();

for (i, byte) in buffer.iter().enumerate() {
    if i > 0 && i % CTNR_BYTES_SIZE == 0 {
        e_stream.flush_bits();
    }
    e_stream.add_bits(*byte as usize, BYTE_LEN).unwrap();
}
e_stream.close_stream().unwrap();
```

I choose to bench a complete writing and reading process with _10kb_ on my
labtop. Here is the criterion report graph and I get a value really similar to
the [bitstream-io](https://docs.rs/bitstream-io/1.0.0/bitstream_io/) crate.
Check on your favorit computer with thecommand `cargo bench`.

In addition, you! developer! If you're looking for a complete swiss knife
library for your bitstreaming, you probably be better with the _bitstream-io_.
All depend of your needs =-) (Sorry, I put that message at the end of the
documentation)

## Next step
I want to give the possiblity to work with iterator instead of already
allocated vectors. For the moment there is no plan or milestones.

## License

This development is under MIT License,