From 236044af028f2fe41e91c6fc743747a79536e857 Mon Sep 17 00:00:00 2001 From: Fabio Lima Date: Tue, 1 Mar 2022 11:16:09 -0300 Subject: [PATCH] Update README.md --- README.md | 42 ++++++++++++++++++++---------------------- 1 file changed, 20 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 214b2b4..1d03f96 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,19 @@ +ULID Creator +====================================================== -# ULID Creator +This is a Java implementation of [Universally Unique Lexicographically Sortable Identifier](https://github.com/ulid/spec). -A Java library for generating [ULIDs](https://github.com/ulid/spec) (Universally Unique Lexicographically Sortable Identifier). +In summary: -* Generated in lexicographical order; +* Sorted by generation time; * Can be stored as a UUID/GUID; * Can be stored as a string of 26 chars; * Can be stored as an array of 16 bytes; * String format is encoded to [Crockford's base32](https://www.crockford.com/base32.html); -* String format is URL safe and case insensitive. +* String format is URL safe, is case insensitive, and has no hyphens. + +This library contains a good amount of [unit tests](https://github.com/f4b6a3/ulid-creator/tree/master/src/test/java/com/github/f4b6a3/ulid). It also has a [micro benchmark](https://github.com/f4b6a3/ulid-creator/tree/master/benchmark) for you to check if the performance is good enough. How to Use ------------------------------------------------------ @@ -49,18 +53,13 @@ Module and bundle names are the same as the root package name. ### ULID -The ULID is a 128 bit long identifier. The first 48 bits represent the number of milliseconds since Unix Epoch, 1970-01-01. The remaining 80 bits are generated by a secure random number generator. +The ULID is a 128 bit long identifier. The first 48 bits represent the number of milliseconds since Unix Epoch, 1970-01-01. The remaining 80 bits are generated by a secure random number generator. Its canonical string representation is 26 characters long. ```java // Generate a ULID Ulid ulid = UlidCreator.getUlid(); ``` -```java -// Generate a ULID with a specific time -Ulid ulid = UlidCreator.getUlid(1234567890); -``` - Sequence of ULIDs: ```text @@ -88,20 +87,13 @@ Sequence of ULIDs: ### Monotonic ULID -The Monotonic ULID is a 128 bit long identifier. The first 48 bits represent the number of milliseconds since Unix Epoch, 1970-01-01. The remaining 80 bits are generated by a secure random number generator. - -The random component is incremented by 1 whenever the current millisecond is equal to the previous one. But when the current millisecond is different, the random component changes to another random value. +The Monotonic ULID is variant of ULID. The random component is incremented by 1 whenever the current millisecond is equal to the previous one. Its main advantage is *speed*. ```java // Generate a Monotonic ULID Ulid ulid = UlidCreator.getMonotonicUlid(); ``` -```java -// Generate a Monotonic ULID with a specific time -Ulid ulid = UlidCreator.getMonotonicUlid(1234567890); -``` - Sequence of Monotonic ULIDs: ```text @@ -233,8 +225,10 @@ THROUGHPUT (operations/msec) Mode Cnt Score Error Units -------------------------------------------------------------------------------- UUID_randomUUID thrpt 5 2060,570 ± 37,242 ops/ms UUID_randomUUID_toString thrpt 5 1177,386 ± 39,803 ops/ms +- - - - - - - - - - - - - - - - - - - - - - - - - - - UlidCreator_getUlid thrpt 5 2740,609 ± 86,350 ops/ms UlidCreator_getUlid_toString thrpt 5 2526,284 ± 56,726 ops/ms +- - - - - - - - - - - - - - - - - - - - - - - - - - - UlidCreator_getMonotonicUlid thrpt 5 19373,150 ± 192,402 ops/ms UlidCreator_getMonotonicUlid_toString thrpt 5 13269,201 ± 254,953 ops/ms -------------------------------------------------------------------------------- @@ -249,9 +243,13 @@ To execute the benchmark, run `./benchmark/run.sh`. Other identifier generators ------------------------------------------- -Check out the other ID generators. +Check out the other ID generators from the same family: -* [UUID Creator](https://github.com/f4b6a3/uuid-creator) -* [TSID Creator](https://github.com/f4b6a3/tsid-creator) -* [KSUID Creator](https://github.com/f4b6a3/ksuid-creator) +* [UUID Creator](https://github.com/f4b6a3/uuid-creator): Universally Unique Identifiers +* [TSID Creator](https://github.com/f4b6a3/tsid-creator): Time Sortable Identifiers +* [KSUID Creator](https://github.com/f4b6a3/ksuid-creator): K-Sortable Globally Unique Identifiers +License +------------------------------------------------------ + +This library is Open Source software released under the [MIT license](https://opensource.org/licenses/MIT).