#human #bits #binary #format #data #encode #binary-data #up #friendly #mechanism

libhumancode

A no_std compatible library that provides a function to enode binary data up to 150 bits in a human friendly format

3 stable releases

2.0.1 Nov 24, 2021
1.0.0 Nov 17, 2021

#309 in Algorithms

MIT/Apache

47KB
640 lines

libhumancode

Crates.io Documentation

libhumancode is a no_std compatible crate that provides a mechanism to encode up to 150 bits of binary data in a human friendly format.

z-base-32 encoding is used to encode all data - this allows for using a minimal number of symbols to encode data (unlike regular base-32, which requires padding characters depending on the number of bits to encode). Additionally, z-base-32 is designed to be human friendly. The tradeoff is that the sender and receiver of a code must agree on the number of bits of data in each code.

libhumancode also uses a configurable number of error correction symbols using a Reed Solomon GF(2^5) code. For each error correcting symbol added, this means that we can detect at least 1 error in a code. For every two symbols added, we can correct an error. Note that these properties are not additive - with 5 error correcting symbols, if we have an input with 2 errors, we will always correct it. If we have an input with 3 errors, we will always report it as incorrect. However, if we have an input with 4 errors, we might accidentally "correct" it to an invalid code. As such, its highly recommended to confirm code corrections with the user.

Example

use libhumancode::{decode_chunk, encode_chunk};

fn main() {
    const DATA: &'static [u8] = &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15];
    const ECC_SYMBOLS: u8 = 5;
    const BITS: u8 = 128;
    const CORRECT_CODE: &'static str = "yyyo-ryar-ywdy-qnyj-befo-adeq-bhix-4os";
    const INVALID_CODE: &'static str = "!!yo-ryar-ywdy-qnyj-befo-adeq-bhix-4os";

    let encoded = encode_chunk(DATA, ECC_SYMBOLS, BITS).unwrap();
    let encoded_pretty = encoded.pretty();

    assert_eq!(encoded_pretty.as_str(), CORRECT_CODE);

    let (decoded, corrected) = decode_chunk(INVALID_CODE, ECC_SYMBOLS, BITS).unwrap();

    assert_eq!(decoded.as_bytes(), DATA);
    assert_eq!(corrected.unwrap().pretty().as_str(), CORRECT_CODE);
}

No_std

No_std mode may be activated by disabling the "std" feature.

License

This project is licensed under either of

at your option.

Dependencies

~240KB