Merge

NUlid.Performance/Program.cs

@@ -24,6 +24,7 @@ private static byte[] GetRandomBytes(int amount)
         return b;
     }
 
+#pragma warning disable CA1822 // Mark members as static
     [Benchmark(Description = "Guid.NewGuid()")]
     public Guid Guid_NewGuid() => Guid.NewGuid();
     [Benchmark(Description = "Ulid.NewUlid(SimpleUlidRng)")]
@@ -54,4 +55,5 @@ private static byte[] GetRandomBytes(int amount)
     public Guid Ulid_ToGuid() => Ulid.NewUlid().ToGuid();
     [Benchmark(Description = "new Ulid(Guid)")]
     public Ulid New_Ulid_Guid() => new(Guid.NewGuid());
+#pragma warning restore CA1822 // Mark members as static
 }

NUlid.Tests/FakeUlidRng.cs

@@ -1,6 +1,5 @@
 using NUlid.Rng;
 using System;
-using System.Collections.Generic;
 
 namespace NUlid.Tests;
 
@@ -13,11 +12,13 @@ namespace NUlid.Tests;
 public class FakeUlidRng(byte[] desiredResult) : IUlidRng
 {
     //Values specifically chosen to make the result spell DEADBEEFDEADBEEF
-    public static readonly IReadOnlyList<byte> DEFAULTRESULT = [107, 148, 213, 185, 207, 107, 148, 213, 185, 207];
+    public static readonly byte[] DEFAULTRESULT = [107, 148, 213, 185, 207, 107, 148, 213, 185, 207];
     private readonly byte[] _desiredresult = desiredResult;
 
     public FakeUlidRng()
-        : this([.. DEFAULTRESULT]) { }
+        : this([.. DEFAULTRESULT]) { }     // make a copy
 
     public byte[] GetRandomBytes(DateTimeOffset dateTime) => _desiredresult;
-}
+
+    public void GetRandomBytes(Span<byte> buffer, DateTimeOffset dateTime) => _desiredresult.AsSpan().CopyTo(buffer);
+}

NUlid.Tests/UlidTests.cs

@@ -322,7 +322,7 @@ public void Ulid_Parse_Handles_Oo_TreatedAs_Zero()  //https://www.crockford.com/
     public void Ulid_Parse_ThrowsFormatException_OnInvalidString2() => Ulid.Parse(_knowntimestamp_string + _knownrandomseq_string.Replace('E', '{')); // Test char after last index in C2B32 array
 
     [TestMethod]
-    [ExpectedException(typeof(ArgumentNullException))]
+    [ExpectedException(typeof(ArgumentException))]
     public void Ulid_Constructor_ThrowsArgumentException_OnNullByteArray() => new Ulid((byte[])null);
 
     [TestMethod]
@@ -337,13 +337,15 @@ public void Ulid_Parse_Handles_Oo_TreatedAs_Zero()  //https://www.crockford.com/
     [ExpectedException(typeof(ArgumentOutOfRangeException))]
     public void Ulid_NewUlid_ThrowsArgumentOutOfRangeException_OnTimestamp() => Ulid.NewUlid(Ulid.MinValue.Time.AddMilliseconds(-1));
 
+#if NETFRAMEWORK
     [TestMethod]
     [ExpectedException(typeof(InvalidOperationException))]
     public void Ulid_NewUlid_ThrowsInvalidOperationException_OnRNGReturningInsufficientBytes()
     {
         var rng = new FakeUlidRng([1, 2, 3]);
         Ulid.NewUlid(rng);
     }
+#endif
 
     [TestMethod]
     public void Ulid_TypeConverter_CanGetUsableConverter()

NUlid/NUlid.csproj

@@ -33,6 +33,10 @@
 		<DocumentationFile>bin\release\NUlid.xml</DocumentationFile>
 	</PropertyGroup>
 
+	<ItemGroup Condition="'$(TargetFramework)' == 'netstandard2.0'">
+		<PackageReference Include="System.Memory" Version="4.5.5" />
+	</ItemGroup>
+
 	<ItemGroup>
 		<None Include="..\logo.png">
 			<Pack>True</Pack>

NUlid/Rng/BaseUlidRng.cs

@@ -10,7 +10,7 @@ public abstract class BaseUlidRng : IUlidRng
     /// <summary>
     /// Default number of random bytes generated
     /// </summary>
-    protected const int RANDLEN = 10;
+    protected internal const int RANDLEN = 10;
 
     /// <summary>
     /// Creates and returns random bytes.
@@ -19,6 +19,9 @@ public abstract class BaseUlidRng : IUlidRng
     /// <returns>Random bytes.</returns>
     public abstract byte[] GetRandomBytes(DateTimeOffset dateTime);
 
+    /// <inheritdoc/>
+    public abstract void GetRandomBytes(Span<byte> buffer, DateTimeOffset dateTime);
+
     /// <summary>
     /// Returns the default <see cref="IUlidRng"/> used when no <see cref="IUlidRng"/> is specified.
     /// </summary>

NUlid/Rng/CSUlidRng.cs

@@ -28,4 +28,27 @@ public override byte[] GetRandomBytes(DateTimeOffset dateTime)
         return buffer;
     }
 #endif
+
+    /// <summary>
+    /// Fills the <paramref name="buffer"/> with returns cryptographically secure random bytes.
+    /// </summary>
+    /// <param name="buffer">The buffer to fill with cryptographically secure random bytes.</param>
+    /// <param name="dateTime">>DateTime for which the random bytes need to be generated; is ignored.</param>
+    /// <exception cref="ArgumentException">The buffer is too small.</exception>
+    public override void GetRandomBytes(Span<byte> buffer, DateTimeOffset dateTime)
+    {
+#if NET6_0_OR_GREATER
+        if (buffer.Length < RANDLEN)
+        {
+            Throw(buffer.Length);
+            static void Throw(int len) => throw new ArgumentException($"The given buffer must be at least {RANDLEN} bytes long, actual: {len}");
+        }
+
+        RandomNumberGenerator.Fill(buffer);
+#else
+        var tmp = new byte[RANDLEN];
+        _rng.GetBytes(tmp);
+        tmp.AsSpan().CopyTo(buffer);
+#endif
+    }
 }

NUlid/Rng/IUlidRng.cs

@@ -13,4 +13,11 @@ public interface IUlidRng
     /// <param name="dateTime">DateTime for which the random bytes need to be generated; can be ignored but provides context.</param>
     /// <returns>Random bytes.</returns>
     byte[] GetRandomBytes(DateTimeOffset dateTime);
+
+    /// <summary>
+    /// Fills the <paramref name="buffer"/> with random bytes.
+    /// </summary>
+    /// <param name="buffer">The buffer to fill with random bytes.</param>
+    /// <param name="dateTime">DateTime for which the random bytes need to be generated; can be ignored but provides context.</param>
+    void GetRandomBytes(Span<byte> buffer, DateTimeOffset dateTime);
 }

NUlid/Rng/MicrosecondUlidRng.cs

@@ -49,6 +49,37 @@ public MicrosecondUlidRng(IUlidRng rng, int bits = 14)
     public byte[] GetRandomBytes(DateTimeOffset dateTime)
     {
         var buffer = _rng.GetRandomBytes(dateTime);
+        Core(buffer, dateTime);
+        return buffer;
+    }
+
+    /// <summary>
+    /// Fills <paramref name="buffer"/> with random bytes based on internal <see cref="IUlidRng"/> and the microseconds of 
+    /// the given <paramref name="dateTime"/>.
+    /// </summary>
+    /// <param name="buffer">The buffer to fill with random bytes.</param>
+    /// <param name="dateTime">
+    /// DateTime for which the random bytes need to be generated; this value is used to determine wether a sequence
+    /// needs to be incremented (same timestamp with millisecond resolution) or reset to a new random value.
+    /// </param>
+    /// <exception cref="ArgumentException">The buffer is too small.</exception>
+    /// <exception cref="InvalidOperationException">
+    /// Thrown when the specified <paramref name="dateTime"/> is before the last time this method was called.
+    /// </exception>
+    public void GetRandomBytes(Span<byte> buffer, DateTimeOffset dateTime)
+    {
+        if (buffer.Length < BaseUlidRng.RANDLEN)
+        {
+            Throw(buffer.Length);
+            static void Throw(int len) => throw new ArgumentException($"The given buffer must be at least {BaseUlidRng.RANDLEN} bytes long, actual: {len}");
+        }
+
+        _rng.GetRandomBytes(buffer, dateTime);
+        Core(buffer, dateTime);
+    }
+
+    private void Core(Span<byte> buffer, DateTimeOffset dateTime)
+    {
         // Extract microseconds from timestamp (14 bits max), align microseconds-MSB (14 bits) to ushort MSB (16 bits) by shifting left 2
         // bits. Then mask out undesired bits
         var usecpart = (ushort)(((dateTime.Ticks % 10000) << 2) & _mask);
@@ -57,6 +88,5 @@ public byte[] GetRandomBytes(DateTimeOffset dateTime)
         // of random data with the microsecondpart
         buffer[0] = (byte)((buffer[0] & _negmaskmsb) | (usecpart >> 8));
         buffer[1] = (byte)((buffer[0] & _negmasklsb) | (usecpart & 0xFF));
-        return buffer;
     }
 }

NUlid/Rng/MonotonicUlidRng.cs

@@ -59,6 +59,36 @@ public MonotonicUlidRng()
     /// Thrown when the specified <paramref name="dateTime"/> is before the last time this method was called.
     /// </exception>
     public override byte[] GetRandomBytes(DateTimeOffset dateTime)
+    {
+        var buffer = new byte[RANDLEN];
+        Core(buffer, dateTime);
+        return buffer;
+    }
+
+    /// <summary>
+    /// Fills the <paramref name="buffer"/> with random bytes based on internal <see cref="IUlidRng"/>.
+    /// </summary>
+    /// <param name="buffer">The buffer to fill with random bytes.</param>
+    /// <param name="dateTime">
+    /// DateTime for which the random bytes need to be generated; this value is used to determine wether a sequence
+    /// needs to be incremented (same timestamp with millisecond resolution) or reset to a new random value.
+    /// </param>
+    /// <exception cref="ArgumentException">The buffer is too small.</exception>
+    /// <exception cref="InvalidOperationException">
+    /// Thrown when the specified <paramref name="dateTime"/> is before the last time this method was called.
+    /// </exception>
+    public override void GetRandomBytes(Span<byte> buffer, DateTimeOffset dateTime)
+    {
+        if (buffer.Length < RANDLEN)
+        {
+            Throw(buffer.Length);
+            static void Throw(int len) => throw new ArgumentException($"The given buffer must be at least {RANDLEN} bytes long, actual: {len}");
+        }
+
+        Core(buffer, dateTime);
+    }
+
+    private void Core(Span<byte> buffer, DateTimeOffset dateTime)
     {
         lock (_genlock)
         {
@@ -83,9 +113,7 @@ public override byte[] GetRandomBytes(DateTimeOffset dateTime)
 
                 _lastgen = timestamp;   // Store last timestamp
             }
-            var buffer = new byte[RANDLEN];
-            _lastvalue.CopyTo(buffer, 0);
-            return buffer;
+            _lastvalue.AsSpan().CopyTo(buffer);
         }
     }
 }

NUlid/Rng/SimpleUlidRng.cs

@@ -24,6 +24,29 @@ public override byte[] GetRandomBytes(DateTimeOffset dateTime)
         return _buffer;
     }
 
+    /// <summary>
+    /// Fills the <paramref name="buffer"/> with random bytes.
+    /// </summary>
+    /// <param name="buffer">The buffer to fill with random bytes.</param>
+    /// <param name="dateTime">DateTime for which the random bytes need to be generated; is ignored.</param>
+    /// <exception cref="ArgumentException">The buffer is too small.</exception>
+    public override void GetRandomBytes(Span<byte> buffer, DateTimeOffset dateTime)
+    {
+        if (buffer.Length < RANDLEN)
+        {
+            Throw(buffer.Length);
+            static void Throw(int len) => throw new ArgumentException($"The given buffer must be at least {RANDLEN} bytes long, actual: {len}");
+        }
+
+#if NET6_0_OR_GREATER
+        Random.Shared.NextBytes(buffer);
+#else
+        var tmp = new byte[RANDLEN];
+        ThreadLocalRandom.Instance.NextBytes(tmp);
+        tmp.AsSpan().CopyTo(buffer);
+#endif
+    }
+
     /// <summary>
     /// Convenience class for dealing with randomness.
     /// </summary>