com.wallstop-studios.unity-helpers 2.0.0-rc76.1 → 2.0.0-rc76.2

package/Runtime/Core/DataStructure/Trie.cs

@@ -0,0 +1,359 @@
+namespace WallstopStudios.UnityHelpers.Core.DataStructure
+{
+    using System;
+    using System.Collections.Generic;
+    using System.Linq;
+    using System.Text;
+    using UnityEngine;
+
+    /// <summary>
+    /// A highly optimized, array-backed Trie implementation for fast prefix search and exact word lookup.
+    /// Preallocates storage based on total characters in the input set and uses integer indices for traversal,
+    /// minimizing memory allocations and indirections. Provides allocation-free prefix search method (aside from
+    /// returned string allocations).
+    /// </summary>
+    public sealed class Trie
+    {
+        private const int Poison = -1;
+
+        private readonly char[] _chars;
+        private readonly int[] _firstChild;
+        private readonly int[] _nextSibling;
+        private readonly bool[] _isWord;
+        private readonly StringBuilder _stringBuilder;
+        private int _nodeCount;
+
+        /// <summary>
+        /// Constructs the Trie from the provided collection of words.
+        /// </summary>
+        /// <param name="words">All possible words to insert into the Trie.</param>
+        public Trie(IEnumerable<string> words)
+        {
+            IReadOnlyList<string> wordList = words as IReadOnlyList<string> ?? words.ToList();
+            int maxWordLength;
+            if (wordList.Count > 0)
+            {
+                maxWordLength = wordList[0].Length;
+                for (int i = 1; i < wordList.Count; ++i)
+                {
+                    maxWordLength = Mathf.Max(maxWordLength, wordList[i].Length);
+                }
+            }
+            else
+            {
+                maxWordLength = 0;
+            }
+
+            int capacity = 1;
+            for (int i = 0; i < wordList.Count; ++i)
+            {
+                capacity += wordList[i].Length;
+            }
+
+            _chars = new char[capacity];
+            _firstChild = new int[capacity];
+            _nextSibling = new int[capacity];
+            _isWord = new bool[capacity];
+
+            Array.Fill(_firstChild, Poison);
+            Array.Fill(_nextSibling, Poison);
+
+            _stringBuilder = new StringBuilder(maxWordLength);
+
+            _nodeCount = 1; // root node index
+            for (int i = 0; i < wordList.Count; ++i)
+            {
+                string word = wordList[i];
+                Insert(word);
+            }
+        }
+
+        // Inserts a single word into the Trie
+        private void Insert(string word)
+        {
+            int node = 0;
+            foreach (char c in word)
+            {
+                int prev = Poison;
+                int child = _firstChild[node];
+                while (child != Poison && _chars[child] != c)
+                {
+                    prev = child;
+                    child = _nextSibling[child];
+                }
+                if (child == Poison)
+                {
+                    child = _nodeCount++;
+                    _chars[child] = c;
+                    _firstChild[child] = Poison;
+                    _nextSibling[child] = Poison;
+                    if (prev == Poison)
+                    {
+                        _firstChild[node] = child;
+                    }
+                    else
+                    {
+                        _nextSibling[prev] = child;
+                    }
+                }
+                node = child;
+            }
+            _isWord[node] = true;
+        }
+
+        /// <summary>
+        /// Determines whether the exact word exists in the Trie.
+        /// </summary>
+        public bool Contains(string word)
+        {
+            int node = 0;
+            foreach (char c in word)
+            {
+                int child = _firstChild[node];
+                while (child != Poison && _chars[child] != c)
+                {
+                    child = _nextSibling[child];
+                }
+
+                if (child == Poison)
+                {
+                    return false;
+                }
+
+                node = child;
+            }
+            return _isWord[node];
+        }
+
+        /// <summary>
+        /// Collects up to maxResults words that start with the given prefix.
+        /// Results are added into the provided list (which is cleared at the start).
+        /// Returns the number of results added.
+        /// </summary>
+        public int GetWordsWithPrefix(
+            string prefix,
+            List<string> results,
+            int maxResults = int.MaxValue
+        )
+        {
+            results.Clear();
+            int node = 0;
+            foreach (char c in prefix)
+            {
+                int child = _firstChild[node];
+                while (child != Poison && _chars[child] != c)
+                {
+                    child = _nextSibling[child];
+                }
+
+                if (child == Poison)
+                {
+                    return 0;
+                }
+
+                node = child;
+            }
+            _stringBuilder.Clear();
+            _stringBuilder.Append(prefix);
+            Collect(node, results, maxResults);
+            return results.Count;
+        }
+
+        // Recursive collection without allocations
+        private void Collect(int node, List<string> results, int maxResults)
+        {
+            if (results.Count >= maxResults)
+            {
+                return;
+            }
+
+            if (_isWord[node])
+            {
+                results.Add(_stringBuilder.ToString());
+                if (results.Count >= maxResults)
+                {
+                    return;
+                }
+            }
+            for (int child = _firstChild[node]; child != Poison; child = _nextSibling[child])
+            {
+                _stringBuilder.Append(_chars[child]);
+                Collect(child, results, maxResults);
+                _stringBuilder.Length--;
+                if (results.Count >= maxResults)
+                {
+                    return;
+                }
+            }
+        }
+    }
+
+    /// <summary>
+    /// A highly optimized, array-backed generic Trie for mapping string keys to values of type T.
+    /// Preallocates storage based on total characters in the key set and uses integer indices for traversal,
+    /// minimizing memory allocations and indirections. Provides allocation-free prefix search (aside from
+    /// the output list allocations themselves).
+    /// </summary>
+    public sealed class Trie<T>
+    {
+        private const int Poison = -1;
+
+        private readonly char[] _chars;
+        private readonly int[] _firstChild;
+        private readonly int[] _nextSibling;
+        private readonly bool[] _hasValue;
+        private readonly T[] _values;
+        private int _nodeCount;
+
+        /// <summary>
+        /// Constructs the Trie from the provided dictionary of keys to values.
+        /// </summary>
+        /// <param name="items">Mapping from unique string keys to values of type T.</param>
+        public Trie(IReadOnlyDictionary<string, T> items)
+        {
+            KeyValuePair<string, T>[] array = items.ToArray();
+            int capacity = 1;
+            foreach (KeyValuePair<string, T> entry in array)
+            {
+                capacity += entry.Key.Length;
+            }
+
+            _chars = new char[capacity];
+            _firstChild = new int[capacity];
+            _nextSibling = new int[capacity];
+            _hasValue = new bool[capacity];
+            _values = new T[capacity];
+
+            Array.Fill(_firstChild, Poison);
+            Array.Fill(_nextSibling, Poison);
+
+            _nodeCount = 1;
+            foreach (KeyValuePair<string, T> kv in array)
+            {
+                Insert(kv.Key, kv.Value);
+            }
+        }
+
+        // Inserts a single key-value pair into the Trie
+        private void Insert(string key, T value)
+        {
+            int node = 0;
+            foreach (char c in key)
+            {
+                int prev = Poison;
+                int child = _firstChild[node];
+                while (child != Poison && _chars[child] != c)
+                {
+                    prev = child;
+                    child = _nextSibling[child];
+                }
+                if (child == Poison)
+                {
+                    child = _nodeCount++;
+                    _chars[child] = c;
+                    _firstChild[child] = Poison;
+                    _nextSibling[child] = Poison;
+                    if (prev == Poison)
+                    {
+                        _firstChild[node] = child;
+                    }
+                    else
+                    {
+                        _nextSibling[prev] = child;
+                    }
+                }
+                node = child;
+            }
+            _hasValue[node] = true;
+            _values[node] = value;
+        }
+
+        /// <summary>
+        /// Attempts to retrieve the value associated with the exact key.
+        /// </summary>
+        public bool TryGetValue(string key, out T value)
+        {
+            int node = 0;
+            foreach (char c in key)
+            {
+                int child = _firstChild[node];
+                while (child != Poison && _chars[child] != c)
+                {
+                    child = _nextSibling[child];
+                }
+
+                if (child == Poison)
+                {
+                    value = default;
+                    return false;
+                }
+                node = child;
+            }
+            if (_hasValue[node])
+            {
+                value = _values[node];
+                return true;
+            }
+            value = default;
+            return false;
+        }
+
+        /// <summary>
+        /// Collects up to maxResults values whose keys start with the given prefix.
+        /// Results are added into the provided list (which is cleared at the start).
+        /// Returns the number of results added.
+        /// </summary>
+        public int GetValuesWithPrefix(
+            string prefix,
+            List<T> results,
+            int maxResults = int.MaxValue
+        )
+        {
+            results.Clear();
+            int node = 0;
+            foreach (char c in prefix)
+            {
+                int child = _firstChild[node];
+                while (child != Poison && _chars[child] != c)
+                {
+                    child = _nextSibling[child];
+                }
+
+                if (child == Poison)
+                {
+                    return 0;
+                }
+
+                node = child;
+            }
+            Collect(node, results, maxResults);
+            return results.Count;
+        }
+
+        // Recursive collection without extra allocations
+        private void Collect(int node, List<T> results, int maxResults)
+        {
+            if (results.Count >= maxResults)
+            {
+                return;
+            }
+
+            if (_hasValue[node])
+            {
+                results.Add(_values[node]);
+                if (results.Count >= maxResults)
+                {
+                    return;
+                }
+            }
+            for (int child = _firstChild[node]; child != Poison; child = _nextSibling[child])
+            {
+                Collect(child, results, maxResults);
+                if (results.Count >= maxResults)
+                {
+                    return;
+                }
+            }
+        }
+    }
+}

package/Runtime/Core/DataStructure/Trie.cs.meta

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: 6693302ec09144868fbf8da3c5f1c298
+timeCreated: 1748539006

package/Runtime/Core/Helper/UnityMainThreadDispatcher.cs

@@ -11,6 +11,8 @@
     {
         private readonly ConcurrentQueue<Action> _actions = new();
 
+        protected override bool Preserve => false;
+
 #if UNITY_EDITOR
         private readonly EditorApplication.CallbackFunction _update;
         private bool _attachedEditorUpdate;
@@ -31,7 +33,7 @@
         private void OnEnable()
         {
 #if UNITY_EDITOR
-            if (!_attachedEditorUpdate)
+            if (!_attachedEditorUpdate && !Application.isPlaying)
             {
                 EditorApplication.update += _update;
                 _attachedEditorUpdate = true;

package/Runtime/Core/Threading/SingleThreadedThreadPool.cs

@@ -16,14 +16,19 @@
         private AutoResetEvent _waitHandle;
         private bool _disposed;
         private readonly ConcurrentQueue<Exception> _exceptions;
+        private readonly TimeSpan _noWorkWaitTime;
 
-        public SingleThreadedThreadPool(bool runInBackground = false)
+        public SingleThreadedThreadPool(
+            bool runInBackground = false,
+            TimeSpan? noWorkWaitTime = null
+        )
         {
             _active = 1;
             _working = 1;
             _work = new ConcurrentQueue<Action>();
             _exceptions = new ConcurrentQueue<Exception>();
             _waitHandle = new AutoResetEvent(false);
+            _noWorkWaitTime = noWorkWaitTime ?? TimeSpan.FromSeconds(1);
             _worker = new Thread(DoWork) { IsBackground = runInBackground };
             _worker.Start();
         }
@@ -95,7 +100,7 @@
                     {
                         try
                         {
-                            _ = _waitHandle?.WaitOne(TimeSpan.FromSeconds(1));
+                            _ = _waitHandle?.WaitOne(_noWorkWaitTime);
                         }
                         catch (ObjectDisposedException)
                         {

package/Runtime/UI/LayeredImage.cs

@@ -4,7 +4,6 @@
     using System.Collections.Generic;
     using System.Diagnostics;
     using System.Linq;
-    using System.Threading;
     using System.Threading.Tasks;
     using Core.Extension;
     using Core.Helper;

package/Tests/Runtime/DataStructures/SpatialTreeTests.cs

@@ -34,7 +34,8 @@
 
             TTree quadTree = CreateTree(points);
 
-            List<Vector2> pointsInRange = quadTree.GetElementsInRange(center, radius).ToList();
+            List<Vector2> pointsInRange = new();
+            quadTree.GetElementsInRange(center, radius, pointsInRange);
             Assert.IsTrue(
                 points.SetEquals(pointsInRange),
                 "Found {0} points in range, expected {1}.",
@@ -46,7 +47,7 @@
             offset.x -= radius * 2;
             offset.y -= radius * 2;
 
-            pointsInRange = quadTree.GetElementsInRange(offset, radius).ToList();
+            quadTree.GetElementsInRange(offset, radius, pointsInRange);
             Assert.AreEqual(
                 0,
                 pointsInRange.Count,
@@ -69,11 +70,10 @@
             List<Vector2> points = new(1) { testPoint };
 
             TTree quadTree = CreateTree(points);
-            List<Vector2> pointsInRange = quadTree
-                .GetElementsInRange(point, range * 0.99f)
-                .ToList();
+            List<Vector2> pointsInRange = new();
+            quadTree.GetElementsInRange(point, range * 0.99f, pointsInRange).ToList();
             Assert.AreEqual(0, pointsInRange.Count);
-            pointsInRange = quadTree.GetElementsInRange(point, range * 1.01f).ToList();
+            quadTree.GetElementsInRange(point, range * 1.01f, pointsInRange);
             Assert.AreEqual(
                 1,
                 pointsInRange.Count,

package/Tests/Runtime/Performance/QuadTreePerformanceTests.cs

@@ -8,7 +8,7 @@
     {
         protected override QuadTree<Vector2> CreateTree(IEnumerable<Vector2> points)
         {
-            return new QuadTree<Vector2>(points, _ => _);
+            return new QuadTree<Vector2>(points, x => x);
         }
     }
 }

package/Tests/Runtime/Performance/SpatialTreePerformanceTest.cs

@@ -24,21 +24,19 @@
 
             Vector2[] points = new Vector2[1_000_000];
             float radius = 500;
-            ParallelLoopResult result = Parallel.For(
+            Parallel.For(
                 0,
-                1_000_000,
-                index =>
+                1_000,
+                y =>
                 {
-                    // ReSharper disable once PossibleLossOfFraction
-                    points[index] = new Vector2(index % 1_000, index / 1_000);
+                    for (int x = 0; x < 1_000; ++x)
+                    {
+                        int index = y * 1_000 + x;
+                        points[index] = new Vector2(x, y);
+                    }
                 }
             );
 
-            while (!result.IsCompleted)
-            {
-                yield return null;
-            }
-
             Stopwatch timer = Stopwatch.StartNew();
             TTree tree = CreateTree(points);
             timer.Stop();
@@ -49,10 +47,12 @@
             int count = 0;
             TimeSpan timeout = TimeSpan.FromSeconds(1);
             timer.Restart();
+            List<Vector2> elementsInRange = new();
             do
             {
-                int elementsInRange = tree.GetElementsInRange(center, radius).Count();
-                Assert.AreEqual(785456, elementsInRange);
+                tree.GetElementsInRange(center, radius, elementsInRange);
+                int elementCount = elementsInRange.Count;
+                Assert.AreEqual(785456, elementCount);
                 ++count;
             } while (timer.Elapsed < timeout);
 
@@ -65,8 +65,9 @@
             timer.Restart();
             do
             {
-                int elementsInRange = tree.GetElementsInRange(center, radius).Count();
-                Assert.AreEqual(196364, elementsInRange);
+                tree.GetElementsInRange(center, radius, elementsInRange);
+                int elementCount = elementsInRange.Count;
+                Assert.AreEqual(196364, elementCount);
                 ++count;
             } while (timer.Elapsed < timeout);
             UnityEngine.Debug.Log(
@@ -78,8 +79,9 @@
             timer.Restart();
             do
             {
-                int elementsInRange = tree.GetElementsInRange(center, radius).Count();
-                Assert.AreEqual(49080, elementsInRange);
+                tree.GetElementsInRange(center, radius, elementsInRange);
+                int elementCount = elementsInRange.Count;
+                Assert.AreEqual(49080, elementCount);
                 ++count;
             } while (timer.Elapsed < timeout);
             UnityEngine.Debug.Log(
@@ -91,8 +93,9 @@
             timer.Restart();
             do
             {
-                int elementsInRange = tree.GetElementsInRange(center, radius).Count();
-                Assert.AreEqual(4, elementsInRange);
+                tree.GetElementsInRange(center, radius, elementsInRange);
+                int elementCount = elementsInRange.Count;
+                Assert.AreEqual(4, elementCount);
                 ++count;
             } while (timer.Elapsed < timeout);
             UnityEngine.Debug.Log(
@@ -149,6 +152,8 @@
                 ++count;
             } while (timer.Elapsed < timeout);
             UnityEngine.Debug.Log($"| ANN - 1 | {(int)Math.Floor(count / timeout.TotalSeconds)} |");
+
+            yield break;
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "com.wallstop-studios.unity-helpers",
-  "version": "2.0.0-rc76.1",
+  "version": "2.0.0-rc76.2",
   "displayName": "Unity Helpers",
   "description": "Various Unity Helper Library",
   "dependencies": {},
@@ -75,5 +75,6 @@
 
 
 
+