feat: added some utility classes as the extended methods

Documentation/index.md

@@ -5,6 +5,7 @@ My utilities library for the UdonSharp / VRChat
 ## 💡 Features
 
 - 🌈 Logger with vivid colors
+- ⚙️ Some extended methods for the arrays, strings, and VRCPlayerApi
 
 ## 💻 System Requirements
 
@@ -24,7 +25,22 @@ My utilities library for the UdonSharp / VRChat
 
 ### 3. Use the utilities, enjoy :D
 
-(To be added)
+Example:
+
+```csharp
+using black.kit.toybox;
+
+public class Example : UdonSharpBehaviour
+{
+    public void Start()
+    {
+      // Example of using the Contains extension method
+      var array = new[] { 1, 2, 3, 4, 5 };
+      Debug.Log($"Contains(3): {array.Contains(3)}");
+      Debug.Log($"Contains(6): {array.Contains(6)}");
+    }
+}
+```
 
 ## License
 

Packages/black.kit.toybox/README.md

@@ -9,6 +9,7 @@ My utilities library for the UdonSharp / VRChat
 ## 💡 Features
 
 - 🌈 Logger with vivid colors
+- ⚙️ Some extended methods for the arrays, strings, and VRCPlayerApi
 
 ## 💻 System Requirements
 
@@ -28,7 +29,22 @@ My utilities library for the UdonSharp / VRChat
 
 ### 3. Use the utilities, enjoy :D
 
-(To be added)
+Example:
+
+```csharp
+using black.kit.toybox;
+
+public class Example : UdonSharpBehaviour
+{
+    public void Start()
+    {
+      // Example of using the Contains extension method
+      var array = new[] { 1, 2, 3, 4, 5 };
+      Debug.Log($"Contains(3): {array.Contains(3)}");
+      Debug.Log($"Contains(6): {array.Contains(6)}");
+    }
+}
+```
 
 ## API
 
@@ -38,6 +54,67 @@ All library components are in the `black.kit.toybox` namespace.
 using black.kit.toybox;
 ```
 
+### Extension methods
+
+#### `bool string.AreAllCharsContained(string chars)`
+
+Determine whether the string contains all the characters in the specified
+string.
+
+```csharp
+"abc".AreAllCharsContained("abcde"); // true
+"abc".AreAllCharsContained("abd"); // false
+"abc".AreAllCharsContained(null); // false
+
+string nullString = null;
+// true (always true if the string is null)
+nullString.AreAllCharsContained("abc");
+```
+
+#### `bool T[].Contains<T>(T value)`
+
+Determines whether the specified array contains the specified value.
+
+```csharp
+int[] array = new[] { 1, 2, 3, 4, 5 };
+array.Contains(3); // true
+array.Contains(6); // false
+
+int[] nullArray = null;
+nullArray.Contains(3); // false (always false if the array is null)
+```
+
+#### `string VRCPlayerApi.GetPlayerName(string fallback = null)`
+
+When the player is valid, return the player's name. Otherwise, it returns
+the specified fallback string.
+
+```csharp
+Networking.LocalPlayer.GetPlayerName("Unknown"); // "Kuroné Kito"
+```
+
+#### `string VRCPlayerApi.GetSafePlayerName(string safeCharset, string fallback = null)`
+
+When the player is valid, return the player's name with only the specified
+characters. Otherwise, it returns the specified fallback string.
+
+Note: The fallback string returns **WITHOUT** validation.
+
+```csharp
+Networking.LocalPlayer.GetSafePlayerName("ABCDEFGHIJKLMNOPQRSTUVWXYZ", "UNKNOWN") // "KURONEKITO"
+```
+
+#### `void GameObject[].SetActive(bool active)`
+
+Batch setting of game object activation status.
+
+```csharp
+// null elements are ignored automatically
+GameObject[] objects = new[] { object1, object2, null };
+objects.SetActive(true); // Activate all objects
+objects.SetActive(false); // Deactivate all objects
+```
+
 ## License
 
 This repository is licensed under the [MIT License](LICENSE).

Packages/black.kit.toybox/Runtime/Scripts/Utils/ArrayUtils.cs

@@ -0,0 +1,57 @@
+using System;
+using UnityEngine;
+
+namespace black.kit.toybox
+{
+    /// <summary>The utility class for arrays</summary>
+    public static class ArrayUtils
+    {
+        /// <summary>
+        /// Determines whether the specified array contains the specified
+        /// value.
+        /// </summary>
+        /// <typeparam name="T">Type of array elements</typeparam>
+        /// <param name="array">Array</param>
+        /// <param name="value">The value to contains</param>
+        /// <returns>
+        /// True if the specified array contains the specified value.
+        /// Otherwise, false.
+        /// </returns>
+        public static bool Contains<T>(
+            this T[] array, T value) where T : IEquatable<T>
+        {
+            if (array == null)
+            {
+                return false;
+            }
+            foreach (var obj in array)
+            {
+                if (obj.Equals(value))
+                {
+                    return true;
+                }
+            }
+            return false;
+        }
+
+        /// <summary>
+        /// Batch setting of game object activation status.
+        /// </summary>
+        /// <param name="array">Array of game objects</param>
+        /// <param name="active">New activation status</param>
+        public static void SetActive(this GameObject[] array, bool active)
+        {
+            if (array == null)
+            {
+                return;
+            }
+            foreach (var obj in array)
+            {
+                if (obj)
+                {
+                    obj.SetActive(active);
+                }
+            }
+        }
+    }
+}

Packages/black.kit.toybox/Runtime/Scripts/Utils/PlayerUtils.cs

@@ -0,0 +1,41 @@
+using VRC.SDKBase;
+
+namespace black.kit.toybox
+{
+    /// <summary>The utility class forVRCPlayerApi.</summary>
+    public static class PlayerUtils
+    {
+        /// <summary>Get the player name.</summary>
+        /// <param name="player">Player instance.</param>
+        /// <param name="fallback">Fallback name.</param>
+        /// <returns>player name</returns>
+        public static string GetPlayerName(
+            this VRCPlayerApi player, string fallback = null)
+        {
+            var concretePlayer = player ?? Networking.LocalPlayer;
+            return concretePlayer == null || !concretePlayer.IsValid()
+                ? fallback
+                : concretePlayer.displayName;
+        }
+
+        /// <summary>Get the safety player name.</summary>
+        /// <remarks>
+        /// Note: The fallback string returns <strong>WITHOUT</strong>
+        /// validation.
+        /// </remarks>
+        /// <param name="player">Player instance.</param>
+        /// <param name="safeCharset">
+        /// String containing characters to be checked.
+        /// </param>
+        /// <param name="fallback">Fallback name.</param>
+        /// <returns>player name</returns>
+        public static string GetSafePlayerName(
+            this VRCPlayerApi player, string safeCharset, string fallback = null)
+        {
+            var displayName = player.GetPlayerName(fallback);
+            return displayName.AreAllCharsContained(safeCharset)
+                ? displayName
+                : fallback;
+        }
+    }
+}

Packages/black.kit.toybox/Runtime/Scripts/Utils/StringUtils.cs

@@ -0,0 +1,39 @@
+namespace black.kit.toybox
+{
+    /// <summary>The utility class for strings</summary>
+    public static class StringUtils
+    {
+        /// <summary>
+        /// Determine whether the string contains all the characters
+        /// in the specified string.
+        /// </summary>
+        /// <param name="target">String to be checked.</param>
+        /// <param name="chars">
+        /// String containing characters to be checked.
+        /// </param>
+        /// <returns>
+        /// True if the string contains all the characters
+        /// in the specified string,
+        /// </returns>
+        public static bool AreAllCharsContained(
+            this string target, string chars)
+        {
+            if (string.IsNullOrEmpty(target))
+            {
+                return true;
+            }
+            if (string.IsNullOrEmpty(chars))
+            {
+                return false;
+            }
+            foreach (char c in target)
+            {
+                if (!chars.Contains(c.ToString()))
+                {
+                    return false;
+                }
+            }
+            return true;
+        }
+    }
+}

Packages/black.kit.toybox/Tests/Runtime/TestArrayUtils.cs

@@ -0,0 +1,47 @@
+using System.Linq;
+using NUnit.Framework;
+using UnityEngine;
+
+namespace black.kit.toybox.Tests
+{
+    /// <summary>Test class for <see cref="ArrayUtils"/>.</summary>
+    [TestFixture]
+    public sealed class TestArrayUtils
+    {
+        /// <summary>
+        /// Test for the <see cref="ArrayUtils.Contains{T}(T[], T)"/> method.
+        /// </summary>
+        [TestCase(new[] { 1, 2, 3 }, 2, ExpectedResult = true)]
+        [TestCase(new[] { 1, 2, 3 }, 4, ExpectedResult = false)]
+        [TestCase(null, 2, ExpectedResult = false)]
+        [TestCase(null, 4, ExpectedResult = false)]
+        public bool Contains(int[] array, int value) => array.Contains(value);
+
+        /// <summary>
+        /// Test for the <see cref="ArrayUtils.SetActive(GameObject[], bool)"/>
+        /// method.
+        /// </summary>
+        [Test]
+        public void SetActive()
+        {
+            GameObject[] array = { new(), null, new() };
+            var exists = array.Where(obj => obj);
+            Assert.DoesNotThrow(() => array.SetActive(true));
+            Assert.IsTrue(exists.All(obj => obj.activeSelf));
+            Assert.DoesNotThrow(() => array.SetActive(false));
+            Assert.IsFalse(exists.Any(obj => obj.activeSelf));
+        }
+
+        /// <summary>
+        /// Test for the <see cref="ArrayUtils.SetActive(GameObject[], bool)"/>
+        /// method.
+        /// </summary>
+        [Test]
+        public void SetActive_Null()
+        {
+            GameObject[] array = null;
+            Assert.DoesNotThrow(() => array.SetActive(true));
+            Assert.DoesNotThrow(() => array.SetActive(false));
+        }
+    }
+}