rusty_ulid 0.10.1

Rust ULID (Universally Unique Lexicographically Sortable Identifier) generation and processing
Documentation

rusty_ulid

Build Status codecov Crates.io docs.rs dependency status tokei Safety Dance

This is a Rust implementation of the ULID Universally Unique Lexicographically Sortable Identifiers.

This crate requires Rust 1.40 or later.

Take a look at the changelog for a detailed list of all changes.

Features

  • lenient parsing of ULID strings as specified in Crockford Base32 Encoding.
  • straight-forward creation of string and binary ULIDs.
  • optional support for monotonic ULIDs.
  • conversion from &[u8].
  • conversion to and from [u8; 16].
  • conversion to and from (u64, u64).
  • conversion to and from u128.
  • serde support for both human-readable and binary encoding.

Quickstart

use rusty_ulid::generate_ulid_string;
use rusty_ulid::generate_ulid_bytes;

// Generate a ULID string
let ulid_string: String = generate_ulid_string();
assert_eq!(ulid_string.len(), 26);

// Generate ULID bytes
let ulid_bytes: [u8; 16] = generate_ulid_bytes();
assert_eq!(ulid_bytes.len(), 16);
use std::str::FromStr;
use rusty_ulid::Ulid;

// Generate a ULID
let ulid = Ulid::generate();

// Generate a string for a ULID
let ulid_string = ulid.to_string();

// Create ULID from a string
let result = Ulid::from_str(&ulid_string);

assert_eq!(Ok(ulid), result);
use rusty_ulid::Ulid;

// Alternative way to parse a ULID string
// This example assumes a function returning a Result.
let ulid: Ulid = "01CAT3X5Y5G9A62FH1FA6T9GVR".parse()?;

let datetime = ulid.datetime();
assert_eq!(datetime.to_string(), "2018-04-11 10:27:03.749 UTC");
# Ok::<(), rusty_ulid::DecodingError>(())

Monotonic ULIDs are supported via Ulid::next_monotonic(previous_ulid) -> Ulid and Ulid::next_strictly_monotonic(previous_ulid) -> Option<Ulid>.

next_monotonic allows overflow of the random part to zero while next_strictly_monotonic returns None instead.

Benchmark

Run the benchmarks by executing cargo bench.

Executable

Install the executable by executing cargo install --path . or cargo install --path . --force if a prior version was already installed.

rusty_ulid usage examples

Just calling the executable generates a ULID.

$ rusty_ulid
01CB2EM1J4EMBWRBJK877TM17S

Calling the executable with -v or --verbose generates a ULID and prints its timestamp.

$ rusty_ulid -v
01CB2EMMMV8P51SCR9ZH8K64CX
2018-04-14 16:08:33.691 UTC

Calling the executable with any number of ULIDs checks them for validity and returns 0 if they are all fine...

$ rusty_ulid 01CB2EM1J4EMBWRBJK877TM17S 01CB2EMMMV8P51SCR9ZH8K64CX
$ echo $?
0

... or 1 if any given value is invalid, printing the invalid values to err.

$ rusty_ulid 01CB2EM1J4EMBWRBJK877TM17S foo 01CB2EMMMV8P51SCR9ZH8K64CX
Invalid ULID strings: ["foo"]
$ echo $?
1

In addition to that, -v or --verbose will print the ULIDs with their respective timestamp.

$ rusty_ulid -v 01CB2EM1J4EMBWRBJK877TM17S foo 01CB2EMMMV8P51SCR9ZH8K64CX
01CB2EM1J4EMBWRBJK877TM17S
2018-04-14 16:08:14.148 UTC

01CB2EMMMV8P51SCR9ZH8K64CX
2018-04-14 16:08:33.691 UTC

Invalid ULID strings: ["foo"]
$ echo $?
1

Executing rusty_ulid -h will print the help.

License

Licensed under either of

at your option.

Licensing

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.