Changed ToVariant1 to ToRfc4122Variant for clarity.

amsga · amsga · commit a8e43b131f46 · 2026-01-30T23:30:54.000+08:00
Changed ToVariant2 to ToMicrosoftVariant for clarity.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [v2.4.0] - 2026-01-30
+[v2.4.0](https://github.com/TensionDev/UUIDUtil/releases/tag/v2.4.0)
+
+### Changed
+- Changed ToVariant1 to ToRfc4122Variant for clarity.
+- Changed ToVariant2 to ToMicrosoftVariant for clarity.
+
+
 ## [v2.3.1] - 2025-07-01
 [v2.3.1](https://github.com/TensionDev/UUIDUtil/releases/tag/v2.3.1)
 
diff --git a/README.md b/README.md
@@ -1,12 +1,98 @@
-# TensionDev.UUID
+﻿# TensionDev.UUID
 
 [![.NET](https://github.com/TensionDev/UUIDUtil/actions/workflows/dotnet.yml/badge.svg)](https://github.com/TensionDev/UUIDUtil/actions/workflows/dotnet.yml)
 [![Package Release](https://github.com/TensionDev/UUIDUtil/actions/workflows/package-release.yml/badge.svg)](https://github.com/TensionDev/UUIDUtil/actions/workflows/package-release.yml)
 [![CodeQL](https://github.com/TensionDev/UUIDUtil/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/TensionDev/UUIDUtil/actions/workflows/github-code-scanning/codeql)
 
-A project to store UUID functions within a library for future use.  
+TensionDev.UUID is a .NET library for working with Universally Unique Identifiers (UUIDs). 
 This project references the following documents for implementation.  
 - [Universally unique identifier - Wikipedia](https://en.wikipedia.org/wiki/Universally_unique_identifier)
 - [MySQL :: MySQL 8.0 Reference Manual :: 12.24 Miscellaneous Functions](https://dev.mysql.com/doc/refman/8.0/en/miscellaneous-functions.html#function_uuid)
 - [rfc4122](https://datatracker.ietf.org/doc/html/rfc4122)
 - [rfc9562](https://datatracker.ietf.org/doc/html/rfc9562)
+
+---
+
+## Features  
+
+- Support for multiple UUID versions:  
+  - v1 (date-time and MAC address)  
+  - v3 (MD5 namespace name-based)  
+  - v4 (random)  
+  - v5 (SHA-1 namespace name-based)  
+  - v6 (date-time-ordered)  
+  - v7 (Unix time + randomness)  
+- Converters:  
+  - `ToGuid()` and `FromGuid(Guid)`  
+  - `ToByteArray()` and `FromBytes(byte[])`  
+  - Variant conversions (`ToVariant1`, `ToVariant2`)  
+- Parsing utilities:  
+  - `Parse(string)`  
+  - `TryParse(string, out Uuid)`  
+- Formatting options:  
+  - `N`, `D`, `B`, `P` (same as System.Guid)  
+- Comparison operators:  
+  - `==`, `!=`, `<`, `>`, `<=`, `>=`  
+- Equality and hashing for dictionary/set usage  
+- Strict RFC compliance for parsing and validation  
+
+---
+
+## Installation
+```
+dotnet add package TensionDev.UUID
+```
+
+---
+
+## Usage Examples
+
+### Generate UUID v1 (date-time and MAC address)
+```csharp
+using TensionDev.UUID;
+
+Uuid uuid = UUIDv1.NewUUIDv1();
+Console.WriteLine(uuid); // Example: 164a714c-0c79-11ec-82a8-0242ac130003
+```
+
+### Generate UUID v4 (random)
+```csharp
+using TensionDev.UUID;
+
+Uuid uuid = UUIDv4.NewUUIDv4();
+Console.WriteLine(uuid); // Example: 550e8400-e29b-41d4-a716-446655440000
+```
+
+### Generate UUID v5 (SHA-1 namespace name-based)
+```csharp
+using TensionDev.UUID;
+
+Uuid uuid = UUIDv5.NewUUIDv5(UUIDNamespace.URL, "https://www.contoso.com");
+Console.WriteLine(uuid); // Example: 1bf6935b-49e6-54cf-a9c8-51fb21c41b46
+```
+
+### Parse and validate
+```csharp
+using TensionDev.UUID;
+
+bool isValid = Uuid.TryParse("550e8400-e29b-41d4-a716-446655440000", out var parsed);
+```
+
+### Byte Conversions
+```csharp
+using TensionDev.UUID;
+
+byte[] bytes = uuid.ToByteArray();
+Uuid fromBytes = Uuid.FromBytes(bytes);
+```
+
+### String Formatting
+```csharp
+using TensionDev.UUID;
+
+Console.WriteLine(uuid.ToString("N")); // 32 hex digits
+Console.WriteLine(uuid.ToString("D")); // canonical form
+Console.WriteLine(uuid.ToString("B")); // with braces
+Console.WriteLine(uuid.ToString("P")); // with parentheses
+```
+
diff --git a/UUIDUtil/UUIDNamespace.cs b/UUIDUtil/UUIDNamespace.cs
@@ -1,6 +1,6 @@
 ﻿// SPDX-License-Identifier: Apache-2.0
 //
-//   Copyright 2021 TensionDev <TensionDev@outlook.com>
+//   Copyright 2021 - 2026 TensionDev <TensionDev@outlook.com>
 //
 //   Licensed under the Apache License, Version 2.0 (the "License");
 //   you may not use this file except in compliance with the License.
diff --git a/UUIDUtil/UUIDUtil.csproj b/UUIDUtil/UUIDUtil.csproj
@@ -10,12 +10,12 @@
     <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
     <PackageRequireLicenseAcceptance>true</PackageRequireLicenseAcceptance>
     <PackageId>TensionDev.UUID</PackageId>
-    <Version>2.3.1</Version>
+    <Version>2.4.0</Version>
     <Authors>TensionDev amsga</Authors>
     <Company>TensionDev</Company>
     <Product>TensionDev.UUID</Product>
-    <Description>A project to store various UUID functions within a library for future use.</Description>
-    <Copyright>Copyright (c) TensionDev 2021</Copyright>
+    <Description>TensionDev.UUID is a .NET library that supports multiple UUID versions (v1, v3, v4, v5, v6, v7) with strict RFC compliance.</Description>
+    <Copyright>Copyright (c) TensionDev 2021 - 2026</Copyright>
     <PackageLicenseExpression>Apache-2.0</PackageLicenseExpression>
     <PackageProjectUrl>https://github.com/TensionDev/UUIDUtil</PackageProjectUrl>
     <RepositoryUrl>https://github.com/TensionDev/UUIDUtil</RepositoryUrl>
diff --git a/UUIDUtil/UUIDv1.cs b/UUIDUtil/UUIDv1.cs
@@ -1,6 +1,6 @@
 ﻿// SPDX-License-Identifier: Apache-2.0
 //
-//   Copyright 2021 TensionDev <TensionDev@outlook.com>
+//   Copyright 2021 - 2026 TensionDev <TensionDev@outlook.com>
 //
 //   Licensed under the Apache License, Version 2.0 (the "License");
 //   you may not use this file except in compliance with the License.
diff --git a/UUIDUtil/UUIDv3.cs b/UUIDUtil/UUIDv3.cs
@@ -1,6 +1,6 @@
 ﻿// SPDX-License-Identifier: Apache-2.0
 //
-//   Copyright 2021 TensionDev <TensionDev@outlook.com>
+//   Copyright 2021 - 2026 TensionDev <TensionDev@outlook.com>
 //
 //   Licensed under the Apache License, Version 2.0 (the "License");
 //   you may not use this file except in compliance with the License.
diff --git a/UUIDUtil/UUIDv4.cs b/UUIDUtil/UUIDv4.cs
@@ -1,6 +1,6 @@
 ﻿// SPDX-License-Identifier: Apache-2.0
 //
-//   Copyright 2021 TensionDev <TensionDev@outlook.com>
+//   Copyright 2021 - 2026 TensionDev <TensionDev@outlook.com>
 //
 //   Licensed under the Apache License, Version 2.0 (the "License");
 //   you may not use this file except in compliance with the License.
diff --git a/UUIDUtil/UUIDv5.cs b/UUIDUtil/UUIDv5.cs
@@ -1,6 +1,6 @@
 ﻿// SPDX-License-Identifier: Apache-2.0
 //
-//   Copyright 2021 TensionDev <TensionDev@outlook.com>
+//   Copyright 2021 - 2026 TensionDev <TensionDev@outlook.com>
 //
 //   Licensed under the Apache License, Version 2.0 (the "License");
 //   you may not use this file except in compliance with the License.
diff --git a/UUIDUtil/UUIDv6.cs b/UUIDUtil/UUIDv6.cs
@@ -1,6 +1,6 @@
 ﻿// SPDX-License-Identifier: Apache-2.0
 //
-//   Copyright 2021 TensionDev <TensionDev@outlook.com>
+//   Copyright 2021 - 2026 TensionDev <TensionDev@outlook.com>
 //
 //   Licensed under the Apache License, Version 2.0 (the "License");
 //   you may not use this file except in compliance with the License.
diff --git a/UUIDUtil/UUIDv7.cs b/UUIDUtil/UUIDv7.cs
@@ -1,6 +1,6 @@
 ﻿// SPDX-License-Identifier: Apache-2.0
 //
-//   Copyright 2021 TensionDev <TensionDev@outlook.com>
+//   Copyright 2021 - 2026 TensionDev <TensionDev@outlook.com>
 //
 //   Licensed under the Apache License, Version 2.0 (the "License");
 //   you may not use this file except in compliance with the License.
diff --git a/UUIDUtil/Uuid.cs b/UUIDUtil/Uuid.cs
@@ -1,6 +1,6 @@
 ﻿// SPDX-License-Identifier: Apache-2.0
 //
-//   Copyright 2021 TensionDev <TensionDev@outlook.com>
+//   Copyright 2021 - 2026 TensionDev <TensionDev@outlook.com>
 //
 //   Licensed under the Apache License, Version 2.0 (the "License");
 //   you may not use this file except in compliance with the License.
@@ -26,7 +26,9 @@ namespace TensionDev.UUID
     public sealed class Uuid : IComparable<Uuid>, IEquatable<Uuid>
     {
         private const string INVALID_FORMAT_STRING = "The format of s is invalid";
-        private const string HEX_FORMAT_STRING = "{0:x2}";
+        private const string ONE_BYTE_HEX_FORMAT_STRING = "{0:x2}";
+        private const string TWO_BYTE_HEX_FORMAT_STRING = "{0:x4}";
+        private const string FOUR_BYTE_HEX_FORMAT_STRING = "{0:x8}";
         private readonly uint _time_low;
         private readonly ushort _time_mid;
         private readonly ushort _time_hi_and_version;
@@ -71,9 +73,9 @@ public Uuid(byte[] b) : this()
             if (b.Length != 16)
                 throw new ArgumentException("b is not 16 bytes long.", nameof(b));
 
-            _time_low = BitConverter.ToUInt32(b, 0);
-            _time_mid = BitConverter.ToUInt16(b, 4);
-            _time_hi_and_version = BitConverter.ToUInt16(b, 6);
+            _time_low = (uint)(b[0] << 24 | b[1] << 16 | b[2] << 8 | b[3]);
+            _time_mid = (ushort)(b[4] << 8 | b[5]);
+            _time_hi_and_version = (ushort)(b[6] << 8 | b[7]);
             _clock_seq_hi_and_reserved = b[8];
             _clock_seq_low = b[9];
             Array.Copy(b, 10, _node, 0, _node.Length);
@@ -139,9 +141,9 @@ public Uuid(string s) : this()
                 }
             }
 
-            _time_low = BitConverter.ToUInt32(b, 0);
-            _time_mid = BitConverter.ToUInt16(b, 4);
-            _time_hi_and_version = BitConverter.ToUInt16(b, 6);
+            _time_low = (uint)(b[0] << 24 | b[1] << 16 | b[2] << 8 | b[3]);
+            _time_mid = (ushort)(b[4] << 8 | b[5]);
+            _time_hi_and_version = (ushort)(b[6] << 8 | b[7]);
             _clock_seq_hi_and_reserved = b[8];
             _clock_seq_low = b[9];
             Array.Copy(b, 10, _node, 0, _node.Length);
@@ -166,9 +168,9 @@ public Uuid(uint a, ushort b, ushort c, byte d, byte e, byte[] f) : this()
             if (f.Length != 6)
                 throw new ArgumentException("f is not 6 bytes long");
 
-            _time_low = (uint)System.Net.IPAddress.HostToNetworkOrder((int)a);
-            _time_mid = (ushort)System.Net.IPAddress.HostToNetworkOrder((Int16)b);
-            _time_hi_and_version = (ushort)System.Net.IPAddress.HostToNetworkOrder((Int16)c);
+            _time_low = a;
+            _time_mid = b;
+            _time_hi_and_version = c;
             _clock_seq_hi_and_reserved = d;
             _clock_seq_low = e;
             f.CopyTo(_node, 0);
@@ -190,9 +192,9 @@ public Uuid(uint a, ushort b, ushort c, byte d, byte e, byte[] f) : this()
         /// <param name="k">The next byte of the Uuid.</param>
         public Uuid(uint a, ushort b, ushort c, byte d, byte e, byte f, byte g, byte h, byte i, byte j, byte k) : this()
         {
-            _time_low = (uint)System.Net.IPAddress.HostToNetworkOrder((int)a);
-            _time_mid = (ushort)System.Net.IPAddress.HostToNetworkOrder((Int16)b);
-            _time_hi_and_version = (ushort)System.Net.IPAddress.HostToNetworkOrder((Int16)c);
+            _time_low = a;
+            _time_mid = b;
+            _time_hi_and_version = c;
             _clock_seq_hi_and_reserved = d;
             _clock_seq_low = e;
             _node[0] = f;
@@ -203,12 +205,6 @@ public Uuid(uint a, ushort b, ushort c, byte d, byte e, byte f, byte g, byte h,
             _node[5] = k;
         }
 
-        //
-        // Summary:
-        //     Initializes a new instance of the Uuid object.
-        //
-        // Returns:
-        //     A new Uuid object.
         /// <summary>
         /// Initializes a new instance of the Uuid object.
         /// </summary>
@@ -344,12 +340,19 @@ public byte[] ToByteArray()
         {
             Byte[] vs = new Byte[16];
 
-            BitConverter.GetBytes(_time_low).CopyTo(vs, 0);
-            BitConverter.GetBytes(_time_mid).CopyTo(vs, 4);
-            BitConverter.GetBytes(_time_hi_and_version).CopyTo(vs, 6);
-            BitConverter.GetBytes(_clock_seq_hi_and_reserved).CopyTo(vs, 8);
-            BitConverter.GetBytes(_clock_seq_low).CopyTo(vs, 9);
-            _node.CopyTo(vs, 10);
+            vs[0] = (Byte)(_time_low >> 24);
+            vs[1] = (Byte)(_time_low >> 16);
+            vs[2] = (Byte)(_time_low >> 8);
+            vs[3] = (Byte)(_time_low);
+            vs[4] = (Byte)(_time_mid >> 8);
+            vs[5] = (Byte)(_time_mid);
+            vs[6] = (Byte)(_time_hi_and_version >> 8);
+            vs[7] = (Byte)(_time_hi_and_version);
+            vs[8] = _clock_seq_hi_and_reserved;
+            vs[9] = _clock_seq_low;
+            Array.Copy(_node, 0, vs, 10, 6);
+
+            String v = BitConverter.ToString(vs);
 
             return vs;
         }
@@ -364,10 +367,10 @@ public Guid ToGuid()
         }
 
         /// <summary>
-        /// Return the Variant 2 version in System.Guid.
+        /// Return the Microsoft Variant version in System.Guid.
         /// </summary>
         /// <returns>A System.Guid object.</returns>
-        public Guid ToVariant2()
+        public Guid ToMicrosoftVariant()
         {
             byte newClockSeq = (byte)(_clock_seq_hi_and_reserved & 0x1F);
             newClockSeq = (byte)(newClockSeq | 0xC0);
@@ -379,11 +382,11 @@ public Guid ToVariant2()
         }
 
         /// <summary>
-        /// Returns the Variant 1 version in TensionDev.UUID.Uuid.
+        /// Returns the RFC 4122 Variant version in TensionDev.UUID.Uuid.
         /// </summary>
         /// <param name="guid">The System.Guid object to convert.</param>
         /// <returns>A TensionDev.UUID.Uuid object.</returns>
-        public static Uuid ToVariant1(Guid guid)
+        public static Uuid ToRfc4122Variant(Guid guid)
         {
             Uuid variant2 = new Uuid(guid.ToString());
             byte newClockSeq = (byte)(variant2._clock_seq_hi_and_reserved & 0x3F);
@@ -443,16 +446,19 @@ private string ToStringCannonical()
         {
             StringBuilder sb = new StringBuilder();
 
-            sb.Append(BitConverter.ToString(BitConverter.GetBytes(_time_low)).Replace("-", ""));
+            // RFC 4122 big-endian layout
+            sb.AppendFormat(FOUR_BYTE_HEX_FORMAT_STRING, _time_low);               // 8 hex digits
             sb.Append("-");
-            sb.Append(BitConverter.ToString(BitConverter.GetBytes(_time_mid)).Replace("-", ""));
+            sb.AppendFormat(TWO_BYTE_HEX_FORMAT_STRING, _time_mid);               // 4 hex digits
             sb.Append("-");
-            sb.Append(BitConverter.ToString(BitConverter.GetBytes(_time_hi_and_version)).Replace("-", ""));
+            sb.AppendFormat(TWO_BYTE_HEX_FORMAT_STRING, _time_hi_and_version);    // 4 hex digits
             sb.Append("-");
-            sb.AppendFormat(HEX_FORMAT_STRING, _clock_seq_hi_and_reserved);
-            sb.AppendFormat(HEX_FORMAT_STRING, _clock_seq_low);
+            sb.AppendFormat(ONE_BYTE_HEX_FORMAT_STRING, _clock_seq_hi_and_reserved);
+            sb.AppendFormat(ONE_BYTE_HEX_FORMAT_STRING, _clock_seq_low);
             sb.Append("-");
-            sb.Append(BitConverter.ToString(_node).Replace("-", ""));
+
+            foreach (byte b in _node)
+                sb.AppendFormat(ONE_BYTE_HEX_FORMAT_STRING, b);
 
             return sb.ToString().ToLower();
         }
@@ -461,12 +467,15 @@ private string ToHexString()
         {
             StringBuilder sb = new StringBuilder();
 
-            sb.Append(BitConverter.ToString(BitConverter.GetBytes(_time_low)).Replace("-", ""));
-            sb.Append(BitConverter.ToString(BitConverter.GetBytes(_time_mid)).Replace("-", ""));
-            sb.Append(BitConverter.ToString(BitConverter.GetBytes(_time_hi_and_version)).Replace("-", ""));
-            sb.AppendFormat(HEX_FORMAT_STRING, _clock_seq_hi_and_reserved);
-            sb.AppendFormat(HEX_FORMAT_STRING, _clock_seq_low);
-            sb.Append(BitConverter.ToString(_node).Replace("-", ""));
+            // RFC 4122 big-endian layout
+            sb.AppendFormat(FOUR_BYTE_HEX_FORMAT_STRING, _time_low);               // 8 hex digits
+            sb.AppendFormat(TWO_BYTE_HEX_FORMAT_STRING, _time_mid);               // 4 hex digits
+            sb.AppendFormat(TWO_BYTE_HEX_FORMAT_STRING, _time_hi_and_version);    // 4 hex digits
+            sb.AppendFormat(ONE_BYTE_HEX_FORMAT_STRING, _clock_seq_hi_and_reserved);
+            sb.AppendFormat(ONE_BYTE_HEX_FORMAT_STRING, _clock_seq_low);
+
+            foreach (byte b in _node)
+                sb.AppendFormat(ONE_BYTE_HEX_FORMAT_STRING, b);
 
             return sb.ToString().ToLower();
         }
@@ -542,7 +551,7 @@ private string ToStringBraces()
         {
             return a.CompareTo(b) > 0;
         }
-        
+
         /// <summary>
         /// Indicates whether the values of the first Uuid object is less than or equal to the other.
         /// </summary>
diff --git a/XUnitTestProjectUUID/UnitTestUuid.cs b/XUnitTestProjectUUID/UnitTestUuid.cs
@@ -355,7 +355,7 @@ public void TestToVariant2()
             Guid expected = new Guid("7d444840-9dc0-11d1-d245-5ffdce74fad2");
             TensionDev.UUID.Uuid uuid = new TensionDev.UUID.Uuid("7d444840-9dc0-11d1-b245-5ffdce74fad2");
 
-            Guid actual = uuid.ToVariant2();
+            Guid actual = uuid.ToMicrosoftVariant();
             Assert.Equal(expected, actual);
         }
 
@@ -365,7 +365,7 @@ public void TestToVariant1()
             TensionDev.UUID.Uuid expected = new TensionDev.UUID.Uuid("7d444840-9dc0-11d1-9245-5ffdce74fad2");
             Guid guid = new Guid("7d444840-9dc0-11d1-d245-5ffdce74fad2");
 
-            TensionDev.UUID.Uuid actual = TensionDev.UUID.Uuid.ToVariant1(guid);
+            TensionDev.UUID.Uuid actual = TensionDev.UUID.Uuid.ToRfc4122Variant(guid);
             Assert.Equal(expected, actual);
         }
 
