englishid
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.
Open-source Licenses
This project, like all projects from Khonsu Labs, are open-source. This repository is available under the MIT License or the Apache License 2.0.
6 Mar 8, 2023
22 Nov 14, 2022
33 Aug 6, 2022
8 Sep 2, 2022
14 Jan 9, 2023
6 Jan 29, 2023
6 Jun 3, 2023
56 Nov 24, 2022
6 May 23, 2021
20 Aug 16, 2022
12 Nov 3, 2022
88 Dec 31, 2022
1 Dec 18, 2021
3 Mar 30, 2024
75 Jul 28, 2022
18 Jul 3, 2021
4 Jul 10, 2022
397 Jan 9, 2023
13 Nov 2, 2022
4 Jul 10, 2022
4 Jul 28, 2022
7 Dec 6, 2022
5 Oct 6, 2022
294 Dec 23, 2022
7.3k Jan 3, 2023
15 Nov 23, 2022
9 Dec 23, 2022
10 Jul 5, 2022
6 Aug 8, 2022