DseApp.ArrayUtils 1.3.0

DseApp.ArrayUtils

高性能的多维数组一维读写工具类，支持任意维度和基本类型的数组操作。

特性

• ✅ 支持任意维度数组（1D、2D、3D...N维）
• ✅ 支持所有基本类型（int、double、float、bool、string等）
• ✅ 高性能的批量写入操作
• ✅ 类型安全的泛型设计
• ✅ 完善的错误处理和边界检查
• ✅ 跨平台支持（.NET Standard 2.0+）
• ✅ 支持数组遍历和直接修改元素值
• ✅ 提供多种遍历模式（直接修改、函数式、只读）

安装

dotnet add package DseApp.ArrayUtils

快速开始

using DseApp.ArrayUtils;

// 创建二维数组
int[,] matrix = new int[3, 4];

// 单个值读写
ArrayUtils.Write(matrix, 42, 5);  // 在线性索引5位置写入42
int value = ArrayUtils.Read<int>(matrix, 5);  // 读取线性索引5的值

// 批量写入
int[] data = new int[] { 100, 200, 300, 400 };
ArrayUtils.Write(matrix, data, 2);  // 从索引2开始批量写入

// 获取数组信息
int totalLength = ArrayUtils.GetLength(matrix);  // 返回12
string shapeInfo = ArrayUtils.GetShapeInfo(matrix);  // "Rank: 2, Dimensions: [3, 4], Length: 12"

API 参考

核心方法

Read<T>(Array src, int index)

从任意维度数组中按线性索引读取值。

Write<T>(Array src, T value, int index)

向任意维度数组中按线性索引写入值。

Write<T>(Array src, T[] values, int startIndex)

批量向任意维度数组中按起始线性索引写入一维数组数据（高性能版本）。

GetLength(Array src)

获取任意维度数组的总元素个数。

GetLinearIndex(Array src, params int[] indices)

从多维索引获取线性索引。

GetShapeInfo(Array src)

获取数组形状信息。

性能优化

批量写入操作采用了优化的索引递进算法，避免了重复的索引计算：

// 传统方法：每次都重新计算索引
for (int i = 0; i < values.Length; i++)
{
    int[] indices = GetIndicesFromLinearIndex(src, startIndex + i); // O(rank)
    src.SetValue(values[i], indices);
}
// 总复杂度：O(n × rank)

// 优化方法：递进式索引更新
int[] indices = GetIndicesFromLinearIndex(src, startIndex); // 只计算一次
for (int i = 0; i < values.Length; i++)
{
    src.SetValue(values[i], indices);
    IncrementIndices(indices, dimensions); // O(1) 平均复杂度
}
// 总复杂度：O(n + rank)

支持的框架

• .NET Standard 2.0
• .NET Standard 2.1
• .NET 6.0
• .NET 7.0
• .NET 8.0

示例

二维数组操作

int[,] matrix = new int[3, 4];

// 初始化
for (int i = 0; i < ArrayUtils.GetLength(matrix); i++)
{
    ArrayUtils.Write(matrix, i + 1, i);
}

// 读取特定位置
Console.WriteLine(ArrayUtils.Read<int>(matrix, 5)); // 输出: 6

// 批量修改
int[] newData = { 100, 200, 300 };
ArrayUtils.Write(matrix, newData, 3);

三维数组操作

int[,,] cube = new int[2, 3, 4];
int[] data = new int[24];

for (int i = 0; i < data.Length; i++)
{
    data[i] = i + 1;
}

ArrayUtils.Write(cube, data, 0);
Console.WriteLine(ArrayUtils.Read<int>(cube, 23)); // 输出: 24

类型转换

double[,] doubleMatrix = new double[2, 2];
ArrayUtils.Write(doubleMatrix, 3.14159, 0);
double pi = ArrayUtils.Read<double>(doubleMatrix, 0);

数组遍历操作

直接修改元素值

int[,] matrix = { { 1, 2 }, { 3, 4 } };

// 使用ActionRef直接修改元素值
ArrayUtils.Foreach<int>(matrix, (ref int x) => {
    x *= 2;  // 直接赋值修改
});

// 结果：{ { 2, 4 }, { 6, 8 } }

函数式遍历

string[,] grid = new string[2, 3];

// 使用Func返回新值
ArrayUtils.Foreach<string>(grid, x => x?.ToUpper() ?? "EMPTY");

// 对于数值数组
int[,] numbers = { { 1, 2 }, { 3, 4 } };
ArrayUtils.Foreach<int>(numbers, x => x * x);  // 平方每个元素

只读遍历

int[,] data = { { 10, 20 }, { 30, 40 } };
int sum = 0;

// 只读遍历，用于统计或计算
ArrayUtils.ForeachReadOnly<int>(data, x => {
    sum += x;
});

Console.WriteLine($"总和: {sum}");  // 输出: 100

复杂遍历示例

// 三维数组的条件修改
int[,,] cube = new int[2, 3, 4];
for (int i = 0; i < ArrayUtils.GetLength(cube); i++)
{
    ArrayUtils.Write(cube, i + 1, i);
}

// 将所有偶数设为0，奇数加倍
ArrayUtils.Foreach<int>(cube, (ref int x) => {
    if (x % 2 == 0)
        x = 0;
    else
        x *= 2;
});

数组形状变换

二维数组转一维数组

int[,] matrix2D = { { 1, 2, 3 }, { 4, 5, 6 } }; // 2x3 = 6 elements

// 转换为一维数组
int[] array1D = (int[])ArrayUtils.Reshape<int>(matrix2D, 6);
// 结果：[1, 2, 3, 4, 5, 6]

一维数组转多维数组

int[] data = new int[12] { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 };

// 转换为3x4二维数组
int[,] matrix = (int[,])ArrayUtils.Reshape<int>(data, 3, 4);

// 转换为2x2x3三维数组
int[,,] cube = (int[,,])ArrayUtils.Reshape<int>(data, 2, 2, 3);

自动类型推断

double[,] doubleMatrix = new double[2, 3];
// ... 填充数据 ...

// 自动推断类型转换为4x3矩阵
double[,] reshaped = (double[,])ArrayUtils.Reshape(doubleMatrix, 4, 3);

获取数组形状信息

int[,,] cube = new int[2, 3, 4];
int[] shape = ArrayUtils.GetShape(cube);
// shape = [2, 3, 4]

int[,] matrix = new int[5, 8];
int[] matrixShape = ArrayUtils.GetShape(matrix);
// matrixShape = [5, 8]

API 参考

核心方法

Read<T>(Array src, int index)

从任意维度数组中按线性索引读取值。

Write<T>(Array src, T value, int index)

向任意维度数组中按线性索引写入值。

Write<T>(Array src, T[] values, int startIndex)

批量向任意维度数组中按起始线性索引写入一维数组数据（高性能版本）。

GetLength(Array src)

获取任意维度数组的总元素个数。

GetLinearIndex(Array src, params int[] indices)

从多维索引获取线性索引。

GetShapeInfo(Array src)

获取数组形状信息。

遍历方法

Foreach<T>(Array src, ActionRef<T> action)

遍历数组并对每个元素执行操作，支持通过ref参数直接修改元素值。

Foreach<T>(Array src, Func<T, T> action)

遍历数组并对每个元素执行函数式操作，使用返回的新值更新数组。

ForeachReadOnly<T>(Array src, Action<T> action)

遍历数组并对每个元素执行只读操作，不修改原数组内容。

数组形状操作

Reshape<T>(Array src, params int[] newShape)

改变数组的形状（重新调整维度），保持总元素个数不变。

Reshape(Array src, params int[] newShape)

自动推断元素类型的数组形状变换。

GetShape(Array src)

获取数组的形状信息（各维度长度）。

新增功能

数组切片 (Slice)

从多维数组中提取子数组（切片）。

int[,] matrix = new int[4, 5];
// ... 填充数据 ...
var sliced = ArrayUtils.Slice(matrix, (1, 3), (2, 4));
// 获取行1-2、列2-3的子数组

数组转置 (Transpose)

交换数组的维度顺序。

int[,] matrix = new int[3, 4];
// ... 填充数据 ...
var transposed = ArrayUtils.Transpose(matrix);
// 3x4 变为 4x3

数组填充 (Fill)

用指定值填充数组的全部或部分区域。

int[,] matrix = new int[3, 4];
// 填充整个数组
ArrayUtils.Fill(matrix, 42);
// 填充指定区域（从索引5开始，填充3个元素）
ArrayUtils.Fill(matrix, 99, 5, 3);

数组连接 (Concatenate)

沿指定维度连接多个数组。

int[,] matrix1 = new int[2, 3];
int[,] matrix2 = new int[2, 3];
// ... 填充数据 ...
var concatenated = ArrayUtils.Concatenate(new[] { matrix1, matrix2 }, axis: 1);
// 沿列方向连接，得到 2x6 数组

数组分割 (Split)

将数组沿指定维度分割为多个子数组。

int[,] matrix = new int[6, 4];
// ... 填充数据 ...
var parts = ArrayUtils.Split(matrix, new[] { 3 }, axis: 0);
// 沿行方向分成3个 2x4 数组

统计函数

计算数组的统计信息。

int[,] matrix = new int[3, 4];
// ... 填充数据 ...
int sum = ArrayUtils.Sum<int>(matrix);
double average = ArrayUtils.Average<int>(matrix);
int max = ArrayUtils.Max<int>(matrix);
int min = ArrayUtils.Min<int>(matrix);

条件查找

查找满足条件的元素。

int[,] matrix = new int[3, 4];
// ... 填充数据 ...
// 查找所有偶数的索引
var evenIndices = ArrayUtils.Where<int>(matrix, x => x % 2 == 0).ToList();
// 查找第一个值为10的索引
int firstIndex = ArrayUtils.FindFirst<int>(matrix, 10);

类型转换

将数组元素转换为另一种类型。

int[,] intMatrix = new int[2, 3];
// ... 填充数据 ...
var doubleMatrix = ArrayUtils.Convert<int, double>(intMatrix, x => x * 1.5);

序列化辅助

将数组与字节流相互转换（仅支持非托管类型）。

int[,] original = new int[3, 4];
// ... 填充数据 ...
byte[] bytes = ArrayUtils.ToBytes<int>(original);
var restored = ArrayUtils.FromBytes<int>(bytes, 3, 4);

克隆与复制

创建数组的深度副本或复制部分数据。

int[,] original = new int[3, 4];
// ... 填充数据 ...
// 深度克隆
var cloned = ArrayUtils.Clone(original);
// 复制部分数据
int[,] destination = new int[3, 4];
ArrayUtils.Copy(original, destination, 2, 5, 4);

数组生成

生成具有特定模式的数组。

// 等差序列
int[] arange = ArrayUtils.Arange<int>(0, 10, 2); // [0, 2, 4, 6, 8]
// 等间隔序列
double[] linspace = ArrayUtils.Linspace<double>(0, 1, 5); // [0, 0.25, 0.5, 0.75, 1]

贡献

欢迎提交 Issue 和 Pull Request！