com.wallstop-studios.unity-helpers 2.0.0-rc78.2 → 2.0.0-rc78.4

package/README.md

@@ -133,17 +133,18 @@ random.NextNoiseMap(width, height); // A configurable noise map generated using
 
 | Random | NextBool | Next | NextUInt | NextFloat | NextDouble | NextUint - Range | NextInt - Range |
 | ------ | -------- | ---- | -------- | --------- | ---------- | ---------------- | --------------- |
-| PcgRandom | 168,140,000 | 168,290,000 | 230,950,000 | 92,140,000 | 92,400,000 |42,940,000 |38,430,000 |
-| SystemRandom | 78,180,000 | 89,840,000 | 37,690,000 | 72,460,000 | 72,880,000 |37,930,000 |33,940,000 |
-| SquirrelRandom | 128,120,000 | 128,190,000 | 163,060,000 | 78,140,000 | 78,720,000 |38,040,000 |36,310,000 |
-| XorShiftRandom | 179,350,000 | 179,350,000 | 256,370,000 | 95,560,000 | 95,590,000 |43,750,000 |39,640,000 |
-| DotNetRandom | 31,610,000 | 31,610,000 | 33,380,000 | 26,710,000 | 27,130,000 |20,120,000 |18,880,000 |
-| WyRandom | 77,910,000 | 77,880,000 | 88,780,000 | 55,640,000 | 55,270,000 |31,810,000 |28,920,000 |
-| SplitMix64 | 161,420,000 | 161,330,000 | 221,880,000 | 89,030,000 | 89,910,000 |42,160,000 |38,760,000 |
-| RomuDuo | 132,840,000 | 133,150,000 | 171,810,000 | 80,290,000 | 79,120,000 |39,790,000 |36,620,000 |
-| XorShiroRandom | 102,500,000 | 102,470,000 | 123,840,000 | 67,970,000 | 67,130,000 |35,850,000 |32,930,000 |
-| UnityRandom | 52,440,000 | 52,440,000 | 57,630,000 | 41,670,000 | 39,940,000 |25,890,000 |25,140,000 |
-| LinearCongruentialGenerator | 177,530,000 | 177,560,000 | 253,480,000 | 94,440,000 | 93,090,000 |42,920,000 |38,960,000 |
+| DotNetRandom | 30,700,000 | 30,900,000 | 32,600,000 | 25,700,000 | 25,800,000 |19,500,000 |18,200,000 |
+| LinearCongruentialGenerator | 179,600,000 | 179,700,000 | 256,600,000 | 91,400,000 | 92,000,000 |43,600,000 |39,600,000 |
+| PcgRandom | 168,400,000 | 168,400,000 | 234,200,000 | 88,800,000 | 89,300,000 |43,000,000 |38,700,000 |
+| RomuDuo | 134,600,000 | 134,700,000 | 173,800,000 | 78,200,000 | 78,800,000 |39,900,000 |36,200,000 |
+| SplitMix64 | 163,200,000 | 163,300,000 | 224,400,000 | 87,600,000 | 87,900,000 |42,600,000 |38,700,000 |
+| SquirrelRandom | 128,300,000 | 128,400,000 | 163,200,000 | 75,800,000 | 76,600,000 |39,500,000 |36,200,000 |
+| SystemRandom | 77,800,000 | 88,800,000 | 37,600,000 | 70,500,000 | 69,600,000 |38,200,000 |34,300,000 |
+| UnityRandom | 53,000,000 | 53,100,000 | 58,300,000 | 41,400,000 | 41,400,000 |26,700,000 |24,900,000 |
+| WyRandom | 79,100,000 | 79,100,000 | 91,100,000 | 53,000,000 | 55,300,000 |32,100,000 |30,000,000 |
+| XorShiftRandom | 179,500,000 | 179,500,000 | 256,500,000 | 92,000,000 | 92,400,000 |42,400,000 |38,500,000 |
+| XoroShiroRandom | 103,600,000 | 103,700,000 | 125,300,000 | 66,200,000 | 67,000,000 |36,900,000 |34,000,000 |
+| XoroShiroEnhancedRandom | 149,700,000 | 149,700,000 | 199,700,000 | 83,000,000 | 83,800,000 |41,400,000 |37,700,000 |
 
 # Spatial Trees
 There are three implemented 2D immutable spatial trees that can store generic objects, as long as there is some resolution function that can convert them into Vector2 spatial positions.

package/Runtime/Core/Extension/IListExtensions.cs

@@ -2,10 +2,18 @@
 {
     using System;
     using System.Collections.Generic;
+    using System.ComponentModel;
+    using System.Diagnostics.Contracts;
     using Helper;
     using Random;
     using Utils;
 
+    public enum SortAlgorithm
+    {
+        ShellEnhanced = 0,
+        Insertion = 1,
+    }
+
     public static class IListExtensions
     {
         public static void Shuffle<T>(this IList<T> list, IRandom random = null)
@@ -87,6 +95,36 @@
             list.RemoveAt(lastIndex);
         }
 
+        public static void Sort<T, TComparer>(
+            this IList<T> array,
+            TComparer comparer,
+            SortAlgorithm sortAlgorithm = SortAlgorithm.ShellEnhanced
+        )
+            where TComparer : IComparer<T>
+        {
+            switch (sortAlgorithm)
+            {
+                case SortAlgorithm.ShellEnhanced:
+                {
+                    ShellSortEnhanced(array, comparer);
+                    return;
+                }
+                case SortAlgorithm.Insertion:
+                {
+                    InsertionSort(array, comparer);
+                    return;
+                }
+                default:
+                {
+                    throw new InvalidEnumArgumentException(
+                        nameof(sortAlgorithm),
+                        (int)sortAlgorithm,
+                        typeof(SortAlgorithm)
+                    );
+                }
+            }
+        }
+
         public static void InsertionSort<T, TComparer>(this IList<T> array, TComparer comparer)
             where TComparer : IComparer<T>
         {
@@ -104,6 +142,61 @@
             }
         }
 
+        /*
+            Implementation copyright Will Stafford Parsons,
+            https://github.com/wstaffordp/bsearch-enhanced/blob/master/examples/benchmark.c#L31-L78
+            
+            Please contact the original author if you would like an explanation of constants.
+         */
+        public static void ShellSortEnhanced<T, TComparer>(this IList<T> array, TComparer comparer)
+            where TComparer : IComparer<T>
+        {
+            int length = array.Count;
+            int gap = array.Count;
+
+            int i;
+            int j;
+            while (gap > 15)
+            {
+                gap = (gap >> 5) + (gap >> 3);
+                i = gap;
+
+                while (i < length)
+                {
+                    T element = array[i];
+                    j = i;
+                    while (j >= gap && 0 < comparer.Compare(array[j - gap], element))
+                    {
+                        array[j] = array[j - gap];
+                        j -= gap;
+                    }
+
+                    array[j] = element;
+                    i++;
+                }
+            }
+
+            i = 1;
+            gap = 0;
+
+            while (i < length)
+            {
+                T element = array[i];
+                j = i;
+
+                while (j > 0 && 0 < comparer.Compare(array[gap], element))
+                {
+                    array[j] = array[gap];
+                    j = gap;
+                    gap--;
+                }
+
+                array[j] = element;
+                gap = i;
+                i++;
+            }
+        }
+
         public static void SortByName<T>(this IList<T> inputList)
             where T : UnityEngine.Object
         {
@@ -121,12 +214,13 @@
                 }
                 default:
                 {
-                    inputList.InsertionSort(UnityObjectNameComparer<T>.Instance);
+                    inputList.Sort(UnityObjectNameComparer<T>.Instance);
                     break;
                 }
             }
         }
 
+        [Pure]
         public static bool IsSorted<T>(this IList<T> list, IComparer<T> comparer = null)
         {
             if (list.Count <= 1)

package/Runtime/Core/Random/PRNG.cs

@@ -2,6 +2,6 @@
 {
     public static class PRNG
     {
-        public static IRandom Instance => PcgRandom.Instance;
+        public static IRandom Instance => XoroShiroEnhancedRandom.Instance;
     }
 }

package/Runtime/Core/Random/XoroShiroEnhancedRandom.cs

@@ -0,0 +1,108 @@
+/*
+    XoroShiroEnhanced is a significant enhancement upon the classic XoroShiroRandom discovered by Will Stafford Parsons.
+        
+    Reference: https://github.com/wstaffordp/bsearch-enhanced/blob/master/examples/benchmark.c#L4-L29
+    
+    Copyright original author: https://github.com/wstaffordp
+ */
+
+namespace WallstopStudios.UnityHelpers.Core.Random
+{
+    using System;
+    using System.Runtime.Serialization;
+    using System.Text.Json.Serialization;
+
+    [Serializable]
+    [DataContract]
+    public sealed class XoroShiroEnhancedRandom : AbstractRandom
+    {
+        private const int UintByteCount = sizeof(uint) * 8;
+
+        public static XoroShiroEnhancedRandom Instance =>
+            ThreadLocalRandom<XoroShiroEnhancedRandom>.Instance;
+
+        public override RandomState InternalState
+        {
+            get
+            {
+                ulong stateA = ((ulong)_a << UintByteCount) | _b;
+                ulong stateB = ((ulong)_c << UintByteCount) | _d;
+                byte[] eBytes = BitConverter.GetBytes(_e);
+                Array.Resize(ref eBytes, sizeof(double));
+                Array.Fill<byte>(eBytes, 0, sizeof(uint), sizeof(double) - sizeof(uint));
+                return new RandomState(stateA, stateB, BitConverter.ToDouble(eBytes, 0));
+            }
+        }
+
+        private uint _a;
+        private uint _b;
+        private uint _c;
+        private uint _d;
+        private uint _e;
+
+        public XoroShiroEnhancedRandom()
+            : this(Guid.NewGuid()) { }
+
+        public XoroShiroEnhancedRandom(Guid guid, uint? extraSeed = null)
+        {
+            byte[] guidArray = guid.ToByteArray();
+            _a = BitConverter.ToUInt32(guidArray, 0);
+            _b = BitConverter.ToUInt32(guidArray, sizeof(uint));
+            _c = BitConverter.ToUInt32(guidArray, sizeof(uint) * 2);
+            _d = BitConverter.ToUInt32(guidArray, sizeof(uint) * 3);
+            _e = extraSeed ?? unchecked((uint)guid.GetHashCode());
+        }
+
+        [JsonConstructor]
+        public XoroShiroEnhancedRandom(RandomState internalState)
+        {
+            unchecked
+            {
+                _a = (uint)(internalState.State1 >> UintByteCount);
+                _b = (uint)internalState.State1;
+                _c = (uint)(internalState.State2 >> UintByteCount);
+                _d = (uint)internalState.State2;
+                double? gaussian = internalState.Gaussian;
+                if (gaussian != null)
+                {
+                    byte[] eBytes = BitConverter.GetBytes(gaussian.Value);
+                    Array.Resize(ref eBytes, sizeof(uint));
+                    _e = BitConverter.ToUInt32(eBytes, 0);
+                }
+                else
+                {
+                    throw new InvalidOperationException(
+                        $"{nameof(XoroShiroEnhancedRandom)} requires a Gaussian state."
+                    );
+                }
+            }
+        }
+
+        public override uint NextUint()
+        {
+            unchecked
+            {
+                uint result = _b + _e;
+                ++_a;
+                if (_a == 0U)
+                {
+                    _c += _e;
+                    _d ^= _b;
+                    _b += _c;
+                    _e ^= _d;
+                    return result;
+                }
+
+                _b = ((_b << 17) | (_b >> 15)) ^ _d;
+                _d += 1111111111U;
+                _e = (result << 13) | (result >> 19);
+                return result;
+            }
+        }
+
+        public override IRandom Copy()
+        {
+            return new XoroShiroEnhancedRandom(InternalState);
+        }
+    }
+}

package/Runtime/Core/Random/XoroShiroEnhancedRandom.cs.meta

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: d8e25c684e0a4d46a1924227eab38602
+timeCreated: 1752453500

package/Runtime/Core/Random/{XorShiroRandom.cs → XoroShiroRandom.cs}

@@ -6,37 +6,37 @@
     using Extension;
     using Helper;
 
-    public sealed class XorShiroRandom
+    public sealed class XoroShiroRandom
         : AbstractRandom,
-            IEquatable<XorShiroRandom>,
+            IEquatable<XoroShiroRandom>,
             IComparable,
-            IComparable<XorShiroRandom>
+            IComparable<XoroShiroRandom>
     {
-        public static XorShiroRandom Instance => ThreadLocalRandom<XorShiroRandom>.Instance;
+        public static XoroShiroRandom Instance => ThreadLocalRandom<XoroShiroRandom>.Instance;
 
         public override RandomState InternalState => new(_s0, _s1, _cachedGaussian);
 
         internal ulong _s0;
         internal ulong _s1;
 
-        public XorShiroRandom()
+        public XoroShiroRandom()
             : this(Guid.NewGuid()) { }
 
-        public XorShiroRandom(Guid guid)
+        public XoroShiroRandom(Guid guid)
         {
             byte[] bytes = guid.ToByteArray();
             _s0 = BitConverter.ToUInt64(bytes, 0);
             _s1 = BitConverter.ToUInt64(bytes, 8);
         }
 
-        public XorShiroRandom(ulong seed1, ulong seed2)
+        public XoroShiroRandom(ulong seed1, ulong seed2)
         {
             _s0 = seed1;
             _s1 = seed2;
         }
 
         [JsonConstructor]
-        public XorShiroRandom(RandomState internalState)
+        public XoroShiroRandom(RandomState internalState)
         {
             _s0 = internalState.State1;
             _s1 = internalState.State2;
@@ -61,7 +61,7 @@
 
         public override IRandom Copy()
         {
-            return new XorShiroRandom(InternalState);
+            return new XoroShiroRandom(InternalState);
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
@@ -72,10 +72,10 @@
 
         public override bool Equals(object obj)
         {
-            return Equals(obj as XorShiroRandom);
+            return Equals(obj as XoroShiroRandom);
         }
 
-        public bool Equals(XorShiroRandom other)
+        public bool Equals(XoroShiroRandom other)
         {
             if (other == null)
             {
@@ -97,10 +97,10 @@
 
         public int CompareTo(object obj)
         {
-            return CompareTo(obj as XorShiroRandom);
+            return CompareTo(obj as XoroShiroRandom);
         }
 
-        public int CompareTo(XorShiroRandom other)
+        public int CompareTo(XoroShiroRandom other)
         {
             if (other == null)
             {

package/Tests/Runtime/Extensions/IListExtensionTests.cs

@@ -100,5 +100,70 @@
                 Assert.That(input.OrderBy(x => x), Is.EqualTo(insertionSorted));
             }
         }
+
+        [Test]
+        public void ShellSortEnhanced()
+        {
+            for (int i = 0; i < NumTries; ++i)
+            {
+                int[] input = Enumerable
+                    .Range(0, 100)
+                    .Select(_ => PRNG.Instance.Next(int.MinValue, int.MaxValue))
+                    .ToArray();
+                int[] conventionalSorted = input.ToArray();
+                Array.Sort(conventionalSorted);
+
+                int[] insertionSorted = input.ToArray();
+                insertionSorted.ShellSortEnhanced(new IntComparer());
+                Assert.That(conventionalSorted, Is.EqualTo(insertionSorted));
+                Assert.That(input.OrderBy(x => x), Is.EqualTo(insertionSorted));
+            }
+        }
+
+        [Test]
+        public void SortDefaultAlgorithm()
+        {
+            for (int i = 0; i < NumTries; ++i)
+            {
+                int[] input = Enumerable
+                    .Range(0, 100)
+                    .Select(_ => PRNG.Instance.Next(int.MinValue, int.MaxValue))
+                    .ToArray();
+                int[] conventionalSorted = input.ToArray();
+                Array.Sort(conventionalSorted);
+
+                int[] insertionSorted = input.ToArray();
+                insertionSorted.Sort(new IntComparer());
+                Assert.That(conventionalSorted, Is.EqualTo(insertionSorted));
+                Assert.That(input.OrderBy(x => x), Is.EqualTo(insertionSorted));
+            }
+        }
+
+        [Test]
+        public void SortAllAlgorithms()
+        {
+            SortAlgorithm[] sortAlgorithms = Enum.GetValues(typeof(SortAlgorithm))
+                .OfType<SortAlgorithm>()
+                .ToArray();
+            Assert.That(sortAlgorithms.Length, Is.GreaterThan(0));
+
+            foreach (SortAlgorithm sortAlgorithm in sortAlgorithms)
+            {
+                for (int i = 0; i < NumTries; ++i)
+                {
+                    int[] input = Enumerable
+                        .Range(0, 100)
+                        .Select(_ => PRNG.Instance.Next(int.MinValue, int.MaxValue))
+                        .ToArray();
+                    int[] conventionalSorted = input.ToArray();
+                    Array.Sort(conventionalSorted);
+
+                    int[] insertionSorted = input.ToArray();
+                    insertionSorted.Sort(new IntComparer(), sortAlgorithm);
+                    Assert.That(conventionalSorted, Is.EqualTo(insertionSorted));
+                    Assert.That(input.OrderBy(x => x), Is.EqualTo(insertionSorted));
+                }
+            }
+        }
     }
 }

package/Tests/Runtime/Performance/ListExtensionPerformanceTests.cs

@@ -0,0 +1,80 @@
+namespace WallstopStudios.UnityHelpers.Tests.Performance
+{
+    using System;
+    using System.Collections.Generic;
+    using System.Diagnostics;
+    using System.Linq;
+    using NUnit.Framework;
+    using WallstopStudios.UnityHelpers.Core.Extension;
+    using WallstopStudios.UnityHelpers.Core.Random;
+
+    public sealed class ListExtensionPerformanceTests
+    {
+        private sealed class IntComparer : IComparer<int>
+        {
+            public static readonly IntComparer Instance = new();
+
+            private IntComparer() { }
+
+            public int Compare(int x, int y)
+            {
+                return x.CompareTo(y);
+            }
+        }
+
+        [Test]
+        public void SortPerformanceTest()
+        {
+            const int NumInvocationsPerIteration = 100;
+            TimeSpan timeout = TimeSpan.FromSeconds(2.5);
+
+            PcgRandom random = new(123456);
+
+            List<int> list = Enumerable.Range(0, 1_000).ToList();
+            list.Shuffle(random);
+
+            int reference = RunTest(list, Array.Sort, timeout);
+            int insertionSort = RunTest(
+                list,
+                input => input.InsertionSort(IntComparer.Instance),
+                timeout
+            );
+            int shellSort = RunTest(
+                list,
+                input => input.ShellSortEnhanced(IntComparer.Instance),
+                timeout
+            );
+
+            UnityEngine.Debug.Log("| Operation | Operations / Second |");
+            UnityEngine.Debug.Log($"| Reference | {reference / timeout.TotalSeconds:N0} |");
+            UnityEngine.Debug.Log($"| InsertionSort | {insertionSort / timeout.TotalSeconds:N0} |");
+            UnityEngine.Debug.Log($"| ShellSort | {shellSort / timeout.TotalSeconds:N0} |");
+            return;
+
+            static int RunTest(List<int> input, Action<int[]> sorter, TimeSpan timeout)
+            {
+                int[] copy = input.ToArray();
+                int length = input.Count;
+
+                int[] toBeSorted = input.ToArray();
+                sorter(toBeSorted);
+                Assert.IsTrue(toBeSorted.IsSorted());
+                Array.Copy(copy, toBeSorted, length);
+
+                int count = 0;
+                Stopwatch timer = Stopwatch.StartNew();
+                do
+                {
+                    for (int i = 0; i < NumInvocationsPerIteration; ++i)
+                    {
+                        sorter(toBeSorted);
+                        Array.Copy(copy, toBeSorted, length);
+                        ++count;
+                    }
+                } while (timer.Elapsed < timeout);
+
+                return count;
+            }
+        }
+    }
+}

package/Tests/Runtime/Performance/ListExtensionPerformanceTests.cs.meta

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: f29dacd797514874baf87805f3804a39
+timeCreated: 1752462474

package/Tests/Runtime/Performance/RandomPerformanceTests.cs

@@ -7,7 +7,7 @@
 
     public sealed class RandomPerformanceTests
     {
-        private const int NumInvocationsPerIteration = 10_000;
+        private const int NumInvocationsPerIteration = 100_000;
 
         [Test]
         public void Benchmark()
@@ -21,17 +21,18 @@
                 "| ------ | -------- | ---- | -------- | --------- | ---------- | ---------------- | --------------- |"
             );
 
-            RunTest(new PcgRandom(), timeout);
-            RunTest(new SystemRandom(), timeout);
-            RunTest(new SquirrelRandom(), timeout);
-            RunTest(new XorShiftRandom(), timeout);
             RunTest(new DotNetRandom(), timeout);
-            RunTest(new WyRandom(), timeout);
-            RunTest(new SplitMix64(), timeout);
+            RunTest(new LinearCongruentialGenerator(), timeout);
+            RunTest(new PcgRandom(), timeout);
             RunTest(new RomuDuo(), timeout);
-            RunTest(new XorShiroRandom(), timeout);
+            RunTest(new SplitMix64(), timeout);
+            RunTest(new SquirrelRandom(), timeout);
+            RunTest(new SystemRandom(), timeout);
             RunTest(new UnityRandom(), timeout);
-            RunTest(new LinearCongruentialGenerator(), timeout);
+            RunTest(new WyRandom(), timeout);
+            RunTest(new XorShiftRandom(), timeout);
+            RunTest(new XoroShiroRandom(), timeout);
+            RunTest(new XoroShiroEnhancedRandom(), timeout);
         }
 
         private static void RunTest<T>(T random, TimeSpan timeout)

package/Tests/Runtime/Random/XoroShiroEnhancedRandomTests.cs

@@ -0,0 +1,12 @@
+namespace WallstopStudios.UnityHelpers.Tests.Random
+{
+    using WallstopStudios.UnityHelpers.Core.Random;
+
+    public sealed class XoroShiroEnhancedRandomTests : RandomTestBase
+    {
+        protected override IRandom NewRandom()
+        {
+            return new XoroShiroEnhancedRandom();
+        }
+    }
+}

package/Tests/Runtime/Random/XoroShiroEnhancedRandomTests.cs.meta

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: b501a5a45d604444bd01ff39d35de6e7
+timeCreated: 1752465449

package/Tests/Runtime/Random/XoroShiroRandomTests.cs

@@ -0,0 +1,9 @@
+namespace WallstopStudios.UnityHelpers.Tests.Random
+{
+    using WallstopStudios.UnityHelpers.Core.Random;
+
+    public sealed class XoroShiroRandomTests : RandomTestBase
+    {
+        protected override IRandom NewRandom() => new XoroShiroRandom();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "com.wallstop-studios.unity-helpers",
-  "version": "2.0.0-rc78.2",
+  "version": "2.0.0-rc78.4",
   "displayName": "Unity Helpers",
   "description": "Various Unity Helper Library",
   "dependencies": {},
@@ -38,61 +38,3 @@
 }
 
 
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-

package/Tests/Runtime/Random/XorShiroRandomTests.cs

@@ -1,9 +0,0 @@
-namespace WallstopStudios.UnityHelpers.Tests.Random
-{
-    using WallstopStudios.UnityHelpers.Core.Random;
-
-    public sealed class XorShiroRandomTests : RandomTestBase
-    {
-        protected override IRandom NewRandom() => new XorShiroRandom();
-    }
-}