rulid.rs's Introduction

Universally Unique Lexicographically Sortable Identifier

UUID can be suboptimal for many uses-cases because:

It isn't the most character efficient way of encoding 128 bits of randomness
The string format itself is apparently based on the original MAC & time version (UUIDv1 from Wikipedia)
It provides no other information than randomness

Instead, herein is proposed ULID:

128-bit compatibility with UUID
1.21e+24 unique ULIDs per millisecond
Lexicographically sortable!
Canonically encoded as a 26 character string, as opposed to the 36 character UUID
Uses Crockford's base32 for better efficiency and readability (5 bits per character)
Case insensitive
No special characters (URL safe)

Implementations in other languages

From the community!

Language	Author
Javascript	alizain
Erlang	savonarola
Elixir	merongivian
Go	imdario
Java	Lewiscowles1986
Julia	ararslan
.NET	RobThree
.NET	fvilers
PHP	Lewiscowles1986
Python	mdipierro
Ruby	rafaelsales

Specification

Below is the current specification of ULID as implemented in this repository.

 01AN4Z07BY      79KA1307SR9X4MV3

|----------|    |----------------|
 Timestamp          Randomness
  10 chars           16 chars
   50bits             80bits
   base32             base32

Components

Timestamp

48 bit integer
UNIX-time in milliseconds
Won't run out of space till the year 10895 AD.

Randomness

80 bits
Cryptographically secure source of randomness, if possible

Sorting

The left-most character must be sorted first, and the right-most character sorted last (lexical order). The default ASCII character set must be used. Within the same millisecond, sort order is not guaranteed

Encoding

Crockford's Base32 is used as shown. This alphabet excludes the letters I, L, O, and U to avoid confusion and abuse.

0123456789ABCDEFGHJKMNPQRSTVWXYZ

Binary Layout and Byte Order

The components are encoded as 16 octets. Each component is encoded with the Most Significant Byte first (network byte order).

0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                      32_bit_uint_time_low                     |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|     16_bit_uint_time_high     |       16_bit_uint_random      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                       32_bit_uint_random                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                       32_bit_uint_random                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

String Representation

ttttttttttrrrrrrrrrrrrrrrr

where
t is Timestamp
r is Randomness

Prior Art

Partly inspired by:

rulid.rs's People

Contributors

Stargazers

Watchers

rulid.rs's Issues

Lots of warnings

build

> rustup run stable cargo test
warning: use of deprecated trait `std::ascii::AsciiExt`: use inherent methods instead
  --> src/lib.rs:11:17
   |
11 | use std::ascii::AsciiExt;
   |                 ^^^^^^^^
   |
   = note: `#[warn(deprecated)]` on by default

warning: unused import: `std::ascii::AsciiExt`
  --> src/lib.rs:11:5
   |
11 | use std::ascii::AsciiExt;
   |     ^^^^^^^^^^^^^^^^^^^^
   |
   = note: `#[warn(unused_imports)]` on by default

warning: `rulid` (lib) generated 2 warnings
   Compiling rulid v0.3.1 (/home/jayvdb/rust/rulid.rs)
warning: use of deprecated trait `std::ascii::AsciiExt`: use inherent methods instead
 --> examples/decodedebug.rs:4:17
  |
4 | use std::ascii::AsciiExt;
  |                 ^^^^^^^^
  |
  = note: `#[warn(deprecated)]` on by default

warning: unused import: `std::ascii::AsciiExt`
 --> examples/decodedebug.rs:4:5
  |
4 | use std::ascii::AsciiExt;
  |     ^^^^^^^^^^^^^^^^^^^^
  |
  = note: `#[warn(unused_imports)]` on by default

warning: `rulid` (example "decodedebug") generated 2 warnings
warning: `rulid` (lib test) generated 2 warnings (2 duplicates)
    Finished test [unoptimized + debuginfo] target(s) in 0.28s
...

clippy:

warning: constants have by default a `'static` lifetime
  --> src/lib.rs:13:28
   |
13 | const CROCKFORD_ALPHABET: &'static [u8] = b"0123456789ABCDEFGHJKMNPQRSTVWXYZ";
   |                           -^^^^^^^----- help: consider removing `'static`: `&[u8]`
   |
   = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#redundant_static_lifetimes
   = note: `#[warn(clippy::redundant_static_lifetimes)]` on by default

warning: unneeded unit return type
   --> src/lib.rs:209:40
    |
209 | pub fn right_shift_2bit(buf: &mut [u8]) -> () {
    |                                        ^^^^^^ help: remove the `-> ()`
    |
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#unused_unit
    = note: `#[warn(clippy::unused_unit)]` on by default

warning: unneeded unit expression
   --> src/lib.rs:222:5
    |
222 |     ()
    |     ^^ help: remove the final `()`
    |
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#unused_unit

warning: unneeded unit return type
   --> src/lib.rs:225:39
    |
225 | pub fn left_shift_6bit(buf: &mut [u8]) -> () {
    |                                       ^^^^^^ help: remove the `-> ()`
    |
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#unused_unit

warning: unneeded unit expression
   --> src/lib.rs:239:5
    |
239 |     ()
    |     ^^ help: remove the final `()`
    |
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#unused_unit

warning: use of deprecated trait `std::ascii::AsciiExt`: use inherent methods instead
  --> src/lib.rs:11:17
   |
11 | use std::ascii::AsciiExt;
   |                 ^^^^^^^^
   |
   = note: `#[warn(deprecated)]` on by default

warning: unused import: `std::ascii::AsciiExt`
  --> src/lib.rs:11:5
   |
11 | use std::ascii::AsciiExt;
   |     ^^^^^^^^^^^^^^^^^^^^
   |
   = note: `#[warn(unused_imports)]` on by default

warning: manual implementation of an assign operation
   --> src/lib.rs:213:5
    |
213 |     buf[0] = buf[0] >> 2;
    |     ^^^^^^^^^^^^^^^^^^^^ help: replace it with: `buf[0] >>= 2`
    |
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#assign_op_pattern
    = note: `#[warn(clippy::assign_op_pattern)]` on by default

warning: the loop variable `i` is only used to index `buf`
   --> src/lib.rs:215:14
    |
215 |     for i in 1..length - 1 {
    |              ^^^^^^^^^^^^^
    |
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#needless_range_loop
    = note: `#[warn(clippy::needless_range_loop)]` on by default
help: consider using an iterator
    |
215 |     for <item> in buf.iter_mut().take(length - 1).skip(1) {
    |         ~~~~~~    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

warning: using `clone` on type `u8` which implements the `Copy` trait
   --> src/lib.rs:219:13
    |
219 |         m = c.clone();
    |             ^^^^^^^^^ help: try removing the `clone` call: `c`
    |
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#clone_on_copy
    = note: `#[warn(clippy::clone_on_copy)]` on by default

warning: manual implementation of an assign operation
   --> src/lib.rs:237:5
    |
237 |     buf[length - 1] = buf[length - 1] << 6;
    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ help: replace it with: `buf[length - 1] <<= 6`
    |
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#assign_op_pattern

warning: useless use of `vec!`
  --> src/lib.rs:54:19
   |
54 |     let mut buf = vec![0u8;10];
   |                   ^^^^^^^^^^^^ help: you can use an array directly: `[0u8; 10]`
   |
   = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#useless_vec
   = note: `#[warn(clippy::useless_vec)]` on by default

warning: `rulid` (lib) generated 12 warnings (run `cargo clippy --fix --lib -p rulid` to apply 9 suggestions)
    Finished dev [unoptimized + debuginfo] target(s) in 0.71s

Recommend Projects