rusty_ulid

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

This crate works with Rust 1.60.0 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.
• support for monotonic ULIDs.
• conversion from &[u8].
• conversion to and from [u8; 16].
• conversion to and from (u64, u64).
• conversion to and from u128.
• optional serde support for both human-readable and binary encoding.
• optional use of either chrono or time.
• optional rocket path/query parameter and form value parsing support.
• optional schemars JsonSchema trait impl for Ulid.

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.

Choosing the right optional features

Parsing and handling ULIDs does not require any dependencies.

Generating ULIDs requires the rand crate as well as either the time or the chrono crate. If both time and chrono are enabled, the time crate will be used to obtain the current time.

The serde dependency is necessary to enable serde support.

The following dependencies are enabled by default: ["rand", "time", "serde"]

You can change this by disabling default-features and defining the enabled features explicitly like this:

[dependencies]
rusty_ulid = { version = "2", default-features = false, features = ["rand", "chrono", "serde"] }

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-14T16:08:33.691Z

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-14T16:08:14.148Z

01CB2EMMMV8P51SCR9ZH8K64CX
2018-04-14T16:08:33.691Z

Invalid ULID strings: ["foo"]

$ echo $?
1

Executing rusty_ulid -h will print the help.

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.

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.