Add polyfill for Guid.CreateVersion7 and Guid.CreateVersion7(DateTimeOffset) (#149)

Author: Copilot

Meziantou.Polyfill.Editor/M;System.Guid.CreateVersion7(System.DateTimeOffset).cs

@@ -0,0 +1,51 @@
+partial class PolyfillExtensions
+{
+    extension(System.Guid)
+    {
+        public static System.Guid CreateVersion7(System.DateTimeOffset timestamp)
+        {
+            // UUIDv7 structure (RFC 9562, Section 5.7):
+            //  0                   1                   2                   3
+            //  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+            // +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+            // |                           unix_ts_ms                          |
+            // +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+            // |          unix_ts_ms           |  ver  |       rand_a          |
+            // +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+            // |var|                        rand_b                             |
+            // +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+            // |                           rand_b                              |
+            // +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+
+            long unixMs = timestamp.ToUnixTimeMilliseconds();
+
+            if (unchecked((ulong)unixMs) > 0xFFFF_FFFF_FFFFUL)
+            {
+                throw new System.ArgumentOutOfRangeException(nameof(timestamp));
+            }
+
+            byte[] rand = new byte[10];
+            using (var rng = System.Security.Cryptography.RandomNumberGenerator.Create())
+            {
+                rng.GetBytes(rand);
+            }
+
+            // Set version 7 in high nibble of UUID byte 6 (rand[0])
+            rand[0] = (byte)((rand[0] & 0x0F) | 0x70);
+
+            // Set variant 0b10 in high 2 bits of UUID byte 8 (rand[2])
+            rand[2] = (byte)((rand[2] & 0x3F) | 0x80);
+
+            // Build the Guid from the UUID v7 big-endian byte layout:
+            // UUID bytes 0-3 → Data1 (upper 32 bits of 48-bit timestamp, big-endian)
+            // UUID bytes 4-5 → Data2 (lower 16 bits of timestamp, big-endian)
+            // UUID bytes 6-7 → Data3 (version nibble + rand_a, big-endian)
+            // UUID bytes 8-15 → Data4 (variant bits + rand_b, stored as-is)
+            return new System.Guid(
+                unchecked((int)(unixMs >> 16)),
+                unchecked((short)(unixMs & 0xFFFF)),
+                (short)((rand[0] << 8) | rand[1]),
+                rand[2], rand[3], rand[4], rand[5], rand[6], rand[7], rand[8], rand[9]);
+        }
+    }
+}

Meziantou.Polyfill.Editor/M;System.Guid.CreateVersion7.cs

@@ -0,0 +1,11 @@
+// when M:System.Guid.CreateVersion7(System.DateTimeOffset)
+partial class PolyfillExtensions
+{
+    extension(System.Guid)
+    {
+        public static System.Guid CreateVersion7()
+        {
+            return System.Guid.CreateVersion7(System.DateTimeOffset.UtcNow);
+        }
+    }
+}

Meziantou.Polyfill.Tests/SystemTests.cs

@@ -2042,4 +2042,79 @@ public void Delegate_EnumerateInvocationList_Null()
         Assert.Equal(0, count);
     }
 
+    [Fact]
+    public void Guid_CreateVersion7_ReturnsVersion7Guid()
+    {
+        var guid = Guid.CreateVersion7();
+        var str = guid.ToString("D");
+
+        // Version should be 7 (character at position 14 in "D" format: xxxxxxxx-xxxx-Vxxx-...)
+        Assert.Equal('7', str[14]);
+
+        // Variant should be 0b10xx (8, 9, a, or b) at position 19
+        Assert.Contains(str[19], new[] { '8', '9', 'a', 'b' });
+    }
+
+    [Fact]
+    public void Guid_CreateVersion7_IsSortable()
+    {
+        // UUID v7 GUIDs with different (1ms apart) timestamps should sort by timestamp
+        var timestamp1 = new DateTimeOffset(2024, 1, 1, 0, 0, 0, 0, TimeSpan.Zero);
+        var timestamp2 = new DateTimeOffset(2024, 1, 1, 0, 0, 0, 1, TimeSpan.Zero);
+
+        var guid1 = Guid.CreateVersion7(timestamp1);
+        var guid2 = Guid.CreateVersion7(timestamp2);
+
+        Assert.True(string.Compare(guid1.ToString("D"), guid2.ToString("D"), StringComparison.Ordinal) < 0);
+    }
+
+    [Fact]
+    public void Guid_CreateVersion7_WithTimestamp_ReturnsVersion7Guid()
+    {
+        var timestamp = new DateTimeOffset(2024, 1, 1, 0, 0, 0, TimeSpan.Zero);
+        var guid = Guid.CreateVersion7(timestamp);
+        var str = guid.ToString("D");
+
+        // Version should be 7
+        Assert.Equal('7', str[14]);
+
+        // Variant should be 0b10xx (8, 9, a, or b)
+        Assert.Contains(str[19], new[] { '8', '9', 'a', 'b' });
+    }
+
+    [Fact]
+    public void Guid_CreateVersion7_WithTimestamp_EmbedsTimestamp()
+    {
+        var timestamp = new DateTimeOffset(2024, 6, 15, 12, 30, 45, 123, TimeSpan.Zero);
+        var guid1 = Guid.CreateVersion7(timestamp);
+        var guid2 = Guid.CreateVersion7(timestamp);
+
+        // Both GUIDs created with the same timestamp should have identical timestamp portions
+        // (first 12 hex chars in "N" format = 48-bit timestamp)
+        var str1 = guid1.ToString("N");
+        var str2 = guid2.ToString("N");
+        Assert.True(str1.AsSpan(0, 12).SequenceEqual(str2.AsSpan(0, 12)));
+    }
+
+    [Fact]
+    public void Guid_CreateVersion7_WithTimestamp_TimestampOrderPreserved()
+    {
+        var timestamp1 = new DateTimeOffset(2024, 1, 1, 0, 0, 0, TimeSpan.Zero);
+        var timestamp2 = new DateTimeOffset(2025, 1, 1, 0, 0, 0, TimeSpan.Zero);
+
+        var guid1 = Guid.CreateVersion7(timestamp1);
+        var guid2 = Guid.CreateVersion7(timestamp2);
+
+        // GUIDs with earlier timestamps should sort before GUIDs with later timestamps
+        Assert.True(string.Compare(guid1.ToString("D"), guid2.ToString("D"), StringComparison.Ordinal) < 0);
+    }
+
+    [Fact]
+    public void Guid_CreateVersion7_WithTimestamp_OutOfRange_ThrowsArgumentOutOfRangeException()
+    {
+        // Timestamp before Unix epoch
+        var beforeEpoch = new DateTimeOffset(1969, 12, 31, 23, 59, 59, TimeSpan.Zero);
+        Assert.Throws<ArgumentOutOfRangeException>(() => Guid.CreateVersion7(beforeEpoch));
+    }
+
 }

Meziantou.Polyfill/Meziantou.Polyfill.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Meziantou.NET.Sdk">
   <PropertyGroup>
     <TargetFrameworks>netstandard2.0</TargetFrameworks>
-    <Version>1.0.102</Version>
+    <Version>1.0.103</Version>
     <TransformOnBuild>true</TransformOnBuild>
     <RoslynVersion>4.3.1</RoslynVersion>
 

README.md

@@ -124,7 +124,7 @@ The filtering logic works as follows:
 - `System.ValueTuple<T1, T2, T3, T4, T5, T6, T7, TRest> where TRest : struct`
 - `System.ITupleInternal`
 
-### Methods (523)
+### Methods (525)
 
 - `System.ArgumentException.ThrowIfNullOrEmpty(System.String? argument, [System.String? paramName = null])`
 - `System.ArgumentException.ThrowIfNullOrWhiteSpace(System.String? argument, [System.String? paramName = null])`
@@ -211,6 +211,7 @@ The filtering logic works as follows:
 - `System.Enum.TryParse<TEnum>(System.ReadOnlySpan<System.Char> value, out TEnum result) where TEnum : struct`
 - `System.Enum.TryParse<TEnum>(System.String? value, System.Boolean ignoreCase, out TEnum result) where TEnum : struct`
 - `System.Enum.TryParse<TEnum>(System.String? value, out TEnum result) where TEnum : struct`
+- `System.Guid.CreateVersion7(System.DateTimeOffset timestamp)`
 - `System.IO.File.AppendAllBytes(System.String path, System.Byte[] bytes)`
 - `System.IO.File.AppendAllBytes(System.String path, System.ReadOnlySpan<System.Byte> bytes)`
 - `System.IO.File.AppendAllBytesAsync(System.String path, System.Byte[] bytes, [System.Threading.CancellationToken cancellationToken = default])`
@@ -641,6 +642,7 @@ The filtering logic works as follows:
 - `System.Xml.Linq.XElement.SaveAsync(System.IO.Stream stream, System.Xml.Linq.SaveOptions options, System.Threading.CancellationToken cancellationToken)`
 - `System.Xml.Linq.XElement.SaveAsync(System.IO.TextWriter textWriter, System.Xml.Linq.SaveOptions options, System.Threading.CancellationToken cancellationToken)`
 - `System.Xml.Linq.XElement.SaveAsync(System.Xml.XmlWriter writer, System.Threading.CancellationToken cancellationToken)`
+- `System.Guid.CreateVersion7()`
 - `System.Random.GetItems<T>(T[] choices, System.Int32 length)`
 - `System.Random.Shuffle<T>(T[] values)`
 - `System.Security.Cryptography.RandomNumberGenerator.GetInt32(System.Int32 toExclusive)`