andrew
/
ulid-creator
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update README.md

This commit is contained in:
Fabio Lima 2022-03-01 11:16:09 -03:00 committed by GitHub
parent 8a5fc3d093
commit 236044af02
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 20 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
README.md
View File

@ -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).