From dfbd6a69c5eb3596dcaace26c70fdbd5085e821c Mon Sep 17 00:00:00 2001
From: GeWuYou <95328647+GeWuYou@users.noreply.github.com>
Date: Sun, 29 Mar 2026 22:54:00 +0800
Subject: [PATCH] =?UTF-8?q?feat(ArrayExtensions):=20=E6=B7=BB=E5=8A=A0?=
 =?UTF-8?q?=E4=BA=8C=E7=BB=B4=E6=95=B0=E7=BB=84=E6=89=A9=E5=B1=95=E6=96=B9?=
 =?UTF-8?q?=E6=B3=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 添加 GetOrDefault 方法用于获取越界时返回默认值的元素
- 添加 GetOr 方法用于获取越界时返回指定回退值的元素
- 添加 TryGet 方法用于尝试获取指定位置的元素
- 添加 GetNeighbors4 方法用于获取四个方向的邻居坐标
- 添加 GetNeighbors8 方法用于获取八个方向的邻居坐标
- 添加 Enumerate 方法用于枚举数组中所有元素及坐标
- 添加 Width 和 Height 方法分别获取数组宽高维度
- 在文件头注释中修复版权年份格式问题
---
 GFramework.Core/Extensions/ArrayExtensions.cs | 133 ++++++++++++++++++
 1 file changed, 133 insertions(+)

diff --git a/GFramework.Core/Extensions/ArrayExtensions.cs b/GFramework.Core/Extensions/ArrayExtensions.cs
index bc711f9..9f26b3a 100644
--- a/GFramework.Core/Extensions/ArrayExtensions.cs
+++ b/GFramework.Core/Extensions/ArrayExtensions.cs
@@ -32,4 +32,137 @@ public static class ArrayExtensions
                x < array.GetLength(0) &&
                y < array.GetLength(1);
     }
+
+
+    /// <summary>
+    /// 获取二维数组指定位置的元素，如果越界则返回默认值。
+    /// </summary>
+    /// <typeparam name="T">数组元素类型。</typeparam>
+    /// <param name="array">要访问的二维数组。</param>
+    /// <param name="x">X 坐标（第一维索引）。</param>
+    /// <param name="y">Y 坐标（第二维索引）。</param>
+    /// <returns>如果在边界内返回该位置的元素；否则返回类型的默认值。</returns>
+    public static T? GetOrDefault<T>(this T[,] array, int x, int y)
+    {
+        return array.IsInBounds(x, y) ? array[x, y] : default;
+    }
+
+    /// <summary>
+    /// 获取二维数组指定位置的元素，如果越界则返回指定的回退值。
+    /// </summary>
+    /// <typeparam name="T">数组元素类型。</typeparam>
+    /// <param name="array">要访问的二维数组。</param>
+    /// <param name="x">X 坐标（第一维索引）。</param>
+    /// <param name="y">Y 坐标（第二维索引）。</param>
+    /// <param name="fallback">当坐标越界时返回的回退值。</param>
+    /// <returns>如果在边界内返回该位置的元素；否则返回指定的回退值。</returns>
+    public static T GetOr<T>(this T[,] array, int x, int y, T fallback)
+    {
+        return array.IsInBounds(x, y) ? array[x, y] : fallback;
+    }
+
+    /// <summary>
+    /// 尝试获取二维数组指定位置的元素。
+    /// </summary>
+    /// <typeparam name="T">数组元素类型。</typeparam>
+    /// <param name="array">要访问的二维数组。</param>
+    /// <param name="x">X 坐标（第一维索引）。</param>
+    /// <param name="y">Y 坐标（第二维索引）。</param>
+    /// <param name="value">输出参数，用于存储获取到的元素值。</param>
+    /// <returns>如果成功获取元素则返回 true；否则返回 false。</returns>
+    public static bool TryGet<T>(this T[,] array, int x, int y, out T value)
+    {
+        if (array.IsInBounds(x, y))
+        {
+            value = array[x, y];
+            return true;
+        }
+
+        value = default!;
+        return false;
+    }
+
+    /// <summary>
+    /// 获取二维数组中某个位置的四个方向邻居坐标（上、下、左、右）。
+    /// </summary>
+    /// <typeparam name="T">数组元素类型。</typeparam>
+    /// <param name="array">源二维数组。</param>
+    /// <param name="x">中心位置的 X 坐标。</param>
+    /// <param name="y">中心位置的 Y 坐标。</param>
+    /// <returns>按顺序返回所有在边界内的邻居坐标。</returns>
+    public static IEnumerable<(int x, int y)> GetNeighbors4<T>(this T[,] array, int x, int y)
+    {
+        var dirs = new (int dx, int dy)[]
+        {
+            (0, -1), (0, 1),
+            (-1, 0), (1, 0)
+        };
+
+        foreach (var (dx, dy) in dirs)
+        {
+            var nx = x + dx;
+            var ny = y + dy;
+
+            if (array.IsInBounds(nx, ny))
+                yield return (nx, ny);
+        }
+    }
+
+    /// <summary>
+    /// 获取二维数组中某个位置的八个方向邻居坐标（包括对角线）。
+    /// </summary>
+    /// <typeparam name="T">数组元素类型。</typeparam>
+    /// <param name="array">源二维数组。</param>
+    /// <param name="x">中心位置的 X 坐标。</param>
+    /// <param name="y">中心位置的 Y 坐标。</param>
+    /// <returns>按顺序返回所有在边界内的邻居坐标（不包括中心位置）。</returns>
+    public static IEnumerable<(int x, int y)> GetNeighbors8<T>(this T[,] array, int x, int y)
+    {
+        for (var dx = -1; dx <= 1; dx++)
+        {
+            for (var dy = -1; dy <= 1; dy++)
+            {
+                if (dx == 0 && dy == 0) continue;
+
+                var nx = x + dx;
+                var ny = y + dy;
+
+                if (array.IsInBounds(nx, ny))
+                    yield return (nx, ny);
+            }
+        }
+    }
+
+    /// <summary>
+    /// 枚举二维数组中的所有元素及其坐标。
+    /// </summary>
+    /// <typeparam name="T">数组元素类型。</typeparam>
+    /// <param name="array">要枚举的二维数组。</param>
+    /// <returns>依次返回每个元素的坐标和值的元组。</returns>
+    public static IEnumerable<(int x, int y, T value)> Enumerate<T>(this T[,] array)
+    {
+        for (var x = 0; x < array.GetLength(0); x++)
+        {
+            for (var y = 0; y < array.GetLength(1); y++)
+            {
+                yield return (x, y, array[x, y]);
+            }
+        }
+    }
+
+    /// <summary>
+    /// 获取二维数组的宽度（第一维长度）。
+    /// </summary>
+    /// <typeparam name="T">数组元素类型。</typeparam>
+    /// <param name="array">要获取宽度的二维数组。</param>
+    /// <returns>数组的第一维长度。</returns>
+    public static int Width<T>(this T[,] array) => array.GetLength(0);
+
+    /// <summary>
+    /// 获取二维数组的高度（第二维长度）。
+    /// </summary>
+    /// <typeparam name="T">数组元素类型。</typeparam>
+    /// <param name="array">要获取高度的二维数组。</param>
+    /// <returns>数组的第二维长度。</returns>
+    public static int Height<T>(this T[,] array) => array.GetLength(1);
 }
\ No newline at end of file