Update documentation with new APIs.

bgrainger · Jul 3, 2023 · 0752fad · 0752fad
1 parent 6e78da5
commit 0752fad
Show file tree

Hide file tree

Showing 3 changed files with 64 additions and 6 deletions.
diff --git a/README.md b/README.md
@@ -5,10 +5,15 @@
 
 ## About
 
-NGuid provides efficient creation of name-based GUIDs according to [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122):
+NGuid provides efficient creation of name-based and random GUIDs according to
+[RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122)
+and the current [revision working draft](https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis):
 
 * Version 3 - created from an MD5 hash of a name
-* Version 5 (default) - created from a SHA1 hash of a name
+* Version 5 - created from a SHA1 hash of a name
+* Version 6 - a field-compatible version of UUIDv1, reordered for improved DB locality
+* Version 7 - a time-ordered value based on a Unix timestamp
+* Version 8 - an RFC-compatible format for experimental or vendor-specific use cases
 
 ## Usage
 
@@ -20,6 +25,30 @@ var guid = GuidHelpers.CreateFromName(GuidHelpers.DnsNamespace, "www.example.org
 var guidv3 = GuidHelpers.CreateFromName(GuidHelpers.DnsNamespace, "www.example.org"u8, version: 3);
 ```
 
+### Experimental
+
+The following APIs are based on the current [working draft](https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis)
+and are subject to change:
+
+```csharp
+// converts {6ba7b810-9dad-11d1-80b4-00c04fd430c8} to {1d19dad6-ba7b-6810-80b4-00c04fd430c8}
+var guidv6 = GuidHelpers.CreateVersion6FromVersion1(GuidHelpers.DnsNamespace);
+
+// creates a v7 GUID using the current time and random data 
+var guidv7 = GuidHelpers.CreateVersion7();
+
+// .NET 8 only: specify a TimeProvider to provide the timestamp
+var guidv7WithTime = GuidHelpers.CreateVersion7(TimeProvider.System);
+
+// creates a v8 GUID using the specified data
+ReadOnlySpan<byte> bytes = GetBytes();
+var guidv8 = GuidHelpers.CreateVersion8(bytes);
+
+// creates a name-based v8 GUID using the specified hash algorithm
+var guidv8ForName = GuidHelpers.CreateVersion8FromName(HashAlgorithmName.SHA256,
+ GuidHelpers.DnsNamespace, "www.example.com"u8);
+```
+
 ## License
 
 [MIT](https://github.com/bgrainger/NGuid/blob/master/LICENSE)
diff --git a/src/NGuid/NGuid.csproj b/src/NGuid/NGuid.csproj
@@ -2,9 +2,9 @@
 
  <PropertyGroup>
  <TargetFrameworks>netstandard2.0;net6.0;net8.0</TargetFrameworks>
- <Description>Creates GUIDs according to RFC 4122.</Description>
+ <Description>Creates GUIDs according to RFC 4122 and the UUID Revision Working Draft.</Description>
  <PackageReadmeFile>README.md</PackageReadmeFile>
- <PackageTags>guid;uuid;rfc4122</PackageTags>
+ <PackageTags>guid;uuid;rfc4122;uuidv6;uuidv7;uuidv8</PackageTags>
  <PackageIcon>NGuid.png</PackageIcon>
  <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
  </PropertyGroup>

diff --git a/src/NGuid/README.md b/src/NGuid/README.md
@@ -1,9 +1,14 @@
 ## NGuid
 
-NGuid provides efficient creation of name-based GUIDs according to [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122):
+NGuid provides efficient creation of name-based and random GUIDs according to
+[RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122)
+and the current [revision working draft](https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis):
 
 * Version 3 - created from an MD5 hash of a name
-* Version 5 (default) - created from a SHA1 hash of a name
+* Version 5 - created from a SHA1 hash of a name
+* Version 6 - a field-compatible version of UUIDv1, reordered for improved DB locality
+* Version 7 - a time-ordered value based on a Unix timestamp
+* Version 8 - an RFC-compatible format for experimental or vendor-specific use cases
 
 ## Usage
 
@@ -14,3 +19,27 @@ var guid = GuidHelpers.CreateFromName(GuidHelpers.DnsNamespace, "www.example.org
 // can also create "Version 3": {0012416f-9eec-3ed4-a8b0-3bceecde1cd9}
 var guidv3 = GuidHelpers.CreateFromName(GuidHelpers.DnsNamespace, "www.example.org"u8, version: 3);
 ```
+
+### Experimental
+
+The following APIs are based on the current [working draft](https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis)
+and are subject to change:
+
+```csharp
+// converts {6ba7b810-9dad-11d1-80b4-00c04fd430c8} to {1d19dad6-ba7b-6810-80b4-00c04fd430c8}
+var guidv6 = GuidHelpers.CreateVersion6FromVersion1(GuidHelpers.DnsNamespace);
+
+// creates a v7 GUID using the current time and random data 
+var guidv7 = GuidHelpers.CreateVersion7();
+
+// .NET 8 only: specify a TimeProvider to provide the timestamp
+var guidv7WithTime = GuidHelpers.CreateVersion7(TimeProvider.System);
+
+// creates a v8 GUID using the specified data
+ReadOnlySpan<byte> bytes = GetBytes();
+var guidv8 = GuidHelpers.CreateVersion8(bytes);
+
+// creates a name-based v8 GUID using the specified hash algorithm
+var guidv8ForName = GuidHelpers.CreateVersion8FromName(HashAlgorithmName.SHA256,
+ GuidHelpers.DnsNamespace, "www.example.com"u8);
+```