com.wallstop-studios.unity-helpers 2.0.4 → 2.1.1

package/{node_modules.meta → Tests/Editor/Tags.meta}

@@ -1,5 +1,5 @@
 fileFormatVersion: 2
-guid: 337a8b4396958284d9f2eb2de3b9ab3d
+guid: 43bfcdf80a014948b5377ffa29afa8df
 folderAsset: yes
 DefaultImporter:
   externalObjects: {}

package/Tests/Editor/Utils/ScriptableObjectSingletonTests.cs

@@ -34,6 +34,8 @@ namespace WallstopStudios.UnityHelpers.Tests.Editor.Utils
             yield return null;
             DeleteAssetIfExists("Assets/Resources/CustomPath/CustomPathSingleton.asset");
             yield return null;
+            DeleteFolderIfEmpty("Assets/Resources/CustomPath");
+            yield return null;
 
             // For nested test types, Unity cannot create valid .asset files (no script file).
             // Instead, create in-memory instances so the singleton loader can discover them via FindObjectsOfTypeAll.
@@ -81,6 +83,43 @@ namespace WallstopStudios.UnityHelpers.Tests.Editor.Utils
             }
         }
 
+        private static void DeleteFolderIfEmpty(string folderPath)
+        {
+            if (string.IsNullOrWhiteSpace(folderPath))
+            {
+                return;
+            }
+
+            if (!AssetDatabase.IsValidFolder(folderPath))
+            {
+                return;
+            }
+
+            string[] subFolders = AssetDatabase.GetSubFolders(folderPath);
+            if (subFolders != null && subFolders.Length > 0)
+            {
+                return;
+            }
+
+            string[] assetGuids = AssetDatabase.FindAssets(string.Empty, new[] { folderPath });
+            for (int i = 0; i < assetGuids.Length; i++)
+            {
+                string guid = assetGuids[i];
+                string assetPath = AssetDatabase.GUIDToAssetPath(guid);
+                if (
+                    !string.IsNullOrEmpty(assetPath)
+                    && !string.Equals(assetPath, folderPath, System.StringComparison.Ordinal)
+                )
+                {
+                    return;
+                }
+            }
+
+            AssetDatabase.DeleteAsset(folderPath);
+            AssetDatabase.SaveAssets();
+            AssetDatabase.Refresh();
+        }
+
         private static TType CreateInMemoryInstance<TType>()
             where TType : ScriptableObject
         {
@@ -144,6 +183,8 @@ namespace WallstopStudios.UnityHelpers.Tests.Editor.Utils
             AssetDatabase.SaveAssets();
             AssetDatabase.Refresh();
             yield return null;
+            DeleteFolderIfEmpty("Assets/Resources/CustomPath");
+            yield return null;
             // Prefer public API surface over reflection to clean up the cached instance
             if (TestSingleton.HasInstance)
             {

package/Tests/Runtime/Extensions/IListExtensionTests.cs

@@ -17,6 +17,14 @@ namespace WallstopStudios.UnityHelpers.Tests.Extensions
             public int Compare(int x, int y) => x.CompareTo(y);
         }
 
+        private sealed class StableTupleComparer : IComparer<ValueTuple<int, int>>
+        {
+            public int Compare(ValueTuple<int, int> x, ValueTuple<int, int> y)
+            {
+                return x.Item1.CompareTo(y.Item1);
+            }
+        }
+
         private readonly struct IntEqualityComparer : IEqualityComparer<int>
         {
             public bool Equals(int x, int y) => x == y;
@@ -135,7 +143,7 @@ namespace WallstopStudios.UnityHelpers.Tests.Extensions
         }
 
         [Test]
-        public void ShellSortEnhanced()
+        public void GhostSort()
         {
             for (int i = 0; i < NumTries; ++i)
             {
@@ -153,6 +161,120 @@ namespace WallstopStudios.UnityHelpers.Tests.Extensions
             }
         }
 
+        [Test]
+        public void MeteorSort()
+        {
+            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[] meteorSorted = input.ToArray();
+                meteorSorted.MeteorSort(new IntComparer());
+                Assert.That(conventionalSorted, Is.EqualTo(meteorSorted));
+                Assert.That(input.OrderBy(x => x), Is.EqualTo(meteorSorted));
+            }
+        }
+
+        [Test]
+        public void PatternDefeatingQuickSort()
+        {
+            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[] pdqSorted = input.ToArray();
+                pdqSorted.PatternDefeatingQuickSort(new IntComparer());
+                Assert.That(conventionalSorted, Is.EqualTo(pdqSorted));
+                Assert.That(input.OrderBy(x => x), Is.EqualTo(pdqSorted));
+            }
+        }
+
+        [Test]
+        public void GrailSort()
+        {
+            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[] grailSorted = input.ToArray();
+                grailSorted.GrailSort(new IntComparer());
+                Assert.That(conventionalSorted, Is.EqualTo(grailSorted));
+                Assert.That(input.OrderBy(x => x), Is.EqualTo(grailSorted));
+            }
+        }
+
+        [Test]
+        public void PowerSort()
+        {
+            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[] powerSorted = input.ToArray();
+                powerSorted.PowerSort(new IntComparer());
+                Assert.That(conventionalSorted, Is.EqualTo(powerSorted));
+                Assert.That(input.OrderBy(x => x), Is.EqualTo(powerSorted));
+            }
+        }
+
+        [Test]
+        public void GrailSortIsStable()
+        {
+            ValueTuple<int, int>[] input = Enumerable
+                .Range(0, 100)
+                .Select(i => ValueTuple.Create(i / 5, i))
+                .ToArray();
+            ValueTuple<int, int>[] grailSorted = input.ToArray();
+            grailSorted.GrailSort(new StableTupleComparer());
+
+            for (int i = 1; i < grailSorted.Length; ++i)
+            {
+                if (grailSorted[i - 1].Item1 == grailSorted[i].Item1)
+                {
+                    Assert.That(grailSorted[i - 1].Item2, Is.LessThan(grailSorted[i].Item2));
+                }
+            }
+        }
+
+        [Test]
+        public void PowerSortIsStable()
+        {
+            ValueTuple<int, int>[] input = Enumerable
+                .Range(0, 100)
+                .Select(i => ValueTuple.Create(i / 4, i))
+                .ToArray();
+            ValueTuple<int, int>[] powerSorted = input.ToArray();
+            powerSorted.PowerSort(new StableTupleComparer());
+
+            for (int i = 1; i < powerSorted.Length; ++i)
+            {
+                if (powerSorted[i - 1].Item1 == powerSorted[i].Item1)
+                {
+                    Assert.That(powerSorted[i - 1].Item2, Is.LessThan(powerSorted[i].Item2));
+                }
+            }
+        }
+
         [Test]
         public void SortDefaultAlgorithm()
         {
@@ -731,6 +853,70 @@ namespace WallstopStudios.UnityHelpers.Tests.Extensions
             Assert.That(single, Is.EqualTo(new[] { 42 }));
         }
 
+        [Test]
+        public void PatternDefeatingQuickSortEmptyList()
+        {
+            int[] empty = Array.Empty<int>();
+            empty.PatternDefeatingQuickSort(new IntComparer());
+            Assert.That(empty, Is.Empty);
+        }
+
+        [Test]
+        public void PatternDefeatingQuickSortSingleElement()
+        {
+            int[] single = { 42 };
+            single.PatternDefeatingQuickSort(new IntComparer());
+            Assert.That(single, Is.EqualTo(new[] { 42 }));
+        }
+
+        [Test]
+        public void GrailSortEmptyList()
+        {
+            int[] empty = Array.Empty<int>();
+            empty.GrailSort(new IntComparer());
+            Assert.That(empty, Is.Empty);
+        }
+
+        [Test]
+        public void GrailSortSingleElement()
+        {
+            int[] single = { 42 };
+            single.GrailSort(new IntComparer());
+            Assert.That(single, Is.EqualTo(new[] { 42 }));
+        }
+
+        [Test]
+        public void PowerSortEmptyList()
+        {
+            int[] empty = Array.Empty<int>();
+            empty.PowerSort(new IntComparer());
+            Assert.That(empty, Is.Empty);
+        }
+
+        [Test]
+        public void PowerSortSingleElement()
+        {
+            int[] single = { 42 };
+            single.PowerSort(new IntComparer());
+            Assert.That(single, Is.EqualTo(new[] { 42 }));
+        }
+
+        [Test]
+        public void MeteorSortEmptyList()
+        {
+            int[] empty = Array.Empty<int>();
+            empty.MeteorSort(new IntComparer());
+            Assert.That(empty, Is.Empty);
+        }
+
+        [Test]
+        public void MeteorSortSingleElement()
+        {
+            int[] single = { 42 };
+            single.MeteorSort(new IntComparer());
+            Assert.That(single, Is.EqualTo(new[] { 42 }));
+        }
+
         [Test]
         public void CombinedOperationsShuffleThenSort()
         {

package/Tests/Runtime/Helper/ObjectsTests.cs

@@ -343,8 +343,8 @@ namespace WallstopStudios.UnityHelpers.Tests.Helper
             CustomEnumerable ascending = new(1, 2, 3);
             CustomEnumerable descending = new(3, 2, 1);
 
-            int ascHash = Objects.EnumerableHashCode<int>(ascending);
-            int descHash = Objects.EnumerableHashCode<int>(descending);
+            int ascHash = Objects.EnumerableHashCode(ascending);
+            int descHash = Objects.EnumerableHashCode(descending);
 
             Assert.AreNotEqual(ascHash, descHash);
         }
@@ -354,7 +354,7 @@ namespace WallstopStudios.UnityHelpers.Tests.Helper
         {
             DisposableEnumerable enumerable = new(1, 2, 3);
 
-            int result = Objects.EnumerableHashCode<int>(enumerable);
+            int result = Objects.EnumerableHashCode(enumerable);
 
             Assert.AreNotEqual(0, result);
             Assert.IsTrue(enumerable.LastEnumerator.WasDisposed);

package/Tests/Runtime/Integrations/Reflex/RelationalComponentsReflexTests.cs

@@ -321,7 +321,7 @@ namespace WallstopStudios.UnityHelpers.Tests.Integrations.Reflex
             GameObject root = Track(new GameObject("ReflexComponentPrefab"));
             ReflexRelationalTester tester = root.AddComponent<ReflexRelationalTester>();
 
-            GameObject child = new GameObject("ReflexComponentPrefabChild");
+            GameObject child = new("ReflexComponentPrefabChild");
             child.AddComponent<CapsuleCollider>();
             child.transform.SetParent(root.transform, false);
 
@@ -334,7 +334,7 @@ namespace WallstopStudios.UnityHelpers.Tests.Integrations.Reflex
             GameObject root = Track(new GameObject("ReflexGameObjectPrefab"));
             root.AddComponent<ReflexRelationalTester>();
 
-            GameObject child = new GameObject("ReflexGameObjectPrefabChild");
+            GameObject child = new("ReflexGameObjectPrefabChild");
             child.AddComponent<CapsuleCollider>();
             child.transform.SetParent(root.transform, false);
 

package/Tests/Runtime/Performance/IListSortingPerformanceTests.cs

@@ -0,0 +1,346 @@
+namespace WallstopStudios.UnityHelpers.Tests.Performance
+{
+    using System;
+    using System.Collections.Generic;
+    using System.Diagnostics;
+    using System.Globalization;
+    using System.Text;
+    using NUnit.Framework;
+    using UnityEngine;
+    using WallstopStudios.UnityHelpers.Core.Extension;
+    using WallstopStudios.UnityHelpers.Core.Random;
+
+    public sealed class IListSortingPerformanceTests
+    {
+        private const string DocumentPath = "Docs/ILIST_SORTING_PERFORMANCE.md";
+        private const string SectionPrefix = "ILIST_SORT_";
+        private const int NearlySortedSwapPercentage = 50;
+
+        private static readonly DatasetSizeSpec[] DatasetSizeSpecs =
+        {
+            new DatasetSizeSpec("100", 100),
+            new DatasetSizeSpec("1,000", 1_000),
+            new DatasetSizeSpec("10,000", 10_000),
+            new DatasetSizeSpec("100,000", 100_000),
+            new DatasetSizeSpec("1,000,000", 1_000_000),
+        };
+
+        private static readonly DatasetState[] DatasetStates =
+        {
+            new DatasetState("Sorted", BuildSortedData),
+            new DatasetState("Nearly Sorted (2% swaps)", BuildNearlySortedData),
+            new DatasetState("Shuffled (deterministic)", BuildShuffledData),
+        };
+
+        private static readonly SortImplementation[] SortImplementations =
+        {
+            new SortImplementation("Ghost", SortAlgorithm.Ghost, false, int.MaxValue),
+            new SortImplementation("Meteor", SortAlgorithm.Meteor, false, int.MaxValue),
+            new SortImplementation(
+                "Pattern-Defeating QuickSort",
+                SortAlgorithm.PatternDefeatingQuickSort,
+                false,
+                int.MaxValue
+            ),
+            new SortImplementation("Grail", SortAlgorithm.Grail, true, int.MaxValue),
+            new SortImplementation("Power", SortAlgorithm.Power, true, int.MaxValue),
+            new SortImplementation("Insertion", SortAlgorithm.Insertion, true, 10_000),
+        };
+
+        [Test]
+        [Timeout(0)]
+        public void Benchmark()
+        {
+            string operatingSystemToken = GetOperatingSystemToken();
+            string sectionName = SectionPrefix + operatingSystemToken;
+
+            List<string> readmeLines = new List<string>
+            {
+                string.Format(
+                    CultureInfo.InvariantCulture,
+                    "_Last updated {0:yyyy-MM-dd HH:mm} UTC on {1}_",
+                    DateTime.UtcNow,
+                    SystemInfo.operatingSystem
+                ),
+                string.Empty,
+                "Times are single-pass measurements in milliseconds (lower is better). `n/a` indicates the algorithm was skipped for the dataset size.",
+                string.Empty,
+            };
+
+            IComparer<int> comparer = Comparer<int>.Default;
+            string headerLine = BuildHeaderLine();
+            string dividerLine = BuildDividerLine();
+
+            foreach (DatasetState datasetState in DatasetStates)
+            {
+                UnityEngine.Debug.Log($"IList Sorting Benchmarks - {datasetState.Label}");
+                UnityEngine.Debug.Log(headerLine);
+                UnityEngine.Debug.Log(dividerLine);
+
+                readmeLines.Add($"### {datasetState.Label}");
+                readmeLines.Add(headerLine);
+                readmeLines.Add(dividerLine);
+
+                foreach (DatasetSizeSpec sizeSpec in DatasetSizeSpecs)
+                {
+                    int[] baseData = datasetState.CreateData(sizeSpec.Count);
+                    string rowLine = BuildRowLine(sizeSpec.Label, baseData, comparer);
+                    UnityEngine.Debug.Log(rowLine);
+                    readmeLines.Add(rowLine);
+                }
+
+                readmeLines.Add(string.Empty);
+                UnityEngine.Debug.Log(string.Empty);
+            }
+
+            BenchmarkReadmeUpdater.UpdateSection(sectionName, readmeLines, DocumentPath);
+        }
+
+        private static string BuildHeaderLine()
+        {
+            StringBuilder headerBuilder = new StringBuilder();
+            headerBuilder.Append("| List Size |");
+            foreach (SortImplementation implementation in SortImplementations)
+            {
+                headerBuilder.Append(' ');
+                headerBuilder.Append(implementation.Label);
+                headerBuilder.Append(" |");
+            }
+
+            return headerBuilder.ToString();
+        }
+
+        private static string BuildDividerLine()
+        {
+            StringBuilder dividerBuilder = new StringBuilder();
+            dividerBuilder.Append("| --- |");
+            foreach (SortImplementation implementation in SortImplementations)
+            {
+                dividerBuilder.Append(" --- |");
+            }
+
+            return dividerBuilder.ToString();
+        }
+
+        private static string BuildRowLine(
+            string sizeLabel,
+            int[] baseData,
+            IComparer<int> comparer
+        )
+        {
+            StringBuilder rowBuilder = new StringBuilder();
+            rowBuilder.Append("| ");
+            rowBuilder.Append(sizeLabel);
+            rowBuilder.Append(" |");
+
+            foreach (SortImplementation implementation in SortImplementations)
+            {
+                string result = BenchmarkImplementation(implementation, baseData, comparer);
+                rowBuilder.Append(' ');
+                rowBuilder.Append(result);
+                rowBuilder.Append(" |");
+            }
+
+            return rowBuilder.ToString();
+        }
+
+        private static string BenchmarkImplementation(
+            SortImplementation implementation,
+            int[] baseData,
+            IComparer<int> comparer
+        )
+        {
+            if (baseData.Length > implementation.MaxSupportedCount)
+            {
+                return "n/a";
+            }
+
+            int[] workingData = new int[baseData.Length];
+            Array.Copy(baseData, workingData, baseData.Length);
+
+            IList<int> workingList = workingData;
+            Stopwatch stopwatch = Stopwatch.StartNew();
+
+            try
+            {
+                implementation.Execute(workingList, comparer);
+            }
+            catch (Exception exception)
+            {
+                UnityEngine.Debug.LogError(
+                    $"Sorting benchmark failed for {implementation.Label}: {exception.Message}"
+                );
+                return "error";
+            }
+            finally
+            {
+                stopwatch.Stop();
+            }
+
+            double milliseconds = stopwatch.Elapsed.TotalMilliseconds;
+            return FormatDuration(milliseconds);
+        }
+
+        private static string FormatDuration(double milliseconds)
+        {
+            if (milliseconds >= 1000d)
+            {
+                double seconds = milliseconds / 1000d;
+                return string.Format(CultureInfo.InvariantCulture, "{0:0.00} s", seconds);
+            }
+
+            if (milliseconds >= 100d)
+            {
+                return string.Format(CultureInfo.InvariantCulture, "{0:0} ms", milliseconds);
+            }
+
+            if (milliseconds >= 10d)
+            {
+                return string.Format(CultureInfo.InvariantCulture, "{0:0.0} ms", milliseconds);
+            }
+
+            if (milliseconds >= 1d)
+            {
+                return string.Format(CultureInfo.InvariantCulture, "{0:0.00} ms", milliseconds);
+            }
+
+            return string.Format(CultureInfo.InvariantCulture, "{0:0.000} ms", milliseconds);
+        }
+
+        private static int[] BuildSortedData(int count)
+        {
+            int[] data = new int[count];
+            for (int i = 0; i < count; ++i)
+            {
+                data[i] = i;
+            }
+
+            return data;
+        }
+
+        private static int[] BuildNearlySortedData(int count)
+        {
+            int[] data = BuildSortedData(count);
+            if (count <= 1)
+            {
+                return data;
+            }
+
+            int swaps = Math.Max(1, count / NearlySortedSwapPercentage);
+            IRandom random = new PcgRandom(unchecked(count * 37));
+
+            for (int i = 0; i < swaps; ++i)
+            {
+                int index = random.Next(0, count - 1);
+                int neighbor = Math.Min(count - 1, index + 1);
+                int temp = data[index];
+                data[index] = data[neighbor];
+                data[neighbor] = temp;
+            }
+
+            return data;
+        }
+
+        private static int[] BuildShuffledData(int count)
+        {
+            int[] data = BuildSortedData(count);
+            if (count <= 1)
+            {
+                return data;
+            }
+
+            IRandom random = new PcgRandom(unchecked(count * 7919));
+
+            for (int i = count - 1; i > 0; --i)
+            {
+                int swapIndex = random.Next(0, i + 1);
+                int temp = data[i];
+                data[i] = data[swapIndex];
+                data[swapIndex] = temp;
+            }
+
+            return data;
+        }
+
+        private static string GetOperatingSystemToken()
+        {
+            RuntimePlatform platform = Application.platform;
+            switch (platform)
+            {
+                case RuntimePlatform.WindowsEditor:
+                case RuntimePlatform.WindowsPlayer:
+                case RuntimePlatform.WindowsServer:
+                    return "WINDOWS";
+                case RuntimePlatform.OSXEditor:
+                case RuntimePlatform.OSXPlayer:
+                    return "MACOS";
+                case RuntimePlatform.LinuxEditor:
+                case RuntimePlatform.LinuxPlayer:
+                case RuntimePlatform.LinuxServer:
+                    return "LINUX";
+                default:
+                    return "OTHER";
+            }
+        }
+
+        private readonly struct DatasetSizeSpec
+        {
+            public DatasetSizeSpec(string label, int count)
+            {
+                Label = label;
+                Count = count;
+            }
+
+            public string Label { get; }
+
+            public int Count { get; }
+        }
+
+        private readonly struct DatasetState
+        {
+            private readonly Func<int, int[]> generator;
+
+            public DatasetState(string label, Func<int, int[]> generator)
+            {
+                Label = label;
+                this.generator = generator;
+            }
+
+            public string Label { get; }
+
+            public int[] CreateData(int count)
+            {
+                return generator(count);
+            }
+        }
+
+        private readonly struct SortImplementation
+        {
+            public SortImplementation(
+                string label,
+                SortAlgorithm algorithm,
+                bool isStable,
+                int maxSupportedCount
+            )
+            {
+                Label = label;
+                Algorithm = algorithm;
+                IsStable = isStable;
+                MaxSupportedCount = maxSupportedCount;
+            }
+
+            public string Label { get; }
+
+            public SortAlgorithm Algorithm { get; }
+
+            public bool IsStable { get; }
+
+            public int MaxSupportedCount { get; }
+
+            public void Execute(IList<int> list, IComparer<int> comparer)
+            {
+                list.Sort(comparer, Algorithm);
+            }
+        }
+    }
+}

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

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: c840f3e2d6f3912498b363680b22a1b2
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Tests/Runtime/Performance/RandomPerformanceTests.cs

@@ -31,12 +31,15 @@ namespace WallstopStudios.UnityHelpers.Tests.Performance
             LogRow(RunTest(new PcgRandom(), timeout));
             LogRow(RunTest(new RomuDuo(), timeout));
             LogRow(RunTest(new SplitMix64(), timeout));
+            LogRow(RunTest(new FlurryBurstRandom(), timeout));
             LogRow(RunTest(new SquirrelRandom(), timeout));
             LogRow(RunTest(new SystemRandom(), timeout));
             LogRow(RunTest(new UnityRandom(), timeout));
             LogRow(RunTest(new WyRandom(), timeout));
             LogRow(RunTest(new XorShiftRandom(), timeout));
             LogRow(RunTest(new XoroShiroRandom(), timeout));
+            LogRow(RunTest(new PhotonSpinRandom(), timeout));
+            LogRow(RunTest(new StormDropRandom(), timeout));
 
             BenchmarkReadmeUpdater.UpdateSection(
                 "RANDOM_BENCHMARKS",