rusty_ulid
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 generate_ulid_string;
use generate_ulid_bytes;
// Generate a ULID string
let ulid_string: String = generate_ulid_string;
assert_eq!;
// Generate ULID bytes
let ulid_bytes: = generate_ulid_bytes;
assert_eq!;
use FromStr;
use Ulid;
// Generate a ULID
let ulid = generate;
// Generate a string for a ULID
let ulid_string = ulid.to_string;
// Create ULID from a string
let result = from_str;
assert_eq!;
use 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!;
# Ok::
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
- 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.