Readme and cargo manifest information

Cargo.toml

@@ -3,11 +3,19 @@ name = "bva"
 version = "0.1.0"
 authors = ["Charles Hubain <[email protected]>"]
 edition = "2018"
+description = "bva is a crate for manipulating bit vectors and doing arithmetics on arbitrarily sized bit vectors."
+documentation = "https://docs.rs/bva"
+readme = "README.md"
+homepage = "https://github.com/haxelion/bva/"
+repository = "https://github.com/haxelion/bva/"
+license = "Apache-2.0"
+keywords = ["bit", "vector", "binary", "arithmetics"]
+categories = ["data-structures", "encoding", "mathematics"]
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
 
 [dev-dependencies]
 
-rand = "0.7"
+rand = "0.7"

README.md

@@ -0,0 +1,39 @@
+# bva
+
+`bva` is a rust crate for manipulating bit vectors and doing arithmetics on arbitrarily sized bit
+vectors.
+
+This crate emphasizes optimizing storage by providing alternative storage options.
+The module `fixed` contains implementations using unsigned integers as storage and thus
+has a fixed capacity. The module `dynamic` contains an implementation using dynamically
+allocated array of integers as storage and therefore has a dynamic capacity. The module
+`auto` contains an implementation capable of switching at runtime between a fixed or
+dynamic capacity implementation to try to minimize dynamic memory allocations.
+All of those implementations implement the `BitVector` trait and can be freely mixed together
+and converted into each other.
+
+## Changelog
+
+* 2020/12/20 - 0.1.0
+    * BitVector trait with fixed, dynamic and auto implementations.
+    * Conversion between all the implementations
+    * Basic arithmetic operations between the different implementations.
+    * Reading and writing bit vector in various format.
+
+## TODO
+
+* More "advanced" arithmetics: multiplication, division, remainder.
+* Fix Display for bit vector longer than 128 bits.
+* Bit operations.
+* Iterator over bits, IntoIterator and FromIterator.
+* Borrowing of bits and bit slice inside a bit vector.
+* Really advanced arithmetics: gcd, modular exponentiation, ...
+* no-std support
+
+## Why
+
+None of the existing crate really satisfied me and I wanted an implementation capable of
+minimizing dynamic memory allocations by automatically switching to fixed storage.
+I also wanted a crate that was capable of doing arithmetics on arbitrarily sized bit vectors, not
+just powers of two.
+Also it was great practice for my rust macro writing skills.

src/auto.rs

@@ -249,6 +249,7 @@ impl Binary for BV {
     }
 }
 
+/// Warning: this implementation is broken for bit vector longer than 128 bits.
 impl Display for BV {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         match self {

src/dynamic/mod.rs

@@ -367,6 +367,7 @@ impl Binary for BVN {
     }
 }
 
+/// Warning: this implementation is broken for bit vector longer than 128 bits.
 impl Display for BVN {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         if let Ok(b) = BV128::try_from(self) {

src/lib.rs

@@ -1,4 +1,4 @@
-//! Crate for manipulating bit vectors and doing arithmetic on arbitrary sized bit vectors.
+//! Crate for manipulating bit vectors and doing arithmetic on arbitrarily sized bit vectors.
 //!
 //! This crate emphasizes optimizing storage by providing alternative storage options.
 //! The module [`fixed`] contains implementations using unsigned integers as storage and thus
@@ -38,7 +38,7 @@ pub enum Endianness {
     BE
 }
 
-/// A trait representing common bit vector operations
+/// A trait representing common bit vector operations.
 pub trait BitVector: Sized + Clone + Debug + PartialEq + Eq + Display + Binary + LowerHex + UpperHex {
     /// Construct a bit vector made of `length` 0 bits.
     /// Will panic if there is not enough capacity and it is a fixed variant.