cKit/Foundation/c_Matrix.h

#ifndef INCLUDED_C_MATRIX_H
#define INCLUDED_C_MATRIX_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*/


/* ------------------------------------------------------------------------------------------------------------------ */
/*  */

// 元素对元素算子：将 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 {
    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 item_size, c_Allocator_t* allocator);
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_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_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; }

/* ------------------------------------------------------------------------------------------------------------------ */
/*  */

// 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);

// 标准线性代数矩阵乘法 (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. 矩阵与标量（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);

/* ------------------------------------------------------------------------------------------------------------------ */
/*  */

/**
 * @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_Transpose(c_Matrix_t* out, const c_Matrix_t* in);

/* ------------------------------------------------------------------------------------------------------------------ */
/*  */


/**
 * @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_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*/