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 UUID/GUID;
* Can be stored as a string of 26 chars; * Can be stored as a string of 26 chars;
* Can be stored as an array of 16 bytes; * 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 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 How to Use
------------------------------------------------------ ------------------------------------------------------
@ -49,18 +53,13 @@ Module and bundle names are the same as the root package name.
### ULID ### 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 ```java
// Generate a ULID // Generate a ULID
Ulid ulid = UlidCreator.getUlid(); Ulid ulid = UlidCreator.getUlid();
``` ```
```java
// Generate a ULID with a specific time
Ulid ulid = UlidCreator.getUlid(1234567890);
```
Sequence of ULIDs: Sequence of ULIDs:
```text ```text
@ -88,20 +87,13 @@ Sequence of ULIDs:
### Monotonic ULID ### 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 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*.
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.
```java ```java
// Generate a Monotonic ULID // Generate a Monotonic ULID
Ulid ulid = UlidCreator.getMonotonicUlid(); Ulid ulid = UlidCreator.getMonotonicUlid();
``` ```
```java
// Generate a Monotonic ULID with a specific time
Ulid ulid = UlidCreator.getMonotonicUlid(1234567890);
```
Sequence of Monotonic ULIDs: Sequence of Monotonic ULIDs:
```text ```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 thrpt 5 2060,570 ± 37,242 ops/ms
UUID_randomUUID_toString thrpt 5 1177,386 ± 39,803 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 thrpt 5 2740,609 ± 86,350 ops/ms
UlidCreator_getUlid_toString thrpt 5 2526,284 ± 56,726 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 thrpt 5 19373,150 ± 192,402 ops/ms
UlidCreator_getMonotonicUlid_toString thrpt 5 13269,201 ± 254,953 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 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) * [UUID Creator](https://github.com/f4b6a3/uuid-creator): Universally Unique Identifiers
* [TSID Creator](https://github.com/f4b6a3/tsid-creator) * [TSID Creator](https://github.com/f4b6a3/tsid-creator): Time Sortable Identifiers
* [KSUID Creator](https://github.com/f4b6a3/ksuid-creator) * [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).