com.wallstop-studios.unity-helpers 2.0.0-rc81.7 → 2.0.0-rc81.9

package/Runtime/Core/Helper/ArrayConverter.cs

@@ -1,39 +1,73 @@
-namespace WallstopStudios.UnityHelpers.Core.Helper
-{
-    using System;
-
-    public static class ArrayConverter
-    {
-        public static byte[] IntArrayToByteArrayBlockCopy(int[] ints)
-        {
-            if (ints == null)
-            {
-                throw new ArgumentNullException(nameof(ints));
-            }
-
-            byte[] bytes = new byte[ints.Length * sizeof(int)];
-            Buffer.BlockCopy(ints, 0, bytes, 0, bytes.Length);
-            return bytes;
-        }
-
-        public static int[] ByteArrayToIntArrayBlockCopy(byte[] bytes)
-        {
-            if (bytes == null)
-            {
-                throw new ArgumentNullException(nameof(bytes), "Byte array cannot be null.");
-            }
-
-            if (bytes.Length % sizeof(int) != 0)
-            {
-                throw new ArgumentException(
-                    $"Byte array length must be a multiple of {sizeof(int)}.",
-                    nameof(bytes)
-                );
-            }
-
-            int[] ints = new int[bytes.Length / sizeof(int)];
-            Buffer.BlockCopy(bytes, 0, ints, 0, bytes.Length);
-            return ints;
-        }
-    }
-}
+namespace WallstopStudios.UnityHelpers.Core.Helper
+{
+    using System;
+
+    /// <summary>
+    /// Provides high-performance array conversion methods using Buffer.BlockCopy for efficient memory operations.
+    /// </summary>
+    /// <remarks>
+    /// Thread Safety: All methods are thread-safe.
+    /// Performance: Uses Buffer.BlockCopy for optimal performance - significantly faster than element-by-element copying.
+    /// </remarks>
+    public static class ArrayConverter
+    {
+        /// <summary>
+        /// Converts an integer array to a byte array using Buffer.BlockCopy for high performance.
+        /// </summary>
+        /// <param name="ints">The integer array to convert.</param>
+        /// <returns>A byte array containing the binary representation of the integers (4 bytes per int).</returns>
+        /// <exception cref="ArgumentNullException">Thrown when ints is null.</exception>
+        /// <remarks>
+        /// Null handling: Throws ArgumentNullException if ints is null.
+        /// Thread-safe: Yes.
+        /// Performance: O(n) where n is array length. Uses native memory copy.
+        /// Allocations: Allocates new byte array of size (ints.Length * 4).
+        /// Edge cases: Empty array returns empty byte array. Endianness depends on system architecture.
+        /// </remarks>
+        public static byte[] IntArrayToByteArrayBlockCopy(int[] ints)
+        {
+            if (ints == null)
+            {
+                throw new ArgumentNullException(nameof(ints));
+            }
+
+            byte[] bytes = new byte[ints.Length * sizeof(int)];
+            Buffer.BlockCopy(ints, 0, bytes, 0, bytes.Length);
+            return bytes;
+        }
+
+        /// <summary>
+        /// Converts a byte array to an integer array using Buffer.BlockCopy for high performance.
+        /// </summary>
+        /// <param name="bytes">The byte array to convert. Must have length divisible by 4.</param>
+        /// <returns>An integer array reconstructed from the byte data (1 int per 4 bytes).</returns>
+        /// <exception cref="ArgumentNullException">Thrown when bytes is null.</exception>
+        /// <exception cref="ArgumentException">Thrown when byte array length is not a multiple of sizeof(int) (4).</exception>
+        /// <remarks>
+        /// Null handling: Throws ArgumentNullException if bytes is null.
+        /// Thread-safe: Yes.
+        /// Performance: O(n) where n is array length. Uses native memory copy.
+        /// Allocations: Allocates new integer array of size (bytes.Length / 4).
+        /// Edge cases: Empty array returns empty int array. Requires byte length to be multiple of 4. Endianness depends on system architecture.
+        /// </remarks>
+        public static int[] ByteArrayToIntArrayBlockCopy(byte[] bytes)
+        {
+            if (bytes == null)
+            {
+                throw new ArgumentNullException(nameof(bytes), "Byte array cannot be null.");
+            }
+
+            if (bytes.Length % sizeof(int) != 0)
+            {
+                throw new ArgumentException(
+                    $"Byte array length must be a multiple of {sizeof(int)}.",
+                    nameof(bytes)
+                );
+            }
+
+            int[] ints = new int[bytes.Length / sizeof(int)];
+            Buffer.BlockCopy(bytes, 0, ints, 0, bytes.Length);
+            return ints;
+        }
+    }
+}

package/Runtime/Core/Helper/ArrayConverter.cs.meta

@@ -1,3 +1,3 @@
-fileFormatVersion: 2
-guid: fa2c6f423a9448a59a9d243b1833d88d
+fileFormatVersion: 2
+guid: fa2c6f423a9448a59a9d243b1833d88d
 timeCreated: 1732491761

package/Runtime/Core/Helper/AssignUtilities.cs

@@ -1,14 +1,33 @@
-namespace WallstopStudios.UnityHelpers.Core.Helper
-{
-    public static class AssignUtilities
-    {
-        // Exchanges the assignTo to have the value of assignFrom.
-        // Returns the old value of AssignTo.
-        public static T Exchange<T>(ref T assignTo, T assignFrom)
-        {
-            T oldValue = assignTo;
-            assignTo = assignFrom;
-            return oldValue;
-        }
-    }
-}
+namespace WallstopStudios.UnityHelpers.Core.Helper
+{
+    /// <summary>
+    /// Provides utility methods for atomic value exchange operations.
+    /// </summary>
+    /// <remarks>
+    /// Thread Safety: Methods are not inherently thread-safe. For thread-safe exchanges, use Interlocked.Exchange.
+    /// Performance: O(1) operations with minimal overhead.
+    /// </remarks>
+    public static class AssignUtilities
+    {
+        /// <summary>
+        /// Atomically exchanges a variable's value and returns the old value.
+        /// </summary>
+        /// <typeparam name="T">The type of the values being exchanged.</typeparam>
+        /// <param name="assignTo">Reference to the variable to assign to.</param>
+        /// <param name="assignFrom">The new value to assign.</param>
+        /// <returns>The old value of assignTo before the exchange.</returns>
+        /// <remarks>
+        /// Null handling: Works with null values for reference types.
+        /// Thread-safe: No. Use Interlocked.Exchange for thread-safe operations.
+        /// Performance: O(1) - single assignment and return.
+        /// Allocations: None.
+        /// Edge cases: For reference types, both old and new values can be null.
+        /// </remarks>
+        public static T Exchange<T>(ref T assignTo, T assignFrom)
+        {
+            T oldValue = assignTo;
+            assignTo = assignFrom;
+            return oldValue;
+        }
+    }
+}

package/Runtime/Core/Helper/AssignUtilities.cs.meta

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

package/Runtime/Core/Helper/DirectoryHelper.cs

@@ -1,196 +1,210 @@
-namespace WallstopStudios.UnityHelpers.Core.Helper
-{
-    using System;
-    using System.IO;
-    using System.Runtime.CompilerServices;
-    using UnityEngine;
-#if UNITY_EDITOR
-    using UnityEditor;
-#endif
-
-    public static class DirectoryHelper
-    {
-        public static void EnsureDirectoryExists(string relativeDirectoryPath)
-        {
-            if (string.IsNullOrWhiteSpace(relativeDirectoryPath))
-            {
-                return;
-            }
-
-#if UNITY_EDITOR
-            if (!relativeDirectoryPath.StartsWith("Assets/"))
-            {
-                if (relativeDirectoryPath.Equals("Assets", StringComparison.OrdinalIgnoreCase))
-                {
-                    return;
-                }
-
-                Debug.LogError(
-                    $"Attempted to create directory outside of Assets: '{relativeDirectoryPath}'"
-                );
-                throw new ArgumentException(
-                    "Cannot create directories outside the Assets folder using AssetDatabase.",
-                    nameof(relativeDirectoryPath)
-                );
-            }
-
-            if (AssetDatabase.IsValidFolder(relativeDirectoryPath))
-            {
-                return;
-            }
-
-            string parentPath = Path.GetDirectoryName(relativeDirectoryPath).SanitizePath();
-            if (
-                string.IsNullOrWhiteSpace(parentPath)
-                || parentPath.Equals("Assets", StringComparison.OrdinalIgnoreCase)
-            )
-            {
-                string folderNameToCreate = Path.GetFileName(relativeDirectoryPath);
-                if (
-                    !string.IsNullOrWhiteSpace(folderNameToCreate)
-                    && !AssetDatabase.IsValidFolder(relativeDirectoryPath)
-                )
-                {
-                    AssetDatabase.CreateFolder("Assets", folderNameToCreate);
-                }
-                return;
-            }
-
-            EnsureDirectoryExists(parentPath);
-            string currentFolderName = Path.GetFileName(relativeDirectoryPath);
-            if (
-                !string.IsNullOrWhiteSpace(currentFolderName)
-                && !AssetDatabase.IsValidFolder(relativeDirectoryPath)
-            )
-            {
-                AssetDatabase.CreateFolder(parentPath, currentFolderName);
-                Debug.Log($"Created folder: {relativeDirectoryPath}");
-            }
-#else
-            Directory.CreateDirectory(relativeDirectoryPath);
-#endif
-        }
-
-        public static string GetCallerScriptDirectory([CallerFilePath] string sourceFilePath = "")
-        {
-            return string.IsNullOrWhiteSpace(sourceFilePath)
-                ? string.Empty
-                : Path.GetDirectoryName(sourceFilePath);
-        }
-
-        public static string FindPackageRootPath(string startDirectory)
-        {
-            return FindRootPath(
-                startDirectory,
-                path => File.Exists(Path.Combine(path, "package.json"))
-            );
-        }
-
-        public static string FindRootPath(
-            string startDirectory,
-            Func<string, bool> terminalCondition
-        )
-        {
-            string currentPath = startDirectory;
-            while (!string.IsNullOrWhiteSpace(currentPath))
-            {
-                try
-                {
-                    if (terminalCondition(currentPath))
-                    {
-                        DirectoryInfo directoryInfo = new(currentPath);
-                        if (!directoryInfo.Exists)
-                        {
-                            return currentPath;
-                        }
-
-                        return directoryInfo.FullName;
-                    }
-                }
-                catch
-                {
-                    return currentPath;
-                }
-
-                try
-                {
-                    string parentPath = Path.GetDirectoryName(currentPath);
-                    if (string.Equals(parentPath, currentPath, StringComparison.OrdinalIgnoreCase))
-                    {
-                        break;
-                    }
-
-                    currentPath = parentPath;
-                }
-                catch
-                {
-                    return currentPath;
-                }
-            }
-
-            return string.Empty;
-        }
-
-        public static string FindAbsolutePathToDirectory(string directory)
-        {
-            string scriptDirectory = GetCallerScriptDirectory();
-            if (string.IsNullOrEmpty(scriptDirectory))
-            {
-                return string.Empty;
-            }
-
-            string packageRootAbsolute = FindPackageRootPath(scriptDirectory);
-            if (string.IsNullOrEmpty(packageRootAbsolute))
-            {
-                return string.Empty;
-            }
-
-            string targetPathAbsolute = Path.Combine(
-                packageRootAbsolute,
-                directory.Replace('/', Path.DirectorySeparatorChar)
-            );
-
-            return AbsoluteToUnityRelativePath(targetPathAbsolute);
-        }
-
-        public static string AbsoluteToUnityRelativePath(string absolutePath)
-        {
-            if (string.IsNullOrWhiteSpace(absolutePath))
-            {
-                return string.Empty;
-            }
-
-            absolutePath = absolutePath.Replace('\\', '/');
-            string projectRoot = Application.dataPath.Replace('\\', '/');
-
-            projectRoot = Path.GetDirectoryName(projectRoot)?.Replace('\\', '/');
-            if (string.IsNullOrWhiteSpace(projectRoot))
-            {
-                return string.Empty;
-            }
-
-            if (absolutePath.StartsWith(projectRoot, StringComparison.OrdinalIgnoreCase))
-            {
-                // +1 to remove the leading slash only if projectRoot doesn't end with one
-                int startIndex = projectRoot.EndsWith("/", StringComparison.OrdinalIgnoreCase)
-                    ? projectRoot.Length
-                    : projectRoot.Length + 1;
-                return absolutePath.Length > startIndex ? absolutePath[startIndex..] : string.Empty;
-            }
-            if (absolutePath.StartsWith(projectRoot, StringComparison.OrdinalIgnoreCase))
-            {
-                int startIndex = projectRoot.EndsWith("/", StringComparison.OrdinalIgnoreCase)
-                    ? projectRoot.Length
-                    : projectRoot.Length + 1;
-                if (startIndex < absolutePath.Length)
-                {
-                    return "Assets/" + absolutePath[startIndex..];
-                }
-
-                return "Assets";
-            }
-
-            return string.Empty;
-        }
-    }
-}
+namespace WallstopStudios.UnityHelpers.Core.Helper
+{
+    using System;
+    using System.IO;
+    using System.Runtime.CompilerServices;
+    using UnityEngine;
+#if UNITY_EDITOR
+    using UnityEditor;
+#endif
+
+    /// <summary>
+    /// Helpers for creating and resolving directories in Unity projects.
+    /// </summary>
+    /// <remarks>
+    /// Editor paths are expected to be under the <c>Assets/</c> folder. Provides conversions between absolute and Unity-relative paths.
+    /// </remarks>
+    public static class DirectoryHelper
+    {
+        /// <summary>
+        /// Ensures a directory exists in the project. In the editor, the directory must be inside <c>Assets/</c> and is created via <c>AssetDatabase</c>.
+        /// </summary>
+        /// <param name="relativeDirectoryPath">Unity relative path (e.g., <c>Assets/MyFolder/Sub</c>).</param>
+        /// <exception cref="ArgumentException">Thrown if attempting to create a directory outside of <c>Assets/</c> in the editor.</exception>
+        public static void EnsureDirectoryExists(string relativeDirectoryPath)
+        {
+            if (string.IsNullOrWhiteSpace(relativeDirectoryPath))
+            {
+                return;
+            }
+
+#if UNITY_EDITOR
+            if (!relativeDirectoryPath.StartsWith("Assets/"))
+            {
+                if (relativeDirectoryPath.Equals("Assets", StringComparison.OrdinalIgnoreCase))
+                {
+                    return;
+                }
+
+                Debug.LogError(
+                    $"Attempted to create directory outside of Assets: '{relativeDirectoryPath}'"
+                );
+                throw new ArgumentException(
+                    "Cannot create directories outside the Assets folder using AssetDatabase.",
+                    nameof(relativeDirectoryPath)
+                );
+            }
+
+            if (AssetDatabase.IsValidFolder(relativeDirectoryPath))
+            {
+                return;
+            }
+
+            string parentPath = Path.GetDirectoryName(relativeDirectoryPath).SanitizePath();
+            if (
+                string.IsNullOrWhiteSpace(parentPath)
+                || parentPath.Equals("Assets", StringComparison.OrdinalIgnoreCase)
+            )
+            {
+                string folderNameToCreate = Path.GetFileName(relativeDirectoryPath);
+                if (
+                    !string.IsNullOrWhiteSpace(folderNameToCreate)
+                    && !AssetDatabase.IsValidFolder(relativeDirectoryPath)
+                )
+                {
+                    AssetDatabase.CreateFolder("Assets", folderNameToCreate);
+                }
+                return;
+            }
+
+            EnsureDirectoryExists(parentPath);
+            string currentFolderName = Path.GetFileName(relativeDirectoryPath);
+            if (
+                !string.IsNullOrWhiteSpace(currentFolderName)
+                && !AssetDatabase.IsValidFolder(relativeDirectoryPath)
+            )
+            {
+                AssetDatabase.CreateFolder(parentPath, currentFolderName);
+                Debug.Log($"Created folder: {relativeDirectoryPath}");
+            }
+#else
+            Directory.CreateDirectory(relativeDirectoryPath);
+#endif
+        }
+
+        /// <summary>
+        /// Gets the directory of the calling source file (useful for locating package-relative content).
+        /// </summary>
+        public static string GetCallerScriptDirectory([CallerFilePath] string sourceFilePath = "")
+        {
+            return string.IsNullOrWhiteSpace(sourceFilePath)
+                ? string.Empty
+                : Path.GetDirectoryName(sourceFilePath);
+        }
+
+        /// <summary>
+        /// Walks up the directory tree until a folder containing <c>package.json</c> is found.
+        /// </summary>
+        public static string FindPackageRootPath(string startDirectory)
+        {
+            return FindRootPath(
+                startDirectory,
+                path => File.Exists(Path.Combine(path, "package.json"))
+            );
+        }
+
+        /// <summary>
+        /// Walks up the directory tree until <paramref name="terminalCondition"/> returns true.
+        /// </summary>
+        public static string FindRootPath(
+            string startDirectory,
+            Func<string, bool> terminalCondition
+        )
+        {
+            string currentPath = startDirectory;
+            while (!string.IsNullOrWhiteSpace(currentPath))
+            {
+                try
+                {
+                    if (terminalCondition(currentPath))
+                    {
+                        DirectoryInfo directoryInfo = new(currentPath);
+                        if (!directoryInfo.Exists)
+                        {
+                            return currentPath;
+                        }
+
+                        return directoryInfo.FullName;
+                    }
+                }
+                catch
+                {
+                    return currentPath;
+                }
+
+                try
+                {
+                    string parentPath = Path.GetDirectoryName(currentPath);
+                    if (string.Equals(parentPath, currentPath, StringComparison.OrdinalIgnoreCase))
+                    {
+                        break;
+                    }
+
+                    currentPath = parentPath;
+                }
+                catch
+                {
+                    return currentPath;
+                }
+            }
+
+            return string.Empty;
+        }
+
+        /// <summary>
+        /// Resolves an absolute path to a directory relative to the package root and returns a Unity-relative path.
+        /// </summary>
+        public static string FindAbsolutePathToDirectory(string directory)
+        {
+            string scriptDirectory = GetCallerScriptDirectory();
+            if (string.IsNullOrEmpty(scriptDirectory))
+            {
+                return string.Empty;
+            }
+
+            string packageRootAbsolute = FindPackageRootPath(scriptDirectory);
+            if (string.IsNullOrEmpty(packageRootAbsolute))
+            {
+                return string.Empty;
+            }
+
+            string targetPathAbsolute = Path.Combine(
+                packageRootAbsolute,
+                directory.Replace('/', Path.DirectorySeparatorChar)
+            );
+
+            return AbsoluteToUnityRelativePath(targetPathAbsolute);
+        }
+
+        /// <summary>
+        /// Converts an absolute OS path to a Unity-relative path (e.g., <c>Assets/...</c>), or empty string if outside the project.
+        /// </summary>
+        public static string AbsoluteToUnityRelativePath(string absolutePath)
+        {
+            if (string.IsNullOrWhiteSpace(absolutePath))
+            {
+                return string.Empty;
+            }
+
+            absolutePath = absolutePath.SanitizePath();
+            string projectRoot = Application.dataPath.SanitizePath();
+
+            projectRoot = Path.GetDirectoryName(projectRoot)?.SanitizePath();
+            if (string.IsNullOrWhiteSpace(projectRoot))
+            {
+                return string.Empty;
+            }
+
+            if (absolutePath.StartsWith(projectRoot, StringComparison.OrdinalIgnoreCase))
+            {
+                // +1 to remove the leading slash only if projectRoot doesn't end with one
+                int startIndex = projectRoot.EndsWith("/", StringComparison.OrdinalIgnoreCase)
+                    ? projectRoot.Length
+                    : projectRoot.Length + 1;
+                return absolutePath.Length > startIndex ? absolutePath[startIndex..] : string.Empty;
+            }
+
+            return string.Empty;
+        }
+    }
+}

package/Runtime/Core/Helper/DirectoryHelper.cs.meta

@@ -1,3 +1,3 @@
-fileFormatVersion: 2
-guid: aefe35fe27e449f2b56e61a24c16cf62
+fileFormatVersion: 2
+guid: aefe35fe27e449f2b56e61a24c16cf62
 timeCreated: 1744994158