% \iffalse meta-comment
%
% Copyright (C) 2018-2019 by F. Pantigny
% -----------------------------------
%
% This file may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
% of this license or (at your option) any later version.
% The latest version of this license is in:
%
% http://www.latex-project.org/lppl.txt
%
% and version 1.3 or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%
% \fi
% \iffalse
\def\myfileversion{3.6}
\def\myfiledate{2019/10/29}
%
%
%<*batchfile>
\begingroup
\input l3docstrip.tex
\keepsilent
\usedir{tex/latex/nicematrix}
\preamble

Copyright (C) 2018-2019 by F. Pantigny
-----------------------------------

This file may be distributed and/or modified under the
conditions of the LaTeX Project Public License, either version 1.3
of this license or (at your option) any later version.
The latest version of this license is in:

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

and version 1.3 or later is part of all distributions of LaTeX
version 2005/12/01 or later.

\endpreamble
\askforoverwritefalse
\endgroup
%</batchfile>
%
%<*driver>
\documentclass[dvipsnames]{l3doc}% dvipsnames is for xcolor (loaded by Tikz)
\VerbatimFootnotes
\usepackage{xltxtra}
\usepackage[xetex]{geometry}
\geometry{left=2.8cm,right=2.8cm,top=2.5cm,bottom=2.5cm,papersize={21cm,29.7cm}}

\usepackage{colortbl}
\usepackage{nicematrix}
\usepackage{siunitx}

\newbox\ExampleOne

\setbox\ExampleOne\hbox{$\begin{NiceArray}{|*{4}{C|}}[hlines,first-row,first-col]
  & e & a & b & c \\
e & e & a & b & c \\
a & a & e & c & b \\
b & b & c & e & a \\
c & c & b & a & e 
\end{NiceArray}$}


\NewDocumentEnvironment {scope} {} {} {}
\def\interitem{\vspace{7mm plus 2 mm minus 3mm}}          
\def\emphase{\bgroup\color{RoyalPurple}\let\next=}
\fvset{commandchars=\~\#\@,formatcom=\color{gray}}
\usepackage{titlesec}
\titlespacing*{\section}{0pt}{6.5ex plus 1ex minus .2ex}{4.3ex plus .2ex}
\titlespacing*{\subsection}{0pt}{4.5ex plus 1ex minus .2ex}{2ex plus .2ex}
\usepackage{multicol}
\usepackage{arydshln}
\setlength{\columnseprule}{0.4pt}
\usepackage{footnotehyper}
\parindent 0pt

\EnableCrossrefs
\begin{document}
\DocInput{nicematrix.dtx}
\end{document}
%</driver>
% \fi 
% \title{The package \pkg{nicematrix}\thanks{This document corresponds to the version~\myfileversion\space of \pkg{nicematrix},
% at the date of~\myfiledate.}} \author{F. Pantigny \\ \texttt{fpantigny@wanadoo.fr}}
%
% \hypersetup
%   {
%     pdfinfo = 
%      {
%        Title = The extension 'nicematrix' ,
%        Subject = A LaTeX extension ,
%        Author = F. Pantigny 
%      }
%   }
%
%
% \maketitle
%
% \begin{abstract}
% The LaTeX package \pkg{nicematrix} provides new environments similar to the
% classical environments |{array}| and |{matrix}| but with some additional
% features. Among these features are the possibilities to fix the width of the
% columns and to draw continuous ellipsis dots between the cells of the array.
% \end{abstract}
%
% \vspace{1cm}
% \section{Presentation}
%
%
% This package can be used with |xelatex|, |lualatex|, |pdflatex| but also by
% the classical workflow |latex|-|dvips|-|ps2pdf| (or Adobe Distiller). Two or
% three compilations may be necessary. This package requires and \textbf{loads}
% the packages \pkg{expl3}, \pkg{l3keys2e}, \pkg{xparse}, \pkg{array},
% \pkg{amsmath} and \pkg{tikz}. It also loads the Tikz library \pkg{fit}. The
% final user only has to load the extension with |\usepackage{nicematrix}|.
%
%
% \medskip
% \begin{savenotes}
% \begin{minipage}{0.6\linewidth}
% This package provides some new tools to draw mathematical matrices. The main
% features are the following:
% \begin{itemize}\setlength{\itemsep}{0pt}
% \item continuous dotted lines\footnote{If the class option |draft| is
% used, these dotted lines will not be drawn for a faster compilation.};
% \item exterior rows and columns for labels;
% \item a control of the width of the columns.
% \end{itemize}
% \end{minipage}
% \end{savenotes}
% \hspace{1.4cm}
% $\begin{bNiceArray}{CCCC}[first-row,first-col,
%                           code-for-first-col=\color{blue}\scriptstyle,
%                           code-for-first-row=\color{blue}\scriptstyle,
%                           columns-width = auto]
%        & C_1     & C_2     & \Cdots  & C_n  \\
% L_1    & a_{11}  & a_{12}  & \Cdots & a_{1n} \\
% L_2    & a_{21}  & a_{22}  & \Cdots & a_{2n} \\
% \Vdots & \Vdots & \Vdots & \Ddots & \Vdots\\
% L_n    & a_{n1}  & a_{n2}  & \Cdots & a_{nn} 
% \end{bNiceArray}$
% 
% \medskip 
% A command |\NiceMatrixOptions| is provided to fix the options (the
% scope of the options fixed by this command is the current TeX group).
%
% 
% \bigskip
% \textbf{An example for the continuous dotted lines}
%
% \medskip
% \begin{minipage}{10cm}
% For example, consider the following code which uses an environment |{pmatrix}|
% of \pkg{amsmath}.
%
% \smallskip
% \begin{BVerbatim}
% $A = \begin{pmatrix}
% 1      & \cdots & \cdots & 1      \\
% 0      & \ddots &        & \vdots \\
% \vdots & \ddots & \ddots & \vdots \\
% 0      & \cdots & 0      & 1
% \end{pmatrix}$
% \end{BVerbatim}
%
% \smallskip
% This code composes the matrix $A$ on the right.
% \end{minipage}\hspace{1cm}
% $A = \begin{pmatrix}
% 1      &\cdots &\cdots &1      \\
% 0      &\ddots &       &\vdots \\
% \vdots &\ddots &\ddots &\vdots \\
% 0      &\cdots &0      &1
% \end{pmatrix}$
%
% 
% \bigskip
% \begin{scope}
% \NiceMatrixOptions{transparent}
% \begin{minipage}{10cm}
% Now, if we use the package \pkg{nicematrix} with the option \\ 
% |transparent|, the same code will give the result on the right.
% \end{minipage}\hspace{1cm}
% $A = \begin{pmatrix}
% 1      & \cdots & \cdots & 1      \\
% 0      & \ddots &        & \vdots \\
% \vdots & \ddots & \ddots & \vdots \\
% 0      & \cdots & 0      & 1
% \end{pmatrix}$
% \end{scope}
%
%
% \section{The environments of this extension} 
%
% The extension \pkg{nicematrix} defines the following new environments.
% 
% \medskip
% \begin{ttfamily}
% \setlength{\tabcolsep}{3mm}
% \begin{tabular}{llll}
% \{NiceMatrix\}  & \{NiceArray\} & \{pNiceArray\}          \\
% \{pNiceMatrix\} &               & \{bNiceArray\}          \\
% \{bNiceMatrix\} &               & \{BNiceArray\}          \\
% \{BNiceMatrix\} &               & \{vNiceArray\}          \\
% \{vNiceMatrix\} &               & \{VNiceArray\}          \\
% \{VNiceMatrix\} &               & \{NiceArrayWithDelims\} \\
% \end{tabular}
% \end{ttfamily}
%
%
% \medskip
% By default, the environments |{NiceMatrix}|, |{pNiceMatrix}|, |{bNiceMatrix}|,
% |{BNiceMatrix}|, |{vNiceMatrix}| and |{VNiceMatrix}| behave almost exactly as
% the corresponding environments of \pkg{amsmath}: |{matrix}|, |{pmatrix}|,
% |{bmatrix}|, |{Bmatrix}|, |{vmatrix}| and |{Vmatrix}|.
% 
%
% \medskip
% The environment |{NiceArray}| is similar to the environment |{array}| of the
% package |{array}|. However, for technical reasons, in the preamble of the
% environment |{NiceArray}|, the user must use the letters |L|, |C| and~|R|
% instead of |l|, |c| and |r|. It's possible to use the constructions
% |w{...}{...}|, |W{...}{...}|\footnote{However, for the columns of type |w| and
% |W|, the cells are composed in math mode (in the environments of
% \pkg{nicematrix}) whereas in |{array}| of \pkg{array}, they are composed in
% text mode.}, "|", |>{...}|, |<{...}|, |@{...}|, |!{...}| and |*{n}{...}| but
% the letters |p|, |m| and |b| should not be used. See p.~\pageref{NiceArray}
% the section relating to |{NiceArray}|.
% 
% 
% \section{The continuous dotted lines}
%
% Inside the environments of the extension \pkg{nicematrix}, new commands are
% defined: |\Ldots|, |\Cdots|, |\Vdots|, |\Ddots|, and |\Iddots|. These commands
% are intended to be used in place of |\dots|, |\cdots|, |\vdots|, |\ddots| and
% |\iddots|.\footnote{The command |\iddots|, defined in \pkg{nicematrix}, is a
% variant of |\ddots| with dots going forward: \smash{$\iddots$}. If |mathdots|
% is loaded, the version of |mathdots| is used. It corresponds to the command
% |\adots| of \pkg{unicode-math}.}
% \newcounter{fniddots}
% \setcounter{fniddots}{\thefootnote}
%
% \smallskip
% Each of them must be used alone in the cell of the array and it draws a dotted
% line between the first non-empty cells\footnote{The precise definition of a
% ``non-empty cell'' is given below (cf. p.~\pageref{empty-cells}).} on both
% sides of the current cell. Of course, for |\Ldots| and |\Cdots|, it's an
% horizontal line; for |\Vdots|, it's a vertical line and for |\Ddots| and
% |\Iddots| diagonal ones.\par\nobreak 
%
% \bigskip
% \begin{BVerbatim}[baseline=c,boxwidth=10cm]
% \begin{bNiceMatrix}
% a_1      & \Cdots &        & & a_1 \\
% \Vdots   & a_2    & \Cdots & & a_2 \\
%          & \Vdots & \Ddots \\
% \\
% a_1      & a_2    &        & & a_n 
% \end{bNiceMatrix}
% \end{BVerbatim}
% $\begin{bNiceMatrix}
% a_1      & \Cdots &        & & a_1 \\
% \Vdots   & a_2    & \Cdots & & a_2 \\
%          & \Vdots & \Ddots \\
% \\
% a_1      & a_2    &        & & a_n 
% \end{bNiceMatrix}$
% 
% \interitem 
% In order to represent the null matrix, one can use the following
% codage:\par\nobreak
%
% \bigskip
% \begin{BVerbatim}[baseline=c,boxwidth=10cm]
% \begin{bNiceMatrix}
% 0      & \Cdots & 0      \\
% \Vdots &        & \Vdots \\
% 0      & \Cdots & 0 
% \end{bNiceMatrix}
% \end{BVerbatim}
% $\begin{bNiceMatrix}
% 0      & \Cdots & 0      \\
% \Vdots &        & \Vdots \\
% 0      & \Cdots & 0 
% \end{bNiceMatrix}$
%
% \bigskip
% However, one may want a larger matrix. Usually, in such a case, the users of
% LaTeX add a new row and a new column. It's possible to use the same method
% with \pkg{nicematrix}:\par\nobreak 
%
% \bigskip
% \begin{BVerbatim}[baseline=c,boxwidth=10cm]
% \begin{bNiceMatrix}
% 0      & \Cdots & \Cdots & 0      \\
% \Vdots &        &        & \Vdots \\
% \Vdots &        &        & \Vdots \\
% 0      & \Cdots & \Cdots & 0 
% \end{bNiceMatrix}
% \end{BVerbatim}
% $\begin{bNiceMatrix}
% 0      & \Cdots & \Cdots & 0      \\
% \Vdots &        &        & \Vdots \\
% \Vdots &        &        & \Vdots \\
% 0      & \Cdots & \Cdots & 0 
% \end{bNiceMatrix}$
% 
% \bigskip
% In the first column of this exemple, there are two instructions |\Vdots| but
% only one dotted line is drawn (there is no overlapping graphic objects in the
% resulting \textsc{pdf}\footnote{And it's not possible to draw a |\Ldots| and a
% |\Cdots| line between the same cells.}).
%
% \bigskip
% In fact, in this example, it would be possible to draw the same matrix more
% easily with the following code:\par\nobreak
%
% \bigskip
% \begin{BVerbatim}[baseline=c,boxwidth=10cm]
% \begin{bNiceMatrix}
% 0       & \Cdots &        & 0      \\
% \Vdots  &        &        &        \\
%         &        &        & \Vdots \\
% 0       &        & \Cdots & 0 
% \end{bNiceMatrix}
% \end{BVerbatim}
% $\begin{bNiceMatrix}
% 0       & \Cdots &        & 0      \\
% \Vdots  &        &        &        \\
%         &        &        & \Vdots \\
% 0       &        & \Cdots & 0 
% \end{bNiceMatrix}$
%
% \bigskip 
% There are also other means to change the size of the matrix. Someone might
% want to use the optional argument of the command~|\\| for the vertical
% dimension and a command~|\hspace*| in a cell for the horizontal
% dimension.\footnote{In \pkg{nicematrix}, one should use |\hspace*| and not
% |\hspace| for such an usage because \pkg{nicematrix} loads \pkg{array}. One
% may also remark that it's possible to fix the width of a column by using the
% environment |{NiceArray}| (or one of its variants) with a column of type~|w|
% or~|W|: see p.~\pageref{width}} 
% 
% However, a command~|\hspace*| might interfer with the construction of the
% dotted lines. That's why the package \pkg{nicematrix} provides a
% command~|\Hspace| which is a variant of |\hspace| transparent for the dotted
% lines of \pkg{nicematrix}.\par\nobreak
%
% \bigskip
% \begin{BVerbatim}[baseline=c,boxwidth=10cm]
% \begin{bNiceMatrix}
% 0      & \Cdots & ~emphase#\Hspace*{1cm}@ & 0      \\
% \Vdots &        &               & \Vdots \\~emphase#[1cm]@
% 0      & \Cdots &               & 0    
% \end{bNiceMatrix}
% \end{BVerbatim}
% $\begin{bNiceMatrix}
% 0      & \Cdots & \Hspace*{1cm} & 0      \\
% \Vdots &        &               & \Vdots \\[1cm]
% 0      & \Cdots &               & 0    
% \end{bNiceMatrix}$
% 
% \subsection{The option nullify-dots}
%
% Consider the following matrix composed classicaly with the environment
% |{pmatrix}| of \pkg{amsmath}.\par\nobreak 
% 
% \medskip
% \begin{BVerbatim}[baseline=c,boxwidth=8cm]
% $A = \begin{pmatrix}
% a_0 & b \\
% a_1 &   \\
% a_2 &   \\
% a_3 &   \\
% a_4 &   \\
% a_5 & b
% \end{pmatrix}$
% \end{BVerbatim}
% $A = \begin{pmatrix}
% a_0 & b \\
% a_1 &   \\
% a_2 &   \\
% a_3 &   \\
% a_4 &   \\
% a_5 & b
% \end{pmatrix}$
%
%
% \bigskip
% If we add |\vdots| instructions in the second column, the geometry of the
% matrix is modified.\par\nobreak
%
% \medskip
% \begin{BVerbatim}[baseline=c,boxwidth=8cm]
% $B = \begin{pmatrix}
% a_0 & b      \\
% a_1 & \vdots \\
% a_2 & \vdots \\
% a_3 & \vdots \\
% a_4 & \vdots \\
% a_5 & b
% \end{pmatrix}$
% \end{BVerbatim}
% $B = \begin{pmatrix}
% a_0 & b      \\
% a_1 & \vdots \\
% a_2 & \vdots \\
% a_3 & \vdots \\
% a_4 & \vdots \\
% a_5 & b
% \end{pmatrix}$
%
% \bigskip
% By default, with \pkg{nicematrix}, if we replace |{pmatrix}| by
% |{pNiceMatrix}| and |\vdots| by |\Vdots|, the geometry of the matrix is not
% changed.\par\nobreak 
%
% \medskip
% \begin{BVerbatim}[baseline=c,boxwidth=8cm]
% $C = \begin{pNiceMatrix}
% a_0 & b       \\
% a_1 & \Vdots  \\
% a_2 & \Vdots  \\
% a_3 & \Vdots  \\
% a_4 & \Vdots  \\
% a_5 & b
% \end{pNiceMatrix}$
% \end{BVerbatim}
% $C = \begin{pNiceMatrix}
% a_0 & b       \\
% a_1 & \Vdots  \\
% a_2 & \Vdots  \\
% a_3 & \Vdots  \\
% a_4 & \Vdots  \\
% a_5 & b
% \end{pNiceMatrix}$
%
% \bigskip
% However, one may prefer the geometry of the first matrix $A$ and would like to
% have such a geometry with a dotted line in the second column. It's possible by
% using the option |nullify-dots| (and only one instruction |\Vdots| is
% necessary).\par\nobreak 
%
% \medskip
% \begin{BVerbatim}[baseline=c,boxwidth=8cm]
% $D = \begin{pNiceMatrix}[~emphase#nullify-dots@]
% a_0 & b      \\
% a_1 & \Vdots \\
% a_2 &        \\
% a_3 &        \\
% a_4 &        \\
% a_5 & b
% \end{pNiceMatrix}$
% \end{BVerbatim}
% $D = \begin{pNiceMatrix}[nullify-dots]
% a_0 & b      \\
% a_1 & \Vdots \\
% a_2 &        \\
% a_3 &        \\
% a_4 &        \\
% a_5 & b
% \end{pNiceMatrix}$
%
% \medskip
% The option |nullify-dots| smashes the instructions |\Ldots| (and the variants)
% vertically but also horizontally.
%
% \medskip
% \textbf{There must be no space before the opening bracket (|[|) of the options
% of the environment.}
%
%
% \subsection{The command \textbackslash Hdotsfor}
%
% Some people commonly use the command |\hdotsfor| of \pkg{amsmath} in order to
% draw horizontal dotted lines in a matrix. In the environments of
% \pkg{nicematrix}, one should use instead |\Hdotsfor| in order to draw dotted
% lines similar to the other dotted lines drawn by the package \pkg{nicematrix}.
%
% As with the other commands of \pkg{nicematrix} (like |\Cdots|, |\Ldots|,
% |\Vdots|, etc.), the dotted line drawn with |\Hdotsfor| extends until the
% contents of the cells on both sides.
%
% \medskip
% \begin{BVerbatim}[baseline=c,boxwidth=7cm]
% $\begin{pNiceMatrix}
% 1 & 2 & 3 & 4 & 5 \\
% 1 & ~emphase#\Hdotsfor{3}@ & 5 \\
% 1 & 2 & 3 & 4 & 5 \\
% 1 & 2 & 3 & 4 & 5 
% \end{pNiceMatrix}$
% \end{BVerbatim}
% $\begin{pNiceMatrix}
% 1 & 2 & 3 & 4 & 5 \\
% 1 & \Hdotsfor{3} & 5 \\
% 1 & 2 & 3 & 4 & 5 \\
% 1 & 2 & 3 & 4 & 5 
% \end{pNiceMatrix}$
%
% \bigskip
% However, if these cells are empty, the dotted line extends only in the cells
% specified by the argument of |\Hdotsfor| (by design).
%
% \medskip
% \begin{BVerbatim}[baseline=c,boxwidth=7cm]
% $\begin{pNiceMatrix}
% 1 & 2 & 3 & 4 & 5 \\
%   & ~emphase#\Hdotsfor{3}@ \\
% 1 & 2 & 3 & 4 & 5 \\
% 1 & 2 & 3 & 4 & 5 
% \end{pNiceMatrix}$
% \end{BVerbatim}
% $\begin{pNiceMatrix}
% 1 & 2 & 3 & 4 & 5 \\
%   & \Hdotsfor{3} \\
% 1 & 2 & 3 & 4 & 5 \\
% 1 & 2 & 3 & 4 & 5 
% \end{pNiceMatrix}$
%
% \bigskip
% The command |\hdotsfor| of \pkg{amsmath} takes an optional argument (between
% square brackets) which is used for fine tuning of the space between two
% consecutive dots. For homogeneity, |\Hdotsfor| has also an optional argument
% but this argument is discarded silently.
%
% Remark: Unlike the command |\hdotsfor| of \pkg{amsmath}, the command
% |\Hdotsfor| may be used when the extension \pkg{colortbl} is loaded (but you
% might have problem if you use |\rowcolor| on the same row as |\Hdotsfor|).
% 
% \subsection{How to generate the continuous dotted lines transparently}
%
% The package \pkg{nicematrix} provides an option called |transparent| for using
% existing code transparently in the environments of the \pkg{amsmath} :
% |{matrix}|, |{pmatrix}|, |{bmatrix}|, etc. In fact, this
% option is an alias for the conjonction of two options: 
% |renew-dots| and |renew-matrix|.\footnote{The options |renew-dots|,
% |renew-matrix| and |transparent| can be fixed with the command
% |\NiceMatrixOptiosn| like the other options. However, they can also be fixed
% as options of the command |\usepackage| (it's an exception for these three
% specific options.)}
%
% \smallskip
%
% \begin{itemize}
% \item The option |renew-dots|\par\nobreak
%
% With this option, the commands |\ldots|, |\cdots|, |\vdots|, |\ddots|,
% |\iddots|\footnotemark[\thefniddots] and |\hdotsfor| are redefined within the
% environments provided by \pkg{nicematrix} and behave like |\Ldots|, |\Cdots|,
% |\Vdots|, |\Ddots|, |\Iddots| and |\Hdotsfor|; the command |\dots|
% (``automatic dots'' of |amsmath|) is also redefined to behave like |\Ldots|. 
%
% \item The option |renew-matrix|\par\nobreak 
%
% With this option, the environment |{matrix}| is redefined and behave like
% |{NiceMatrix}|, and so on for the five variants.
% \end{itemize}
%
% \bigskip 
% Therefore, with the option |transparent|, a classical code gives directly the
% ouput of \pkg{nicematrix}.\par\nobreak
%
% \bigskip
% \begin{scope}
% \NiceMatrixOptions{transparent}
% \begin{BVerbatim}[baseline=c,boxwidth=10cm]
% ~emphase#\NiceMatrixOptions{transparent}@
% \begin{pmatrix}
% 1      & \cdots & \cdots & 1      \\
% 0      & \ddots &        & \vdots \\
% \vdots & \ddots & \ddots & \vdots \\
% 0      & \cdots & 0      & 1
% \end{pmatrix}
% \end{BVerbatim}
% $\begin{pmatrix}
% 1      & \cdots & \cdots & 1      \\
% 0      & \ddots &        & \vdots \\
% \vdots & \ddots & \ddots & \vdots \\
% 0      & \cdots & 0      & 1
% \end{pmatrix}$
% \end{scope}
% 
%
% 
% 
% \section{The Tikz nodes created by nicematrix}
% 
% The package \pkg{nicematrix} creates a Tikz node for each cell of the
% considered array. These nodes are used to draw the dotted lines between the
% cells of the matrix. However, the user may wish to use directly these nodes.
% It's possible. First, the user have to give a name to the array (with the key
% called |name|). Then, the nodes are accessible through the names
% ``\textsl{name}-$i$-$j$'' where \textsl{name} is the name given to the array
% and $i$ and $j$ the numbers of the row and the column of the considered cell.
% 
% \medskip
% \begin{BVerbatim}[baseline=c,boxwidth=11cm]
% $\begin{pNiceMatrix}[name=~emphase#mymatrix@]
% 1 & 2 & 3 \\
% 4 & 5 & 6 \\
% 7 & 8 & 9 
% \end{pNiceMatrix}$
% \tikz[remember picture,overlay] 
%      \draw ~emphase#(mymatrix-2-2)@ circle (2mm) ; 
% \end{BVerbatim}
% $\begin{pNiceMatrix}[name=mymatrix]
% 1 & 2 & 3 \\
% 4 & 5 & 6 \\
% 7 & 8 & 9 
% \end{pNiceMatrix}$
% \tikz[remember picture,overlay] 
%      \draw (mymatrix-2-2) circle (2mm) ; 
%
% \medskip
% Don't forget the options |remember picture| and |overlay|.
%
% \bigskip
% In the following example, we have underlined all the nodes of the matrix.
% \begin{scope}
% \tikzset{every node/.style = {fill = red!15, inner sep = 0pt}}
% \[\begin{pNiceMatrix}
% a & a + b & a + b + c \\
% a & a     & a + b  \\
% a & a     & a 
% \end{pNiceMatrix}\]
% \end{scope}
% 
%
% \bigskip
% In fact, the package \pkg{nicematrix} can create ``extra nodes''. These new
% nodes are created if the option |create-extra-nodes| is used. There are two
% series of extra nodes: the ``medium nodes'' and the ``large nodes''.
%
% \medskip
% The names of the ``medium nodes'' are constructed by adding the suffix
% ``|-medium|'' to the names of the ``normal nodes''. In the following example,
% we have underlined the ``medium nodes''. We consider that this example is
% self-explanatory.
% \[\begin{pNiceMatrix}[
%  create-extra-nodes,
%  code-after = {\begin{tikzpicture}
%                   [every node/.style = {fill = red!15,
%                                         blend mode = multiply,
%                                         inner sep = -\pgflinewidth/2},
%                    name suffix = -medium]
%                \node [fit = (1-1)] {} ;
%                \node [fit = (1-2)] {} ;
%                \node [fit = (1-3)] {} ;
%                \node [fit = (2-1)] {} ;
%                \node [fit = (2-2)] {} ;
%                \node [fit = (2-3)] {} ;
%                \node [fit = (3-1)] {} ;
%                \node [fit = (3-2)] {} ;
%                \node [fit = (3-3)] {} ;
%                \end{tikzpicture}}]
% a & a + b & a + b + c \\
% a & a     & a + b  \\
% a & a     & a 
% \end{pNiceMatrix}\]
%
%
% \medskip
% The names of the ``large nodes'' are constructed by adding the suffix
% ``|-large|'' to the names of the ``normal nodes''. In the following example,
% we have underlined the ``large nodes''. We consider that this example is
% self-explanatory.\footnote{There is no ``large nodes'' created in the exterior
% rows and columns (for these rows and columns, cf. p.~\pageref{exterior}).}
%
% \[\begin{pNiceMatrix}[
%  create-extra-nodes,
%  code-after = {\begin{tikzpicture}
%                   [every node/.style = {blend mode = multiply,
%                                         inner sep = -\pgflinewidth/2},
%                    name suffix = -large]
%                \node [fit = (1-1),fill = red!15] {} ;
%                \node [fit = (1-3),fill = red!15] {} ;
%                \node [fit = (2-2),fill = red!15] {} ;
%                \node [fit = (3-1),fill = red!15] {} ;
%                \node [fit = (3-3),fill = red!15] {} ;
%                \node [fit = (1-2),fill = blue!15] {} ;
%                \node [fit = (2-1),fill = blue!15] {} ;
%                \node [fit = (2-3),fill = blue!15] {} ;
%                \node [fit = (3-2),fill = blue!15] {} ;
%                \end{tikzpicture}}]
% a & a + b & a + b + c \\
% a & a     & a + b  \\
% a & a     & a 
% \end{pNiceMatrix}\]
% 
%
% \medskip
% The ``large nodes'' of the first column and last column may appear too small
% for some usage. That's why it's possible to use the options |left-margin| and
% |right-margin| to add space on both sides of the array and also space in the
% ``large nodes'' of the first column and last column. In the following example,
% we have used the options |left-margin| and |right-margin|.\footnote{The
% options |left-margin| and |right-margin| take dimensions as values but, if no
% value is given, the default value is used, which is |\arraycolsep| (by
% default: 5~pt). There is also an option |margin| to fix both |left-margin| and
% |right-margin| to the same value.}
% \[\begin{pNiceMatrix}[
%  create-extra-nodes,left-margin,right-margin,
%  code-after = {\begin{tikzpicture}
%                   [every node/.style = {blend mode = multiply,
%                                         inner sep = -\pgflinewidth/2},
%                    name suffix = -large]
%                \node [fit = (1-1),fill = red!15] {} ;
%                \node [fit = (1-3),fill = red!15] {} ;
%                \node [fit = (2-2),fill = red!15] {} ;
%                \node [fit = (3-1),fill = red!15] {} ;
%                \node [fit = (3-3),fill = red!15] {} ;
%                \node [fit = (1-2),fill = blue!15] {} ;
%                \node [fit = (2-1),fill = blue!15] {} ;
%                \node [fit = (2-3),fill = blue!15] {} ;
%                \node [fit = (3-2),fill = blue!15] {} ;
%                \end{tikzpicture}}]
% a & a + b & a + b + c \\
% a & a     & a + b  \\
% a & a     & a 
% \end{pNiceMatrix}\]
% 
% \medskip
% It's also possible to add more space on both side of the array with the
% options |extra-left-margin| and |extra-right-margin|. These margins are not
% incorporated in the ``large nodes''. It's possible to fix both values with the
% option |extra-margin| and, in the following example, we use |extra-margin|
% with the value $3$~pt.
% \[\begin{pNiceMatrix}[
%  create-extra-nodes,margin,extra-margin=3pt,
%  code-after = {\begin{tikzpicture}
%                   [every node/.style = {blend mode = multiply,
%                                         inner sep = -\pgflinewidth/2},
%                    name suffix = -large]
%                \node [fit = (1-1),fill = red!15] {} ;
%                \node [fit = (1-3),fill = red!15] {} ;
%                \node [fit = (2-2),fill = red!15] {} ;
%                \node [fit = (3-1),fill = red!15] {} ;
%                \node [fit = (3-3),fill = red!15] {} ;
%                \node [fit = (1-2),fill = blue!15] {} ;
%                \node [fit = (2-1),fill = blue!15] {} ;
%                \node [fit = (2-3),fill = blue!15] {} ;
%                \node [fit = (3-2),fill = blue!15] {} ;
%                \end{tikzpicture}}]
% a & a + b & a + b + c \\
% a & a     & a + b  \\
% a & a     & a 
% \end{pNiceMatrix}\]
%
% \medskip
% In this case, if we want a control over the height of the rows, we can add a
% |\strut| in each row of the array.
% \[\begin{pNiceMatrix}[
%  create-extra-nodes,left-margin,right-margin,extra-right-margin=3pt,
%  extra-left-margin=3pt,
%  code-after = {\begin{tikzpicture}
%                   [every node/.style = {blend mode = multiply,
%                                         inner sep = -\pgflinewidth/2},
%                    name suffix = -large]
%                \node [fit = (1-1),fill = red!15] {} ;
%                \node [fit = (1-3),fill = red!15] {} ;
%                \node [fit = (2-2),fill = red!15] {} ;
%                \node [fit = (3-1),fill = red!15] {} ;
%                \node [fit = (3-3),fill = red!15] {} ;
%                \node [fit = (1-2),fill = blue!15] {} ;
%                \node [fit = (2-1),fill = blue!15] {} ;
%                \node [fit = (2-3),fill = blue!15] {} ;
%                \node [fit = (3-2),fill = blue!15] {} ;
%                \end{tikzpicture}}]
% \strut a & a + b & a + b + c \\
% \strut a & a     & a + b  \\
% \strut a & a     & a 
% \end{pNiceMatrix}\]
%
% \bigskip
% We explain below how to fill the nodes created by \pkg{nicematrix} (cf. p.
% \pageref{highlight}). 
%
% \section{The code-after}
%
% The option |code-after| may be used to give some code that will be excuted
% after the construction of the matrix (and, hence, after the construction of
% all the Tikz nodes).
%
% In the |code-after|, the Tikz nodes should be accessed by a name of the form
% $i$-$j$ (without the prefix of the name of the environment).
%
% Moreover, a special command, called |\line| is available to draw directly
% dotted lines between nodes.
%
% \medskip
% \begin{BVerbatim}[baseline=c,boxwidth=12cm]
% $\begin{pNiceMatrix}[~emphase#code-after = \line{1-1}{3-3}@]
% 0 & 0 & 0 \\
% 0 &   & 0 \\
% 0 & 0 & 0 
% \end{pNiceMatrix}$
% \end{BVerbatim}
% $\begin{pNiceMatrix}[code-after = \line{1-1}{3-3}]
% 0 & 0 & 0 \\
% 0 &   & 0 \\
% 0 & 0 & 0 
% \end{pNiceMatrix}$
%
% 
% \section{The environment \{NiceArray\}}
% \label{NiceArray}
%
% The environment |{NiceArray}| is similar to the environment |{array}|. As for
% |{array}|, the mandatory argument is the preamble of the array. However, for
% technical reasons, in this preamble, the user must use the letters |L|, |C|
% and~|R|\footnote{The column types |L|, |C| and |R| are defined locally inside
% |{NiceArray}| with |\newcolumntype| of \pkg{array}. This definition overrides
% an eventual previous definition. In fact, the column types |w| and |W| are
% also redefined.} instead of |l|, |c| and |r|. It's possible
% to use the constructions |w{...}{...}|, |W{...}{...}|, "|", |>{...}|,
% |<{...}|, |@{...}|, |!{...}| and |*{n}{...}| but the letters |p|, |m| and |b|
% should not be used.\footnote{In a command |\multicolumn|, one should also use
% the letters |L|, |C|, |R|.} 
%
% \medskip
% The environment |{NiceArray}| accepts the classical options |t|, |c| and |b|
% of |{array}| but also other options defined by \pkg{nicematrix} (|renew-dots|,
% |columns-width|, etc.).
%
% 
% \vspace{1cm}
% An example with a linear system (we need |{NiceArray}| for the vertical rule):
%
% \bigskip
% \begin{BVerbatim}[baseline=c,boxwidth=10cm]
% $\left[\begin{NiceArray}{CCCC|C}
% a_1    & ?      & \Cdots & ?       & ?     \\
% 0      &        & \Ddots & \Vdots  & \Vdots\\
% \Vdots & \Ddots & \Ddots & ? \\ 
% 0      & \Cdots & 0      & a_n     & ?     
% \end{NiceArray}\right]$
% \end{BVerbatim}
% $\left[\begin{NiceArray}{CCCC|C}
% a_1    & ?      & \Cdots & ?       & ?     \\
% 0      &        & \Ddots & \Vdots  & \Vdots\\
% \Vdots & \Ddots & \Ddots & ? \\ 
% 0      & \Cdots & 0      & a_n     & ?     
% \end{NiceArray}\right]$
%
% \bigskip
% In fact, there is also variants for the environment |{NiceArray}|:
% |{pNiceArray}|, |{bNiceArray}|, |{BNiceArray}|, |{vNiceArray}| and
% |{VNiceArray}|. 
% 
% In the following example, we use an environment |{pNiceArray}| (we don't use
% |{pNiceMatrix}| because we want to use the types |L| and |R| 
% --- in |{pNiceMatrix}|, all the columns are of type |C|).
%
% \bigskip
% \begin{BVerbatim}[baseline=c,boxwidth=10cm]
% $\begin{pNiceArray}{LCR}
% a_{11}    & \Cdots & a_{1n} \\
% a_{21}    &        & a_{2n} \\
% \Vdots    &        & \Vdots \\
% a_{n-1,1} & \Cdots & a_{n-1,n} 
% \end{pNiceArray}$
% \end{BVerbatim}
% $\begin{pNiceArray}{LCR}
% a_{11}    & \Cdots & a_{1n} \\
% a_{21}    &        & a_{2n} \\
% \Vdots    &        & \Vdots \\
% a_{n-1,1} & \Cdots & a_{n-1,n} 
% \end{pNiceArray}$
%
%
% \bigskip
% In fact, the environment |{pNiceArray}| and its variants are based upon a
% more general environment, called |{NiceArrayWithDelims}|. The first two
% mandatory arguments of this environment are the left and right delimiters used
% in the construction of the matrix. It's possible to use
% |{NiceArrayWithDelims}| if we want to use atypical delimiters.
%
% \medskip
% \begin{BVerbatim}[baseline=c,boxwidth=11cm]
% $\begin{~emphase#NiceArrayWithDelims@}
%    {\downarrow}{\downarrow}{CCC}
% 1 & 2 & 3 \\
% 4 & 5 & 6 \\
% 7 & 8 & 9 \\
% \end{~emphase#NiceArrayWithDelims@}$
% \end{BVerbatim}
% $\begin{NiceArrayWithDelims}
%    {\downarrow}{\downarrow}{CCC}
% 1 & 2 & 3 \\
% 4 & 5 & 6 \\
% 7 & 8 & 9 \\
% \end{NiceArrayWithDelims}$
%
%
% \bigskip
% \section{The exterior rows and columns}
% The options |first-row|, |last-row|, |first-col| and |last-col| allow the
% composition of exterior rows and columns in the environments of
% \pkg{nicematrix}. 
% \label{exterior}
%
% A potential first row has the number $0$ (and not $1$). Idem for the potential
% first column. In general cases, one must specify the number of the last row
% and the number of the last column as values of |last-row| and |last-col|.
% 
% \begin{Verbatim}
% $\begin{pNiceMatrix}[~emphase#first-row,last-row=5,first-col,last-col=5@]
%     & C_1    & C_2    & C_3    & C_4    &     \\
% L_1 & a_{11} & a_{12} & a_{13} & a_{14} & L_1 \\
% L_2 & a_{21} & a_{22} & a_{23} & a_{24} & L_2 \\
% L_3 & a_{31} & a_{32} & a_{33} & a_{34} & L_3 \\
% L_4 & a_{41} & a_{42} & a_{43} & a_{44} & L_4 \\
%     & C_1    & C_2    & C_3    & C_4    &     
% \end{pNiceMatrix}$
% \end{Verbatim}
%
% \[\begin{pNiceMatrix}[first-row,last-row=5,first-col,last-col=5]
%     & C_1    & C_2    & C_3    & C_4    &     \\
% L_1 & a_{11} & a_{12} & a_{13} & a_{14} & L_1 \\
% L_2 & a_{21} & a_{22} & a_{23} & a_{24} & L_2 \\
% L_3 & a_{31} & a_{32} & a_{33} & a_{34} & L_3 \\
% L_4 & a_{41} & a_{42} & a_{43} & a_{44} & L_4 \\
%     & C_1    & C_2    & C_3    & C_4    &     
% \end{pNiceMatrix}\]
%
% \bigskip
% We have several remarks to do.
% \begin{itemize}
% \item For the environments with an explicit preamble (i.e. |{NiceArray}| and
% its variants), no letter must be given in that preamble for the potential
% first column and the potential last column: the first column will be
% automatically (and necessarily) of type |R| and the last column will be
% automatically of % type |L|.
% \item In an environment with an explicit preamble, the option |last-col| must
% be used \emph{without} value: the number of columns will be automatically
% computed from the preamble of the array.
% \item For the potential last row, the option |last-row| may, in fact, be used
% without value. In this case, \pkg{nicematrix} computes, during the first
% compilation, the number of row of the array and writes that information in the
% |.aux| file for the second run. In the following example, the option
% |last-row| will be used without value.
% \end{itemize}
% 
% \bigskip
% It's possible to control the appearance of these rows and columns with options
% |code-for-first-row|, |code-for-last-row|, |code-for-first-col| and
% |code-for-last-col|. These options
% specify tokens that will be inserted before each cell of the corresponding row
% or column. 
% 
%
% \begin{Verbatim}
% \NiceMatrixOptions{~emphase#code-for-first-row@ = \color{red},
%                    ~emphase#code-for-first-col@ = \color{blue},
%                    ~emphase#code-for-last-row@ = \color{green},
%                    ~emphase#code-for-last-col@ = \color{magenta}}
% $\begin{pNiceArray}{CC|CC}[first-row,last-row,first-col,last-col]
%     & C_1    & C_2    & C_3    & C_4    &     \\
% L_1 & a_{11} & a_{12} & a_{13} & a_{14} & L_1 \\
% L_2 & a_{21} & a_{22} & a_{23} & a_{24} & L_2 \\
% \hline
% L_3 & a_{31} & a_{32} & a_{33} & a_{34} & L_3 \\
% L_4 & a_{41} & a_{42} & a_{43} & a_{44} & L_4 \\
%     & C_1    & C_2    & C_3    & C_4    &     
% \end{pNiceArray}$
% \end{Verbatim}
%
% \begin{scope}
% \NiceMatrixOptions{code-for-first-row = \color{red},
%                    code-for-first-col = \color{blue},
%                    code-for-last-row = \color{green},
%                    code-for-last-col = \color{magenta}}
% \[\begin{pNiceArray}{CC|CC}[first-row,last-row,first-col,last-col]
%     & C_1    & \multicolumn1C{C_2}    & C_3    & C_4    &     \\
% L_1 & a_{11} & a_{12} & a_{13} & a_{14} & L_1 \\
% L_2 & a_{21} & a_{22} & a_{23} & a_{24} & L_2 \\
% \hline
% L_3 & a_{31} & a_{32} & a_{33} & a_{34} & L_3 \\
% L_4 & a_{41} & a_{42} & a_{43} & a_{44} & L_4 \\
%     & C_1    & \multicolumn1C{C_2}    & C_3    & C_4    &     
% \end{pNiceArray}\]
% \end{scope}
%
%
% \emph{Remarks}
% \begin{itemize}[beginpenalty=10000]
% \item As shown in the previous example, an horizontal rule (drawn by |\hline|)
% doesn't extend in the exterior columns and a vertical rule (specified by a
% ``\verb+|+'' in the preamble of the array) doesn't extend in the exterior
% rows.\footnote{The latter is not true when the extension \pkg{arydshln} is
% loaded besides \pkg{nicematrix}. In fact, \pkg{nicematrix} and \pkg{arydhsln}
% are not totally compatible because \pkg{arydshln} redefines many internals of
% \pkg{array}. On another note, if one really wants a vertical rule running in
% the first and in the last row, he should use |!{\vline}| instead of \verb+|+
% in the preamble of the array.} 
% \item Logically, the potential option |columns-width| (described
% p.~\pageref{width}) doesn't apply to the ``first column'' and ``last column''.
% \item For technical reasons, it's not possible to use the option of the
% command |\\| after the ``first row'' or before the ``last row'' (the placement
% of the delimiters would be wrong). 
% \end{itemize}
% 
% 
% 
%
%
% \section{The dotted lines to separate rows or columns}
%
%
% In the environments of the extension \pkg{nicematrix}, it's possible to use
% the command |\hdottedline| (provided by \pkg{nicematrix}) which is a
% counterpart of the classical commands |\hline| and |\hdashline| (the latter is
% a command of\pkg{arydshln}).
%
% \medskip
% \begin{BVerbatim}[baseline=c,boxwidth=9.5cm]
% \begin{pNiceMatrix}
% 1 & 2 & 3 & 4 & 5 \\
% ~emphase#\hdottedline@
% 6 & 7 & 8 & 9 & 10 \\
% 11 & 12 & 13 & 14 & 15 
% \end{pNiceMatrix}
% \end{BVerbatim}
% $\begin{pNiceMatrix}
% 1 & 2 & 3 & 4 & 5 \\
% \hdottedline
% 6 & 7 & 8 & 9 & 10 \\
% 11 & 12 & 13 & 14 & 15 
% \end{pNiceMatrix}$
%
%
% \bigskip
% In the environments with an explicit preamble (like |{NiceArray}|, etc.), it's
% possible to draw a vertical dotted line with the specifier ``|:|''.
% 
% \medskip
% \begin{BVerbatim}[baseline=c,boxwidth=9.5cm]
% \left(\begin{NiceArray}{CCCC~emphase#:@C}
% 1 & 2 & 3 & 4 & 5 \\
% 6 & 7 & 8 & 9 & 10 \\
% 11 & 12 & 13 & 14 & 15 
% \end{NiceArray}\right)
% \end{BVerbatim}
% $\left(\begin{NiceArray}{CCCC:C}
% 1 & 2 & 3 & 4 & 5 \\
% 6 & 7 & 8 & 9 & 10 \\
% 11 & 12 & 13 & 14 & 15 
% \end{NiceArray}\right)$
%
%
% \bigskip 
% These dotted lines do \emph{not} extend in the potential exterior rows and
% columns.
%
% 
% \medskip
% \begin{BVerbatim}[baseline=c,boxwidth=9.5cm]
% $\begin{pNiceArray}{CCC:C}[
%     first-row,last-col, 
%     code-for-first-row = \color{blue}\scriptstyle,
%     code-for-last-col = \color{blue}\scriptstyle ]
% C_1 & C_2 & C_3 & C_4 \\
% 1 & 2 & 3 & 4 & L_1 \\
% 5 & 6 & 7 & 8 & L_2 \\
% 9 & 10 & 11 & 12 & L_3 \\
% \hdottedline
% 13 & 14 & 15 & 16 & L_4 
% \end{pNiceArray}$
% \end{BVerbatim}
% $\begin{pNiceArray}{CCC:C}[
%     first-row,last-col, 
%     code-for-first-row = \color{blue}\scriptstyle,
%     code-for-last-col = \color{blue}\scriptstyle ]
% C_1 & C_2 & C_3 & C_4 \\
% 1 & 2 & 3 & 4 & L_1 \\
% 5 & 6 & 7 & 8 & L_2 \\
% 9 & 10 & 11 & 12 & L_3 \\
% \hdottedline
% 13 & 14 & 15 & 16 & L_4 
% \end{pNiceArray}$
% 
% \bigskip
% It's possible to change in \pkg{nicematrix} the letter used to specify a
% vertical dotted line with the option |letter-for-dotted-lines| available in
% |\NiceMatrixOptions|. For example, in this document, we have loaded the
% extension \pkg{arydshln} which uses the letter ``:'' to specify a vertical
% dashed line. Thus, by using |letter-for-dotted-lines|, we can use the
% vertical lines of both \pkg{arydshln} and \pkg{nicematrix}.
% 
% \medskip
% \begin{BVerbatim}[baseline=c,boxwidth=9.5cm]
% \NiceMatrixOptions{letter-for-dotted-lines = V}
% \left(\begin{NiceArray}{~emphase#C|C:CVC@}
% 1 & 2 & 3 & 4 \\
% 5 & 6 & 7 & 8 \\
% 9 & 10 & 11 & 12
% \end{NiceArray}\right)
% \end{BVerbatim}
% \begin{scope}
% \NiceMatrixOptions{letter-for-dotted-lines = V}
% $\left(\begin{NiceArray}{C|C:CVC}
% 1 & 2 & 3 & 4 \\
% 5 & 6 & 7 & 8 \\
% 9 & 10 & 11 & 12
% \end{NiceArray}\right)$
% \end{scope}
%
% \section{The width of the columns}
% \label{width}
%
% In the environments with an explicit preamble (like |{NiceArray}|,
% |{pNiceArray}|, etc.), it's possible to fix the  width of a given column with
% the standard letters |w| and |W| of the package \pkg{array}. 
% 
% \medskip
% \begin{BVerbatim}[baseline=c,boxwidth=10cm]
% $\left(\begin{NiceArray}{~emphase#wc{1cm}@CC}
% 1  & 12 & -123 \\
% 12 & 0  & 0    \\
% 4  & 1  & 2 
% \end{NiceArray}\right)$
% \end{BVerbatim}
% $\left(\begin{NiceArray}{wc{1cm}CC}
% 1  & 12 & -123 \\
% 12 & 0  & 0    \\
% 4  & 1  & 2 
% \end{NiceArray}\right)$
%
%
% \bigskip
% In the environments of \pkg{nicematrix}, it's also possible to fix the width
% of all the columns of a matrix directly with the option |columns-width|.
% 
% \medskip
% \begin{BVerbatim}[baseline=c,boxwidth=10cm]
% $\begin{pNiceMatrix}[~emphase#columns-width = 1cm@]
% 1  & 12 & -123 \\
% 12 & 0  & 0    \\
% 4  & 1  & 2 
% \end{pNiceMatrix}$
% \end{BVerbatim}
% $\begin{pNiceMatrix}[columns-width = 1cm]
% 1  & 12 & -123 \\
% 12 & 0  & 0    \\
% 4  & 1  & 2 
% \end{pNiceMatrix}$
%
% \medskip
% Note that the space inserted between two columns (equal to 2 |\arraycolsep|)
% is not suppressed (of course, it's possible to suppress this space by setting
% |\arraycolsep| equal to $0$~pt).
%
% \bigskip
% It's possible to give the special value |auto| to the option |columns-width|:
% all the columns of the array will have a width equal to the widest cell of 
% the array.\footnote{The result is achieved with only one compilation (but Tikz
% will have written informations in the |.aux| file and a message requiring a
% second compilation will appear).}\par\nobreak 
%
% \medskip
% \begin{BVerbatim}[baseline=c,boxwidth=10cm]
% $\begin{pNiceMatrix}[~emphase#columns-width = auto@]
% 1  & 12 & -123 \\
% 12 & 0  & 0    \\
% 4  & 1  & 2 
% \end{pNiceMatrix}$
% \end{BVerbatim}
% $\begin{pNiceMatrix}[columns-width = auto]
% 1  & 12 & -123 \\
% 12 & 0  & 0    \\
% 4  & 1  & 2 
% \end{pNiceMatrix}$
% 
% \bigskip
% Without surprise, it's possible to fix the width of the columns of all the
% matrices of a current scope with the command |\NiceMatrixOptions|.\par\nobreak
%
% \medskip
% \begin{BVerbatim}[baseline=c,boxwidth=8.5cm]
% ~emphase#\NiceMatrixOptions{columns-width=10mm}@
% $\begin{pNiceMatrix}
% a & b \\ c & d \\
% \end{pNiceMatrix}
% = 
% \begin{pNiceMatrix}
% 1   & 1245 \\ 345 & 2 \\
% \end{pNiceMatrix}$
% \end{BVerbatim}
% \begin{scope}
% \NiceMatrixOptions{columns-width=10mm}
% $\begin{pNiceMatrix}
% a & b \\
% c & d \\
% \end{pNiceMatrix}
% = 
% \begin{pNiceMatrix}
% 1   & 1245 \\
% 345 & 2 \\
% \end{pNiceMatrix}$
% \end{scope}
% 
% 
% \bigskip
% But it's also possible to fix a zone where all the matrices will have their
% columns of the same width, equal to the widest cell of all the matrices. This
% construction uses the environment |{NiceMatrixBlock}| with the option
% |auto-columns-width|.\footnote{At this time, this is the only usage of the
% environment |{NiceMatrixBlock}| but it may have other usages in the future.}
%
% \medskip
% \begin{BVerbatim}[baseline=c,boxwidth=8.5cm]
% ~emphase#\begin{NiceMatrixBlock}[auto-columns-width]@
% $\begin{pNiceMatrix}
% a & b \\ c & d \\
% \end{pNiceMatrix}
% = 
% \begin{pNiceMatrix}
% 1   & 1245 \\ 345 & 2 \\
% \end{pNiceMatrix}$
% ~emphase#\end{NiceMatrixBlock}@
% \end{BVerbatim}
% \begin{NiceMatrixBlock}[auto-columns-width]
% $\begin{pNiceMatrix}
% a & b \\ c & d \\
% \end{pNiceMatrix}
% = 
% \begin{pNiceMatrix}
% 1   & 1245 \\  345 & 2 \\
% \end{pNiceMatrix}$
% \end{NiceMatrixBlock}
%
% \medskip
% \textbf{Several compilations may be necessary to achieve the job.}
%
%
% \section{Block matrices}
%
% In the environments of \pkg{nicematrix}, it's possible to use the command
% |\Block| in order to place an element in the center of a rectangle of merged
% cells of the array.
%
% The command |\Block| must be used in the upper leftmost cell of the array with
% two arguments. The first argument is the size of the block with the syntax
% $i$\verb|-|$j$ where $i$ is the number of rows of the block and $j$ its number
% of columns. The second argument is the content of the block (composed in math
% mode).
%
%
%
% \medskip
% \begin{BVerbatim}[baseline=c,boxwidth=10.6cm]
% \arrayrulecolor{cyan}
% $\begin{bNiceArray}{CCC|C}[margin]
% ~emphase#\Block{3-3}{A}@ & & & 0 \\
% & \hspace*{1cm} & & \Vdots \\
% & & & 0 \\
% \hline
% 0 & \Cdots& 0 & 0
% \end{bNiceArray}$
% \arrayrulecolor{black}
% \end{BVerbatim}
% \begin{scope}
% \arrayrulecolor{cyan}
% $\begin{bNiceArray}{CCC|C}[margin]
% \Block{3-3}{A} & & & 0 \\
% & \hspace*{1cm} & & \Vdots \\
% & & & 0 \\
% \hline
% 0 & \Cdots& 0 & 0
% \end{bNiceArray}$
% \arrayrulecolor{black}
% \end{scope}
%
% \bigskip
% One may wish to raise the size of the ``$A$'' placed in the block of the
% previous  example. Since this element is composed in math mode, it's not
% possible to use directly a command like |\large|, |\Large| and |\LARGE|.
% That's why the command |\Block| provides an option between angle brackets to
% specificy some TeX code which will be inserted before the beginning of the
% math mode. 
%
% \medskip
% \begin{BVerbatim}[baseline=c,boxwidth=10.6cm]
% \arrayrulecolor{cyan}
% $\begin{bNiceArray}{CCC|C}[margin]
% \Block{3-3}~emphase#<\Large>@{A} & & & 0 \\
% & \hspace*{1cm} & & \Vdots \\
% & & & 0 \\
% \hline
% 0 & \Cdots& 0 & 0
% \end{bNiceArray}$
% \arrayrulecolor{black}
% \end{BVerbatim}
% \begin{scope}
% \arrayrulecolor{cyan}
% $\begin{bNiceArray}{CCC|C}[margin]
% \Block{3-3}<\Large>{A} & & & 0 \\
% & \hspace*{1cm} & & \Vdots \\
% & & & 0 \\
% \hline
% 0 & \Cdots& 0 & 0
% \end{bNiceArray}$
% \arrayrulecolor{black}
% \end{scope}
%
% \medskip
% For technical reasons, you can't write |\Block{|$i$|-|$j$|}{<}|. But you can
% write |\Block{|$i$|-|$j$|}<>{<}| with the expected result.
% 
% 
%
% \section{The option small}
%
% With the option |small|, the environments of the extension \pkg{nicematrix}
% are composed in a way similar to the environment |{smallmatrix}| of the
% extension \pkg{amsmath} (and the environments |{psmallmatrix}|,
% |{bsmallmatrix}|, etc. of the extension \pkg{mathtools}).
%
% \bigskip
% \begin{Verbatim}
% $\begin{bNiceArray}{CCCC|C}[~emphase#small@, 
%                             last-col, 
%                             code-for-last-col = \scriptscriptstyle, 
%                             columns-width = 3mm ] 
% 1 & -2 & 3 & 4 & 5 \\
% 0 & 3  & 2 & 1 & 2 & L_2 \gets 2 L_1 - L_2 \\
% 0 & 1  & 1 & 2 & 3 & L_3 \gets L_1 + L_3 \\
% \end{bNiceArray}$
% \end{Verbatim}
% %
% \[\begin{bNiceArray}{CCCC|C}[small, last-col, 
%                      code-for-last-col = \scriptscriptstyle, 
%                      columns-width=3mm]
% 1 & -2 & 3 & 4 & 5 \\
% 0 & 3  & 2 & 1 & 2 & L_2 \gets 2 L_1 - L_2 \\
% 0 & 1  & 1 & 2 & 3 & L_3 \gets L_1 + L_3 \\
% \end{bNiceArray}\]
%
%
%
% \bigskip
% One should note that the environment |{NiceMatrix}| with the option |small| is
% not composed \emph{exactly} as the environment |{smallmatrix}|. Indeed, all
% the environments of \pkg{nicematrix} are constructed upon |{array}| (of the
% extension \pkg{array}) whereas the environment |{smallmatrix}| is constructed
% directly with an |\halign| of TeX.
%
% \medskip
% In fact, the option |small| corresponds to the following tuning:
% \begin{itemize}
% \item the cells of the array are composed with \verb|\scriptstyle| ; 
% \item \verb|\arraystretch| is set to $0.47$ ; 
% \item \verb|\arraycolsep| is set to $1.45$~pt ; 
% \item the characteristics of the dotted lines are also modified.
% \end{itemize}
%
% \section{The counters iRow and jCol}
%
% In the cells of the array, it's possible to use the LaTeX counters |iRow| and
% |jCol| which represents the number of the current row and the number of the
% current col\footnote{We recall that the first row (if it exists) has the
% number~$0$ and that the first col (if it exists) has also the number~$0$).}. Of
% course, the user must not change the value of the these counters which are
% used internally by \pkg{nicematrix}.
%
% \medskip
% \begin{BVerbatim}[baseline=c,boxwidth=10.6cm]
% $\begin{pNiceMatrix}% don't forget the %
%     [first-row,
%      first-col,
%      code-for-first-row = \mathbf{~emphase#\alph{jCol}@} ,
%      code-for-first-col = \mathbf{~emphase#\arabic{iRow}@} ]
% &   &    &    &   \\
% & 1 & 2  & 3  & 4 \\
% & 5 & 6  & 7  & 8 \\
% & 9 & 10 & 11 & 12
% \end{pNiceMatrix}$
% \end{BVerbatim}
% $\begin{pNiceMatrix}[first-row,
%                    first-col,
%                    code-for-first-row = \mathbf{\alph{jCol}} ,
%                    code-for-first-col = \mathbf{\arabic{iRow}} ]
% &   &    &    &   \\
% & 1 & 2  & 3  & 4 \\
% & 5 & 6  & 7  & 8 \\
% & 9 & 10 & 11 & 12
% \end{pNiceMatrix}$
% 
% \smallskip
% If LaTeX counters called |iRow| and |jCol| are defined in the document by
% extensions other than \pkg{nicematrix} (or by the user), they are shadowed in
% the environements of \pkg{nicematrix}.
%
% \section{The option hlines}
% 
% You can add horizontal rules between rows in the environments of
% \pkg{nicematrix} with the usual command |\hline|. But, by convenience, the
% extension \pkg{nicematrix} also provides the option |hlines|. With this
% option, all the horizontal rules will be drawn (excepted, of course, the rule
% before the potential ``first row'' and the rule after the potential ``last
% row'').
% 
% \medskip
% \begin{BVerbatim}[baseline=c,boxwidth=10.6cm]
% $\begin{NiceArray}{|*{4}{C|}}[~emphase#hlines@,first-row,first-col]
%   & e & a & b & c \\
% e & e & a & b & c \\
% a & a & e & c & b \\
% b & b & c & e & a \\
% c & c & b & a & e 
% \end{NiceArray}$
% \end{BVerbatim}
% \raise-5mm\box\ExampleOne
% 
% \section{Utilisation of the column type S of siunitx}
%
% If the package \pkg{siunitx} is loaded (before or after \pkg{nicematrix}),
% it's possible to use the |S| column type of \pkg{siunitx} in the environments
% of \pkg{nicematrix}. The implementation doesn't use explicitly any private
% macro of \pkg{siunitx}. 
% 
% 
% \medskip
% \begin{BVerbatim}[baseline = c, boxwidth = 10.5cm]
% $\begin{pNiceArray}{~emphase#S@CWc{1cm}C}[nullify-dots,first-row]
% {C_1} & \Cdots &  & C_n \\
% 2.3  & 0 & \Cdots & 0 \\
% 12.4 & \Vdots & & \Vdots \\
% 1.45 \\
% 7.2  & 0 & \Cdots & 0 
% \end{pNiceArray}$
% \end{BVerbatim}
% $\begin{pNiceArray}{SCWc{1cm}C}[nullify-dots,first-row]
% {C_1} & \Cdots &  & C_n \\
% 2.3  & 0 & \Cdots & 0 \\
% 12.4 & \Vdots & & \Vdots \\
% 1.45 \\
% 7.2  & 0 & \Cdots & 0 
% \end{pNiceArray}$
% 
% On the other hand, the |d| columns of the package \pkg{dcolumn} are not
% supported by \pkg{nicematrix}.
%
% \section{Technical remarks}
%
% \subsection{Intersections of dotted lines}
%
% Since the version 3.1 of \pkg{nicematrix}, the dotted lines created by
% |\Cdots|, |\Ldots|, |\Vdots|, etc. can't intersect.\footnote{Of the contrary,
% dotted lines created by |\hdottedline|, the letter ``|:|'' in the preamble
% of the array and the command |\line| in the |code-after| can have
% intersections with other dotted lines.}  
%
% That means that a dotted line created by one these commands automatically
% stops when it arrives on a dotted line already drawn. Therefore, the order in
% which dotted lines are drawn is important. Here's that order (by design) :
% |\Hdotsfor|, |\Vdots|, |\Ddots|, |\Iddots|, |\Cdots| and |\Ldots|.
%
% With this structure, it's possible to draw the following matrix.
%
% \medskip
% \begin{BVerbatim}[baseline = c, boxwidth = 10.5cm]
% $\begin{pNiceMatrix}[nullify-dots]
% 1 & 2 & 3 & \Cdots & n \\
% 1 & 2 & 3 & \Cdots & n \\
% \Vdots & \Cdots & & \Hspace*{15mm} & \Vdots \\
% & \Cdots & & &  \\
% & \Cdots & & &  \\
% & \Cdots & & &  \\
% \end{pNiceMatrix}$
% \end{BVerbatim}
% % $\begin{pNiceMatrix}[nullify-dots]
% 1 & 2 & 3 & \Cdots & n \\
% 1 & 2 & 3 & \Cdots & n \\
% \Vdots & \Cdots & & \Hspace*{15mm} & \Vdots \\
% & \Cdots & & &  \\
% & \Cdots & & &  \\
% & \Cdots & & &  \\
% \end{pNiceMatrix}$
% 
% 
% 
% 
% \subsection{Diagonal lines} 
%
% By default, all the diagonal lines\footnote{We speak of the lines created by
% |\Ddots| and not the lines created by a command |\line| in |code-after|.} of a
% same array are ``parallelized''. That means that the first diagonal line is
% drawn and, then, the other lines are drawn parallel to the first one (by
% rotation around the left-most extremity of the line). That's why the position
% of the instructions |\Ddots| in the array can have a marked effect on the
% final result.
%
% \medskip
% In the following examples, the first |\Ddots| instruction is written in color:
% 
% \medskip
% \begin{scope}
% \begin{minipage}{9.5cm}
% Example with parallelization (default):
% \begin{Verbatim}
% $A = \begin{pNiceMatrix}
% 1      & \Cdots &        & 1      \\
% a+b    & ~emphase#\Ddots@~ &        & \Vdots \\
% \Vdots & \Ddots &        &        \\
% a+b    & \Cdots & a+b    & 1
% \end{pNiceMatrix}$
% \end{Verbatim}
% \end{minipage}
% $A = \begin{pNiceMatrix}
% 1      & \Cdots &     & 1      \\
% a+b    & \Ddots &     & \Vdots \\
% \Vdots & \Ddots &     &        \\
% a+b    & \Cdots & a+b & 1
% \end{pNiceMatrix}$
% 
% \bigskip
% \NiceMatrixOptions{parallelize-diags=true}%
% \begin{minipage}{9.5cm}
% % \begin{Verbatim}
% $A = \begin{pNiceMatrix}
% 1      & \Cdots &        & 1      \\
% a+b    &        &        & \Vdots \\
% \Vdots & ~emphase#\Ddots@~ & \Ddots &        \\
% a+b    & \Cdots & a+b    & 1
% \end{pNiceMatrix}$
% \end{Verbatim}
% \end{minipage}
% $A = \begin{pNiceMatrix}
% 1      & \Cdots &        & 1      \\
% a+b    &        &        & \Vdots \\
% \Vdots & \Ddots & \Ddots &        \\
% a+b    & \Cdots & a+b    & 1
% \end{pNiceMatrix}$
%
% \bigskip
% It's possible to turn off the parallelization with the option
% |parallelize-diags| set to |false|: \par\nobreak
%
% \medskip
% \NiceMatrixOptions{parallelize-diags=false}%
% \begin{minipage}{9.5cm}
% The same example without parallelization:
% \end{minipage}
% $A = \begin{pNiceMatrix}
% 1      & \Cdots  &     & 1      \\
% a+b    & \Ddots  &     & \Vdots \\
% \Vdots & \Ddots  &     &        \\
% a+b    & \Cdots  & a+b & 1
% \end{pNiceMatrix}$
%
%
% \end{scope}
%
% \subsection{The ``empty'' cells}
% 
% \label{empty-cells}
% An instruction like |\Ldots|, |\Cdots|, etc. tries to determine the first
% non-empty cells on both sides. However, an empty cell is not necessarily a
% cell with no TeX content (that is to say a cell with no token between the two 
% ampersands~|&|). Indeed, a cell with contents |\hspace*{1cm}| may be
% considered as empty.
%
% \interitem
% For \pkg{nicematrix}, the precise rules are as follow.
%
% \begin{itemize}
% \item An implicit cell is empty. For example, in the following matrix:
%
% \begin{Verbatim}
% \begin{pmatrix}
% a & b \\
% c \\
% \end{pmatrix}
% \end{Verbatim}
% 
% the last cell (second row and second column) is empty.
%
% \medskip
% \item Each cell whose TeX ouput has a width less than 0.5~pt is empty.
%
% \medskip
% \item A cell which contains a command |\Ldots|, |\Cdots|, |\Vdots|, |\Ddots|
% or |\Iddots| is empty. We recall that these commands should be used alone in a
% cell. 
%
% \medskip
% \item A cell with a command |\Hspace| (or |\Hspace*|) is empty. This command
% |\Hspace| is a command defined by the package \pkg{nicematrix} with the same
% meaning as |\hspace| except that the cell where it is used is considered as
% empty. This command can be used to fix the width of some columns of the matrix
% without interfering with \pkg{nicematrix}.
% % \end{itemize}
%
%
% \subsection{The option exterior-arraycolsep}
% 
% The environment |{array}| inserts an horizontal space equal to |\arraycolsep|
% before and after each column. In particular, there is a space equal to
% |\arraycolsep| before and after the array. This feature of the environment
% |{array}| was probably not a good idea\footnote{In the documentation of
% |{amsmath}|, we can read: {\itshape The extra space of |\arraycolsep| that
% \pkg{array} adds on each side is a waste so we remove it [in |{matrix}|]
% (perhaps we should instead remove it from array in general, but that's a
% harder task).} It's possible to suppress these spaces for a given environment
% |{array}| with a construction like
% |\begin{array}{@{}ccccc@{}}...\end{array}|.}. 
% The environment |{matrix}| of \pkg{amsmath} and its variants (|{pmatrix}|,
% |{vmatrix}|, etc.) of \pkg{amsmath} prefer to delete these spaces with
% explicit instructions |\hskip -\arraycolsep|. The extension \pkg{nicematrix}
% does the same in all its environments, |{NiceArray}| included. However, if the
% user wants the environment |{NiceArray}| behaving by default like the
% environment |{array}| of \pkg{array} (for example, when adapting an existing
% document) it's possible to control this behaviour with the option
% |exterior-arraycolsep|, set by the command |\NiceMatrixOptions|. With this
% option, exterior spaces of length |\arraycolsep| will be inserted in the
% environments |{NiceArray}| (the other environments of \pkg{nicematrix} are not
% affected). 
%
%
% \subsection{The class option draft}
%
% The package \pkg{nicematrix} is rather slow when drawing the dotted lines
% (generated by |\Cdots|, |\Ldots|, |\Ddots|, etc. but also by |\hdottedline| or
% the specifier |:|).\footnote{The main reason is that we want dotted lines with
% round dots (and not square dots) with the same space on both extremities of
% the lines. To achieve this goal, we have to construct our own system of dotted
% lines.} 
%
% That's why, when the class option |draft| is used, the dotted lines are not
% drawn, for a faster compilation. 
% 
% \subsection{A technical problem with the argument of
% \textbackslash\textbackslash}
% 
%
% For technical, reasons, if you use the optional argument of the command |\\|,
% the vertical space added will also be added to the ``normal'' node
% corresponding at the previous node. 
%
% \medskip
% \begin{BVerbatim}[baseline=c,boxwidth=11cm]
%      \begin{pNiceMatrix}
%      a & \frac AB \\~emphase#[2mm]@
%      b & c
%      \end{pNiceMatrix}
% \end{BVerbatim}
% $\begin{pNiceMatrix}[
%    code-after = {\tikz \node [inner sep = 0pt,
%                               fill = red!15,
%                               blend mode = multiply,
%                               fit = (1-2) ] {} ; } ]
% a & \frac AB \\[2mm]
% b & c
% \end{pNiceMatrix}$
%
% \bigskip
% There are two solutions to solve this problem. The first solution is to use a
% TeX command to insert space between the rows.
%
% \medskip
% \begin{BVerbatim}[baseline=c,boxwidth=11cm]
%      \begin{pNiceMatrix}
%      a & \frac AB \\
%      ~emphase#\noalign{\kern2mm}@
%      b & c
%      \end{pNiceMatrix}
% \end{BVerbatim}
% $\begin{pNiceMatrix}[
%    code-after = {\tikz \node [inner sep = 0pt,
%                               fill = red!15,
%                               blend mode = multiply,
%                               fit = (1-2) ] {} ; } ]
% a & \frac AB \\
% \noalign{\kern2mm}
% b & c
% \end{pNiceMatrix}$
%
%
% \bigskip
% The other solution is to use the command |\multicolumn| in the previous cell.
%
% \medskip
% \begin{BVerbatim}[baseline=c,boxwidth=11cm]
%      \begin{pNiceMatrix}
%      a & ~emphase#\multicolumn1C{\frac AB}@ \\[2mm]
%      b & c
%      \end{pNiceMatrix}
% \end{BVerbatim}
% $\begin{pNiceMatrix}[
%    code-after = {\tikz \node [inner sep = 0pt,
%                               fill = red!15,
%                               blend mode = multiply,
%                               fit = (1-2) ] {} ; } ]
% a & \multicolumn1C{\frac AB} \\[2mm]
% b & c
% \end{pNiceMatrix}$
%
%
% \subsection{Obsolete environments}      
% 
% The version 3.0 of \pkg{nicematrix} has introduced the environment
% |{pNiceArray}| (and its variants) with the options |first-row|, |last-row|,
% |first-col| and |last-col|. 
%
% Consequently the following environments present in previous versions of
% \pkg{nicematrix} are deprecated:
% %
% \begin{itemize}
% \item |{NiceArrayCwithDelims}| ;
% \item |{pNiceArrayC}|, |{bNiceArrayC}|, |{BNiceArrayC}|, |{vNiceArrayC}|,
% |{VNiceArrayC}| ;
% \item |{NiceArrayRCwithDelims}| ;
% \item |{pNiceArrayRC}|, |{bNiceArrayRC}|, |{BNiceArrayRC}|, |{vNiceArrayRC}|,
% |{VNiceArrayRC}|.
% \end{itemize}
%       
% They might be deleted in a future version of \pkg{nicematrix}.
%
% \section{Examples}
%
% \subsection{Dotted lines}
%
% \medskip
% A tridiagonal matrix:
% 
% \bigskip
% \begin{BVerbatim}[baseline=c]
% $\begin{pNiceMatrix}[nullify-dots]
% a      & b      & 0      &        & \Cdots & 0      \\ 
% b      & a      & b      & \Ddots &        & \Vdots \\
% 0      & b      & a      & \Ddots &        &        \\
%        & \Ddots & \Ddots & \Ddots &        & 0      \\
% \Vdots &        &        &        &        & b      \\
% 0      & \Cdots &        & 0      & b      & a
% \end{pNiceMatrix}$
% \end{BVerbatim}
% \hspace{1.5cm}
% $\begin{pNiceMatrix}[nullify-dots]
% a      & b      & 0      &        & \Cdots & 0      \\ 
% b      & a      & b      & \Ddots &        & \Vdots \\
% 0      & b      & a      & \Ddots &        &        \\
%        & \Ddots & \Ddots & \Ddots &        & 0      \\
% \Vdots &        &        &        &        & b      \\
% 0      & \Cdots &        & 0      & b      & a
% \end{pNiceMatrix}$
%
% \vspace{2cm}
%
% A permutation matrix:
%
% \bigskip
% \begin{BVerbatim}[baseline=c]
% $\begin{pNiceMatrix}
% 0       & 1 & 0 &        & \Cdots &   0    \\
% \Vdots  &   &   & \Ddots &        & \Vdots \\
%         &   &   & \Ddots &        &        \\
%         &   &   & \Ddots &        &   0    \\
% 0       & 0 &   &        &        &   1    \\
% 1       & 0 &   & \Cdots &        &   0    
% \end{pNiceMatrix}$
% \end{BVerbatim}
% \hspace{2.5cm}
% $\begin{pNiceMatrix}
% 0       & 1 & 0 &        & \Cdots &   0    \\
% \Vdots  &   &   & \Ddots &        & \Vdots \\
%         &   &   & \Ddots &        &        \\
%         &   &   & \Ddots &        &   0    \\
% 0       & 0 &   &        &        &   1    \\
% 1       & 0 &   & \Cdots &        &   0    
% \end{pNiceMatrix}$
%
% \vspace{2cm}
%
% An example with |\Iddots|: \par\nobreak
%
% \bigskip
% \begin{BVerbatim}[baseline=c]
% $\begin{pNiceMatrix}
% 1       & \Cdots  &         & 1      \\
% \Vdots  &         &         & 0      \\
%         & ~emphase#\Iddots@ & ~emphase#\Iddots@ & \Vdots \\
% 1       & 0       & \Cdots  & 0 
% \end{pNiceMatrix}$
% \end{BVerbatim}
% \hspace{4cm}
% $\begin{pNiceMatrix}
% 1       & \Cdots  &         & 1      \\
% \Vdots  &         &         & 0      \\
%         & \Iddots & \Iddots & \Vdots \\
% 1       & 0       & \Cdots  & 0 
% \end{pNiceMatrix}$
%
%
% \vspace{2cm}
% An example with |\multicolumn|:\par\nobreak
%
% \bigskip
% \begin{BVerbatim}
% \begin{BNiceMatrix}[nullify-dots]
% 1 & 2 & 3 & 4 & 5 & 6 & 7 & 8 & 9 & 10\\
% 1 & 2 & 3 & 4 & 5 & 6 & 7 & 8 & 9 & 10\\
% \Cdots &  & ~emphase#\multicolumn{6}{C}{10 \text{ other rows}}@ & \Cdots \\
% 1 & 2 & 3 & 4 & 5 & 6 & 7 & 8 & 9 & 10
% \end{BNiceMatrix}
% \end{BVerbatim}
% 
% \bigskip
% \[\begin{BNiceMatrix}[nullify-dots]
% 1 & 2 & 3 & 4 & 5 & 6 & 7 & 8 & 9 & 10\\
% 1 & 2 & 3 & 4 & 5 & 6 & 7 & 8 & 9 & 10\\
% \Cdots &  & \multicolumn{6}{C}{10 \text{ other rows}} & \Cdots \\
% 1 & 2 & 3 & 4 & 5 & 6 & 7 & 8 & 9 & 10
% \end{BNiceMatrix}\]
% 
% \vspace{2cm}
% An example with |\Hdotsfor|:\par\nobreak
%
% \bigskip
% \begin{BVerbatim}[baseline=c,boxwidth=11cm]
% \begin{pNiceMatrix}[nullify-dots]
% 0 & 1 & 1 & 1 & 1 & 0 \\
% 0 & 1 & 1 & 1 & 1 & 0 \\
% \Vdots  & ~emphase#\Hdotsfor{4}@ & \Vdots \\
%  & ~emphase#\Hdotsfor{4}@ & \\
%  & ~emphase#\Hdotsfor{4}@ & \\
%  & ~emphase#\Hdotsfor{4}@ & \\
% 0 & 1 & 1 & 1 & 1 & 0 
% \end{pNiceMatrix}
% \end{BVerbatim}
% $\begin{pNiceMatrix}[nullify-dots]
% 0 & 1 & 1 & 1 & 1 & 0 \\
% 0 & 1 & 1 & 1 & 1 & 0 \\
% \Vdots  & \Hdotsfor{4} & \Vdots \\
%  & \Hdotsfor{4} & \\
%  & \Hdotsfor{4} & \\
%  & \Hdotsfor{4} & \\
% 0 & 1 & 1 & 1 & 1 & 0 
% \end{pNiceMatrix}$
%
% \vspace{2cm}
% An example for the resultant of two polynoms:\par\nobreak
%
% \bigskip
% \begin{BVerbatim}
% \setlength{\extrarowheight}{1mm}
% \[\begin{vNiceArray}{CCCC:CCC}[columns-width=6mm]
% a_0   &      &&       &b_0    &      &     \\
% a_1   &\Ddots&&       &b_1    &\Ddots&     \\
% \Vdots&\Ddots&&       &\Vdots &\Ddots&b_0  \\
% a_p   &      &&a_0    &       &      &b_1   \\
%       &\Ddots&&a_1    &b_q    &      &\Vdots\\
%       &      &&\Vdots &       &\Ddots&      \\
%       &      &&a_p     &       &      &b_q    
% \end{vNiceArray}\]
% \end{BVerbatim}
% 
% \bigskip
%
% \begin{scope}
% \setlength{\extrarowheight}{1mm}
% \[\begin{vNiceArray}{CCCC:CCC}[columns-width=6mm]
% a_0   &      &&       &b_0    &      &     \\
% a_1   &\Ddots&&       &b_1    &\Ddots&     \\
% \Vdots&\Ddots&&       &\Vdots &\Ddots&b_0  \\
% a_p   &      &&a_0    &       &      &b_1   \\
%       &\Ddots&&a_1    &b_q    &      &\Vdots\\
%       &      &&\Vdots &       &\Ddots&      \\
%       &      &&a_p     &       &      &b_q    
% \end{vNiceArray}\]
% \end{scope}   
%
% \vspace{2cm}
% An example for a linear system (the vertical rule has been drawn in cyan with
% the tools of \pkg{colortbl}):\par\nobreak
%
% \begin{Verbatim}
% \arrayrulecolor{cyan}
% $\begin{pNiceArray}{*6C|C}[nullify-dots,last-col,code-for-last-col={\scriptstyle}]
% 1      & 1 & 1 &\Cdots &   & 1      & 0      & \\
% 0      & 1 & 0 &\Cdots &   & 0      &        & L_2 \gets L_2-L_1 \\
% 0      & 0 & 1 &\Ddots &   & \Vdots &        & L_3 \gets L_3-L_1 \\
%        &   &   &\Ddots &   &        & \Vdots & \Vdots \\
% \Vdots &   &   &\Ddots &   & 0      & \\
% 0      &   &   &\Cdots & 0 & 1      & 0      & L_n \gets L_n-L_1 
% \end{pNiceArray}$
% \arrayrulecolor{black}
% \end{Verbatim}
% 
% \arrayrulecolor{cyan}
% \[\begin{pNiceArray}{*6C|C}[nullify-dots,last-col,
%       code-for-last-col={\scriptstyle}]
% 1      & 1 & 1 &\Cdots &   & 1      & 0      & \\
% 0      & 1 & 0 &\Cdots &   & 0      &        & L_2 \gets L_2-L_1 \\
% 0      & 0 & 1 &\Ddots &   & \Vdots &        & L_3 \gets L_3-L_1 \\
%        &   &   &\Ddots &   &        & \Vdots & \Vdots \\
% \Vdots &   &   &\Ddots &   & 0      & \\
% 0      &   &   &\Cdots & 0 & 1      & 0      & L_n \gets L_n-L_1 
% \end{pNiceArray}\]
% \arrayrulecolor{black}
%
%
% \subsection{Width of the columns}
% 
%
% \medskip
% In the following example, we use |{NiceMatrixBlock}| with the option
% |auto-columns-width| because we want the same automatic width for all the
% columns of the matrices. 
%
% \bigskip
% \begin{BVerbatim}
% ~emphase#\begin{NiceMatrixBlock}[auto-columns-width]@
% \NiceMatrixOptions{code-for-last-col = \color{blue}\scriptstyle}
% \setlength{\extrarowheight}{1mm}
% \quad $\begin{pNiceArray}{CCCC:C}[last-col]
% 1&1&1&1&1&\\
% 2&4&8&16&9&\\
% 3&9&27&81&36&\\
% 4&16&64&256&100&
% \end{pNiceArray}$
% ...
% ~emphase#\end{NiceMatrixBlock}@
% \end{BVerbatim}
% 
% \bigskip
% 
% \begin{multicols}{2}
% \begin{NiceMatrixBlock}[auto-columns-width]
% \NiceMatrixOptions{code-for-last-col = \color{blue}\scriptstyle}
% \setlength{\extrarowheight}{1mm}
%
% \enskip $\begin{pNiceArray}{CCCC:C}[last-col]
% 1&1&1&1&1&\\
% 2&4&8&16&9&\\
% 3&9&27&81&36&\\
% 4&16&64&256&100&
% \end{pNiceArray}$
%
% \medskip
%
% \enskip $\begin{pNiceArray}{CCCC:C}[last-col]
% 1&1&1&1&1&\\
% 0&2&6&14&7&L_2\gets-2L_1+L_2 \\
% 0&6&24&78&33&L_3\gets-3L_1+L_3 \\
% 0&12&60&252&96&L_4\gets-4L_1+L_4 
% \end{pNiceArray}$
%
% \medskip
%
% \enskip $\begin{pNiceArray}{CCCC:C}[last-col]
% 1&1&1&1&1&\\
% 0&1&3&7&\frac72&L_2\gets\frac12L_2\\
% 0&3&12&39&\frac{33}2&L_3\gets\frac12L_3 \\
% 0&1&5&21&8&L_4\gets\frac1{12}L_4 
% \end{pNiceArray}$
%
% \medskip
%
% \enskip $\begin{pNiceArray}{CCCC:C}[last-col]
% 1&1&1&1&1&\\
% 0&1&3&7&\frac72&\\
% 0&0&3&18&6&L_3 \gets -3L_2+L_3 \\
% 0&0&-2&-14&-\frac92&L_4 \gets L_2-L_4 
% \end{pNiceArray}$
%
% \medskip
%
% \enskip $\begin{pNiceArray}{CCCC:C}[last-col]
% 1&1&1&1&1&\\
% 0&1&3&7&\frac72&\\
% 0&0&1&6&2&L_3 \gets \frac13L_3\\
% 0&0&-2&-14&-\frac92&
% \end{pNiceArray}$
%
% \medskip
%
% \enskip $\begin{pNiceArray}{CCCC:C}[last-col]
% 1&1&1&1&1&\\
% 0&1&3&7&\frac72&\\
% 0&0&1&6&2& \\
% 0&0&0&-2&-\frac12 & L_4 \gets 2L_3+L_4 
% \end{pNiceArray}$
% \end{NiceMatrixBlock}
% \end{multicols}
% 
% 
% \subsection{How to highlight cells of the matrix}
%
% \label{highlight}
% \medskip
% In order to highlight a cell of a matrix, it's possible to ``draw'' one of the
% correspondant nodes (the ``normal node'', the ``medium node'' or the ``large
% node''). In the following example, we use the ``large nodes'' of the diagonal
% of the matrix (with the Tikz key ``|name suffix|'', it's easy to use the
% ``large nodes''). 
%
% In order to have the continuity of the lines, we have to set
%  |inner sep = -\pgflinewidth/2|.
%
% \begin{Verbatim}
% $\begin{pNiceArray}{>{\strut}CCCC}%
%    [create-extra-nodes,margin,extra-margin = 2pt ,
%     code-after = {\begin{tikzpicture}
%                      [~emphase#name suffix = -large@,
%                       every node/.style = {draw,
%                                            ~emphase#inner sep = -\pgflinewidth/2@}]
%                      \node [fit = (1-1)] {} ; 
%                      \node [fit = (2-2)] {} ; 
%                      \node [fit = (3-3)] {} ; 
%                      \node [fit = (4-4)] {} ; 
%                   \end{tikzpicture}}]
% a_{11} & a_{12} & a_{13} & a_{14} \\
% a_{21} & a_{22} & a_{23} & a_{24} \\
% a_{31} & a_{32} & a_{33} & a_{34} \\
% a_{41} & a_{42} & a_{43} & a_{44} 
% \end{pNiceArray}$
% \end{Verbatim}
%
%
% \[\begin{pNiceArray}{>{\strut}CCCC}[
%     create-extra-nodes,margin,extra-margin = 2pt,
%     code-after = {\begin{tikzpicture}[name suffix = -large,
%                                       every node/.style = {draw,
%                                                            inner sep = -\pgflinewidth/2}]
%                      \node [fit = (1-1)] {} ; 
%                      \node [fit = (2-2)] {} ; 
%                      \node [fit = (3-3)] {} ; 
%                      \node [fit = (4-4)] {} ; 
%                   \end{tikzpicture}}]
% a_{11} & a_{12} & a_{13} & a_{14} \\
% a_{21} & a_{22} & a_{23} & a_{24} \\
% a_{31} & a_{32} & a_{33} & a_{34} \\
% a_{41} & a_{42} & a_{43} & a_{44} 
% \end{pNiceArray}\]
% 
%
% \vspace{1cm}
% The package \pkg{nicematrix} is constructed upon the environment |{array}|
% and, therefore, it's possible to use the package \pkg{colortbl} in the
% environments of \pkg{nicematrix}. However, it's not always easy to do a fine
% tuning of \pkg{colortbl}. That's why we propose another method to highlight a
% row of the matrix. We create a rectangular Tikz node which encompasses the
% nodes of the second row with the Tikz library \pkg{fit}. This Tikz node is
% filled after the construction of the matrix. In order to see the text
% \emph{under} this node, we have to use transparency with the |blend mode|
% equal to |multiply|. Warning: some \textsc{pdf} readers are not able to render
% transparency correctly. 
%
% \tikzset{highlight/.style={rectangle,
%                            fill=red!15,
%                            blend mode = multiply, 
%                            rounded corners = 0.5 mm, 
%                            inner sep=1pt}}
%
% \medskip
% \begin{Verbatim}
% \tikzset{highlight/.style={rectangle,
%                            fill=red!15,
%                            ~emphase#blend mode = multiply@,
%                            rounded corners = 0.5 mm, 
%                            inner sep=1pt}}
%
% $\begin{bNiceMatrix}[~emphase#code-after = {\tikz \node[highlight, fit = (2-1) (2-3)] {} ;}@]
% 0 & \Cdots & 0 \\
% 1 & \Cdots & 1 \\
% 0 & \Cdots & 0 
% \end{bNiceMatrix}$
% \end{Verbatim}
% 
% \[\begin{bNiceMatrix}[code-after = {\tikz \node[highlight, fit = (2-1) (2-3)] {} ;}]
% 0 & \Cdots & 0 \\
% 1 & \Cdots & 1 \\
% 0 & \Cdots & 0 
% \end{bNiceMatrix}\]
% 
%
% \bigskip
% This code fails with |latex|-|dvips|-|ps2pdf| because Tikz for |dvips|, as for
% now, doesn't support blend modes. However, the following code, in the
% preamble, should activate blend modes in this way of compilation. 
%
%
% \begin{scope} \small
% |\ExplSyntaxOn|
%
% |\makeatletter|
%
% |\tl_set:Nn \l_tmpa_tl {pgfsys-dvips.def}|
%
% |\tl_if_eq:NNT \l_tmpa_tl \pgfsysdriver|
%
% |  {\cs_set:Npn\pgfsys@blend@mode#1{\special{ps:~/\tl_upper_case:n #1~.setblendmode}}}|
%
% |\makeatother|
%
% |\ExplSyntaxOff|
% \end{scope}
% 
% \vspace{1cm}
% Considerer now the following matrix which we have named |example|.
%
% \medskip
% \begin{Verbatim}
% $\begin{pNiceArray}{CCC}[~emphase#name=example@,last-col,create-extra-nodes]
% a & a + b & a + b + c & L_1\\
% a & a     & a + b     & L_2 \\
% a & a     & a         & L_3
% \end{pNiceArray}$
% \end{Verbatim}
%                           
% \[\begin{pNiceArray}{CCC}[last-col]
% a & a + b & a + b + c & L_1\\
% a & a     & a + b     & L_2 \\
% a & a     & a         & L_3
% \end{pNiceArray}\]
% 
% \bigskip
% If we want to highlight each row of this matrix, we can use the previous
% technique three times. 
%
% \begin{Verbatim}
% \tikzset{myoptions/.style={remember picture, 
%                            overlay,
%                            name prefix = example-,
%                            every node/.style = {fill = red!15,
%                                                 blend mode = multiply,
%                                                 inner sep = 0pt}}}
% \end{Verbatim}
% 
%
% \tikzset{myoptions/.style={remember picture, 
%                            overlay,
%                            name prefix = example-,
%                            every node/.style = {fill = red!15,
%                                                 blend mode = multiply,
%                                                 inner sep = 0pt}}}
%
% \begin{Verbatim}
% \begin{tikzpicture}[myoptions]
% \node [fit = (1-1) (1-3)] {} ;
% \node [fit = (2-1) (2-3)] {} ;
% \node [fit = (3-1) (3-3)] {} ;
% \end{tikzpicture}
% \end{Verbatim}
%
% \medskip
% We obtain the following matrix.
% 
% \[\begin{pNiceArray}{CCC}[
%      last-col,
%      create-extra-nodes,
%      code-after = {\begin{tikzpicture}[every node/.style = {fill = red!15,
%                                                             blend mode = multiply,
%                                                             inner sep = 0pt}]
%                    \node [fit = (1-1) (1-3)] {} ;
%                    \node [fit = (2-1) (2-3)] {} ;
%                    \node [fit = (3-1) (3-3)] {} ;
%                    \end{tikzpicture}}]
% a & a + b & a + b + c & L_1\\
% a & a     & a + b     & L_2 \\
% a & a     & a         & L_3
% \end{pNiceArray}\]
%
% \medskip
% The result may seem disappointing. We can improve it by using the ``medium
% nodes'' instead of the ``normal nodes''. 
%
% \begin{Verbatim}
% \begin{tikzpicture}[myoptions, ~emphase#name suffix = -medium@]
% \node [fit = (1-1) (1-3)] {} ;
% \node [fit = (2-1) (2-3)] {} ;
% \node [fit = (3-1) (3-3)] {} ;
% \end{tikzpicture}
% \end{Verbatim}
%
% \medskip
% We obtain the following matrix.
% 
% \[\begin{pNiceArray}{CCC}[
%      last-col,
%      create-extra-nodes,
%      code-after = {\begin{tikzpicture}[every node/.style = {fill = red!15,
%                                                             blend mode = multiply,
%                                                             inner sep = 0pt},
%                                        name suffix = -medium]
%                    \node [fit = (1-1) (1-3)] {} ;
%                    \node [fit = (2-1) (2-3)] {} ;
%                    \node [fit = (3-1) (3-3)] {} ;
%                    \end{tikzpicture}}]
% a & a + b & a + b + c & L_1\\
% a & a     & a + b     & L_2 \\
% a & a     & a         & L_3
% \end{pNiceArray}\]
%
%                           
% \vspace{1cm}
% 
% In the following example, we use the ``large nodes'' to highlight a zone of
% the matrix.\par\nobreak 
% \begin{Verbatim}
% \begin{pNiceArray}{>{\strut}CCCC}%
%    [create-extra-nodes,margin,extra-margin=2pt,
%     code-after = {\tikz \path [~emphase#name suffix = -large@,
%                                fill = red!15, 
%                                blend mode = multiply]
%                         (1-1.north west)
%                      |- (2-2.north west)
%                      |- (3-3.north west)
%                      |- (4-4.north west)
%                      |- (4-4.south east)
%                      |- (1-1.north west) ; } ]
% A_{11} & A_{12} & A_{13} & A_{14} \\
% A_{21} & A_{22} & A_{23} & A_{24} \\
% A_{31} & A_{32} & A_{33} & A_{34} \\
% A_{41} & A_{42} & A_{43} & A_{44}  
% \end{pNiceArray}
% \end{Verbatim}
%                              
% \[ \begin{pNiceArray}{>{\strut}CCCC}[
%     create-extra-nodes,margin,extra-margin=2pt,
%     code-after = {\tikz \path [name suffix = -large,
%                                fill = red!15, 
%                                blend mode = multiply]
%                         (1-1.north west)
%                      |- (2-2.north west)
%                      |- (3-3.north west)
%                      |- (4-4.north west)
%                      |- (4-4.south east)
%                      |- (1-1.north west) ; } ]
% A_{11} & A_{12} & A_{13} & A_{14} \\
% A_{21} & A_{22} & A_{23} & A_{24} \\
% A_{31} & A_{32} & A_{33} & A_{34} \\
% A_{41} & A_{42} & A_{43} & A_{44}  
% \end{pNiceArray}\]
%
% 
% \subsection{Direct utilisation of the Tikz nodes}
%
% In the following example, we illustrate the mathematical product of two
% matrices. 
%
% \medskip
% The utilisation of |{NiceMatrixBlock}| with the option |auto-columns-width|
% gives the same width for all the columns and, therefore, a perfect alignment
% of the two superposed matrices.
% \begin{Verbatim}
% \begin{NiceMatrixBlock}[auto-columns-width]
% \end{Verbatim}
%
% \begin{Verbatim}
% \NiceMatrixOptions{nullify-dots}
% \end{Verbatim}
%
% The three matrices will be displayed using an environment |{array}| (an
% environment |{tabular}| may also be possible).
% \begin{Verbatim}
% $\begin{array}{cc}
% & 
% \end{Verbatim}
%
% The matrix $B$ has a ``first row'' (for $C_j$) and that's why we use the key
% |first-row|. 
% \begin{Verbatim}
% \begin{bNiceArray}{C>{\strut}CCCC}[name=B,first-row]
%       &        & C_j \\
% b_{11} & \Cdots & b_{1j} & \Cdots & b_{1n} \\
% \Vdots &       & \Vdots &       & \Vdots \\
%        &       & b_{kj}  \\
%        &       & \Vdots \\
%  b_{n1}  & \Cdots & b_{nj} & \Cdots & b_{nn} 
% \end{bNiceArray} \\ \\
% \end{Verbatim}
%
% The matrix $A$ has a ``first column'' (for $L_i$) and that's why we use the
% key |first-col|.
% \begin{Verbatim}
% \begin{bNiceArray}{CC>{\strut}CCC}[name=A,first-col]
%     & a_{11} & \Cdots &  &  & a_{nn} \\
%     & \Vdots &       &  &  & \Vdots \\
% L_i & a_{i1} & \Cdots & a_{ik} & \Cdots & a_{in} \\
%     & \Vdots &       &  &  & \Vdots \\
%     & a_{n1} & \Cdots &  &  & a_{nn} \\
% \end{bNiceArray}
% & 
% \end{Verbatim}
%
% In the matrix product, the two dotted lines have an open extremity.
% \begin{Verbatim}
% \begin{bNiceArray}{CC>{\strut}CCC}
%        &         & & & \\
%        &         & \Vdots \\
% \Cdots &         & c_{ij}  \\
% \\
% \\
% \end{bNiceArray} 
% \end{array}$
%
% \end{NiceMatrixBlock}
% \end{Verbatim}
%
% \begin{Verbatim}                             
% \begin{tikzpicture}[remember picture, overlay]
%  \node [highlight, fit = (A-3-1) (A-3-5) ] {} ; 
%  \node [highlight, fit = (B-1-3) (B-5-3) ] {} ; 
%  \draw [color = gray] (A-3-3) to [bend left] (B-3-3) ; 
% \end{tikzpicture}
% \end{Verbatim}
% 
%
% \begin{NiceMatrixBlock}[auto-columns-width]
% \NiceMatrixOptions{nullify-dots}
% $\begin{array}{cc}
% & 
% \begin{bNiceArray}{C>{\strut}CCCC}[name=B,first-row]
%        &        & C_j    \\
% b_{11} & \Cdots & b_{1j} & \Cdots & b_{1n} \\
% \Vdots &        & \Vdots &        & \Vdots \\
%        &        & b_{kj} \\
%        &        & \Vdots \\
% b_{n1} & \Cdots & b_{nj} & \Cdots & b_{nn} 
% \end{bNiceArray} \\ \\
% \begin{bNiceArray}{CC>{\strut}CCC}[name=A,first-col]
%     & a_{11} & \Cdots &        &        & a_{nn} \\
%     & \Vdots &        &        &        & \Vdots \\
% L_i & a_{i1} & \Cdots & a_{ik} & \Cdots & a_{in} \\
%     & \Vdots &        &        &        & \Vdots \\
%     & a_{n1} & \Cdots &        &        & a_{nn} \\
% \end{bNiceArray}
% & 
% \begin{bNiceArray}{CC>{\strut}CCC}
%        &         &        & & \\
%        &         & \Vdots \\
% \Cdots &         & c_{ij} \\
% \\
% \\
% \end{bNiceArray} 
% \end{array}$
%
% \end{NiceMatrixBlock}
%
% \begin{tikzpicture}[remember picture, overlay]
%  \node [highlight, fit = (A-3-1) (A-3-5) ] {} ; 
%  \node [highlight, fit = (B-1-3) (B-5-3) ] {} ; 
%  \draw [color = gray] (A-3-3) to [bend left] (B-3-3) ; 
% \end{tikzpicture}
%
% 
% 
% \section{Implementation}
%
% By default, the package \pkg{nicematrix} doesn't patch any existing code.
%
% \smallskip
% However, when the option |renew-dots| is used, the commands |\cdots|,
% |\ldots|, |\dots|, |\vdots|, |\ddots| and |\iddots| are redefined in the
% environments provided by \pkg{nicematrix} as explained previously. In the same
% way, if the option |renew-matrix| is used, the environment |{matrix}| of
% \pkg{amsmath} is redefined. 
%
% \smallskip
% On the other hand, the environment |{array}| is never redefined.
%
% \smallskip
% Of course, the package \pkg{nicematrix} uses the features of the package
% \pkg{array}. It tries to be independent of its implementation. Unfortunately,
% it was not possible to be strictly independent: the package \pkg{nicematrix}
% relies upon the fact that the package |{array}| uses |\ialign| to begin the
% |\halign|. 
% 
%
% \subsection{Declaration of the package and extensions loaded}
%
% First, \pkg{tikz} and the Tikz library |fit| are loaded before the
% |\ProvidesExplPackage|. They are loaded this way because |\usetikzlibrary| in
% |expl3| code fails.\footnote{cf.
% |tex.stackexchange.com/questions/57424/using-of-usetikzlibrary-in-an-expl3-package-fails|}  
% 
%    \begin{macrocode}
%<@@=nm>
%    \end{macrocode}
%
%    \begin{macrocode}
\RequirePackage{tikz}
\usetikzlibrary{fit}
\RequirePackage{expl3}[2019/07/01]
%    \end{macrocode}
% 
% We give the traditionnal declaration of a package written with |expl3|:
%    \begin{macrocode}
\RequirePackage{l3keys2e}
\ProvidesExplPackage
  {nicematrix}
  {\myfiledate}
  {\myfileversion}
  {Several features to improve the typesetting of mathematical matrices with TikZ}
%    \end{macrocode}
% 
% \bigskip
% We test if the class option |draft| has been used. In this case, we raise the
% flag |\c_@@_draft_bool| because we won't draw the dotted lines if the option
% |draft| is used. 
%    \begin{macrocode}
\bool_new:N \c_@@_draft_bool
\DeclareOption { draft } { \bool_set_true:N \c_@@_draft_bool }
\DeclareOption* { }
\ProcessOptions \relax
%    \end{macrocode}
%
%
% 
% The command for the treatment of the options of |\usepackage| is at the end of
% this package for technical reasons. 
% 
% \bigskip
% We load \pkg{array} and \pkg{amsmath}.
%    \begin{macrocode}
\RequirePackage { array }
\RequirePackage { amsmath }
\RequirePackage { xparse } [ 2018-07-01 ]
%    \end{macrocode}
%
% \bigskip
%    \begin{macrocode}
\cs_new_protected:Npn \@@_error:n { \msg_error:nn { nicematrix } }
\cs_new_protected:Npn \@@_error:nn { \msg_error:nnn { nicematrix } }
\cs_new_protected:Npn \@@_error:nnn { \msg_error:nnnn { nicematrix } }
\cs_new_protected:Npn \@@_fatal:n { \msg_fatal:nn { nicematrix } }
\cs_new_protected:Npn \@@_fatal:nn { \msg_fatal:nn { nicematrix } }
\cs_new_protected:Npn \@@_msg_new:nn { \msg_new:nnn { nicematrix } }
\cs_new_protected:Npn \@@_msg_new:nnn { \msg_new:nnnn { nicematrix } }
%    \end{macrocode}
% 
%    \begin{macrocode}
\cs_new_protected:Npn \@@_msg_redirect_name:nn 
  { \msg_redirect_name:nnn { nicematrix } }
%    \end{macrocode}
%
%
% \subsection{Technical  definitions}
%
% We test whether the current class is \cls{revtex4-1} or \cls{revtex4-2}
% because these classes redefines |\array| (of \pkg{array}) in a way
% incompatible with our programmation.
%    \begin{macrocode}
\bool_new:N \c_@@_revtex_bool
\@ifclassloaded { revtex4-1 }
  { \bool_set_true:N \c_@@_revtex_bool }
  { }
\@ifclassloaded { revtex4-2 }
  { \bool_set_true:N \c_@@_revtex_bool }
  { }
%    \end{macrocode}
%
% 
% The following message must be defined right now because it may be used during
% the loading of the package.
%    \begin{macrocode}
\@@_msg_new:nn { Draft~mode }
  { The~compilation~is~in~draft~mode:~the~dotted~lines~won't~be~drawn. }
%    \end{macrocode}
%
%    \begin{macrocode}
\bool_if:NT \c_@@_draft_bool 
  { \msg_warning:nn { nicematrix }  { Draft~mode } }
%    \end{macrocode}
% 
%
% \bigskip
% We define a command |\iddots| similar to |\ddots| ($\ddots$) but with dots
% going forward ($\iddots$). We use |\ProvideDocumentCommand| of \pkg{xparse},
% and so, if the command |\iddots| has already been defined (for example by the
% package \pkg{mathdots}), we don't define it again. 
% 
%    \begin{macrocode}
\ProvideDocumentCommand \iddots { }
  { 
    \mathinner
      { 
        \mkern 1 mu 
        \raise \p@ \hbox:n { . }
        \mkern 2 mu
        \raise 4 \p@ \hbox:n { . }
        \mkern 2 mu
        \raise 7 \p@ \vbox { \kern 7 pt \hbox:n { . } } \mkern 1 mu 
      } 
  }
%    \end{macrocode}
%
% This definition is a variant of the standard definition of |\ddots|.
%
%
% \bigskip 
% The following counter will count the environments |{NiceArray}|. The value of
% this counter will be used to prefix the names of the Tikz nodes created in the
% array. 
%    \begin{macrocode}
\int_new:N \g_@@_env_int
%    \end{macrocode}
% 
% \bigskip
% We also define a counter to count the environments |{NiceMatrixBlock}|.
%    \begin{macrocode}
\int_new:N \g_@@_NiceMatrixBlock_int
%    \end{macrocode}
%
% \bigskip
% The dimension |\l_@@_columns_width_dim| will be used when the options specify
% that all the columns must have the same width (but, if the key |columns-width|
% is used with the special value |auto|, the boolean
% |l_@@_auto_columns_width_bool| also will be raised).
%    \begin{macrocode}
\dim_new:N \l_@@_columns_width_dim
%    \end{macrocode}
%
% \bigskip
% The sequence |\g_@@_names_seq| will be the list of all the names of
% environments used (via the option |name|) in the document: two environments
% must not have the same name. However, it's possible to use the option
% |allow-duplicate-names|.
%    \begin{macrocode}
\seq_new:N \g_@@_names_seq
%    \end{macrocode}
%

% \bigskip
% We want to know if we are in an environment of \pkg{nicematrix} because we
% will raise an error if the user tries to use nested environments.
%    \begin{macrocode}
\bool_new:N \l_@@_in_env_bool
%    \end{macrocode}
% 
%
% \bigskip
% If the user uses |{NiceArray}| (and not another environment relying upon
% |{NiceArrayWithDelims}| like |{pNiceArray}|), we will raise the flag
% |\l_@@_NiceArray_bool|. We have to know that, because, in |{NiceArray}|, we
% won't use a structure with |\left| and |\right| and we will use the option of
% position (|t|, |b| or |c|). 
%    \begin{macrocode}
\bool_new:N \l_@@_NiceArray_bool
%    \end{macrocode}
% 
%
% \bigskip
%    \begin{macrocode}
\cs_new_protected:Npn \@@_test_if_math_mode:
  { 
    \if_mode_math: \else:
      \@@_fatal:n { Outside~math~mode } 
    \fi:
  }
%    \end{macrocode}
%
% \bigskip
% Consider the following code:
% \begin{Verbatim}
% $\begin{pNiceMatrix}
% a & b & c \\
% d & e & \Vdots \\
% f & \Cdots \\
% g & h & i \\
% \end{pNiceMatrix}$
% \end{Verbatim}
%
% First, the dotted line created by the |\Vdots| will be drawn. The implicit
% cell in position 2-3 will be considered as ``dotted''. Then, we will have to
% draw the dotted line specified by the |\Cdots|; the final extremity of that
% line will be exactly in position 2-3 and, for that new second line, it should
% be considered as a \emph{closed} extremity (since it is dotted). However, we
% don't have the (normal) Tikz node of that node (since it's an implicit cell):
% we can't draw such a line. That's why that dotted line will be said
% \emph{impossible} and an error will be raised.\footnote{Of course, the user
% should solve the problem by adding the lacking ampersands.}
%    \begin{macrocode}
\bool_new:N \l_@@_impossible_line_bool
%    \end{macrocode}
% 
%   
% \bigskip
% We have to know whether \pkg{colortbl} is loaded for the redefinition of
% |\everycr| and for |\vline|.
%    \begin{macrocode}
\bool_new:N \c_@@_colortbl_loaded_bool 
\AtBeginDocument 
  { 
    \@ifpackageloaded { colortbl }
      { 
        \bool_set_true:N \c_@@_colortbl_loaded_bool 
        \cs_set_protected:Npn \@@_vline_i: { { \CT@arc@ \vline } }
      }
      { } 
  }
%    \end{macrocode}
% 
% \bigskip
% The length |\l_@@_inter_dots_dim| is the distance between two dots for the
% dotted lines. The default value is 0.45~em but it will be changed if the
% option |small| is used.
%    \begin{macrocode}
\dim_new:N \l_@@_inter_dots_dim
\dim_set:Nn \l_@@_inter_dots_dim { 0.45 em }
%    \end{macrocode}
% The length |\l_@@_radius_dim| is the radius of the dots for the dotted lines.
% The default value is 0.34~pt but it will be changed if the option |small| is
% used. 
%    \begin{macrocode}
\dim_new:N \l_@@_radius_dim
\dim_set:Nn \l_@@_radius_dim { 0.53 pt }
%    \end{macrocode}
%
% \bigskip
% The name of the current environment (will be used only in the error messages).
%    \begin{macrocode}
\str_new:N \g_@@_type_env_str
%    \end{macrocode}
%
%    \begin{macrocode}
\tl_new:N \g_@@_code_after_tl
%    \end{macrocode}
% 
%
% \bigskip
% The counters |\l_@@_save_iRow_int| and |\l_@@_save_jCol_int| will be used to
% save the values of the eventual LaTeX counters |iRow| and |jCol|. These LaTeX
% counters will be restored at the end of the environment.
%    \begin{macrocode}
\int_new:N \l_@@_save_iRow_int
\int_new:N \l_@@_save_jCol_int
%    \end{macrocode}
%
% The TeX counters |\c@iRow| and |\c@jCol| will be created in the beginning of
% the environment |{NiceArrayWithDelims}| (if they don't exist previously).
% 
% \bigskip
% \subsubsection{Variables for the exterior rows and columns}
%
% The keys for the exterior rows and columns are |first-row|, |first-col|,
% |last-row| and |last-col|. However, internally, these keys are not coded in a
% similar way. 
%
% \bigskip
% \begin{itemize} 
% \item \textbf{First row}\par\nobreak
% The integer |\l_@@_first_row_int| is the number of the first row of the
% array. The default value is $1$, but, if the option |first-row| is used,
% the value will be~$0$. As usual, the global version is for the passage in the
% |\group_insert_after:N|. 
%    \begin{macrocode}
\int_new:N \l_@@_first_row_int
\int_set:Nn \l_@@_first_row_int 1
%    \end{macrocode}
%
% \medskip
% \item \textbf{First column}\par\nobreak
% The integer |\l_@@_first_col_int| is the number of the first column of the
% array. The default value is $1$, but, if the option |first-col| is used, 
% the value will be~$0$. 
%    \begin{macrocode}
\int_new:N \l_@@_first_col_int
\int_set:Nn \l_@@_first_col_int 1
%    \end{macrocode}
% 
% \medskip
% \item \textbf{Last row}\par\nobreak
% The counter |\l_@@_last_row_int| is the number of the eventual ``last row'',
% as specified by the key |last-row|. A value of $-2$ means that there is no
% ``last row''. A value of $-1$ means that there is a ``last row'' but we don't
% know the number of that row (the key |last-row| has been used without value
% and the actual value has not still been read in the |aux| file).
%    \begin{macrocode}
\int_new:N \l_@@_last_row_int 
\int_set:Nn \l_@@_last_row_int { -2 }
%    \end{macrocode}
%
% \smallskip
% If, in an environment like |{pNiceArray}|, the option |last-row| is used
% without value, we will globally raise the following flag. It will be used to
% know if we have, after the construction of the array, to write in the |aux|
% file the number of the ``last row''.\footnote{We can't use
% |\l_@@_last_row_int| for this usage because, if \pkg{nicematrix} has read its
% value from the |aux| file, the value of the counter won't be $-1$ any longer.}
%    \begin{macrocode}
\bool_new:N \l_@@_last_row_without_value_bool
%    \end{macrocode}
%
% \medskip
% \item \textbf{Last column}\par\nobreak
%
% For the eventual ``last column'', we use an integer. A value of $-1$ means
% that there is no last column.
%    \begin{macrocode}
\int_new:N \l_@@_last_col_int
\int_set:Nn \l_@@_last_col_int { -1 }
%    \end{macrocode}
%
% However, we have also a boolean. Consider the following code: 
% \begin{center}
% \begin{BVerbatim}
% \begin{pNiceArray}{CC}[last-col]
% 1 & 2 \\
% 3 & 4
% \end{pNiceArray}
% \end{BVerbatim}
% \end{center}
% In such a code, the ``last column'' specified by the key |last-col| is not
% used. We want to be able to detect such a situation and we create a boolean
% for that job.
%    \begin{macrocode}
\bool_new:N \g_@@_last_col_found_bool
%    \end{macrocode}
% This boolean is set to |false| at the end of |\@@_pre_array:|.
% \end{itemize}
%       
% \bigskip
% \subsubsection{The column S of siunitx}
%
% 
% We want to know whether the package \pkg{siunitx} is loaded and, if it is
% loaded, we redefine the |S| columns of \pkg{siunitx}.
%    \begin{macrocode}
\bool_new:N \c_@@_siunitx_loaded_bool 
\AtBeginDocument 
  { 
    \@ifpackageloaded { siunitx }
      { \bool_set_true:N \c_@@_siunitx_loaded_bool }
      { } 
  }
%    \end{macrocode}
% 
% \medskip
% The command |\NC@rewrite@S| is a LaTeX command created by \pkg{siunitx} in
% connection with the |S| column. In the code of \pkg{siunitx}, this command is
% defined by:
% \begin{Verbatim}[commandchars=\~\!\+, formatcom = \small]
% \renewcommand*{\NC@rewrite@S}[1][]
%   {
%     \@temptokena \exp_after:wN
%       {
%         \tex_the:D \@temptokena
%         > { \__siunitx_table_collect_begin: S {#1} }
%         c
%         < { \__siunitx_table_print: }
%       }
%     \NC@find
%   } 
% \end{Verbatim}
% We want to patch this command (in the environments of \pkg{nicematrix}) in
% order to have:
% \begin{Verbatim}[commandchars=\~\!\+, formatcom = \small]
% \renewcommand*{\NC@rewrite@S}[1][]
%   {
%     \@temptokena \exp_after:wN
%       {
%         \tex_the:D \@temptokena
%         > { ~emphase!\@@_Cell:+ \__siunitx_table_collect_begin: S {#1} }
%         c
%         < { \__siunitx_table_print: ~emphase!\@@_end_Cell:+ }
%       }
%     \NC@find
%   } 
% \end{Verbatim}
% However, we don't want do use explicitly any private command of \pkg{siunitx}.
% That's why we will extract the name of the two |\__siunitx...| commands by
% their position in the code of |\NC@rewrite@S|. 
%
% Since the command |\NC@rewrite@S| appends some tokens to the \emph{toks} list
% |\@temptokena|, we use the LaTeX command |\NC@rewrite@S| in a group
% (|\group_begin:|--|\group_end:|) and we extract the two command names which
% are in the toks |\@temptokena|. However, this extraction can be done only
% when \pkg{siunitx} is loaded (and it may be loaded after \pkg{nicematrix})
% and, in fact, after the beginning of the document --- because some
% instructions of \pkg{siunitx} are executed in a |\AtBeginDocument|). That's
% why this extraction will be done only at the first utilisation of an
% environment of \pkg{nicematrix} with the command |\@@_adapt_S_column:|. 
%    \begin{macrocode}
\cs_set_protected:Npn \@@_adapt_S_column:
  {
%    \end{macrocode}
% In the preamble of the LaTeX document, the boolean |\c_@@_siunitx_loaded_bool|
% won't be known. That's why we test the existence of
% |\c_@@_siunitx_loaded_bool| and not its value.\footnote{Indeed,
% \pkg{nicematrix} may be used in the preamble of the LaTeX document. For
% example, in this document, we compose a matrix in the box |\ExampleOne| before
% loading \pkg{arydshln} (because \pkg{arydshln} is not totally compatible with
% \pkg{nicematrix}).} 
%    \begin{macrocode}   
    \bool_if:NT \c_@@_siunitx_loaded_bool
      { 
        \group_begin:
        \@temptokena = { }
%    \end{macrocode}
% We protect |\NC@find| which is at the end of |\NC@rewrite@S|.
%    \begin{macrocode}
        \cs_set_eq:NN \NC@find \prg_do_nothing:
        \NC@rewrite@S { }
%    \end{macrocode}
% Conversion of the \emph{toks} |\@temptokena| in a token list of \pkg{expl3}
% (the toks are not supported by \pkg{expl3} but we can, nevertheless, use the
% option |V| for |\tl_gset:NV|).
%    \begin{macrocode}
        \tl_gset:NV \g_tmpa_tl \@temptokena 
        \group_end:
        \tl_new:N \c_@@_table_collect_begin_tl
        \tl_set:Nx \l_tmpa_tl { \tl_item:Nn \g_tmpa_tl 2 }
        \tl_gset:Nx \c_@@_table_collect_begin_tl { \tl_item:Nn \l_tmpa_tl 1 }
        \tl_new:N \c_@@_table_print_tl
        \tl_gset:Nx \c_@@_table_print_tl { \tl_item:Nn \g_tmpa_tl { -1 } }
%    \end{macrocode}
% The token lists |\c_@@_table_collect_begin_tl| and |\c_@@_table_print_tl|
% contain now the two commands of \pkg{siunitx}.
% 
% \smallskip
% If the adaptation has been done, the command |\@@_adapt_S_column:| becomes
% no-op (globally). 
%    \begin{macrocode}
        \cs_gset_eq:NN \@@_adapt_S_column: \prg_do_nothing:
      }
  }
%    \end{macrocode}
%
% \bigskip
% The command |\@@_renew_NC@rewrite@S:| will be used in each environment of
% \pkg{nicematrix} in order to ``rewrite'' the |S| column in each environment
% (only if the boolean |\c_@@_siunitx_loaded_bool| is raised, of course).
%    \begin{macrocode}
\cs_new_protected:Npn \@@_renew_NC@rewrite@S:
  {
    \renewcommand*{\NC@rewrite@S}[1][]
      {
        \@temptokena \exp_after:wN
          {
            \tex_the:D \@temptokena
            > { \@@_Cell: \c_@@_table_collect_begin_tl S {##1} }
            c
            < { \c_@@_table_print_tl \@@_end_Cell: }
          }
        \NC@find
      }
  }
%    \end{macrocode}
%                               
%
% \bigskip 
% \subsection{The options}
% 
%
%
% The token list |\l_@@_pos_env_str| will contain one of the three values |t|,
% |c| or |b| and will indicate the position of the environment as in the option
% of the environment |{array}|. For the environment |{pNiceMatrix}|,
% |{pNiceArray}| and their variants, the value will programmatically be fixed to
% |c|. For the environment |{NiceArray}|, however, the three values |t|, |c| and
% |b| are possible.
%    \begin{macrocode}
\str_new:N \l_@@_pos_env_str 
\str_set:Nn \l_@@_pos_env_str c
%    \end{macrocode}
% 
% \bigskip
% The flag |\l_@@_exterior_arraycolsep_bool| corresponds to the option
% |exterior-arraycolsep|. If this option is set, a space equal to |\arraycolsep|
% will be put on both sides of an environment |{NiceArray}| (as it is done in
% |{array}| of \pkg{array}).
%    \begin{macrocode}
\bool_new:N \l_@@_exterior_arraycolsep_bool
%    \end{macrocode}
%
% \bigskip
% The flag |\l_@@_parallelize_diags_bool| controls whether the diagonals are
% parallelized. The initial value is~|true|.
%    \begin{macrocode}
\bool_new:N \l_@@_parallelize_diags_bool
\bool_set_true:N \l_@@_parallelize_diags_bool
%    \end{macrocode}
%
% \bigskip
% The flag |\l_@@_hlines_bool| corresponds to the option |\hlines|.
%    \begin{macrocode}
\bool_new:N \l_@@_hlines_bool
%    \end{macrocode}
% 
% \bigskip
% The flag |\l_@@_nullify_dots_bool| corresponds to the option |nullify-dots|.
% When the flag is down, the instructions like |\vdots| are inserted within a
% |\hphantom| (and so the constructed matrix has exactly the same size as a
% matrix constructed with the classical |{matrix}| and |\ldots|, |\vdots|,
% etc.). 
%    \begin{macrocode}
\bool_new:N \l_@@_nullify_dots_bool
%    \end{macrocode}
%
%
% \bigskip
% The following flag will be used when the current options specify that all the
% columns of the array must have the same width equal to the largest width of a
% cell of the array (except the cells of the potential exterior columns).
%    \begin{macrocode}
\bool_new:N \l_@@_auto_columns_width_bool
%    \end{macrocode}
% 
% 
% \bigskip
% The token list |\l_@@_name_str| will contain the optional name of the
% environment: this name can be used to access to the Tikz nodes created in the
% array from outside the environment.  
%    \begin{macrocode}
\str_new:N \l_@@_name_str
%    \end{macrocode}
%
% \bigskip
% The boolean |\l_@@_extra_nodes_bool| will be used to indicate whether the
% ``medium nodes'' and ``large nodes'' are created in the array. 
%    \begin{macrocode}
\bool_new:N \l_@@_extra_nodes_bool
\bool_new:N \g_@@_extra_nodes_bool
%    \end{macrocode}
%
% \bigskip
% The dimensions |\l_@@_left_margin_dim| and |\l_@@_right_margin_dim| correspond
% to the options |left-margin| and |right-margin|. 
%    \begin{macrocode}
\dim_new:N \l_@@_left_margin_dim
\dim_new:N \l_@@_right_margin_dim
\dim_new:N \g_@@_width_last_col_dim
\dim_new:N \g_@@_width_first_col_dim
%    \end{macrocode}
%                              
% \bigskip
% The dimensions |\l_@@_extra_left_margin_dim| and
% |\l_@@_extra_right_margin_dim| correspond to the options |extra-left-margin|
% and |extra-right-margin|.  
%    \begin{macrocode}
\dim_new:N \l_@@_extra_left_margin_dim
\dim_new:N \l_@@_extra_right_margin_dim
%    \end{macrocode}
% 
%
%
% \bigskip
% First, we define a set of keys ``|NiceMatrix / Global|'' which will be used
% (with the mechanism of |.inherit:n|) by other sets of keys.
%    \begin{macrocode}
\keys_define:nn { NiceMatrix / Global }
  {
    code-for-first-col .tl_set:N = \l_@@_code_for_first_col_tl ,
    code-for-first-col .value_required:n = true ,
    code-for-last-col .tl_set:N = \l_@@_code_for_last_col_tl ,
    code-for-last-col .value_required:n = true ,
    code-for-first-row .tl_set:N = \l_@@_code_for_first_row_tl ,
    code-for-first-row .value_required:n = true ,
    code-for-last-row .tl_set:N = \l_@@_code_for_last_row_tl ,
    code-for-last-row .value_required:n = true ,
    small .bool_set:N = \l_@@_small_bool ,
    hlines .bool_set:N = \l_@@_hlines_bool ,
    parallelize-diags .bool_set:N = \l_@@_parallelize_diags_bool ,
%    \end{macrocode}
%
% \bigskip
% With the option |renew-dots|, the command |\cdots|, |\ldots|, |\vdots| and
% |\ddots| are redefined and behave like the commands |\Cdots|, |\Ldots|,
% |\Vdots| and |\Ddots|. 
%    \begin{macrocode}
    renew-dots .bool_set:N = \l_@@_renew_dots_bool ,
    renew-dots .value_forbidden:n = true ,
    nullify-dots .bool_set:N = \l_@@_nullify_dots_bool ,
%    \end{macrocode}
%
% \bigskip
% An option to test whether the extra nodes will be created (these nodes are the
% ``medium nodes'' and the ``large nodes''). In some circonstancies, the extra
% nodes are created automatically, for example when a dotted line has an
% ``open'' extremity.
%    \begin{macrocode}
    create-extra-nodes .bool_set:N = \l_@@_extra_nodes_bool ,
    left-margin .dim_set:N = \l_@@_left_margin_dim ,
    left-margin .default:n = \arraycolsep ,
    right-margin .dim_set:N = \l_@@_right_margin_dim ,
    right-margin .default:n = \arraycolsep ,
    margin .meta:n = { left-margin = #1 , right-margin = #1 } ,
    margin .default:n = \arraycolsep ,
    extra-left-margin .dim_set:N = \l_@@_extra_left_margin_dim ,
    extra-right-margin .dim_set:N = \l_@@_extra_right_margin_dim ,
    extra-margin .meta:n = 
     { extra-left-margin = #1 , extra-right-margin = #1 } ,
  }
%    \end{macrocode}
%
% \bigskip
% We define a set of keys used by the environments of \pkg{nicematrix} (but not
% by the command |\NiceMatrixOptions|). 
%    \begin{macrocode}
\keys_define:nn { NiceMatrix / Env }
  {
    columns-width .code:n = 
      \str_if_eq:nnTF { #1 } { auto }
        { \bool_set_true:N \l_@@_auto_columns_width_bool }
        { \dim_set:Nn \l_@@_columns_width_dim { #1 } } , 
    columns-width .value_required:n = true ,
    name .code:n = 
      \unless \ifmeasuring@
          \str_set:Nn \l_tmpa_str { #1 }
          \seq_if_in:NVTF \g_@@_names_seq \l_tmpa_str
             { \@@_error:nn { Duplicate~name } { #1 } }
             { \seq_gput_left:NV \g_@@_names_seq \l_tmpa_str }
          \str_set_eq:NN \l_@@_name_str \l_tmpa_str 
      \fi ,
    name .value_required:n = true ,
    code-after .tl_gset:N = \g_@@_code_after_tl ,
    code-after .value_required:n = true ,
    first-col .code:n = \int_zero:N \l_@@_first_col_int , 
    first-row .code:n = \int_zero:N \l_@@_first_row_int ,
    last-row .int_set:N = \l_@@_last_row_int ,
    last-row .default:n = -1 ,
  }
%    \end{macrocode}
% 
% \bigskip
% We begin the construction of the major sets of keys (used by the different
% user commands and environments). 
%    \begin{macrocode}
\keys_define:nn { NiceMatrix }
  { 
    NiceMatrixOptions .inherit:n = 
      {  
        NiceMatrix / Global ,
      } ,
    NiceMatrix .inherit:n = 
      { 
        NiceMatrix / Global ,
        NiceMatrix / Env 
      } ,
    NiceArray .inherit:n = 
      { 
        NiceMatrix / Global ,
        NiceMatrix / Env ,
      } ,
    pNiceArray .inherit:n = 
      { 
        NiceMatrix / Global ,
        NiceMatrix / Env ,
      } 
  }
%    \end{macrocode}
% 
%
% \bigskip
% We finalise the definition of the set of keys 
% ``|NiceMatrix / NiceMatrixOptions|'' with the options specific to
% |\NiceMatrixOptions|.    
%    \begin{macrocode}
\keys_define:nn { NiceMatrix / NiceMatrixOptions }
  { 
%    \end{macrocode}
%                              
% With the option |renew-matrix|, the environment |{matrix}| of \pkg{amsmath}
% and its variants are redefined to behave like the environment |{NiceMatrix}|
% and its variants. 
%    \begin{macrocode}
    renew-matrix .code:n = \@@_renew_matrix: ,
    renew-matrix .value_forbidden:n = true ,
    RenewMatrix .code:n = \@@_error:n { Option~RenewMatrix~suppressed } 
                          \@@_renew_matrix: ,
    transparent .meta:n = { renew-dots , renew-matrix } ,
    transparent .value_forbidden:n = true,
    Transparent .code:n = \@@_error:n { Option~Transparent~suppressed } 
                          \@@_renew_matrix:
                          \bool_set_true:N \l_@@_renew_dots_bool ,
%    \end{macrocode}
%                              
%
% \bigskip
% The option |exterior-arraycolsep| will have effect only in |{NiceArray}| for
% those who want to have for |{NiceArray}| the same behaviour as |{array}|.
%    \begin{macrocode}
    exterior-arraycolsep .bool_set:N = \l_@@_exterior_arraycolsep_bool ,
%    \end{macrocode}
%
% \bigskip
% If the option |columns-width| is used, all the columns will have the same
% width.  
%
% In |\NiceMatrixOptions|, the special value |auto| is not available.
%    \begin{macrocode}
    columns-width .code:n = 
      \str_if_eq:nnTF { #1 } { auto }
        { \@@_error:n { Option~auto~for~columns-width } }
        { \dim_set:Nn \l_@@_columns_width_dim { #1 } } ,
%    \end{macrocode}
%
% \bigskip
% Usually, an error is raised when the user tries to give the same to name two
% distincts environments of \pkg{nicematrix} (theses names are global and not
% local to the current TeX scope). However, the option |allow-duplicate-names|
% disables this feature. 
%    \begin{macrocode}
    allow-duplicate-names .code:n = 
      \@@_msg_redirect_name:nn { Duplicate~name } { none } ,
    allow-duplicate-names .value_forbidden:n = true ,
%    \end{macrocode}
%
% \bigskip
% By default, the specifier used in the preamble of the array (for example in
% |{pNiceArray}|) to draw a vertical dotted line between two columns is the
% colon ``|:|''. However, it's possible to change this letter with
% |letter-for-dotted-lines| and, by the way, the letter ``|:|'' will remain free
% for other packages (for example \pkg{arydshln}).
%    \begin{macrocode}
    letter-for-dotted-lines .code:n = 
      {
        \int_compare:nTF { \tl_count:n { #1 } = \c_one_int }
          { \str_set:Nx \l_@@_letter_for_dotted_lines_str { #1 } }
          { \@@_error:n { Bad~value~for~letter~for~dotted~lines } } 
      } ,
    letter-for-dotted-lines .value_required:n = true ,
%    \end{macrocode}
%
% \bigskip
%    \begin{macrocode}
    unknown .code:n  = \@@_error:n { Unknown~key~for~NiceMatrixOptions } 
  }
%    \end{macrocode}
%
%    \begin{macrocode}
\str_new:N \l_@@_letter_for_dotted_lines_str
\str_set_eq:NN \l_@@_letter_for_dotted_lines_str \c_colon_str
%    \end{macrocode}
%       
% \bigskip
% |\NiceMatrixOptions| is the command of the \pkg{nicematrix} package to fix
% options at the document level. The scope of these specifications is the
% current TeX group. 
%    \begin{macrocode}
\NewDocumentCommand \NiceMatrixOptions { m }
  { \keys_set:nn { NiceMatrix / NiceMatrixOptions } { #1 } }
%    \end{macrocode}
%
%
% \bigskip
% We finalise the definition of the set of keys 
% ``|NiceMatrix / NiceMatrix|'' with the options specific to |{NiceMatrix}|.
%
%    \begin{macrocode}
\keys_define:nn { NiceMatrix / NiceMatrix }
  { 
    last-col .code:n = \tl_if_empty:nTF {#1}
                         { \@@_error:n { last-col~empty~for~NiceMatrix } }
                         { \int_set:Nn \l_@@_last_col_int { #1 } } ,
    unknown .code:n = \@@_error:n { Unknown~option~for~NiceMatrix } 
  }
%    \end{macrocode}
%
%
% 
% \bigskip
% We finalise the definition of the set of keys ``|NiceMatrix / NiceArray|''
% with the options specific to |{NiceArray}|. 
%
%    \begin{macrocode}
\keys_define:nn { NiceMatrix / NiceArray }
  {
%    \end{macrocode}
% 
% \bigskip
% The options |c|, |t| and |b| of the environment |{NiceArray}| have the same
% meaning as the option of the classical environment |{array}|.
%    \begin{macrocode}
    c .code:n = \str_set:Nn \l_@@_pos_env_str c ,
    t .code:n = \str_set:Nn \l_@@_pos_env_str t ,
    b .code:n = \str_set:Nn \l_@@_pos_env_str b ,
%    \end{macrocode}
% 
% In the environments |{NiceArray}| and its variants, the option |last-col| must
% be used without value because the number of columns of the array can be read
% in the preamble of the array.
%    \begin{macrocode}
    last-col .code:n = \tl_if_empty:nF {#1}
                         { \@@_error:n { last-col~non~empty~for~NiceArray } } 
                       \int_zero:N \l_@@_last_col_int ,
    unknown .code:n = \@@_error:n { Unknown~option~for~NiceArray } 
  }
%    \end{macrocode}
%
%
%    
%    \begin{macrocode}
\keys_define:nn { NiceMatrix / pNiceArray }
  { 
    first-col .code:n = \int_zero:N \l_@@_first_col_int , 
    last-col .code:n = \tl_if_empty:nF {#1}
                         { \@@_error:n { last-col~non~empty~for~NiceArray } } 
                       \int_zero:N \l_@@_last_col_int ,
    first-row .code:n = \int_zero:N \l_@@_first_row_int ,
    last-row .int_set:N = \l_@@_last_row_int ,
    last-row .default:n = -1 ,
    unknown .code:n = \@@_error:n { Unknown~option~for~NiceMatrix } 
  }
%    \end{macrocode}
%
%
% \subsection{Important code used by \{NiceArrayWithDelims\} }
%
% The pseudo-environment |\@@_Cell:|--|\@@_end_Cell:| will be used to format the
% cells of the array. In the code, the affectations are global because this
% pseudo-environment will be used in the cells of a |\halign| (via an
% environment |{array}|). 
%
%    \begin{macrocode}
\cs_new_protected:Nn \@@_Cell:
  { 
%    \end{macrocode}
% We increment |\c@jCol|, which is the counter of the columns. 
%    \begin{macrocode}
    \int_gincr:N \c@jCol
%    \end{macrocode}
% Now, we increment the counter of the rows. We don't do this incrementation in
% the |\everycr| because some packages, like \pkg{arydshln}, create special rows
% in the |\halign| that we don't want to take into account. 
%    \begin{macrocode}
    \int_compare:nNnT \c@jCol = \c_one_int
      { 
        \int_compare:nNnT \l_@@_first_col_int = \c_one_int
          \@@_begin_of_row: 
      }
    \int_gset:Nn \g_@@_col_total_int 
      { \int_max:nn \g_@@_col_total_int \c@jCol }
%    \end{macrocode}
% The content of the cell is composed in the box |\l_tmpa_box| because we want
% to compute some dimensions of the box. The |\hbox_set_end:| corresponding to
% this |\hbox_set:Nw| will be in the |\@@_end_Cell:| (and the
% |\c_math_toggle_token| also).
%    \begin{macrocode}
    \hbox_set:Nw \l_tmpa_box 
    \c_math_toggle_token
    \bool_if:NT \l_@@_small_bool \scriptstyle 
%    \end{macrocode}
% 
% We will call \emph{corners} of the matrix the cases which are at the
% intersection of the exterior rows and exterior columns (of course, the four
% corners doesn't always exist simultaneously). In a corner of the matrix, it
% would be logical to use none of the codes |\l_@@_code_for_first_row_tl| and
% \emph{al}. As for now, this result is acheived only for the north-west corner
% (this allows an automatic numerotation of the rows ans the columns with |iRow|
% and |jCol| with the first col and the first row --- probably the preferential
% choice for such a numerotation).
%    \begin{macrocode}
    \int_compare:nNnTF \c@iRow = \c_zero_int 
      { \int_compare:nNnT \c@jCol > \c_zero_int \l_@@_code_for_first_row_tl }
      {
        \int_compare:nNnT \c@iRow = \l_@@_last_row_int
          \l_@@_code_for_last_row_tl 
      }
  }
%    \end{macrocode}
%
% \interitem
% The following macro |\@@_begin_of_row| is usually used in the cell
% number~$1$ of the array. However, when the key |first-col| is used,
% |\@@_begin_of_row| is executed in the cell number~$0$ of the array.
%    \begin{macrocode}
\cs_new_protected:Nn \@@_begin_of_row:
  {
    \int_gincr:N \c@iRow 
    \dim_gset_eq:NN \g_@@_dp_ante_last_row_dim \g_@@_dp_last_row_dim 
    \dim_gzero:N \g_@@_dp_last_row_dim 
    \dim_gzero:N \g_@@_ht_last_row_dim 
  }
%    \end{macrocode}
% 
%
% \interitem
% The following code is used in each cell of the array. It actualises quantities
% that, at the end of the array, will give informations about the vertical
% dimension of the two first rows and the two last rows.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_actualization_for_first_and_last_row:
  {
    \int_compare:nNnT \c@iRow = \c_zero_int
      { 
        \dim_gset:Nn \g_@@_dp_row_zero_dim
          { \dim_max:nn \g_@@_dp_row_zero_dim { \box_dp:N \l_tmpa_box } }
        \dim_gset:Nn \g_@@_ht_row_zero_dim
          { \dim_max:nn \g_@@_ht_row_zero_dim { \box_ht:N \l_tmpa_box } } 
      }
    \int_compare:nNnT \c@iRow = \c_one_int
      { 
        \dim_gset:Nn \g_@@_ht_row_one_dim
          { \dim_max:nn \g_@@_ht_row_one_dim { \box_ht:N \l_tmpa_box } } 
      }
    \dim_gset:Nn \g_@@_ht_last_row_dim
      { \dim_max:nn \g_@@_ht_last_row_dim { \box_ht:N \l_tmpa_box } } 
    \dim_gset:Nn \g_@@_dp_last_row_dim
      { \dim_max:nn \g_@@_dp_last_row_dim { \box_dp:N \l_tmpa_box } } 
  }
%    \end{macrocode}
%
%    \begin{macrocode}
\cs_new_protected:Nn \@@_end_Cell:
  { 
    \c_math_toggle_token 
    \hbox_set_end:
%    \end{macrocode}
%
% We want to compute in |\g_@@_max_cell_width_dim| the width of the widest cell
% of the array (except the cells of the ``first column'' and the ``last
% column''). 
% 
%    \begin{macrocode}
    \dim_gset:Nn \g_@@_max_cell_width_dim
      { \dim_max:nn \g_@@_max_cell_width_dim { \box_wd:N \l_tmpa_box } }
%    \end{macrocode}
%
% The following computations are for the ``first row'' and the ``last row''.
%    \begin{macrocode}
    \@@_actualization_for_first_and_last_row:
%    \end{macrocode}
% 
% Now, we can create the Tikz node of the cell.
%    \begin{macrocode}
    \tikz 
      [ 
        remember~picture , 
        inner~sep = \c_zero_dim , 
        minimum~width = \c_zero_dim , 
        baseline 
      ]
    \node 
      [
        anchor = base ,
        name = nm - \int_use:N \g_@@_env_int -
                    \int_use:N \c@iRow -
                    \int_use:N \c@jCol ,
        alias = 
          \str_if_empty:NF \l_@@_name_str
            { 
              \l_@@_name_str -
              \int_use:N \c@iRow -
              \int_use:N \c@jCol
            } 
      ] 
    \bgroup 
    \box_use:N \l_tmpa_box
    \egroup ;
  } 
%    \end{macrocode}
%
% 
%    \begin{macrocode}
\cs_generate_variant:Nn \dim_set:Nn { N x }
%    \end{macrocode}
% 
% \bigskip
% In the environment |{NiceArrayWithDelims}|, we will have to redefine the
% column types |w| and |W|. These definitions are rather long because we have to
% construct the |w|-nodes in these columns. The redefinition of these two column
% types are very close and that's why we use a macro |\@@_renewcolumntype:nn|.
% The first argument is the type of the column (|w| or |W|) and the second
% argument is a code inserted at a special place and which is the only
% difference between the two definitions.
%    \begin{macrocode}
\cs_new_protected:Nn \@@_renewcolumntype:nn
  {
    \newcolumntype #1 [ 2 ]
      { 
        > { 
            \hbox_set:Nw \l_tmpa_box
            \@@_Cell:
          }
        c
        < { 
            \@@_end_Cell:
            \hbox_set_end:
            #2 
            \hbox_set:Nn \l_tmpb_box 
              { \makebox [ ##2 ] [ ##1 ] { \box_use:N \l_tmpa_box } }
            \dim_set:Nn \l_tmpa_dim { \box_dp:N \l_tmpb_box }
            \box_move_down:nn \l_tmpa_dim 
              { 
                \vbox:n
                  { 
                    \hbox_to_wd:nn { \box_wd:N \l_tmpb_box }
                      { 
                        \hfil 
                        \tikz [ remember~picture , overlay ]
                        \coordinate (@@~north~east) ; 
                      }
                    \hbox:n
                      {
                        \tikz [ remember~picture , overlay ]
                        \coordinate (@@~south~west) ;
                        \box_move_up:nn \l_tmpa_dim { \box_use:N \l_tmpb_box }
                      }         
                  }
              }
%    \end{macrocode}
% The |w|-node is created using the Tikz library |fit| after construction of the
% nodes |(@@~south~west)| and |(@@~north~east)|. It's not possible to construct
% by a standard |node| instruction because such a construction give an erroneous
% result with some engines (|XeTeX|, |LuaTeX|) although the result is good with
% |pdflatex| (why?). 
%    \begin{macrocode}
            \tikz [ remember~picture , overlay ]
            \node 
              [
                node~contents = { } ,
                name = nm - \int_use:N \g_@@_env_int -
                            \int_use:N \c@iRow -
                            \int_use:N \c@jCol - w,
                alias = 
                  \str_if_empty:NF \l_@@_name_str
                    { 
                      \l_@@_name_str -
                      \int_use:N \c@iRow -
                      \int_use:N \c@jCol - w 
                    } ,
                inner~sep = \c_zero_dim ,
                fit = (@@~south~west) (@@~north~east)
              ] 
            ;
          }  
      }
  }
%    \end{macrocode}
% 
% 
% \interitem
% The argument of the following command |\@@_instruction_of_type:n| defined
% below is the type of the instruction (|Cdots|, |Vdots|, |Ddots|, etc.). This
% command writes in the corresponding |\g_@@_|\textsl{type}|_lines_tl| the
% instruction which will really draw the line after the construction of the
% matrix. 
%
% \medskip
% For example, for the following matrix,
% 
% \smallskip
% \begin{BVerbatim}[baseline=c,boxwidth=11cm]
% \begin{pNiceMatrix}
% 1 & 2 & 3 & 4 \\
% 5 & \Cdots & & 6 \\
% 7 & \Cdots \\
% \end{pNiceMatrix}
% \end{BVerbatim}
% $\begin{pNiceMatrix}
% 1 & 2 & 3 & 4 \\
% 5 & \Cdots & & 6 \\
% 7 & \Cdots \\
% \end{pNiceMatrix}$
%
% \smallskip
% the content of |\g_@@_Cdots_lines_tl| will be:
% 
% \smallskip
% \begin{scope}
% \color{gray}
% \verb|\@@_draw_Cdots:nn {2}{2}|
%
% \verb|\@@_draw_Cdots:nn {3}{2}|
% \end{scope} 
% 
%
% We begin with a test of the flag |\c_@@_draft_bool| because, if the key
% |draft| is used, the dotted lines are not drawn.
%    \begin{macrocode}
\bool_if:NTF \c_@@_draft_bool
  { \cs_set_protected:Npn \@@_instruction_of_type:n #1 { } }
  {
    \cs_new_protected:Npn \@@_instruction_of_type:n #1
      { 
%    \end{macrocode}
% It's important to use a |\tl_gput_right:cx| and not a |\tl_gput_left:cx|
% because we want the |\Ddots| lines to be drawn in the order of appearance
% in the array (for parallelisation).
%    \begin{macrocode}
        \tl_gput_right:cx 
          { g_@@_ #1 _ lines _ tl }
          { 
            \use:c { @@ _ draw _ #1 : nn } 
              { \int_use:N \c@iRow } 
              { \int_use:N \c@jCol }
          }
      }  
  }
%    \end{macrocode}
%
%  
% \bigskip
% We want to use |\array| of \pkg{array}. However, if the class used is
% \cls{revtex4-1} or \cls{revtex4-2}, we have to do some tuning and use the
% command |\@array@array| instead of |\array| because these classes do a
% redefinition of |\array| incompatible with our use of |\array|. 
%
%    \begin{macrocode}
\cs_new_protected:Npn \@@_array:
  {
    \bool_if:NTF \c_@@_revtex_bool
      { 
        \cs_set_eq:NN \@acoll \@arrayacol 
        \cs_set_eq:NN \@acolr \@arrayacol 
        \cs_set_eq:NN \@acol \@arrayacol 
        \cs_set:Npn \@halignto { }
        \@array@array
      }
      \array
%    \end{macrocode}
% |\l_@@_pos_env_str| may have the value |t|, |c| or |b|.
%    \begin{macrocode}
    [ \l_@@_pos_env_str ]
  }
%    \end{macrocode}
%
%
% 
% \bigskip
% The following must \emph{not} be protected because it begins with |\noalign|. 
%    \begin{macrocode}
\cs_new:Npn \@@_everycr:
  { \noalign { \@@_everycr_i: } }
%    \end{macrocode}
%
%    \begin{macrocode}
\cs_new_protected:Npn \@@_everycr_i:
  { 
    \int_gzero:N \c@jCol 
    \bool_if:NT \l_@@_hlines_bool
      {
%    \end{macrocode}
% The counter |\c@iRow| has the value $-1$ only if there is a ``first
% row'' and that we are before that ``first row'', i.e. just before the
% beginning of the array. 
%    \begin{macrocode}
        \int_compare:nNnT \c@iRow > { -1 }
          {
            \int_compare:nNnF \c@iRow = \l_@@_last_row_int  
              { 
                \hrule \@height \arrayrulewidth
                \skip_vertical:n { - \arrayrulewidth }
              }
          } 
      }
  }
%    \end{macrocode}
% 
% \bigskip
% The following code |\@@_pre_array:| is used in |{NiceArrayWithDelims}|. It
% exists as a standalone macro only for lisibility.
% \label{prearray}
%
%   \begin{macrocode}
\cs_new_protected:Npn \@@_pre_array:
  {
    \cs_if_exist:NT \theiRow
      { \int_set_eq:NN \l_@@_save_iRow_int \c@iRow }
    \int_gzero_new:N \c@iRow
    \cs_if_exist:NT \thejCol
      { \int_set_eq:NN \l_@@_save_jCol_int \c@jCol }
    \int_gzero_new:N \c@jCol
    \normalbaselines
%    \end{macrocode}
% If the option |small| is used, we have to do some tuning. In particular, we
% change the value of |\arraystretch| (this parameter is used in the
% construction of |\@arstrutbox| in the beginning of |{array}|).
%    \begin{macrocode}
    \bool_if:NT \l_@@_small_bool
      {
%    \end{macrocode}
%    \begin{macrocode}
        \cs_set:Npn \arraystretch { 0.47 }
        \dim_set:Nn \arraycolsep { 1.45 pt }
      }
%    \end{macrocode}
%
% 
% \medskip
% We switch to a global version of the boolean |\g_@@_extra_nodes_bool|,
% because, in some circonstancies, the boolean will be raised from inside a
% cell of the |\halign| (in particular in a column of type~|w|).
% 
%    \begin{macrocode}
    \bool_gset_eq:NN \g_@@_extra_nodes_bool \l_@@_extra_nodes_bool
%    \end{macrocode}
%
% \bigskip
% The environment |{array}| uses internally the command |\ialign|. We change the
% definition of |\ialign| for several reasons. In particular, |\ialign| sets
% |\everycr| to |{ }| and we \emph{need} to have to change the value of
% |\everycr|. 
%    \begin{macrocode}
    \cs_set:Npn \ialign 
      { 
        \bool_if:NTF \c_@@_colortbl_loaded_bool
          {
            \CT@everycr 
              { 
                \noalign { \cs_gset_eq:NN \CT@row@color \prg_do_nothing: }
                \@@_everycr:
              }
          }
          { \everycr { \@@_everycr: } }
        \tabskip = \c_zero_skip
%    \end{macrocode}
%
% The box |\@arstrutbox| is a box constructed in the beginning of the
% environment |{array}|. The construction of that box takes into account the
% current values of |\arraystretch|\footnote{The option |small| of
% \pkg{nicematrix} changes (among other) the value of |\arraystretch|. This is
% done, of course, before the call of |{array}|.} and |\extrarowheight| (of
% \pkg{array}). That box is inserted (via |\@arstrut|) in the beginning of each
% row of the array. That's why we use the dimensions of that box to initialize
% the variables which will be the dimensions of the potential first and last row
% of the environment. This initialization must be done after the creation of
% |\@arstrutbox| and that's why we do it in the |\ialign|.
%    \begin{macrocode}
        \dim_gzero_new:N \g_@@_dp_row_zero_dim
        \dim_gset:Nn \g_@@_dp_row_zero_dim { \box_dp:N \@arstrutbox }
        \dim_gzero_new:N \g_@@_ht_row_zero_dim
        \dim_gset:Nn \g_@@_ht_row_zero_dim { \box_ht:N \@arstrutbox }
        \dim_gzero_new:N \g_@@_ht_row_one_dim
        \dim_gset:Nn \g_@@_ht_row_one_dim { \box_ht:N \@arstrutbox }
        \dim_gzero_new:N \g_@@_dp_ante_last_row_dim
        \dim_gset:Nn \g_@@_dp_ante_last_row_dim { \box_dp:N \@arstrutbox }
        \dim_gzero_new:N \g_@@_ht_last_row_dim
        \dim_gset:Nn \g_@@_ht_last_row_dim { \box_ht:N \@arstrutbox }
        \dim_gzero_new:N \g_@@_dp_last_row_dim
        \dim_gset:Nn \g_@@_dp_last_row_dim { \box_dp:N \@arstrutbox }
%    \end{macrocode}
% After its first utilisation, the definition of |\ialign| will revert
% automatically to its default definition. With this programmation, we will
% have, in the cells of the array, a clean version of |\ialign|.\footnote{The
% user will probably not employ directly |\ialign| in the array...  but more
% likely environments that utilize |\ialign| internally (e.g.: |{substack}|).}
%    \begin{macrocode}
        \cs_set:Npn \ialign 
           { 
             \everycr { } 
             \tabskip = \c_zero_skip
             \halign
           }
        \halign 
      }
%    \end{macrocode}
%                                                   
% We define the new column types |L|, |C| and |R| that must be used instead of
% |l|, |c| and |r| in the preamble of |{NiceArray}|.
%    \begin{macrocode}
    \newcolumntype L { > \@@_Cell: l < \@@_end_Cell: }
    \newcolumntype C { > \@@_Cell: c < \@@_end_Cell: }
    \newcolumntype R { > \@@_Cell: r < \@@_end_Cell: }
%    \end{macrocode}    
%
%    \begin{macrocode}
    \cs_set_eq:NN \Ldots \@@_Ldots
    \cs_set_eq:NN \Cdots \@@_Cdots
    \cs_set_eq:NN \Vdots \@@_Vdots
    \cs_set_eq:NN \Ddots \@@_Ddots
    \cs_set_eq:NN \Iddots \@@_Iddots
    \cs_set_eq:NN \hdottedline \@@_hdottedline:
    \cs_set_eq:NN \Hspace \@@_Hspace:
    \cs_set_eq:NN \Hdotsfor \@@_Hdotsfor:
    \cs_set_eq:NN \multicolumn \@@_multicolumn:nnn
    \cs_set_eq:NN \Block \@@_Block:
    \bool_if:NT \l_@@_renew_dots_bool
      { 
        \cs_set_eq:NN \ldots \@@_Ldots
        \cs_set_eq:NN \cdots \@@_Cdots
        \cs_set_eq:NN \vdots \@@_Vdots
        \cs_set_eq:NN \ddots \@@_Ddots
        \cs_set_eq:NN \iddots \@@_Iddots
        \cs_set_eq:NN \dots \@@_Ldots
        \cs_set_eq:NN \hdotsfor \@@_Hdotsfor:
      }
%    \end{macrocode}
% 
%
% The sequence |\g_@@_multicolumn_cells_seq| will contain the list of the cells
% of the array where a command |\multicolumn{|$n$|}{...}{...}| with $n>1$ is
% issued. In |\g_@@_multicolumn_sizes_seq|, the ``sizes'' (that is to say the
% values of $n$) correspondant will be stored. These lists will be used for the
% creation of the ``medium nodes'' (if they are created). 
%    \begin{macrocode}
    \seq_gclear_new:N \g_@@_multicolumn_cells_seq
    \seq_gclear_new:N \g_@@_multicolumn_sizes_seq
%    \end{macrocode}
% 
%
% The counter |\c@iRow| will be used to count the rows of the array (its
% incrementation will be in the first cell of the row). 
%    \begin{macrocode}
    \int_gset:Nn \c@iRow { \l_@@_first_row_int - 1 }
%    \end{macrocode}
%
% At the end of the environment |{array}|, |\c@iRow| will be the total
% number de rows and |\g_@@_row_total_int| will be the number or rows excepted
% the last row (if |\l_@@_last_row_bool| has been raised with the option
% |last-row|). 
%    \begin{macrocode}
    \int_gzero_new:N \g_@@_row_total_int
%    \end{macrocode}
%
% The counter |\c@jCol| will be used to count the columns of the array.
% Since we want to know the total number of columns of the matrix, we also
% create a counter |\g_@@_col_total_int|. These counters are updated in the
% command |\@@_Cell:| executed at the beginning of each cell.  
%    \begin{macrocode}
    \int_gzero_new:N \g_@@_col_total_int
%    \end{macrocode}
%
%    \begin{macrocode}
    \cs_set_eq:NN \@ifnextchar \new@ifnextchar
%    \end{macrocode}
%
% We nullify the definitions of the column types |w| and |W| before their
% redefinition because we want to avoid a warning in the log file for a
% redefinition of a column type. We must put |\relax| and not
% |\prg_do_nothing:|.
%    \begin{macrocode}
    \cs_set_eq:NN \NC@find@w \relax
    \cs_set_eq:NN \NC@find@W \relax
    \@@_renewcolumntype:nn w { }
    \@@_renewcolumntype:nn W { \cs_set_eq:NN \hss \hfil }
%    \end{macrocode}
%                               
% \bigskip
% By default, the letter used to specify a dotted line in the preamble of an
% environment of \pkg{nicematrix} (for example in |{pNiceArray}|) is the letter
% |:|. However, this letter is used by some extensions, for example
% \pkg{arydshln}. That's why it's possible to change the letter used by
% \pkg{nicematrix} with the option |letter-for-dotted-lines| which changes the
% value of |\l_@@_letter_for_dotted_lines_str|. We rescan this string (which is
% always of length~1) in particular for the case where |pdflatex| is used with
% \pkg{french-babel} (the colon is activated by \pkg{french-babel} at the
% beginning of the document).
%    \begin{macrocode}
    \tl_set_rescan:Nno  
      \l_@@_letter_for_dotted_lines_str { } \l_@@_letter_for_dotted_lines_str  
    \exp_args:NV \newcolumntype \l_@@_letter_for_dotted_lines_str
      {
        !
          {
            \skip_horizontal:n { 0.53 pt }
%    \end{macrocode}
% If the array is an array with all the columns of the same width, we don't ask
% for the creation of the extra nodes because we will use the ``|col|'' nodes
% for the vertical dotted line.
%    \begin{macrocode}
            \bool_if:nF
              { 
                \l_@@_auto_columns_width_bool 
                || \dim_compare_p:nNn \l_@@_columns_width_dim > \c_zero_dim
              }
              { \bool_gset_true:N \g_@@_extra_nodes_bool }
%    \end{macrocode}
%
% \medskip
% Consider the following code:
% \begin{center}
% \begin{BVerbatim}
% \begin{NiceArray}{C:CC:C}
% a & b
% c & d \\
% e & f & g & h \\
% i & j & k & l 
% \end{NiceArray}
% \end{BVerbatim}
% \end{center}
% The first ``|:|'' in the preamble will be encountered during the first row of
% the environment |{NiceArray}| but the second one will be encountered only in
% the third row. We have to issue a command |\vdottedline:n| in the |code-after|
% only one time for each ``|:|'' in the preamble. That's why we keep a counter
% |\g_@@_last_vdotted_col_int| and with this counter, we know whether a letter
% ``|:|'' encountered during the parsing has already been taken into account in
% the |code-after|.
%    \begin{macrocode}
            \int_compare:nNnT \c@jCol > \g_@@_last_vdotted_col_int
              {
                \int_gset_eq:NN \g_@@_last_vdotted_col_int \c@jCol
                \tl_gput_right:Nx \g_@@_code_after_tl
%    \end{macrocode}
% The command |\@@_vdottedline:n| is protected, and, therefore, won't be
% expanded before writing on |\g_@@_code_after_tl|.
%    \begin{macrocode}
                  { \@@_vdottedline:n { \int_use:N \c@jCol } }
              }
          }
      }
    \int_gzero_new:N \g_@@_last_vdotted_col_int
    \bool_if:NT \c_@@_siunitx_loaded_bool \@@_renew_NC@rewrite@S:
    \int_gset:Nn \g_@@_last_vdotted_col_int { -1 }
    \bool_gset_false:N \g_@@_last_col_found_bool 
%    \end{macrocode}
%
% \medskip
% During the construction of the array, the instructions |\Cdots|, |\Ldots|,
% etc. will be written in token lists |\g_@@_Cdots_lines_tl|, etc. which will be
% executed after the construction of the array. 
%    \begin{macrocode}
    \tl_gclear_new:N \g_@@_Cdots_lines_tl
    \tl_gclear_new:N \g_@@_Ldots_lines_tl
    \tl_gclear_new:N \g_@@_Vdots_lines_tl
    \tl_gclear_new:N \g_@@_Ddots_lines_tl
    \tl_gclear_new:N \g_@@_Iddots_lines_tl
    \tl_gclear_new:N \g_@@_Hdotsfor_lines_tl
 }
%    \end{macrocode}
% 
% \bigskip
% \subsection{The environment \{NiceArrayWithDelims\}}
%
%    \begin{macrocode}
\NewDocumentEnvironment { NiceArrayWithDelims } { m m O { } m ! O { } }
  { 
    \str_if_empty:NT \g_@@_type_env_str 
      { \str_gset:Nn \g_@@_type_env_str { NiceArrayWithDelims } }
    \@@_adapt_S_column:
    \@@_test_if_math_mode:
    \bool_if:NT \l_@@_in_env_bool { \@@_fatal:n { Yet~in~env } } 
    \bool_set_true:N \l_@@_in_env_bool
%    \end{macrocode}
%
% We deactivate Tikz externalization (since we use Tikz pictures with the
% options |overlay| and |remember picture|, there would be errors).
%    \begin{macrocode}
    \cs_if_exist:NT \tikz@library@external@loaded
      {
        \tikzset { external / export = false }
        \cs_if_exist:NT \ifstandalone
          { \tikzset { external / optimize = false } }
      }
%    \end{macrocode}
%
% We increment the counter |\g_@@_env_int| which counts the environments
% of the extension.
%    \begin{macrocode}
    \int_gincr:N \g_@@_env_int
    \bool_if:NF \l_@@_block_auto_columns_width_bool
      { \dim_gzero_new:N \g_@@_max_cell_width_dim }
%    \end{macrocode}
%
% We do a redefinition of |\@arrayrule| because we want that the vertical rules
% drawn by "|" in the preamble of the array don't extend in the potential
% exterior rows.
%    \begin{macrocode}
    \cs_set_protected:Npn \@arrayrule { \@addtopreamble \@@_vline: }
%    \end{macrocode}
% 
%
% The set of keys is not exactly the same for |{NiceArray}| and for the variants
% of |{NiceArray}| (|{pNiceArray}|, |{bNiceArray}|, etc.) because, for
% |{NiceArray}|, we have the options |t|, |c| and |b|.
%    \begin{macrocode}
    \bool_if:NTF \l_@@_NiceArray_bool 
      { \keys_set:nn { NiceMatrix / NiceArray } }
      { \keys_set:nn { NiceMatrix / pNiceArray } }
    { #3 , #5 } 
%    \end{macrocode}
%
% A value of $-1$ for the counter |\l_@@_last_row_int| means that the user has
% used the option |last-row| without value, that is to say without specifying
% the number of that last row. In this case, we try to read that value from the
% |aux| file (if it has been written on a previous run). 
%
%    \begin{macrocode}
    \int_compare:nNnT \l_@@_last_row_int = { -1 }
      {
        \bool_set_true:N \l_@@_last_row_without_value_bool
%    \end{macrocode}
% A value based on the name is more reliable than a value based on the number of
% the environment.
%    \begin{macrocode}
        \str_if_empty:NTF \l_@@_name_str
          {
            \cs_if_exist:cT { @@_last_row_ \int_use:N \g_@@_env_int } 
              { 
                \int_set:Nn \l_@@_last_row_int 
                  { \use:c { @@_last_row_ \int_use:N \g_@@_env_int } }
              }  
          }
          {
            \cs_if_exist:cT { @@_last_row_ \l_@@_name_str } 
              { 
                \int_set:Nn \l_@@_last_row_int 
                  { \use:c { @@_last_row_ \l_@@_name_str } }
              }  
          }
      }
%    \end{macrocode}
%
% The code in |\@@_pre_array:| is common to |{NiceArrayWithDelims}| and
% |{NiceMatrix}|. 
%    \begin{macrocode}
    \@@_pre_array:
%    \end{macrocode}
%
% \medskip
% We compute the width of the two delimiters.
%    \begin{macrocode}
    \dim_gzero_new:N \g_@@_left_delim_dim
    \dim_gzero_new:N \g_@@_right_delim_dim
    \bool_if:NTF \l_@@_NiceArray_bool
      {
        \dim_gset:Nn \g_@@_left_delim_dim { 2 \arraycolsep }
        \dim_gset:Nn \g_@@_right_delim_dim { 2 \arraycolsep }
      }
      { 
        \group_begin:
        \dim_set_eq:NN \nulldelimiterspace \c_zero_dim
        \hbox_set:Nn \l_tmpa_box
          {
            \c_math_toggle_token
            \left #1 \vcenter to 3 cm { } \right.
            \c_math_toggle_token

          }
        \dim_gset:Nn \g_@@_left_delim_dim { \box_wd:N \l_tmpa_box }
        \hbox_set:Nn \l_tmpa_box
          {
            \dim_set_eq:NN \nulldelimiterspace \c_zero_dim
            \c_math_toggle_token
            \left. \vcenter to 3 cm { } \right #2
            \c_math_toggle_token
          }
        \dim_gset:Nn \g_@@_right_delim_dim { \box_wd:N \l_tmpa_box }
        \group_end:
      }
%    \end{macrocode}
% 
% \medskip
% The array will be composed in a box (named |\l_@@_the_array_box|) because we
% have to do manipulations concerning the potential exterior rows.
%    \begin{macrocode}
    \box_clear_new:N \l_@@_the_array_box
%    \end{macrocode}
%
% \medskip
% We construct the preamble of the array in |\l_tmpa_tl|.
%    \begin{macrocode}
    \tl_set:Nn \l_tmpa_tl { #4 }
    \int_compare:nNnTF \l_@@_first_col_int = \c_zero_int
      { \tl_put_left:NV \l_tmpa_tl \c_@@_preamble_first_col_tl }
      {
        \bool_if:NT \l_@@_NiceArray_bool
          {
            \bool_if:NF \l_@@_exterior_arraycolsep_bool
              { \tl_put_left:Nn \l_tmpa_tl { @ { } } }
          }
      }
    \int_compare:nNnTF \l_@@_last_col_int > { -1 }
      { \tl_put_right:NV \l_tmpa_tl \c_@@_preamble_last_col_tl }
      { 
        \bool_if:NT \l_@@_NiceArray_bool
          {
            \bool_if:NF \l_@@_exterior_arraycolsep_bool
              { \tl_put_right:Nn \l_tmpa_tl { @ { } } }
          }
      }
%    \end{macrocode}
% Here is the beginning of the box which will contain the array. The
% |\hbox_set_end:| corresponding to this |\hbox_set:Nw| will be in the second
% part of the environment (and the closing |\c_math_toggle_token| also).
%    \begin{macrocode}
    \hbox_set:Nw \l_@@_the_array_box
    \skip_horizontal:n \l_@@_left_margin_dim 
    \skip_horizontal:n \l_@@_extra_left_margin_dim 
    \c_math_toggle_token
%    \end{macrocode}
% Here is the call to |\array| (we have a dedicated macro |\@@_array:| because
% of compatibility with the classes \cls{revtex4-1} and \cls{revtex4-2}).
%    \begin{macrocode}
    \exp_args:NV \@@_array: \l_tmpa_tl
  }
%    \end{macrocode}
%
% \bigskip
% We begin the second part of the environment |{NiceArrayWithDelims}|. If all
% the columns must have the same width (if the user has used the option
% |columns-width| or the option |auto-column-width| of the environment
% |{NiceMatrixBlock}|), we add a row in the array to fix the width of the
% columns and construct the ``|col|'' nodes |nm-|\textsl{a}|-col-|\textsl{j}
% (these nodes will be used by the horizontal open dotted lines and by the
% commands |\@@_vdottedline:n|).
% 
%    \begin{macrocode}
  { 
    \bool_if:nT
      {
        \l_@@_auto_columns_width_bool 
        || \dim_compare_p:nNn \l_@@_columns_width_dim > \c_zero_dim
      }
      {
        \crcr
        \int_compare:nNnT \l_@@_first_col_int = 0 { \omit & }
        \omit
%    \end{macrocode}
% First, we put a ``|col|'' node on the left of the first column (of course, we
% have to do that \emph{after} the |\omit|).
%    \begin{macrocode}
        \skip_horizontal:N \arraycolsep
        \tikz [ remember~picture , overlay ]
          \coordinate [ name = nm - \int_use:N \g_@@_env_int - col - 0 ] ;
        \skip_horizontal:n { - \arraycolsep }
%    \end{macrocode}
% We compute in |\g_tmpa_dim| the common width of the columns. We use a global
% variable because we are in a cell of an |\halign| and because we have to use this
% variable in other cells (of the same row). The affectation of |\g_tmpa_dim|,
% like all the affectations, must be done after the |\omit| of the cell.
%    \begin{macrocode}
        \bool_if:nTF 
          { 
            \l_@@_auto_columns_width_bool 
            && ! \l_@@_block_auto_columns_width_bool 
          }
          { 
            \dim_gset:Nn \g_tmpa_dim
              { \g_@@_max_cell_width_dim + 2 \arraycolsep } 
          }
          { 
            \dim_gset:Nn \g_tmpa_dim
              { \l_@@_columns_width_dim + 2 \arraycolsep } 
          }
        \skip_horizontal:N \g_tmpa_dim
        \tikz [ remember~picture , overlay ]
          \coordinate [ name = nm - \int_use:N \g_@@_env_int - col - 1 ] ;
%    \end{macrocode}
% We begin a loop over the columns. The integer |\g_tmpa_int| will be the
% number of the current column. This integer is not used to fix the
% width of the column (since all the columns have the same width equal to
% |\g_@@_tmpa_dim|) but for the Tikz nodes.
%    \begin{macrocode}
        \int_gset:Nn \g_tmpa_int 1            
        \bool_if:nTF \g_@@_last_col_found_bool 
          { \prg_replicate:nn { \g_@@_col_total_int - 3 } }
          { \prg_replicate:nn { \g_@@_col_total_int - 2 } }
          { 
             & 
             \omit
%    \end{macrocode}
% The incrementation of the counter |\g_tmpa_int| must be done after the |\omit|
% of the cell.
%    \begin{macrocode}
             \int_gincr:N \g_tmpa_int 
             \skip_horizontal:N \g_tmpa_dim
%    \end{macrocode}
% We create a ``|col|'' node on the right of the current column.
%    \begin{macrocode}
             \tikz [ remember~picture , overlay ]
               \coordinate             
                 [
                   name = nm - \int_use:N \g_@@_env_int -
                          col - \int_use:N \g_tmpa_int
                 ] ; 
          }
%    \end{macrocode}
% For the last column, we want a special treatment because of the final
% |\arraycolsep|. 
%    \begin{macrocode}
        & 
        \omit
        \int_gincr:N \g_tmpa_int 
        \skip_horizontal:N \g_tmpa_dim
        \skip_horizontal:n { - \arraycolsep }
        \tikz [ remember~picture , overlay ]
          \coordinate             
            [
              name = nm - \int_use:N \g_@@_env_int -
                     col - \int_use:N \g_tmpa_int
            ] ; 
        \skip_horizontal:N \arraycolsep
      }
    \endarray
    \c_math_toggle_token
    \skip_horizontal:n \l_@@_right_margin_dim 
    \skip_horizontal:n \l_@@_extra_right_margin_dim 
    \hbox_set_end:
%    \end{macrocode}
%
% \bigskip
%
%    \begin{macrocode}
    \int_compare:nNnT \l_@@_last_row_int > { -2 }
      {
        \bool_if:NF \l_@@_last_row_without_value_bool
          {
            \int_compare:nNnF \l_@@_last_row_int = \c@iRow
              { 
                \@@_error:n { Wrong~last~row } 
                \int_gset_eq:NN \l_@@_last_row_int \c@iRow
              }
          } 
      }
%    \end{macrocode}
%
%
% Now, we compute |\l_tmpa_dim| which is the vertical dimension of the ``first
% row'' above the array (when the key |first-row| is used).
%    \begin{macrocode}
    \int_compare:nNnTF \l_@@_first_row_int = \c_zero_int
      { 
        \dim_set:Nn \l_tmpa_dim 
          { \g_@@_dp_row_zero_dim + \lineskip + \g_@@_ht_row_zero_dim }
      }
      { \dim_zero:N \l_tmpa_dim }
%    \end{macrocode}
% We compute |\l_tmpb_dim| which is the vertical dimension of the ``last row''
% below the array (when the key |last-row| is used). A value of $-2$ for
% |\l_@@_last_row_int| means that there is no ``last row''.\footnote{A value of
% $-1$ for |\l_@@_last_row_int| means that there is a ``last row'' but the
% number of that row is unknown (the user have not set the value with the option
% |last row|).} 
%    \begin{macrocode}
    \int_compare:nNnTF \l_@@_last_row_int > { -2 }
      {
        \dim_set:Nn \l_tmpb_dim
          { \g_@@_ht_last_row_dim + \lineskip + \g_@@_dp_last_row_dim }
      }
      { \dim_zero:N \l_tmpb_dim }
%    \end{macrocode}
% 
% \bigskip
% Now, we begin the real construction in the output flow of TeX. First, we take
% into account a potential ``first column'' (we remind that this ``first
% column'' has been constructed in an overlapping position and that we have
% computed its width in |\g_@@_width_first_col_dim|: see
% p.~\pageref{overlap-left}). 
%    \begin{macrocode}
    \int_compare:nNnT \l_@@_first_col_int = \c_zero_int
      { 
        \skip_horizontal:n \arraycolsep
        \skip_horizontal:n \g_@@_width_first_col_dim 
      }
%    \end{macrocode}
%
% The construction of the real box is different in |{NiceArray}| and in its
% variants (|{pNiceArray}|, etc.) because, in |{NiceArray}|, we have to take
% into account the option of position (|t|, |c| or |b|). We begin with
% |{NiceArray}|. 
%    \begin{macrocode}
    \bool_if:NTF \l_@@_NiceArray_bool
      { 
        \int_compare:nNnT \l_@@_first_row_int = \c_zero_int
          { 
            \str_if_eq:VnTF \l_@@_pos_env_str { t }
              {
                \box_move_up:nn 
                  { \l_tmpa_dim - \g_@@_ht_row_zero_dim + \g_@@_ht_row_one_dim }
              }
          }
          {
            \int_compare:nNnT \l_@@_last_row_int > 0
              {
                \str_if_eq:VnT \l_@@_pos_env_str { b }
                  {
                    \box_move_down:nn
                      { 
                        \l_tmpb_dim 
                        - \g_@@_dp_last_row_dim + \g_@@_dp_ante_last_row_dim 
                      } 
                  }
              }
          }
        { \box_use_drop:N \l_@@_the_array_box }
      } 
%    \end{macrocode}
%
% Now, in the case of an environment |{pNiceArray}|, |{bNiceArray}|, etc.
%    \begin{macrocode}
      {
        \hbox_set:Nn \l_tmpa_box
          {
            \c_math_toggle_token
            \left #1
            \vcenter 
              { 
%    \end{macrocode}
% We take into account the ``first row'' (we have previously computed its size
% in |\l_tmpa_dim|).
%    \begin{macrocode}
                \skip_vertical:n { - \l_tmpa_dim }
                \hbox:n 
                  { 
                    \skip_horizontal:n { - \arraycolsep }
                    \box_use_drop:N \l_@@_the_array_box
                    \skip_horizontal:n { - \arraycolsep }
                  }
%    \end{macrocode}
% We take into account the ``last row'' (we have previously computed its size
% in |\l_tmpb_dim|).
%    \begin{macrocode}
                \skip_vertical:n { - \l_tmpb_dim }
              }
            \right #2 
            \c_math_toggle_token
          }
        \box_set_ht:Nn \l_tmpa_box { \box_ht:N \l_tmpa_box + \l_tmpa_dim }
        \box_set_dp:Nn \l_tmpa_box { \box_dp:N \l_tmpa_box + \l_tmpb_dim } 
        \box_use_drop:N \l_tmpa_box
      } 
%    \end{macrocode}
% We take into account a potential ``last column'' (this ``last
% column'' has been constructed in an overlapping position and we have computed
% its width in |\g_@@_width_last_col_dim|: see p.~\pageref{overlap-right}).
%    \begin{macrocode}           
    \bool_if:NT \g_@@_last_col_found_bool 
      { 
        \skip_horizontal:n \g_@@_width_last_col_dim 
        \skip_horizontal:n \arraycolsep 
      }
    \@@_after_array:
  }
%    \end{macrocode}
% This is the end of the environment |{NiceArrayWithDelims}|.
%
% 
% \interitem
% Here is the preamble for the ``first column'' (if the user uses the key
% |first-col|) 
%    \begin{macrocode}
\tl_const:Nn \c_@@_preamble_first_col_tl
  {
    > 
      { 
        \@@_begin_of_row:
%    \end{macrocode}
% The contents of the cell is constructed in the box |\l_tmpa_box| because we
% have to compute some dimensions of this box.
%    \begin{macrocode}
        \hbox_set:Nw \l_tmpa_box 
        \c_math_toggle_token
        \bool_if:NT \l_@@_small_bool \scriptstyle
        \int_compare:nNnT \c@iRow > \c_zero_int \l_@@_code_for_first_col_tl
      }
    l
    < 
      { 
        \c_math_toggle_token
        \hbox_set_end:
        \@@_actualization_for_first_and_last_row:
%    \end{macrocode}
% We actualise the width of the ``first column'' because we will use this width
% after the construction of the array.
%    \begin{macrocode}
        \dim_gset:Nn \g_@@_width_first_col_dim
          { 
            \dim_max:nn 
              \g_@@_width_first_col_dim
              { \box_wd:N \l_tmpa_box }
          }
%    \end{macrocode}
% The content of the cell is inserted in an overlapping position.
% \label{overlap-left}
%    \begin{macrocode}
        \hbox_overlap_left:n
          { 
            \tikz 
              [ 
                remember~picture , 
                inner~sep = \c_zero_dim , 
                minimum~width = \c_zero_dim , 
                baseline
              ]
            \node 
              [ 
                anchor = base ,
                name = 
                  nm -
                  \int_use:N \g_@@_env_int -
                  \int_use:N \c@iRow -
                  0 ,
                alias = 
                  \str_if_empty:NF \l_@@_name_str
                    { 
                      \l_@@_name_str -
                      \int_use:N \c@iRow -
                      0
                    }
              ]
              { \box_use:N \l_tmpa_box } ; 
            \skip_horizontal:n
              { 
                \g_@@_left_delim_dim + 
                \l_@@_left_margin_dim + 
                \l_@@_extra_left_margin_dim
              }
          }
        \skip_horizontal:n { - 2 \arraycolsep } 
      }
  }
%    \end{macrocode}
%
%
% Here is the preamble for the ``last column'' (if the user uses the key
% |last-col|).
%    \begin{macrocode}
\tl_const:Nn \c_@@_preamble_last_col_tl
  {
    > 
      { 
%    \end{macrocode}
% With the flag |\g_@@_last_col_found_bool|, we will know that the ``last
% column'' is really used.
%    \begin{macrocode}           
        \bool_gset_true:N \g_@@_last_col_found_bool
        \int_gincr:N \c@jCol
        \int_gset:Nn \g_@@_col_total_int
          { \int_max:nn \g_@@_col_total_int \c@jCol }
%    \end{macrocode}
% The contents of the cell is constructed in the box |\l_tmpa_box| because we
% have to compute some dimensions of this box.
%    \begin{macrocode}
        \hbox_set:Nw \l_tmpa_box 
          \c_math_toggle_token
          \bool_if:NT \l_@@_small_bool \scriptstyle 
          \l_@@_code_for_last_col_tl
      }
    l
    < 
      { 
        \c_math_toggle_token
        \hbox_set_end:
        \@@_actualization_for_first_and_last_row:
%    \end{macrocode}
% We actualise the width of the ``last column'' because we will use this width
% after the construction of the array.
%    \begin{macrocode}
        \dim_gset:Nn \g_@@_width_last_col_dim
           { 
             \dim_max:nn 
               \g_@@_width_last_col_dim
               { \box_wd:N \l_tmpa_box }
           }
        \skip_horizontal:n { - 2 \arraycolsep }
%    \end{macrocode}
% The content of the cell is inserted in an overlapping position.
% \label{overlap-right}
%    \begin{macrocode}
        \hbox_overlap_right:n
          { 
            \skip_horizontal:n
              { 
                \g_@@_right_delim_dim + 
                \l_@@_right_margin_dim + 
                \l_@@_extra_right_margin_dim
              }
            \tikz 
              [ 
                remember~picture , 
                inner~sep = \c_zero_dim , 
                minimum~width = \c_zero_dim , 
                baseline
              ]
            \node 
              [ 
                anchor = base ,
                name = 
                  nm -
                  \int_use:N \g_@@_env_int -
                  \int_use:N \c@iRow -
                  \int_use:N \c@jCol ,
                alias = 
                  \str_if_empty:NF \l_@@_name_str
                    { 
                      \l_@@_name_str -
                      \int_use:N \c@iRow -
                      \int_use:N \c@jCol
                    }
              ]
              { \box_use:N \l_tmpa_box } ; 
          } 
      }
  }
%    \end{macrocode}
%
%
% \interitem
% The environment |{NiceArray}| is constructed upon the environment
% |{NiceArrayWithDelims}| but, in fact, there is a flag |\l_@@_NiceArray_bool|.
% In |{NiceArrayWithDelims}|, some special code will be executed if this flag is
% raised. 
%    \begin{macrocode}
\NewDocumentEnvironment { NiceArray } { }
  { 
    \bool_set_true:N \l_@@_NiceArray_bool
    \str_if_empty:NT \g_@@_type_env_str 
      { \str_gset:Nn \g_@@_type_env_str { NiceArray } }
%    \end{macrocode}
% We put . and . for the delimiters but, in fact, that doesn't matter because
% these arguments won't be used in |{NiceArrayWithDelims}| (because the flag
% |\l_@@_NiceArray_bool| is raised).
%    \begin{macrocode} 
    \NiceArrayWithDelims . . 
  }
  { \endNiceArrayWithDelims }
%    \end{macrocode}
%               
% 
% \interitem
% We create the variants of the environment |{NiceArrayWithDelims}|. These
% variants exist since the version 3.0 of \pkg{nicematrix}.
%
%   \begin{macrocode}
\NewDocumentEnvironment { pNiceArray } { }
  {
    \str_if_empty:NT \g_@@_type_env_str 
      { \str_gset:Nn \g_@@_type_env_str { pNiceArray } }
    \@@_test_if_math_mode:
    \NiceArrayWithDelims ( )
  }
  { \endNiceArrayWithDelims }
%    \end{macrocode}
%               
%   \begin{macrocode}
\NewDocumentEnvironment { bNiceArray } { }
  {
    \str_if_empty:NT \g_@@_type_env_str 
      { \str_gset:Nn \g_@@_type_env_str { NiceArray } }
    \@@_test_if_math_mode:
    \NiceArrayWithDelims [ ]
  }
  { \endNiceArrayWithDelims }
%    \end{macrocode}
%               
%   \begin{macrocode}
\NewDocumentEnvironment { BNiceArray } { }
  {
    \str_if_empty:NT \g_@@_type_env_str 
      { \str_gset:Nn \g_@@_type_env_str { BNiceArray } }
    \@@_test_if_math_mode:
    \NiceArrayWithDelims \{ \}
  }
  { \endNiceArrayWithDelims }
%    \end{macrocode}
%               
%   \begin{macrocode}
\NewDocumentEnvironment { vNiceArray } { }
  {
    \str_if_empty:NT \g_@@_type_env_str 
      { \str_gset:Nn \g_@@_type_env_str { vNiceArray } }
    \@@_test_if_math_mode:
    \NiceArrayWithDelims | |
  }
  { \endNiceArrayWithDelims }
%    \end{macrocode}
%               
%   \begin{macrocode}
\NewDocumentEnvironment { VNiceArray } { }
  {
    \str_if_empty:NT \g_@@_type_env_str 
      { \str_gset:Nn \g_@@_type_env_str { VNiceArray } }
    \@@_test_if_math_mode:
    \NiceArrayWithDelims \| \|
  }
  { \endNiceArrayWithDelims }
%    \end{macrocode}
%
% \bigskip
% \subsection{The environment \{NiceMatrix\} and its variants}
%
%    \begin{macrocode}
\cs_new_protected:Npn \@@_define_env:n #1
  {
    \NewDocumentEnvironment { #1 NiceMatrix } { ! O { } }
      {
        \str_gset:Nn \g_@@_type_env_str { #1 NiceMatrix } 
        \keys_set:nn { NiceMatrix / NiceMatrix } { ##1 }
        \begin { #1 NiceArray } 
          { 
            * 
              { 
                \int_compare:nNnTF \l_@@_last_col_int = { -1 }  
                  \c@MaxMatrixCols
                  { \int_eval:n { \l_@@_last_col_int - 1 } }
              } 
              C 
          } 
      }
      { \end { #1 NiceArray } }
  }
%    \end{macrocode}
%
%    \begin{macrocode}
\@@_define_env:n { }
\@@_define_env:n p 
\@@_define_env:n b 
\@@_define_env:n B
\@@_define_env:n v
\@@_define_env:n V
%    \end{macrocode}
%
% 
% \bigskip
% \subsection{How to know whether a cell is ``empty''}
%
% The conditionnal |\@@_if_not_empty_cell:nnT| tests whether a cell is empty.
% The first two arguments must be LaTeX3 counters for the row and the column of
% the considered cell. 
%    \begin{macrocode}
\prg_set_conditional:Npnn \@@_if_not_empty_cell:nn #1 #2 { T , TF }
  { 
%    \end{macrocode}
% First, we want to test whether the cell is in the virtual sequence of
% ``non-empty'' cells. There are several important remarks:
% \begin{itemize}
% \item we don't use a |expl3| sequence for efficiency;
% \item the ``non-empty'' cells in this sequence are not, in fact, all the
% non-empty cells of the array: on the contrary they are only cells declared
% as non-empty for a special reason (as of now, there are only cells which are
% on a dotted line which is already drawn or which will be drawn ``just
% after''); 
% \item the flag |\l_tmpa_bool| will be raised when the cell is actually on
% this virtual sequence.
% \end{itemize}
%    \begin{macrocode}
    \bool_set_false:N \l_tmpa_bool
    \cs_if_exist:cTF
      { @@ _ dotted _ \int_use:N #1 - \int_use:N #2 }
      \prg_return_true:
      { 
%    \end{macrocode}
% We know that the cell is not in the virtual sequence of the ``non-empty''
% cells. Now, we test wether the cell is a ``virtual cell'', that is to say a
% cell after the |\\| of the line of the array. It's easy to known whether a
% cell is vitual: the cell is virtual if, and only if, the corresponding Tikz
% node doesn't exist.
%    \begin{macrocode}
        \cs_if_free:cTF 
          { 
            pgf@sh@ns@nm - 
            \int_use:N \g_@@_env_int - 
            \int_use:N #1 - 
            \int_use:N #2 
          } 
          { \prg_return_false: }
          {
%    \end{macrocode}
% Now, we want to test whether the cell is in the virtual sequence of
% ``empty'' cells. There are several important remarks:
% \begin{itemize}
% \item we don't use a |expl3| sequence for efficiency ;
% \item the ``empty'' cells in this sequence are not, in fact, all the
% non-empty cells of the array: on the contrary they are only cells declared
% as non-empty for a special reason ;
% \item the flag |\l_tmpa_bool| will be raised when the cell is actually on
% this virtual sequence.
% \end{itemize}
%    \begin{macrocode}
            \bool_set_false:N \l_tmpa_bool
            \cs_if_exist:cT
              { @@ _ empty _ \int_use:N #1 - \int_use:N #2 }
              { 
                \int_compare:nNnT
                  { \use:c { @@ _ empty _ \int_use:N #1 - \int_use:N #2 } }
                  = 
                  \g_@@_env_int
                { \bool_set_true:N \l_tmpa_bool }
              } 
            \bool_if:NTF \l_tmpa_bool
              \prg_return_false:
%    \end{macrocode}
% In the general case, we consider the width of the Tikz node corresponding to
% the cell. In order to compute this width, we have to extract the coordinate of
% the west and east anchors of the node. This extraction needs a command
% environment |{pgfpicture}| but, in fact, nothing is drawn.  
%    \begin{macrocode}
              { 
                \begin { pgfpicture }
%    \end{macrocode}
% We store the name of the node corresponding to the cell in |\l_tmpa_tl|.
%    \begin{macrocode}
                \tl_set:Nx \l_tmpa_tl 
                   { 
                     nm - 
                     \int_use:N \g_@@_env_int - 
                     \int_use:N #1 - 
                     \int_use:N #2 
                   } 
                \pgfpointanchor \l_tmpa_tl { east }
                \dim_gset:Nn \g_tmpa_dim \pgf@x
                \pgfpointanchor \l_tmpa_tl { west }
                \dim_gset:Nn \g_tmpb_dim \pgf@x
                \end { pgfpicture } 
                \dim_compare:nNnTF 
                  { \dim_abs:n { \g_tmpb_dim - \g_tmpa_dim } } < { 0.5 pt }
                  \prg_return_false:
                  \prg_return_true:
              }
          }
      }
  }
%    \end{macrocode}
%
% 
% \subsection{After the construction of the array}
%
%
%    \begin{macrocode}
\cs_new_protected:Nn \@@_after_array:
  { 
    \int_compare:nNnTF \c@iRow > \c_zero_int
      \@@_after_array_i:
      { 
        \@@_error:n { Zero~row } 
        \@@_restore_iRow_jCol:
      }
  }
%    \end{macrocode}
%
%
% \medskip
% We deactivate Tikz externalization (since we use Tikz pictures with the
% options |overlay| and |remember picture|, there would be errors).
%    \begin{macrocode}
\cs_new_protected:Nn \@@_after_array_i:
  { 
    \group_begin:
    \cs_if_exist:NT \tikz@library@external@loaded
      { \tikzset { external / export = false } } 
%    \end{macrocode}
% Now, the definition of |\c@jCol| and
% |\g_@@_col_total_int| change: |\c@jCol| will be the number of
% columns without the ``last column''; |\g_@@_col_total_int| will be the
% number of columns with this ``last column''.\footnote{We remind that the
% potential ``first column'' has the number~$0$.}
%    \begin{macrocode}
    \int_gset_eq:NN \c@jCol \g_@@_col_total_int
    \bool_if:nT \g_@@_last_col_found_bool { \int_gdecr:N \c@jCol } 
%    \end{macrocode}
%
% We fix also the value of |\c@iRow| and |\g_@@_row_total_int| with the
% same principle.
%    \begin{macrocode}
    \int_gset_eq:NN \g_@@_row_total_int \c@iRow
    \int_compare:nNnT \l_@@_last_row_int > { -1 }
      { \int_gsub:Nn \c@iRow \c_one_int }
%    \end{macrocode}
%
% In the user has used the option |last-row| without value, we write in the
% |aux| file the number of that last row for the next run.
%    \begin{macrocode}
    \bool_if:NT \l_@@_last_row_without_value_bool
      {
        \iow_now:Nn \@mainaux \ExplSyntaxOn 
        \iow_now:Nx \@mainaux 
          { 
            \cs_gset:cpn { @@_last_row_ \int_use:N \g_@@_env_int } 
              { \int_use:N \g_@@_row_total_int }
          }  
%    \end{macrocode}
% If the environment has a name, we also write a value based on the name
% because it's more reliable than a value based on the number of the
% environment. 
%    \begin{macrocode}
        \str_if_empty:NF \l_@@_name_str
          { 
            \iow_now:Nx \@mainaux 
              { 
                \cs_gset:cpn { @@_last_row_ \l_@@_name_str } 
                  { \int_use:N \g_@@_row_total_int }
              }  
          }
        \iow_now:Nn \@mainaux \ExplSyntaxOff 
      }
%    \end{macrocode}
% 
%
% By default, the diagonal lines will be parallelized\footnote{It's possible to
% use the option |parallelize-diags| to disable this parallelization.}. There
% are two types of diagonals lines: the $|\Ddots|$ diagonals and the |\Iddots|
% diagonals. We have to count both types in order to know whether a diagonal is
% the first of its type in the current |{NiceArray}| environment.
%    \begin{macrocode}
    \bool_if:NT \l_@@_parallelize_diags_bool
      { 
        \int_zero_new:N \l_@@_ddots_int
        \int_zero_new:N \l_@@_iddots_int
%    \end{macrocode}
%
% The dimensions |\l_@@_delta_x_one_dim| and |\l_@@_delta_y_one_dim| will
% contain the $\Delta_x$ and $\Delta_y$ of the first |\Ddots| diagonal. We have
% to store these values in order to draw the others |\Ddots| diagonals parallel
% to the first one. Similarly |\l_@@_delta_x_two_dim| and
% |\l_@@_delta_y_two_dim| are the $\Delta_x$ and $\Delta_y$ of the first
% |\Iddots| diagonal. 
%    \begin{macrocode}
        \dim_zero_new:N \l_@@_delta_x_one_dim
        \dim_zero_new:N \l_@@_delta_y_one_dim
        \dim_zero_new:N \l_@@_delta_x_two_dim
        \dim_zero_new:N \l_@@_delta_y_two_dim
      }
%    \end{macrocode}
%
% If the user has used the option |create-extra-nodes|, the ``medium nodes'' and
% ``large nodes'' are created. We recall that the command
% |\@@_create_extra_nodes:|, when used once, becomes no-op (in the current TeX
% group). 
%    \begin{macrocode}
    \bool_if:NT \g_@@_extra_nodes_bool \@@_create_extra_nodes:
    \int_zero_new:N \l_@@_initial_i_int
    \int_zero_new:N \l_@@_initial_j_int
    \int_zero_new:N \l_@@_final_i_int
    \int_zero_new:N \l_@@_final_j_int
    \bool_set_false:N \l_@@_initial_open_bool
    \bool_set_false:N \l_@@_final_open_bool
%    \end{macrocode}
%
% If the option |small| is used, the values |\l_@@_radius_dim| and
% |\l_@@_inter_dots_dim| (used to draw the dotted lines) are changed.
%    \begin{macrocode}     
    \bool_if:NT \l_@@_small_bool 
      { 
        \dim_set:Nn \l_@@_radius_dim { 0.37 pt }
        \dim_set:Nn \l_@@_inter_dots_dim { 0.25 em } 
      }
%    \end{macrocode}
%
% \bigskip
% Now, we really draw the lines. The code to draw the lines has been constructed
% in the token lists |\g_@@_Vdots_lines_tl|, etc.
%    \begin{macrocode}
    \g_@@_Hdotsfor_lines_tl
    \g_@@_Vdots_lines_tl
    \g_@@_Ddots_lines_tl
    \g_@@_Iddots_lines_tl
    \g_@@_Cdots_lines_tl
    \g_@@_Ldots_lines_tl
%    \end{macrocode}
%
% \bigskip
% Now, the |code-after|.
%    \begin{macrocode}
    \tikzset 
      { 
        every~picture / .style = 
          { 
            overlay ,
            remember~picture ,
            name~prefix = nm - \int_use:N \g_@@_env_int - 
          }
      }
    \cs_set_eq:NN \line \@@_line:nn
    \g_@@_code_after_tl 
    \tl_gclear:N \g_@@_code_after_tl
    \group_end:
    \str_gclear:N \g_@@_type_env_str
    \@@_restore_iRow_jCol:
  }
%    \end{macrocode}
%
%    \begin{macrocode}
\cs_new_protected:Nn \@@_restore_iRow_jCol:
  {
    \cs_if_exist:NT \theiRow { \int_gset_eq:NN \c@iRow \l_@@_save_iRow_int } 
    \cs_if_exist:NT \thejCol { \int_gset_eq:NN \c@jCol \l_@@_save_jCol_int } 
  }
%    \end{macrocode}
%
% \bigskip
% A dotted line will be said \emph{open} in one of its extremities when it stops
% on the edge of the matrix and \emph{closed} otherwise. In the following
% matrix, the dotted line is closed on its left extremity and open on its right.
% \[ \begin{pNiceMatrix}
% a+b+c & a+b & a\\
% a & \Cdots \\
% a & a+b & a+b+c
% \end{pNiceMatrix}\]
% For a closed extremity, we use the normal node and for a open one, we use the
% ``medium node'' or, if it exists, the |w|~node (the medium and large nodes are
% created with |\@@_create_extra_nodes:| if they have not been created yet).
% \[ \begin{pNiceMatrix}[create-extra-nodes,
%                        code-after = {\begin{tikzpicture} 
%                                      \node [highlight, fit={(2-1)}] {} ;
%                                      \node [highlight, fit={(2-3-medium)}] {};
%                                      \end{tikzpicture}
%                                    }]
% a+b+c & a+b & a\\
% a & \Cdots \\
% a & a+b & a+b+c
% \end{pNiceMatrix}\]
%
% 
% \bigskip
% The command |\@@_find_extremities_of_line:nnnn| takes four arguments:
%
% \begin{itemize}
% \item the first argument is the row of the cell where the command was issued;
% \item the second argument is the column of the cell where the command was
% issued; 
% \item the third argument is the $x$-value of the orientation vector of the
% line; 
% \item the fourth argument is the $y$-value of the orientation vector of the
% line; 
% \end{itemize}
%
% This command computes:
%
% \begin{itemize}
% \item |\l_@@_initial_i_int| and |\l_@@_initial_j_int| which are the
% coordinates of one extremity of the line; 
% \item |\l_@@_final_i_int| and |\l_@@_final_j_int| which are the coordinates of
% the other extremity of the line; 
% \item |\l_@@_initial_open_bool| and |\l_@@_final_open_bool| to indicate
% whether the extremities are open or not. 
% \end{itemize}
%
%    \begin{macrocode}       
\cs_new_protected:Nn \@@_find_extremities_of_line:nnnn
  { 
%    \end{macrocode}
% First, we declare the current cell as ``dotted'' because we forbide
% intersections of dotted lines.
%    \begin{macrocode}         
    \cs_set:cpn { @@ _ dotted _ #1 - #2 } { }
%    \end{macrocode}
% Initialization of variables.
%    \begin{macrocode}
    \int_set:Nn \l_@@_initial_i_int { #1 }
    \int_set:Nn \l_@@_initial_j_int { #2 }
    \int_set:Nn \l_@@_final_i_int { #1 }
    \int_set:Nn \l_@@_final_j_int { #2 }
%    \end{macrocode}
% We will do two loops: one when determinating the initial cell and the other
% when determinating the final cell. The boolean |\l_@@_stop_loop_bool| will be
% used to control these loops. 
%    \begin{macrocode}
    \bool_set_false:N \l_@@_stop_loop_bool
    \bool_do_until:Nn \l_@@_stop_loop_bool 
      { 
        \int_add:Nn \l_@@_final_i_int { #3 }
        \int_add:Nn \l_@@_final_j_int { #4 }
%    \end{macrocode}
% We test if we are still in the matrix. 
%    \begin{macrocode}
        \bool_set_false:N \l_@@_final_open_bool
        \int_compare:nNnTF \l_@@_final_i_int > \c@iRow
          {
            \int_compare:nNnT { #3 } = 1
              { \bool_set_true:N \l_@@_final_open_bool }
          }
          {
            \int_compare:nNnTF \l_@@_final_j_int < 1
              { 
                \int_compare:nNnT { #4 } = { -1 }
                  { \bool_set_true:N \l_@@_final_open_bool }
              }
              {
                \int_compare:nNnT \l_@@_final_j_int > \c@jCol
                  { 
                    \int_compare:nNnT { #4 } = 1
                      { \bool_set_true:N \l_@@_final_open_bool }
                  }
              }
          }
        \bool_if:NTF \l_@@_final_open_bool 
%    \end{macrocode}
% If we are outside the matrix, we have found the extremity of the dotted line
% and it's a \emph{open} extremity. 
%    \begin{macrocode}
          { 
%    \end{macrocode}
% We do a step backwards because we will draw the dotted line upon the last cell
% in the matrix (we will use the ``medium node'' of this cell).
%    \begin{macrocode}  
            \int_sub:Nn \l_@@_final_i_int { #3 }
            \int_sub:Nn \l_@@_final_j_int { #4 }
            \bool_set_true:N \l_@@_stop_loop_bool
          }
%    \end{macrocode}
% If we are in the matrix, we test whether the cell is empty. If it's not the
% case, we stop the loop because we have found the correct values for
% |\l_@@_final_i_int| and |\l_@@_final_j_int|. 
%    \begin{macrocode}
          { 
            \@@_if_not_empty_cell:nnTF \l_@@_final_i_int \l_@@_final_j_int
              { \bool_set_true:N \l_@@_stop_loop_bool }
%    \end{macrocode}
% If the case is empty, we declare that the cell as non-empty. Indeed, we will
% draw a dotted line and the cell will be on that dotted line. All the cells of
% a dotted line have to be mark as ``dotted'' because we don't want
% intersections between dotted lines.
%    \begin{macrocode} 
              { 
                \cs_set:cpn 
                  { 
                    @@ _ dotted _
                    \int_use:N \l_@@_final_i_int - 
                    \int_use:N \l_@@_final_j_int 
                  } 
                  { }
              }
          }
      }
%    \end{macrocode}
% We test wether the initial extremity of the dotted line is an implicit cell
% already dotted (by another dotted line). In this case, we can't draw the line
% because we have no Tikz node at the extremity of the arrow (and we can't use
% the ``medium node'' or the ``large node'' because we should use the normal
% node since the extremity is not open).
%    \begin{macrocode}
    \cs_if_free:cT 
      { 
        pgf@sh@ns@nm - 
        \int_use:N \g_@@_env_int -
        \int_use:N \l_@@_final_i_int - 
        \int_use:N \l_@@_final_j_int 
      }
      { 
        \bool_if:NF \l_@@_final_open_bool
          { 
            \msg_error:nnx { nicematrix } { Impossible~line } 
              { \int_use:N \l_@@_final_i_int }
            \bool_set_true:N \l_@@_impossible_line_bool 
          }
      }
%    \end{macrocode}
% 
% \interitem
% For |\l_@@_initial_i_int| and |\l_@@_initial_j_int| the programmation is
% similar to the previous one.
%    \begin{macrocode}
    \bool_set_false:N \l_@@_stop_loop_bool
    \bool_do_until:Nn \l_@@_stop_loop_bool 
      { 
        \int_sub:Nn \l_@@_initial_i_int { #3 }
        \int_sub:Nn \l_@@_initial_j_int { #4 }
        \bool_set_false:N \l_@@_initial_open_bool
        \int_compare:nNnTF \l_@@_initial_i_int < 1
          {
            \int_compare:nNnT { #3 } = 1
              { \bool_set_true:N \l_@@_initial_open_bool }
          }
          { 
            \int_compare:nNnTF \l_@@_initial_j_int < 1
              { 
                \int_compare:nNnT { #4 } = 1
                  { \bool_set_true:N \l_@@_initial_open_bool }
              }
              { 
                \int_compare:nNnT \l_@@_initial_j_int > \c@jCol
                  { 
                    \int_compare:nNnT { #4 } = { -1 }
                      { \bool_set_true:N \l_@@_initial_open_bool }
                  }
              }
          }
        \bool_if:NTF \l_@@_initial_open_bool
          { 
            \int_add:Nn \l_@@_initial_i_int { #3 }
            \int_add:Nn \l_@@_initial_j_int { #4 }
            \bool_set_true:N \l_@@_stop_loop_bool
          }
          { 
            \@@_if_not_empty_cell:nnTF 
              \l_@@_initial_i_int \l_@@_initial_j_int
              { \bool_set_true:N \l_@@_stop_loop_bool }
              {
                \cs_set:cpn 
                  { 
                    @@ _ dotted _ 
                    \int_use:N \l_@@_initial_i_int - 
                    \int_use:N \l_@@_initial_j_int 
                  } 
                  { }
              }
          }
      }
%    \end{macrocode}
% We test wether the initial extremity of the dotted line is an implicit cell
% already dotted (by another dotted line). In this case, we can't draw the line
% because we have no Tikz node at the extremity of the arrow (and we can't use
% the ``medium node'' or the ``large node'' because we should use the normal
% node since the extremity is not open).
%    \begin{macrocode}
    \cs_if_free:cT 
      { 
        pgf@sh@ns@nm - 
        \int_use:N \g_@@_env_int -
        \int_use:N \l_@@_initial_i_int - 
        \int_use:N \l_@@_initial_j_int 
      }
      { 
        \bool_if:NF \l_@@_initial_open_bool
          { 
            \msg_error:nnx { nicematrix } { Impossible~line } 
              { \int_use:N \l_@@_initial_i_int }
            \bool_set_true:N \l_@@_impossible_line_bool 
          }
      }
%    \end{macrocode}
% If we have at least one open extremity, we create the ``medium nodes'' in the
% matrix\footnote{We should change this. Indeed, for an open extremity of an
% \emph{horizontal} dotted line, we use the |w|~node, if, it exists, and not the
% ``medium node''.}. We remind that, when used once, the command 
% |\@@_create_extra_nodes:| becomes no-op in the current TeX group. 
%    \begin{macrocode}
    \bool_if:nT \l_@@_initial_open_bool \@@_create_extra_nodes: 
    \bool_if:NT \l_@@_final_open_bool \@@_create_extra_nodes: 
  }
%    \end{macrocode}
%
% 
%
% \interitem 
% The command |\@@_retrieve_coords:nn| retrieves the Tikz coordinates of the two
% extremities of the dotted line we will have to draw \footnote{In fact, with
% diagonal lines, or vertical lines in columns of type |L| or |R|, an adjustment
% of one of the coordinates may be done.}. This command has four implicit
% arguments which are |\l_@@_initial_i_int|, |\l_@@_initial_j_int|,
% |\l_@@_final_i_int| and |\l_@@_final_j_int|. 
%
% The two arguments of the command |\@@_retrieve_coords:nn| are the suffix and
% the anchor that must be used for the two nodes. 
%
% The coordinates are stored in |\g_@@_x_initial_dim|, |\g_@@_y_initial_dim|,
% |\g_@@_x_final_dim|, |\g_@@_y_final_dim|. These variables are global for
% technical reasons: we have to do an affectation in an environment
% |{tikzpicture}|. 
%    \begin{macrocode}
\cs_new_protected:Nn \@@_retrieve_coords:nn
  { 
    \dim_gzero_new:N \g_@@_x_initial_dim 
    \dim_gzero_new:N \g_@@_y_initial_dim 
    \dim_gzero_new:N \g_@@_x_final_dim 
    \dim_gzero_new:N \g_@@_y_final_dim
    \begin { tikzpicture } [ remember~picture ]
      \tikz@parse@node \pgfutil@firstofone
        ( nm - \int_use:N \g_@@_env_int -
               \int_use:N \l_@@_initial_i_int -
               \int_use:N \l_@@_initial_j_int #1 )
      \dim_gset:Nn \g_@@_x_initial_dim \pgf@x
      \dim_gset:Nn \g_@@_y_initial_dim \pgf@y
      \tikz@parse@node \pgfutil@firstofone
        ( nm - \int_use:N \g_@@_env_int -
               \int_use:N \l_@@_final_i_int -
               \int_use:N \l_@@_final_j_int #2 )
      \dim_gset:Nn \g_@@_x_final_dim \pgf@x
      \dim_gset:Nn \g_@@_y_final_dim \pgf@y
    \end { tikzpicture } 
  }
\cs_generate_variant:Nn \@@_retrieve_coords:nn { x x }
%    \end{macrocode}
%
% \interitem 
% For the horizontal lines with open extremities, we must take into account the
% ``|col|'' nodes created in the environments which have a fixed width of the
% columns. The following command will recompute the $x$-value of the extremities
% in this case (erasing the value computed in |\@@_retrieve_coords:nn|).
%    \begin{macrocode}
\cs_new_protected:Nn \@@_adjust_with_col_nodes:
  { 
    \bool_if:NT \l_@@_initial_open_bool
      { 
        \cs_if_exist:cT
          { pgf@sh@ns@nm - \int_use:N \g_@@_env_int - col - 0 } 
          {
            \begin { tikzpicture } [ remember~picture ]
            \tikz@parse@node \pgfutil@firstofone
              ( nm - \int_use:N \g_@@_env_int - col - 0 ) 
            \dim_gset:Nn \g_@@_x_initial_dim \pgf@x
            \end { tikzpicture }
          }
      }       
    \bool_if:NT \l_@@_final_open_bool
      { 
        \cs_if_exist:cT
          { 
            pgf@sh@ns@nm - \int_use:N \g_@@_env_int - col - 
            \int_use:N \c@jCol 
          } 
          {
            \begin { tikzpicture } [ remember~picture ]
            \tikz@parse@node \pgfutil@firstofone
              ( 
                nm - \int_use:N \g_@@_env_int - col - 
                \int_use:N \c@jCol 
              ) 
            \dim_gset:Nn \g_@@_x_final_dim \pgf@x
            \end { tikzpicture }
          }
      }       
  }
%    \end{macrocode}
%
% \interitem
%    \begin{macrocode}
\cs_new_protected:Nn \@@_draw_Ldots:nn
  { 
    \cs_if_free:cT { @@ _ dotted _ #1 - #2 }
      {
        \bool_set_false:N \l_@@_impossible_line_bool
        \@@_find_extremities_of_line:nnnn { #1 } { #2 } \c_zero_int \c_one_int
        \bool_if:NF \l_@@_impossible_line_bool \@@_actually_draw_Ldots:
      }
  }
%    \end{macrocode}
% 
% \medskip
% The command |\@@_actually_draw_Ldots:| draws the |Ldots| line using
% |\l_@@_initial_i_int|, |\l_@@_initial_j_int|, |\l_@@_initial_open_bool|,
% |\l_@@_final_i_int|, |\l_@@_final_j_int| and |\l_@@_final_open_bool|. We have
% a dedicated command because if is used also by |\Hdotsfor|. 
%    \begin{macrocode}
\cs_new_protected:Nn \@@_actually_draw_Ldots:
  { 
    \@@_retrieve_coords:xx 
      { 
        \bool_if:NTF \l_@@_initial_open_bool
          {
%    \end{macrocode}
% If a |w| node exists we use the |w| node for the extremity.
%    \begin{macrocode}
           \cs_if_exist:cTF
             { 
               pgf@sh@ns@nm 
               - \int_use:N \g_@@_env_int 
               - \int_use:N \l_@@_initial_i_int 
               - \int_use:N \l_@@_initial_j_int - w 
             }
             { - w.base~west }
             { - medium.base~west }
         }
         { .base~east }
      }
      {
        \bool_if:NTF \l_@@_final_open_bool
          {
            \cs_if_exist:cTF
              { 
                pgf@sh@ns@nm 
                - \int_use:N \g_@@_env_int 
                - \int_use:N \l_@@_final_i_int 
                - \int_use:N \l_@@_final_j_int - w 
              }
              { - w.base~east }
              { - medium.base~east }
          }
          { .base~west }
      }
    \@@_adjust_with_col_nodes:
    \bool_if:NT \l_@@_initial_open_bool
      { \dim_gset_eq:NN \g_@@_y_initial_dim \g_@@_y_final_dim }
    \bool_if:NT \l_@@_final_open_bool                 
      { \dim_gset_eq:NN \g_@@_y_final_dim \g_@@_y_initial_dim }
%    \end{macrocode}
% We raise the line of a quantity equal to the radius of the dots because we
% want the dots really ``on'' the line of texte.
%    \begin{macrocode}
    \dim_gadd:Nn \g_@@_y_initial_dim { 0.53 pt }
    \dim_gadd:Nn \g_@@_y_final_dim { 0.53 pt }
    \@@_draw_tikz_line:
  }
%    \end{macrocode}
%
% \bigskip
%    \begin{macrocode}
\cs_new_protected:Nn \@@_draw_Cdots:nn
  { 
    \cs_if_free:cT { @@ _ dotted _ #1 - #2 }
      {
        \bool_set_false:N \l_@@_impossible_line_bool
        \@@_find_extremities_of_line:nnnn { #1 } { #2 } \c_zero_int \c_one_int 
        \bool_if:NF \l_@@_impossible_line_bool
          {
            \@@_retrieve_coords:xx 
              { 
                \bool_if:NTF \l_@@_initial_open_bool
                  {
                    \cs_if_exist:cTF
                      { 
                        pgf@sh@ns@nm 
                        - \int_use:N \g_@@_env_int 
                        - \int_use:N \l_@@_initial_i_int 
                        - \int_use:N \l_@@_initial_j_int - w 
                      }
                      { - w.mid~west }
                      { - medium.mid~west }
                  }
                  { .mid~east }
              }
              {
                \bool_if:NTF \l_@@_final_open_bool
                  {
                    \cs_if_exist:cTF
                      { 
                        pgf@sh@ns@nm 
                        - \int_use:N \g_@@_env_int 
                        - \int_use:N \l_@@_final_i_int 
                        - \int_use:N \l_@@_final_j_int - w 
                      }
                      { - w.mid~east }
                      { - medium.mid~east }
                  }
                  { .mid~west }
              }
            \@@_adjust_with_col_nodes:
            \bool_if:NT \l_@@_initial_open_bool
              { \dim_gset_eq:NN \g_@@_y_initial_dim \g_@@_y_final_dim }
            \bool_if:NT \l_@@_final_open_bool                 
              { \dim_gset_eq:NN \g_@@_y_final_dim \g_@@_y_initial_dim }
            \@@_draw_tikz_line:
          }
      }
  }
%    \end{macrocode}
%
% \bigskip
% For the vertical dots, we have to distinguish different instances because we
% want really vertical lines. Be careful: it's not possible to insert the
% command |\@@_retrieve_coords:nn| in the arguments |T| and |F| of the
% \pkg{expl3} commands (why?). 
%    \begin{macrocode}      
\cs_new_protected:Nn \@@_draw_Vdots:nn
  { 
    \cs_if_free:cT { @@ _ dotted _ #1 - #2 }
      {
        \bool_set_false:N \l_@@_impossible_line_bool
        \@@_find_extremities_of_line:nnnn { #1 } { #2 } \c_one_int \c_zero_int
        \bool_if:NF \l_@@_impossible_line_bool
          {
            \@@_retrieve_coords:xx 
              { 
                \bool_if:NTF \l_@@_initial_open_bool
                  { - medium.north~west }
                  { .south~west }
              } 
              { 
                \bool_if:NTF \l_@@_final_open_bool
                  { - medium.south~west }
                  { .north~west }
              }
%    \end{macrocode}
% The boolean |\l_tmpa_bool| indicates whether the column is of type |l| (|L| of
% |{NiceArray}|) or may be considered as if.
%    \begin{macrocode}      
            \bool_set:Nn \l_tmpa_bool 
              { \dim_compare_p:nNn \g_@@_x_initial_dim = \g_@@_x_final_dim }
            \@@_retrieve_coords:xx 
              { 
                \bool_if:NTF \l_@@_initial_open_bool
                  { - medium.north }
                  { .south }
              } 
              { 
                \bool_if:NTF \l_@@_final_open_bool  
                  { - medium.south }
                  { .north }
              }
%    \end{macrocode}
% The boolean |\l_tmpb_bool| indicates whether the column is of type |c| (|C| of
% |{NiceArray}|) or may be considered as if.
%    \begin{macrocode}      
            \bool_set:Nn \l_tmpb_bool 
              { \dim_compare_p:nNn \g_@@_x_initial_dim = \g_@@_x_final_dim }
            \bool_if:NF \l_tmpb_bool
              { 
                \dim_gset:Nn \g_@@_x_initial_dim
                  { 
                    \bool_if:NTF \l_tmpa_bool \dim_min:nn \dim_max:nn
                      \g_@@_x_initial_dim \g_@@_x_final_dim
                  }
                \dim_gset_eq:NN \g_@@_x_final_dim \g_@@_x_initial_dim
              }
            \@@_draw_tikz_line:
          }
      }
  }
%    \end{macrocode}
%
% \interitem
% For the diagonal lines, the situation is a bit more complicated because, by
% default, we parallelize the diagonals lines. The first diagonal line is drawn
% and then, all the other diagonal lines are drawn parallel to the first one.
%    \begin{macrocode}
\cs_new_protected:Nn \@@_draw_Ddots:nn
  { 
    \cs_if_free:cT { @@ _ dotted _ #1 - #2 }
      { 
        \bool_set_false:N \l_@@_impossible_line_bool
        \@@_find_extremities_of_line:nnnn { #1 } { #2 } \c_one_int \c_one_int
        \bool_if:NF \l_@@_impossible_line_bool
          {
            \@@_retrieve_coords:xx 
              { 
                \bool_if:NTF \l_@@_initial_open_bool
                  { - medium.north~west }
                  { .south~east }
              } 
              { 
                \bool_if:NTF \l_@@_final_open_bool
                  { - medium.south~east }
                  { .north~west }
              }
%    \end{macrocode}
% We have retrieved the coordinates in the usual way (they are stored in
% |\g_@@_x_initial_dim|, etc.). If the parallelization of the diagonals is set,
% we will have (maybe) to adjust the fourth coordinate. 
%    \begin{macrocode}
            \bool_if:NT \l_@@_parallelize_diags_bool
              { 
                \int_incr:N \l_@@_ddots_int
%    \end{macrocode}
% We test if the diagonal line is the first one (the counter |\l_@@_ddots_int|
% is created for this usage). 
%    \begin{macrocode}
                \int_compare:nNnTF \l_@@_ddots_int = \c_one_int
%    \end{macrocode}
% If the diagonal line is the first one, we have no adjustment of the line to do
% but we store the $\Delta_x$ and the $\Delta_y$ of the line because these
% values will be used to draw the others diagonal lines parallels to the first
% one. 
%    \begin{macrocode}
                  { 
                    \dim_set:Nn \l_@@_delta_x_one_dim 
                      { \g_@@_x_final_dim - \g_@@_x_initial_dim }
                    \dim_set:Nn \l_@@_delta_y_one_dim 
                      { \g_@@_y_final_dim - \g_@@_y_initial_dim }
                  }
%    \end{macrocode}
% If the diagonal line is not the first one, we have to adjust the second
% extremity of the line by modifying the coordinate |\g_@@_y_initial_dim|.
%    \begin{macrocode}
                  { 
                    \dim_gset:Nn \g_@@_y_final_dim          
                      { 
                        \g_@@_y_initial_dim +
                        ( \g_@@_x_final_dim - \g_@@_x_initial_dim ) * 
                        \dim_ratio:nn \l_@@_delta_y_one_dim \l_@@_delta_x_one_dim 
                      }
                  }
              }
%    \end{macrocode}
% Now, we can draw the dotted line (after a possible change of
% |\g_@@_y_initial_dim|). 
%    \begin{macrocode}
            \@@_draw_tikz_line:
          }
      }
  }
%    \end{macrocode}
%
% \bigskip
% We draw the |\Iddots| diagonals in the same way.
%    \begin{macrocode}
\cs_new_protected:Nn \@@_draw_Iddots:nn
  {
    \cs_if_free:cT { @@ _ dotted _ #1 - #2 }
      { 
        \bool_set_false:N \l_@@_impossible_line_bool
        \@@_find_extremities_of_line:nnnn { #1 } { #2 } 1 { -1 }
        \bool_if:NF \l_@@_impossible_line_bool
          {
            \@@_retrieve_coords:xx 
              { 
                \bool_if:NTF \l_@@_initial_open_bool
                  { - medium.north~east }
                  { .south~west }
              } 
              { 
                \bool_if:NTF \l_@@_final_open_bool
                  { - medium.south~west }
                  { .north~east }
              }
            \bool_if:NT \l_@@_parallelize_diags_bool
              { 
                \int_incr:N \l_@@_iddots_int
                \int_compare:nNnTF \l_@@_iddots_int = \c_one_int
                  { 
                    \dim_set:Nn \l_@@_delta_x_two_dim 
                      { \g_@@_x_final_dim - \g_@@_x_initial_dim }
                    \dim_set:Nn \l_@@_delta_y_two_dim 
                      { \g_@@_y_final_dim - \g_@@_y_initial_dim }
                  }
                  { 
                    \dim_gset:Nn \g_@@_y_final_dim
                       { 
                         \g_@@_y_initial_dim +
                         ( \g_@@_x_final_dim - \g_@@_x_initial_dim ) *
                         \dim_ratio:nn \l_@@_delta_y_two_dim \l_@@_delta_x_two_dim 
                       }
                  }
              }
            \@@_draw_tikz_line:
          }
      }
  }
%    \end{macrocode}
%
% \bigskip
% \subsection{The actual instructions for drawing the dotted line with Tikz}
%
% The command |\@@_draw_tikz_line:| draws the line using four implicit
% arguments:  
%
% \quad |\g_@@_x_initial_dim|, |\g_@@_y_initial_dim|, |\g_@@_x_final_dim| and
% |\g_@@_y_final_dim|. These variables are global for technical reasons: their
% first affectation was in an instruction |\tikz|. 
%
%    \begin{macrocode}
\cs_new_protected:Nn \@@_draw_tikz_line:
  { 
%    \end{macrocode}
% The dimension |\l_@@_l_dim| is the length $\ell$ of the line to draw. We use
% the floating point reals of \pkg{expl3} to compute this length.
%    \begin{macrocode}
    \dim_zero_new:N \l_@@_l_dim
    \dim_set:Nn \l_@@_l_dim
      { 
        \fp_to_dim:n 
          { 
            sqrt 
             ( 
               (   \dim_use:N \g_@@_x_final_dim 
                 - \dim_use:N \g_@@_x_initial_dim 
               ) ^ 2
                  +
               (   \dim_use:N \g_@@_y_final_dim 
                 - \dim_use:N \g_@@_y_initial_dim
               ) ^ 2 
             )
          }
      }
%    \end{macrocode}
% We draw only if the length is not equal to zero (in fact, in the first
% compilation, the length may be equal to zero). 
%    \begin{macrocode}
    \dim_compare:nNnF \l_@@_l_dim = \c_zero_dim
%    \end{macrocode}
% The integer |\l_tmpa_int| is the number of dots of the dotted line.
%    \begin{macrocode}
      { 
        \bool_if:NTF \l_@@_initial_open_bool
          { 
            \bool_if:NTF \l_@@_final_open_bool
              { 
                \int_set:Nn \l_tmpa_int 
                  { \dim_ratio:nn \l_@@_l_dim \l_@@_inter_dots_dim }
              }
              { 
                \int_set:Nn \l_tmpa_int 
                  { \dim_ratio:nn { \l_@@_l_dim - 0.3 em } \l_@@_inter_dots_dim }
              }
          }
          { 
            \bool_if:NTF \l_@@_final_open_bool
              { 
                \int_set:Nn \l_tmpa_int 
                  { \dim_ratio:nn { \l_@@_l_dim - 0.3 em } \l_@@_inter_dots_dim }
              }
              { 
                \int_set:Nn \l_tmpa_int 
                  { \dim_ratio:nn { \l_@@_l_dim - 0.6 em } \l_@@_inter_dots_dim}
              }
          }
%    \end{macrocode}
% The dimensions |\l_tmpa_dim| and |\l_tmpb_dim| are the coordinates of the
% vector between two dots in the dotted line.
%    \begin{macrocode}
        \dim_set:Nn \l_tmpa_dim 
          { 
            ( \g_@@_x_final_dim - \g_@@_x_initial_dim ) *
            \dim_ratio:nn \l_@@_inter_dots_dim \l_@@_l_dim 
          }
        \dim_set:Nn \l_tmpb_dim 
          { 
            ( \g_@@_y_final_dim - \g_@@_y_initial_dim ) *
            \dim_ratio:nn \l_@@_inter_dots_dim \l_@@_l_dim
          }
%    \end{macrocode}
%
% The length $\ell$ is the length of the dotted line. We note $\Delta$ the
% length between two dots and $n$ the number of intervals between dots. We note
% $\delta = \frac12(\ell - n \Delta)$. The distance between the initial
% extremity of the line and the first dot will be equal to $k\cdot\delta$ where 
% $k=0$, $1$ or $2$. We first compute this number $k$ in |\l_tmpb_int|.
%    \begin{macrocode}
        \int_set:Nn \l_tmpb_int
          { 
            \bool_if:NTF \l_@@_initial_open_bool
              { \bool_if:NTF \l_@@_final_open_bool 1 0 }
              { \bool_if:NTF \l_@@_final_open_bool 2 1 }
          }
%    \end{macrocode}
% In the loop over the dots (|\int_step_inline:nnnn|), the dimensions
% |\g_@@_x_initial_dim| and |\g_@@_y_initial_dim| will be used for the
% coordinates of the dots. But, before the loop, we must move until the 
% first dot.
%
%    \begin{macrocode}
        \dim_gadd:Nn \g_@@_x_initial_dim
          {  
            ( \g_@@_x_final_dim - \g_@@_x_initial_dim ) *
            \dim_ratio:nn 
            { \l_@@_l_dim - \l_@@_inter_dots_dim * \l_tmpa_int }
            { \l_@@_l_dim * 2 }
            * \l_tmpb_int
          }
%    \end{macrocode}
% (In a multiplication of a dimension and an integer, the integer must always be
% put in second position.) 
%    \begin{macrocode}         
        \dim_gadd:Nn \g_@@_y_initial_dim 
          {   
            ( \g_@@_y_final_dim - \g_@@_y_initial_dim ) * 
            \dim_ratio:nn 
              { \l_@@_l_dim - \l_@@_inter_dots_dim * \l_tmpa_int } 
              { \l_@@_l_dim * 2 } * 
            \l_tmpb_int
          }
        \begin { tikzpicture } [ overlay ]
          \int_step_inline:nnn 0 \l_tmpa_int
            { 
              \pgfpathcircle 
                { \pgfpoint { \g_@@_x_initial_dim } { \g_@@_y_initial_dim } }
                { \l_@@_radius_dim }
              \pgfusepath { fill }
              \dim_gadd:Nn \g_@@_x_initial_dim \l_tmpa_dim
              \dim_gadd:Nn \g_@@_y_initial_dim \l_tmpb_dim 
            }
        \end { tikzpicture } 
      }
  }
%    \end{macrocode}
%
% \subsection{User commands available in the new environments}
%
% We give new names for the commands |\ldots|, |\cdots|, |\vdots| and |\ddots|
% because these commands will be redefined (if the option |renew-dots| is used).
%    \begin{macrocode}
\cs_set_eq:NN \@@_ldots \ldots
\cs_set_eq:NN \@@_cdots \cdots
\cs_set_eq:NN \@@_vdots \vdots
\cs_set_eq:NN \@@_ddots \ddots
\cs_set_eq:NN \@@_iddots \iddots
%    \end{macrocode}
%
% \interitem
% The command |\@@_add_to_empty_cells:| adds the current cell to
% |\g_@@_empty_cells_seq| which is the list of the empty cells (the cells
% explicitly declared ``empty'': there may be, of course, other empty cells in
% the matrix). 
%    \begin{macrocode}
\cs_new_protected:Nn \@@_add_to_empty_cells:
  { 
    \cs_gset:cpx 
      { @@ _ empty _ \int_use:N \c@iRow - \int_use:N \c@jCol } 
      { \int_use:N \g_@@_env_int }
  }
%    \end{macrocode}
%
% \interitem 
% The commands |\@@_Ldots|, |\@@_Cdots|, |\@@_Vdots|, |\@@_Ddots| and
% |\@@_Iddots| will be linked to |\Ldots|, |\Cdots|, |\Vdots|, |\Ddots| and
% |\Iddots| in the environments |{NiceArray}| (the other environments of
% \pkg{nicematrix} rely upon |{NiceArray}|). 
%
% The starred versions of these commands are deprecated since version~3.1 but
% they are still available.
%    \begin{macrocode}
\NewDocumentCommand \@@_Ldots { s }
  { 
    \bool_if:nF { #1 } { \@@_instruction_of_type:n { Ldots } }
    \bool_if:NF \l_@@_nullify_dots_bool { \phantom \@@_ldots }
    \@@_add_to_empty_cells:
  }
%    \end{macrocode}
%
% \bigskip
%    \begin{macrocode}
\NewDocumentCommand \@@_Cdots { s }
  { 
    \bool_if:nF { #1 } { \@@_instruction_of_type:n { Cdots } }
    \bool_if:NF \l_@@_nullify_dots_bool { \phantom \@@_cdots }
    \@@_add_to_empty_cells:
  }
%    \end{macrocode}
%
% \bigskip
%    \begin{macrocode}
\NewDocumentCommand \@@_Vdots { s }
  {
    \bool_if:nF { #1 } { \@@_instruction_of_type:n { Vdots } }
    \bool_if:NF \l_@@_nullify_dots_bool { \phantom \@@_vdots }
    \@@_add_to_empty_cells:
  }
%    \end{macrocode}
%
% \bigskip
%    \begin{macrocode}
\NewDocumentCommand \@@_Ddots { s }
  { 
    \bool_if:nF { #1 } { \@@_instruction_of_type:n { Ddots } }
    \bool_if:NF \l_@@_nullify_dots_bool { \phantom \@@_ddots }
    \@@_add_to_empty_cells:
  }
%    \end{macrocode}
%
% \bigskip
%    \begin{macrocode}
\NewDocumentCommand \@@_Iddots { s }
  { 
    \bool_if:nF { #1 } { \@@_instruction_of_type:n { Iddots } }
    \bool_if:NF \l_@@_nullify_dots_bool { \phantom \@@_iddots }
    \@@_add_to_empty_cells:
  }
%    \end{macrocode}
%
%
% \bigskip
% The command |\@@_Hspace:| will be linked to |\hspace| in |{NiceArray}|.
%    \begin{macrocode}
\cs_new_protected:Nn \@@_Hspace:
  { 
   \@@_add_to_empty_cells:
   \hspace
  }
%    \end{macrocode}
%
%
% \bigskip
% In the environment |{NiceArray}|, the command |\multicolumn| will be linked to
% the following command |\@@_multicolumn:nnn|.
%    \begin{macrocode}
\cs_set_eq:NN \@@_old_multicolumn \multicolumn
\cs_new:Npn \@@_multicolumn:nnn #1 #2 #3
  { 
    \@@_old_multicolumn { #1 } { #2 } { #3 }
    \int_compare:nNnT #1 > 1
      {
        \seq_gput_left:Nx \g_@@_multicolumn_cells_seq
          { \int_eval:n \c@iRow - \int_use:N \c@jCol }
        \seq_gput_left:Nn \g_@@_multicolumn_sizes_seq { #1 } 
      }
    \int_gadd:Nn \c@jCol { #1 - 1 }
  }
%    \end{macrocode}
%
%
% \bigskip
% The command |\@@_Hdotsfor| will be linked to |\Hdotsfor| in |{NiceArray}|.
% This command uses an optional argument like |\hdotsfor| but this argument is
% discarded (in |\hdotsfor|, this argument is used for fine tuning of the space
% between two consecutive dots). Tikz nodes are created for all the cells of
% the array, even the implicit cells of the |\Hdotsfor|. 
%
% \medskip
% This command must not be protected since it begins with |\multicolumn|.
%    \begin{macrocode}
\cs_new:Npn \@@_Hdotsfor:
  {
    \multicolumn { 1 } { C } { }
    \@@_Hdotsfor_i
  }
%    \end{macrocode}
%
% The command |\@@_Hdotsfor_i| is defined with the tools of \pkg{xparse} because
% it has an optionnal argument. Note that such a command defined by
% |\NewDocumentCommand| is protected and that's why we have put the
% |\multicolumn| before (in the definition of |\@@_Hdotsfor:|).
%    \begin{macrocode}
\bool_if:NTF \c_@@_draft_bool
  {
    \NewDocumentCommand \@@_Hdotsfor_i { O { }  m }
      { \prg_replicate:nn { #2 - 1 } { & \multicolumn { 1 } { C } { } } } 
  }
  {
    \NewDocumentCommand \@@_Hdotsfor_i { O { }  m }
      {
        \tl_gput_right:Nx \g_@@_Hdotsfor_lines_tl
          {
            \@@_draw_Hdotsfor:nnn
              { \int_use:N \c@iRow }
              { \int_use:N \c@jCol } 
              { #2 }
          }
        \prg_replicate:nn { #2 - 1 } { & \multicolumn { 1 } { C } { } }
      } 
  }
%    \end{macrocode}
% 
% \medskip
%    \begin{macrocode}
\cs_new_protected:Nn \@@_draw_Hdotsfor:nnn
  { 
    \bool_set_false:N \l_@@_initial_open_bool
    \bool_set_false:N \l_@@_final_open_bool
%    \end{macrocode}
% For the row, it's easy.
%    \begin{macrocode}
    \int_set:Nn \l_@@_initial_i_int { #1 }
    \int_set:Nn \l_@@_final_i_int { #1 }
%    \end{macrocode}
% For the column, it's a bit more complicated.
%    \begin{macrocode}
    \int_compare:nNnTF #2 = 1
      { 
        \int_set:Nn \l_@@_initial_j_int 1
        \bool_set_true:N \l_@@_initial_open_bool
      }
      {
        \int_set:Nn \l_tmpa_int { #2 - 1 }
        \@@_if_not_empty_cell:nnTF \l_@@_initial_i_int \l_tmpa_int
          { \int_set:Nn \l_@@_initial_j_int { #2 - 1 } }
          { 
            \int_set:Nn \l_@@_initial_j_int {#2}
            \bool_set_true:N \l_@@_initial_open_bool
          }
      }
    \int_compare:nNnTF { #2 + #3 -1 } = \c@jCol
      { 
        \int_set:Nn \l_@@_final_j_int { #2 + #3 - 1 }
        \bool_set_true:N \l_@@_final_open_bool
      }
      {
        \int_set:Nn \l_tmpa_int { #2 + #3 }
        \@@_if_not_empty_cell:nnTF \l_@@_final_i_int \l_tmpa_int
          { \int_set:Nn \l_@@_final_j_int { #2 + #3 } }
          { 
            \int_set:Nn \l_@@_final_j_int { #2 + #3 - 1 }
            \bool_set_true:N \l_@@_final_open_bool
          }
      }
    \bool_if:nT { \l_@@_initial_open_bool || \l_@@_final_open_bool }
      \@@_create_extra_nodes: 
    \@@_actually_draw_Ldots:
%    \end{macrocode}
% We declare all the cells concerned by the |\Hdotsfor| as ``dotted'' (for the
% dotted lines created by |\Cdots|, |\Ldots|, etc., this job is done by
% |\@@_find_extremities_of_line:nnnn|). This declaration is done by defining a
% special control sequence (to nil).
%    \begin{macrocode}
    \int_step_inline:nnn { #2 } { #2 + #3 - 1 }
      { \cs_set:cpn { @@ _ dotted _ #1 - ##1 } { } }
  }
%    \end{macrocode}
% 
%
%
% \subsection{The command \textbackslash line accessible in code-after}
%
% In the |code-after|, the command |\@@_line:nn| will be linked to |\line|. This
% command takes two arguments which are the specification of two cells in the
% array (in the format $i$-$j$) and draws a dotted line between these cells. 
%    \begin{macrocode}
\cs_new_protected:Nn \@@_line:nn
  {
    \bool_if:NF \c_@@_draft_bool
      {
        \dim_zero_new:N \g_@@_x_initial_dim
        \dim_zero_new:N \g_@@_y_initial_dim
        \dim_zero_new:N \g_@@_x_final_dim
        \dim_zero_new:N \g_@@_y_final_dim
        \bool_set_false:N \l_@@_initial_open_bool
        \bool_set_false:N \l_@@_final_open_bool
        \bool_if:nTF
          {
            \cs_if_exist_p:c { pgf@sh@ns@nm - \int_use:N \g_@@_env_int - #1 }  
            && 
            \cs_if_exist_p:c { pgf@sh@ns@nm - \int_use:N \g_@@_env_int - #2 } 
          }
          {
            \begin { tikzpicture }
               \path~(#1)~--~(#2)~node[at~start]~(i)~{}~node[at~end]~(f)~{} ;
               \tikz@parse@node \pgfutil@firstofone ( i )
               \dim_gset:Nn \g_@@_x_initial_dim \pgf@x
               \dim_gset:Nn \g_@@_y_initial_dim \pgf@y
               \tikz@parse@node \pgfutil@firstofone ( f )
               \dim_gset:Nn \g_@@_x_final_dim \pgf@x
               \dim_gset:Nn \g_@@_y_final_dim \pgf@y
            \end { tikzpicture }  
            \@@_draw_tikz_line:
          }
          { 
            \@@_error:nnn { unknown~cell~for~line~in~code-after } 
              { #1 } { #2 }
          }
      }
  }
%    \end{macrocode}
% 
% 
% The commands |\Ldots|, |\Cdots|, |\Vdots|, |\Ddots|, and |\Iddots| don't use
% this command because they have to do other settings (for example, the diagonal
% lines must be parallelized). 
%
% \bigskip
% \subsection{The commands to draw dotted lines to separate columns and rows}
%
% The command |\hdottedline| draws an horizontal dotted line to separate two
% rows. Similarly, the letter ``:'' in the preamble draws a vertical dotted line
% (the letter can be changed with the option |letter-for-dotted-lines|). Both
% mechanisms write instructions in the |code-after|. The actual instructions in
% the |code-after| use the commands |\@@_hdottedline:n| and |\@@_vdottedline:n|.
% 
% \bigskip
% We want the horizontal lines at the same position\footnote{In fact, almost the
% same position because of the width of the line: the width of a dotted line is
% not the same as the width of a line created by |\hline|.} as the line created
% by |\hline| (or |\hdashline| of \pkg{arydshln}). That's why we use a
% |\noalign| to insert a box with a |\dotfill|.
%
% 
% 
% \medskip
% Some extensions, like the extension \pkg{doc}, do a redefinition of the
% command |\dotfill| of LaTeX. That's why we define a command |\@@_dotfill:| as
% we wish. We test whether we are in draft mode because, in this case, we don't
% draw the dotted lines.
%    \begin{macrocode}
\bool_if:NTF \c_@@_draft_bool
  { \cs_set_eq:NN \@@_dotfill: \prg_do_nothing: }
  {
    \cs_set:Npn \@@_dotfill:
      { 
%    \end{macrocode}
% If the option |small| is used, we change the space between dots (we can't
% use |\l_@@_inter_dots_dim| which will be set after the construction of the
% array). We can't put the |\bool_if:NT| in the first argument of
% |\hbox_to_wd:nn| because |\cleaders| is a special TeX primitive.
%    \begin{macrocode}
        \bool_if:NT \l_@@_small_bool
          { \dim_set:Nn \l_@@_inter_dots_dim { 0.25 em } }
        \cleaders 
        \hbox_to_wd:nn 
          { \l_@@_inter_dots_dim }
          { 
            \c_math_toggle_token
            \bool_if:NT \l_@@_small_bool \scriptstyle 
            \hss . \hss 
            \c_math_toggle_token
          } 
        \hfill 
      }
  }
%    \end{macrocode}
%                                      
% This command must \emph{not} be protected because it starts with |\noalign|.
%    \begin{macrocode}
\cs_new:Npn \@@_hdottedline:
  {
    \noalign 
      { 
        \bool_gset_true:N \g_@@_extra_nodes_bool
        \cs_if_exist:cTF { @@_width_ \int_use:N \g_@@_env_int }
          { \dim_set_eq:Nc \l_tmpa_dim { @@_width_ \int_use:N \g_@@_env_int } }
          { \dim_set:Nn \l_tmpa_dim { 5 mm } }
        \hbox_overlap_right:n 
          {
            \bool_if:nT 
              {
                \l_@@_NiceArray_bool
                    &&
                ! \l_@@_exterior_arraycolsep_bool
                    &&
                \int_compare_p:nNn \l_@@_first_col_int > \c_zero_int
              }
              { \skip_horizontal:n { - \arraycolsep } } 
            \hbox_to_wd:nn 
              { 
                \l_tmpa_dim + 2 \arraycolsep 
                - \l_@@_left_margin_dim - \l_@@_right_margin_dim 
              } 
            \@@_dotfill: 
          }
      } 
  }
%    \end{macrocode}
%
% \bigskip
%    \begin{macrocode}
\cs_new_protected:Nn \@@_vdottedline:n
  {
%    \end{macrocode}
% We should allow the letter ``|:|'' in the first position of the preamble
% but that would need a special programmation.
%    \begin{macrocode}
    \int_compare:nNnTF #1 = \c_zero_int
      { \@@_error:n { Use~of~:~in~first~position } }
      {   
        \bool_if:NF \c_@@_draft_bool
          {
            \dim_zero_new:N \g_@@_x_initial_dim
            \dim_zero_new:N \g_@@_y_initial_dim
            \dim_zero_new:N \g_@@_x_final_dim
            \dim_zero_new:N \g_@@_y_final_dim
            \bool_set_true:N \l_@@_initial_open_bool 
            \bool_set_true:N \l_@@_final_open_bool 
%    \end{macrocode}
% If a ``|col|'' node exists (if the array has been constructed with a fixed
% width of column), we use it.
%    \begin{macrocode}
            \cs_if_exist:cTF
              { pgf@sh@ns@nm -\int_use:N \g_@@_env_int - col - #1 }
              {
                \begin { tikzpicture } [ remember~picture ]
                  \tikz@parse@node\pgfutil@firstofone
                    ( col - #1 )
                  \dim_gset:Nn \g_@@_x_initial_dim \pgf@x
                  \dim_gset:Nn \g_@@_x_final_dim \pgf@x
                  \dim_gset:Nn \g_@@_y_final_dim \pgf@y
                \end { tikzpicture }
                \dim_gset:Nn \g_@@_y_initial_dim { - \c_max_dim }
                \int_step_inline:nn \c@jCol 
                  {
                    \begin { tikzpicture } [ remember~picture ]
                      \tikz@parse@node\pgfutil@firstofone
                        ( 1 - ##1 . north~east )
                      \dim_gset:Nn \g_@@_y_initial_dim
                        { \dim_max:nn \g_@@_y_initial_dim \pgf@y }
                    \end { tikzpicture }
                  }
              }
%    \end{macrocode}
% If not, we use the ``large node''.
%    \begin{macrocode}
              {
                \begin { tikzpicture } [ remember~picture ]
                  \tikz@parse@node\pgfutil@firstofone
                    ( 1 - #1 - large .north~east )
                  \dim_gset:Nn \g_@@_x_initial_dim \pgf@x
                  \dim_gset:Nn \g_@@_y_initial_dim \pgf@y
                  \tikz@parse@node\pgfutil@firstofone
                    ( \int_use:N \c@iRow - #1 - large .south~east )
                  \dim_gset:Nn \g_@@_x_final_dim \pgf@x
                  \dim_gset:Nn \g_@@_y_final_dim \pgf@y
                \end { tikzpicture }
%    \end{macrocode}
% However, if the previous column was constructed with a letter |w|, we use the
% |w|-nodes (and we erase the previous computation of the $x$-value of the
% vertical dotted line).
%    \begin{macrocode}
                \cs_if_exist:cT
                  { pgf@sh@ns@nm -\int_use:N \g_@@_env_int - 1 - #1 - w }
                  {
                    \begin { tikzpicture } [ remember~picture ]
                      \tikz@parse@node\pgfutil@firstofone
                        ( 1 - #1 - w .north~east )
                      \dim_gset:Nn \g_@@_x_initial_dim \pgf@x
                      \tikz@parse@node\pgfutil@firstofone
                        ( \int_use:N \c@iRow - #1 - w .south~east )
                      \dim_gset:Nn \g_@@_x_final_dim \pgf@x
                    \end { tikzpicture }
                    \dim_gadd:Nn \g_@@_x_initial_dim \arraycolsep
                    \dim_gadd:Nn \g_@@_x_final_dim \arraycolsep
                  }
              }
            \@@_draw_tikz_line:
          } 
      }
  }
%    \end{macrocode}
% 
%
% \bigskip
% \subsection{The vertical rules}
%
% We don't want that a vertical rule drawn by the specifier ``"|"'' extends
% in the eventual ``first row'' and ``last row'' of the array.
% 
% The natural way to do that would be to redefine the specifier ``"|"''
% with |\newcolumntype|:
% \begin{Verbatim}[commandchars=\~\#\+]
%    \newcolumntype { | }
%      { ! { \int_compare:nNnF \c@iRow = \c_zero_int \vline } } 
% \end{Verbatim}
% 
% However, this code fails is the user uses "\DefineShortVerb{\|}" of
% \pkg{fancyvrb}. Moreover, it would not be able to deal correctly with two
% consecutive specifiers ``"|"'' (in a preambule like "ccc||ccc").
%
% That's why we will do a redefinition of the macro |\@arrayrule| of \pkg{array}
% and this redefinition will add |\@@_vline:| instead of |\vline| to the
% preamble.
%
% Here is the definition of |\@@_vline:|. This definition \emph{must} be
% protected because you don't want that macro expanded during the construction
% of the preamble (the tests must be effective in each row and not once when the
% preamble is constructed).
%    \begin{macrocode}
\cs_new_protected:Npn \@@_vline:
  { 
    \int_compare:nNnTF \l_@@_first_col_int = \c_zero_int 
      { 
        \int_compare:nNnTF \c@jCol = \c_zero_int
          {
            \int_compare:nNnTF \l_@@_first_row_int = \c_zero_int
              {     
                \int_compare:nNnF \c@iRow = \c_zero_int 
                  { 
                    \int_compare:nNnF \c@iRow = \l_@@_last_row_int
                    \@@_vline_i: 
                  }  
              }
              {
                \int_compare:nNnF \c@iRow = \c_zero_int
                  { 
                    \int_compare:nNnF \c@iRow = \l_@@_last_row_int
                    \@@_vline_i: 
                  }   
              }    
           }
           {     
             \int_compare:nNnF \c@iRow = \c_zero_int 
               { 
                 \int_compare:nNnF \c@iRow = \l_@@_last_row_int
                 \@@_vline_i: 
               }  
           }
      }
      { 
        \int_compare:nNnTF \c@jCol = \c_zero_int
          {
            \int_compare:nNnF \c@iRow = { -1 }
              { 
                \int_compare:nNnF \c@iRow = { \l_@@_last_row_int - 1 }
                  \@@_vline_i:
              } 
          }
          {     
            \int_compare:nNnF \c@iRow = \c_zero_int 
              { 
                \int_compare:nNnF \c@iRow = \l_@@_last_row_int
                \@@_vline_i: 
              } 
          }
      }   
  } 
%    \end{macrocode}
% 
% \medskip
% If \pkg{colortbl} is loaded, the following macro will redefined (in a
% |\AtBeginDocument|) to take into account the color fixed by |\arrayrulecolor|
% of \pkg{colortbl}. 
%    \begin{macrocode}
\cs_set_eq:NN \@@_vline_i: \vline
%    \end{macrocode}
%
% \bigskip 
% \subsection{The environment \{NiceMatrixBlock\}}
%
% The following flag will be raised when all the columns of the environments of
% the block must have the same width in ``auto'' mode.
%    \begin{macrocode}
\bool_new:N \l_@@_block_auto_columns_width_bool
%    \end{macrocode}
%
% \bigskip
% As of now, there is only one option available for the environment
% |{NiceMatrixBlock}|. 
%    \begin{macrocode}
\keys_define:nn { NiceMatrix / NiceMatrixBlock } 
  {
    auto-columns-width .code:n = 
      { 
        \bool_set_true:N \l_@@_block_auto_columns_width_bool
        \dim_gzero_new:N \g_@@_max_cell_width_dim
        \bool_set_true:N \l_@@_auto_columns_width_bool
      }
  }
%    \end{macrocode}
%
% \bigskip
%    \begin{macrocode}
\NewDocumentEnvironment { NiceMatrixBlock } { ! O { } }
  {
    \int_gincr:N \g_@@_NiceMatrixBlock_int
    \dim_zero:N \l_@@_columns_width_dim
    \keys_set:nn { NiceMatrix / NiceMatrixBlock } { #1 }
    \bool_if:NT \l_@@_block_auto_columns_width_bool
      {
        \cs_if_exist:cT { @@_max_cell_width_ \int_use:N \g_@@_NiceMatrixBlock_int }
          {
            \dim_set:Nx \l_@@_columns_width_dim
              { \use:c { @@_max_cell_width _ \int_use:N \g_@@_NiceMatrixBlock_int } }
          } 
      }
  }
%    \end{macrocode}
%
% \medskip
% At the end of the environment |{NiceMatrixBlock}|, we write in the main |.aux|
% file instructions for the column width of all the environments of the block
% (that's why we have stored the number of the first environment of the block in
% the counter |\l_@@_first_env_block_int|). 
%    \begin{macrocode}
  { 
    \bool_if:NT \l_@@_block_auto_columns_width_bool
      {
        \iow_now:Nn \@mainaux \ExplSyntaxOn
        \iow_now:Nx \@mainaux         
          { 
            \cs_gset:cpn 
              { @@ _ max _ cell _ width _ \int_use:N \g_@@_NiceMatrixBlock_int } 
              { \dim_use:N \g_@@_max_cell_width_dim }
          }
        \iow_now:Nn \@mainaux \ExplSyntaxOff
      }
  }
%    \end{macrocode}
%
%
% \subsection{The extra nodes}
%
% First, two variants of the functions |\dim_min:nn| and |\dim_max:nn|.
%    \begin{macrocode}
\cs_generate_variant:Nn \dim_min:nn { v n }
\cs_generate_variant:Nn \dim_max:nn { v n }
%    \end{macrocode}
%
% \bigskip
% The macro |\@@_create_extra_nodes:| must \emph{not} be used in the
% |code-after| because the |code-after| is executed in a scope of |prefix name|.
%
%
% \bigskip
% For each row $i$, we compute two dimensions
% \texttt{l_@@_row_\textsl{i}_min_dim} and \texttt{l_@@_row_\textsl{i}_max_dim}.
% The dimension \texttt{l_@@_row_\textsl{i}_min_dim} is the minimal 
% $y$-value of all the cells of the row~$i$. The dimension
% \texttt{l_@@_row_\textsl{i}_max_dim} is the maximal $y$-value of all the cells
% of the row~$i$. 
%
% Similarly, for each column $j$, we compute two dimensions
% \texttt{l_@@_column_\textsl{j}_min_dim} and
% \texttt{l_@@_column_\textsl{j}_max_dim}. The dimension
% \texttt{l_@@_column_\textsl{j}_min_dim} is the minimal $x$-value of all the
% cells of the column~$j$. The dimension \texttt{l_@@_column_\textsl{j}_max_dim}
% is the maximal $x$-value of all the cells of the column~$j$.
%
% Since these dimensions will be computed as maximum or minimum, we initialize
% them to |\c_max_dim| or |-\c_max_dim|. 
%    \begin{macrocode}
\cs_new_protected:Nn \@@_create_extra_nodes:
  {
    \begin { tikzpicture } [ remember~picture , overlay ]
      \int_step_variable:nnNn \l_@@_first_row_int \g_@@_row_total_int \@@_i:
        { 
          \dim_zero_new:c { l_@@_row_\@@_i: _min_dim } 
          \dim_set_eq:cN { l_@@_row_\@@_i: _min_dim } \c_max_dim
          \dim_zero_new:c { l_@@_row_\@@_i: _max_dim } 
          \dim_set:cn { l_@@_row_\@@_i: _max_dim } { - \c_max_dim }
        }
      \int_step_variable:nnNn \l_@@_first_col_int \g_@@_col_total_int \@@_j:
        {
          \dim_zero_new:c { l_@@_column_\@@_j: _min_dim } 
          \dim_set_eq:cN { l_@@_column_\@@_j: _min_dim } \c_max_dim
          \dim_zero_new:c { l_@@_column_\@@_j: _max_dim } 
          \dim_set:cn { l_@@_column_\@@_j: _max_dim } { - \c_max_dim }
        }
%    \end{macrocode}
% We begin the two nested loops over the rows and the columns of the array.
%    \begin{macrocode}
      \int_step_variable:nnNn \l_@@_first_row_int \g_@@_row_total_int \@@_i:
        { 
          \int_step_variable:nnNn 
            \l_@@_first_col_int \g_@@_col_total_int \@@_j: 
%    \end{macrocode}
% Maybe the cell ($i$-$j$) is an implicit cell (that is to say a cell after
% implicit ampersands |&|). In this case, of course, we don't update the
% dimensions we want to compute. 
%    \begin{macrocode}
            { \cs_if_exist:cT 
                { pgf@sh@ns@nm - \int_use:N \g_@@_env_int - \@@_i: - \@@_j: }
%    \end{macrocode}
% We retrieve the coordinates of the anchor |south west| of the (normal) node of
% the cell ($i$-$j$). They will be stored in |\pgf@x| and |\pgf@y|.
%    \begin{macrocode}
                {
                  \tikz@parse@node \pgfutil@firstofone 
                    ( nm - \int_use:N \g_@@_env_int 
                         - \@@_i: - \@@_j: .south~west )
                  \dim_set:cn { l_@@_row_\@@_i: _min_dim}
                    { \dim_min:vn { l_@@_row _ \@@_i: _min_dim } \pgf@y }  
                  \seq_if_in:NxF \g_@@_multicolumn_cells_seq { \@@_i: - \@@_j: }
                    { 
                      \dim_set:cn { l_@@_column _ \@@_j: _min_dim}
                        { \dim_min:vn { l_@@_column _ \@@_j: _min_dim } \pgf@x }
                    }
%    \end{macrocode}
% We retrieve the coordinates of the anchor |north east| of the (normal) node of
% the cell ($i$-$j$). They will be stored in |\pgf@x| and |\pgf@y|.
%    \begin{macrocode}
                  \tikz@parse@node \pgfutil@firstofone 
                    ( nm - \int_use:N \g_@@_env_int - \@@_i: - \@@_j: .north~east )
                  \dim_set:cn { l_@@_row _ \@@_i: _ max_dim }
                    { \dim_max:vn { l_@@_row _ \@@_i: _ max_dim } \pgf@y }
                  \seq_if_in:NxF \g_@@_multicolumn_cells_seq { \@@_i: - \@@_j: }
                    { 
                      \dim_set:cn { l_@@_column _ \@@_j: _ max_dim }
                        { \dim_max:vn { l_@@_column _ \@@_j: _max_dim } \pgf@x }
                    } 
                }
            }
        }
%    \end{macrocode}
% Now, we can create the ``medium nodes''. We use a command |\@@_create_nodes:|
% because this command will also be used for the creation of the ``large nodes''
% (after changing the value of |name-suffix|). 
%    \begin{macrocode} 
      \tikzset { name~suffix = -medium }
      \@@_create_nodes:
%    \end{macrocode}
% 
% \bigskip
% For ``large nodes'', the exterior rows and columns don't interfer.
% That's why the loop over the rows will start at 1 and the loop over the
% columns will stop at $|\c@jCol|$ (and not |\g_@@_col_total_int|). Idem
% for the rows. 
%     \begin{macrocode}
      \int_set:Nn \l_@@_first_row_int 1
      \int_set:Nn \l_@@_first_col_int 1
%    \end{macrocode}
% We have to change the values of all the dimensions
% \texttt{l_@@_row_\textsl{i}_min_dim}, \texttt{l_@@_row_\textsl{i}_max_dim},
% \texttt{l_@@_column_\textsl{j}_min_dim} and
% \texttt{l_@@_column_\textsl{j}_max_dim}.  
%    \begin{macrocode} 
      \int_step_variable:nNn { \c@iRow - 1 } \@@_i:
        { 
          \dim_set:cn { l_@@_row _ \@@_i: _ min _ dim }  
            {
              (  
                \dim_use:c { l_@@_row _ \@@_i: _ min _ dim } + 
                \dim_use:c { l_@@_row _ \int_eval:n { \@@_i: + 1 } _ max _ dim }
              ) 
              / 2
            }
          \dim_set_eq:cc { l_@@_row _ \int_eval:n { \@@_i: + 1 } _ max _ dim } 
            { l_@@_row_\@@_i: _min_dim } 
        }
      \int_step_variable:nNn { \c@jCol - 1 } \@@_j:
        { 
          \dim_set:cn { l_@@_column _ \@@_j: _ max _ dim }  
            { 
              (  
                \dim_use:c 
                  { l_@@_column _ \@@_j: _ max _ dim } + 
                \dim_use:c 
                  { l_@@_column _ \int_eval:n { \@@_j: + 1 } _ min _ dim }
              ) 
              / 2
            }
          \dim_set_eq:cc { l_@@_column _ \int_eval:n { \@@_j: + 1 } _ min _ dim }
            { l_@@_column _ \@@_j: _ max _ dim } 
        }
      \dim_sub:cn 
        { l_@@_column _ 1 _ min _ dim } 
        \l_@@_left_margin_dim
      \dim_add:cn 
        { l_@@_column _ \int_use:N \c@jCol _ max _ dim } 
        \l_@@_right_margin_dim
%    \end{macrocode}
% Now, we can actually create the ``large nodes''.
%    \begin{macrocode}
      \tikzset { name~suffix = -large }
      \@@_create_nodes:
      \end{tikzpicture}
%    \end{macrocode}
%
% \medskip
% When used once, the command |\@@_create_extra_nodes:| must become no-op (in
% the current TeX group). That's why we put a nullification of the command.
%    \begin{macrocode}
      \cs_set:Npn \@@_create_extra_nodes: { }
%    \end{macrocode}
% 
% \medskip
% We can now compute the width of the array (used by |\hdottedline|).
%    \begin{macrocode}
      \begin { tikzpicture } [ remember~picture , overlay ]
        \tikz@parse@node \pgfutil@firstofone 
          ( nm - \int_use:N \g_@@_env_int - 1 - 1 - large .north~west )
        \dim_gset:Nn \g_tmpa_dim \pgf@x 
        \tikz@parse@node \pgfutil@firstofone 
          ( nm - \int_use:N \g_@@_env_int - 1 - 
                 \int_use:N \c@jCol - large .north~east )
        \dim_gset:Nn \g_tmpb_dim \pgf@x 
      \end { tikzpicture }      
      \iow_now:Nn \@mainaux \ExplSyntaxOn 
      \iow_now:Nx \@mainaux 
        { 
          \cs_gset:cpn { @@_width_ \int_use:N \g_@@_env_int }
            { \dim_eval:n { \g_tmpb_dim - \g_tmpa_dim } } 
        }
      \iow_now:Nn \@mainaux \ExplSyntaxOff
  }
%    \end{macrocode}
% 
%
% \bigskip
% The control sequence |\@@_create_nodes:| is used twice: for the construction
% of the ``medium nodes'' and for the construction of the ``large nodes''. The
% nodes are constructed with the value of all the dimensions
% \texttt{l_@@_row_\textsl{i}_min_dim}, \texttt{l_@@_row_\textsl{i}_max_dim},
% \texttt{l_@@_column_\textsl{j}_min_dim} and
% \texttt{l_@@_column_\textsl{j}_max_dim}. Between the construction of the
% ``medium nodes'' and the ``large nodes'', the values of these dimensions are
% changed. 
%     \begin{macrocode}
\cs_new_protected:Nn \@@_create_nodes:
  { 
    \int_step_variable:nnNn \l_@@_first_row_int \g_@@_row_total_int \@@_i:
      { 
        \int_step_variable:nnNn \l_@@_first_col_int \g_@@_col_total_int \@@_j:
%    \end{macrocode}
% We create two ponctual nodes for the extremities of a diagonal of the
% rectangular node we want to create. These nodes |(@@~south~west)| and
% |(@@~north~east)| are not available for the user of \pkg{nicematrix}. That's
% why their names are independent of the row and the column. In the two nested
% loops, they will be overwritten until the last cell.
%    \begin{macrocode}
          {
            \coordinate ( @@~south~west ) 
               at ( \dim_use:c { l_@@_column_ \@@_j: _min_dim } ,
                    \dim_use:c { l_@@_row_ \@@_i: _min_dim } ) ; 
            \coordinate ( @@~north~east ) 
               at ( \dim_use:c { l_@@_column_ \@@_j: _max_dim } ,
                    \dim_use:c { l_@@_row_ \@@_i: _max_dim } ) ; 
%    \end{macrocode}
% We can eventually draw the rectangular node for the cell (|\@@_i|-|\@@_j|).
% This node is created with the Tikz library \pkg{fit}. Don't forget that the
% Tikz option |name suffix| has been set to |-medium| or |-large|. 
%    \begin{macrocode}
            \node
              [ 
                node~contents = { } ,
                fit = ( @@~south~west ) ( @@~north~east )  ,
                inner~sep = \c_zero_dim ,
                name = nm - \int_use:N \g_@@_env_int - \@@_i: - \@@_j: ,
                alias = 
                  \str_if_empty:NF \l_@@_name_str 
                    { \l_@@_name_str - \@@_i: - \@@_j: }
              ] 
              ; 
          }
      }
%    \end{macrocode}
% Now, we create the nodes for the cells of the |\multicolumn|. We recall that
% we have stored in |\g_@@_multicolumn_cells_seq| the list of the cells where a
% |\multicolumn{|$n$|}{...}{...}| with $n$>1 was issued and in
% |\g_@@_multicolumn_sizes_seq| the correspondant values of $n$. 
%    \begin{macrocode}
    \seq_mapthread_function:NNN 
      \g_@@_multicolumn_cells_seq 
      \g_@@_multicolumn_sizes_seq
      \@@_node_for_multicolumn:nn
  }
%    \end{macrocode}
%
% 
%    \begin{macrocode}
\cs_new_protected:Npn \@@_extract_coords: #1 - #2 \q_stop
  { 
    \cs_set:Npn \@@_i: { #1 } 
    \cs_set:Npn \@@_j: { #2 }
  }
%    \end{macrocode}
%
% The command |\@@_node_for_multicolumn:nn| takes two arguments. The first is
% the position of the cell where the command |\multicolumn{|$n$|}{...}{...}| was
% issued in the format $i$|-|$j$ and the second is the value of~$n$ (the length
% of the ``multi-cell''). 
%    \begin{macrocode}
\cs_new_protected:Nn \@@_node_for_multicolumn:nn
  { 
    \@@_extract_coords: #1 \q_stop
    \coordinate ( @@~south~west ) at
      (
        \dim_use:c { l_@@_column _ \@@_j: _ min _ dim } ,
        \dim_use:c { l_@@_row _ \@@_i: _ min _ dim } 
      ) ; 
    \coordinate ( @@~north~east ) at
      ( 
        \dim_use:c { l_@@_column _ \int_eval:n { \@@_j: + #2 - 1 } _ max _ dim} ,
        \dim_use:c { l_@@_row _ \@@_i: _ max _ dim } 
      ) ; 
    \node 
      [ 
        node~contents = { } ,
        fit = ( @@~south~west ) ( @@~north~east ) ,
        inner~sep = \c_zero_dim ,
        name = nm - \int_use:N \g_@@_env_int - \@@_i: - \@@_j: ,
        alias = 
          \str_if_empty:NF \l_@@_name_str 
            { \l_@@_name_str - \@@_i: - \@@_j: }
      ] 
      ; 
  }
%    \end{macrocode}
%
%
% \subsection{Block matrices}
%
% The code in this section if for the construction of \emph{block matrices}. It
% has no direct link with the environment |{NiceMatrixBlock}|.
% 
% The following command will be linked to |\Block| in the environments of
% \pkg{nicematrix}. We define it with |\NewExpandableDocumentCommand| of
% \pkg{xparse} because it has an optionnal argument between |<| and |>| (for TeX
% instructions put before the math mode of the label) and because it must be
% expandable since it reduces (in the case of a block of only one row) to a
% command |\multicolumn|. 
%    \begin{macrocode}
\NewExpandableDocumentCommand \@@_Block: { m D < > { } m }
  {
    \@@_Block_i #1 \q_stop { #2 } { #3 }
  }
%    \end{macrocode}
% 
% \medskip
% The first argument of |\@@_Block:| (which is required) has a special syntax.
% It must be of the form $i$|-|$j$ where $i$ and $j$ are the size (in rows and 
% columns) of the block.
%    \begin{macrocode}
\cs_new:Npn \@@_Block_i #1-#2 \q_stop
  {
    \@@_Block_ii:nnnn { #1 } { #2 } 
  }
%    \end{macrocode}
%
% \medskip
% Now, the arguments have been extracted: |#1| is $i$ (the number of rows of the
% block), |#2| is $j$ (the number of columns of the block), |#3| are the tokens
% to put before the math mode and |#4| is the label of the block. The following
% command must \emph{not} be protected because it contains a command
% |\multicolumn| (in the case of a block of only one row).
%    \begin{macrocode}
\cs_new:Npn \@@_Block_ii:nnnn #1 #2 #3 #4
  {
%    \end{macrocode}
% 
% \medskip
% In the case of a block of only one row, we use a |\multicolumn| and not the
% general technique because, in this case, we want the label perfectly aligned
% with the base line of that row of the array.
%    \begin{macrocode}
    \int_compare:nNnTF { #1 } = 1
      {
        \multicolumn { #2 } { C } { \hbox:n { #3 $#4$ } }
        \@@_gobble_ampersands:n { #2 - 1 }
      }
      { \@@_Block_iii:nnnn { #1 } { #2 } { #3 } { #4 } }
  }
%    \end{macrocode}
%
% \medskip
% The command |\@@_Block_iii:nnnn| is for the case of a block of $n$~rows with
% $n>1$. 
%    \begin{macrocode}
\cs_new_protected:Npn \@@_Block_iii:nnnn #1 #2 #3 #4
  {
    \bool_gset_true:N \g_@@_extra_nodes_bool
%    \end{macrocode}
% We write an instruction in the |code-after|. We write the instruction in the
% beginning of the |code-after| (the |left| in |\tl_gput_left:Nx|) because we
% want the Tikz nodes corresponding of the block created \emph{before} potential
% instructions written by the user in the |code-after| (these instructions may
% use the Tikz node of the created block).
%    \begin{macrocode}
    \tl_gput_left:Nx \g_@@_code_after_tl
      {
        \@@_Block_iv:nnnnn
          { \int_use:N \c@iRow }
          { \int_use:N \c@jCol }
          { \int_eval:n { \c@iRow + #1 - 1 } }
          { \int_eval:n { \c@jCol + #2 - 1 } }
          \exp_not:n { { #3 $ #4 $ } } 
      } 
  }
%    \end{macrocode}
%
% \medskip
% The command |\@@_gobble_ampersands:n| will gobble $n$ ampersands (and also the
% spaces) where $n$ is the argument of the command. This command is fully
% expandable and we need this feature.
%    \begin{macrocode}
\group_begin:
  \char_set_catcode_letter:N \&
  \cs_new:Npn \@@_gobble_ampersands:n #1 
    {
      \int_compare:nNnT { #1 } > 0 
        { 
          \peek_charcode_remove_ignore_spaces:NT & 
            { \@@_gobble_ampersands:n { #1 - 1 } } 
        }
    }
\group_end:
%    \end{macrocode}
%                          
%
% \medskip
% The following command |\@@_Block_iii:nnnnn| will be used in the |code-after|.
% It's necessary to create two Tikz nodes because we want the label |#5| really
% drawn in the \emph{center} of the node.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_Block_iv:nnnnn #1 #2 #3 #4 #5
  { 
    \bool_if:nTF
      { 
           \int_compare_p:nNn { #3 } > \c@iRow 
        || \int_compare_p:nNn { #4 } > \c@jCol 
      }
      { \msg_error:nnnn { nicematrix } { Block~too~large } { #1 } { #2 } }
      {
        \begin{tikzpicture}
        \node 
          [ 
            fit = ( #1 - #2 - medium . north~west ) 
                  ( #3 - #4 - medium . south~east ) ,
            inner~sep = 0 pt ,
          ] 
%    \end{macrocode}
% We don't forget the name of the node because the user may wish to use it.
%    \begin{macrocode}
          (#1-#2) { } ;
         \node at (#1-#2.center) { #5 } ;
    \end{tikzpicture}
      }
  }
%    \end{macrocode}
%                          
% % \subsection{How to draw the dotted lines transparently}
%    \begin{macrocode}
\cs_set_protected:Npn \@@_renew_matrix:
  { 
    \RenewDocumentEnvironment { pmatrix } { }
      { \pNiceMatrix } 
      { \endpNiceMatrix }
    \RenewDocumentEnvironment { vmatrix } { }
      { \vNiceMatrix }
      { \endvNiceMatrix }
    \RenewDocumentEnvironment { Vmatrix } { }
      { \VNiceMatrix }
      { \endVNiceMatrix }
    \RenewDocumentEnvironment { bmatrix } { }
      { \bNiceMatrix }
      { \endbNiceMatrix }
    \RenewDocumentEnvironment { Bmatrix } { }
      { \BNiceMatrix }
      { \endBNiceMatrix }
  }
%    \end{macrocode}
%
%
%
% \subsection{We process the options}
%
% We process the options when the package is loaded (with |\usepackage|) but we
% recommend to use |\NiceMatrixOptions| instead. 
%
% We must process these options after the definition of the environment
% |{NiceMatrix}| because the option |renew-matrix| executes the code
% |\cs_set_eq:NN \env@matrix \NiceMatrix|.  
%
% Of course, the command |\NiceMatrix| must be defined before such an
% instruction is executed. 
%    \begin{macrocode}
\keys_define:nn { NiceMatrix / Package }
  {
    renew-dots .bool_set:N = \l_@@_renew_dots_bool ,
    renew-dots .value_forbidden:n = true ,
    renew-matrix .code:n = \@@_renew_matrix: ,
    renew-matrix .value_forbidden:n = true ,
    transparent .meta:n = { renew-dots , renew-matrix } ,
    transparent .value_forbidden:n = true,
  }
\ProcessKeysOptions { NiceMatrix / Package }
%    \end{macrocode}
%
% \subsection{Error messages of the package}
%
%
%    \begin{macrocode}
\@@_msg_new:nn { unknown~cell~for~line~in~code-after }
  {
    Your~command~\token_to_str:N\line\{#1\}\{#2\}~in~the~'code-after'~
    can't~be~executed~because~a~Tikz~node~doesn't~exist.\\
    If~you~go~on~this~command~will~be~ignored.
  }
%    \end{macrocode}
%
%
%    \begin{macrocode}
\@@_msg_new:nn { last-col~non~empty~for~NiceArray }
  {
    In~the~environment~\{\g_@@_type_env_str\},~you~must~use~the~option~
    'last-col'~without~value~(the~number~of~columns~is~known~by~the~
    preamble~of~the~environment).\\
    However,~you~can~go~on~for~this~time~
    (the~value~'\l_keys_value_tl'~will~be~ignored). 
  }
%    \end{macrocode}
%
%    \begin{macrocode}
\@@_msg_new:nn { last-col~empty~for~NiceMatrix }
  {
    In~the~environment~\{\g_@@_type_env_str\}~you~can't~use~the~option~
    'last-col'~without~value.~You~must~give~the~number~of~that~last~column.\\
    If~you~go~on~this~option~will~be~ignored.
  }
%    \end{macrocode}
% 
%    \begin{macrocode}
\@@_msg_new:nn { Block~too~large }
  {
    You~try~to~draw~a~block~in~the~cell~#1-#2~of~your~matrix~but~the~matrix~is~
    too~small~for~that~block.\\
    If~you~go~on,~this~command~line~will~be~ignored.
  }
%    \end{macrocode}
%
% 
%    \begin{macrocode}
\@@_msg_new:nn { Impossible~line }
  {
    A~dotted~line~can't~be~drawn~because~you~have~not~put~
    all~the~ampersands~required~on~the~row~#1.\\
    If~you~go~on,~this~dotted~line~will~be~ignored.
  }
%    \end{macrocode}
%
%    \begin{macrocode}
\@@_msg_new:nn { Wrong~last~row }
  { 
    You~have~used~'last-row=\int_use:N \l_@@_last_row_int'~but~your~environment~
    \{\g_@@_type_env_str\}~seems~to~have~\int_use:N \c@iRow 
    rows.~If~you~go~on,~the~value~of~\int_use:N \c@iRow 
    will~be~used~for~last~row.~You~can~avoid~this~problem~by~using~'last-row'~
    without~value~(more~compilations~might~be~necessary).
  }
%    \end{macrocode}     
%
%
%    \begin{macrocode}
\@@_msg_new:nn { Yet~in~env }
  { 
    Environments~\{NiceArray\}~(or~\{NiceMatrix\},~etc.)~can't~be~nested.\\ 
    This~error~is~fatal.
  }
%    \end{macrocode}
%
%    \begin{macrocode}
\@@_msg_new:nn { Outside~math~mode }
  {
    The~environment~\{\g_@@_type_env_str\}~can~be~used~only~in~math~mode~
    (and~not~in~\token_to_str:N \vcenter).\\
    This~error~is~fatal.
  }
%    \end{macrocode}
%
%    \begin{macrocode}
\@@_msg_new:nn { Option~Transparent~suppressed }
  { 
    The~option~'Transparent'~has~been~renamed~'transparent'.\\
    However,~you~can~go~on~for~this~time.
  }
\@@_msg_new:nn { Option~RenewMatrix~suppressed }
  { 
    The~option~'RenewMatrix'~has~been~renamed~'renew-matrix'.\\
    However,~you~can~go~on~for~this~time.
  }
%    \end{macrocode}
%
%    \begin{macrocode}
\@@_msg_new:nn { Bad~value~for~letter~for~dotted~lines }
  { 
    The~value~of~key~'\tl_use:N\l_keys_key_tl'~must~be~of~length~1.\\
    If~you~go~on,~it~will~be~ignored. 
  }
%    \end{macrocode}
%
%
%    \begin{macrocode}
\@@_msg_new:nnn { Unknown~key~for~NiceMatrixOptions }
  {
    The~key~'\tl_use:N\l_keys_key_tl'~is~unknown~for~the~command~
    \token_to_str:N \NiceMatrixOptions. \\
    If~you~go~on,~it~will~be~ignored. \\
    For~a~list~of~the~available~keys,~type~H~<return>.
  }
  { 
    The~available~options~are~(in~alphabetic~order):~
    allow-duplicate-names,~
    code-for-first-col,~
    code-for-first-row,~
    code-for-last-col,~
    code-for-last-row,~
    exterior-arraycolsep,~
    hlines,~
    left-margin,~
    letter-for-dotted-lines,~
    nullify-dots,~
    parallelize-diags,~
    renew-dots,~
    renew-matrix,~
    right-margin,~
    small~
    and~transparent
  }
%    \end{macrocode}
%
%    \begin{macrocode}
\@@_msg_new:nnn { Unknown~option~for~NiceArray }
  { 
    The~option~'\tl_use:N\l_keys_key_tl'~is~unknown~for~the~environment~
    \{NiceArray\}. \\
    If~you~go~on,~it~will~be~ignored. \\
    For~a~list~of~the~available~options,~type~H~<return>.
  }
  {
    The~available~options~are~(in~alphabetic~order):~
    b,~
    c,~
    code-after,~
    code-for-first-col,~
    code-for-first-row,~
    code-for-last-col,~
    code-for-last-row,~
    columns-width,~
    create-extra-nodes,~
    extra-left-margin,~
    extra-right-margin,~
    first-col,~
    first-row,~
    hlines,~
    last-col,~
    last-row,~
    left-margin,~
    name,~
    nullify-dots,~
    parallelize-diags,~
    renew-dots,~
    right-margin,~
    small~
    and~t.
  }
%    \end{macrocode}
%
% \medskip
% This error message is used for the set of keys |NiceMatrix/NiceMatrix| and
% |NiceMatrix/pNiceArray| (but not by |NiceMatrix/NiceArray| (because, for this
% set of keys, there is also the options |t|, |c| and~|b|).
%    \begin{macrocode}
\@@_msg_new:nnn { Unknown~option~for~NiceMatrix }
  { 
    The~option~'\tl_use:N\l_keys_key_tl'~is~unknown~for~the~environment~
    \{\g_@@_type_env_str\}. \\
    If~you~go~on,~it~will~be~ignored. \\
    For~a~list~of~the~available~options,~type~H~<return>.
  }
  {
    The~available~options~are~(in~alphabetic~order):~
    code-after,~
    code-for-first-col,~
    code-for-first-row,~
    code-for-last-col,~
    code-for-last-row,~
    columns-width,~
    create-extra-nodes,~
    extra-left-margin,~
    extra-right-margin,~
    first-col,~
    first-row,~
    hlines,~
    last-col,~
    last-row,~
    left-margin,~
    name,~
    nullify-dots,~
    parallelize-diags,~
    renew-dots,~
    right-margin~
    and~small.
  }
%    \end{macrocode}
%
% The following message should be changed because, normally, there can be any
% longer artefact in the environments of \pkg{amsmath}.
%    \begin{macrocode}
\@@_msg_new:nnn { Duplicate~name }
  { 
    The~name~'\l_keys_value_tl'~is~already~used~and~you~shouldn't~use~
    the~same~environment~name~twice.~You~can~go~on,~but,~
    maybe,~you~will~have~incorrect~results~especially~ 
    if~you~use~'columns-width=auto'.~If~you~use~nicematrix~inside~some~
    environments~of~amsmath,~this~error~may~be~an~artefact.~In~this~case,~
    use~the~option~'allow-duplicate-names'.\\
    For~a~list~of~the~names~already~used,~type~H~<return>. \\ 
  }
  {
    The~names~already~defined~in~this~document~are:~
    \seq_use:Nnnn \g_@@_names_seq { ,~ } { ,~ } { ~and~ }.
  }
%    \end{macrocode}
%
%    \begin{macrocode}
\@@_msg_new:nn { Option~auto~for~columns-width }
  { 
    You~can't~give~the~value~'auto'~to~the~option~'columns-width'~here.~
    If~you~go~on,~the~option~will~be~ignored.
  }
%    \end{macrocode}
% 
%    \begin{macrocode}
\@@_msg_new:nn { Zero~row }
  { 
    There~is~a~problem.~Maybe~your~environment~\{\g_@@_type_env_str\}~is~empty.~ 
    Maybe~you~have~used~l,~c~and~r~instead~of~L,~C~and~R~in~the~preamble~
    of~your~environment. \\
    If~you~go~on,~the~result~may~be~incorrect.
  }
%    \end{macrocode}
%
%    \begin{macrocode}
\@@_msg_new:nn { Use~of~:~in~first~position }
  { 
    You~can't~use~the~column~specifier~'\l_@@_letter_for_dotted_lines_str'~in~the~
    first~position~of~the~preamble~of~the~environment~\{\g_@@_type_env_str\}. \\
    If~you~go~on,~this~dotted~line~will~be~ignored.
  }
%    \end{macrocode}
%
%
% \subsection{Obsolete environments}
%
%    \begin{macrocode}
\@@_msg_new:nn { Obsolete~environment }
  {
    The~environment~\{\@currenvir\}~is~obsolete.~
    We~should~use~#1~instead.
  }
%    \end{macrocode}
%
%    \begin{macrocode} 
\NewDocumentEnvironment { pNiceArrayC } { }
  {
    \msg_info:nnn { nicematrix } { Obsolete~environment } 
      { the~option~'last-col' }
    \int_set:Nn \l_@@_last_col_int \c_zero_dim
    \pNiceArray
  }
  { \endpNiceArray }
%    \end{macrocode}
%
%    \begin{macrocode} 
\NewDocumentEnvironment { bNiceArrayC } { }
  {
    \msg_info:nnn { nicematrix } { Obsolete~environment } 
      { the~option~'last-col' }
    \int_set:Nn \l_@@_last_col_int \c_zero_dim
    \bNiceArray
  }
  { \endbNiceArray }
%    \end{macrocode}
%
%    \begin{macrocode} 
\NewDocumentEnvironment { BNiceArrayC } { }
  {
    \msg_info:nnn { nicematrix } { Obsolete~environment } 
      { the~option~'last-col' }
    \int_set:Nn \l_@@_last_col_int \c_zero_dim
    \BNiceArray
  }
  { \endBNiceArray }
%    \end{macrocode}
%
%    \begin{macrocode} 
\NewDocumentEnvironment { vNiceArrayC } { }
  {
    \msg_info:nnn { nicematrix } { Obsolete~environment } 
      { the~option~'last-col' }
    \int_set:Nn \l_@@_last_col_int \c_zero_dim
    \vNiceArray
  }
  { \endvNiceArray }
%    \end{macrocode}
%
%    \begin{macrocode} 
\NewDocumentEnvironment { VNiceArrayC } { }
  {
    \msg_info:nnn { nicematrix } { Obsolete~environment } 
      { the~option~'last-col' }
    \int_set:Nn \l_@@_last_col_int \c_zero_dim
    \VNiceArray
  }
  { \endVNiceArray }
%    \end{macrocode}
% 
%    \begin{macrocode} 
\NewDocumentEnvironment { pNiceArrayRC } { }
  {
    \msg_info:nnn { nicematrix } { Obsolete~environment } 
      { the~options~'last-col'~and~'first-row' } 
    \int_set:Nn \l_@@_last_col_int \c_zero_dim
    \int_set:Nn \l_@@_first_row_int \c_zero_int
    \pNiceArray
  }
  { \endpNiceArray }
%    \end{macrocode}
%
%    \begin{macrocode} 
\NewDocumentEnvironment { bNiceArrayRC } { }
  {
    \msg_info:nnn { nicematrix } { Obsolete~environment } 
      { the~options~'last-col'~and~'first-row' } 
    \int_set:Nn \l_@@_last_col_int \c_zero_dim
    \int_set:Nn \l_@@_first_row_int \c_zero_int
    \bNiceArray
  }
  { \endbNiceArray }
%    \end{macrocode}
%
%    \begin{macrocode} 
\NewDocumentEnvironment { BNiceArrayRC } { }
  {
    \msg_info:nnn { nicematrix } { Obsolete~environment } 
      { the~options~'last-col'~and~'first-row' } 
    \int_set:Nn \l_@@_last_col_int \c_zero_dim
    \int_set:Nn \l_@@_first_row_int \c_zero_int
    \BNiceArray
  }
  { \endBNiceArray }
%    \end{macrocode}
%
%    \begin{macrocode} 
\NewDocumentEnvironment { vNiceArrayRC } { }
  {
    \msg_info:nnn { nicematrix } { Obsolete~environment } 
      { the~options~'last-col'~and~'first-row' } 
    \bool_set_true:N \l_@@_last_col_bool
    \int_set:Nn \l_@@_first_row_int \c_zero_int
    \vNiceArray
  }
  { \endvNiceArray }
%    \end{macrocode}
%
%    \begin{macrocode} 
\NewDocumentEnvironment { VNiceArrayRC } { }
  {
    \msg_info:nnn { nicematrix } { Obsolete~environment } 
      { the~options~'last-col'~and~'first-row' } 
    \int_set:Nn \l_@@_last_col_int \c_zero_dim
    \int_set:Nn \l_@@_first_row_int \c_zero_int
    \VNiceArray
  }
  { \endVNiceArray }
%    \end{macrocode}
%
%    \begin{macrocode} 
\NewDocumentEnvironment { NiceArrayCwithDelims } { }
  {
    \msg_info:nnn { nicematrix } { Obsolete~environment } 
      { the~option~'last-col' }
    \int_set:Nn \l_@@_last_col_int \c_zero_dim
    \NiceArrayWithDelims
  }
  { \endNiceArrayWithDelims }
%    \end{macrocode}
%
%    \begin{macrocode} 
\NewDocumentEnvironment { NiceArrayRCwithDelims } { }
  {
    \msg_info:nnn { nicematrix } { Obsolete~environment } 
      { the~options~'last-col'~and~'first-row' } 
    \int_set:Nn \l_@@_last_col_int \c_zero_dim
    \int_set:Nn \l_@@_first_row_int \c_zero_int
    \NiceArrayWithDelims
  }
  { \endNiceArrayWithDelims }
%    \end{macrocode}
%
% 
% \vspace{1cm}
% \section{History}
%
% \subsection*{Changes between versions 1.0 and 1.1}
% 
% The dotted lines are no longer drawn with Tikz nodes but with Tikz circles
% (for efficiency). 
% 
% Modification of the code which is now twice faster.
%
% \subsection*{Changes between versions 1.1 and 1.2}
%
% New environment |{NiceArray}| with column types |L|, |C| and |R|.
%
% \subsection*{Changes between version 1.2 and 1.3}
%
% New environment |{pNiceArrayC}| and its variants.
%
% Correction of a bug in the definition of |{BNiceMatrix}|, |{vNiceMatrix}| and
% |{VNiceMatrix}| (in fact, it was a typo).
%
% Options are now available locally in |{pNiceMatrix}| and its variants. 
% 
% The names of the options are changed. The old names were names in ``camel
% style''. 
%
% \subsection*{Changes between version 1.3 and 1.4}
% 
% The column types |w| and |W| can now be used in the environments
% |{NiceArray}|, |{pNiceArrayC}| and its variants with the same meaning as in
% the package \pkg{array}. 
% 
% New option |columns-width| to fix the same width for all the columns of the
% array. 
% 
%
% \subsection*{Changes between version 1.4 and 2.0}
% 
% The versions 1.0 to 1.4 of \pkg{nicematrix} were focused on the continuous
% dotted lines whereas the version 2.0 of \pkg{nicematrix} provides different
% features to improve the typesetting of mathematical matrices. 
%
% \subsection*{Changes between version 2.0 and 2.1}
%
% New implementation of the environment |{pNiceArrayRC}|. With this new
% implementation, there is no restriction on the width of the columns.
%
% The package \pkg{nicematrix} no longer loads \pkg{mathtools} but only
% \pkg{amsmath}. 
%
% Creation of ``medium nodes'' and ``large nodes''.
%
% \subsection*{Changes between version 2.1 and 2.1.1}
%
% Small corrections: for example, the option |code-for-first-row| is now
% available in the command |\NiceMatrixOptions|. 
%
% Following a discussion on
% TeX StackExchange\footnote{cf.
% |tex.stackexchange.com/questions/450841/tikz-externalize-and-nicematrix-package|},  
% Tikz externalization is now deactivated in the environments of the
% extension \pkg{nicematrix}.\footnote{Before this version, there was an error
% when using \pkg{nicematrix} with Tikz externalization. In any case, it's not
% possible to externalize the Tikz elements constructed by \pkg{nicematrix}
% because they use the options |overlay| and |remember picture|.} 
% 
% \subsection*{Changes between version 2.1 and 2.1.2}
% Option |draft|: with this option, the dotted lines are not drawn (quicker).
%
% \subsection*{Changes between version 2.1.2 and 2.1.3}
%
% When searching the end of a dotted line from a command like |\Cdots| issued in
% the ``main matrix'' (not in the exterior column), the cells in the exterior
% column are considered as outside the matrix. That means that it's possible to
% do the following matrix with only a |\Cdots| command (and a single |\Vdots|).
% \[\begin{pNiceArray}{Wc{5mm}CWc{5mm}}[first-row,last-col]
% & C_j & \\
% \mbox{\Large $0$} & \Vdots & \mbox{\Large $0$} \\
%              & \strut a & \Cdots &  L_i \\
% \mbox{\Large $0$} &  & \mbox{\Large $0$} \\
% \end{pNiceArray}\]
%
% \subsection*{Changes between version 2.1.3 and 2.1.4}
%
% Replacement of some options |O { }| in commands and environments defined with
% \pkg{xparse} by |! O { }| (because a recent version of \pkg{xparse} introduced
% the specifier |!| and modified the default behaviour of the last optional
% arguments). 
%
% See |www.texdev.net/2018/04/21/xparse-optional-arguments-at-the-end|
%
% \subsection*{Changes between version 2.1.4 and 2.1.5}
%
% Compatibility with the classes \cls{revtex4-1} and \cls{revtex4-2}.
% 
% Option |allow-duplicate-names|.
%
% \subsection*{Changes between version 2.1.5 and 2.2}
%
% Possibility to draw horizontal dotted lines to separate rows with the command 
% |\hdottedline| (similar to the classical command |\hline| and the command
% |\hdashline| of \pkg{arydshln}). 
%
% Possibility to draw vertical dotted lines to separate columns with the
% specifier ``|:|'' in the preamble (similar to the classical specifier
% ``"|"'' and the specifier ``|:|'' of \pkg{arydshln}).
%
% \subsection*{Changes between version 2.2 and 2.2.1}
%
% Improvment of the vertical dotted lines drawn by the specifier ``:'' in the
% preamble. 
%
% Modification of the position of the dotted lines drawn by |\hdottedline|.
%
% \subsection*{Changes between version 2.2.1 and 2.3}
%
% Compatibility with the column type |S| of \pkg{siunitx}.
% 
% Option |hlines|.
% 
% A warning is issued when the |draft| mode is used. In this case, the dotted
% lines are not drawn.
%
%
% \subsection*{Changes between version 2.3 and 3.0}
%
% Modification of |\Hdotsfor|. Now |\Hdotsfor| erases the |\vlines| (of ``"|"'')
% as |\hdotsfor| does.
%
% Composition of exterior rows and columns on the four sides of the matrix (and
% not only on two sides) with the options |first-row|, |last-row|, |first-col|
% and |last-col|.
%
% \subsection*{Changes between version 3.0 and 3.1}
%
% Command |\Block| to draw block matrices.
% 
% Error message when the user gives an incorrect value for |last-row|.
%
% A dotted line can no longer cross another dotted line (except the dotted lines
% drawn by |\cdottedline|, the symbol |:| (in the preamble of the array) and
% |\line| in |code-after|. 
%
% The starred versions of |\Cdots|, |\Ldots|, etc. are now deprecated because,
% with the new implementation, they become pointless. These starred versions
% are no longer documented.
% 
% The vertical rules in the matrices (drawn by "|") are now compatible with
% the color fixed by \pkg{colortbl}.
%
% Correction of a bug: it was not possible to use the colon |:| in the preamble
% of an array when |pdflatex| was used with \pkg{french-babel} (because
% \pkg{french-babel} activates the colon in the beginning of the document).
% 
%
% \subsection*{Changes between version 3.1 and 3.2 (and 3.2a)}
%
% Option |small|.
%
% \subsection*{Changes between version 3.2 and 3.3}
%
% The options |first-row|, |last-row|, |first-col| and |last-col| are now
% available in the environments |{NiceMatrix}|, |{pNiceMatrix}|,
% |{bNiceMatrix}|, etc.
%
% The option |columns-width=auto| doesn't need any more a second compilation.
% 
% The options |renew-dots|, |renew-matrix| and |transparent| are now available
% as package options (as said in the documentation).
%
% The previous version of \pkg{nicematrix} was incompatible with a recent
% version of \pkg{expl3} (released 2019/09/30). This version is compatible.
%
%
% \subsection*{Changes between version 3.3 and 3.4}
%
% Following a discussion on TeX StackExchange\footnote{cf.
% |tex.stackexchange.com/questions/510841/nicematrix-and-tikz-external-optimize|}, 
% optimization of Tikz externalization is disabled in the environments of
% \pkg{nicematrix} when the class \cls{standalone} or the package
% \pkg{standalone} is used. 
% 
% \subsection*{Changes between version 3.4 and 3.5} 
%
% Correction on a bug on the two previous versions where the |code-after| was
% not executed.
% 
% \subsection*{Changes between version 3.5 and 3.6} 
%
% LaTeX counters |iRow| and |jCol| available in the cells of the array.
% 
% Addition of |\normalbaselines| before the construction of the array: in
% environments like |{align}| of \pkg{amsmath} the value of |\baselineskip| is
% changed and if the options |first-row| and |last-row| were used in an
% environment of \pkg{nicematrix}, the position of the delimiters was wrong.
% 
% A warning is written in the |.log| file if an obsolete environment is used.
%
% There is no longer artificial errors |Duplicate~name| in the environments of
% \pkg{amsmath}. 
% \PrintIndex
% 
% \tableofcontents
% \endinput
%
% Local Variables:
% TeX-fold-mode: t
% TeX-fold-preserve-comments: nil
% ispell-local-dictionary: english
% fill-column: 80
% End:

