Crate libhumancode

Source
Expand description

§libhumancode

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.

Modules§

  • decoder
    Using the ChunkDecoder interfaces in this module may allow for a smaller binary size in the future. However, currently there is no size advantage to using these interfaces over crate::decode_chunk(). These interfaces primarily exist for consistency with the API of the crate::encoder module.
  • encoder
    Using the ChunkEncoder interfaces may allow for a smaller binary size since it may allow for certain pre-calculated tables to be removed at build time. This won’t work for all targets and at best can save about 1k over using crate::encode_chunk() directly.

Structs§

  • DecodedChunk
    A decoded chunk of bytes
  • EncodedChunk
    An Encoded chunk of bytes
  • EncodedChunkPretty
    A code in the “pretty” format - every group of 4 characters will be separated by a “-” to make it easier for a human to read.
  • EncodedChunkRaw
    A code in the “raw” format - just a list of z-base-32 characters with no separators
  • InputErrorCause
    An InputErrorCause can be formatted to get a string explaining the error.
  • UsageErrorCause
    A UsageErrorCause can be formatted to get a string explaining the error.

Enums§

Functions§