From 863faed5ea8d89ca413d1fdfc2bbe7bdf12ad988 Mon Sep 17 00:00:00 2001
From: bbaldino <bbaldino@gmail.com>
Date: Thu, 30 May 2024 14:17:50 -0700
Subject: [PATCH] readme updates

---
 README.md | 21 +++++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 72d4df3..e56fdcc 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,24 @@
 # BitCursor
 
 BitCursor is similar to std::io::Cursor, but allows reading various amounts of bits from a given buffer in addition
-to byte-sized chunks.  It's built on top of the [ux](https://crates.io/crates/ux) crate for types.
+to byte-sized chunks.  It's built on top of the [ux](https://crates.io/crates/ux) crate for types and leverages 
+[bitvec](https://docs.rs/bitvec/latest/bitvec/) to provide a more complete implementation.
 
+# Examples
+
+```rust
+let data: Vec<u8> = vec![0b11100000, 0b11101111];
+let mut cursor = BitCursor::from_vec(data);
+
+// Read any non-standard-width type from the cursor
+let u3_val = cursor.read_u3().unwrap();
+assert_eq!(u3_val, ux::u3::new(0b111));
+// Sizes larger than 8 bits require a byte order argument
+let u13_val = cursor
+    .read_u13::<crate::byte_order::NetworkOrder>()
+    .unwrap();
+assert_eq!(u13_val, ux::u13::new(0b0000011101111));
+```
 
 # Design
 
@@ -20,6 +36,3 @@ to byte-sized chunks.  It's built on top of the [ux](https://crates.io/crates/ux
 
 ### `BitCursor`
 `BitCursor` is analgous to the [`std::io::Cursor`](https://doc.rust-lang.org/std/io/struct.Cursor.html) type, but its API is defined in terms of bits instead of bytes.
-
-### `BitSlice`/`BitSliceMut`
-The `std::io` types' APIs often use the `&[u8]` type for 'slices', so `BitCursor`'s equivalent would be to use a slice of `u1`: `&[u1]`, but, for ergonomic reasons, we instead use `BitSlice`/`BitSliceMut` types to mimic `&[u1]` and `&mut [u1]`.