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§

HumancodeError
Common error type used by all fallible operations

Functions§

decode_chunk
Decode and correct an encoded message.
encode_chunk
Encode a chunk of input data