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:

// 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.

// 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:

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 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