20 releases (2 stable)
2.0.0 | Jan 28, 2023 |
---|---|
1.0.0 | Jan 22, 2022 |
0.11.0 | Jul 4, 2021 |
0.10.1 | Jan 25, 2021 |
0.4.1 | Jul 2, 2018 |
#166 in Encoding
9,696 downloads per month
Used in 26 crates
(15 directly)
115KB
1.5K
SLoC
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 forUlid
.
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.
Dependencies
~1–32MB
~493K SLoC