% ^^A  ================================== 元注释 ==================================
% \iffalse meta-comment
%
% 文件：lt3matrix.dtx
%
% 版权所有 (C) 2026 Ms_yam
%
% 本文件可以依据 LaTeX 项目公共许可证（LPPL）1.3c
% 或（由你选择）任何更高版本的条款进行分发和/或修改。
% 该许可证的最新版本位于
%
%    http://www.latex-project.org/lppl.txt
%
% 本文件的维护状态为“维护中”。
%
% 当前维护者：Ms_yam
% 
% 错误报告及维护联系：ms_yam@163.com
%
% \fi
%
% ^^A ================================== 安装信息 ==================================
% \iffalse 
%<*install>
\begingroup

\input docstrip.tex
\keepsilent
\askforoverwritefalse

\preamble
\endpreamble

\postamble
\endpostamble

\generate{
    \file{\jobname.ins} {\from{\jobname.dtx}{install}}
    \file{\jobname.sty} {\from{\jobname.dtx}{package}}   
    \let\MetaPrefix\relax
    \def\MetaPrefix{} 
    \nopreamble\nopostamble
    \file{README.md}   {\from{\jobname.dtx}{readme}}
  }
  
\ifx\documentclass\@undefined
  \endbatchfile
\fi

\endgroup
%</install>
% \fi
%
% ^^A ================================== 文档驱动 ==================================
% \iffalse
%<*driver>
\documentclass[full]{l3doc}
\usepackage{lt3matrix}

% ^^A 添加中文支持及设置超级链接
\usepackage[UTF8,heading]{ctex} 
\hypersetup
  { 
    colorlinks,
    linkcolor=blue,
    hyperindex,
    pdfstartview=FitH,
    plainpages=false,
    backref
  }

% ^^A 引用待办包
\usepackage{todo}

% ^^A 汉化 l3doc 的部分定义
\DeclareDocumentEnvironment { texnote } { }
  {
    \endgraf
    \vspace{0.5em}% 3mm => 0.5em
    \small\textbf{\TeX{} 黑客笔记：}% \TeX~hackers~note:
  }
  { \vspace{0.5em} } % 3mm => 0.5em

% ^^A 不建索引的命令
\DoNotIndex{ \group_begin:, \group_end: }

\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
% ^^A ================================ RADME ME ================================
% \iffalse 
%<*readme> ^^A README
# 基本说明

本宏包基于 `expl3` 和 `l3fparray` 实现，提供轻量级的矩阵数据结构及常用矩阵操作，
包括矩阵的创建、修改、逐元素运算、矩阵间运算、映射和排版等功能。

目前，宏包仍处于开发阶段，部分计划中的功能尚未实现。

## AI 使用声明

本项目在开发和文档编写过程中使用了 AI 辅助。

- **代码**：代码由人工编写和修改。AI 用于辅助发现潜在问题并提供分析建议。
所有代码修改和最终决策均由作者完成。
- **文档**：AI 用于协助起草文档。中文版由作者审核和修订，英文版则由 AI 根据中文版翻译。

如中英文文档存在差异，以中文版为准。

## 许可

版权所有 (C) 2026 Ms_yam

本文件可以依据 LaTeX 项目公共许可证（LPPL）1.3c
或（由你选择）任何更高版本的条款进行分发和/或修改。

该许可证的最新版本位于：

http://www.latex-project.org/lppl.txt

本文件的维护状态为“维护中”。

当前维护者：Ms_yam

错误报告及维护联系：ms_yam@163.com

## 编译

本宏包设计为单文件包，可以直接使用以下命令编译：

```sh
# 提取宏包文件
xetex matrix.dtx

# 编译文档
xelatex matrix.dtx
```

# Overview

This package is implemented using `expl3` and `l3fparray`. 
It provides a lightweight matrix data structure and commonly 
used matrix operations, including matrix creation, modification, 
element-wise operations, operations between matrices, mapping, and typesetting.

The package is currently under development, and some 
planned features have not yet been implemented.

## AI Usage Statement

AI tools were used as an auxiliary aid in the development
 and documentation of this project.

- **Code**: The code was written and modified manually. 
AI was used to help identify potential issues and provide suggestions for investigation. 
All code changes and final decisions were made by the author.
- **Documentation**: AI was used to assist in drafting the documentation. 
The Chinese version was reviewed and edited by the author, 
while the English version was translated by AI based on the Chinese version.

In the event of any discrepancies between the Chinese and 
English documentation, the Chinese version shall prevail.

## License

Copyright (C) 2026 Ms_yam

This file may be distributed and/or modified under the terms of the
LaTeX Project Public License (LPPL), version 1.3c or (at your option)
any later version.

The latest version of this license is available at:

http://www.latex-project.org/lppl.txt

This work is maintained.

Current Maintainer: Ms_yam

Contact for bug reports and maintenance: ms_yam@163.com

## Compilation

This package is designed as a single-file package. You can compile it
directly using the following commands:

```sh
# Extract the package files
xetex matrix.dtx

# Compile the documentation
xelatex matrix.dtx
```

%</readme>
% \fi
%
% ^^A ================================== 文档内容 ==================================
%
% \title{基于 \pkg{l3fparray} 的轻量矩阵\\Lightweight Matrix Based on \pkg{l3fparray}}^^A
%
% \author{Ms\_yam\thanks{E-mail: \href{mailto:Ms_yam@163.com}{Ms\_yam@163.com}}}
% 
% \date{2026-11-16}
%
% \maketitle
%
% ^^A ---------------------------------- 文档部分 ----------------------------------
%
% \begin{documentation}
%
%
% \section[用户文档]{用户文档~\hyperref[sec:user-guide:en]{\scriptsize[English]}}\label{sec:user-guide:cn}
%
% \subsection{宏包简介}
%
% \pkg{matrix} 提供一种轻量矩阵类型，主要用于 TeX 文档中的矩阵演示、
% 数值示例和几何变换。使用者可以创建矩阵、设置矩阵元素、执行矩阵运算、
% 遍历元素，并将矩阵排版到数学公式中。
%
% 本宏包中的矩阵具有确定的行数和列数。通常，矩阵创建后其维度不应修改，
% 且本宏包不提供直接修改矩阵维度的接口。
% 但当矩阵作为运算结果时，其维度会根据运算结果自动更新。
% 矩阵元素则可以通过赋值命令修改。矩阵的创建和修改均为全局操作：
% 在 TeX 分组内执行修改命令，分组结束后矩阵内容不会自动恢复。
%
% 空矩阵也具有明确的行数和列数，但不包含任何元素。
% 行数和列数不能为负数。
%
% 
% \subsection{快速开始}
%
% 下面的例子创建一个 $2\times3$ 矩阵，然后设置元素，并在数学模式中排版：
% \begin{verbatim}
% \ExplSyntaxOn
% \matrix_new:Nnn \l_demo_matrix { 2 } { 3 }
% \matrix_gset:Nn \l_demo_matrix { 1, 2, 3, 4, 5, 6 }
% \[
%   \matrix_use:N \l_demo_matrix
% \]
% \ExplSyntaxOff
% \end{verbatim}
% 其效果为：
% \ExplSyntaxOn
% \matrix_new:Nnn \l_demo_matrix { 2 } { 3 }
% \matrix_gset:Nn \l_demo_matrix { 1, 2, 3, 4, 5, 6 }
% \[
%   \matrix_use:N \l_demo_matrix
% \]
% \ExplSyntaxOff
%
%
% \subsection{命令与参数约定}
%
% 本宏包主要作为 \pkg{expl3} 的基础扩展宏包，其主要接口遵循
% \pkg{expl3} 的命名规范，使用时应处于 \cs{ExplSyntaxOn} 状态。
% 此外，为方便不熟悉 \pkg{expl3} 的 \LaTeX 用户使用，
% 本宏包也为常用操作提供了相应的 \LaTeX2e 风格命令。
%
% \pkg{expl3} 风格命令名称中，冒号后的字母表示参数的形式：
% |N| 接收单个控制序列，|n| 接收按原样传入的一般参数
% （通常写在一对花括号中），|c| 则根据给出的字符名称构造控制序列。
% 因此，|N| 形式直接接收矩阵变量，例如 \cs{matrix_new:Nnn}；
% |c| 形式接收矩阵变量的名称（不带反斜杠），例如
% \cs{matrix_new:cnn} |{l_demo_matrix}| |{2}| |{2}|。
% 同一组命令的不同变体执行相同操作，区别仅在于相应参数的传递形式。
%
% 在本文档中，\meta{matrix} 表示矩阵变量；\meta{destination} 表示接收结果的目标矩阵；
% \meta{source} 表示作为输入的源矩阵。除创建命令外，作为参数传入的矩阵
% 都应当已经创建。
%
%
% \subsection{创建矩阵}
%
% \begin{function}{\matrix_new:Nnn, \matrix_new:cnn}
%   \begin{syntax}
%     \cs{matrix_new:Nnn} \meta{matrix} \Arg{rows} \Arg{columns}
%   \end{syntax}
%   创建一个普通矩阵，所有元素均初始化为零。
%
%   \meta{matrix} 是新矩阵的变量；\meta{rows} 和 \meta{columns}
%   分别指定矩阵的行数和列数。两个参数均按整数表达式求值，
%   且必须为非负数。维度允许为零。
%
%   如果矩阵变量已经定义，则产生错误。
% \end{function}
%
% \begin{function}{\matrix_const:Nnnn, \matrix_const:cnnn}
%   \begin{syntax}
%     \cs{matrix_const:Nnnn} \meta{matrix} \Arg{rows} \Arg{columns} \Arg{comma list}
%   \end{syntax}
%   创建一个常量矩阵，并使用逗号分隔列表初始化其元素。
%   元素按照行优先顺序填入；列表中未指定的元素初始化为零。
%   常量矩阵不能通过本宏包提供的矩阵修改命令进行修改。
%
%   \meta{matrix}、\meta{rows} 和 \meta{columns} 的含义与
%   \cs{matrix_new:Nnn} 相同。\meta{comma list} 是矩阵元素列表，
%   每一项均按浮点数表达式求值。
%   列表项数不得超过矩阵的元素总数；如果超过，则产生错误，
%   且矩阵不会被创建。
% \end{function}
% 
%
% \subsection{设置和修改矩阵}
%
% 以下命令用于修改已创建矩阵的内容。目标矩阵必须是普通矩阵；
% 如果目标矩阵是常量矩阵，则会产生错误。所有修改操作均为全局操作。
%
% \begin{function}{\matrix_gzero:N, \matrix_gzero:c}
%   \begin{syntax}
%     \cs{matrix_gzero:N} \meta{matrix}
%   \end{syntax}
%   将 \meta{matrix} 的所有元素设为零，同时保持矩阵的行数和列数不变。
%   如果矩阵为空，则其维度信息保持不变。
% \end{function}
%
% \begin{function}{\matrix_gset:Nn, \matrix_gset:cn}
%   \begin{syntax}
%     \cs{matrix_gset:Nn} \meta{matrix} \Arg{comma list}
%   \end{syntax}
%   使用逗号分隔列表重新设置 \meta{matrix} 的所有元素，
%   并按照行优先顺序写入。列表中的每一项均按浮点数表达式求值。
%   列表项数不得超过矩阵的元素总数；如果列表项数不足，
%   则剩余元素设为零。如果列表项数过多，则产生错误，
%   且本次设置不会执行。矩阵的行数和列数保持不变。
% \end{function}
%
% \begin{function}
%   {
%     \matrix_gset_eq:NN,
%     \matrix_gset_eq:cN,
%     \matrix_gset_eq:Nc
%   }
%   \begin{syntax}
%     \cs{matrix_gset_eq:NN} \meta{destination} \meta{source}
%   \end{syntax}
%   将 \meta{source} 的维度和元素复制到 \meta{destination}。
%   目标矩阵的维度会相应更新。复制完成后，两个矩阵的数据相互独立；
%   后续修改其中一个矩阵不会影响另一个矩阵。
%
%   \meta{destination} 必须是已创建的普通矩阵；
%   \meta{source} 必须是已创建的矩阵，可以是普通矩阵或常量矩阵。
%   源矩阵不会被修改。
% \end{function}
%
%
% \subsection{逐元素运算}
%
% 本节介绍对矩阵中的每个元素分别执行相同运算的命令。
% 根据结果的存储方式，命令分为两种形式：一种直接将结果写回原矩阵，
% 另一种将结果写入另一个目标矩阵。无论采用哪种形式，
% 用于存储运算结果的矩阵都必须是已创建的普通矩阵。
%
% 直接写回原矩阵的形式保持矩阵的维度不变；
% 写入目标矩阵的形式则会将目标矩阵的维度更新为与源矩阵相同。
% 当目标矩阵与源矩阵是同一个矩阵时，运算结果仍会写回该矩阵，
% 但相比直接写回原矩阵的形式，需要额外的临时矩阵空间分配和回收操作。
% 因此，这种情况下建议使用直接写回原矩阵的形式。
%
% \begin{function}{\matrix_gnegate:N, \matrix_gabs:N, \matrix_gsign:N}
%   \begin{syntax}
%     \cs{matrix_gnegate:N} \meta{matrix}
%     \cs{matrix_gabs:N} \meta{matrix}
%     \cs{matrix_gsign:N} \meta{matrix}
%   \end{syntax}
%   分别将 \meta{matrix} 的每个元素替换为其相反数、绝对值和符号值，
%   并将运算结果写回其自身。
% \end{function}
%
% \begin{function}{\matrix_gnegate:NN, \matrix_gabs:NN, \matrix_gsign:NN}
%   \begin{syntax}
%     \cs{matrix_gnegate:NN} \meta{destination} \meta{source}
%     \cs{matrix_gabs:NN} \meta{destination} \meta{source}
%     \cs{matrix_gsign:NN} \meta{destination} \meta{source}
%   \end{syntax}
%   对 \meta{source} 的每个元素执行相应运算，并将结果写入
%   \meta{destination}。
% \end{function}
%
% \begin{function}{\matrix_ground:Nn}
%   \begin{syntax}
%     \cs{matrix_ground:Nn} \meta{matrix} \Arg{digits}
%   \end{syntax}
%   对 \meta{matrix} 的每个元素执行舍入，并将结果写回其自身。
%   \meta{digits} 是传递给 \pkg{l3fp} 的 \texttt{round} 运算的精度参数。
% \end{function}
%
% \begin{function}{\matrix_ground:NNn}
%   \begin{syntax}
%     \cs{matrix_ground:NNn} \meta{destination} \meta{source} \Arg{digits}
%   \end{syntax}
%   对 \meta{source} 的每个元素执行舍入，并将结果写入 \meta{destination}。
%   \meta{digits} 的含义与 \cs{matrix_ground:Nn} 中相同。
% \end{function}
%
% \begin{function}
%   {
%     \matrix_gadd:Nn, \matrix_gsub:Nn,
%     \matrix_gmul:Nn, \matrix_gdiv:Nn,
%     \matrix_gpower:Nn
%   }
%   \begin{syntax}
%     \cs{matrix_gadd:Nn} \meta{matrix} \Arg{scalar}
%     \cs{matrix_gsub:Nn} \meta{matrix} \Arg{scalar}
%     \cs{matrix_gmul:Nn} \meta{matrix} \Arg{scalar}
%     \cs{matrix_gdiv:Nn} \meta{matrix} \Arg{scalar}
%     \cs{matrix_gpower:Nn} \meta{matrix} \Arg{scalar}
%   \end{syntax}
%   将矩阵 \meta{matrix} 的每个元素分别与 \meta{scalar} 执行加、减、乘、除或乘方运算，
%   并将结果写回其自身。对于矩阵 $A$ 和标量 $c$，对应的逐元素运算依次为
%   $A+c$、$A-c$、$A\times c$、$A/c$ 和 $A^c$。
%   \meta{scalar} 按 \pkg{l3fp} 浮点表达式求值。
% \end{function}
%
% \begin{function}
%   {
%     \matrix_gadd:NNn, \matrix_gsub:NNn,
%     \matrix_gmul:NNn, \matrix_gdiv:NNn,
%     \matrix_gpower:NNn
%   }
%   \begin{syntax}
%     \cs{matrix_gadd:NNn} \meta{destination} \meta{source} \Arg{scalar}
%     \cs{matrix_gsub:NNn} \meta{destination} \meta{source} \Arg{scalar}
%     \cs{matrix_gmul:NNn} \meta{destination} \meta{source} \Arg{scalar}
%     \cs{matrix_gdiv:NNn} \meta{destination} \meta{source} \Arg{scalar}
%     \cs{matrix_gpower:NNn} \meta{destination} \meta{source} \Arg{scalar}
%   \end{syntax}
%   将 \meta{source} 的每个元素分别与 \meta{scalar} 执行加、减、乘、除或乘方运算，
%   并将结果写入 \meta{destination}。
%   对于源矩阵 $A$ 和标量 $c$，对应的逐元素运算依次为
%   $A+c$、$A-c$、$A\times c$、$A/c$ 和 $A^c$。
%   \meta{scalar} 按 \pkg{l3fp} 浮点表达式求值。
% \end{function}
%
%
% \subsection{矩阵间的运算}
%
% 本节介绍两个矩阵之间的加法、减法和乘法运算。
% 根据结果的存储方式，命令分为两种形式：一种将结果写入目标矩阵，
% 另一种直接写回操作数。用于存储运算结果的矩阵必须是已创建的普通矩阵；
% 作为输入的操作数必须是已创建的矩阵，可以是普通矩阵或常量矩阵。
%
% \begin{function}{\matrix_gadd:NNN, \matrix_gsub:NNN}
%   \begin{syntax}
%     \cs{matrix_gadd:NNN} \meta{destination} \meta{matrix A} \meta{matrix B}
%     \cs{matrix_gsub:NNN} \meta{destination} \meta{matrix A} \meta{matrix B}
%   \end{syntax}
%   分别计算两个矩阵对应元素的和或差，并将结果写入
%   \meta{destination}。两个操作数的行数和列数必须分别相等，
%   否则产生维度不匹配错误。目标矩阵的维度更新为与操作数相同。
% \end{function}
%
% \begin{function}{\matrix_gadd:NN, \matrix_gsub:NN}
%   \begin{syntax}
%     \cs{matrix_gadd:NN} \meta{matrix A} \meta{matrix B}
%     \cs{matrix_gsub:NN} \meta{matrix A} \meta{matrix B}
%   \end{syntax}
%   分别执行原地运算 $A\leftarrow A+B$ 和 $A\leftarrow A-B$。
%   两个矩阵的行数和列数必须分别相等，否则产生维度不匹配错误。
%   运算结果写回第一个矩阵，其维度保持不变；第二个矩阵仅作为输入，
%   不会被修改。
% \end{function}
%
% \begin{function}{\matrix_gmul:NNN}
%   \begin{syntax}
%     \cs{matrix_multiply:NNN} \meta{destination} \meta{matrix A} \meta{matrix B}
%   \end{syntax}
%   计算两个矩阵的乘积 $AB$。\meta{matrix A} 的列数必须等于
%   \meta{matrix B} 的行数，否则产生维度不匹配错误。
%   将结果写入 \meta{destination}，其维度更新为
%   \meta{matrix A} 的行数乘以 \meta{matrix B} 的列数。
% \end{function}
%
% \begin{function}{\matrix_gmul:NN}
%   \begin{syntax}
%     \cs{matrix_multiply:NN} \meta{matrix A} \meta{matrix B}
%   \end{syntax}
%   计算两个矩阵的乘积 $AB$。\meta{matrix A} 的列数必须等于
%   \meta{matrix B} 的行数，否则产生维度不匹配错误。
%   将结果写回第一个矩阵，即执行 $A\leftarrow AB$；
%   第一个矩阵的维度更新为乘积结果的维度。
% \end{function}
% 
% 
% \subsection{基于矩阵的映射}
%
% 映射按行优先顺序访问矩阵中的元素，并在每次访问时
% 将当前元素值传递给回调。映射机制只负责读取和传递元素值，
% 不会自动将回调结果写回矩阵。如果矩阵为空，则不会调用回调。
%
% \begin{function}{\matrix_map_function:NN}
%   \begin{syntax}
%     \cs{matrix_map_function:NN} \meta{matrix} \meta{function}
%   \end{syntax}
%   对 \meta{matrix} 的每个元素调用一次 \meta{function}。
%   \meta{function} 必须接收一个参数，该参数为当前元素值。
% \end{function}
%
% \begin{function}{\matrix_map_inline:Nn}
%   \begin{syntax}
%     \cs{matrix_map_inline:Nn} \meta{matrix} \Arg{inline code}
%   \end{syntax}
%   对 \meta{matrix} 的每个元素执行一次 \meta{inline code}。
%   在内联代码中，|##1| 表示当前元素值。由于代码作为映射命令的
%   参数传入，参数标记需要写成两个 |#|。
%
%   例如，下面的代码依次将矩阵元素写入终端：
%   \begin{verbatim}
%   \matrix_map_inline:Nn \l_demo_matrix
%     { \iow_term:n { ##1 } }
%   \end{verbatim}
% \end{function}
%
% \begin{function}{\matrix_map_break:, \matrix_map_break:n}
%   \begin{syntax}
%     \cs{matrix_map_break:}
%     \cs{matrix_map_break:n} \Arg{code}
%   \end{syntax}
%   在映射回调中调用 \cs{matrix_map_break:} 可以提前结束当前映射。
%   \cs{matrix_map_break:n} 除了结束映射，还会在退出映射时执行
%   \meta{code}。
% \end{function}
%
% 
% \subsection{显示和检查矩阵}
%
% \begin{function}{\matrix_use:N, \matrix_use:c}
%   \begin{syntax}
%     \cs{matrix_use:N} \meta{matrix}
%   \end{syntax}
%   在数学模式中排版 \meta{matrix}。非空矩阵以圆括号矩阵的形式显示；
%   空矩阵则显示其维度信息，例如 $2\times0$。
%   本命令不会自动进入数学模式，因此必须在数学模式中调用。
% \end{function}
%
% \begin{function}{\matrix_log:N, \matrix_log:c}
%   \begin{syntax}
%     \cs{matrix_log:N} \meta{matrix}
%   \end{syntax}
%   将 \meta{matrix} 的维度、存储信息和元素内容写入编译日志，
%   用于检查矩阵状态和调试。本命令不会在页面正文中排版矩阵。
% \end{function}
%
% 
% \subsection{预定义矩阵和临时变量}
%
% \begin{variable}{\c_empty_matrix}
%   $0\times0$ 空矩阵。
% \end{variable}
% \begin{variable}{\c_identity_two_matrix, \c_identity_three_matrix, \c_identity_four_matrix}
%   分别为 $2\times2$、$3\times3$ 和 $4\times4$ 单位矩阵。\\
%   \ExplSyntaxOn
%     $\matrix_use:N \c_identity_two_matrix$、$\matrix_use:N \c_identity_three_matrix$、
%     $\matrix_use:N \c_identity_four_matrix$
%   \ExplSyntaxOff
% \end{variable}
%
% \begin{variable}{\g_tmpa_matrix, \g_tmpb_matrix}
%   用于全局赋值的临时矩阵变量。本宏包的内部代码不会使用这些变量，
%   因此可以安全地与本宏包提供的命令一起使用。
%   但是，它们可能会被其他代码覆盖，因此只能用于短期存储。
% \end{variable}
%
% 
% \subsection{\LaTeX2e 命令}
%
% 本宏包计划提供部分 \LaTeX2e 风格的命令接口。
% 由于目前尚未完成相关命令的设计与实现，本节暂为空。
%
% 
% \subsection{错误条件}
%
% 当前实现会在以下情况下报告错误：
% \begin{itemize}
%   \item 创建矩阵时，行数或列数为负数；
%   \item 创建矩阵时，矩阵变量已经定义；
%   \item 将常量矩阵用作修改操作的目标矩阵；
%   \item 创建或设置矩阵时，元素列表中的项数超过矩阵的元素总数；
%   \item 执行矩阵间的逐元素二元运算时，两个操作数的维度不一致；
%   \item 执行矩阵乘法时，左操作数的列数与右操作数的行数不一致。
% \end{itemize}
%
% \cleardoublepage{}
% 
% ^^A 清理中文版中的示例代码定义的变量
% \ExplSyntaxOn 
% \cs_undefine:N \l_demo_matrix
% \ExplSyntaxOff
% 
% \section[User Guide]{User Guide~\hyperref[sec:user-guide:cn]{\scriptsize[中文]}}\label{sec:user-guide:en}
% 
% \subsection{Package Overview}
%
% The \pkg{matrix} package provides a lightweight matrix type, primarily
% intended for matrix demonstrations, numerical examples, and geometric
% transformations in TeX documents. It allows users to create matrices,
% set matrix elements, perform matrix operations, iterate over elements,
% and typeset matrices in mathematical expressions.
%
% Matrices provided by this package have a defined number of rows and
% columns. In general, their dimensions are not intended to be changed
% after creation, and the package provides no direct interface for
% modifying them. However, when a matrix is used to store an operation
% result, its dimensions are updated automatically to match the result.
% Matrix elements can be modified using assignment commands. Matrix
% creation and modification operations are global: changes made within
% a TeX group are not automatically reverted when the group ends.
%
% Empty matrices also have well-defined numbers of rows and columns,
% but contain no elements. The number of rows and columns cannot be
% negative.
%
% \subsection{Quick Start}
%
% The following example creates a $2\times3$ matrix, assigns values to
% its elements, and typesets the matrix in math mode:
% \begin{verbatim}
% \ExplSyntaxOn
% \matrix_new:Nnn \l_demo_matrix { 2 } { 3 }
% \matrix_gset:Nn \l_demo_matrix { 1, 2, 3, 4, 5, 6 }
% \[
%   \matrix_use:N \l_demo_matrix
% \]
% \ExplSyntaxOff
% \end{verbatim}
% The output is:
% \ExplSyntaxOn
% \matrix_new:Nnn \l_demo_matrix { 2 } { 3 }
% \matrix_gset:Nn \l_demo_matrix { 1, 2, 3, 4, 5, 6 }
% \[
%   \matrix_use:N \l_demo_matrix
% \]
% \ExplSyntaxOff
%
%
% \subsection{Command and Argument Conventions}
%
% This package is primarily intended as a basic extension to \pkg{expl3},
% and its main interfaces follow the \pkg{expl3} naming conventions.
% These commands should be used with \cs{ExplSyntaxOn} enabled.
% In addition, the package provides corresponding \LaTeX2e-style
% commands for commonly used operations, making them accessible to
% \LaTeX users who are not familiar with \pkg{expl3}.
%
% In \pkg{expl3}-style command names, the letters following the colon
% indicate the forms of the arguments:
% |N| accepts a single control sequence, |n| accepts a general argument
% (usually enclosed in a pair of braces), and |c| converts a
% character-based name into a control sequence for use.
% Thus, the |N| form takes a matrix variable directly, as in
% \cs{matrix_new:Nnn}, whereas the |c| form takes the name of a matrix
% variable (without the leading backslash), as in
% \cs{matrix_new:cnn} |{l_demo_matrix}| |{2}| |{2}|.
% Different variants of the same command perform the same operation;
% they differ only in how the corresponding arguments are passed.
%
% In this document, \meta{matrix} denotes a matrix variable;
% \meta{destination} denotes the target matrix that receives a result;
% and \meta{source} denotes an input matrix.
% Except for creation commands, any matrix passed as an argument
% must have been created beforehand.
% 
%
% \subsection{Creating Matrices}
%
% \begin{function}{\matrix_new:Nnn, \matrix_new:cnn}
%   \begin{syntax}
%     \cs{matrix_new:Nnn} \meta{matrix} \Arg{rows} \Arg{columns}
%   \end{syntax}
%   Creates a regular matrix with all elements initially set to zero.
%
%   \meta{matrix} is the variable for the new matrix.
%   \meta{rows} and \meta{columns} specify the number of rows and
%   columns, respectively. Both arguments are evaluated as integer
%   expressions and must be non-negative. Zero dimensions are allowed.
%
%   An error is raised if the matrix variable has already been defined.
% \end{function}
%
% \begin{function}{\matrix_const:Nnnn, \matrix_const:cnnn}
%   \begin{syntax}
%     \cs{matrix_const:Nnnn} \meta{matrix} \Arg{rows} \Arg{columns} \Arg{comma list}
%   \end{syntax}
%   Creates a constant matrix and initializes its elements from a
%   comma-separated list. The elements are filled in row-major order.
%   Any elements not specified in the list are initialized to zero.
%   A constant matrix cannot be modified using the matrix modification
%   commands provided by this package.
%
%   \meta{matrix}, \meta{rows}, and \meta{columns} have the same meanings
%   as for \cs{matrix_new:Nnn}. \meta{comma list} is the list of matrix
%   elements, with each item evaluated as a floating-point expression.
%   The number of items must not exceed the total number of elements
%   in the matrix. If it does, an error is raised and the matrix is
%   not created.
% \end{function}
% 
%
% \subsection{Setting and Modifying Matrices}
%
% The following functions modify the contents of an existing matrix.
% The destination matrix must be a regular matrix; an error is raised
% if it is a constant matrix. All modifications are global.
%
% \begin{function}{\matrix_gzero:N, \matrix_gzero:c}
%   \begin{syntax}
%     \cs{matrix_gzero:N} \meta{matrix}
%   \end{syntax}
%   Sets all elements of \meta{matrix} to zero, leaving its number of
%   rows and columns unchanged. If the matrix is empty, its dimensions
%   remain unchanged.
% \end{function}
%
% \begin{function}{\matrix_gset:Nn, \matrix_gset:cn}
%   \begin{syntax}
%     \cs{matrix_gset:Nn} \meta{matrix} \Arg{comma list}
%   \end{syntax}
%   Sets all elements of \meta{matrix} using a comma-separated list,
%   with the elements filled in row-major order. Each item in the list
%   is evaluated as a floating-point expression.
%   The number of items must not exceed the total number of elements
%   in the matrix. If fewer items are provided, the remaining elements
%   are set to zero. If too many items are provided, an error is raised
%   and the assignment is not performed. The dimensions of the matrix
%   remain unchanged.
% \end{function}
%
% \begin{function}
%   {
%     \matrix_gset_eq:NN,
%     \matrix_gset_eq:cN,
%     \matrix_gset_eq:Nc
%   }
%   \begin{syntax}
%     \cs{matrix_gset_eq:NN} \meta{destination} \meta{source}
%   \end{syntax}
%   Copies the dimensions and elements of \meta{source} to
%   \meta{destination}. The dimensions of the destination matrix are
%   updated accordingly. After the copy, the two matrices have
%   independent data; subsequent modifications to either matrix
%   do not affect the other.
%
%   \meta{destination} must be an existing regular matrix.
%   \meta{source} must be an existing matrix and may be either
%   a regular matrix or a constant matrix. The source matrix
%   is not modified.
% \end{function}
% 
% 
% \subsection{Element-wise Operations}
%
% This section describes commands that perform the same operation
% on each element of a matrix. Depending on how the results are stored,
% the commands are provided in two forms: one writes the results back
% to the original matrix, while the other writes them to a separate
% destination matrix. In either form, the matrix used to store the
% results must be an existing regular (non-constant) matrix.
%
% The form that writes the results back to the original matrix
% preserves its dimensions, whereas the form that writes the results
% to a destination matrix updates the destination dimensions to match
% those of the source matrix. If the destination and source are the
% same matrix, the results are still written back to that matrix.
% However, compared with the form that writes directly to the original
% matrix, this requires additional allocation and deallocation of
% temporary matrix storage. Therefore, the former form is recommended
% in this case.
%
% \begin{function}{\matrix_gnegate:N, \matrix_gabs:N, \matrix_gsign:N}
%   \begin{syntax}
%     \cs{matrix_gnegate:N} \meta{matrix}
%     \cs{matrix_gabs:N} \meta{matrix}
%     \cs{matrix_gsign:N} \meta{matrix}
%   \end{syntax}
%   Replaces each element of \meta{matrix} with its negation,
%   absolute value, or sign, respectively, and writes the results
%   back to the same matrix.
% \end{function}
%
% \begin{function}{\matrix_gnegate:NN, \matrix_gabs:NN, \matrix_gsign:NN}
%   \begin{syntax}
%     \cs{matrix_gnegate:NN} \meta{destination} \meta{source}
%     \cs{matrix_gabs:NN} \meta{destination} \meta{source}
%     \cs{matrix_gsign:NN} \meta{destination} \meta{source}
%   \end{syntax}
%   Applies the corresponding operation to each element of
%   \meta{source} and writes the results to \meta{destination}.
% \end{function}
%
% \begin{function}{\matrix_ground:Nn}
%   \begin{syntax}
%     \cs{matrix_ground:Nn} \meta{matrix} \Arg{digits}
%   \end{syntax}
%   Rounds each element of \meta{matrix} and writes the results
%   back to the same matrix. \meta{digits} is the precision argument
%   passed to the \texttt{round} operation of \pkg{l3fp}.
% \end{function}
%
% \begin{function}{\matrix_ground:NNn}
%   \begin{syntax}
%     \cs{matrix_ground:NNn} \meta{destination} \meta{source} \Arg{digits}
%   \end{syntax}
%   Rounds each element of \meta{source} and writes the results
%   to \meta{destination}. The meaning of \meta{digits} is the same
%   as for \cs{matrix_ground:Nn}.
% \end{function}
%
% \begin{function}
%   {
%     \matrix_gadd:Nn, \matrix_gsub:Nn,
%     \matrix_gmul:Nn, \matrix_gdiv:Nn,
%     \matrix_gpower:Nn
%   }
%   \begin{syntax}
%     \cs{matrix_gadd:Nn} \meta{matrix} \Arg{scalar}
%     \cs{matrix_gsub:Nn} \meta{matrix} \Arg{scalar}
%     \cs{matrix_gmul:Nn} \meta{matrix} \Arg{scalar}
%     \cs{matrix_gdiv:Nn} \meta{matrix} \Arg{scalar}
%     \cs{matrix_gpower:Nn} \meta{matrix} \Arg{scalar}
%   \end{syntax}
%   Performs addition, subtraction, multiplication, division, or
%   exponentiation, respectively, between each element of
%   \meta{matrix} and \meta{scalar}, and writes the results back
%   to the same matrix. For a matrix $A$ and a scalar $c$,
%   the corresponding element-wise operations are
%   $A+c$, $A-c$, $A\times c$, $A/c$, and $A^c$, respectively.
%   \meta{scalar} is evaluated as a floating-point expression
%   by \pkg{l3fp}.
% \end{function}
%
% \begin{function}
%   {
%     \matrix_gadd:NNn, \matrix_gsub:NNn,
%     \matrix_gmul:NNn, \matrix_gdiv:NNn,
%     \matrix_gpower:NNn
%   }
%   \begin{syntax}
%     \cs{matrix_gadd:NNn} \meta{destination} \meta{source} \Arg{scalar}
%     \cs{matrix_gsub:NNn} \meta{destination} \meta{source} \Arg{scalar}
%     \cs{matrix_gmul:NNn} \meta{destination} \meta{source} \Arg{scalar}
%     \cs{matrix_gdiv:NNn} \meta{destination} \meta{source} \Arg{scalar}
%     \cs{matrix_gpower:NNn} \meta{destination} \meta{source} \Arg{scalar}
%   \end{syntax}
%   Performs addition, subtraction, multiplication, division, or
%   exponentiation, respectively, between each element of
%   \meta{source} and \meta{scalar}, and writes the results to
%   \meta{destination}. For a source matrix $A$ and a scalar $c$,
%   the corresponding element-wise operations are
%   $A+c$, $A-c$, $A\times c$, $A/c$, and $A^c$, respectively.
%   \meta{scalar} is evaluated as a floating-point expression
%   by \pkg{l3fp}.
% \end{function}
%
% 
% \subsection{Operations Between Matrices}
%
% This section describes addition, subtraction, and multiplication
% between two matrices. Depending on how the results are stored,
% the commands are provided in two forms: one writes the results
% to a destination matrix, while the other writes them back to
% an operand. The matrix used to store the results must be an
% existing regular matrix; input operands must be existing matrices
% and may be either regular or constant matrices.
%
% \begin{function}{\matrix_gadd:NNN, \matrix_gsub:NNN}
%   \begin{syntax}
%     \cs{matrix_gadd:NNN} \meta{destination} \meta{matrix A} \meta{matrix B}
%     \cs{matrix_gsub:NNN} \meta{destination} \meta{matrix A} \meta{matrix B}
%   \end{syntax}
%   Computes the element-wise sum or difference of two matrices,
%   respectively, and writes the result to \meta{destination}.
%   The two operands must have the same number of rows and the same
%   number of columns; otherwise, a dimension mismatch error is raised.
%   The dimensions of the destination matrix are updated to match
%   those of the operands.
% \end{function}
%
% \begin{function}{\matrix_gadd:NN, \matrix_gsub:NN}
%   \begin{syntax}
%     \cs{matrix_gadd:NN} \meta{matrix A} \meta{matrix B}
%     \cs{matrix_gsub:NN} \meta{matrix A} \meta{matrix B}
%   \end{syntax}
%   Performs the in-place operation $A\leftarrow A+B$ or
%   $A\leftarrow A-B$, respectively. The two matrices must have
%   the same number of rows and the same number of columns;
%   otherwise, a dimension mismatch error is raised.
%   The result is written back to the first matrix, whose dimensions
%   remain unchanged. The second matrix is used only as input
%   and is not modified.
% \end{function}
%
% \begin{function}{\matrix_gmul:NNN}
%   \begin{syntax}
%     \cs{matrix_multiply:NNN} \meta{destination} \meta{matrix A} \meta{matrix B}
%   \end{syntax}
%   Computes the matrix product $AB$. The number of columns in
%   \meta{matrix A} must equal the number of rows in \meta{matrix B};
%   otherwise, a dimension mismatch error is raised.
%   The result is written to \meta{destination}, whose dimensions
%   are updated to the number of rows in \meta{matrix A} by the
%   number of columns in \meta{matrix B}.
% \end{function}
%
% \begin{function}{\matrix_gmul:NN}
%   \begin{syntax}
%     \cs{matrix_multiply:NN} \meta{matrix A} \meta{matrix B}
%   \end{syntax}
%   Computes the matrix product $AB$. The number of columns in
%   \meta{matrix A} must equal the number of rows in \meta{matrix B};
%   otherwise, a dimension mismatch error is raised.
%   The result is written back to the first matrix, performing
%   the operation $A\leftarrow AB$. The dimensions of the first
%   matrix are updated to match those of the product.
% \end{function}
%
% 
% \subsection{Mapping over Matrices}
%
% Mapping visits the elements of a matrix in row-major order and
% passes the value of the current element to the callback on each
% iteration. The mapping mechanism only reads and passes element
% values; it does not automatically write callback results back
% to the matrix. If the matrix is empty, the callback is not invoked.
%
% \begin{function}{\matrix_map_function:NN}
%   \begin{syntax}
%     \cs{matrix_map_function:NN} \meta{matrix} \meta{function}
%   \end{syntax}
%   Calls \meta{function} once for each element of \meta{matrix}.
%   \meta{function} must accept one argument, which is the value
%   of the current element.
% \end{function}
%
% \begin{function}{\matrix_map_inline:Nn}
%   \begin{syntax}
%     \cs{matrix_map_inline:Nn} \meta{matrix} \Arg{inline code}
%   \end{syntax}
%   Executes \meta{inline code} once for each element of \meta{matrix}.
%   Within the inline code, |##1| represents the value of the current
%   element. Since the code is passed as an argument to the mapping
%   command, the parameter marker must be doubled.
%
%   For example, the following code writes the matrix elements
%   to the terminal in sequence:
%   \begin{verbatim}
%   \matrix_map_inline:Nn \l_demo_matrix
%     { \iow_term:n { ##1 } }
%   \end{verbatim}
% \end{function}
%
% \begin{function}{\matrix_map_break:, \matrix_map_break:n}
%   \begin{syntax}
%     \cs{matrix_map_break:}
%     \cs{matrix_map_break:n} \Arg{code}
%   \end{syntax}
%   Calling \cs{matrix_map_break:} within a mapping callback
%   terminates the current mapping early.
%   In addition to terminating the mapping,
%   \cs{matrix_map_break:n} executes \meta{code} when the mapping exits.
% \end{function}
%
% 
% \subsection{Displaying and Inspecting Matrices}
%
% \begin{function}{\matrix_use:N, \matrix_use:c}
%   \begin{syntax}
%     \cs{matrix_use:N} \meta{matrix}
%   \end{syntax}
%   Typesets \meta{matrix} in mathematical mode. Non-empty matrices
%   are displayed as parenthesized matrices, while empty matrices
%   display their dimensions, such as $2\times0$.
%   This command does not enter mathematical mode automatically
%   and must therefore be used in mathematical mode.
% \end{function}
%
% \begin{function}{\matrix_log:N, \matrix_log:c}
%   \begin{syntax}
%     \cs{matrix_log:N} \meta{matrix}
%   \end{syntax}
%   Writes the dimensions, storage information, and element contents
%   of \meta{matrix} to the compilation log for inspection and
%   debugging. This command does not typeset the matrix in the
%   document body.
% \end{function}
%
% 
% \subsection{Predefined Matrices and Scratch Variables}
%
% \begin{variable}{\c_empty_matrix}
%   The empty $0\times0$ matrix.
% \end{variable}
% \begin{variable}{\c_identity_two_matrix, \c_identity_three_matrix, \c_identity_four_matrix}
%   The $2\times2$, $3\times3$, and $4\times4$ identity matrices, respectively.\\
%   \ExplSyntaxOn
%     $\matrix_use:N \c_identity_two_matrix$、$\matrix_use:N \c_identity_three_matrix$、
%     $\matrix_use:N \c_identity_four_matrix$
%   \ExplSyntaxOff
% \end{variable}
%
% \begin{variable}{\g_tmpa_matrix, \g_tmpb_matrix}
%   Scratch matrix variables for global assignments. These variables
%   are not used by the package's internal code and can therefore
%   be safely used with commands provided by this package.
%   However, they may be overwritten by other code and should only
%   be used for short-term storage.
% \end{variable}
%
% 
% \subsection{\LaTeX2e Commands}
%
% The package is intended to provide some \LaTeX2e-style command
% interfaces. As the design and implementation of these commands
% have not yet been completed, this section is currently empty.
%
% 
% \subsection{Error Conditions}
%
% The current implementation reports an error under the following
% conditions:
% \begin{itemize}
%   \item The number of rows or columns is negative when creating a matrix;
%   \item The matrix variable has already been defined when creating a matrix;
%   \item A constant matrix is used as the target of a modification operation;
%   \item The number of items in the element list exceeds the total
%         number of elements in the matrix when creating or setting a matrix;
%   \item The dimensions of the two operands do not match when performing
%         an element-wise binary operation between matrices;
%   \item The number of columns in the left operand does not match
%         the number of rows in the right operand when performing
%         matrix multiplication.
% \end{itemize}
%
% \cleardoublepage{}
%
% 
% \end{documentation}
%
%
% ^^A ---------------------------------- 实现部分 ----------------------------------
%
% \begin{implementation}
%
% \section{实现设计}
%
% 一个矩阵对象由矩阵描述符和矩阵数据两部分组成。矩阵变量直接存储
% 矩阵描述符，而矩阵描述符中的一个字段记录矩阵数据的存储位置。
%
% 矩阵数据实际存储在 \pkg{fparray} 数组中。由于后者的数据修改
% 采用全局操作，为保证矩阵描述符与矩阵数据的更新保持同步，
% 两者的更新也均采用全局操作。因此，矩阵的创建和修改不会因普通
% \TeX{} 分组结束而自动恢复。
%
% \subsection{矩阵描述符}
%
% 矩阵描述符是一个特殊的凭据表，由以下四个整数字段组成：
% |<length>|、|<rows>|、|<columns>| 和 |<space-index>|。
% 各字段之间使用专用扫描标记分隔，并以结束标记结尾。
% 各字段的含义如下：
% \begin{description}
%   \item[|<length>|] 矩阵的元素总数，即行数与列数的乘积；
%   \item[|<rows>| / |<columns>|] 矩阵的行数和列数；
%   \item[|<space-index>|] 矩阵在所属存储类别中的逻辑索引。
% \end{description}
%
% \subsection{存储管理}
%
% 矩阵数据存储在 \pkg{fparray} 数组的一段连续空间中。
% 存储管理器负责这段空间的分配与定位，并根据矩阵的元素总数
% 选择相应的存储类别。
%
% \subsubsection{存储类别与数组组织}
%
% 通常，存储管理器按照固定的空间容量，将 \pkg{fparray} 数组
% 划分为若干个独立空间，每个空间用于存储一个矩阵。
% 目前，存储管理器提供 $A$、$B$、$C$ 三种存储类别，分别用于存储
% 小型、中型和大型矩阵。对于超大型矩阵，则采用 $D$ 类存储方式，
% 为每个矩阵单独创建数组。
%
% 各类别的当前参数如下：
% \begin{center}
%   \begin{tabular}{c|r|r}
%     类别 & 单个空间容量 & 每个数组可容纳的空间数 \\
%     \hline
%     A & 20 & 200 \\
%     B & 100 & 40 \\
%     C & 1000 & 4 \\
%     D & 按矩阵长度分配 & 每个数组对应一个矩阵
%   \end{tabular}
% \end{center}
%
% \subsubsection{逻辑索引与空间定位}
%
% 矩阵的存储类别由其元素总数决定，具体划分如下：
% 元素总数不超过 $20$ 时使用 $A$ 类；超过 $20$ 且不超过 $100$ 时使用 $B$ 类；
% 超过 $100$ 且不超过 $1000$ 时使用 $C$ 类；超过 $1000$ 时使用 $D$ 类。
%
% |<space-index>| 表示矩阵在所属存储类别中的逻辑索引。
% 矩阵的元素总数决定其存储类别，而存储类别与逻辑索引共同确定
% 矩阵数据的实际存储位置。
%
% 对于 $A$、$B$、$C$ 类，存储管理器根据逻辑索引以及该类别每个数组
% 所能容纳的空间数，计算矩阵所属的数组编号和空间基址。
% 数组名称由存储类别字母和数组编号组成，空间基址从 $1$ 开始。
%
% 对于 $D$ 类，每个矩阵对应一个单独的数组，逻辑索引对应其数组。
% 数组基址始终为 $1$，数组长度由矩阵的元素总数决定。
%
% \subsubsection{分配与回收}
%
% 空间分配优先使用回收序列中的索引；没有可回收空间时，才使用该类别的
% 下一个索引。
% 元素总数为零时不分配实际空间。普通空矩阵使用索引 $0$，常量空矩阵使用索引
% $-1$；这两个值是空矩阵的逻辑标记，不对应任何数组或数组区间。
%
% 回收时，$A$、$B$、$C$ 类只将空间索引放回对应的回收序列，底层数组继续保留，
% 后续分配可以复用该空间。$D$ 类回收时，除登记索引外，还会删除对应的独立数组。
% 空间回收函数本身不判断矩阵是否为常量；常量空间是否允许回收由矩阵操作层保证。
%
%
% \subsection{常量矩阵}
%
% 常量矩阵不使用额外的常量标记字段。宏包使用一个全局序列保存常量矩阵的
% 完整描述符内容，并通过描述符内容比较判断矩阵是否为常量。
% 修改矩阵之前，矩阵操作层检查目标描述符是否存在于该序列中；匹配时报告
% 常量矩阵错误，并中止当前操作。
%
% 这种识别方式以描述符内容而不是控制序列名称为依据。因此，复制或等价引用
% 常量矩阵描述符后，只要描述符内容不变，仍会被识别为常量矩阵。
% 常量矩阵的非空数据仍按正常类别规则分配空间。
%
% 常量保护由矩阵操作接口实现，存储管理器不承担常量判断。该保护针对宏包
% 提供的矩阵修改接口，不等同于对底层 \pkg{fparray} 变量的访问控制。
%
% \subsection{零矩阵与空矩阵}
%
% 零矩阵是所有元素均为零的矩阵，不是一种单独的存储类别。零矩阵仍按其元素
% 总数选择 $A$、$B$、$C$ 或 $D$ 类空间；归零操作直接将其现有空间置零。
%
% 空矩阵是元素总数为零的合法矩阵，包括 $0\times0$、$m\times0$ 和
% $0\times n$。空矩阵不分配实际存储空间，但行数和列数仍保留在描述符中。
% 因此，不同维度的空矩阵仍是不同形状的矩阵，参与运算时仍须执行维度兼容性检查。
%
% 对于结果元素总数为零的运算，结果描述符仍会按目标维度更新，但不会分配空间。
%
%
% 
% \section{宏包准备}
%  
%    \begin{macrocode}
%<*package>
%<@@=matrix>
%    \end{macrocode}
%
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesExplPackage{lt3matrix}{2026-11-16}{0.1} 
  {a lightweight global matrix base-on fparray}
%    \end{macrocode}
%
%
% 定义一些 \pkg{expl3} 函数的常用变体。 
%    \begin{macrocode}
\cs_generate_variant:Nn \iow_log:n { V, e }
%    \end{macrocode}
%
%  
% \begin{variable}{\l_@@_tmpa_int, \l_@@_tmpb_int, \l_@@_tmpa_fp, \l_@@_tmpb_fp,
%                  \l_@@_tmpa_tl,  \l_@@_tmpb_tl}
% 定义一些通用的临时变量。
%    \begin{macrocode}
\int_new:N  \l_@@_tmpa_int
\int_new:N  \l_@@_tmpb_int
\fp_new:N   \l_@@_tmpa_fp
\fp_new:N   \l_@@_tmpb_fp
\tl_new:N   \l_@@_tmpa_tl
\tl_new:N   \l_@@_tmpb_tl
%    \end{macrocode}
% \end{variable}
%   
%  
%    
% \section{核心命令}
% 
% \subsection{消息}
%
% 
% \begin{variable}{negative-dimension, constant-matrix, too-many-elements, dimension-mismatch}
% 错误消息。
%    \begin{macrocode}
\msg_new:nnn { matrix } { negative-dimension }
  {
    Matrix~dimensions~'#1'~must~be~non-negative.
  }
\msg_new:nnn { matrix } { constant-matrix }
  {
    The~matrix~'#1'~is~constant~and~cannot~be~modified.
  }
\msg_new:nnn { matrix } { too-many-elements }
  {
    The~input~list~'#1'~contains~too~many~elements.
  }
\msg_new:nnn { matrix } { dimension-mismatch }
  {
    The~dimensions~of~the~operands~are~incompatible~for~this~operation.
  }
%    \end{macrocode}
% \end{variable}
% 
% 
% \subsection{元信息}
%
% 矩阵的元信息包含总长度、行数、列数及实际数据索引，索引指向实际数据。
% 
% \subsubsection{基础变量}
% 
% \begin{variable}{\s_@@, \s_@@_mark, \s_@@_stop}
% 存储数据用的扫描标记。
%    \begin{macrocode}
\scan_new:N \s_@@
\scan_new:N \s_@@_mark
\scan_new:N \s_@@_stop
%    \end{macrocode}
% \end{variable}
% 
% \begin{variable}{\g_@@_const_seq}
% 常量矩阵登记表。
%    \begin{macrocode}
\seq_new:N \g_@@_const_seq
%    \end{macrocode}
% \end{variable}
% 
% 
% \begin{variable}{\l_@@_length_int, \l_@@_row_int, \l_@@_col_int, \l_@@_index_int}
% 保存矩阵信息的临时变量。
%    \begin{macrocode}
\int_new:N  \l_@@_length_int
\int_new:N  \l_@@_row_int
\int_new:N  \l_@@_col_int
\int_new:N  \l_@@_index_int
%    \end{macrocode}
% \end{variable}
% 
%
% \subsubsection{设置信息}
% 
% \begin{macro}{\@@_meta_gset:N, \@@_meta_gset:Nnnnn}
% 将 |#1| 的值设置为矩阵基本信息。
%    \begin{macrocode}
\cs_new:Nn \@@_meta_gset:Nnnnn
  {
    \tl_gset:Nn #1 
      { 
        \s_@@      #2 % Length
        \s_@@_mark #3 % Row Count
        \s_@@_mark #4 % Column Count
        \s_@@_mark #5 % Index
        \s_@@_stop 
      }
  }
\cs_generate_variant:Nn \@@_meta_gset:Nnnnn { NVVVV }
%    \end{macrocode}
% 这是一个使用临时变量的简化版本。   
%    \begin{macrocode}
\cs_new:Nn \@@_meta_gset:N
  {
    \@@_meta_gset:NVVVV #1
      \l_@@_length_int
      \l_@@_row_int
      \l_@@_col_int
      \l_@@_index_int
  }
%    \end{macrocode}
% \end{macro}
%
% 
% \subsubsection{解析信息}
% 
% \begin{macro}{\@@_parse_aux:w}
% 解析矩阵信息，并结果设置到 |#5~#8|。
%    \begin{macrocode}
\cs_new:Npn \@@_parse_aux:w
  \s_@@      #1
  \s_@@_mark #2
  \s_@@_mark #3
  \s_@@_mark #4
  \s_@@_stop #5#6#7#8
  {
    \int_set:Nn #5 {#1}
    \int_set:Nn #6 {#2}
    \int_set:Nn #7 {#3}
    \int_set:Nn #8 {#4}
  } 
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\@@_meta_parse:N, \@@_meta_parse:NNNNN}
% 解析矩阵信息，并结果设置到 |#2~#5|。
%    \begin{macrocode}
\cs_new:Nn \@@_meta_parse:NNNNN 
  {
    \exp_last_unbraced:NV 
      \@@_parse_aux:w #1 #2#3#4#5
  }
%    \end{macrocode}
% 这是一个使用临时变量的简化版本。   
%    \begin{macrocode}
\cs_new:Nn \@@_meta_parse:N
  {
    \exp_last_unbraced:NV 
      \@@_parse_aux:w #1
      \l_@@_length_int
      \l_@@_row_int
      \l_@@_col_int
      \l_@@_index_int
  }
%    \end{macrocode}
% \end{macro}
% 
% 
% \subsection{数据池}
% 
% 在实际实现中，每个 \texttt{fparray} 按固定大小划分为若干空间，
% 每个空间只存储一份矩阵数据。根据空间大小，预定义
% 小（$A$ 类）、中（$B$ 类）和大（$C$ 类）三种存储池，
% 以适应不同大小的矩阵。
% 
% In practice, each \texttt{fparray} is divided into a number of
% fixed-size spaces, each of which stores one matrix.
% Three storage pool classes are predefined according to space size:
% small ($A$), medium ($B$), and large ($C$),
% to accommodate matrices of different sizes.
%
% 对于元素总数超过 $C$ 类空间容量的矩阵（$D$ 类），
% 则为每个矩阵单独分配一个数组。
%
% Matrices whose number of elements exceeds the capacity of a
% $C$-class space ($D$ class) are allocated a separate array.
% 
% \subsubsection{常量}
% 
% 
% \begin{variable}{\c_@@_size_a_int, \c_@@_size_b_int, \c_@@_size_c_int}
% 三种划分 \pkg{fparray} 对应的空间大小。
%    \begin{macrocode}
\int_const:Nn \c_@@_size_a_int { 20   }
\int_const:Nn \c_@@_size_b_int { 100  }
\int_const:Nn \c_@@_size_c_int { 1000 }
%    \end{macrocode}
% \end{variable}
% 
% 
% \begin{variable}{\c_@@_array_length_int}
% 每个 \pkg{fparray} 变量的长度。
%    \begin{macrocode}
\int_const:Nn \c_@@_array_length_int { 4000 }
%    \end{macrocode}
% \end{variable}
% 
%  
% \begin{variable}{\c_@@_count_a_int, \c_@@_count_b_int, \c_@@_count_c_int}
% 单个 \pkg{fparray} 实际划分出的空间数量。
%    \begin{macrocode}
\int_const:Nn \c_@@_count_a_int 
  { \c_@@_array_length_int / \c_@@_size_a_int }
\int_const:Nn \c_@@_count_b_int
  { \c_@@_array_length_int / \c_@@_size_b_int }
\int_const:Nn \c_@@_count_c_int
  { \c_@@_array_length_int / \c_@@_size_c_int }
%    \end{macrocode}
% \end{variable}
% 
% 
% \subsubsection{变量}
% 
% \begin{variable}{\g_@@_a_i_fparray, \g_@@_b_i_fparray, \g_@@_c_i_fparray, \g_@@_d_i_fparray}
% 四种数据池演示，当前不实际申请（使用时自动申请）。\\
% 数据池的变量名形式为：\cs[no-index]{g_@@_<type>_<array index>_faparray}。
%    \begin{macrocode}
%<demo>\fparray_new:Nn \g_@@_a_i_fparray { \c_@@_array_length_int }
%<demo>\fparray_new:Nn \g_@@_b_i_fparray { \c_@@_array_length_int }
%<demo>\fparray_new:Nn \g_@@_c_i_fparray { \c_@@_array_length_int }
%<demo>\fparray_new:Nn \g_@@_d_i_fparray { \l_@@_length_int }
%    \end{macrocode}
% \end{variable}
% 
%  
% 
% \begin{variable}{\g_@@_next_a_int, \g_@@_next_b_int, \g_@@_next_c_int, \g_@@_next_d_int}
% 数据池中的下一个空间索引。
%    \begin{macrocode}
\int_new:N    \g_@@_next_a_int
\int_new:N    \g_@@_next_b_int
\int_new:N    \g_@@_next_c_int
\int_new:N    \g_@@_next_d_int
%    \end{macrocode} 
%    \begin{macrocode}
\int_gset:Nn  \g_@@_next_a_int { 1 }
\int_gset:Nn  \g_@@_next_b_int { 1 }
\int_gset:Nn  \g_@@_next_c_int { 1 }
\int_gset:Nn  \g_@@_next_d_int { 1 }
%    \end{macrocode}
% \end{variable}
% 
% 
% \begin{variable}{\g_@@_free_a_seq, \g_@@_free_b_seq, \g_@@_free_c_seq, \g_@@_free_d_seq}
% 数据池回收的空间索引。
%    \begin{macrocode}
\seq_new:N    \g_@@_free_a_seq
\seq_new:N    \g_@@_free_b_seq
\seq_new:N    \g_@@_free_c_seq
\seq_new:N    \g_@@_free_d_seq
%    \end{macrocode}
% \end{variable}
% 
% \begin{variable}{\l_@@_space_class_tl, \l_@@_space_size_int}
% 用于存储空间属性的临时变量。
%    \begin{macrocode}
\tl_new:N   \l_@@_space_class_tl
\int_new:N  \l_@@_space_size_int
%    \end{macrocode}
% \end{variable}
% 
% \begin{variable}{\l_@@_fparray, \l_@@_base_int}
% 用于存储实际分配的空间的信息的临时变量。
%    \begin{macrocode}
\cs_new:Npn \l_@@_fparray {}
\int_new:N  \l_@@_base_int
%    \end{macrocode}
% \end{variable}
%
%
% \subsubsection{空间选择}
% 
% \begin{macro}{\@@_space_select:, \@@_space_select:n}
% 查询某个长度（|#1|）的矩阵对应的空间的相关属性（类型与大小）。
% 结果保存在 \cs{l_@@_space_type_tl} 与 \cs{l_@@_space_size_int} 中。
%    \begin{macrocode}
\cs_new:Nn \@@_space_select:n
  {
    \int_compare:nNnTF {#1} > { \c_@@_size_a_int }
      {
        \int_compare:nNnTF {#1} > { \c_@@_size_b_int }
          {
            \int_compare:nNnTF {#1} > { \c_@@_size_c_int }
              { % Class D
                \tl_set:Nn  \l_@@_space_class_tl {d}
                \int_set:Nn \l_@@_space_size_int {#1}
              }
              {  % Class C
                \tl_set:Nn  \l_@@_space_class_tl {c}
                \int_set:Nn \l_@@_space_size_int { \c_@@_size_c_int }
              }          
          }
          { % Class B
              \tl_set:Nn  \l_@@_space_class_tl {b}
              \int_set:Nn \l_@@_space_size_int { \c_@@_size_b_int }
          }
      }
      {
        \int_compare:nNnTF {#1} = { 0 }
          { % Empty           
            \tl_set:Nn  \l_@@_space_class_tl {}
            \int_set:Nn \l_@@_space_size_int { 0 }
          }
          { % Class A
            \tl_set:Nn  \l_@@_space_class_tl {a}
            \int_set:Nn \l_@@_space_size_int { \c_@@_size_a_int }
          }
      }
  }
%    \end{macrocode}
% 这是一个使用临时变量的简化版本。
%    \begin{macrocode}
\cs_new:Nn \@@_space_select:
  {
    \@@_space_select:n { \l_@@_length_int }
  }
%    \end{macrocode}
% \end{macro}
% 
% 
% \subsubsection{空间分配}
%
% \begin{macro}{\@@_space_allocate_aux:n}
% 获取下一个可用空间索引。|#1| 空间类型，结果保存在 \cs{l_@@_index_int} 中。
%    \begin{macrocode}
\cs_new:Nn \@@_space_allocate_aux:n 
  {
    \seq_if_empty:cTF { g_@@_free_#1_seq }
      { % 无回收空间，使用下一个空间
        \int_set_eq:Nc \l_@@_index_int { g_@@_next_#1_int  }
        \int_set_eq:Nc \l_@@_tmpa_int  { c_@@_count_#1_int }
        \int_compare:nNnT
          { \int_mod:nn { \l_@@_index_int } { \l_@@_tmpa_int } } = { 1 }
          { % 需要新数组
            \int_set:Nn \l_@@_tmpb_int
              { \int_div_truncate:nn { \l_@@_index_int - 1} { \l_@@_tmpa_int } }
            \int_incr:N \l_@@_tmpb_int
            \exp_args:Nc \fparray_new:Nn 
              { g_@@_#1_ \int_to_roman:n { \l_@@_tmpb_int } _fparray }
              { \c_@@_array_length_int }
          }
          \int_gincr:c { g_@@_next_#1_int }
      }
      { % 有回收空间，直接使用
        \seq_gpop_left:cN { g_@@_free_#1_seq } \l_@@_tmpa_tl
        \int_set:Nn \l_@@_index_int { \l_@@_tmpa_tl }
      }
  }
\cs_generate_variant:Nn \@@_space_allocate_aux:n { V }
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\@@_space_allocate_aux_d:n}
% 获取下一个可用空间索引（|D| 类型）。|#1| 空间大小，结果保存在 \cs{l_@@_index_int} 中。
%    \begin{macrocode}
\cs_new:Nn \@@_space_allocate_aux_d:n
  {
    \seq_if_empty:NTF \g_@@_free_d_seq
      { % 无回收空间，使用下一个空间
        \int_set_eq:NN \l_@@_index_int \g_@@_next_d_int 
        \int_gincr:N \g_@@_next_d_int
      }
      { % 有回收空间，直接使用
        \seq_gpop_left:NN \g_@@_free_d_seq \l_@@_tmpa_tl
        \int_set:Nn \l_@@_index_int { \l_@@_tmpa_tl }
      }
      \exp_args:Nc \fparray_new:Nn 
        { g_@@_d_ \int_to_roman:n { \l_@@_index_int } _fparray }
        { #1 }
  }
%    \end{macrocode}
% \end{macro}
% 
% 
% \begin{macro}{\@@_space_allocate:, \@@_space_allocate:n}
% 申请空间。|#1| 空间大小，结果保存在 \cs{l_@@_index_int} 中。
%    \begin{macrocode}
\cs_new:Nn \@@_space_allocate:n 
  {
    \int_compare:nNnTF {#1} = { 0 }
      { \int_set:Nn \l_@@_index_int { 0 } } % Emtpy Matrices
      { 
        \@@_space_select:n {#1}
        \int_compare:nNnTF {#1} > { \c_@@_size_c_int }
          { \@@_space_allocate_aux_d:n {#1} } % Class D
          { \@@_space_allocate_aux:V \l_@@_space_class_tl } % Class A ~ C
      }
  }
%    \end{macrocode}
% 这是一个使用临时变量的简化版本。
%    \begin{macrocode}
\cs_new:Nn \@@_space_allocate:
  {
    \@@_space_allocate:n { \l_@@_length_int }
  }
%    \end{macrocode}
% \end{macro}
% 
% 
% \subsubsection{空间回收}
% 
% \begin{macro}{\@@_space_free_aux:nn}
% 回收空间辅助函数。|#1| 空间大小，|#2| 空间索引。
%    \begin{macrocode}
\cs_new:Nn \@@_space_free_aux:nn 
  {
    \@@_space_select:n {#1}
    \seq_gput_right:cn { g_@@_free_ \l_@@_space_class_tl _seq } {#2}
    \int_compare:nNnT {#1} > { \c_@@_size_c_int }
      { \cs_undefine:c { g_@@_d_ \int_to_roman:n { #2 } _fparray } }
  }
\cs_generate_variant:Nn \@@_space_free_aux:nn { VV } 
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\@@_space_free:, \@@_space_free:nn}
% 回收空间函数。|#1| 空间大小，|#2| 空间索引。不负责常量空间校对。
%    \begin{macrocode}
\cs_new:Nn \@@_space_free:nn 
  {
    \int_compare:nNnT {#1} > {0}
      {
        \int_set:Nn \l_@@_tmpa_int {#1}
        \int_set:Nn \l_@@_tmpb_int {#2}
        \@@_space_free_aux:VV \l_@@_tmpa_int \l_@@_tmpb_int
      }    
  }
%    \end{macrocode}
% 这是一个使用临时变量的简化版本。
%    \begin{macrocode}
\cs_new:Nn \@@_space_free:
  {
    \@@_space_free:nn      
      { \l_@@_length_int }
      { \l_@@_index_int  } 
  }
%    \end{macrocode}
% \end{macro}
% 
% 
% \subsubsection{查询定位}
% 
% \begin{macro}{\@@_space_query_aux:nn}
% 查询指定类型的空间的信息。|#1| 空间类型，|#2| 空间索引。
% 结果保存在 \cs{l_@@_fparray} 与 \cs{l_@@_base_int} 中。
%    \begin{macrocode}
\cs_new:Nn \@@_space_query_aux:nn
  {
    \int_set_eq:Nc \l_@@_tmpa_int { c_@@_count_#1_int }
    \int_set:Nn    \l_@@_tmpb_int
      { \int_div_truncate:nn { #2 - 1 } { \l_@@_tmpa_int } }
    \int_incr:N    \l_@@_tmpb_int
    \cs_set_eq:Nc  \l_@@_fparray 
      { g_@@_#1_ \int_to_roman:n { \l_@@_tmpb_int } _fparray }
    \int_set:Nn    \l_@@_base_int
      { 
        \int_mod:nn { #2 - 1 } { \l_@@_tmpa_int } * 
        \int_use:c  { c_@@_size_#1_int } + 1
      }      
  }
\cs_generate_variant:Nn \@@_space_query_aux:nn { V }
%    \end{macrocode}
% \end{macro}
% 
% 
% \begin{macro}{\@@_space_query:, \@@_space_query:nn}
% 查询空间信息。|#1| 空间大小，|#2| 空间索引。
% 结果保存在 \cs{l_@@_fparray} 与 \cs{l_@@_base_int} 中。
%    \begin{macrocode}
\cs_new:Nn \@@_space_query:nn
  {
    \@@_space_select:n {#1}
    \int_compare:nNnTF {#1} = { 0 }
      { 
        \int_zero:N \l_@@_base_int
        \cs_set:Npn \l_@@_fparray {}         
      }
      {
        \int_compare:nNnTF {#1} > { \c_@@_size_c_int } 
          { % Class D
            \int_set:Nn   \l_@@_base_int { 1 }
            \cs_set_eq:Nc \l_@@_fparray
              { g_@@_d_ \int_to_roman:n {#2} _fparray }
          } 
          { \@@_space_query_aux:Vn \l_@@_space_class_tl {#2} } % Class A ~ C
      }
  }
%    \end{macrocode}
% 这是一个使用临时变量的简化版本。
%    \begin{macrocode}
\cs_new:Nn \@@_space_query:
  {
    \@@_space_query:nn      
      { \l_@@_length_int }
      { \l_@@_index_int  } 
  }
%    \end{macrocode}
% \end{macro}
% 
% 
% \subsubsection{数据设置}
% 
% 
% 
% \begin{macro}{\@@_data_gzero:, \@@_data_gzero:Nnn}
% 将指定 \pkg{fparray} 的指定区间的数据置零。
% |#1| 数组，|#2| 起点，|#3| 长度。
%    \begin{macrocode}
\cs_new:Nn \@@_data_gzero:Nnn
  {
    \int_step_inline:nnn {#2} { #2 + #3 - 1 }      
      { \fparray_gset:Nnn #1 {##1} { 0 } }
  }
%    \end{macrocode}
% 这是一个使用临时变量的简化版本。
%    \begin{macrocode}
\cs_new:Nn \@@_data_gzero:
  {
    \@@_data_gzero:Nnn \l_@@_fparray
      { \l_@@_base_int } 
      { \l_@@_space_size_int }
  }
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\@@_data_gset:n, \@@_data_gset:Nnnn}
% 使用指定数据将填充 \pkg{fparray} 的指定区间，数据不足时补零。
% |#1| 数组，|#2| 起点，|#3| 长度，|#4| 指定数据。
%    \begin{macrocode}
\cs_new:Nn \@@_data_gset:Nnnn
  {
    \int_set:Nn \l_@@_tmpa_int {#2} 
    \clist_map_inline:nn {#4} % Fill Data
      {
        \fparray_gset:Nnn #1 { \l_@@_tmpa_int } {##1}
        \int_incr:N \l_@@_tmpa_int
      }
    \int_step_inline:nnn      % Fill 0
      { \l_@@_tmpa_int } { #2 + #3 - 1 }
      { \fparray_gset:Nnn #1 {##1} { 0 } }
  }
%    \end{macrocode}
% 这是一个使用临时变量的简化版本。
%    \begin{macrocode}
\cs_new:Nn \@@_data_gset:n
  {
    \@@_data_gset:Nnnn \l_@@_fparray
      { \l_@@_base_int } 
      { \l_@@_space_size_int }
      {#1}
  }
%    \end{macrocode}
% \end{macro}
% 
% 
% \begin{macro}{\@@_data_gcopy:NnNnn}
% 使两块区域的内容完成相等。
% |#1| 目标数组，|#2| 目标起点，|#3| 源数组，|#4| 源起点，|#4| 长度。
%    \begin{macrocode}
\cs_new:Nn \@@_data_gcopy:NnNnn
  {
    \int_step_inline:nnn { 0 } { #5 - 1 }
      {
        \fparray_gset:Nnn #1 { #2 + ##1 }
          { \fparray_item:Nn #3 { #4 + ##1 } }
      }
  }
%    \end{macrocode}
% \end{macro}
% 
% 
% \subsubsection{数据输出}
% 
% 
% \begin{macro}{\@@_data_typeset:Nnnn}
% 在公式环境中排版 \pkg{fparray} 内容，命令本身不会自动切换到公式环境。
% |#1| 数组，|#2| 起点，|#3| 长度，|#4| 每行列数。
%    \begin{macrocode}
\cs_new:Nn \@@_data_typeset:Nnnn
  {
    \tl_set:Nn \l_@@_tmpa_tl 
      { \left( \begin{array}{*{#4}{c}} }
    \int_step_inline:nnn { #2 } { #2 + #3 - 1 }
      { 
        \tl_put_right:Ne \l_@@_tmpa_tl 
          { \fparray_item:Nn #1 {##1} }
        \int_compare:nNnTF 
          { \int_mod:nn { ##1 - #2 + 1} { #4 } } = { 0 }
          { \tl_put_right:Nn \l_@@_tmpa_tl { \\ } } 
          { \tl_put_right:Nn \l_@@_tmpa_tl { & } }
      }
    \regex_replace_once:nnN { \c{\\}\Z } {} \l_@@_tmpa_tl 
    \tl_put_right:Nn \l_@@_tmpa_tl 
      { \end{array} \right) } 
    \l_@@_tmpa_tl  
  }
%    \end{macrocode}
% \end{macro}
% 
% 
% \begin{macro}{\@@_data_log:Nnnn}
% 在日志中查看 \pkg{fparray} 内容。|#1| 数组，|#2| 起点，|#3| 长度，|#4| 每行列数。
%    \begin{macrocode}
\cs_new:Nn \@@_data_log:Nnnn
  {
    \int_set:Nn \l_@@_tmpa_int { 1 }
    \tl_set:Ne \l_@@_tmpa_tl 
      { <\int_use:N \l_@@_tmpa_int>:~ }
    \int_step_inline:nnn { #2 } { #2 + #3 - 1 }
      { 
        \tl_put_right:Ne \l_@@_tmpa_tl 
          { \fparray_item:Nn #1 {##1} }
        \int_compare:nNnTF 
          { \int_mod:nn { ##1 - #2 + 1} { #4 } } = { 0 }
          { 
            \iow_log:V  \l_@@_tmpa_tl 
            \int_incr:N \l_@@_tmpa_int
            \tl_set:Ne  \l_@@_tmpa_tl 
              { <\int_use:N \l_@@_tmpa_int>:~ }
          } 
          { \tl_put_right:Nn \l_@@_tmpa_tl  { ,~ } }
      }  
  }
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\@@_data_log:Nnnnn}
% 在日志中查看 \pkg{fparray} 内容。|#1| 数组，|#2| 起点，|#3| 长度，|#4| 每行列数, |#5| 空间长度。
%    \begin{macrocode}
\cs_new:Nn \@@_data_log:Nnnnn
  { 
    \@@_data_log:Nnnn #1 {#2} {#3} {#4}
    \tl_set:Nn \l_@@_tmpa_tl { <unused>: }
    \int_step_inline:nnn { #3 } { #5 - 1 }
      { 
        \tl_put_right:Ne \l_@@_tmpa_tl 
          { ~\fparray_item:Nn #1 { #2 + ##1 }, }
      }
    \int_compare:nNnTF {#3} = {#5}
      { \tl_put_right:Nn \l_@@_tmpa_tl { ~none. }  }
      { \regex_replace_once:nnN { ,\Z } { . } \l_@@_tmpa_tl  }
    \iow_log:V \l_@@_tmpa_tl 
  }
%    \end{macrocode}
% \end{macro}
% 
% \section{矩阵命令}
% 
% 
% \subsection{创建与初始化矩阵}
% 
% 
% \subsubsection{创建矩阵}
% 
% \begin{macro}{\matrix_new:Nnn, \matrix_new:cnn}
% 定义新矩阵。
%    \begin{macrocode}
\cs_new_protected:Nn \matrix_new:Nnn
  {
    \bool_lazy_or:nnTF
      { \int_compare_p:nNn {#2} < {0} }
      { \int_compare_p:nNn {#3} < {0} }
      { \msg_error:nnn { matrix } { negative-dimension } {#2x#3} }  
      {
        \tl_new:N #1  % 防止变量已使用
        \int_set:Nn \l_@@_length_int { #2 * #3 }
        \int_set:Nn \l_@@_row_int {#2}
        \int_set:Nn \l_@@_col_int {#3}
        \int_compare:nNnTF 
          { \l_@@_length_int } = { 0 }
          { \int_set:Nn \l_@@_index_int { 0 } } % Empty Matrices
          { % Non-Empty Matrices
            \@@_space_allocate:
            \@@_space_query:
            \@@_data_gzero:
          }
        \@@_meta_gset:N #1
      }
  }
\cs_generate_variant:Nn \matrix_new:Nnn { c }
%    \end{macrocode}
% \end{macro}
% 
% 
% \begin{macro}{\matrix_const:Nnnn, \matrix_const:cnnn}
% 定义新矩阵。
%    \begin{macrocode}
\cs_new_protected:Nn \matrix_const:Nnnn
  {
    \bool_lazy_or:nnTF
      { \int_compare_p:nNn {#2} < {0} }
      { \int_compare_p:nNn {#3} < {0} }
      { \msg_error:nnn { matrix } { negative-dimension } {#2x#3} } 
      {
        \int_set:Nn \l_@@_length_int { #2 * #3 }
        \int_set:Nn \l_@@_row_int {#2}
        \int_set:Nn \l_@@_col_int {#3}
        \int_compare:nNnTF 
          { \clist_count:n {#4} } > { \l_@@_length_int } 
          { \msg_error:nnn { matrix } { too-many-elements } {#4} }          
          { 
            \tl_new:N #1  % 防止变量已使用
            \int_compare:nNnTF 
              { \l_@@_length_int } = { 0 }
              { \int_set:Nn \l_@@_index_int { -1 } } % Empty Matrices
              { % Non-Empty Matrices
                \@@_space_allocate:
                \@@_space_query:
                \@@_data_gset:n {#4}
              } 
            \@@_meta_gset:N #1
            \seq_gput_right:NV \g_@@_const_seq #1        
          }        
      }
  }
\cs_generate_variant:Nn \matrix_const:Nnnn { c }
%    \end{macrocode}
% \end{macro}
% 
% 
% \subsubsection{设置矩阵}
% 
% \begin{macro}{\matrix_gzero:N, \matrix_gzero:c}
% 矩阵归零。
%    \begin{macrocode}
\cs_new_protected:Nn \matrix_gzero:N
  {    
    \seq_if_in:NVTF \g_@@_const_seq #1
      { \msg_error:nnn { matrix } { constant-matrix } { \token_to_str:N #1 } }
      {
        \@@_meta_parse:N #1
        \int_compare:nNnT
          { \l_@@_length_int } > { 0 }
          { \@@_space_query: \@@_data_gzero: }
      }
  }
\cs_generate_variant:Nn \matrix_gzero:N { c }
%    \end{macrocode}
% \end{macro}
% 
% 
% \begin{macro}{\matrix_gset:Nn, \matrix_gset:cn}
% 设置矩阵的值。
%    \begin{macrocode}
\cs_new_protected:Nn \matrix_gset:Nn 
  {
    \seq_if_in:NVTF \g_@@_const_seq #1
      { \msg_error:nnn { matrix } { constant-matrix } { \token_to_str:N #1 } }
      {        
        \@@_meta_parse:N #1
        \int_compare:nNnTF 
          { \clist_count:n {#2} } > { \l_@@_length_int } 
          { \msg_error:nnn { matrix } { too-many-elements } {#2} }
          { \@@_space_query: \@@_data_gset:n {#2} }    
      }
  }
\cs_generate_variant:Nn \matrix_gset:Nn { c }
%    \end{macrocode}
% \end{macro}
% 
% 
% \subsubsection{显示矩阵}
% 
% \begin{macro}{\matrix_use:N, \matrix_use:c}
% 显示矩阵。
%    \begin{macrocode}
\cs_new_protected:Nn \matrix_use:N
  {
    \@@_meta_parse:N #1   
    \int_compare:nNnTF
      { \l_@@_length_int } = { 0 }
      { \left(~<\int_use:N \l_@@_row_int>~x~<\int_use:N \l_@@_col_int>~\right) }
      { 
        \@@_space_query:
        \@@_data_typeset:Nnnn \l_@@_fparray 
          { \l_@@_base_int } { \l_@@_length_int } { \l_@@_col_int }
      }
  }
\cs_generate_variant:Nn \matrix_use:N { c }
%    \end{macrocode}
% \end{macro}
%  
% 
% \begin{macro}{\matrix_log:N}
% 查看矩阵。
%    \begin{macrocode}
\cs_new_protected:Nn \matrix_log:N
  {
    \@@_meta_parse:N #1
    \iow_log:n { The~matrix's~base~information:~ }
    \iow_log:V #1
    \int_compare:nNnTF { \l_@@_length_int } > { 0 }
      {
        \@@_space_query:nn { \l_@@_length_int } { \l_@@_index_int }
        \iow_log:e { The~matrix's~data: <base:~\int_use:N \l_@@_base_int>~ }
        \@@_data_log:Nnnnn \l_@@_fparray
          { \l_@@_base_int } { \l_@@_length_int } 
          { \l_@@_col_int  } { \l_@@_space_size_int }
      }
      { \iow_log:n { The~matrix~does~not~has~any~data~! } }    
  }
\cs_generate_variant:Nn \matrix_log:N { c }
%    \end{macrocode}
% \end{macro}
% 
% 
% \subsubsection{预定义矩阵}
% 
% \begin{macro}{\g_tmpa_matrix, \g_tmpb_matrix}
% 本宏包永不使用的临时变量。
%    \begin{macrocode}
\matrix_new:Nnn  \g_tmpa_matrix { 0 } { 0 }
\matrix_new:Nnn  \g_tmpb_matrix { 0 } { 0 }
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\c_empty_matrix, \c_identity_two_matrix, 
%               \c_identity_three_matrix , \c_identity_four_matrix }
% 定义长度为零的特殊矩阵，零索引不指向任何实际数据。
%    \begin{macrocode}
\matrix_const:Nnnn \c_empty_matrix 
  { 0 } { 0 } {}
\matrix_const:Nnnn \c_identity_two_matrix 
  { 2 } { 2 } { 1, 0, 0, 1 }
\matrix_const:Nnnn \c_identity_three_matrix 
  { 3 } { 3 } { 1, 0, 0, 0, 1, 0, 0, 0, 1 }
\matrix_const:Nnnn \c_identity_four_matrix 
  { 4 } { 4 } 
  { 
    1, 0, 0, 0, 
    0, 1, 0, 0, 
    0, 0, 1, 0, 
    0, 0, 0, 1 
  }
%    \end{macrocode}
% \end{macro}
% 
% 
% \subsection{映射与运算}
% 
% \subsubsection{运算专用变量}
% 
% \begin{variable}
%   {   
%     \l_@@_opa_row_int, \l_@@_opb_row_int, 
%     \l_@@_opa_col_int, \l_@@_opb_col_int, 
%     \l_@@_old_length_int, \l_@@_old_index_int
%   }
% 矩阵运算时使用的临时元数据。
%    \begin{macrocode}
\int_new:N  \l_@@_opa_row_int
\int_new:N  \l_@@_opb_row_int
\int_new:N  \l_@@_opa_col_int
\int_new:N  \l_@@_opb_col_int
\int_new:N  \l_@@_old_length_int
\int_new:N  \l_@@_old_index_int
%    \end{macrocode}
% \end{variable}
% 
% \begin{variable}{\l_@@_opa_fparray,  \l_@@_opb_fparray,
%                  \l_@@_opa_base_int, \l_@@_opb_base_int}
% 矩阵运算时使用的临时数组信息。
%    \begin{macrocode}
\cs_new:Npn \l_@@_opa_fparray {}
\cs_new:Npn \l_@@_opb_fparray {}
\int_new:N  \l_@@_opa_base_int
\int_new:N  \l_@@_opb_base_int
%    \end{macrocode}
% \end{variable}
% 
% \subsubsection{运算准备与收尾}
% 
% \begin{macro}{\@@_left_operand_prepare:N, \@@_right_operand_prepare:N}
% 操作数准备。
%    \begin{macrocode}
\cs_new:Nn \@@_left_operand_prepare:N
  {
    \@@_meta_parse:N #1
    \int_set_eq:NN \l_@@_opa_row_int    \l_@@_row_int 
    \int_set_eq:NN \l_@@_opa_col_int    \l_@@_col_int
    \@@_space_query:
    \cs_set_eq:NN  \l_@@_opa_fparray    \l_@@_fparray
    \int_set_eq:NN \l_@@_opa_base_int   \l_@@_base_int
  }
\cs_new:Nn \@@_right_operand_prepare:N
  {
    \@@_meta_parse:N #1
    \int_set_eq:NN \l_@@_opb_row_int    \l_@@_row_int 
    \int_set_eq:NN \l_@@_opb_col_int    \l_@@_col_int
    \@@_space_query:
    \cs_set_eq:NN   \l_@@_opb_fparray    \l_@@_fparray
    \int_set_eq:NN  \l_@@_opb_base_int   \l_@@_base_int
  }
\cs_generate_variant:Nn \@@_left_operand_prepare:N  { c }
\cs_generate_variant:Nn \@@_right_operand_prepare:N { c }
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\@@_inplace_prepare:N}
% 原地修改准备，清空旧的空间信息以误回收。
%    \begin{macrocode}
\cs_new:Nn \@@_inplace_prepare:N
  {
    \seq_if_in:NVTF \g_@@_const_seq #1
      { 
        \msg_error:nnn { matrix } { constant-matrix } { \token_to_str:N #1 } 
        \matrix_map_break:
      }
      {
        \@@_meta_parse:N #1
        \@@_space_query:
        \int_zero:N \l_@@_old_length_int
        \int_zero:N \l_@@_old_index_int
      }    
  }
\cs_generate_variant:Nn \@@_inplace_prepare:N { c }
%    \end{macrocode}
% \end{macro}
% 
% 
% \begin{macro}{\@@_result_prepare:Nnn}
% 结果准备，额外提供行列数，需要重新申请空间。旧空间不保留暂不回收。
%    \begin{macrocode}
\cs_new:Nn \@@_result_prepare:Nnn
  {
    \seq_if_in:NVTF \g_@@_const_seq #1
      { 
        \msg_error:nnn { matrix } { constant-matrix } { \token_to_str:N #1 } 
        \matrix_map_break:
      }
      {
        \@@_meta_parse:N #1
        \int_set_eq:NN \l_@@_old_length_int \l_@@_length_int
        \int_set_eq:NN \l_@@_old_index_int  \l_@@_index_int
        \int_set:Nn \l_@@_row_int {#2}
        \int_set:Nn \l_@@_col_int {#3}
        \int_set:Nn \l_@@_length_int { #2 * #3 }
        \@@_space_allocate:
        \@@_meta_gset:N #1
        \@@_space_query:
        \int_step_inline:nnn { \l_@@_length_int } { \l_@@_space_size_int - 1 }
          { \fparray_gset:Nnn \l_@@_fparray { \l_@@_base_int + ##1 } { 0 } }      
      }    
  }
\cs_generate_variant:Nn \@@_result_prepare:Nnn { c }
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\@@_operation_cleanup:}
% 运算收尾。
%    \begin{macrocode}
\cs_new:Nn \@@_operation_cleanup:
  {
    \@@_space_free:nn 
      { \l_@@_old_length_int } { \l_@@_old_index_int } 
    \int_zero:N \l_@@_old_length_int
    \int_zero:N \l_@@_old_index_int
  }
%    \end{macrocode}
% \end{macro}
% 
% \subsubsection{通用映射函数}
% 
% \begin{variable}{\g_@@_map_depth_int}
% 映射嵌套深度变量。
%    \begin{macrocode}
\int_new:N  \g_@@_map_depth_int
%    \end{macrocode}
% \end{variable}
% 
% 
% \begin{variable}{\g_@@_map_intarray}
% 有限的嵌套变量。
%    \begin{macrocode}
\intarray_new:Nn \g_@@_map_intarray { 400 }
%    \end{macrocode}
% \end{variable}
% 
% \begin{macro}{\@@_map_state_save:, \@@_map_state_restore:}
% 有限的嵌套变量的保存与恢复。
%    \begin{macrocode}
\cs_new_protected:Nn \@@_map_state_save:
  {
    \int_set:Nn \l_@@_tmpa_int { (\g_@@_map_depth_int - 2) * 10 }
    \intarray_gset:Nnn \g_@@_map_intarray 
      { \l_@@_tmpa_int + 1 } { \l_@@_length_int }
    \intarray_gset:Nnn \g_@@_map_intarray 
      { \l_@@_tmpa_int + 2 } { \l_@@_row_int }
    \intarray_gset:Nnn \g_@@_map_intarray 
      { \l_@@_tmpa_int + 3 } { \l_@@_col_int }
    \intarray_gset:Nnn \g_@@_map_intarray 
      { \l_@@_tmpa_int + 4 } { \l_@@_index_int }
    \intarray_gset:Nnn \g_@@_map_intarray 
      { \l_@@_tmpa_int + 5 } { \l_@@_base_int }
  }
\cs_new_protected:Nn \@@_map_state_restore:
  {
    \int_set:Nn \l_@@_tmpa_int { (\g_@@_map_depth_int - 2) * 10 }
    \int_set:Nn \l_@@_length_int
      { \intarray_item:Nn \g_@@_map_intarray { \l_@@_tmpa_int + 1 } }
    \int_set:Nn \l_@@_row_int
      { \intarray_item:Nn \g_@@_map_intarray { \l_@@_tmpa_int + 2 } }
    \int_set:Nn \l_@@_col_int
      { \intarray_item:Nn \g_@@_map_intarray { \l_@@_tmpa_int + 3 } }
    \int_set:Nn \l_@@_index_int
      { \intarray_item:Nn \g_@@_map_intarray { \l_@@_tmpa_int + 4 } }
    \int_set:Nn \l_@@_base_int
      { \intarray_item:Nn \g_@@_map_intarray { \l_@@_tmpa_int + 5 } }
  }
%    \end{macrocode}
% \end{macro}
% 
% 
% \begin{macro}{\@@_map_item:n, \@@_map_push:, \@@_map_pop:}
% 当前映射元素处理函数。
%    \begin{macrocode}
\cs_new:Npn \@@_map_item:n #1 { }
%    \end{macrocode}
% 保存当前元素处理函数。
%    \begin{macrocode}
\cs_new_protected:Nn \@@_map_push:
  {
    \int_gincr:N \g_@@_map_depth_int
    \int_compare:nNnT
      { \g_@@_map_depth_int } > { 1 }
      {
        \cs_gset_eq:cN
          { @@_map_item_ \int_use:N \g_@@_map_depth_int :n }
          \@@_map_item:n
        \cs_gset_eq:cN
          { g_@@_map_\int_use:N \g_@@_map_depth_int _fparray }
          \l_@@_fparray
        \@@_map_state_save:
      }    
  }
%    \end{macrocode}
% 恢复上一级元素处理函数。
%    \begin{macrocode}
\cs_new_protected:Nn \@@_map_pop:
  {
    \int_compare:nNnT
      { \g_@@_map_depth_int } > { 1 }
      {
        \cs_gset_eq:Nc \@@_map_item:n
          { @@_map_item_ \int_use:N \g_@@_map_depth_int :n }
        \cs_set_eq:Nc \l_@@_fparray
          { g_@@_map_\int_use:N \g_@@_map_depth_int _fparray }          
        \@@_map_state_restore:
      }    
    \int_gdecr:N \g_@@_map_depth_int
  }
%    \end{macrocode}
% \end{macro}
% 
% 
% \begin{macro}{\matrix_map_break:, \matrix_map_break:n}
% 定义中断函数。
%    \begin{macrocode}
\cs_new_protected:Nn \matrix_map_break:
  { \prg_map_break:Nn \matrix_map_break: {  } }
\cs_new_protected:Nn \matrix_map_break:n
  { \prg_map_break:Nn \matrix_map_break: {#1} }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\matrix_map_function:NN}
% 函数式映射函数。
%    \begin{macrocode}
\cs_new_protected:Nn \matrix_map_function:NN
  {
    \@@_map_push:
    \@@_meta_parse:N #1        
    \int_compare:nNnT { \l_@@_length_int } = { 0 }
      { \matrix_map_break: }
    \@@_space_query:
    \int_step_inline:nnn {0} { \l_@@_length_int - 1 }
      {
        \exp_args:Ne #2 
          { \fparray_item:Nn \l_@@_fparray { \l_@@_base_int + ##1 } } 
      }
    \prg_break_point:Nn \matrix_map_break: { \@@_map_pop: } 
  }
%    \end{macrocode}
% \end{macro} 
% 
% \begin{macro}{\matrix_map_inline:Nn}
% 内联式映射函数。
%    \begin{macrocode}
\cs_new_protected:Nn \matrix_map_inline:Nn
  {
    \@@_map_push:
    \@@_meta_parse:N #1 
    \cs_gset:Nn \@@_map_item:n {#2}
    \int_compare:nNnT { \l_@@_length_int } = { 0 }
      { \matrix_map_break: }
    \@@_space_query:
    \int_step_inline:nnn {0} { \l_@@_length_int - 1 }
      {
        \exp_args:Ne \@@_map_item:n
          { \fparray_item:Nn \l_@@_fparray { \l_@@_base_int + ##1 } } 
      }
    \prg_break_point:Nn \matrix_map_break: { \@@_map_pop: } 
  }
%    \end{macrocode}
% \end{macro} 
% 
% 
% \subsubsection{原地映射运算}
% 
% \begin{macro}{\@@_map_inplace:Nn}
% 通过映射修改矩阵的元素。
%    \begin{macrocode}
\cs_new:Nn \@@_map_inplace:Nn
  {    
    \@@_map_push:
    \@@_inplace_prepare:N #1    
    \int_compare:nNnT { \l_@@_length_int } = { 0 }
      { \matrix_map_break: }
    \cs_gset:Nn \@@_map_item:n {#2}
    \int_step_inline:nnn {0} { \l_@@_length_int - 1 }
      {
        \fparray_gset:Nnn \l_@@_fparray { \l_@@_base_int + ##1 }
          {
            \exp_args:Ne \@@_map_item:n
              { \fparray_item:Nn \l_@@_fparray { \l_@@_base_int + ##1 } } 
          }            
      }
    \prg_break_point:Nn \matrix_map_break: { \@@_map_pop: } 
  }
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\matrix_gnegate:N, \matrix_gabs:N, \matrix_gsign:N, \matrix_ground:Nn}
% 求 $-A$、$\vert A \vert$、$sign(A)$ 与 $round(A, n)$。
%    \begin{macrocode}
\cs_new_protected:Nn \matrix_gnegate:N
  { \@@_map_inplace:Nn #1 { -##1 } }
\cs_new_protected:Nn \matrix_gabs:N
  { \@@_map_inplace:Nn #1 { abs(##1) }  }
\cs_new_protected:Nn \matrix_gsign:N
  { \@@_map_inplace:Nn #1 { sign(##1) } }
\cs_new_protected:Nn \matrix_ground:Nn
  { \@@_map_inplace:Nn #1 { round(##1, #2) } }
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\matrix_gadd:Nn, \matrix_gsub:Nn, 
%               \matrix_gmul:Nn, \matrix_gdiv:Nn, \matrix_gpower:Nn}
% 求 $A + c$、$A - c$、$cA$、$A / c$ 及 $A ^ c$。
%    \begin{macrocode}
\cs_new_protected:Nn \matrix_gadd:Nn
  { \@@_map_inplace:Nn #1 { ##1 + #2 } }
\cs_new_protected:Nn \matrix_gsub:Nn
  { \@@_map_inplace:Nn #1 { ##1 - #2 } }
\cs_new_protected:Nn \matrix_gmul:Nn
  { \@@_map_inplace:Nn #1 { ##1 * #2 } }
\cs_new_protected:Nn \matrix_gdiv:Nn
  { \@@_map_inplace:Nn #1 { ##1 / #2 } }
\cs_new_protected:Nn \matrix_gpower:Nn
  { \@@_map_inplace:Nn #1 { ##1 ^ #2 } }
%    \end{macrocode}
% \end{macro}
% 
% 
% \subsubsection{单矩阵映射运算}
% 
% 
% \begin{macro}{\@@_map_operate:NNn}
% 通过映射逐元素计算，操作数只有一个矩阵。
%    \begin{macrocode}
\cs_new:Nn \@@_map_operate:NNn
  { 
    \@@_map_push:    
    \@@_left_operand_prepare:N #2
    \@@_result_prepare:Nnn #1 { \l_@@_opa_row_int } { \l_@@_opa_col_int }
    \int_compare:nNnT { \l_@@_length_int } = { 0 }
      { \matrix_map_break: } 
    \cs_gset:Nn \@@_map_item:n {#3}
    \int_step_inline:nnn {0} { \l_@@_length_int - 1 }
      {
        \fparray_gset:Nnn \l_@@_fparray { \l_@@_base_int + ##1 }
          {
            \exp_args:Ne \@@_map_item:n
              { \fparray_item:Nn \l_@@_opa_fparray { \l_@@_opa_base_int + ##1 } } 
          }            
      }
    \prg_break_point:Nn \matrix_map_break: 
      { \@@_map_pop: \@@_operation_cleanup: }     
  }
%    \end{macrocode}
% \end{macro}
% 
% 
% \begin{macro}{\matrix_gset_eq:NN, \matrix_gset_eq:Nc, \matrix_gset_eq:cN}
% 矩阵赋值。
%    \begin{macrocode}
\cs_new_protected:Nn \matrix_gset_eq:NN
  { \@@_map_operate:NNn #1 #2 {##1} }
\cs_generate_variant:Nn \matrix_gset_eq:NN { c, Nc }
%    \end{macrocode}
% \end{macro}
% 
% 
% \begin{macro}{\matrix_gnegate:NN, \matrix_gabs:NN, \matrix_gsign:NN, \matrix_ground:NNn}
% 求 $Z=-A$、$Z=\vert A \vert$ 与 $Z=sign(A)$ 与 $Z=round(A, n)$。
%    \begin{macrocode}
\cs_new_protected:Nn \matrix_gnegate:NN
  { \@@_map_operate:NNn #1 #2 {-##1} }
\cs_new_protected:Nn \matrix_gabs:NN
  { \@@_map_operate:NNn #1 #2 { abs(##1) }  }
\cs_new_protected:Nn \matrix_gsign:NN
  { \@@_map_operate:NNn #1 #2 { sign(##1) } }
\cs_new_protected:Nn \matrix_ground:NNn
  { \@@_map_operate:NNn #1 #2 { round(##1, #3) } }
%    \end{macrocode}
% \end{macro}
% 
% 
% 
% \begin{macro}{\matrix_gadd:Nn, \matrix_gsub:Nn, 
%               \matrix_gmul:Nn, \matrix_gdiv:Nn, \matrix_gpower:Nn}
% 求 $Z=A + c$、$Z=A - c$、$Z=cA$、$Z=A / c$ 及 $Z=A ^ c$。
%    \begin{macrocode}
\cs_new_protected:Nn \matrix_gadd:NNn
  { \@@_map_operate:NNn #1 #2 { ##1 + #3 } }
\cs_new_protected:Nn \matrix_gsub:NNn
  { \@@_map_operate:NNn #1 #2 { ##1 - #3 } }
\cs_new_protected:Nn \matrix_gmul:NNn
  { \@@_map_operate:NNn #1 #2 { ##1 * #3 } }
\cs_new_protected:Nn \matrix_gdiv:NNn
  { \@@_map_operate:NNn #1 #2 { ##1 / #3 } }
\cs_new_protected:Nn \matrix_gpower:NNn
  { \@@_map_operate:NNn #1 #2 { ##1 ^ #3 } }
%    \end{macrocode}
% \end{macro}
% 
% 
% \subsubsection{双矩阵映射运算}
% 
% 
% \begin{macro}{\@@_map_operate:NNNn}
% 通过映射逐元素计算，操作数有两个矩阵。
%    \begin{macrocode}
\cs_new:Nn \@@_map_operate:NNNn
  { 
    \@@_map_push:    
    \@@_left_operand_prepare:N  #2
    \@@_right_operand_prepare:N #3
    \bool_lazy_and:nnF
      { \int_compare_p:nNn \l_@@_opa_row_int = \l_@@_opb_row_int }
      { \int_compare_p:nNn \l_@@_opa_col_int = \l_@@_opb_col_int }
      { 
        \msg_error:nn { matrix } { dimension-mismatch }
        \matrix_map_break: 
      } 
    \@@_result_prepare:Nnn #1 { \l_@@_opa_row_int } { \l_@@_opa_col_int }
    \int_compare:nNnT { \l_@@_length_int } = { 0 }
      { \matrix_map_break: }
    \cs_gset:Npn \@@_map_item:n ##1 ##2 {#4}
    \int_step_inline:nnn {0} { \l_@@_length_int - 1 }
      {
        \fparray_gset:Nnn \l_@@_fparray { \l_@@_base_int + ##1 }
          {
            \exp_args:Nee \@@_map_item:n
              { \fparray_item:Nn \l_@@_opa_fparray { \l_@@_opa_base_int + ##1 } } 
              { \fparray_item:Nn \l_@@_opb_fparray { \l_@@_opb_base_int + ##1 } } 
          }            
      }
    \prg_break_point:Nn \matrix_map_break: 
      { \@@_map_pop: \@@_operation_cleanup: }     
  }
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\matrix_gadd:NNN, \matrix_gsub:NNN}
% 求 $Z=A + B$、$Z=A - B$
%    \begin{macrocode}
\cs_new_protected:Nn \matrix_gadd:NNN
  { \@@_map_operate:NNNn #1 #2 #3 { ##1 + ##2 } }
\cs_new_protected:Nn \matrix_gsub:NNN
  { \@@_map_operate:NNNn #1 #2 #3 { ##1 - ##2 } }
%    \end{macrocode}
% \end{macro}
% 
% 
% \begin{macro}{\matrix_gadd:NN, \matrix_gsub:NN}
% 求 $A + B$、$A - B$。
%    \begin{macrocode}
\cs_new_protected:Nn \matrix_gadd:NN
  { \@@_map_operate:NNNn #1 #1 #2 { ##1 + ##2 } }
\cs_new_protected:Nn \matrix_gsub:NN
  { \@@_map_operate:NNNn #1 #1 #2 { ##1 - ##2 } }
%    \end{macrocode}
% \end{macro}
% 
% 
% \subsection{非映射运算}
% 
% \begin{macro}{\@@_multiply_aux:nn}
% 计算 $Z_{ij} = \sum_{k=1}^nA_{ik}B_{kj}$。注意，为减少运算，此处代码坐标从 $0$ 计。
%    \begin{macrocode}
\cs_new:Nn \@@_multiply_aux:nn
  {
    \fp_zero:N \l_@@_tmpa_fp
    \int_step_inline:nnn { 0 } { \l_@@_opa_col_int - 1 }
      {
        \fp_add:Nn \l_@@_tmpa_fp
          {
            \fparray_item:Nn \l_@@_opa_fparray 
              { \l_@@_opa_base_int +  #1 * \l_@@_opa_col_int + ##1 } 
            *
            \fparray_item:Nn \l_@@_opb_fparray 
              { \l_@@_opb_base_int + ##1 * \l_@@_opb_col_int +  #2 }
          }         
      }
    \fparray_gset:Nnn \l_@@_fparray 
      { \l_@@_base_int + #1 * \l_@@_col_int + #2 }
      { \l_@@_tmpa_fp }
  }
%    \end{macrocode}
% \end{macro}
% 
% 
% \begin{macro}{\matrix_gmul:NNN}
% 计算 $Z = AB$。
%    \begin{macrocode}
\cs_new_protected:Nn \matrix_gmul:NNN
  { 
    \group_begin:
    \@@_left_operand_prepare:N  #2 
    \@@_right_operand_prepare:N #3
    \int_compare:nNnF
      { \l_@@_opa_col_int } = { \l_@@_opb_row_int }
      { 
        \msg_error:nn { matrix } { dimension-mismatch }
        \matrix_map_break: 
      }
    \@@_result_prepare:Nnn #1 { \l_@@_opa_row_int } { \l_@@_opb_col_int }
    \int_compare:nNnT { \l_@@_length_int } = { 0 }
      { \matrix_map_break: }
    \int_step_inline:nnn { 0 } { \l_@@_opa_row_int - 1 }
      {
        \int_step_inline:nnn { 0 } { \l_@@_opb_col_int - 1 }
          {
            \@@_multiply_aux:nn {##1} {####1}
          }         
      }
    \prg_break_point:Nn \matrix_map_break: 
      { \@@_operation_cleanup: }   
    \group_end:  
  }
%    \end{macrocode}
% \end{macro}
% 
% 
% \begin{macro}{\matrix_gmul:NN}
% 求 $AB$。
%    \begin{macrocode}
\cs_new_protected:Nn \matrix_gmul:NN
  { \matrix_gmul:NNN #1 #1 #2 }
%    \end{macrocode}
% \end{macro}
% 
%
% 
% \begin{variable}{}
% 
%    \begin{macrocode}
%    \end{macrocode}
% \end{variable}
%
% 
%    \begin{macrocode}
\ExplSyntaxOff
%</package>
%    \end{macrocode}
%
%
% \end{implementation}
%
% \PrintChanges
% \PrintIndex
%
% 
\endinput