diff --git a/README.md b/README.md index ea8497a..e67bd2d 100644 --- 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 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 index 6a4b4f4..11015a0 100644 --- a/src/NGuid/NGuid.csproj +++ b/src/NGuid/NGuid.csproj @@ -2,9 +2,9 @@ netstandard2.0;net6.0;net8.0 - Creates GUIDs according to RFC 4122. + Creates GUIDs according to RFC 4122 and the UUID Revision Working Draft. README.md - guid;uuid;rfc4122 + guid;uuid;rfc4122;uuidv6;uuidv7;uuidv8 NGuid.png true diff --git a/src/NGuid/README.md b/src/NGuid/README.md index a190d02..e3f41a3 100644 --- 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 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); +```