重构

Foundation/c_Matrix.h

@@ -1,90 +1,102 @@
 #ifndef INCLUDED_C_MATRIX_H
 #define INCLUDED_C_MATRIX_H
 
-#ifndef INCLUDED_C_ARRAY_H
-#include <c_Array.h>
-#endif /*INCLUDED_C_ARRAY_H*/
+#ifndef INCLUDED_C_TYPES_H
+#include <c_Types.h>
+#endif /*INCLUDED_C_TYPES_H*/
+
+
+#ifndef INCLUDED_C_ALLOCATOR_H
+#include <c_Allocator.h>
+#endif /*INCLUDED_C_ALLOCATOR_H*/
 
 
 /* ------------------------------------------------------------------------------------------------------------------ */
 /*  */
 
-// “主元全为0”而触发矩阵奇异错误
-#define C_ERR_SINGULAR C_ERR_FAIL
+// 元素对元素算子：将 a 和 b 运算后的结果写入 out 中
+typedef void (*c_Matrix_OpFn_t)(void* out, const void* a, const void* b, void* ud);
+
+// 变号算子：将 in 取负（或执行共轭对调等）后写入 out 中
+typedef void (*c_Matrix_NegFn_t)(void* out, const void* in, void* ud);
 
-/* ------------------------------------------------------------------------------------------------------------------ */
-/*  */
 
 typedef struct {
-    c_Array_t* array;  // 内部封装的一维泛型数组
-    c_size_t rows;     // 矩阵行数
-    c_size_t cols;     // 矩阵列数
-}c_Matrix_t;
-
-// 泛型数学算子包
-typedef struct {
-    void (*zero)(void* out);                            // 设为 0
-    void (*one)(void* out);                             // 设为 1
-    void (*add)(const void* a, const void* b, void* out); // out = a + b
-    void (*sub)(const void* a, const void* b, void* out); // out = a - b
-    void (*mul)(const void* a, const void* b, void* out); // out = a * b
-    void (*div)(const void* a, const void* b, void* out); // out = a / b
-    int  (*is_zero)(const void* a);                     // 判断是否为 0 (或接近 0)
-    int  (*compare_abs)(const void* a, const void* b);   // 绝对值比较：|a| > |b| 返回 1, 否则返回 0
-} c_MatrixOps_t;
+    void* data;               // 一维扁平化的连续行优先（Row-Major）存储区
+    c_size_t rows;            // 矩阵的固定总行数
+    c_size_t cols;            // 矩阵的固定总列数
+    c_size_t item_size;       // 单个元素的字节大小
+    c_Allocator_t allocator;  // 内部绑定的自主内存管理器
+} c_Matrix_t;
 
 /* ------------------------------------------------------------------------------------------------------------------ */
 /*  */
 
-c_err_t c_Matrix_Init(c_Matrix_t* self, c_size_t rows, c_size_t cols, c_size_t element_size);
+c_err_t c_Matrix_Init(c_Matrix_t* self, c_size_t rows, c_size_t cols, c_size_t item_size, c_Allocator_t* allocator);
+void    c_Matrix_Destroy(c_Matrix_t* self);
 
-void c_Matrix_Destroy(c_Matrix_t* self);
+// 核心定点操作 API (安全值复制模式)
+c_err_t c_Matrix_Write(c_Matrix_t* self, c_size_t r, c_size_t c, const void* item);
+c_err_t c_Matrix_Read(const c_Matrix_t* self, c_size_t r, c_size_t c, void* out_item);
+void*   c_Matrix_Get(const c_Matrix_t* self, c_size_t r, c_size_t c);
 
-c_size_t c_Matrix_ElementSize(c_Matrix_t* self);
+// 矩阵高级辅助操作
+c_err_t c_Matrix_Fill(c_Matrix_t* self, const void* item);
+c_err_t c_Matrix_CopyRow(const c_Matrix_t* self, c_size_t r, void* out_row_buffer);
 
-c_err_t c_Matrix_Get(c_Matrix_t* self, c_size_t row, c_size_t col, void** value);
-
-c_err_t c_Matrix_Put(c_Matrix_t* self, c_size_t row, c_size_t col, void* value);
+// 内联高频辅助接口
+C_STATIC_FORCE_INLINE c_size_t c_Matrix_Rows(const c_Matrix_t* self) { return self ? self->rows : 0; }
+C_STATIC_FORCE_INLINE c_size_t c_Matrix_Cols(const c_Matrix_t* self) { return self ? self->cols : 0; }
 
 /* ------------------------------------------------------------------------------------------------------------------ */
-/*
+/*  */
 
-float 运算 举例
-    void float_matmul_callback(const void* a, const void* b, void** c) {
-        float val_a = *(const float*)a;
-        float val_b = *(const float*)b;
+// 1. 矩阵与矩阵之间的加、减、乘、除（其中加减除为 Element-wise 逐元素运算，乘法为标准线性代数矩阵乘法）
+c_err_t c_Matrix_Add(c_Matrix_t* out, const c_Matrix_t* lhs, const c_Matrix_t* rhs, c_Matrix_OpFn_t add_op, void* ud);
+c_err_t c_Matrix_Sub(c_Matrix_t* out, const c_Matrix_t* lhs, const c_Matrix_t* rhs, c_Matrix_OpFn_t sub_op, void* ud);
+c_err_t c_Matrix_Div(c_Matrix_t* out, const c_Matrix_t* lhs, const c_Matrix_t* rhs, c_Matrix_OpFn_t div_op, void* ud);
 
-        // 1. 拿到外部矩阵 C[i][j] 的真实内存地址
-        float* dest_cell = *(float**)c;
+// 标准线性代数矩阵乘法 (Matrix Multiplication)：要求 lhs 的列数等于 rhs 的行数
+// 内部包含累加逻辑，因此除了乘法算子，还需要额外传入一个加法算子
+c_err_t c_Matrix_Mul(c_Matrix_t* out, const c_Matrix_t* lhs, const c_Matrix_t* rhs,
+                     c_Matrix_OpFn_t mul_op, c_Matrix_OpFn_t add_op, void* ud);
 
-        // 2. 严格执行乘加（+=）
-        *dest_cell += val_a * val_b;
-    }
- */
+// 2. 矩阵与标量（Scalar）的加减乘除（即矩阵中的每一个元素都与外部单值标量进行运算）
+c_err_t c_Matrix_AddScalar(c_Matrix_t* out, const c_Matrix_t* in, const void* scalar, c_Matrix_OpFn_t add_op, void* ud);
+c_err_t c_Matrix_SubScalar(c_Matrix_t* out, const c_Matrix_t* in, const void* scalar, c_Matrix_OpFn_t sub_op, void* ud);
+c_err_t c_Matrix_MulScalar(c_Matrix_t* out, const c_Matrix_t* in, const void* scalar, c_Matrix_OpFn_t mul_op, void* ud);
+c_err_t c_Matrix_DivScalar(c_Matrix_t* out, const c_Matrix_t* in, const void* scalar, c_Matrix_OpFn_t div_op, void* ud);
 
-c_err_t c_Matrix_Multiply(const c_Matrix_t* A, const c_Matrix_t* B, c_Matrix_t* C, void (*multiply)(const void* a, const void* b, void** c)) ;
-
-c_err_t c_Matrix_TransposeTo(c_Matrix_t* src, c_Matrix_t* dst);
-
-c_err_t c_Matrix_InPlaceTranspose(c_Matrix_t* self);
+/* ------------------------------------------------------------------------------------------------------------------ */
+/*  */
 
 /**
- * @brief 计算方阵的行列式
- * @param self 矩阵指针
- * @param ops 用户注册的泛型数学算子包
- * @param out_det 存储计算结果的内存指针（外部分配）
- * @return c_err_t 成功返回 C_SUCCESS，非方阵返回 C_ERR_PARAM
+ * @brief 矩阵转置 (Matrix Transpose)
+ * @param out 存储结果的目标矩阵。空间几何拓扑必须满足：out->rows == in->cols 且 out->cols == in->rows
+ * @param in 输入的原矩阵 (M x N)
+ * @return c_err_t 成功返回 C_ERR_OK
  */
-c_err_t c_Matrix_Determinant(const c_Matrix_t* self, const c_MatrixOps_t* ops, void* out_det);
+c_err_t c_Matrix_Transpose(c_Matrix_t* out, const c_Matrix_t* in);
+
+/* ------------------------------------------------------------------------------------------------------------------ */
+/*  */
+
 
 /**
- * @brief 使用高斯消元法求解线性方程组 Ax = b
- * @param A  NxN 的系数矩阵指针
- * @param b  Nx1 的常数项向量矩阵指针
- * @param x  Nx1 的解向量矩阵指针（外部分配好内存）
- * @param ops 用户注册的泛型数学算子包
- * @return c_err_t 成功返回 C_SUCCESS，维度不匹配返回 C_ERR_PARAM，矩阵奇异返回 C_ERR_SINGULAR
+ * @brief 泛型矩阵行列式求解 (Matrix Determinant)
+ * @note 采用经典的拉普拉斯代数余子式递归展开法（Laplace Expansion）
+ * @param self 目标矩阵，空间拓扑必须为方阵：self->rows == self->cols
+ * @param out_det 外部提供用以承接最终行列式标量值的缓冲区（大小必须 >= item_size）
+ * @param add_op 加法算子
+ * @param sub_op 减法算子
+ * @param mul_op 乘法算子
+ * @param neg_op 变号/取负算子
+ * @param ud 用户自定义上下文指针
+ * @return c_err_t 成功返回 C_ERR_OK，方阵校验失败返回 C_ERR_OUTOFBOUND
  */
-c_err_t c_Matrix_Solve(const c_Matrix_t* A, const c_Matrix_t* b, c_Matrix_t* x, const c_MatrixOps_t* ops);
+c_err_t c_Matrix_Determinant(c_Matrix_t* self, void* out_det,
+                             c_Matrix_OpFn_t add_op, c_Matrix_OpFn_t sub_op,
+                             c_Matrix_OpFn_t mul_op, c_Matrix_NegFn_t neg_op,
+                             void* ud);
 
 #endif /*INCLUDED_C_MATRIX_H*/