Crate englishid[][src]

Expand description

English formatting for unsigned integer IDs and arbitrary data.

englishid forbids unsafe code crate version Live Build Status Documentation for main branch

English formatting for unsigned integers. Useful for encoding large IDs in a human-readable and recognizable format. Uses a modified list of words based on a list created by the EFF.

Basic Usage

Generating an ID can be done from any primitive unsigned integer type:

use englishid::EnglishId;

let english_id = EnglishId::from(42_u16).to_string().unwrap();
assert_eq!(english_id, "accept-abacus");

Use the corresponding parse method to extract the encoded id:

let parsed = englishid::parse_u16("accept-abacus").unwrap();
assert_eq!(parsed, 42);

Restricting word-length

The wordlist used can encode 52 bits of information in 4 words. If you’d prefer to restrict your u64 IDs to 52 bits, you can set the number of words used:

use englishid::EnglishId;

let english_id = EnglishId::from(123456789_u64).words(4).to_string().unwrap();
assert_eq!(english_id, "haunt-subtitle-abandon-abacus");
assert_eq!(englishid::parse_u64(&english_id).unwrap(), 123456789_u64);

If a value is ever out of acceptable ranges, Error::ValueOutOfRange will be returned.

Encoding/decoding arbitrary data

This crate also offers functions that allow encoding arbitrary bytes of information using the same word list. If you will always know the data size, you can use the fixed_length functions:

let payload = b"hello world";
let encoded = englishid::encode_fixed_length(payload);
assert_eq!(encoded, "hatchback-reissue-residual-overbuilt-ladybug-tusk-buffing");
assert_eq!(englishid::decode_fixed_length(&encoded, payload.len()).unwrap(), payload);

If you are encoding payloads of differing lengths and want the length to be encoded into the resulting englishid string, encode() and decode() will do that for you:

let payload = b"hello world";
let encoded = englishid::encode(payload).unwrap();
assert_eq!(encoded, "able-hatchback-reissue-residual-overbuilt-ladybug-tusk-buffing");
assert_eq!(englishid::decode(&encoded).unwrap(), payload);

Or, if you have an enum that can correspond to a byte length, you can use a custom header value:

enum PrivateKey {
    Ed25519([u8; 32]),
    Ed448([u8; 56])
}

impl PrivateKey {
    fn as_bytes(&self) -> &[u8] {
        match self {
            Self::Ed25519(key) => key,
            Self::Ed448(key) => key,
        }
    }

    fn kind(&self) -> u16 {
        match self {
            Self::Ed25519(_) => 1,
            Self::Ed448(_) => 2,
        }
    }

    fn byte_length(kind: u16) -> usize {
        match kind {
            1 => 32,
            2 => 56,
            _ => 0,
        }
    }
}

let key = PrivateKey::Ed25519([0; 32]);
let encoded = englishid::encode_with_custom_header(key.as_bytes(), key.kind()).unwrap();
assert_eq!(englishid::decode_with_custom_header(&encoded, PrivateKey::byte_length).unwrap(), key.as_bytes());

Limits on data encoding

When encoding using the fixed_length APIs, there is no limit to the amount of data that can be encoded.

When using the automatic length header or a custom header, the value in the header cannot be larger than 8190. This limit may be removed in the future, but this crate is not intended for large payload encoding.

Version stability

The maintainers of this crate will treat changes to the wordlist as breaking changes in the eyes of semantic versioning. In the future, this crate may support additional wordlists which will provide another mechanism to releasing wordlist updates, which should be infrequent.

If an issue is discovered that generated data that was unable to be recovered into its original form, fixes will be shipped on minor releases and versions that can generate invalid data will be yanked.

Structs

An ID that can be converted to a set of “safe” words.

Enums

An error from encoding or parsing an EnglishId.

Statics

A list of words based on the list created by the EFF, but with some additional words to expand the list to 8,192 entries.

Functions

Decodes englishid that was previously encoded using encode().

Decodes englishid that was previously encoded using encode_fixed_length()., expecting an output size of length.

Decodes englishid that was previously encoded using encode_with_custom_header(). After parsing the embedded header, callback is invoked with the value. The callback is responsible for returning the number of bytes the result is expected to contain.

Encodes data using englishid with enough information to be able to be decoded without additional information. To decode, use the decode() function.

Encodes data using englishid, for situations where the decoder knows the expected length of data. To decode, use the decode_fixed_length() function.

Encodes data using englishid, encoding header at the start. To decode, use the decode_with_custom_header() function.

Parses a previously-encoded EnglishId.

Parses a previously-encoded EnglishId.

Parses a previously-encoded EnglishId.

Parses a previously-encoded EnglishId.

Parses a previously-encoded EnglishId.