base64id-rs

A pure rust library for representing 64 bit integers as base64url encoded strings. ```txt base64url i64 u64

B21CkMCtWZA 535157120202267024 535157120202267024 fHH_W21Typg 8967229101212682904 8967229101212682904 kjsG-f3NhxI -7909720649771415790 10537023423938135826 jHamKFSl5oM -8325284168998721917 10121459904710829699 ```

A 64 bit integer (8 bytes) is efficiently stored and manipulated in memory. When the value needs to be sent to a web client over HTTP, the value is base64url encoded and sent as exactly 11 base64url characters (11 bytes).

For a video of the underlying concept in action, see here.

Benefits

• 64 bit integers are sent in a url safe manor
• Reduces the number of bytes needed to send the integer as compared to decimal, which would require up to 20 bytes.
• Allows users to easily copy/paste the integer as a string

Motivation

I've used this concept a number of times in personal and work projects as I find it very useful. The problem is I've had to reimplement the functionality everytime.

The motivation for this library was to design and implement the core concept once, while paying attention to metrics such as performance, correctness, and compatability. To that end: - the library is no_std by default; with no heap allocation required, all execution is done on the stack - all base64 bit manipulation code is unit tested with fixed random values for compliance with RFC 4648

Installation

Add the following to your Cargo.toml file toml [dependencies] base64id = { version = "0.1", features = ["std"] }

For #![no_std] environments the std cargo feature can be omitted.

Usage

All work is done using the Id64 struct.

Encoding

You can convert an i64 or u64 into a Id64 as follows ```rs use base64id::Id64;

fn main() { let idi64 = Id64::from(1i64); let idu64 = Id64::from(1u64);

println!("{id_i64} {id_u64}"); // AAAAAAAAAAE AAAAAAAAAAE

} ```

Decoding

You can also use FromStr to convert strings into an Id64 ```rs use base64id::{Error, Id64}; use std::str::FromStr;

fn main() -> Result<(), Error> { let idstr = Id64::fromstr("PDFehCFVGqA")?;

println!("{}", i64::from(id_str)); // 4337351837722417824

Ok(())

} ```

Third Party Crates

Support for Serde, Rand and SQLx may be enabled through the use of optional cargo feature flags.

Rand

You can use the rand feature flag for working with the rand crate. ```rs use base64id::Id64; use rand::random;

let id: Id64 = random();

println!("{id}"); // 11 random base64url characters ```

Serde

You can use the serde feature flag to drive Serialize and Deserialize on Id64. ```rs use base64id::Id64; use serde::{Deserialize, Serialize};

[derive(Serialize, Deserialize)]

struct Record { id: Id64, }

let record = Record { id: Id64::from(0u64), };

println!("{}", serdejson::tostring(&record)?); // {"id":"AAAAAAAAAAA"} ```

SQLx

You can use the sqlx feature flag for using an Id64 with SQLx SQL commands. ```rs use base64id::Id64; use sqlx::{ sqlite::{Sqlite, SqliteConnection}, Connection, }; use std::str::FromStr;

let id = Id64::from_str("IkoY0lQYRrI")?; let mut conn = SqliteConnection::connect("sqlite::memory:").await?;

sqlx::query("CREATE TABLE sqlx (id INT PRIMARY KEY)") .execute(&mut conn) .await?;

sqlx::query("INSERT INTO sqlx VALUES (?)") .bind(id) .execute(&mut conn) .await?;

let output = sqlx::queryas::("SELECT id FROM sqlx LIMIT 1") .fetchone(&mut conn) .await?;

println!("{output}"); // IkoY0lQYRrI ```

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.