azamcodec-rs

An encoder and decoder implementation in Rust for Azam Codec, a lexicographically sortable multi-section base16 encoding of byte array. Zero external dependencies.

License

MIT Licence Copyright (c) 2022 Azamshul Azizy

Usage

Import the crate and start using it.

Decoding

```rust use azamcodec::{azam_decode, decode::AzamDecode};

// Decode first section of Azam-encoded string as u32, using trait [AzamDecode] on uint type. // "xytxvyyf" decodes to 0xdeadbeefu32, the rest of string is ignored. let x = u32::azam_decode("xytxvyyfh5wgg1"); // 0xdeadbeefu32

// Decode multiple sections of Azam-encoded string to a tuple using azamdecode! macro. // "xytxvyyf" decodes to 0xdeadbeefu32. // "h5" decodes to 0x15u8. // "wgg1" decodes to 0xc001u16. let (x, y, z) = azamdecode!("xytxvyyfh5wgg1", u32, u8, u16).unwrap(); // (0xdeadbeefu32, 0x15u8, c001u16)

// Decode multiple sections of Azam-encoded string into custom struct. struct Id { recordid: u32, typeid: u8, variantid: u16, } impl Id { pub fn fromstr(value: &str) -> Self { // reader can be anything that implements std::io::Read. // e.g. network stream or file // This example reads from a byte array, which is backed by a string. let reader = &mut value.asbytes(); let recordid = u32::azamdecoderead(reader).unwrap(); let typeid = u8::azamdecoderead(reader).unwrap(); let variantid = u16::azamdecoderead(reader).unwrap(); Self { recordid, typeid, variant_id, } } } ```

Encoding

```rust use azamcodec::{azam_encode, encode::AzamEncode};

// Encode u32 value as Azam-encoded string as u32, using trait [AzamEncode] on uint type. // 0xdeadbeefu32 encodes to "xytxvyyf". let x = 0xdeadbeefu32.azam_encode(); // "xytxvyyf"

// Encode multiple values as Azam-encoded string, using [azam_decode!] macro. // 0xdeadbeefu32 encodes to "xytxvyyf". // 0x15u8 encodes to "h5". // 0xc001u16 encodes to "wgg1". let x = azam_encode!(0xdeadbeefu32, 0x15u8, 0xc001u16); // "xytxvyyfh5wgg1"

// Encode multiple values as Azam-encoded string from custom struct. struct Id { recordid: u32, typeid: u8, variantid: u16, } impl Id { pub fn tostr(&self) -> String { // writer can be anything that implements std::io::Write. // This example writes to a byte array, then converted to string. // e.g. network stream or file let mut writer = Vec::::new(); self.recordid.azamencodewrite(&mut writer).unwrap(); self.typeid.azamencodewrite(&mut writer).unwrap(); self.variantid.azamencodewrite(&mut writer).unwrap(); String::fromutf8(writer).unwrap() } } ```

Development

Standard Rust development applies. Benchmark is also included, executable via cargo bench.