Align with coding standards

.github/workflows/package-and-push.yml

@@ -11,7 +11,7 @@ on:
 env:
   NUGET_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}
   REPOSITORY_URL:  https://nuget.pkg.github.com/${{ github.repository_owner }}/index.json
-  PROJECT_NAME: Utilities
+  PROJECT_NAME: FluffyVoid.Utilities
 jobs:
   build:
     runs-on: ubuntu-latest

Utilities.sln → FluffyVoid.Utilities.sln

@@ -1,6 +1,6 @@
 
 Microsoft Visual Studio Solution File, Format Version 12.00
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Utilities", "Utilities\Utilities.csproj", "{47E7E1A0-A17A-4FCB-8A25-3E1B063BDF2A}"
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "FluffyVoid.Utilities", "FluffyVoid.Utilities\FluffyVoid.Utilities.csproj", "{47E7E1A0-A17A-4FCB-8A25-3E1B063BDF2A}"
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution

FluffyVoid.Utilities/ArrayUtility.cs

@@ -0,0 +1,36 @@
+using FluffyVoid.Utilities.Formatters;
+
+namespace FluffyVoid.Utilities
+{
+    /// <summary>
+    ///     Organizational class for utilities that relate to arrays
+    /// </summary>
+    public static class ArrayUtility
+    {
+        /// <summary>
+        ///     Determines weather a specified index is within the bounds of an array
+        /// </summary>
+        /// <param name="source">Reference to the array calling the function</param>
+        /// <param name="index">The desired index to check</param>
+        /// <typeparam name="T">The type of the array's elements</typeparam>
+        /// <returns>True if the index is within the bounds of the array, otherwise false</returns>
+        public static bool InBounds<T>(this T[] source, int index)
+        {
+            return index < source.Length && index >= 0;
+        }
+        /// <summary>
+        ///     Converts an array to a string representation using the passed in string
+        ///     formatter
+        /// </summary>
+        /// <param name="value">The enum to convert</param>
+        /// <param name="formatter">The string formatter to use when converting to a string</param>
+        /// <returns>The user-friendly readable string</returns>
+        public static string? ToString<T>(this T[]          value,
+                                          IStringFormatter? formatter)
+        {
+            return formatter != null
+                ? formatter.ToString(value)
+                : value.ToString();
+        }
+    }
+}

FluffyVoid.Utilities/Cloning/IDeepCloneable.cs

@@ -0,0 +1,31 @@
+namespace FluffyVoid.Utilities.Cloning
+{
+    /// <summary>
+    ///     Defines a contract for any class wishing to enforce deep copy capabilities
+    /// </summary>
+    public interface IDeepCloneable
+    {
+        /// <summary>
+        ///     Returns a deep copy of the object to ensure that the returned copy is a
+        ///     unique entity, and not sharing references
+        ///     with the current object
+        /// </summary>
+        /// <returns>A new deeply copied version of the object</returns>
+        object DeepClone();
+    }
+
+    /// <summary>
+    ///     Defines a contract for any class wishing to enforce deep copy capabilities
+    /// </summary>
+    /// <typeparam name="T">The type of object that the class will be deep copying</typeparam>
+    public interface IDeepCloneable<out T> : IDeepCloneable
+    {
+        /// <summary>
+        ///     Returns a deep copy of the object to ensure that the returned copy is a
+        ///     unique entity, and not sharing references
+        ///     with the current object
+        /// </summary>
+        /// <returns>A new deeply copied version of the object</returns>
+        new T DeepClone();
+    }
+}

FluffyVoid.Utilities/Cloning/IShallowCloneable.cs

@@ -0,0 +1,29 @@
+namespace FluffyVoid.Utilities.Cloning
+{
+    /// <summary>
+    ///     Defines a contract for any class wishing to enforce shallow copy
+    ///     capabilities
+    /// </summary>
+    public interface IShallowCloneable
+    {
+        /// <summary>
+        ///     Returns a shallow copy of the object
+        /// </summary>
+        /// <returns>A new shallowly copied version of the object</returns>
+        object ShallowClone();
+    }
+
+    /// <summary>
+    ///     Defines a contract for any class wishing to enforce shallow copy
+    ///     capabilities
+    /// </summary>
+    /// <typeparam name="T">The type of object that the class will be shallow copying</typeparam>
+    public interface IShallowCloneable<out T> : IShallowCloneable
+    {
+        /// <summary>
+        ///     Returns a shallow copy of the object
+        /// </summary>
+        /// <returns>A new shallowly copied version of the object</returns>
+        new T ShallowClone();
+    }
+}

FluffyVoid.Utilities/DataStructures/AutoQueue.cs

@@ -0,0 +1,115 @@
+namespace FluffyVoid.Utilities.DataStructures
+{
+    /// <summary>
+    ///     Custom queue that can process IQueueable objects automatically with dynamic
+    ///     queue times for each item in the queue
+    /// </summary>
+    /// <typeparam name="T">The type of item to queue</typeparam>
+    public class AutoQueue<T>
+        where T : IQueueable
+    {
+        /// <summary>
+        ///     The amount of time that has elapsed for the current queued item
+        /// </summary>
+        private float _elapsed;
+        /// <summary>
+        ///     The amount of time to wait until dispatching the next queued item
+        /// </summary>
+        private float _interval;
+        /// <summary>
+        ///     Whether the queue system is currently running or is idle
+        /// </summary>
+        private bool _isRunning;
+        /// <summary>
+        ///     Collection of queued items
+        /// </summary>
+        private readonly Queue<T> _queuedItems;
+
+        /// <summary>
+        ///     Default constructor used to set up the queue
+        /// </summary>
+        public AutoQueue()
+        {
+            _queuedItems = new Queue<T>();
+        }
+        /// <summary>
+        ///     Enqueues an object for processing into the queue
+        /// </summary>
+        /// <param name="item">The item to queue</param>
+        public void Enqueue(T item)
+        {
+            if (!_isRunning)
+            {
+                item.Process();
+                _interval  = item.Time;
+                _elapsed   = 0.0f;
+                _isRunning = true;
+            }
+            else
+            {
+                _queuedItems.Enqueue(item);
+            }
+        }
+        /// <summary>
+        ///     Flushes the queue and processes all items in the queue immediately
+        /// </summary>
+        public void Flush()
+        {
+            while (_queuedItems.Count > 0)
+            {
+                T item = _queuedItems.Dequeue();
+                item.Process();
+            }
+
+            _isRunning = false;
+            _elapsed   = 0.0f;
+        }
+        /// <summary>
+        ///     Processes the next item in the queue, skipping any current wait time in
+        ///     effect
+        /// </summary>
+        // ReSharper disable once MemberCanBePrivate.Global
+        public void Next()
+        {
+            if (_queuedItems.Count > 0)
+            {
+                T item = _queuedItems.Dequeue();
+                _interval = item.Time;
+                _elapsed  = 0.0f;
+                item.Process();
+            }
+            else
+            {
+                _isRunning = false;
+                _elapsed   = 0.0f;
+            }
+        }
+        /// <summary>
+        ///     Resets the queue system back to its default state
+        /// </summary>
+        public void Reset()
+        {
+            _queuedItems.Clear();
+            _isRunning = false;
+            _elapsed   = 0.0f;
+        }
+        /// <summary>
+        ///     Updates the currently active queue time to dispatch items at variable
+        ///     intervals
+        /// </summary>
+        /// <param name="dt">The amount of time passed since the last call to Update</param>
+        public void Update(float dt)
+        {
+            if (!_isRunning)
+            {
+                return;
+            }
+
+            _elapsed += dt;
+            if (_elapsed >= _interval)
+            {
+                Next();
+            }
+        }
+    }
+}

FluffyVoid.Utilities/DataStructures/CachedItem.cs

@@ -0,0 +1,148 @@
+using FluffyVoid.Utilities.Formatters;
+using Newtonsoft.Json;
+
+namespace FluffyVoid.Utilities.DataStructures
+{
+    /// <summary>
+    ///     Wrapper for an object that allows for storing a working value that can be
+    ///     applied or reset
+    /// </summary>
+    /// <typeparam name="TType">The type to use as the value</typeparam>
+    [Serializable, JsonObject(MemberSerialization.OptIn),]
+    public class CachedItem<TType>
+        : DataItem<TType>
+    {
+        /// <summary>
+        ///     The actual value of the object, that is only updated to the working value
+        ///     upon Apply
+        /// </summary>
+        [JsonProperty]
+        public override TType? Value
+        {
+            get => CurrentValue;
+            set => WorkingValue = value;
+        }
+        /// <summary>
+        ///     The working value that is in flux until Apply or Reset is called
+        /// </summary>
+        public TType? WorkingValue { get; protected set; }
+
+        /// <summary>
+        ///     Constructor used to initialize the CachedItem
+        /// </summary>
+        public CachedItem()
+        {
+            WorkingValue = default;
+            Name         = "Data";
+        }
+        /// <summary>
+        ///     Constructor used to initialize the CachedItem
+        /// </summary>
+        /// <param name="startingValue">The value to assign to the working and true values</param>
+        public CachedItem(TType startingValue)
+        {
+            WorkingValue  = startingValue;
+            PreviousValue = default;
+            CurrentValue  = startingValue;
+            Name          = "Data";
+        }
+        /// <summary>
+        ///     Constructor used to initialize the CachedItem
+        /// </summary>
+        /// <param name="startingValue">The value to assign to the working and true values</param>
+        /// <param name="name">The name to assign to the data object</param>
+        public CachedItem(TType startingValue, string name)
+        {
+            WorkingValue  = startingValue;
+            PreviousValue = default;
+            CurrentValue  = startingValue;
+            Name          = name;
+        }
+        /// <summary>
+        ///     Constructor used to initialize the CachedItem
+        /// </summary>
+        /// <param name="startingValue">The value to assign to the working and true values</param>
+        /// <param name="name">The name to assign to the data object</param>
+        /// <param name="formatter">The string formatter to assign to the data object</param>
+        public CachedItem(TType                   startingValue,
+                          string                  name,
+                          IStringFormatter<TType> formatter)
+        {
+            WorkingValue  = startingValue;
+            PreviousValue = default;
+            CurrentValue  = startingValue;
+            Name          = name;
+            Formatter     = formatter;
+        }
+        /// <summary>
+        ///     Constructor used to initialize the CachedItem
+        /// </summary>
+        /// <param name="startingValue">The value to assign to the working and true values</param>
+        /// <param name="formatter">The string formatter to assign to the data object</param>
+        public CachedItem(TType                   startingValue,
+                          IStringFormatter<TType> formatter)
+        {
+            WorkingValue  = startingValue;
+            PreviousValue = default;
+            CurrentValue  = startingValue;
+            Name          = "Data";
+            Formatter     = formatter;
+        }
+
+        /// <summary>
+        ///     Applies the working value to the true value
+        /// </summary>
+        public void Apply()
+        {
+            PreviousValue = CurrentValue;
+            CurrentValue  = WorkingValue;
+            if (PreviousValue == null && CurrentValue != null)
+            {
+                OnValueChanged(default, CurrentValue);
+            }
+            else if (PreviousValue != null &&
+                     !PreviousValue.Equals(CurrentValue))
+            {
+                OnValueChanged(PreviousValue, CurrentValue);
+            }
+        }
+        /// <summary>
+        ///     Resets the working value back to the true value
+        /// </summary>
+        public void Reset()
+        {
+            WorkingValue = CurrentValue;
+        }
+        /// <summary>
+        ///     Allows setting of a value without triggering the ValueChanged event
+        /// </summary>
+        /// <param name="value">The value to set</param>
+        public override void SetWithoutNotify(TType value)
+        {
+            base.SetWithoutNotify(value);
+            WorkingValue = value;
+        }
+        /// <summary>
+        ///     ToString override that attempts to use an assigned string formatter if it
+        ///     can, otherwise it will ToString the
+        ///     current working value
+        /// </summary>
+        /// <returns>The string representation of this data object</returns>
+        public override string ToString()
+        {
+            if (Formatter != null)
+            {
+                string? result = Formatter.ToString(WorkingValue);
+                return result ?? string.Empty;
+            }
+
+            if (WorkingValue != null &&
+                !string.IsNullOrEmpty(WorkingValue.ToString()))
+            {
+                return WorkingValue.ToString()!;
+            }
+
+            return "null";
+        }
+    }
+}