rogusdev / fast32

Base 32 + 64 encoding and decoding identifiers + bytes in rust, quickly

fast32

Base32 and base64 encoding in Rust. Primarily for integer (u64, u128) and UUID identifiers (behind feature uuid), as well as arbitrary byte arrays. And do it all very quickly (more on this below).

The crate has installation instructions, and the documentation has extensive examples.

Encoding integers

Note that by default, encoding an integer into base32 or base64 via normal algorithms does not "look like" a number -- notably the rightmost character usually looks off, and there are sometimes more characters than there needs to be. This might be a plus for obfuscation, barely, but it makes them hard to reason about quickly, and it's also more efficient to process them as integers rather than arbitrary arrays of bytes (because we know upfront that integers are always a small size).

For example, the normal/base10 integer 31 processed normally, as bytes, into official RFC 4648 base32 hex, without padding, will come out as "D4". In contrast, processing it as an integer, as this library can, will come out as "Z" (in Crockford's base32 alphabet) which is more intuitively one less than 32 at "10", as one might hope (vs "EA" in base32 hex -- note that's an A not a 4 so the string changed nonintuitively for an increment of 1). This is helpful with "nice looking" urls of base32 encodings of identifiers, etc.

Speed

This is intended to be as fast as basically possible, while still keeping an intuitive interface.

It is, per the bench comparisons in this repo, on my machine, about 65-100%+ faster than the closest alternative for decoding u64s, and ~15-50%+ faster for encoding u64s, with bigger percent improvements for larger numbers. (That repo does not offer u128 or uuid support to compare against.)

It is also ~35-40% faster on decoding and encoding raw bytes vs the closest other alternative that is more mature but does not offer this crate's integer encoding/decoding, on top of the slower performance. There is an earlier and seemingly long abandoned alternative that is generally about 3x slower than this crate (and thus ~2x slower than the other alternative as well), but still somewhat popular.

Summary

In short, this crate should do everything you want for base32 and base64 encoding (please raise an issue if it doesn't!) while doing all of it very quickly and conveniently.

fast32's Issues

Unexpected/unhandled error when decoding.

Hello, I was using this library to check if a number was in base32 using the decode function.

fn is_base32_number(s: &str) -> bool {
    match RFC4648.decode(s.as_bytes()) {
        Ok(_) => true,
        Err(_) => false,
    }
}

When I pass a string that has a length less than 6 to the function, it panics with a "attempt to subtract with overflow" without throwing a DecodeError, which is caused by the following function:

fast32/src/base32/alphabet.rs

Line 154 in e9d8048

fn rem_pad(a: &[u8], pad: char) -> &[u8] {

, more specifically where it tries to index a[len - 6].

I made what i feel like is a bandaid fix, but I have only been writing rust for like a week or 2 so I am not sure if it follows the best conventions and guidelines.

I am sure this is not an intended function of decode method, but from what I have been reading it would follow Rust conventions to make it as safe as possible.

Provide lowercase alphabets

I want to encode into lowercase crockford Base32. Currently I use to_ascii_lowercase to do this in-place. Although it avoids character tables and doesn't support crockford encoding, an alternative project, base32ct, provides a means of encoding directly into lowercase base32.