Rewrite docs #73

Author: fabiolimace

.gitignore

@@ -46,4 +46,6 @@ hs_err_pid*
 
 notes/*
 
+docs/javadoc/*
+
 

CHANGELOG.md

@@ -6,6 +6,9 @@ All notable changes to this project will be documented in this file.
 
 Nothing unreleased.
 
+## [5.1.2] - 2022-09-11
+
+Rewrite docs. #73
 
 ## [5.1.1] - 2022-08-21
 
@@ -343,7 +346,8 @@ Remove `Fingerprint` // too complex
 -   Removed UuidSettings.getNodeIdentifierDeprecated // remove deprecated
 -   Renamed UuidSettings to UuidCreatorSettings
 
-[unreleased]: https://github.com/f4b6a3/uuid-creator/compare/uuid-creator-5.1.1...HEAD
+[unreleased]: https://github.com/f4b6a3/uuid-creator/compare/uuid-creator-5.1.2...HEAD
+[5.1.2]: https://github.com/f4b6a3/uuid-creator/compare/uuid-creator-5.1.1...uuid-creator-5.1.2
 [5.1.1]: https://github.com/f4b6a3/uuid-creator/compare/uuid-creator-5.1.0...uuid-creator-5.1.1
 [5.1.0]: https://github.com/f4b6a3/uuid-creator/compare/uuid-creator-5.0.0...uuid-creator-5.1.0
 [5.0.0]: https://github.com/f4b6a3/uuid-creator/compare/uuid-creator-4.6.1...uuid-creator-5.0.0

README.md

@@ -1,29 +1,32 @@
 
+
 UUID Creator
 ======================================================
 
-This is a Java library for [RFC-4122 Universally Unique Identifiers](https://en.wikipedia.org/wiki/Universally_unique_identifier).
+This is a Java library for generating [Universally Unique Identifiers](https://en.wikipedia.org/wiki/Universally_unique_identifier).
+
+UUIDs:
 
-RFC-4122 UUIDs:
+*   __UUID Version 1__: the time-based version with gregorian epoch specified in RFC-4122;
+*   __UUID Version 2__: the DCE Security version with embedded POSIX UIDs specified in DCE 1.1;
+*   __UUID Version 3__: the name-based version that uses MD5 hashing specified in RFC-4122;
+*   __UUID Version 4__: the randomly or pseudo-randomly generated version specified in RFC-4122;
+*   __UUID Version 5__: the name-based version that uses SHA-1 hashing specified in RFC-4122;
+*   __UUID Version 6__: the time-ordered version with gregorian epoch proposed as [new UUID format](https://github.com/uuid6/uuid6-ietf-draft);
+*   __UUID Version 7__: the time-ordered version with Unix epoch proposed as [new UUID format](https://github.com/uuid6/uuid6-ietf-draft).
 
-*   __Version 1__: Time-based;
-*   __Version 2__: DCE Security;
-*   __Version 3__: Name-based with MD5;
-*   __Version 4__: Random-based;
-*   __Version 5__: Name-based with SHA1;
-*   __Version 6__: Time-ordered ([IETF draft](https://github.com/uuid6/uuid6-ietf-draft));
-*   __Version 7__: Time-ordered with Unix Epoch ([IETF draft](https://github.com/uuid6/uuid6-ietf-draft)).
+COMB GUIDs:
 
-Non-standard GUIDs:
+*   __Prefix COMB GUID__: a combination of random bytes with a prefix (millisecond);
+*   __Suffix COMB GUID__: a combination of random bytes with a suffix (millisecond);
+*   __Short Prefix COMB GUID__: a combination of random bytes with a small prefix (minute);
+*   __Short Suffix COMB GUID__: a combination of random bytes with a small suffix (minute).
 
-*   __Prefix COMB__: combination of the creation millisecond (prefix) with random bytes;
-*   __Suffix COMB__: combination of the creation millisecond (suffix) with random bytes;
-*   __Short Prefix COMB__: combination the creation minute (prefix) with random bytes;
-*   __Short Suffix COMB__: combination the creation minute (suffix) with random bytes.
+This project contains a [micro benchmark](https://github.com/f4b6a3/uuid-creator/tree/master/benchmark) and a good amount of [unit tests](https://github.com/f4b6a3/uuid-creator/tree/master/src/test/java/com/github/f4b6a3/uuid).
 
-This library contains a good amount of [unit tests](https://github.com/f4b6a3/uuid-creator/tree/master/src/test/java/com/github/f4b6a3/uuid). It also has a [micro benchmark](https://github.com/f4b6a3/uuid-creator/tree/master/benchmark) for you to check if the performance is good enough.
+The jar file can be downloaded directly from [maven.org](https://repo1.maven.org/maven2/com/github/f4b6a3/uuid-creator/).
 
-Read the [Wiki pages](https://github.com/f4b6a3/uuid-creator/wiki).
+Read the [Wiki pages](https://github.com/f4b6a3/uuid-creator/wiki) and the [Javadocs](https://javadoc.io/doc/com.github.f4b6a3/uuid-creator).
 
 Maven dependency
 ------------------------------------------------------
@@ -35,7 +38,7 @@ Add these lines to your `pom.xml`:
 <dependency>
   <groupId>com.github.f4b6a3</groupId>
   <artifactId>uuid-creator</artifactId>
-  <version>5.1.1</version>
+  <version>5.1.2</version>
 </dependency>
 ```
 See more options in [maven.org](https://search.maven.org/artifact/com.github.f4b6a3/uuid-creator).
@@ -50,242 +53,74 @@ Module and bundle names are the same as the root package name.
 How to Use
 ------------------------------------------------------
 
-### Library Facade
+All UUID types can be created from the facade [`UuidCreator`](https://github.com/f4b6a3/uuid-creator/blob/master/src/main/java/com/github/f4b6a3/uuid/UuidCreator.java).
 
-Create a [Random-based](https://github.com/f4b6a3/uuid-creator/wiki/1.4.-Random-based) UUID:
+Create a [Random-based](https://github.com/f4b6a3/uuid-creator/wiki/1.4.-Random-based) unique identifier (UUIDv4):
 
 ```java
 UUID uuid = UuidCreator.getRandomBased();
 ```
 
-Create a [Time-based](https://github.com/f4b6a3/uuid-creator/wiki/1.1.-Time-based) UUID:
+Create a [Time-based](https://github.com/f4b6a3/uuid-creator/wiki/1.1.-Time-based) unique identifier (UUIDv1):
 
 ```java
 UUID uuid = UuidCreator.getTimeBased();
 ```
 
-Create a [Time-ordered](https://github.com/f4b6a3/uuid-creator/wiki/1.6.-Time-ordered) UUID:
+Create a [Time-ordered](https://github.com/f4b6a3/uuid-creator/wiki/1.6.-Time-ordered) unique identifier (UUIDv6):
 
 ```java
 UUID uuid = UuidCreator.getTimeOrdered();
 ```
 
-Create a [Time-ordered with Unix Epoch](https://github.com/f4b6a3/uuid-creator/wiki/1.7.-Time-ordered-epoch) UUID:
+Create a [Time-ordered with Unix Epoch](https://github.com/f4b6a3/uuid-creator/wiki/1.7.-Time-ordered-epoch) unique identifier (UUIDv7)
 
 ```java
 UUID uuid = UuidCreator.getTimeOrderedEpoch();
 ```
 
-Create a [Name-based with MD5](https://github.com/f4b6a3/uuid-creator/wiki/1.3.-Name-based-with-MD5) UUID:
+Create a [Name-based with MD5](https://github.com/f4b6a3/uuid-creator/wiki/1.3.-Name-based-with-MD5) unique identifier (UUIDv3)
 
 ```java
-String name = "https://github.com/";
-UUID uuid = UuidCreator.getNameBasedMd5(UuidNamespace.NAMESPACE_URL, name);
+UUID uuid = UuidCreator.getNameBasedMd5(UuidNamespace.NAMESPACE_URL, "https://github.com/");
 ```
 
-Create a [Name-based with SHA-1](https://github.com/f4b6a3/uuid-creator/wiki/1.5.-Name-based-with-SHA-1) UUID:
+Create a [Name-based with SHA-1](https://github.com/f4b6a3/uuid-creator/wiki/1.5.-Name-based-with-SHA-1) unique identifier (UUIDv5)
 
 ```java
-String name = "https://github.com/";
-UUID uuid = UuidCreator.getNameBasedSha1(UuidNamespace.NAMESPACE_URL, name);
+UUID uuid = UuidCreator.getNameBasedSha1(UuidNamespace.NAMESPACE_URL, "https://github.com/");
 ```
 
-Create a [DCE Security](https://github.com/f4b6a3/uuid-creator/wiki/1.2.-DCE-Security) UUID:
+Create a [DCE Security](https://github.com/f4b6a3/uuid-creator/wiki/1.2.-DCE-Security) unique identifier (UUIDv2)
 
 ```java
-int localIdentifier = 1701;
-UUID uuid = UuidCreator.getDceSecurity(UuidLocalDomain.LOCAL_DOMAIN_PERSON, localIdentifier);
+UUID uuid = UuidCreator.getDceSecurity(UuidLocalDomain.LOCAL_DOMAIN_PERSON, 1234);
 ```
 
-Create a [Prefix COMB](https://github.com/f4b6a3/uuid-creator/wiki/2.1.-Prefix-COMB) GUID:
+Create a [Prefix COMB GUID](https://github.com/f4b6a3/uuid-creator/wiki/2.1.-Prefix-COMB):
 
 ```java
 UUID uuid = UuidCreator.getPrefixComb();
 ```
 
-Create a [Suffix COMB](https://github.com/f4b6a3/uuid-creator/wiki/2.2.-Suffix-COMB) GUID:
+Create a [Suffix COMB GUID](https://github.com/f4b6a3/uuid-creator/wiki/2.2.-Suffix-COMB):
 
 ```java
 UUID uuid = UuidCreator.getSuffixComb();
 ```
 
-Create a [Short Prefix COMB](https://github.com/f4b6a3/uuid-creator/wiki/2.3.-Short-Prefix-COMB) GUID:
+Create a [Short Prefix COMB GUID](https://github.com/f4b6a3/uuid-creator/wiki/2.3.-Short-Prefix-COMB):
 
 ```java
 UUID uuid = UuidCreator.getShortPrefixComb();
 ```
 
-Create a [Short Suffix COMB](https://github.com/f4b6a3/uuid-creator/wiki/2.4.-Short-Suffix-COMB) GUID:
+Create a [Short Suffix COMB GUID](https://github.com/f4b6a3/uuid-creator/wiki/2.4.-Short-Suffix-COMB):
 
 ```java
 UUID uuid = UuidCreator.getShortSuffixComb();
 ```
 
-### Library Utilities
-
-This library provides many utilities for validation, version checking, information extraction, etc.
-
-Validate a UUID string:
-
-```java
-UuidValidator.isValid(uuid);
-UuidValidator.validate(uuid); // Throws an exception if INVALID
-```
-
-Check  the version of UUID:
-
-```java
-UuidUtil.isTimeBased(uuid);
-UuidUtil.isTimeOrdered(uuid);
-UuidUtil.isRandomBased(uuid);
-```
-Extract information from a UUID:
-
-```java
-Instant instant = UuidUtil.getInstant(uuid);
-int clocksq = UuidUtil.getClockSequence(uuid);
-long nodeid = UuidUtil.getNodeIdentifier(uuid);
-UuidVersion version = UuidUtil.getVersion(uuid);
-UuidVariant variant = UuidUtil.getVariant(uuid);
-```
-
-Extract information from a COMB GUID:
-
-```java
-long prefix = UuidUtil.getPrefix(comb); // Unix milliseconds
-long suffix = UuidUtil.getSuffix(comb); // Unix milliseconds
-Instant instant = UuidUtil.getPrefixInstant(comb);
-Instant instant = UuidUtil.getSuffixInstant(comb);
-```
-
-Get the machine ID:
-
-```java
-long id = MachineId.getMachineId(); // 0x7bc3cfd7844f46ad (8918200211668420269)
-UUID uuid = MachineId.getMachineUuid(); // 7bc3cfd7-844f-46ad-81a9-1aa22d3c427a
-```
-
-### Library Codecs
-
-This library also provides many codecs for canonical string, byte array, base-n, slugs, etc.
-
-#### Main codecs
-
-Convert a UUID to and from [byte array](https://github.com/f4b6a3/uuid-creator/wiki/4.0.-Library-codecs#binarycodec):
-
-```java
-UUID uuid = BinaryCodec.INSTANCE.decode(/* 16 bytes */);
-byte[] bytes = BinaryCodec.INSTANCE.encode(uuid);
-```
-Convert a UUID to and from [canonical string](https://github.com/f4b6a3/uuid-creator/wiki/4.0.-Library-codecs#stringcodec):
-
-```java
-// 7x faster than `UUID.fromString()` and `UUID.toString()`
-UUID uuid = StringCodec.INSTANCE.decode("01234567-89ab-4def-a123-456789abcdef");
-String string = StringCodec.INSTANCE.encode(uuid);
-```
-
-Convert a UUID to and from [URI](https://github.com/f4b6a3/uuid-creator/wiki/4.0.-Library-codecs#uricodec):
-
-```java
-UUID uuid = UriCodec.INSTANCE.decode("urn:uuid:01234567-89ab-4def-a123-456789abcdef");
-URI uri = UriCodec.INSTANCE.encode(uuid);
-```
-
-#### Base-N codecs
-
-There are base-n codecs for base-16, base-32, base-58, base-62 and base-64.
-
-Custom codecs can be instantiated with `BaseNCodec.newInstance(int|String)`.
-
-Convert a UUID to and from [base-n](https://github.com/f4b6a3/uuid-creator/wiki/4.0.-Library-codecs#base-n-codecs):
-
-```java
-// 22x faster than `UUID.toString().replaceAll("-", "")`
-UUID uuid = Base16Codec.INSTANCE.decode("0123456789ab4defa123456789abcdef");
-String string = Base16Codec.INSTANCE.encode(uuid);
-```
-
-```java
-UUID uuid = Base32Codec.INSTANCE.decode("aerukz4jvng67ijdivtytk6n54");
-String string = Base32Codec.INSTANCE.encode(uuid);
-```
-
-```java
-UUID uuid = Base58BtcCodec.INSTANCE.decode("199dn6s7UNiX3LyNkQ1Cfx");
-String string = Base58BtcCodec.INSTANCE.encode(uuid);
-```
-
-```java
-UUID uuid = Base62Codec.INSTANCE.decode("0296tiiBY28FKCYq1PVSGd");
-String string = Base62Codec.INSTANCE.encode(uuid);
-```
-
-```java
-UUID uuid = Base64UrlCodec.INSTANCE.decode("ASNFZ4mrTe-hI0VniavN7w");
-String string = Base64UrlCodec.INSTANCE.encode(uuid);
-```
-
-Convert a UUID to and from a *custom* base-n:
-
-```java
-// a base-20 string using a CUSTOM radix (20)
-int radix = 20; // expanded to "0123456789abcdefghij"
-BaseNCodec codec = BaseNCodec.newInstance(radix);
-
-UUID uuid = codec.decode("00b5740h195313554732654bjhj9e7");
-String string = codec.encode(uuid);
-```
-
-```java
-// a base-10 string using a CUSTOM alphabet ("0-9")
-String alphabet = "0-9"; // expanded to "0123456789"
-BaseNCodec codec = BaseNCodec.newInstance(alphabet);
-
-UUID uuid = codec.decode("001512366075203566477668990085887675887");
-String string = codec.encode(uuid);
-```
-
-Using a fast division library to boost encoding speed:
-
-```java
-// a base-62 codec using a fast division library, i.e., `libdivide`
-CustomDivider divider = x -> {
-    /* my division code here */
-    return new long[] { quotient, remainder };
-};
-BaseNCodec codec = BaseNCodec.newInstance(62, divider);
-```
-
-#### Other codecs
-
-Convert a UUID to and from [Slug](https://github.com/f4b6a3/uuid-creator/wiki/4.0.-Library-codecs#slugcodec):
-
-```java
-UUID uuid = SlugCodec.INSTANCE.decode("SgEjRWeJq97xI0VniavN7w");
-String string = SlugCodec.INSTANCE.encode(uuid);
-```
-
-Convert a UUID to and from [NCName](https://github.com/f4b6a3/uuid-creator/wiki/4.0.-Library-codecs#ncnamecodec):
-
-```java
-UUID uuid = NcnameCodec.INSTANCE.decode("EASNFZ4mr3vEjRWeJq83vK");
-String string = NcnameCodec.INSTANCE.encode(uuid);
-```
-
-Convert a UUID to and from [.Net Guid](https://github.com/f4b6a3/uuid-creator/wiki/4.0.-Library-codecs#dotnetguid1codec-and-dotnetguid4codec):
-
-```java
-// Convert time-based (version 1) to .Net Guid
-UUID guid = DotNetGuid1Codec.INSTANCE.encode(uuid);
-UUID uuid = DotNetGuid1Codec.INSTANCE.decode(guid);
-```
-```java
-// Convert random-based (version 4) to .Net Guid
-UUID guid = DotNetGuid4Codec.INSTANCE.encode(uuid);
-UUID uuid = DotNetGuid4Codec.INSTANCE.encode(guid);
-```
-
 Other identifier generators
 ------------------------------------------------------
 
@@ -299,3 +134,4 @@ License
 ------------------------------------------------------
 
 This library is Open Source software released under the [MIT license](https://opensource.org/licenses/MIT).
+

benchmark/README.md

@@ -1 +1,4 @@
 To execute the benchmark, run the script `./benchmark/run.sh`.
+
+See the [benchmark page in the Wiki](https://github.com/f4b6a3/uuid-creator/wiki/5.0.-Benchmark).
+

benchmark/src/main/java/benchmark/Throughput.java

@@ -23,11 +23,11 @@
 //import com.github.f4b6a3.uuid.codec.base.Base64UrlCodec;
 
 @Fork(1)
-@Threads(1)
+@Threads(4)
 @State(Scope.Benchmark)
+@BenchmarkMode(Mode.Throughput)
 @Warmup(iterations = 5, time = 1)
 @Measurement(iterations = 5, time = 3)
-@BenchmarkMode(Mode.Throughput)
 @OutputTimeUnit(TimeUnit.MILLISECONDS)
 public class Throughput {