# dseapp.arrayutils

**Repository Path**: wangyunchina/dseapp.arrayutils

## Basic Information

- **Project Name**: dseapp.arrayutils
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-20
- **Last Updated**: 2026-01-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DseApp.ArrayUtils

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

## 特性

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

## 安装

```bash
dotnet add package DseApp.ArrayUtils
```

## 快速开始

```csharp
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)`
获取数组形状信息。

## 性能优化

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

```csharp
// 传统方法：每次都重新计算索引
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

## 示例

### 二维数组操作

```csharp
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);
```

### 三维数组操作

```csharp
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
```

### 类型转换

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

### 数组遍历操作

#### 直接修改元素值

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

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

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

#### 函数式遍历

```csharp
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);  // 平方每个元素
```

#### 只读遍历

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

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

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

#### 复杂遍历示例

```csharp
// 三维数组的条件修改
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;
});
```

### 数组形状变换

#### 二维数组转一维数组

```csharp
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]
```

#### 一维数组转多维数组

```csharp
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);
```

#### 自动类型推断

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

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

#### 获取数组形状信息

```csharp
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)
从多维数组中提取子数组（切片）。

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

### 数组转置 (Transpose)
交换数组的维度顺序。

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

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

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

### 数组连接 (Concatenate)
沿指定维度连接多个数组。

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

### 数组分割 (Split)
将数组沿指定维度分割为多个子数组。

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

### 统计函数
计算数组的统计信息。

```csharp
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);
```

### 条件查找
查找满足条件的元素。

```csharp
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);
```

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

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

### 序列化辅助
将数组与字节流相互转换（仅支持非托管类型）。

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

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

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

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

```csharp
// 等差序列
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！