#string-representation #ascii #parser #numbers #codec #integer-value

ascii_basing

Functions to create base 62 (ASCII) String representations of integers

1 unstable release

0.1.0 Jun 27, 2024

#1951 in Encoding


Used in structurray

Apache-2.0

20KB
153 lines

ascii_basing

A Rust Library that converts unsigned 32-bit integers (u32s) to unique String values that are always smaller or as small as base 10 representations of the given integer and can be decoded back to the exact value before encoding. ascii_basing does this using standard library functions to implement a Base62 encoding and decoding algorithm. For more information on how to use this crate, check the documentation.


lib.rs:

Base62 Converter & Deconverter

Convert your positive integers to ASCII-safe Strings for situations where a concise String representation of an integer is desired, such as when automatically generating file names or identifiers.

Each possible integer value is assigned a unique String representation, allowing for lossless conversion between Strings and [u32] values. Each additional character in a String representation can be thought of as another digit in a Base62 system. The Base62 system is similar to the hexadecimal system except that instead of only 16 digits, 62 digits are used. Here is a list of all 62 digits used by this crate, in order from least to greatest value:

0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ

Since the String representation of integers is based on Base62, lower values have shorter representations, but thanks to the large amount of values each digit could be, representations (of 32-bit integers) are never more than 6 characters long.

Example

As a quick example, let's encode a value using the encode function from the encoding module, then decode it using the decode function from the decoding module, like so:

let number: u32 = 52 * 62 * 62 + 9 * 62 + 35; // = 200481
let representation = encoding::encode(number,Some(3)).unwrap();
assert_eq!(String::from("Q9z"),representation);
assert_eq!(number,decoding::decode(representation.chars()).unwrap());

Alternatives

This library creates output similar to base-62, but the implementation is distinct. The main advantages of this library (as of now) are encoding 0 to the string "0" rather than an empty String, and allowing for users to give Optional hints about the size of encoded values (which are used to pre-allocate String capacity). base-62 has the advantage of allowing encoding and decoding of unsigned integers in &[u8] format rather than only u32 format.

In general, it is best to use base-62 when large numbers or byte sequences need to be encoded, and to use this library in most other situations.

No runtime deps