From 0f959efd5e84fa5dd3ad8435df6d4f08b44307ab Mon Sep 17 00:00:00 2001 From: Edgar Luque Date: Sat, 12 Nov 2022 17:39:57 +0100 Subject: [PATCH] better docs etc --- Cargo.toml | 8 +++++++ README.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ src/lib.rs | 59 +++++++++++++++++++++++++++++++++++++++++++++------- 3 files changed, 121 insertions(+), 7 deletions(-) create mode 100644 README.md diff --git a/Cargo.toml b/Cargo.toml index 618b9c3..32538a6 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -2,6 +2,14 @@ name = "teeint" version = "0.1.0" edition = "2021" +authors = ["Edgar "] +description = "A teeworlds variable int packer/unpacker." +repository = "https://github.com/edg-l/teeint/" +license = "MIT OR Apache-2.0" +keywords = ["ddnet", "teeworlds", "packer", "unpacker"] +categories = ["algorithms", "compression"] +documentation = "https://docs.rs/teeint" +readme = "README.md" # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html diff --git a/README.md b/README.md new file mode 100644 index 0000000..72a4c06 --- /dev/null +++ b/README.md @@ -0,0 +1,61 @@ +# teeint + +A teeworlds variable integer packer/unpacker. + +### Packing + +```rust +use std::io::Cursor; + +let mut buff = Cursor::new([0; 2]); + +teeint::pack(&mut buff, 64).unwrap(); + +let buff = buff.into_inner(); +assert_eq!(buff[0], 0b1000_0000); +assert_eq!(buff[1], 0b0000_0001); +``` + +Or using the trait [PackTwInt]: +```rust +use std::io::Cursor; +use teeint::PackTwInt; + +let mut buff = Cursor::new([0; 2]); + +64.pack(&mut buff).unwrap(); + +let buff = buff.into_inner(); +assert_eq!(buff[0], 0b1000_0000); +assert_eq!(buff[1], 0b0000_0001); +``` + +Or +```rust +use teeint::PackTwInt; + +let mut buff = [0; 2]; +64.pack(&mut buff.as_mut_slice()).unwrap(); +assert_eq!(buff[0], 0b1000_0000); +assert_eq!(buff[1], 0b0000_0001); +``` + +### Unpacking +```rust +use std::io::Cursor; + +let mut buff = Cursor::new([0b1000_0000, 0b0000_0001]); +let data = teeint::unpack(&mut buff).unwrap(); +assert_eq!(data, 64); +``` + +Or using the trait [UnPackTwInt]: +```rust +use teeint::UnPackTwInt; + +let buff = [0b1000_0000, 0b0000_0001]; +let result = buff.as_slice().unpack().unwrap(); +assert_eq!(result, 64); +``` + +License: MIT OR Apache-2.0 diff --git a/src/lib.rs b/src/lib.rs index f83bfa6..551ab5a 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,6 +1,6 @@ //! A teeworlds variable integer packer/unpacker. //! -//! Packing: +//! ## Packing //! //! ``` //! use std::io::Cursor; @@ -28,11 +28,41 @@ //! assert_eq!(buff[1], 0b0000_0001); //! ``` //! +//! Or +//! ``` +//! use teeint::PackTwInt; +//! +//! let mut buff = [0; 2]; +//! 64.pack(&mut buff.as_mut_slice()).unwrap(); +//! assert_eq!(buff[0], 0b1000_0000); +//! assert_eq!(buff[1], 0b0000_0001); +//! ``` +//! +//! ## Unpacking +//! ``` +//! use std::io::Cursor; +//! +//! let mut buff = Cursor::new([0b1000_0000, 0b0000_0001]); +//! let data = teeint::unpack(&mut buff).unwrap(); +//! assert_eq!(data, 64); +//! ``` +//! +//! Or using the trait [UnPackTwInt]: +//! ``` +//! use teeint::UnPackTwInt; +//! +//! let buff = [0b1000_0000, 0b0000_0001]; +//! let result = buff.as_slice().unpack().unwrap(); +//! assert_eq!(result, 64); +//! ``` + +#![forbid(unsafe_code)] +#![deny(missing_docs)] use std::io::{Read, Result, Write}; /// Pack a i32 into a teeworlds variable integer. -pub fn pack(dst: &mut impl Write, mut value: i32) -> Result<()> { +pub fn pack(dst: &mut T, mut value: i32) -> Result<()> { let mut current_byte: u8 = 0; /* @@ -67,7 +97,7 @@ pub fn pack(dst: &mut impl Write, mut value: i32) -> Result<()> { } /// Unpack a teeworlds variable int from the provided reader. -pub fn unpack(src: &mut impl Read) -> Result { +pub fn unpack(src: &mut T) -> Result { // Adapted from https://github.com/ddnet/ddnet/blob/79df5893ff26fa75d67e46f99e58f75b739ac362/src/engine/shared/compression.cpp#L10 let mut result: i32; let mut current_byte: u8 = 0; @@ -100,11 +130,11 @@ pub fn unpack(src: &mut impl Read) -> Result { /// This trait is more of a convenience to allow writing `0i32.pack(&mut buff)` pub trait PackTwInt { /// Pack this value into a teeworlds variable int. - fn pack(self, dst: &mut impl Write) -> Result<()>; + fn pack(self, dst: &mut T) -> Result<()>; } impl PackTwInt for i32 { - fn pack(self, dst: &mut impl Write) -> Result<()> { + fn pack(self, dst: &mut T) -> Result<()> { pack(dst, self) } } @@ -112,12 +142,12 @@ impl PackTwInt for i32 { /// Trait implemented by buffers holding a teeworlds variable int. /// /// This trait is more of a convenience to allow writing `let data = buff.unpack()?;` -pub trait UnpPackTwInt: Read { +pub trait UnPackTwInt: Read { /// Unpack this reader holding a teeworlds variable int to a i32. fn unpack(&mut self) -> Result; } -impl UnpPackTwInt for T { +impl UnPackTwInt for T { fn unpack(&mut self) -> Result { unpack(self) } @@ -255,10 +285,25 @@ mod tests { assert_eq!(buff[1], 0b0000_0001); } + #[test] + pub fn pack_64_trait_slice() { + let mut buff = [0; 2]; + assert!(64.pack(&mut buff.as_mut_slice()).is_ok()); + assert_eq!(buff[0], 0b1000_0000); + assert_eq!(buff[1], 0b0000_0001); + } + #[test] pub fn unpack_64_trait() { let mut buff = Cursor::new([0b1000_0000, 0b0000_0001]); let result = buff.unpack().unwrap(); assert_eq!(result, 64); } + + #[test] + pub fn unpack_64_trait_slice() { + let buff = [0b1000_0000, 0b0000_0001]; + let result = buff.as_slice().unpack().unwrap(); + assert_eq!(result, 64); + } }