path: root/macros/latex/contrib/nicematrix/nicematrix.tex

% -*- coding: utf-8 ; -*- This file should be compiled with XeLaTeX only
\documentclass[dvipsnames]{article}% dvipsnames is for xcolor (loaded by TikZ,
                                   % loaded by nicematrix) 

\usepackage{geometry}
\geometry{left=2.8cm,right=2.8cm,top=2.5cm,bottom=2.5cm,papersize={21cm,29.7cm}}

\usepackage{nicematrix}

\usepackage{tikz}
\usetikzlibrary{fit,patterns,arrows.meta,decorations.pathmorphing}

\usepackage{enumitem}
\usepackage{siunitx}
\usepackage{verbatim}
\usepackage{caption}
\usepackage{tocloft}
\setlength{\cftsubsecnumwidth}{3em} % for the numbers of subsections of the TOC

% We use \MakeShortVerb of shortvrb and not \DefineShortVerb of fancyvrb
% because we don't want small elements in verbatim to be colored in gray
\usepackage{shortvrb}
\MakeShortVerb{\|}

\usepackage{fancyvrb}
\fvset{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}


\def\interitem{\vspace{7mm plus 2 mm minus 3mm}}
\def\emphase{\bgroup\color{RoyalPurple}\let\next=}

\usepackage{footnote}
\usepackage{booktabs}
\usepackage{varwidth}
\usepackage{tcolorbox}
\usepackage{adjustbox}
\usepackage[auto-lang=false]{lipsum}

\NewDocumentEnvironment {scope} {} {} {}

\NewDocumentCommand {\pkg} {m} {\textsf{#1}}
\NewDocumentCommand {\cls} {m} {\textsf{#1}}

\setlength{\parindent}{0pt}
\skip \footins = 2 \bigskipamount


\NewDocumentCommand{\Definition}{m}
  {{\setlength{\fboxsep}{1pt}\colorbox{gray!20}{\ttfamily \vphantom{gl}#1}}}

\NewDocumentCommand{\DefinitionCommand}{m}
  {{\setlength{\fboxsep}{1pt}\colorbox{gray!20}{\ttfamily
        \vphantom{gl}\textbackslash #1}}}


\usepackage{makeidx}
\makeindex


\usepackage{piton}
\PitonOptions{language = minimal, detected-commands = {emph,textsl}, splittable = 4}
\SetPitonStyle{ Number = , Comment = }

\ExplSyntaxOn

\dim_new:N \l__pantigny_width_dim 

\keys_define:nn { pantigny }
  { width .dim_set:N = \l__pantigny_width_dim }

\NewPitonEnvironment { Code } { O { } }
  { 
    \char_set_catcode_other:N |
    \cs_set_eq:NN \emph \emphase
    \dim_zero:N \l__pantigny_width_dim 
    \keys_set:nn { pantigny } { #1 }
    \color{gray}
    \dim_compare:nNnT \l__pantigny_width_dim > \c_zero_dim 
      { 
        \PitonOptions { width = \l__pantigny_width_dim } 
        \begin{minipage}[c]{\l__pantigny_width_dim} 
      }
  }
  { \dim_compare:nNnT \l__pantigny_width_dim > \c_zero_dim 
      { \end{minipage} }
  }


\ExplSyntaxOff  


\NewDocumentCommand{\indexcommand}{m}{\index{#1@\texttt{\textbackslash #1}}}

\NewDocumentCommand{\indexenv}{m}{\index{#1@\texttt{\{#1\}}}}

\usepackage[hyperfootnotes = false]{hyperref}

\hypersetup
  {
    pdfinfo = 
     {
       Title = The package 'nicematrix' ,
       Subject = A LaTeX package ,
       Author = F. Pantigny 
     }
  }



\begin{document}

\VerbatimFootnotes


\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}}


\maketitle

\begin{abstract}
The LaTeX package \pkg{nicematrix} provides new environments similar to the
classical environments |{tabular}|, |{array}| and |{matrix}| of \pkg{array}
and \pkg{amsmath} but with extended features. 
\end{abstract}




\vspace{1cm}
\hspace{1cm}
$\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}$\hspace{2cm}
\begin{NiceTabular}{lSSSS}[code-before = \rowcolor{red!15}{1-2} \rowcolors{3}{blue!15}{}]
\toprule
\Block{2-1}{Product} & \multicolumn{3}{c}{dimensions (cm)} & \Block{2-1}{\rotate Price} \\
\cmidrule(rl){2-4} 
 & L & l & h \\
\midrule
small    & 3   & 5.5  & 1   & 30    \\
standard & 5.5 & 8    & 1.5 & 50.5  \\
premium  & 8.5 & 10.5 & 2   & 80    \\
extra    & 8.5 & 10   & 1.5 & 85.5  \\
special  & 12  & 12   & 0.5 & 70    \\
\bottomrule
\end{NiceTabular}

\vspace{1cm}
The package \pkg{nicematrix} is entirely contained in the file
|nicematrix.sty|. This file may be put in the current directory or in a
|texmf| tree. However, the best is to install \pkg{nicematrix} with a TeX
distribution such as MiKTeX, TeX Live or MacTeX.

\medskip
\emph{Remark}\par\nobreak

If you use LaTeX via Internet with, for example, Overleaf, you
can upload the file |nicematrix.sty| in the repertory of your 
project in order to take full advantage of the latest version de
\pkg{nicematrix}.\footnote{The latest version of the file
|nicematrix.sty| may be downloaded from the \textsc{svn} server of
TeXLive:\newline
\small
\url{https:www.tug.org/svn/texlive/trunk/Master/texmf-dist/tex/latex/nicematrix/nicematrix.sty}}

\medskip
This package can be used with |xelatex|, |lualatex|, |pdflatex| but also by
the classical workflow |latex|-|dvips|-|ps2pdf| (or Adobe Distiller).
\textsl{However, the file nicematrix.dtx of the present documentation should
be compiled with XeLaTeX.}

\medskip
This package requires and \textbf{loads} the packages \pkg{l3keys2e},
\pkg{array}, \pkg{amsmath}, \pkg{pgfcore} and the module \pkg{shapes} of
\textsc{pgf} (\pkg{tikz}, which is a layer over \textsc{pgf}, is \emph{not}
loaded). The final user only has to load the package with
|\usepackage{nicematrix}|.


\medskip
The idea of \pkg{nicematrix} is to create \textsc{pgf} nodes under the cells
and the positions of the rules of the tabular created by \pkg{array} and to
use these nodes to develop new features. As usual with \textsc{pgf}, the
coordinates of these nodes are written in the |aux| to be used on the next
compilation and that's why \pkg{nicematrix} may need \textbf{several
compilations}.\footnote{If you use Overleaf, Overleaf will do automatically
a sufficient number of compilations.}

\medskip
Most features of \pkg{nicematrix} may be used without explicit use of
\textsc{pgf} or TikZ (which, in fact, is not loaded by default).

\medskip
\indexcommand{NiceMatrixOptions}
A command |\NiceMatrixOptions| is provided to fix the options (the
scope of the options fixed by this command is the current TeX group: they are
semi-global). 



\newpage

\section{The environments of this package} 

The package \pkg{nicematrix} defines the following new environments.

\medskip
\begin{ttfamily}
\setlength{\tabcolsep}{3mm}
\begin{tabular}{llll}
\{NiceTabular\}  & \{NiceArray\}  & \{NiceMatrix\}   \\
\{NiceTabular*\} & \{pNiceArray\} & \{pNiceMatrix\}  \\
\{NiceTabularX\} & \{bNiceArray\} & \{bNiceMatrix\}  \\
                 & \{BNiceArray\} & \{BNiceMatrix\}  \\
                 & \{vNiceArray\} & \{vNiceMatrix\}  \\
                 & \{VNiceArray\} & \{VNiceMatrix\}  
\end{tabular}
\end{ttfamily}

%
\medskip
The environments |{NiceArray}|, |{NiceTabular}| and |{NiceTabular*}| are
similar to the environments |{array}|, |{tabular}| and |{tabular*}| of the
package \pkg{array} (which is loaded by \pkg{nicematrix}).

\medskip
The environments |{pNiceArray}|, |{bNiceArray}|, etc. have no equivalent in
\pkg{array}. 

\medskip
The environments |{NiceMatrix}|, |{pNiceMatrix}|, etc. are similar to the
corresponding environments of \pkg{amsmath} (which is loaded by
\pkg{nicematrix}): |{matrix}|, |{pmatrix}|, etc. 

\medskip
The environment |{NiceTabularX}| is similar to the environment |{tabularx}|
from the eponymous package.\footnote{In fact, it's possible to use directly the
|X| columns in the environment |{NiceTabular}| (and the required
width for the tabular is fixed by the key |width|): cf. p.~\pageref{X-columns}}.

\medskip
\textbf{It's recommended to use primarily the classical environments and to use the
environments of \pkg{nicematrix} only when some feature provided by these
environments is used (this will save memory).}

\medskip 
All the environments of the package \pkg{nicematrix} accept, between square
brackets, an optional list of \textsl{key=value} pairs. \textbf{There must be
no space before the opening bracket (|[|) of this list of options.}


\section{The vertical space between the rows}

\label{cell-space}
\index{cell-space-top-limit}
\index{cell-space-bottom-limit}
\index{cell-space-limits}


It's well known that some rows of the arrays created by default with LaTeX
are, by default, too close to each other. Here is a classical example.

\medskip
\begin{Code}[width=9cm]
$\begin{pmatrix}
\frac{1}{2} & -\frac{1}{2} \\
\frac{1}{3} & \frac{1}{4} \\
\end{pmatrix}$
\end{Code}
$\begin{pmatrix}
\frac{1}{2} & -\frac{1}{2} \\
\frac{1}{3} & \frac{1}{4} \\
\end{pmatrix}$

\bigskip
Inspired by the package \pkg{cellspace} which deals with that problem, the
package \pkg{nicematrix} provides two keys |cell-space-top-limit| and
|cell-space-bottom-limit| similar to the parameters of \pkg{cellspace} called
|\cellspacetoplimit| and
|\cellspacebottomlimit|.\index{cellspace@\pkg{cellspace} (package)}

There is also a key |cell-space-limits| to set both parameters at once.

The initial value of these parameters is $0$~pt in order to have for the
environments of \pkg{nicematrix} the same behaviour as those of \pkg{array}
and \pkg{amsmath}. However, a value of $1$~pt would probably be a good choice
and we suggest to set them with |\NiceMatrixOptions|.\footnote{One should
remark that these parameters apply also to the columns of type |S| of
\pkg{siunitx} whereas the package \pkg{cellspace} is not able to act on such
columns of type~|S|.}

\medskip
\begin{Code}
\NiceMatrixOptions{\emph{cell-space-limits = 1pt}}
\end{Code}

\begin{Code}[width=9cm]
$\begin{pNiceMatrix}
\frac12 & -\frac12 \\
\frac13 & \frac14 \\
\end{pNiceMatrix}$
\end{Code}
\begin{scope}
\NiceMatrixOptions{cell-space-limits = 1pt}
$\begin{pNiceMatrix}
\frac12 & -\frac12 \\
\frac13 & \frac14 \\
\end{pNiceMatrix}$
\end{scope}

\bigskip
It's also possible to change these parameters for only a few rows by using the 
command |\RowStyle| provided by \pkg{nicematrix} (cf.~p.~\pageref{RowStyle}).



\bigskip
\section{The vertical position of the arrays}

\index{baseline (key for an environment)}

The package \pkg{nicematrix} provides a option |baseline| for the vertical
position of the arrays. This option takes in as value an integer which is the
number of the row on which the array will be aligned.

\medskip
\begin{Code}[width=9cm]
$A = \begin{pNiceMatrix}[\emph{baseline=2}]
\frac{1}{\sqrt{1+p^2}} & p & 1-p \\
1 & 1 & 1 \\
1 & p & 1+p
\end{pNiceMatrix}$
\end{Code}
$A = \begin{pNiceMatrix}[baseline=2]
\frac{1}{\sqrt{1+p^2}} & p & 1-p \\
1 & 1 & 1 \\
1 & p & 1+p
\end{pNiceMatrix}$


\medskip
It's also possible to use the option |baseline| with one of the special values
|t|, |c| or |b|. These letters may also be used absolutely like the option of
the environments |{tabular}| and |{array}| of \pkg{array}. The initial value
of |baseline| is~|c|. 


\medskip
In the following example, we use the option |t| (equivalent to |baseline=t|)
immediately after an |\item| of list. One should remark that the presence of a
|\hline| at the beginning of the array doesn't prevent the alignment of the
baseline with the baseline of the first row (with |{tabular}| or |{array}| of
\pkg{array}, one must use |\firsthline|).

\medskip
\begin{Code}[width=9cm]
\begin{enumerate}
\item an item
\smallskip
\item \renewcommand{\arraystretch}{1.2}
$\begin{NiceArray}\emph{[t]}{lcccccc}
\hline
n   & 0 & 1 & 2 & 3 & 4  & 5 \\
u_n & 1 & 2 & 4 & 8 & 16 & 32 
\hline
\end{NiceArray}$
\end{enumerate}
\end{Code}
\begin{minipage}{5cm}
\begin{enumerate}
\item an item
\smallskip
\item \renewcommand{\arraystretch}{1.2}
$\begin{NiceArray}[t]{lcccccc}
\hline
n   & 0 & 1 & 2 & 3 & 4  & 5  \\
u_n & 1 & 2 & 4 & 8 & 16 & 32 \\
\hline
\end{NiceArray}$
\end{enumerate}
\end{minipage}

\medskip
However, it's also possible to use the tools of
\pkg{booktabs}\footnote{The extension \pkg{booktabs} is \emph{not} loaded
by \pkg{nicematrix}.}: |\toprule|,
|\bottomrule|, |\midrule|, etc.\par\nobreak

\smallskip
\begin{Code}[width=9cm]
\begin{enumerate}
\item an item
\smallskip
\item 
$\begin{NiceArray}[t]{lcccccc}
\emph{\toprule}
n   & 0 & 1 & 2 & 3 & 4  & 5 \\
\emph{\midrule}
u_n & 1 & 2 & 4 & 8 & 16 & 32 
\emph{\bottomrule}
\end{NiceArray}$
\end{enumerate}
\end{Code}
\begin{minipage}{5cm}
\begin{enumerate}
\item an item
\smallskip
\item 
$\begin{NiceArray}[t]{lcccccc}
\toprule
n   & 0 & 1 & 2 & 3 & 4  & 5  \\
\midrule
u_n & 1 & 2 & 4 & 8 & 16 & 32 \\
\bottomrule
\end{NiceArray}$
\end{enumerate}
\end{minipage}

\bigskip
It's also possible to use the key |baseline| to align a matrix on an
horizontal rule (drawn by |\hline|). In this aim, one should give the value
|line-|\textsl{i} where \textsl{i} is the number of the row \emph{following} the
horizontal rule.

\smallskip
\begin{Verbatim}
\NiceMatrixOptions{cell-space-limits=1pt}
\end{Verbatim}

\smallskip
\begin{Code}[width=9cm]
$A=\begin{pNiceArray}{cc|cc}\emph{[baseline=line-3]}
\dfrac{1}{A} & \dfrac{1}{B} & 0 & 0 \\
\dfrac{1}{C} & \dfrac{1}{D} & 0 & 0 \\
\hline
0 & 0 & A & B \\
0 & 0 & D & D \\
\end{pNiceArray}$
\end{Code}
\begin{scope}
\NiceMatrixOptions{cell-space-limits=1pt}
\raisebox{-5mm}{$A=\begin{pNiceArray}{cc|cc}[baseline=line-3]
\dfrac{1}{A} & \dfrac{1}{B} & 0 & 0 \\
\dfrac{1}{C} & \dfrac{1}{D} & 0 & 0 \\
\hline
0 & 0 & A & B \\
0 & 0 & D & D \\
\end{pNiceArray}$}
\end{scope}


\section{The blocks}
\label{Block}

\index{Blocks@\textbf{Blocks in the tabulars}|(}
\indexcommand{Block}


\subsection{General case}

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.\footnote{The spaces after a command |\Block| are deleted.}

The command |\Block| must be used in the upper leftmost cell of the cells of the
block with two mandatory arguments. 

\begin{itemize}
\item The first argument is the size of the block with the syntax
$i$|-|$j$ where $i$ is the number of rows of the block and $j$ its number
of columns. 

If this argument is empty, its default
value is |1-1|. If the number of rows is not specified, or equal to |*|, the
block extends until the last row (idem for the columns).

\item The second argument is the content of the block. In |{NiceTabular}|,
|{NiceTabular*}| and |{NiceTabularX}|, the content of the block is composed in
text mode whereas, in the other environments, it is composed in math mode.
\end{itemize}


\interitem
Here is an example of utilisation of the command |\Block| in mathematical matrices.

\medskip
\begin{Code}[width=10.6cm]
$\begin{bNiceArray}{cw{c}{1cm}c|c}[margin]
\emph{\Block{3-3}{A}} & & & 0 \\
& & & \Vdots \\
& & & 0 \\
\hline
0 & \Cdots& 0 & 0
\end{bNiceArray}$
\end{Code}
$\begin{bNiceArray}{cw{c}{1cm}c|c}[margin]
\Block{3-3}{A} & & & 0 \\
& & & \Vdots \\
& & & 0 \\
\hline
0 & \Cdots& 0 & 0
\end{bNiceArray}$

\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
specify some TeX code which will be inserted before the beginning of the
math mode.\footnote{This argument between angular brackets may also be used to
insert a command of font such as |\bfseries| when the command |\\| is used in
the content of the block. It's also possible to put in that optional argument
the command |\rotate| provided by \pkg{nicematrix} (cf. part~\ref{rotate},
p.~\pageref{rotate}).} 

\medskip
\begin{Code}[width=10.6cm]
$\begin{bNiceArray}{cw{c}{1cm}c|c}[margin]
\Block{3-3}\emph{<\Large>}{A} & & & 0 \\
0 & & & \Vdots \\
& & & 0 \\
\hline
0 & \Cdots& 0 & 0
\end{bNiceArray}$
\end{Code}
\begin{scope}
$\begin{bNiceArray}{cw{c}{1cm}c|c}[margin]
\Block{3-3}<\Large>{A} & & & 0 \\
& & & \Vdots \\
& & & 0 \\
\hline
0 & \Cdots& 0 & 0
\end{bNiceArray}$
\end{scope}



\interitem
In fact, the command |\Block| accepts as first optional argument (between
square brackets) a list of couples \textsl{key=value}. 

First, there are keys which are quick tools to control the apperance of the block.

\begin{itemize}
\item \index{fill (key of \texttt{\textbackslash Block})}
the key \Definition{fill} takes in as value a color and fills the block
with that color;
\item \index{opacity  (key of \texttt{\textbackslash Block})} 
the key \Definition{opacity} sets the opacity of the filling color specified by
|fill|; 
\item \index{draw (key of \texttt{\textbackslash Block})}
the key \Definition{draw} takes in as value a color and strokes the
frame of the block with that color (the default value of that key is the
current color of the rules of the array);
\item \index{color!key of \texttt{\textbackslash Block}} 
the key \Definition{color} takes in as value a color and apply that
color the content of the block but draws also the frame of the block with that
color;
\item \index{vlines!key of \texttt{\textbackslash Block}} 
\index{hvlines!key of \texttt{\textbackslash Block}} 
\index{hlines!key of \texttt{\textbackslash Block}}
the keys \Definition{hlines}, \Definition{vlines} and
\Definition{hvlines} draw all the corresponding rules in the
block;\footnote{However, the rules are not drawn in the sub-blocks of the
block, as always with \pkg{nicematrix}: the rules are not drawn in the blocks,
except when they have the key |transparent|
(cf. section~\ref{rules} p.~\pageref{rules}).}
\item \index{line-width (key of \texttt{\textbackslash Block})}
the key \Definition{line-width} is the width of the rules (is relevant
only when one of the keys |draw|, |hvlines|, |vlines| and |hlines| is used);
\item \index{rounded-corners!key of \texttt{\textbackslash Block}}
\index{Corners (rounded ---)!for a block} 
the key \Definition{rounded-corners} requires rounded corners (for the
frame drawn by |draw| and the shape drawn by |fill|) with a radius equal to
the value of that key (the default value is 4~pt\footnote{This value is the
initial value of the \emph{rounded corners} of TikZ.}).
\end{itemize}

\medskip
Sometimes, these tools are not sufficient to control the appearance of the
block. The following keys are more powerful but also more difficult to use.
Moreover, the require the loading of TikZ by the user (with
|\usepackage{tikz}|). By default, \pkg{nicematrix} does not load TikZ but only
\textsc{pgf}, which is a sublayer of TikZ.

\begin{itemize}
\item \index{borders (key of \texttt{\textbackslash Block})}
\index{tikzz@tikz!key of ``borders'' de \texttt{\textbackslash Block}}
The key \Definition{borders} provides the ability to draw only some
borders of the blocks; the value of that key is a (comma-separated) list of
elements covered by |left|, |right|, |top| and |bottom|; it's possible, in
fact, in the list which is the value of the key |borders|, to add an entry of
the form |tikz={|\textsl{list}|}| where \textsl{list} is a list of couples
\textsl{key=value} of TikZ specifying the graphical characteristics of the
lines that will be drawn (for an example, see p.~\pageref{dashed}).

\item \index{tikzz@tikz!key of \texttt{\textbackslash Block}}
When the key \Definition{tikz} is used, the TikZ path corresponding of
the rectangle which delimits the block is executed with TikZ\footnote{TikZ
should be loaded (by default, \pkg{nicematrix} only loads \textsc{pgf}) and,
if it's not, an error will be raised.} by using as options the value of that
key |tikz| (which must be a list of keys allowed for a TikZ path). 

In fact, in the list of the keys provided by the user as value of |tikz|, it's
possible to put a key \Definition{offset}. That key is not provided by TikZ but
by \pkg{nicematrix}. It will narrow the rectangular frame corresponding to the
block by a margin (horizontally and vertically) equal to the value (of that key
|offset|). That new frame, a bit narrower, will be executed by TikZ with options
which are the other keys in the list of keys provided as value to the key |tikz|
of |\Block|.

For examples, cf. p.~\pageref{tikz-key-examples}.
\end{itemize}


\medskip
There is also some technical keys:

\begin{itemize}
\item \index{name!key of \texttt{\textbackslash Block}}
the key \Definition{name} provides a name to the rectangular TikZ node
corresponding to the block; it's possible to use that name with TikZ in the
|\CodeAfter| of the environment (cf.~p.~\pageref{code-after});
\item \index{respect-arraystretch (key of \texttt{\textbackslash Block})}
the key \Definition{respect-arraystretch} prevents the setting of
|\arraystretch| to $1$ at the beginning of the block (which is the behaviour
by default) ;
\item \index{transparent (key of \texttt{\textbackslash Block})}
By default, the rules are not drawn in the blocks (see the section about
the rules: section~\ref{rules} p.~\pageref{rules}). However, if the key
\Definition{transparent} is used, the rules are drawn. For an example, see
section~\ref{tikz-key-examples} on page~\pageref{tikz-key-examples}. Caution:
that key does not imply that the content of the block will be transparent!
\end{itemize}

There is also keys for the horizontal and vertical positions of the content of
the block: cf.~\ref{horizontal-block} p.~\pageref{horizontal-block}.

\interitem
{\bfseries One must remark that, by default, the commands |\Blocks| don't create
  space}. There is exception only for the blocks mono-column and the blocks
mono-row under some conditions as explained just below.

\medskip
In the following example, we have had to enlarge by hand the columns 2 and 3
(with the construction |w{c}{...}| of \pkg{array}).

\bigskip
\begin{Code}
\begin{NiceTabular}{cw{c}{2cm}w{c}{3cm}c}
rose      & tulip & daisy & dahlia \\
violet  & \emph{\Block[draw=red,fill=[RGB]{204,204,255},rounded-corners]{2-2}
                {\LARGE Some beautiful flowers}} & & marigold \\
   & & marigold \\
iris & & & lis \\
arum & periwinkle & forget-me-not &  hyacinth
\end{NiceTabular}
\end{Code}

\medskip
\begin{center}
\begin{NiceTabular}{cw{c}{2cm}w{c}{3cm}c}
rose      & tulip & daisy & dahlia \\
violet  & \Block[draw=red,fill=[RGB]{204,204,255},rounded-corners]{2-2}
  {\LARGE Some beautiful flowers} & & marigold \\
 iris & & & lis \\
 arum      & periwinkle & forget-me-not & hyacinth 
\end{NiceTabular}
\end{center}

\subsection{The mono-column blocks}

The mono-column blocks have a special behaviour.

\begin{itemize}
\item The natural width of the contents of these blocks is taken into account
for the width of the current column.

In the columns with a fixed width (columns |w{...}{...}|, |W{...}{...}|,
|p{...}|, |b{...}|, |m{...}|, |V| and |X|), the content of the block is
formatted as a paragraph of that width.

\item The specification of the horizontal position provided by the type of
column (|c|, |r| or |l|) is taken into account for the blocks. For a block in a
column ot type |p{...}| (without option for |p|) , the alignment |c| will be
used for the block. Of course, the |\Block| may have its own specification of
alignment: cf.~\ref{horizontal-block} p.~\pageref{horizontal-block}.

\item The specifications of font specified for the column by a construction
|>{...}| in the preamble of the array are taken into account for the
mono-column blocks of that column (this behaviour is probably expected).
\end{itemize}


\bigskip
\begin{scope}
\hfuzz=10cm
\begin{Code}[width=12cm]
\begin{NiceTabular}{@{}>{\bfseries}lr@{}} \hline
\Block{2-1}{John}    & 12 \\
                     & 13 \\ \hline
Steph                &  8 \\ \hline
\Block{3-1}{Sarah}   & 18 \\
                     & 17 \\
                     & 15 \\ \hline
Ashley               & 20 \\ \hline
Henry                & 14 \\ \hline
\Block{2-1}{Madison} & 15 \\
                     & 19 \\ \hline
\end{NiceTabular}
\end{Code}
\begin{NiceTabular}{@{}>{\bfseries}lr@{}}[baseline=c] \hline
\Block{2-1}{John}    & 12 \\
                     & 13 \\ \hline
Steph                &  8 \\ \hline
\Block{3-1}{Sarah}   & 18 \\
                     & 17 \\
                     & 15 \\ \hline
Ashley               & 20 \\ \hline
Henry                & 14 \\ \hline
\Block{2-1}{Madison} & 15 \\
                     & 19 \\ \hline
\end{NiceTabular}
\end{scope}


\subsection{The mono-row blocks}

For the mono-row blocks, the natural height and depth are taken into account
for the height and depth of the current row (as does a standard |\multicolumn|
of LaTeX), except when an option of vertical position has been used for the block
(one of the keys |t|, |b|, |m|, |T| and |B| described in the part
\ref{vertical-pos-block}, p.~\pageref{vertical-pos-block}).

\subsection{The mono-cell blocks}

A mono-cell block inherits all the properties of the mono-row blocks and
mono-column blocks.

\medskip
At first sight, one may think that there is no point using a mono-cell block.
However, there are some good reasons to use such a block.
\begin{itemize}
\item It's possible to use the command |\\| in a (mono-cell) block.

\item It's possible to use the option of horizontal alignment of the block in
derogation of the type of column given in the preamble of the array.

\item It's possible do draw a frame around the cell with the key |draw| of the
command |\Block| and to fill the background with rounded corners with the keys
|fill| and |rounded-corners|.\footnote{If one simply wishes to color the
background of a unique cell, there is no point using the command |\Block|:
it's possible to use the command |\cellcolor| (when the key |color-inside| is
used).}

\item It's possible to draw one or several borders of the cell with the key |borders|.
\end{itemize}

\bigskip
\begin{Code}[width=10cm]
\begin{NiceTabular}{cc}
\toprule
Writer & \emph{\Block[l]{}{year\\ of birth}} \\
\midrule
Hugo & 1802 \\
Balzac & 1799 \\
\bottomrule
\end{NiceTabular}
\end{Code}
\begin{NiceTabular}{cc}
\toprule
Writer & \Block[l]{}{year\\ of birth} \\
\midrule
Hugo & 1802 \\
Balzac & 1799 \\
\bottomrule
\end{NiceTabular}

\medskip
We recall that if the first mandatory argument of |\Block| is left blank, the
block is mono-cell.\footnote{One may consider that the default value of the
first mandatory argument of |\Block| is |1-1|.}




\subsection{Horizontal position of the content of the block}

\label{horizontal-block}

The command |\Block| accepts the keys \Definition{l}, \Definition{c} and
\Definition{r} for the horizontal position of its content.

\medskip
\begin{Code}[width=10.6cm]
$\begin{bNiceArray}{cw{c}{1cm}c|c}[margin]
\Block\emph{[r]}{3-3}<\LARGE>{A} & & & 0 \\
& & & \Vdots \\
& & & 0 \\
\hline
0 & \Cdots& 0 & 0
\end{bNiceArray}$
\end{Code}
$\begin{bNiceArray}{cw{c}{1cm}c|c}[margin]
\Block[r]{3-3}<\LARGE>{A} & & & 0 \\
& & & \Vdots \\
& & & 0 \\
\hline
0 & \Cdots& 0 & 0
\end{bNiceArray}$


\medskip
By default, the horizontal position of the content of a block is computed
by using the positions of the \emph{contents} of the columns implied in that
block. That's why, in the following example, the header ``First group'' is
correctly centered despite the instruction |!{\qquad}| in the preamble which
has been used to increase the space between the columns (this
is not the behaviour of |\multicolumn|).

\medskip
\begin{center}
\begin{Code}
\begin{NiceTabular}{@{}c!{\qquad}ccc\emph{!{\qquad}}ccc@{}}
\toprule
Rank & \emph{\Block{1-3}{First group}} & & & \Block{1-3}{Second group} \\
     & 1A & 1B & 1C & 2A & 2B & 2C \\
\midrule
 1 & 0.657 & 0.913 & 0.733 & 0.830 & 0.387 & 0.893\\
 2 & 0.343 & 0.537 & 0.655 & 0.690 & 0.471 & 0.333\\
 3 & 0.783 & 0.885 & 0.015 & 0.306 & 0.643 & 0.263\\
 4 & 0.161 & 0.708 & 0.386 & 0.257 & 0.074 & 0.336\\
\bottomrule
\end{NiceTabular}
\end{Code}
\end{center}

\bigskip
\begin{center}
\begin{NiceTabular}{@{}c!{\qquad}ccc!{\qquad}ccc@{}}
\toprule
Rank & \Block{1-3}{First group} & & & \Block{1-3}{Second group} \\
     & 1A & 1B & 1C & 2A & 2B & 2C \\
\midrule
 1 & 0.657 & 0.913 & 0.733 & 0.830 & 0.387 & 0.893\\
 2 & 0.343 & 0.537 & 0.655 & 0.690 & 0.471 & 0.333\\
 3 & 0.783 & 0.885 & 0.015 & 0.306 & 0.643 & 0.263\\
 4 & 0.161 & 0.708 & 0.386 & 0.257 & 0.074 & 0.336\\
\bottomrule
\end{NiceTabular}
\end{center}

\medskip
In order to have an horizontal positionning of the content of the block computed
with the limits of the columns of the LaTeX array (and not with the contents of
those columns), one may use the key \Definition{L}, \Definition{R} and
\Definition{C} of the command |\Block|.

\medskip
Here is the same example with the key |C| for the first block.

\medskip
\begin{center}
\begin{Code}
\begin{NiceTabular}{@{}c!{\qquad}ccc\emph{!{\qquad}}ccc@{}}
\toprule
Rank & \emph{\Block[C]{1-3}{First group}} & & & \Block{1-3}{Second group} \\
     & 1A & 1B & 1C & 2A & 2B & 2C \\
\midrule
 1 & 0.657 & 0.913 & 0.733 & 0.830 & 0.387 & 0.893\\
 2 & 0.343 & 0.537 & 0.655 & 0.690 & 0.471 & 0.333\\
 3 & 0.783 & 0.885 & 0.015 & 0.306 & 0.643 & 0.263\\
 4 & 0.161 & 0.708 & 0.386 & 0.257 & 0.074 & 0.336\\
\bottomrule
\end{NiceTabular}
\end{Code}
\end{center}

\bigskip
\begin{center}
\begin{NiceTabular}{@{}c!{\qquad}ccc!{\qquad}ccc@{}}
\toprule
Rank & \Block[C]{1-3}{First group} & & & \Block{1-3}{Second group} \\
     & 1A & 1B & 1C & 2A & 2B & 2C \\
\midrule
 1 & 0.657 & 0.913 & 0.733 & 0.830 & 0.387 & 0.893\\
 2 & 0.343 & 0.537 & 0.655 & 0.690 & 0.471 & 0.333\\
 3 & 0.783 & 0.885 & 0.015 & 0.306 & 0.643 & 0.263\\
 4 & 0.161 & 0.708 & 0.386 & 0.257 & 0.074 & 0.336\\
\bottomrule
\end{NiceTabular}
\end{center}


\bigskip
\colorbox{yellow!50}{\bfseries New 6.28}\par\nobreak

\smallskip
The command |\Block| supports also a key |p|. With that key, the content of the
block is formatted like a paragraph (as in a column of type |p|). That key may
be used in conjunction with the key |l|, |c| or |r|, and, in that case, the
paragraph is formatted with |\raggedright|, |\centering| or |\raggedleft|. With
the key |j|, the paragraph is justified.

\subsection{Vertical position of the content of the block}

\label{vertical-pos-block}

For the vertical position, the command |\Blocks| accepts the keys
|m|, |t|, |b|, |T| and |B|.


\begin{itemize}
\item \index{v-center (key of \texttt{\textbackslash Block})}
With the key \Definition{m}\footnote{That key has an alias: |v-center|.}, the content of the block is vertically centered.
\item With the key \Definition{t}, the baseline of the content of the block is aligned
with the baseline of the first row concerned by the block.
\item with the key \Definition{b}, the baseline of the last row of the content of the
block (we recall that the content of a block may contains several lines
separated by |\\|) is aligned with the baseline of the last of the rows of the
array involved in the block.
\item With the key \Definition{T}, the content of the block is set upwards. 

No vertical margin is added. However, the contents of the block is (always)
composed by \pkg{nicematrix} in a |{minipage}|, a |{tabular}| or an |{array}|
and, hence, there will still remain a margin (in most cases). If needed, it's
always possible to add a |\strut|...

\item With the key \Definition{B}, the content of the block is set downwards.
\end{itemize}

When no key is given, the key |m| applies (except in the mono-row blocks).



\medskip
\begin{scope}
\NiceMatrixOptions{rules/color=[gray]{0.75}, hvlines}

\begin{BVerbatim}
\NiceMatrixOptions{rules/color=[gray]{0.75}, hvlines}
\end{BVerbatim}

\bigskip

\begin{Code}[width=10cm]
\begin{NiceTabular}{ccc}
\Block[fill=red!10,\emph{t},l]{4-2}{two\\lines}
 & & \Huge Un\\
 & & deux  \\
 & & trois  \\
 & & \Huge quatre  \\
text & text \\
\end{NiceTabular}
\end{Code}
\begin{NiceTabular}{ccc}
\Block[fill=red!10,t,l]{4-2}{two\\lines}
 & & \Huge Un\\
 & & deux  \\
 & & trois  \\
 & & \Huge quatre  \\
text & text \\
\end{NiceTabular}


\bigskip
\begin{Code}[width=10cm]
\begin{NiceTabular}{ccc}
\Block[fill=red!10,\emph{b},r]{4-2}{two\\lines}
 & & \Huge Un\\
 & & deux  \\
 & & trois  \\
 & & \Huge quatre  \\
text & text \\
\end{NiceTabular}
\end{Code}
\begin{NiceTabular}{ccc}
\Block[fill=red!10,b,r]{4-2}{two\\lines}
 & & \Huge Un\\
 & & deux  \\
 & & trois  \\
 & & \Huge quatre  \\
text & text \\
\end{NiceTabular}

\bigskip
\begin{Code}[width=10cm]
\begin{NiceTabular}{ccc}
\Block[fill=red!10,\emph{T},l]{4-2}{two\\lines}
 & & \Huge Un\\
 & & deux  \\
 & & trois  \\
 & & \Huge quatre  \\
text & text \\
\end{NiceTabular}
\end{Code}
\begin{NiceTabular}{ccc}
\Block[fill=red!10,T,l]{4-2}{two\\lines}
 & & \Huge Un\\
 & & deux  \\
 & & trois  \\
 & & \Huge quatre  \\
text & text \\
\end{NiceTabular}


\bigskip
\begin{Code}[width=10cm]
\begin{NiceTabular}{ccc}
\Block[fill=red!10,\emph{B},r]{4-2}{two\\lines}
 & & \Huge Un\\
 & & deux  \\
 & & trois  \\
 & & \Huge quatre  \\
text & text \\
\end{NiceTabular}
\end{Code}
\begin{NiceTabular}{ccc}
\Block[fill=red!10,B,r]{4-2}{two\\lines}
 & & \Huge Un\\
 & & deux  \\
 & & trois  \\
 & & \Huge quatre  \\
text & text \\
\end{NiceTabular}


\end{scope}

\subsection{\textbackslash\textbackslash\ and \& in the blocks}

\index{ampersand-in-blocks}

\colorbox{yellow!50}{\bfseries New 6.28}\par\nobreak

The extension \pkg{nicemtrix} provides the ability to use |\\| and |&| directly
in the content of a block (in order to format its contents) but there is some rectrictions.

\begin{itemize}
\item One must not use both |\\| and |&| in the same block.

\item For |\\|, there is no other restriction. It's possible to use |\\| in a
block to format a text on several rows.

\item In order to use |&|, the key |ampersand-in-blocks| must been activated. Then,
the block is divided in sub-blocks as illustrated below. Be careful: with
|ampersand-in-blocks| is in force, the (main) argument of the command |\Block|
is syntactically divided into sub-blocks by splitting on the ampersands~|&|, the
ampersands between curly braced are protected but not those in an
environment.\footnote{It's not possible to write
  |\Block[ampersand-in-blocks]{}{\begin{array}{cc}1&2\end{array}}|. Of course,
  it's possible without the key |ampersand-in-blocks|.}
\end{itemize}

When the key |ampersand-in-blocks|
As we can see, the blocks (which was are in fact mono-cell blocks) are divided
into sub-blocks of the same size. However, maybe the following code would be prefered.

\medskip
\begin{Code}[width=85mm]
\begin{NiceTabular}{lccccc}%
   [hvlines,ampersand-in-blocks]
  & \Block{1-5}{the five first
                 natural numbers} \\ 
3 & \Block{1-5}{one & two & three} \\
4 & \Block{1-5}{one& two & three & four} \\
5 & one & two & three & four & five \\
\end{NiceTabular}
\end{Code}
%
\begin{NiceTabular}{lccccc}%
   [hvlines,ampersand-in-blocks]
  & \Block{1-5}{the five first natural numbers} \\ 
3 & \Block{1-5}{one & two & three} \\
4 & \Block{1-5}{one& two & three & four} \\
5 & one & two & three & four & five \\
\end{NiceTabular}

\medskip
In this code, we have blocks of size |1-5| which are divided into three or four
sub-blocks. 



\index{Blocks@\textbf{Blocks in the tabulars}|)}


\section{The rules}

\label{rules}
\index{Rules@\textbf{Rules in the tabulars}|(}
\index{Lines in the tabulars|see{Rules}}

The usual techniques for the rules may be used in the environments of
\pkg{nicematrix} (except |\vline|). However, there is some small differences
with the classical environments.

\bigskip
\subsection{Some differences with the classical environments}

\subsubsection{The vertical rules}

In the environments of \pkg{nicematrix}, the vertical rules specified by
\verb+|+ in the preambles of the environments are never broken, even by an
incomplete row or by a double horizontal rule specified by |\hline\hline|
(there is no need to use the package~\pkg{hhline}).

\bigskip
\begin{Code}[width=10cm]
\begin{NiceTabular}{|c|c|} \hline
First & Second \\ \emph{\hline\hline}
Peter \\ \hline
Mary & George\\ \hline
\end{NiceTabular}
\end{Code}
\begin{NiceTabular}{|c|c|}[c] \hline
First & Second \\ \hline\hline
Peter \\ \hline
Mary  & George \\ \hline
\end{NiceTabular}


\bigskip
However, the vertical rules are not drawn in the blocks (created by |\Block|:
cf.~p.~\pageref{Block}) nor in the corners (created by the key |corner|:
cf.~p.~\pageref{corners}) nor in the potential exterior rows (created by the
keys |first-row| and |last-row|: cf.~p.~\pageref{exterior}).

\bigskip
\index{booktabs@\pkg{booktabs} (package)}
If you use \pkg{booktabs} (which provides |\toprule|, |\midrule|,
|\bottomrule|, etc.) and if you really want to add vertical rules (which is
not in the spirit of \pkg{booktabs}), you should notice that the vertical rules
drawn by \pkg{nicematrix} are compatible with \pkg{booktabs}.

\medskip
\begin{Code}[width=10.5cm]
$\begin{NiceArray}{\emph{|cccc|}} \toprule
a & b & c & d \\ \midrule
1 & 2 & 3 & 4 \\
1 & 2 & 3 & 4 \\ \bottomrule
\end{NiceArray}$
\end{Code}
$\begin{NiceArray}{|cccc|}
\toprule
a & b & c & d \\
\midrule
1 & 2 & 3 & 4 \\
1 & 2 & 3 & 4 \\
\bottomrule
\end{NiceArray}$

\bigskip
However, it's still possible to define a specifier (named, for instance, |I|)
to draw vertical rules with the standard behaviour of \pkg{array}.

\begin{Verbatim}
\newcolumntype{I}{!{\vrule}}
\end{Verbatim}


\bigskip
\subsubsection{The command \textbackslash cline}

\label{remark-cline}
\index{cline@\texttt{\textbackslash cline} (LaTeX command)}

The horizontal and vertical rules drawn by |\hline| and the specifier
``\verb+|+'' make the array larger or wider by a quantity equal to the width
of the rule (with \pkg{array} and also with \pkg{nicematrix}).

\smallskip
For historical reasons, this is not the case with the command |\cline|, as
shown by the following example.

\medskip
\begin{Code}[width=10cm]
\setlength{\arrayrulewidth}{2pt}
\begin{tabular}{cccc} \hline
A&B&C&D \\ \emph{\cline{2-2}}
A&B&C&D \\ \hline
\end{tabular}
\end{Code}
\begin{scope}
\setlength{\arrayrulewidth}{2pt}
\begin{tabular}[c]{cccc}
\hline
A&B&C&D \\
\cline{2-2}
A&B&C&D \\
\hline
\end{tabular}
\end{scope}

\medskip
\index{standard-cline}
In the environments of \pkg{nicematrix}, this situation is corrected (it's
still possible to go to the standard behaviour of |\cline| with the key |standard-cline|).

\medskip
\begin{Code}[width=10cm]
\setlength{\arrayrulewidth}{2pt}
\begin{NiceTabular}{cccc} \hline
A&B&C&D \\ \emph{\cline{2}}
A&B&C&D \\ \hline
\end{NiceTabular}
\end{Code}
\begin{scope}
\setlength{\arrayrulewidth}{2pt}
\begin{NiceTabular}[c]{cccc}
\hline
A&B&C&D \\ \cline{2}
A&B&C&D \\ \hline
\end{NiceTabular}
\end{scope}

\medskip
In the environments of \pkg{nicematrix}, an instruction |\cline{|\textsl{\texttt{i}}|}| 
is equivalent to |\cline{|\textsl{\texttt{i}}|-|\textsl{\texttt{i}}|}|.


\subsection{The thickness and the color of the rules}

\indexcommand{arrayrulewidth}
\index{Colour!of the rules}
\index{width!subkey of ``rules''} 
\index{rules (key for an environment)}

The environments of \pkg{nicematrix} provide a key |rules/width| to set the
width (in fact the thickness) of the rules in the current environment. In
fact, this key merely sets the value of the standard LaTeX length
|\arrayrulewidth|. 

\smallskip
It's well known that \pkg{colortbl} provides the command |\arrayrulecolor| in
order to specify the color of the rules.

\smallskip
\indexcommand{arrayrulecolor}
With \pkg{nicematrix}, it's possible to specify the color of the rules even when
\pkg{colortbl} is not loaded. For sake of compatibility, the command is also
named |\arrayrulecolor|. However, \pkg{nicematrix} also provides a key
|rules/color|, available in |\NiceMatrixOptions| or in an individual
environment, to fix the color of the rules. This key sets the value locally
(whereas |\arrayrulecolor| acts globally!) and should be prefered.

\medskip
\begin{Code}[width=15cm]
\begin{NiceTabular}{|ccc|}[\emph{rules/color=[gray]{0.9},rules/width=1pt}]
\hline
rose & tulipe & lys \\
arum & iris & violette \\
muguet & dahlia & souci \\
\hline
\end{NiceTabular}
\end{Code}
\hspace{-5cm}
\begin{NiceTabular}{|ccc|}[rules/color=[gray]{0.9},rules/width=1pt]
\hline
rose & tulipe & lys \\
arum & iris & violette \\
muguet & dahlia & souci \\
\hline
\end{NiceTabular}


\medskip
In fact, in that example, instead of |\hline|, it would have a better choice to
use |\Hline|, provided by \pkg{nicematrix} and described just below, because it
ensures a better output in the PDF viewers at the low levels of zoom.

\subsection{The tools of nicematrix for the rules}

Here are the tools provided by \pkg{nicematrix} for the rules.
\begin{itemize}
\item the keys |hlines|, |vlines|, |hvlines| and |hvlines-except-borders|;
\item the specifier ``\verb+|+'' in the preamble (for the environments with
preamble);
\item \indexcommand{Hline}
the command |\Hline|.
\end{itemize}

\medskip
\textbf{All these tools don't draw the rules in the blocks nor in the
empty corners (when the key |corners| is used), nor in the exterior rows and
columns.}
\begin{itemize} 
\item These blocks are:
\begin{itemize}
\item the blocks created by the command |\Block|\footnote{And also the command |\multicolumn| but
it's recommended to use instead |\Block| in the environments of
\pkg{nicematrix}.} presented
p.~\pageref{Block};
\item the blocks implicitely delimited by the continuous dotted lines created
by |\Cdots|, |\Vdots|, etc. (cf.~p.~\pageref{Cdots}).
\end{itemize}
\item The corners are created by the key |corners| explained below (see
p.~\pageref{corners}).
\item For the exterior rows and columns, see~p.~\pageref{exterior}.
\end{itemize}

In particular, this remark exhibits a first difference between the standard
command |\hline| and the command |\Hline| provided by \pkg{nicematrix}.

Moreover, the key |\Hline| takes in an optional argument (between square
brackets) which is a list of \textsl{key=value} pairs. For the description of
those keys, see |custom-line| on p.~\pageref{custom-line}.\footnote{Technical
  remark: If the user wants to write a command over the command |\Hline|, it
  shall be ensured that this new command is expandable in the TeX sens (by
  using, for instance, |\NewExpandableDocumentCommand| of LaTeX3, |\newcommand|
  of LaTeX or |\def| of TeX). Example:
  |\newcommand{\RedLine}{\Hline[color=red]}|}


\bigskip
As well as the command |\Hline|, the specifier ``\verb+|+'' supports an optional
argument between square brackets for the characteristics of the rule.

\medskip
\begin{Code}[width=10cm]
\begin{NiceTabular}{ | c \emph{|[color=blue]} c |}
\Hline
a & b \\
\emph{\Hline[color=red]}
c & d \\
\Hline
\end{NiceTabular}
\end{Code}
%
\begin{NiceTabular}{|c|[color=blue]c|}
\Hline
a & b \\
\Hline[color=red]
c & d \\
\Hline
\end{NiceTabular}



\subsubsection{The keys hlines and vlines}

\index{hlines|see{Rules}}
\index{hlines!key for an environment}
\index{vlines|see{Rules}}
\index{vlines!key for an environment}

The keys |hlines| and |vlines| (which draw, of course, horizontal and vertical
rules) take in as value a list of numbers which are the numbers of the rules
to draw.\footnote{It's possible to put in that list some intervals of integers
with the syntax $i$|-|$j$.}

In fact, for the environments with delimiters (such as |{pNiceMatrix}| or
|{bNiceArray}|), the key |vlines| don't draw the exterior rules (this is
certainly the expected behaviour).

\medskip
\begin{Code}[width=10.6cm]
$\begin{pNiceMatrix}[\emph{vlines},rules/width=0.2pt]
1 & 2 & 3 & 4 & 5 & 6 \\
1 & 2 & 3 & 4 & 5 & 6 \\
1 & 2 & 3 & 4 & 5 & 6 
\end{pNiceMatrix}$
\end{Code}
$\begin{pNiceMatrix}[vlines,rules/width=0.2pt]
1 & 2 & 3 & 4 & 5 & 6 \\
1 & 2 & 3 & 4 & 5 & 6 \\
1 & 2 & 3 & 4 & 5 & 6 
\end{pNiceMatrix}$


\medskip
When the key |hlines| is in force, it's still possible to use |\Hline\Hline| to
put a double horizontal rule. As well, it's possible to put \verb+||+ in the
preamble (of an environment with preamble) to put a double vertical rule, even
when the key |vlines| is in force.

\medskip
\begin{Code}[width=10.6cm]
$\begin{NiceArray}{c\emph{||}ccccc}[hlines,vlines]
  & a & b & c & d & e \\ \emph{\Hline\Hline}
x & 0 & 0 & 0 & 0 & 0 \\
y & 0 & 0 & 0 & 0 & 0 \\
z & 0 & 0 & 0 & 0 & 0 \\
\end{NiceArray}$
\end{Code}
$\begin{NiceArray}{c||ccccc}[hlines,vlines]
  & a & b & c & d & e \\ \Hline\Hline
x & 0 & 0 & 0 & 0 & 0 \\
y & 0 & 0 & 0 & 0 & 0 \\
z & 0 & 0 & 0 & 0 & 0 \\
\end{NiceArray}$



\subsubsection{The keys hvlines and hvlines-except-borders}
\label{hvlines}

\index{hvlines|see{Rules}}
\index{hvlines!key for an environment}
\index{hvlines-except-borders}


The key |hvlines| (no value) is the conjonction of the keys |hlines| and |vlines|.

\smallskip
\begin{Code}
\setlength{\arrayrulewidth}{1pt}
\begin{NiceTabular}{cccc}[\emph{hvlines},rules/color=blue]
rose      & tulipe & marguerite & dahlia \\
violette  & \Block[draw=red]{2-2}{\LARGE fleurs}  & & souci \\
pervenche & & & lys \\
arum      & iris & jacinthe & muguet 
\end{NiceTabular}
\end{Code}

\begin{center}
\setlength{\arrayrulewidth}{1pt}
\begin{NiceTabular}{cccc}[hvlines,rules/color=blue]
rose      & tulipe & marguerite & dahlia \\
violette  & \Block[draw=red]{2-2}{\LARGE fleurs}  & & souci \\
pervenche & & & lys \\
arum      & iris & jacinthe & muguet 
\end{NiceTabular}
\end{center}

\bigskip
It's worth noting that, when the key |rounded-corners| is used for the
environment |{NiceTabular}|, the key |hvlines| draws rounded corners for the
exterior frame of the tabular: cf. part~\ref{tabular-rounded-corners},
p.~\pageref{tabular-rounded-corners}.

\bigskip
The key |hvlines-except-borders| is similar to the key |hvlines| but does not
draw the rules on the horizontal and vertical borders of the array. For an
example of use of that key, see the part ``Use with tcolorbox'',
p.~\pageref{tcolorbox}. 

\subsubsection{The (empty) corners}

\label{corners}
\index{Corners (the empty ---)}
\index{corners (key of an environment)}

The four |corners| of an array will be designed by |NW|, |SW|, |NE| and |SE|
(\emph{north west}, \emph{south west}, \emph{north east} and \emph{south east}).

For each of these corners, we will call \emph{empty corner} (or simply
\emph{corner}) the reunion of all the empty rectangles starting from the cell
actually in the corner of the array.\footnote{For sake of completeness, we
should also say that a cell contained in a block (even an empty cell) is not
taken into account for the determination of the corners. That behaviour is
natural. The precise definition of a ``non-empty cell'' is given below (cf.
p.~\pageref{empty-cells}).}

However, it's possible, for a cell without content, to require \pkg{nicematrix}
to consider that cell as not empty with the key |\NotEmpty|.

\bigskip
\begin{minipage}{9cm}
In the example on the right (where B is in the center of a block of size
$2\times2$), we have colored in blue the four (empty) corners of the array. 
\end{minipage}\hspace{2cm}%
\begin{NiceTabular}
  [cell-space-top-limit=3pt,hvlines,rules={color=white,width=0.1pt}]
  {*{6}{c}}
\CodeBefore
  \rectanglecolor{blue!10}{1-1}{4-2}
  \rectanglecolor{blue!10}{1-1}{1-4}
  \rectanglecolor{blue!10}{1-6}{3-6}
  \rectanglecolor{blue!10}{7-1}{9-1}
  \rectanglecolor{blue!10}{7-5}{9-6}
\Body
  &   &   &   & A \\
  &   & A & A & A \\
  &   &   & A \\
  &   & A & A & A & A \\
A & A & A & A & A & A \\
A & A & A & A & A & A \\
  & A & A & A \\
  & \Block{2-2}{B} & & A \\
  &   &   & A \\
\end{NiceTabular}

\bigskip
When the key |corners|\footnote{The key |corners| that we describe now
has no direct link with the key |rounded-corners| described in the part
\ref{tabular-rounded-corners}, p.~\pageref{tabular-rounded-corners}} is used,
\pkg{nicematrix} computes the (empty) corners and these corners will be taken
into account by the tools for drawing the rules (the rules won't be drawn in
the corners).

\bigskip
\begin{Code}[width=11cm]
\NiceMatrixOptions{cell-space-top-limit=3pt}
\begin{NiceTabular}{*{6}{c}}[\emph{corners},hvlines]
  &   &   &   & A \\
  &   & A & A & A \\
  &   &   & A \\
  &   & A & A & A & A \\
A & A & A & A & A & A \\
A & A & A & A & A & A \\
  & A & A & A \\
  & \Block{2-2}{B} & & A \\
  &   &   & A \\
\end{NiceTabular}
\end{Code}
\begin{NiceTabular}{*{6}{c}}[corners,hvlines,cell-space-top-limit=3pt]
  &   &   &   & A \\
  &   & A & A & A \\
  &   &   & A \\
  &   & A & A & A & A \\
A & A & A & A & A & A \\
A & A & A & A & A & A \\
  & A & A & A \\
  & \Block{2-2}{B} & & A \\
  &   &   & A \\
\end{NiceTabular}


\bigskip
It's also possible to provide to the key |corners| a (comma-separated) list of
corners (designed by |NW|, |SW|, |NE| and |SE|).

\medskip
\begin{Code}[width=11cm]
\NiceMatrixOptions{cell-space-top-limit=3pt}
\begin{NiceTabular}{*{6}{c}}[\emph{corners=NE},hvlines]
1\\
1&1\\
1&2&1\\
1&3&3&1\\
1&4&6&4&1\\
 & & & & &1
\end{NiceTabular}
\end{Code}
\begin{NiceTabular}{*{6}{c}}[c,corners=NE,hvlines,cell-space-top-limit=3pt]
1\\
1&1\\
1&2&1\\
1&3&3&1\\
1&4&6&4&1\\
 & & & & &1
\end{NiceTabular}


\medskip
$\triangleright$ The corners are also taken into account by the tools provided
by \pkg{nicematrix} to color cells, rows and columns. These tools don't color
the cells which are in the corners (cf.~p.~\pageref{color-in-code-before}). The
command |\TikzEveryCell| available in the |\CodeBefore| and the |\CodeAfter|
(cf. p.~\pageref{TikzEveryCell}) takes also into account the empty corners.

\subsubsection{The command \textbackslash diagbox}

\indexcommand{diagbox}

The command |\diagbox| (inspired by the package \pkg{diagbox}), allows, when
it is used in a cell, to slash that cell diagonally downwards.

\medskip
\begin{Code}[width=10cm]
$\begin{NiceArray}{*{5}{c}}[hvlines]
\emph{\diagbox{x}{y}}  & 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{Code}
$\begin{NiceArray}{*{5}{c}}[hvlines]
\diagbox{x}{y}  & 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}$

\medskip
It's possible to use the command |\diagbox| in a |\Block|.




\subsubsection{Commands for customized rules}

\label{custom-line}
\index{command (key of ``custom-line'')}
\index{ccommand (key of ``custom-line'')}
\index{letter (key of ``custom-line'')}
\index{custom-line|(}


It's also possible to define commands and letters for customized rules with
the key |custom-line| available in |\NiceMatrixOptions| and in the options of
individual environments. That key takes in as argument a list of
\textsl{key=value} pairs. First, there is three keys to define the tools which
will be used to use that new type of rule.

\begin{itemize}
\item the key |command| is the name (without the backslash) of a command that
will be created by \pkg{nicematrix} and that will be available for the final
user in order to draw horizontal rules (similarly to |\hline|);

\item the key |ccommand| is the name (without the backslash) of a command
that will be created by \pkg{nicematrix} and that will be available for the
final user to order to draw partial horizontal rules (similarly to |\cline|,
hence the name |ccommand|): the argument of that command is a list of
intervals of columns specified by the syntax~$i$ or $i$-$j$.\footnote{It's
recommended to use such commands only once in a row because each use will
create space between the rows corresponding to the total width of the rule.}

\item the key |letter| takes in as argument a letter\footnote{The following
letters are forbidden: \verb+lcrpmbVX|()[]!@<>+} that the user will use in
the preamble of an environment with preamble (such as |{NiceTabular}| in order
to specify a vertical rule.
\end{itemize}

\bigskip
We will now speak of the keys which describe the rule itself. Those keys may
also be used in the (optional) argument of an individual command |\Hline| or in
the (optional) argument of a specifier ``\verb+|+'' in the preamble of an
environment. 

\bigskip
There is three possibilities.

\begin{itemize}
\item \emph{First possibility}\par\nobreak

It's possible to specify composite rules, with a color and a color for the
inter-rule space (as possible with \pkg{colortbl} for instance).

\begin{itemize}
\index{multiplicity (key of ``custom-line'')}
\index{color!key of ``custom-line''}
\index{sep-color (key of ``custom-line'')}
\item the key |multiplicity| is the number of consecutive rules that will be
drawn: for instance, a value of $2$ will create double rules such those
created by |\hline\hline| or \verb+||+ in the preamble of an environment;

\item the key |color| sets the color of the rules ;

\item the key |sep-color| sets the color between two successive rules (should be
used only in conjonction with |multiplicity|). The name of that key is inspired
by the command |\doublerulesepcolor| of \pkg{colortbl}.
\end{itemize}

\medskip
That system may be used, in particular, for the definition of commands and
letters to draw rules with a specific color (and those rules will respect the
blocks and corners as do all the rules of \pkg{nicematrix}). 

\medskip
\begin{Code}
\begin{NiceTabular}{lcIcIc}\emph{[custom-line = {letter=I, color=blue}]}
\hline
          & \Block{1-3}{dimensions} \\
          & L & l & h \\
\hline
Product A & 3 & 1 & 2 \\
Product B & 1 & 3 & 4 \\
Product C & 5 & 4 & 1 \\
\hline
\end{NiceTabular}
\end{Code}


\begin{center}
\begin{NiceTabular}{lcIcIc}[custom-line = {letter=I, color=blue}]
\hline
          & \Block{1-3}{dimensions} \\
          & L & l & H \\
\hline
Product A & 3 & 1 & 2 \\
Product B & 1 & 3 & 4 \\
Product C & 5 & 4 & 1 \\
\hline
\end{NiceTabular}
\end{center}


\bigskip
The key |sep-color| with the value |white| may also be used in case of an
horizontal double-rule on the top of a colored cell (if we want the space
between both rules above the cell not colored by the color of the cell).

\begin{scope}
\NiceMatrixOptions
  {
    custom-line = 
     {
       command = DoubleRule , 
       multiplicity = 2 , 
       sep-color = white
     }
  }


\begin{Code}[width=10cm]
\NiceMatrixOptions
  {
    custom-line = 
     {
       command = DoubleRule , 
       multiplicity = 2 , 
       \emph{sep-color = white}
     }
  }

\begin{NiceTabular}{ccc}[color-inside]
one & two & three \\
\emph{\DoubleRule}
four & \cellcolor{yellow} five & six \\
\end{NiceTabular}
\end{Code}
\begin{NiceTabular}{ccc}[color-inside]
one & two & three \\
\DoubleRule
four & \cellcolor{yellow} five & six \\
\end{NiceTabular}

\end{scope}




\bigskip
\item \emph{Second possibility}\par\nobreak

\index{tikzz@tikz!key of ``custom-line''}
\index{total-width (key of ``custom-line'')}

It's possible to use the key |tikz| (if TikZ is loaded). In that case, the
rule is drawn directly with TikZ by using as parameters the value of the key
|tikz| which must be a list of \textsl{key=value} pairs which may be applied
to a TikZ path.

By default, no space is reserved for the rule that will be drawn with TikZ. It
is possible to specify a reservation (horizontal for a vertical rule and
vertical for an horizontal one) with the key |total-width|. That value of that
key, is, in some ways, the width of the rule that will be drawn
(\pkg{nicematrix} does not compute that width from the characteristics of the
rule specified in |tikz|).



\bigskip
Here is an example with the key |dotted| of TikZ.

\begin{Code}[width=9cm]
\NiceMatrixOptions
  {
    custom-line = 
     {
       letter = I , 
       \emph{tikz = dotted ,
       total-width = \pgflinewidth}
     }
  }

\begin{NiceTabular}{cIcIc}
one & two & three \\
four & five & six \\
seven & eight & nine
\end{NiceTabular}
\end{Code}
\begin{scope}
\NiceMatrixOptions
  {
    custom-line = 
     {
       letter = I , 
       tikz = dotted ,
       total-width = \pgflinewidth
     }
  }
\begin{NiceTabular}{cIcIc}
one & two & three \\
four & five & six \\
seven & eight & nine
\end{NiceTabular}
\end{scope}

\bigskip
\item \emph{Third possibility} : the key \Definition{dotted}
\label{dotted}
\index{dotted (key of ``custom-line'')}
\indexcommand{hdottedline}
\indexcommand{cdottedline}

As one can see, the dots of a dotted line of TikZ have the shape of a square,
and not a circle. That's why the extension \pkg{nicematrix} provides in the
key |custom-line| a key |dotted| which will draw rounded dots. The initial
value of the key |total-width| is, in this case, equal to the diameter of the dots
(but the user may change the value with the key |total-width| if needed). Those
dotted rules are also used by \pkg{nicematrix} to draw continuous dotted rules
between cells of the matrix with |\Cdots|, |\Vdots|, etc. (cf. p.~\pageref{Cdots}).

In fact, \pkg{nicematrix} defines by default the commands
\Definition{hdottedline} and \Definition{cdottedline} and the letter ``|:|'' for
those dotted rules.\footnote{However, it's possible to overwrite those
  definitions with a |custom-line| (in order, for example, to switch to dashed
  lines).}

\smallskip
\begin{Code}
\NiceMatrixOptions \emph{% \textsl{present in nicematrix.sty}}
  { 
    custom-line = 
      { 
        letter = : , 
        command = hdottedline , 
        ccommand = cdottedline ,
        \emph{dotted} 
      }
  } 
\end{Code}

Thus, it's possible to use the commands |\hdottedline| and |\cdottedline |to
draw horizontal dotted rules.

\medskip
\begin{Code}[width=9.5cm]
\begin{pNiceMatrix}
1 & 2 & 3 & 4 & 5 \\
\emph{\hdottedline}
6 & 7 & 8 & 9 & 10 \\
\emph{\cdottedline{1,4-5}}
11 & 12 & 13 & 14 & 15 
\end{pNiceMatrix}
\end{Code}
$\begin{pNiceMatrix}
1 & 2 & 3 & 4 & 5 \\
\hdottedline
6 & 7 & 8 & 9 & 10 \\
\cdottedline{1,4-5}
11 & 12 & 13 & 14 & 15 
\end{pNiceMatrix}$


\bigskip
In the environments with an explicit preamble (like |{NiceTabular}|,
|{NiceArray}|, etc.), it's possible to draw a vertical dotted line with the
specifier ``|:|''.

\medskip
\begin{Code}[width=9.5cm]
$\left(\begin{NiceArray}{cccc\emph{:}c}
1 & 2 & 3 & 4 & 5 \\
6 & 7 & 8 & 9 & 10 \\
11 & 12 & 13 & 14 & 15 
\end{NiceArray}\right)
\end{Code}
$\left(\begin{NiceArray}{cccc:c}
1 & 2 & 3 & 4 & 5 \\
6 & 7 & 8 & 9 & 10 \\
11 & 12 & 13 & 14 & 15 
\end{NiceArray}\right)$

\end{itemize}

\index{custom-line|)}
\index{Rules@\textbf{Rules in the tabulars}|)}


\section{The color of the background of the rows and columns}

\index{Colour!of the cells}

\subsection{Use of colortbl}

\index{colortbl@\pkg{colortbl} (package)}

We recall that the package \pkg{colortbl} can be loaded directly with
|\usepackage{colortbl}| or by loading \pkg{xcolor} with the key |table|:
|\usepackage[table]{xcolor}|. 

\medskip
However, there is two drawbacks:
\begin{itemize}
\item The package \pkg{colortbl} patches \pkg{array}, leading to some
incompatibilities (for instance with the command |\hdotsfor|).

\item The package \pkg{colortbl} constructs the array row by row, alterning
colored rectangles, rules and contents of the cells. The resulting
\textsc{pdf} is difficult to interpret by some \textsc{pdf} viewers and may
lead to artefacts on the screen.
\begin{itemize}
\item Some rules seem to disappear. This is because many PDF viewers give
priority to graphical element drawn posteriorly (which is in the spirit of the
``painting model'' of PostScript and PDF). Concerning this problem, MuPDF
(which is used, for instance, by SumatraPDF) gives better results than Adobe
Reader).
\item A thin white line may appear between two cells of the same color. This
phenomenon occurs when each cell is colored with its own instruction |fill|
(the PostScript operator |fill| noted |f| in PDF). This is the case with
\pkg{colortbl}: each cell is colored on its own, even when |\columncolor| or
|\rowcolor| is used.

As for this phenomenon, Adobe Reader gives better results than MuPDF.
\end{itemize}

The package \pkg{nicematrix} provides tools to avoid those problems.
\end{itemize}

\subsection{The tools of nicematrix in the \textbackslash CodeBefore}

\label{color-in-code-before}
\index{code-before!key for an environment}
\index{CodeBefore@\texttt{\textbackslash CodeBefore}...\texttt{\textbackslash Body}}
\index{Body@\texttt{\textbackslash Body}|see{\texttt{\textbackslash CodeBefore}}}

The package \pkg{nicematrix} provides some tools (independent of \pkg{colortbl})
to draw the colored panels first, and, then, the content of the cells and the
rules. This strategy is more conform to the ``painting model'' of the formats
PostScript and \textsc{pdf} and is more suitable for the \textsc{pdf} viewers.
However, it requires several compilations.\footnote{If you use Overleaf,
  Overleaf will do automatically a sufficient number of compilations.}

\medskip
The extension \pkg{nicematrix} provides a key |code-before| for some code that
will be executed before the drawing of the tabular. 

\medskip 
An alternative syntax is provided: it's possible to put the content of that
|code-before| between the keywords |\CodeBefore| and |\Body| at the beginning
of the environment.

\begin{Code}
\begin{pNiceArray}{\textsl{preamble}}
\emph{\CodeBefore [\textsl{options}]}
  \textsl{instructions of the code-before}
\emph{\Body}
  \textsl{contents of the environment}
\end{pNiceArray}
\end{Code}

\smallskip
The optional argument between square brackets is a list of \textsl{key=value}
pairs which will be presented progressively in this
documentation.\footnote{The available keys are |create-cell-nodes|,
|sub-matrix| (and its subkeys) and \texttt{delimiters-color}.}

\medskip
New commands are available in that |\CodeBefore|: |\cellcolor|,
|\rectanglecolor|, |\rowcolor|, |\columncolor|, |\rowcolors|,
|\rowlistcolors|, |\chessboardcolors| and |\arraycolor|.\footnote{Remark that,
in the |\CodeBefore|, PGF/TikZ nodes of the form ``\verb+(i-|j)+'' are
also available to indicate the position to the potential rules:
cf.~p.~\pageref{nodes-i}.}
\label{code-before}

\index{cellcolor@\texttt{\textbackslash cellcolor}!command of
  \texttt{\textbackslash CodeBefore}} 
\index{rectanglecolor@\texttt{\textbackslash rectanglecolor} (in
  \texttt{\textbackslash CodeBefore})}
\index{rowcolor@\texttt{\textbackslash rowcolor}!command of \texttt{\textbackslash CodeBefore}}
\index{columncolor@\texttt{\textbackslash columncolor}!command of
  \texttt{\textbackslash CodeBefore}}
\index{rowcolors@\texttt{\textbackslash rowcolors} (command of \texttt{\textbackslash CodeBefore})}
\index{rowlistcolor@\texttt{\textbackslash rowlistcolors} (command of
  \texttt{\textbackslash CodeBefore})}
\index{chessboardcolors@\texttt{\textbackslash chessboardcolors}!(commande
  du \texttt{\textbackslash CodeBefore})}
\index{arraycolor@\texttt{\textbackslash arraycolor} (command of \texttt{\textbackslash
  CodeBefore)}}

The names of these commands are inspired by the names of the commands provided
by \pkg{colortbl}.


\medskip
These commands don't color the cells which are in the ``corners'' if the key
|corners| is used. That key has been described p.~\pageref{corners}.

\medskip
These commands respect the rounded corners if the key |rounded-corners|
(described in the part \ref{tabular-rounded-corners} at the
page~\pageref{tabular-rounded-corners}) has been used.

\medskip
All these commands accept an optional argument, between square brackets and
in first position. That optional argument may contain two elements (separated
by a comma)
\begin{itemize}
\item the colorimetric space (|RGB|, |rgb|, |HTML|, etc) as specified by the
the extension \pkg{xcolor};
\item \index{opacity (key of commands such as\newline \texttt{\textbackslash rowcolor}, etc.)}
a specification of opacity of the form \texttt{opacity =
  \textsl{value}}.\footnote{Caution : that feature creates instructions of
  transparency in the \textsc{pdf} and some \textsc{pdr} don't support such instructions.}
\end{itemize}

\bigskip

We describe now in detail those commands.

\medskip
\begin{itemize}
\item The command \Definition{\textbackslash cellcolor} takes its name from
the command |\cellcolor| of \pkg{colortbl}.

This command takes in as mandatory arguments a color and a list of cells, each
of which with the format $i$-$j$ where $i$ is the number of the row and $j$ the
number of the colummn of the cell. In fact, despite its name, this command may
be used to color a whole row (with the syntax $i$-) or a whole column (with the
syntax -$j$).

\medskip
\begin{scope}
\hfuzz=10cm
\begin{Code}[width=10cm]
\begin{NiceTabular}{ccc}[hvlines]
\CodeBefore
  \emph{\cellcolor[HTML]{FFFF88}{3-1,2-2,-3}}
\Body
a & b & c \\ 
e & f & g \\ 
h & i & j \\ 
\end{NiceTabular}
\end{Code}
\begin{NiceTabular}{ccc}[hvlines]
\CodeBefore
  \cellcolor[HTML]{FFFF88}{3-1,2-2,-3}
\Body
a & b & c \\ 
e & f & g \\ 
h & i & j \\ 
\end{NiceTabular}
\end{scope}

\bigskip
\item The command \Definition{\textbackslash rectanglecolor} takes three
mandatory arguments. The first is the color. The second is the upper-left cell
of the rectangle and the third is the lower-right cell of the rectangle.

\medskip
\begin{scope}
\hfuzz=10cm
\begin{Code}[width=10cm]
\begin{NiceTabular}{ccc}[hvlines]
\CodeBefore
  \emph{\rectanglecolor{blue!15}{2-2}{3-3}}
\Body
a & b & c \\ 
e & f & g \\ 
h & i & j \\ 
\end{NiceTabular}
\end{Code}
\begin{NiceTabular}{ccc}[hvlines]
\CodeBefore
   \rectanglecolor{blue!15}{2-2}{3-3}
\Body
a & b & c \\ 
e & f & g \\ 
h & i & j \\ 
\end{NiceTabular}
\end{scope}

\bigskip
\item The command \Definition{\textbackslash arraycolor} takes in as mandatory
argument a color and color the whole tabular with that color (except the
potential exterior rows and columns: cf.~p.~\pageref{exterior}). It's only a
particular case of |\rectanglecolor|.


\bigskip
\item The command \Definition{\textbackslash chessboardcolors} takes in as
mandatory arguments two colors and it colors the cells of the tabular in
quincunx with these colors.

\medskip
\begin{scope}
\hfuzz=10cm
\begin{Code}[width=9cm]
$\begin{pNiceMatrix}[r,margin] 
\CodeBefore
  \emph{\chessboardcolors{red!15}{blue!15}}
\Body
1 & -1 & 1 \\
-1 & 1 & -1 \\
1 & -1 & 1 
\end{pNiceMatrix}$
\end{Code}
$\begin{pNiceMatrix}[r,baseline=1, margin] 
\CodeBefore 
\chessboardcolors{red!15}{blue!15}
\Body
1 & -1 & 1 \\
-1 & 1 & -1 \\
1 & -1 & 1 
\end{pNiceMatrix}$
\end{scope}

\medskip
We have used the key |r| which aligns all the columns rightwards (cf.
p.~\pageref{columns-width}).


\bigskip
\item The command \Definition{\textbackslash rowcolor} takes its name from the
command |\rowcolor| of \pkg{colortbl}. Its first mandatory argument is the
color and the second is a comma-separated list of rows or interval of rows
with the form $a$-$b$ (an interval of the form $a$- represent all the rows
from the row $a$ until the end).

\medskip
\begin{scope}
\hfuzz = 10cm
\begin{Code}[width=9cm]
$\begin{NiceArray}{lll}[hvlines] 
\CodeBefore
  \emph{\rowcolor{red!15}{1,3-5,8-}}
\Body
a_1 & b_1 & c_1 \\
a_2 & b_2 & c_2 \\
a_3 & b_3 & c_3 \\
a_4 & b_4 & c_4 \\
a_5 & b_5 & c_5 \\
a_6 & b_6 & c_6 \\
a_7 & b_7 & c_7 \\
a_8 & b_8 & c_8 \\
a_9 & b_9 & c_9 \\
a_{10} & b_{10} & c_{10} \\
\end{NiceArray}$
\end{Code}
$\begin{NiceArray}{lll}[baseline=4,hvlines] 
\CodeBefore 
\rowcolor{red!15}{1,3-5,8-}
\Body
a_1 & b_1 & c_1 \\
a_2 & b_2 & c_2 \\
a_3 & b_3 & c_3 \\
a_4 & b_4 & c_4 \\
a_5 & b_5 & c_5 \\
a_6 & b_6 & c_6 \\
a_7 & b_7 & c_7 \\
a_8 & b_8 & c_8 \\
a_9 & b_9 & c_9 \\
a_{10} & b_{10} & c_{10} \\
\end{NiceArray}$
\end{scope}


\bigskip
\item The command \Definition{\textbackslash columncolor} takes its name from
the command |\columncolor| of \pkg{colortbl}. Its syntax is similar to the
syntax of |\rowcolor|.

\bigskip
\item The command \Definition{\textbackslash rowcolors} (with a \emph{s})
takes its name from the command |\rowcolors| of \pkg{colortbl}. The \emph{s}
emphasizes the fact that there is \emph{two} colors. This command colors
alternately the rows of the tabular with the two colors (provided in second
and third argument), beginning with the row whose number is given in first
(mandatory) argument. One of the arguments of color may be empty (no color is
applied in the corresponding rows).

In fact, the first (mandatory) argument is, more generally, a comma separated
list of intervals describing the rows involved in the action of |\rowcolors|
(an interval of the form $i$|-| describes in fact the interval of all the rows
of the tabular, beginning with the row~$i$).


\bigskip
The last argument of |\rowcolors| is an optional list of pairs
\textsl{key=value} (the optional argument in the first position corresponds to
the colorimetric space). The available keys are |cols|, |restart| and
|respect-blocks|.

\index{cols (key of \texttt{\textbackslash rowcolors} of \texttt{\textbackslash CodeBefore})}
\index{restart (key of \texttt{\textbackslash rowcolors} of \texttt{\textbackslash CodeBefore})}
\index{respect-blocks (key of \texttt{\textbackslash rowcolors} du\newline \texttt{\textbackslash CodeBefore})}

\begin{itemize}
\item The key \Definition{cols} describes a set of columns. The command
|\rowcolors| will color only the cells of these columns. The value is a
comma-separated list of intervals of the form $i$-$j$ (where $i$ or $j$ may be
replaced by |*|).
\item With the key \Definition{restart}, each interval of rows (specified by the
first mandatory argument) begins with the same color.\footnote{Otherwise, the color
of a given row relies only upon the parity of its absolute number.}
\item With the key \Definition{respect-blocks} the ``rows'' alternately colored
may extend over several rows if they have to incorporate blocks (created with
the command |\Block|: cf.~p.~\pageref{Block}).
\end{itemize}

\medskip
\begin{scope}
\hfuzz=10cm
\begin{Code}[width=10cm]
\begin{NiceTabular}{clr}[hvlines]
\CodeBefore
  \emph{\rowcolors[gray]{2}{0.8}{}[cols=2-3,restart]}
\Body
\Block{1-*}{Results} \\
John & 12 \\
Stephen & 8 \\
Sarah & 18 \\
Ashley & 20 \\
Henry & 14 \\
Madison & 15 
\end{NiceTabular}
\end{Code}
\begin{NiceTabular}{clr}[hvlines,baseline=2]
\CodeBefore
 \rowcolors[gray]{2}{0.8}{}[cols=2-3,restart]
\Body
\Block{1-*}{Results} \\
\Block{2-1}{A}& John & 12 \\
              & Stephen & 8 \\
\Block{4-1}{B}& Sarah & 18 \\
              & Ashley & 20 \\
              & Henry & 14 \\
              & Madison & 15 
\end{NiceTabular}
\end{scope}

\vspace{1cm}
\begin{scope}
\hfuzz=10cm
\begin{Code}[width=10cm]
\begin{NiceTabular}{lr}[hvlines]
\CodeBefore
  \emph{\rowcolors{1}{blue!10}{}[respect-blocks]}
\Body
\Block{2-1}{John}    & 12 \\
                     & 13 \\
Steph                &  8 \\
\Block{3-1}{Sarah}   & 18 \\
                     & 17 \\
                     & 15 \\
Ashley               & 20 \\
Henry                & 14 \\
\Block{2-1}{Madison} & 15 \\
                     & 19
\end{NiceTabular}
\end{Code}
\begin{NiceTabular}{lr}[hvlines,baseline=c]
\CodeBefore
  \rowcolors{1}{blue!10}{}[respect-blocks]
\Body
\Block{2-1}{John}    & 12 \\
                     & 13 \\
Steph                &  8 \\
\Block{3-1}{Sarah}   & 18 \\
                     & 17 \\
                     & 15 \\
Ashley               & 20 \\
Henry                & 14 \\
\Block{2-1}{Madison} & 15 \\
                     & 19
\end{NiceTabular}
\end{scope}




\bigskip
\item The extension \pkg{nicematrix} provides also a command
\Definition{\textbackslash rowlistcolors}. This command generalises the
command |\rowcolors|: instead of two successive arguments for the colors, this
command takes in an argument which is a (comma-separated) list of colors. In
that list, the symbol |=| represent a color identical to the previous one.

\smallskip
\begin{Code}[width=10cm]
\begin{NiceTabular}{c}
\CodeBefore
  \emph{\rowlistcolors{1}{red!15,blue!15,green!15}}
\Body
Peter \\
James \\
Abigail \\
Elisabeth \\
Claudius \\
Jane \\
Alexandra \\
\end{NiceTabular}
\end{Code}
\begin{NiceTabular}{c}
\CodeBefore
  \rowlistcolors{1}{red!15,blue!15,green!15}
\Body
Peter \\
James \\
Abigail \\
Elisabeth \\
Claudius \\
Jane \\
Alexandra \\
\end{NiceTabular}

\bigskip
It's also possible to use in the command |\rowlistcolors| a color series
defined by the command |\definecolorseries| of \pkg{xcolor} (and initialized
with the command |\resetcolorseries|\footnote{For the initialization, in the
following example, you have used the counter |iRow| (which corresponds to the
internal TeX counter |\c@iRow|) which, when used in the
|\CodeBefore| (and in the |\CodeAfter|) corresponds to the number of rows of
the array: cf.~p~\pageref{iRow}. That leads to an adjustement of the gradation
of the colors to the size of the tabular.}).

\index{definecolorseries@\texttt{\textbackslash definecolorseries} (command of \pkg{xcolor})}
\index{resetcolorseries@\texttt{\textbackslash resetcolorseries} (command of \pkg{xcolor})}

\smallskip
\begin{Code}[width=12.5cm]
\begin{NiceTabular}{c}
\CodeBefore
   \emph{\definecolorseries{BlueWhite}{rgb}{last}{blue}{white}
   \resetcolorseries[\value{iRow}]{BlueWhite}
   \rowlistcolors{1}{BlueWhite!!+}}
\Body
Peter \\
James \\
Abigail \\
Elisabeth \\
Claudius \\
Jane \\
Alexandra \\
\end{NiceTabular}
\end{Code}
\hspace{-1cm}
\begin{NiceTabular}{c}
\CodeBefore
   \definecolorseries{BlueWhite}{rgb}{last}{blue}{white}
   \resetcolorseries[\value{iRow}]{BlueWhite}
   \rowlistcolors{1}{BlueWhite!!+}
\Body
Peter \\
James \\
Abigail \\
Elisabeth \\
Claudius \\
Jane \\
Alexandra \\
\end{NiceTabular}
\end{itemize}

\vspace{1cm}
We recall that all the color commands we have described don't color the cells
which are in the ``corners''. In the following example, we use the key
|corners| to require the determination of the corner \emph{north east} (NE).

\medskip
\index{corners (key of an environment)|textit}
\begin{Code}[width=15cm]
\begin{NiceTabular}{ccccccc}[\emph{corners=NE},margin,hvlines,first-row,first-col]
\CodeBefore
  \emph{\rowlistcolors{1}{blue!15, }}
\Body
  & 0 & 1 & 2 & 3 & 4 & 5 & 6 \\
0 & 1 \\
1 & 1 & 1 \\
2 & 1 & 2 & 1 \\
3 & 1 & 3 & 3 & 1 \\
4 & 1 & 4 & 6 & 4 & 1 \\
5 & 1 & 5 & 10 & 10 & 5 & 1 \\
6 & 1 & 6 & 15 & 20 & 15 & 6 & 1 \\
\end{NiceTabular}
\end{Code}
\hspace{-6cm}
\begin{NiceTabular}{ccccccc}[corners=NE,margin,hvlines,first-row,first-col]
\CodeBefore
  \rowlistcolors{1}{blue!15, }
\Body
  & 0 & 1 & 2 & 3 & 4 & 5 & 6 \\
0 & 1 \\
1 & 1 & 1 \\
2 & 1 & 2 & 1 \\
3 & 1 & 3 & 3 & 1 \\
4 & 1 & 4 & 6 & 4 & 1 \\
5 & 1 & 5 & 10 & 10 & 5 & 1 \\
6 & 1 & 6 & 15 & 20 & 15 & 6 & 1 \\
\end{NiceTabular}

\medskip
The previous example uses the keys |first-row| and |first-col| which are
described in the chapter concerning the «exterior» rows and columns
(cf.~p.~\pageref{exterior}). 

As one can see, \emph{by default}, the coloring commands that we have described
don't apply in those exterior rows and columns.

However, it may still be possible to color in those rows and columns by
providing explicity the numbers of those rows and columns.

In the following example, we require a color in the column~$0$ (which is the
«first column» and which exists because the key |first-col| has been used).

\medskip
\begin{Code}[width=15cm]
\begin{NiceTabular}{ccccccc}[\emph{corners=NE},margin,hvlines,first-row,first-col]
\CodeBefore
  \rowlistcolors{1}{blue!15, }
  \emph{\columncolor{red!15}{0}}
\Body
  & 0 & 1 & 2 & 3 & 4 & 5 & 6 \\
0 & 1 \\
1 & 1 & 1 \\
2 & 1 & 2 & 1 \\
3 & 1 & 3 & 3 & 1 \\
4 & 1 & 4 & 6 & 4 & 1 \\
5 & 1 & 5 & 10 & 10 & 5 & 1 \\
6 & 1 & 6 & 15 & 20 & 15 & 6 & 1 \\
\end{NiceTabular}
\end{Code}
\hspace{-6cm}
\begin{NiceTabular}{ccccccc}[corners=NE,margin,hvlines,first-row,first-col]
\CodeBefore
  \rowlistcolors{1}{blue!15, }
  \columncolor{red!15}{0}
\Body
  & 0 & 1 & 2 & 3 & 4 & 5 & 6 \\
0 & 1 \\
1 & 1 & 1 \\
2 & 1 & 2 & 1 \\
3 & 1 & 3 & 3 & 1 \\
4 & 1 & 4 & 6 & 4 & 1 \\
5 & 1 & 5 & 10 & 10 & 5 & 1 \\
6 & 1 & 6 & 15 & 20 & 15 & 6 & 1 \\
\end{NiceTabular}



\bigskip
One should remark that all the previous commands are compatible with the
commands of \pkg{booktabs} (|\toprule|, |\midrule|, |\bottomrule|, etc).
However, \pkg{booktabs} is \emph{not} loaded by \pkg{nicematrix}.

\medskip
\index{rotate@\texttt{\textbackslash rotate}|textit}
\begin{scope}
\hfuzz=10cm
\begin{Code}[width=8.5cm]
\begin{NiceTabular}[c]{lSSSS}
\CodeBefore
  \rowcolor{red!15}{1-2} 
  \rowcolors{3}{blue!15}{}
\Body
\emph{\toprule}
\Block{2-1}{Product} & 
\Block{1-3}{dimensions (cm)} & & & 
\Block{2-1}{\rotate Price} \\
\emph{\cmidrule(rl){2-4}}
 & L & l & h \\
\emph{\midrule}
small    & 3   & 5.5  & 1   & 30    \\
standard & 5.5 & 8    & 1.5 & 50.5  \\
premium  & 8.5 & 10.5 & 2   & 80    \\
extra    & 8.5 & 10   & 1.5 & 85.5  \\
special  & 12  & 12   & 0.5 & 70    \\
\emph{\bottomrule}
\end{NiceTabular}
\end{Code}
\begin{NiceTabular}[c]{lSSSS}
\CodeBefore
  \rowcolor{red!15}{1-2} 
  \rowcolors{3}{blue!15}{}
\Body
\toprule
\Block{2-1}{Product} & 
\Block{1-3}{dimensions (cm)} & & & 
\Block{2-1}{\rotate Price} \\
\cmidrule(rl){2-4} 
 & L & l & h \\
\midrule
small    & 3   & 5.5  & 1   & 30    \\
standard & 5.5 & 8    & 1.5 & 50.5  \\
premium  & 8.5 & 10.5 & 2   & 80    \\
extra    & 8.5 & 10   & 1.5 & 85.5  \\
special  & 12  & 12   & 0.5 & 70    \\
\bottomrule
\end{NiceTabular}
\end{scope}

\index{S (the columns S of \pkg{siunitx})|textit}
\medskip 
We have used the type of column |S| of \pkg{siunitx}.


\subsection{Color tools to be used inside the tabular}

\index{color-inside}
\index{cellcolor@\texttt{\textbackslash cellcolor}!command in tabular}
\index{rowcolor@\texttt{\textbackslash rowcolor}!command in tabular}
\index{columncolor@\texttt{\textbackslash columncolor}!command in the preamble
  of an environment}  


It's possible to access the preceding tools with a syntax close to the syntax
of \pkg{colortbl}. For that, one must use the key |color-inside|\footnote{There
  is an alias for that key : \texttt{colortbl-like}.} in the
current environment.\footnote{Up to now, this key is \emph{not} available in |\NiceMatrixOptions|.}

There are several commands available (the first three ones are inspired by
\pkg{colortbl} but are \emph{independent} of \pkg{colortbl}):
\begin{itemize}
\item \DefinitionCommand{cellcolor} which colorizes a cell;\footnote{However,
  this command cellcolor will delete the following spaces, which does not the
  command cellcolor of \pkg{colortbl}.}
\item \DefinitionCommand{rowcolor} which must be used in a cell and which
colorizes the end of the row;\footnote{If you want a commande to color the
  following $n$~rows, consider the command |\RowStyle| and its key |rowcolor|,
  p.~\pageref{RowStyle}} 
\item \DefinitionCommand{columncolor} which must be used in the preamble of the
environment with the same syntax as the corresponding command of \pkg{colortbl}
(however, unlike the command columncolor of \pkg{colortbl}, this command
|\columncolor| can appear within another command, itself used in the preamble of
the array);
\item \DefinitionCommand{rowcolors} which takes in as arguments two colors and
color the rest of the tabular with those colors;
\item \DefinitionCommand{rowlistcolors} which takes in as argument a color and
color the rest of the tabular with the colors of that list of
colors.\footnote{When the command |\rowlistcolors| (or the command |\rowcolors|
  is used in a cell of the column~$j$ of the array, the command applies only on
  the columns above~$j$ (by design).}
\end{itemize}
These commands are compatible with the commands for the overlays of Beamer
(|\only|, etc.) 

\smallskip
\begin{Code}
\NewDocumentCommand { \Blue } { } { \emph{\columncolor{blue!15}} }
\begin{NiceTabular}[color-inside]{>{\Blue}c>{\Blue}cc} 
\toprule
\emph{\rowcolor{red!15}}
Last name & First name & Birth day \\
\midrule
Achard  & Jacques & 5 juin 1962 \\
Lefebvre & Mathilde & 23 mai 1988 \\
Vanesse & Stephany & 30 octobre 1994 \\
Dupont & Chantal & 15 janvier 1998 \\
\bottomrule
\end{NiceTabular}
\end{Code}


\begin{center}
\NewDocumentCommand { \Blue } { } { \columncolor{blue!15} }
\begin{NiceTabular}[color-inside]{>{\Blue}c>{\Blue}cc} 
\toprule
\rowcolor{red!15}
Last name & First name & Birth day \\
\midrule
Achard  & Jacques & 5 juin 1962 \\
Lefebvre & Mathilde & 23 mai 1988 \\
Vanesse & Stephany & 30 octobre 1994 \\
Dupont & Chantal & 15 janvier 1998 \\
\bottomrule
\end{NiceTabular}
\end{center}

\bigskip
Each use of the |\rowlistcolors| (or |\rowcolors|, which is, in fact, a
special case of |\rowlistcolors|) stops the potential coloring
schemes\footnote{We say \emph{schemes} in plural form because it's possible to
  start simultaneously several coloring schemes if they apply on different
  columns.} specified by a previous command |\rowlistcolors|. In particular,
it's possible to start coloring the rows with |\rowlistcolors{...}| and stop
coloring by a command |\rowlistcolors| with an empty argument.

\bigskip
\begin{Code}[width=10cm]
\begin{NiceTabular}{c}[hvlines,color-inside]
one \\
two \\
\emph{\rowlistcolors{red!15}}
three \\
four \\
five \\
\emph{\rowlistcolors{}}
six \\
seven \\
\end{NiceTabular}
\end{Code}
\begin{NiceTabular}{c}[hvlines,color-inside]
one \\
two \\
\rowlistcolors{red!15}
three \\
four \\
five \\
\rowlistcolors{}
six \\
seven \\
\end{NiceTabular}


\subsection{The special color ``nocolor''}

\index{nocolor}

The extension \pkg{nicematrix} provides the special color |nocolor| which may be
used in all the coloring commands provided by \pkg{nicematrix} (in the
|\CodeBefore| or the array itself).

The cells marked by this color won't be colored, whatever the other instructions
of coloring which may apply to these cells.

Therefore, the color |nocolor| is an easy way to add an exception to a more
general coloring command.

\section{The command \textbackslash RowStyle}

\label{RowStyle}
\indexcommand{RowStyle}
\index{cell-space-top-limit}
\index{cell-space-bottom-limit}
\index{cell-space-limits}


The command |\RowStyle| takes in as argument some formatting intructions that
will be applied to each cell on the rest of the current row.

\medskip
That command also takes in as optional argument (between square brackets)
a list of \textsl{key=value} pairs. 
\begin{itemize}
\item \index{nb-rows (key of \texttt{\textbackslash RowStyle})} The key \Definition{nb-rows} sets
the number of rows to which the specifications of the current command will
apply (with the special value |*|, it will apply to all the following rows).
\item The keys \Definition{cell-space-top-limit}, \Definition{cell-space-bottom-limit} and
\Definition{cell-space-limits} are available with the same meaning that the
corresponding global keys (cf. p.~\pageref{cell-space}).
\item \index{rowcolor (key of \texttt{\textbackslash RowStyle})}
\index{color!key of \texttt{\textbackslash RowStyle}}
The key \Definition{rowcolor} sets the color of the background and the key
\Definition{color} sets the color of the text.\footnote{The key |color| uses the command
|\color| but also inserts an instruction |\leavevmode| before. This
instruction prevents an extra vertical space in the cells which belong to
columns of type |p|, |b|, |m|, |X| and |V| (which start in
vertical mode of LaTeX).}
\item \index{bold (key of \texttt{\textbackslash RowStyle})} The key
\Definition{bold} enforces bold characters for the cells of the row, both in
math and text mode. 
\end{itemize}

\medskip
\begin{Code}[width=12cm]
\begin{NiceTabular}{cccc}
\hline
\emph{\RowStyle[cell-space-limits=3pt]{\rotate}}
first & second & third & fourth \\
\emph{\RowStyle[nb-rows=2,rowcolor=blue!50,color=white]{\sffamily}}
1 & 2 & 3 & 4 \\
I & II & III & IV 
\end{NiceTabular}
\end{Code}
\index{rotate@\texttt{\textbackslash rotate}|textit}
\begin{NiceTabular}{cccc}
\hline
\RowStyle[cell-space-limits=3pt]{\rotate}
first & second & third & fourth \\
\RowStyle[nb-rows=2,rowcolor=blue!50,color=white]{\sffamily}
1 & 2 & 3 & 4 \\
I & II & III & IV \\
\end{NiceTabular}

\medskip
The command |\rotate| is described p.~\pageref{rotate}.

\section{The width of the columns}

\label{width}
\index{width@\textbf{Width of the columns}|(}

\subsection{Basic tools}

In the environments with an explicit preamble (like |{NiceTabular}|,
|{NiceArray}|, etc.), it's possible to fix the width of a given column with
the standard letters |w|, |W|, |p|, |b| and |m| of the package \pkg{array}. 

\medskip
\begin{Code}[width=9cm]
\begin{NiceTabular}{\emph{W{c}{2cm}}cc}[hvlines]
Paris  & New York & Madrid \\
Berlin & London   & Roma   \\
Rio    & Tokyo    & Oslo 
\end{NiceTabular}
\end{Code}
\begin{NiceTabular}{W{c}{2cm}cc}[hvlines]
Paris  & New York & Madrid \\
Berlin & London   & Roma   \\
Rio    & Tokyo    & Oslo 
\end{NiceTabular}


\bigskip
\index{columns-width}
In the environments of \pkg{nicematrix}, it's also possible to fix the \emph{minimal}
width of all the columns (except the potential exterior columns: cf. p.~\pageref{exterior}) directly
with the key |columns-width|. 

\medskip
\begin{Code}[width=10cm]
$\begin{pNiceMatrix}[\emph{columns-width = 1cm}]
1  & 12 & -123 \\
12 & 0  & 0    \\
4  & 1  & 2 
\end{pNiceMatrix}$
\end{Code}
$\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 |\tabcolsep| in
|{NiceTabular}| and to 2 |\arraycolsep| in the other environments)
is not suppressed (of course, it's possible to suppress this space by setting
|\tabcolsep| or |\arraycolsep| equal to $0$~pt before the environment).

\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 PGF/TikZ
will have written informations in the |aux| file and a message requiring a
second compilation will appear).}\par\nobreak

\medskip
\begin{Code}[width=10cm]
$\begin{pNiceMatrix}[\emph{columns-width = auto}]
1  & 12 & -123 \\
12 & 0  & 0    \\
4  & 1  & 2 
\end{pNiceMatrix}$
\end{Code}
$\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 minimal width of the columns of all
the arrays of a current scope with the command
|\NiceMatrixOptions|.\par\nobreak

\medskip
\begin{Code}[width=8.5cm]
\emph{\NiceMatrixOptions{columns-width=10mm}}
$\begin{pNiceMatrix}
a & b \\ c & d 
\end{pNiceMatrix}
= 
\begin{pNiceMatrix}
1   & 1245 \\ 345 & 2 
\end{pNiceMatrix}$
\end{Code}
\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
\index{NiceMatrixBlock@\texttt{\{NiceMatrixBlock\}}}
\index{auto-columns-width!(key of \texttt{\{NiceMatrixBlock\}})}
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.}.
The environment |{NiceMatrixBlock}| has no direct link with the command
|\Block| presented previously in this document (cf.~p.~\pageref{Block}).

\medskip
\begin{Code}[width=8.5cm]
\emph{\begin{NiceMatrixBlock}[auto-columns-width]}
$\begin{array}{c}
\begin{bNiceMatrix}
 9 & 17 \\ -2 & 5 
 \end{bNiceMatrix} \\ \\
\begin{bNiceMatrix}
 1   & 1245345 \\  345 & 2 
\end{bNiceMatrix} \\
\end{array}$
\emph{\end{NiceMatrixBlock}}
\end{Code}
\begin{NiceMatrixBlock}[auto-columns-width]
$\begin{array}{c}
\begin{bNiceMatrix}
 9 & 17 \\ -2 & 5 
 \end{bNiceMatrix} \\ \\
\begin{bNiceMatrix}
 1   & 1245345 \\  345 & 2 
\end{bNiceMatrix} \\
\end{array}$
\end{NiceMatrixBlock}

\subsection{The columns X}

\label{X-columns}
\index{tabularx@\pkg{tabularx} (package)}
\index{NiceTabularX@\texttt{\{NiceTabularX\}}}
\index{X (the columns X)}
\index{width!key of \texttt{\{NiceTabular\}}}

The environment |{NiceTabular}| provides |X| columns similar to those provided
by the environment |{tabularx}| of the eponymous package.

The required width of the tabular may be specified with the key |width| (in
|{NiceTabular}| or in |\NiceMatrixOptions|). The initial value of this
parameter is |\linewidth| (and not |\textwidth|).

For sake of similarity with the environment |{tabularx}|, \pkg{nicematrix}
also provides an environment |{NiceTabularX}| with a syntax similar to the
syntax of |{tabularx}|, that is to say with a first mandatory argument
which is the width of the tabular.

As with the packages \pkg{tabu}\footnote{The extension \pkg{tabu} is now
considered as deprecated.} and \pkg{tabularray}, the specifier |X| takes
in an optional argument (between square brackets) which is a list of keys.
\begin{itemize}
\item It's possible to give a weight for the column by providing a positive
integer directly as argument of the specifier |X|. For example, a column
|X[2]| will have a width double of the width of a column~|X| (which has a
weight equal to $1$).\footnote{The negative values of the weight, as provided
by \pkg{tabu} (which is now obsolete), are \emph{not} supported by \pkg{nicematrix}.
If such a value is used, an error will be raised.}
\item It's possible to specify an horizontal alignment with one of the
letters |l|, |c| and |r| (which insert respectively |\raggedright|,
|\centering| and |\raggedleft| followed by |\arraybackslash|).
\item It's possible to specify a vertical alignment with one of the keys
|t| (alias |p|), |m| and |b| (which construct respectively columns of type
|p|, |m| and |b|). The default value is |t|.
\end{itemize}

\begin{Code}
\emph{\begin{NiceTabular}[width=9cm]{X[2,l]X[l]}[hvlines]}
a rather long text which fits on several lines 
& a rather long text which fits on several lines \\
a shorter text & a shorter text
\end{NiceTabular}
\end{Code}

\begin{center}
\begin{NiceTabular}[width=9cm]{X[2,l]X[l]}[hvlines]
a rather long text which fits on several lines 
& a rather long text which fits on several lines \\
a shorter text & a shorter text
\end{NiceTabular}
\end{center}


\subsection{The columns V of varwidth}

\label{varwidth}
\index{varwidth@\pkg{varwidth} (package)}
\index{V (the columns V of \pkg{varwidth})}


Let's recall first the behaviour of the environment |{varwidth}| of the
eponymous package \pkg{varwidth}. That environment is similar to the classical
environment |{minipage}| but the width provided in the argument is only the
\emph{maximal} width of the created box. In the general case, the width of the
box constructed by an environment |{varwidth}| is the natural width of its
contents.

\medskip
That point is illustrated on the following examples.

\medskip
\begin{Code}[width=6cm]
\fbox{%
\begin{\emph{varwidth}}{8cm}
\begin{itemize}
\item first item
\item second item
\end{itemize}
\end{\emph{varwidth}}}
\end{Code}
\fbox{\begin{varwidth}{8cm}
\begin{itemize}
\item first item
\item second item
\end{itemize}
\end{varwidth}}

\bigskip
\begin{Code}[width=6cm]
\fbox{%
\begin{\emph{minipage}}{8cm}
\begin{itemize}
\item first item
\item second item
\end{itemize}
\end{\emph{minipage}}}
\end{Code}
\fbox{\begin{minipage}{8cm}
\begin{itemize}
\item first item
\item second item
\end{itemize}
\end{minipage}}


\bigskip
The package \pkg{varwidth} provides also the column type |V|. A column of type
|V{|$\langle$\textsl{dim}$\rangle$|}| encapsulates all its cells in a
|{varwidth}| with the argument $\langle$\textsl{dim}$\rangle$ (and does also some tuning).

\smallskip
When the package \pkg{varwidth} is loaded, the columns |V| of \pkg{varwidth}
are supported by \pkg{nicematrix}. 

\medskip
\begin{Code}
\begin{NiceTabular}[corners=NW,hvlines]{\emph{V{3cm}V{3cm}V{3cm}}}
& some text & some very very very long text \\
some very very very long text \\
some very very very long text 
\end{NiceTabular}
\end{Code}

\medskip
\begin{center}
\begin{NiceTabular}[corners=NW,hvlines]{V{3cm}V{3cm}V{3cm}}
& some text & some very very very long text \\
some very very very long text \\
some very very very long text 
\end{NiceTabular}
\end{center}

\bigskip
Concerning \pkg{nicematrix}, one of the
interests of this type of columns is that, for a cell of a column of type~|V|,
the PGF/TikZ node created by \pkg{nicematrix} for the content of that cell has
a width adjusted to the content of the cell : cf. p.~\pageref{node-V}. 


\bigskip
The columns |V| of \pkg{nicematrix} supports the keys |t|, |p|, |m|, |b|, |l|,
|c| and |r| also supported by the columns |X|: see their description in the
section~\ref{X-columns}, p.~\pageref{X-columns}.

\bigskip
One should remark that the extension \pkg{varwidth} (at least in its version
0.92) has some problems: for instance, with LuaLaTeX, it does not work when
the content begins with |\color|.

\index{width@\textbf{Width of the columns}|)}


\bigskip
\section{The exterior rows and columns}

\index{first-row}
\index{last-row}
\index{first-col}
\index{last-col}

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}. It's particularly interesting for the (mathematical)
matrices. 
\label{exterior}

A potential ``first row'' (exterior) has the number $0$ (and not $1$). Idem
for the potential ``first column''. 

\begin{Code}
$\begin{pNiceMatrix}[\emph{first-row,last-row,first-col,last-col},nullify-dots]
       & C_1    & \Cdots &        & C_4    &        \\
L_1    & a_{11} & a_{12} & a_{13} & a_{14} & L_1    \\
\Vdots & a_{21} & a_{22} & a_{23} & a_{24} & \Vdots \\
       & a_{31} & a_{32} & a_{33} & a_{34} &        \\
L_4    & a_{41} & a_{42} & a_{43} & a_{44} & L_4    \\
       & C_1    & \Cdots &        & C_4    &     
\end{pNiceMatrix}$
\end{Code}

\[\begin{pNiceMatrix}[first-row,last-row,first-col,last-col,nullify-dots]
       & C_1    & \Cdots &        & C_4    &        \\
L_1    & a_{11} & a_{12} & a_{13} & a_{14} & L_1    \\
\Vdots & a_{21} & a_{22} & a_{23} & a_{24} & \Vdots \\
       & a_{31} & a_{32} & a_{33} & a_{34} &        \\
L_4    & a_{41} & a_{42} & a_{43} & a_{44} & L_4    \\
       & C_1    & \Cdots &        & C_4    &     
\end{pNiceMatrix}\]

\medskip
The dotted lines have been drawn with the tools presented p.~\pageref{Cdots}.

\bigskip
We have several remarks to do.
\begin{itemize}[beginpenalty=10000]
\item For the environments with an explicit preamble (i.e. |{NiceTabular}|,
|{NiceArray}| and its variants), no letter must be given in that preamble for
the potential first column and the potential last column: they will
automatically (and necessarily) be of type |r| for the first column and |l|
for the last one.\footnote{The users wishing exterior columns with another
type of alignment should consider the command |\SubMatrix| available in the
|\CodeAfter| and in the |\CodeBefore| (cf.~p.~\pageref{sub-matrix}).}
\item One may wonder how \pkg{nicematrix} determines the number of rows and
columns which are needed for the composition of the ``last row'' and ``last
column''.
\begin{itemize}
\item For the environments with explicit preamble, like |{NiceTabular}| and
|{pNiceArray}|, the number of columns can obviously be computed from the
preamble.

\item When the option |light-syntax| (cf. p. \pageref{light-syntax}) is used,
\pkg{nicematrix} has, in any case, to load the whole body of the environment
(and that's why it's not possible to put verbatim material in the array with
the option |light-syntax|). The analysis of this whole body gives the number
of rows and the number of columns.

\item In the other cases, \pkg{nicematrix} compute the number of rows and
columns during the first compilation and write the result in the |aux| file
for the next run.

\textsl{However, it's possible to provide the number of the last row and the
number of the last column as values of the options |last-row| and |last-col|,
tending to an acceleration of the whole compilation of the document.} That's
what we will do throughout the rest of the document.
\end{itemize}
\end{itemize}

\bigskip
\index{code-for-first-row}
\index{code-for-first-col}
\index{code-for-last-row}
\index{code-for-last-col}
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{Code}
\NiceMatrixOptions{\emph{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{displaymath}
\begin{pNiceArray}{cc|cc}[first-row,last-row=5,first-col,last-col,nullify-dots]
       & C_1    & \multicolumn1c{\Cdots} &        & C_4    &        \\
L_1    & a_{11} & a_{12} & a_{13} & a_{14} & L_1    \\
\Vdots & a_{21} & a_{22} & a_{23} & a_{24} & \Vdots \\
\hline
       & a_{31} & a_{32} & a_{33} & a_{34} &        \\
L_4    & a_{41} & a_{42} & a_{43} & a_{44} & L_4    \\
       & C_1    & \multicolumn1c{\Cdots} &        & C_4    &     
\end{pNiceArray}
\end{displaymath}
\end{Code}

\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{displaymath}
\begin{pNiceArray}{cc|cc}[first-row,last-row=5,first-col,last-col,nullify-dots]
       & C_1    & \multicolumn1c{\Cdots} &        & C_4    &        \\
L_1    & a_{11} & a_{12} & a_{13} & a_{14} & L_1    \\
\Vdots & a_{21} & a_{22} & a_{23} & a_{24} & \Vdots \\
\hline
       & a_{31} & a_{32} & a_{33} & a_{34} &        \\
L_4    & a_{41} & a_{42} & a_{43} & a_{44} & L_4    \\
       & C_1    & \multicolumn1c{\Cdots} &        & C_4    &     
\end{pNiceArray}
\end{displaymath}
\end{scope}


\emph{Remarks}
\begin{itemize}[beginpenalty=10000]
\item As shown in the previous example, the horizontal and vertical rules
don't extend in the exterior rows and columns. This remark also applies to the
customized rules created by the key |custom-line|
(cf.~p.~\pageref{custom-line}). 

\item A specification of color present in |code-for-first-row| also applies to
a dotted line drawn in that exterior ``first row'' (except if a value has
been given to |xdots/color|). Idem for the other exterior rows and columns.

\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. If you are looking for a workaround,
consider the command |\SubMatrix| in the |\CodeAfter| (and the |\CodeBefore|)
described p.~\pageref{sub-matrix}. 
\end{itemize}





\section{The continuous dotted lines}

\label{Cdots}
\index{dotted@\textbf{Dotted lines}|(}
\indexcommand{Ldots}
\indexcommand{Cdots}
\index{Ddots@\texttt{\textbackslash Ddots}|textbf}
\index{Iddots@\texttt{\textbackslash Iddots}|textbf}
\indexcommand{Vdots}
\index{mathdots@\pkg{mathdots} (package)}
\index{xdots (and its subkeys)}

Inside the environments of the package \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. 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. It's possible to change the color of these lines
with the option |color|.\footnote{It's also possible to change the color of
all these dotted lines with the option |xdots/color| (\textsl{xdots} to
remind that it works for |\Cdots|, |\Ldots|, |\Vdots|, etc.): cf. p.
\pageref{customisation}.}\par\nobreak  

\bigskip
\begin{Code}[width=10cm]
\begin{bNiceMatrix}
a_1      & \Cdots &        & & a_1    \\
\Vdots   & a_2    & \Cdots & & a_2    \\
         & \Vdots & \Ddots[color=red] \\
\\
a_1      & a_2    &        & & a_n 
\end{bNiceMatrix}
\end{Code}
$\begin{bNiceMatrix}
a_1      & \Cdots &        & & a_1    \\
\Vdots   & a_2    & \Cdots & & a_2    \\
         & \Vdots & \Ddots[color=red] \\
\\
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{Code}[width=10cm]
\begin{bNiceMatrix}
0      & \Cdots & 0      \\
\Vdots &        & \Vdots \\
0      & \Cdots & 0 
\end{bNiceMatrix}
\end{Code}
$\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{Code}[width=10cm]
\begin{bNiceMatrix}
0      & \Cdots & \Cdots & 0      \\
\Vdots &        &        & \Vdots \\
\Vdots &        &        & \Vdots \\
0      & \Cdots & \Cdots & 0 
\end{bNiceMatrix}
\end{Code}
$\begin{bNiceMatrix}
0      & \Cdots & \Cdots & 0      \\
\Vdots &        &        & \Vdots \\
\Vdots &        &        & \Vdots \\
0      & \Cdots & \Cdots & 0 
\end{bNiceMatrix}$

\bigskip
In the first column of this example, there are two instructions |\Vdots| but,
of course, only one dotted line is drawn.

\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{Code}[width=10cm]
\begin{bNiceMatrix}
0       & \Cdots &        & 0      \\
\Vdots  &        &        &        \\
        &        &        & \Vdots \\
0       &        & \Cdots & 0 
\end{bNiceMatrix}
\end{Code}
$\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}} 

\indexcommand{Hspace}
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{Code}[width=10cm]
$\begin{bNiceMatrix}
0      & \Cdots & \emph{\Hspace*{1cm}} & 0      \\
\Vdots &        &               & \Vdots \\[1cm]
0      & \Cdots &               & 0    
\end{bNiceMatrix}$
\end{Code}
$\begin{bNiceMatrix}
0      & \Cdots & \Hspace*{1cm} & 0      \\
\Vdots &        &               & \Vdots \\[1cm]
0      & \Cdots &               & 0    
\end{bNiceMatrix}$

\subsection{The option nullify-dots}

\index{nullify-dots}

Consider the following matrix composed classicaly with the environment
|{pmatrix}| of \pkg{amsmath}.\par\nobreak 

\medskip
\begin{Code}[width=10cm]
$A = \begin{pmatrix}
h & i & j & k & l & m \\
x &   &   &   &   & x 
\end{pmatrix}$
\end{Code}
$A = \begin{pmatrix}
h & i & j & k & l & m \\
x   &     &     &    &     & x 
\end{pmatrix}$


\bigskip
If we add |\ldots| instructions in the second row, the geometry of the
matrix is modified.\par\nobreak

\medskip
\begin{Code}[width=10cm]
$B = \begin{pmatrix}
h & i & j & k & l & m \\
x & \ldots & \ldots  & \ldots & \ldots & x 
\end{pmatrix}$
\end{Code}
$B = \begin{pmatrix}
h & i & j & k & l & m \\
x   & \ldots   & \ldots  & \ldots & \ldots & x 
\end{pmatrix}$

\bigskip
By default, with \pkg{nicematrix}, if we replace |{pmatrix}| by
|{pNiceMatrix}| and |\ldots| by |\Ldots|, the geometry of the matrix is not
changed.\par\nobreak 

\medskip
\begin{Code}[width=10cm]
$C = \begin{pNiceMatrix}
h & i & j & k & l & m \\
x & \Ldots & \Ldots & \Ldots & \Ldots & x 
\end{pNiceMatrix}$
\end{Code}
$C = \begin{pNiceMatrix}
h & i & j & k & l & m \\
x & \Ldots & \Ldots  & \Ldots & \Ldots & x 
\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 row. It's possible by
using the option |nullify-dots| (and only one instruction |\Ldots| is
necessary).\par\nobreak 

\medskip
\begin{Code}[width=10cm]
$D = \begin{pNiceMatrix}[\emph{nullify-dots}]
h & i & j & k & l & m \\
x & \Ldots & &  &  & x 
\end{pNiceMatrix}$
\end{Code}
$D = \begin{pNiceMatrix}[nullify-dots]
h & i & j & k & l & m \\
x & \Ldots & &  &  & x 
\end{pNiceMatrix}$

\medskip
The option |nullify-dots| smashes the instructions |\Ldots| (and the variants)
horizontally but also vertically.

\medskip
Caution : the key |nullify-dots| has a name that may be confusing; that key does
not imply that the dotted rules won't be drawn!



\subsection{The commands \textbackslash Hdotsfor and \textbackslash Vdotsfor}

\indexcommand{Hdotsfor}
\indexcommand{Vdotsfor}

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{Code}[width=7cm]
$\begin{pNiceMatrix}
1 & 2 & 3 & 4 & 5 \\
1 & \emph{\Hdotsfor{3}} & 5 \\
1 & 2 & 3 & 4 & 5 \\
1 & 2 & 3 & 4 & 5 
\end{pNiceMatrix}$
\end{Code}
$\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{Code}[width=7cm]
$\begin{pNiceMatrix}
1 & 2 & 3 & 4 & 5 \\
  & \emph{\Hdotsfor{3}} \\
1 & 2 & 3 & 4 & 5 \\
1 & 2 & 3 & 4 & 5 
\end{pNiceMatrix}$
\end{Code}
$\begin{pNiceMatrix}
1 & 2 & 3 & 4 & 5 \\
  & \Hdotsfor{3} \\
1 & 2 & 3 & 4 & 5 \\
1 & 2 & 3 & 4 & 5 
\end{pNiceMatrix}$

\medskip
Remark: Unlike the command |\hdotsfor| of \pkg{amsmath}, the command
|\Hdotsfor| may be used even when the package \pkg{colortbl}\footnote{We
recall that when \pkg{xcolor} is loaded with the option |table|, the
package \pkg{colortbl} is loaded.} is loaded (but you might have problem if
you use |\rowcolor| on the same row as |\Hdotsfor|). However, when using
\pkg{nicematrix}, it's recommended to use the coloring tools provided by
\pkg{nicematrix} instead of \pkg{colortbl}.

\bigskip
The package \pkg{nicematrix} also provides a command |\Vdotsfor| similar to
|\Hdotsfor| but for the vertical dotted lines.
\bigskip
The following example uses both |\Hdotsfor| and |\Vdotsfor|:

\smallskip
\begin{scope}
\small
\begin{Code}
\begin{bNiceMatrix}
C[a_1,a_1] & \Cdots & C[a_1,a_n]
  & \hspace*{20mm} & C[a_1,a_1^{(p)}] & \Cdots & C[a_1,a_n^{(p)}] \\
\Vdots & \Ddots & \Vdots
  & \emph{\Hdotsfor{1}} & \Vdots & \Ddots & \Vdots \\
C[a_n,a_1] & \Cdots & C[a_n,a_n]
  & & C[a_n,a_1^{(p)}] & \Cdots & C[a_n,a_n^{(p)}] \\
\rule{0pt}{15mm}\NotEmpty  & \emph{\Vdotsfor{1}} & & \Ddots & & \emph{\Vdotsfor{1}} \\
C[a_1^{(p)},a_1] & \Cdots & C[a_1^{(p)},a_n]
  & & C[a_1^{(p)},a_1^{(p)}] & \Cdots & C[a_1^{(p)},a_n^{(p)}] \\
\Vdots & \Ddots & \Vdots
  & \emph{\Hdotsfor{1}} & \Vdots & \Ddots & \Vdots \\
C[a_n^{(p)},a_1] & \Cdots & C[a_n^{(p)},a_n]
  & & C[a_n^{(p)},a_1^{(p)}] & \Cdots & C[a_n^{(p)},a_n^{(p)}]
\end{bNiceMatrix}
\end{Code}%
\end{scope}


\[\begin{bNiceMatrix}
C[a_1,a_1] & \Cdots & C[a_1,a_n] & \hspace*{20mm} & C[a_1,a_1^{(p)}] & \Cdots & C[a_1,a_n^{(p)}] \\
\Vdots & \Ddots & \Vdots & \Hdotsfor{1} &  \Vdots & \Ddots & \Vdots \\
C[a_n,a_1] & \Cdots & C[a_n,a_n] & & C[a_n,a_1^{(p)}] & \Cdots & C[a_n,a_n^{(p)}] \\
\rule{0pt}{15mm}\NotEmpty & \Vdotsfor{1} & & \Ddots & & \Vdotsfor{1} \\
C[a_1^{(p)},a_1] & \Cdots & C[a_1^{(p)},a_n] & & C[a_1^{(p)},a_1^{(p)}] & \Cdots & C[a_1^{(p)},a_n^{(p)}] \\
\Vdots & \Ddots & \Vdots & \Hdotsfor{1} & \Vdots & \Ddots & \Vdots \\
C[a_n^{(p)},a_1] & \Cdots & C[a_n^{(p)},a_n] & & C[a_n^{(p)},a_1^{(p)}] & \Cdots & C[a_n^{(p)},a_n^{(p)}]
\end{bNiceMatrix}\]



\subsection{How to generate the continuous dotted lines transparently}

\index{renew-matrix}
\index{renew-dots}

Imagine you have a document with a great number of mathematical matrices with
ellipsis. You may wish to use the dotted lines of \pkg{nicematrix} without
having to modify the code of each matrix. It's possible with the keys.
|renew-dots| and |renew-matrix|.\footnote{The options |renew-dots|,
|renew-matrix| can be fixed with the command
|\NiceMatrixOptions| like the other options. However, they can also be fixed
as options of the command |\usepackage|.}

\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 keys |renew-dots| and |renew-matrix|, a classical code
gives directly the ouput of \pkg{nicematrix}.\par\nobreak

\medskip
\begin{scope}
\NiceMatrixOptions{renew-dots,renew-matrix}
\begin{Code}[width=10cm]
\emph{\NiceMatrixOptions{renew-dots,renew-matrix}}
\begin{pmatrix}
1      & \cdots & \cdots & 1      \\
0      & \ddots &        & \vdots \\
\vdots & \ddots & \ddots & \vdots \\
0      & \cdots & 0      & 1
\end{pmatrix}
\end{Code}
$\begin{pmatrix}
1      & \cdots & \cdots & 1      \\
0      & \ddots &        & \vdots \\
\vdots & \ddots & \ddots & \vdots \\
0      & \cdots & 0      & 1
\end{pmatrix}$
\end{scope}

\subsection{The labels of the dotted lines}

The commands |\Ldots|, |\Cdots|, |\Vdots|, |\Ddots|, |\Iddots|, |\Hdotsfor| and
|\Vdotsfor| (and the command |\line| in the |\CodeAfter| which is described
p.~\pageref{line-in-code-after}) accept two optional arguments specified by the
tokens |_| and |^| for labels positionned below and above the line. The
arguments are composed in math mode with |\scriptstyle|.

The version 6.22 of \pkg{nicematrix} has introduced a new label, specified by
the token ``|:|'' for a label placed on the line. The label is composed on a
white background which is put on the line previously drawn (see example on
p.~\pageref{ex:colon}).

\bigskip
\begin{Code}[width=10cm]
$\begin{bNiceMatrix}
1 & \hspace*{1cm}            & 0 \\[8mm]
  & \emph{\Ddots^{n \text{ times}}} &   \\
0 &                          & 1 
\end{bNiceMatrix}$
\end{Code}
$\begin{bNiceMatrix}
1 & \hspace*{1cm}            & 0 \\[8mm]
  & \Ddots^{n \text{ times}} &   \\
0 &                          & 1 
\end{bNiceMatrix}$


\bigskip
With the key |xdots/horizontal-labels|, the labels stay horizontal.\par\nobreak
%
\medskip
\begin{Code}[width=10cm]
$\begin{bNiceMatrix}[xdots/horizontal-labels]
1 & \hspace*{1cm}            & 0 \\[8mm]
  & \emph{\Ddots^{n \text{ times}}} &   \\
0 &                          & 1 
\end{bNiceMatrix}$
\end{Code}
$\begin{bNiceMatrix}[xdots/horizontal-labels]
1 & \hspace*{1cm}            & 0 \\[8mm]
  & \Ddots^{n \text{ times}} &   \\
0 &                          & 1 
\end{bNiceMatrix}$


\subsection{Customisation of the dotted lines}

\label{customisation} 
\index{color!key for the dotted rules}
\index{radius (key for the dotted rules)}
\index{inter (key for the dotted rules)}
\index{line-style (key for the dotted rules)}
\index{shorten (key for the dotted rules)}
\index{shorten-end (key for the dotted rules)}
\index{shorten-start (key for the dotted rules)}
\index{horizontal-labels (key for the dotted rules)}

The dotted lines drawn by |\Ldots|, |\Cdots|, |\Vdots|, |\Ddots|, |\Iddots|,
|\Hdotsfor| and |\Vdotsfor| (and by the command |\line| in the |\CodeAfter|
which is described p.~\pageref{line-in-code-after}) may be customized by the following
options (specified between square brackets after the command):
\begin{itemize}
\item |horizontal-labels|;
\item |color|;
\item |radius|;
\item |shorten-start|, |shorten-end| and |shorten|;
\item |inter|;
\item |line-style|.
\end{itemize}

These options may also be fixed with |\NiceMatrixOptions|, as options of
|\CodeAfter| or at the level of a given environment but, in those cases, they
must be prefixed by |xdots| (\textsl{xdots} to remind that it works for
|\Cdots|, |\Ldots|, |\Vdots|, etc.), and, thus have for names:
\begin{itemize}
\item |xdots/horizontal-labels|;
\item |xdots/color|;
\item |xdots/radius|;
\item |xdots/shorten-start|, |xdots/shorten-end| and |xdots/shorten|;
\item |xdots/inter|;
\item |xdots/line-style|.
\end{itemize}

For the clarity of the explanations, we will use those names.


\bigskip
With the key \Definition{xdots/horizontal-labels}, the labels (introduced by~|_|,
|^| and~|:|) stay horizontal.

\bigskip
The option \Definition{xdots/color} fixes the color or the dotted line. However,
one should remark that the dotted lines drawn in the exterior rows and columns
have a special treatment: cf. p.~\pageref{exterior}.

\bigskip
The option \Definition{radius} fixes the radius of the dots. The initial value
is 0.53~pt.

\bigskip
The keys \Definition{xdots/shorten-start} and \Definition{xdots/shorten-end} fix
the margin at the extremities of the line. The key |xdots/shorten| fixes both
parameters. The initial value is 0.3~em (it is recommanded to use a unit of
length dependent of the current font).\footnote{In fact, when 
  |xdots/shorten|, |xdots/shorten-start| and |xdots/shorten-end| are used in
  |\NiceMatrixOptions| or at the level of an environment (such as
  |{pNiceMatrix}|), those keys only apply to the extremeties of dotted lines
  corresponding to a non-empty content of a cell. When they are used for a command
  such as |\Cdots| (and, in that case, their names are |shorten|,
  |shorten-start| and |shorten-end|), they apply to all the extremities.}

\bigskip
The option \Definition{xdots/inter} fixes the length between the dots. The
initial value is 0.45~em (it is recommanded to use a unit of length dependent of
the current font).

\bigskip
\textbf{The option \Definition{xdots/line-style}}\par\nobreak

\smallskip
It should be pointed that, by default, the lines drawn by TikZ with the
parameter |dotted| are composed of square dots (and not rounded
ones).\footnote{The first reason of this behaviour is that the \textsc{pdf}
format includes a description for dashed lines. The lines specified with this
descriptor are displayed very efficiently by the \textsc{pdf} readers. It's
easy, starting from these dashed lines,
to create a line composed by square dots whereas a line of rounded dots needs
a specification of each dot in the \textsc{pdf} file. Nevertheless, you can
have a look at the following page to see how to have dotted rules with rounded
dots in TikZ:\newline \small
\url{https://tex.stackexchange.com/questions/52848/tikz-line-with-large-dots}}

\begin{BVerbatim}[baseline=c,boxwidth=9cm]
\tikz \draw [dotted] (0,0) -- (5,0) ;
\end{BVerbatim}
\tikz \draw [dotted] (0,0) -- (5,0) ;

\medskip
In order to provide lines with rounded dots in the style of those provided by
|\ldots| (at least with the \emph{Computer Modern} fonts), the package
\pkg{nicematrix} embeds its own system to draw a dotted line (and this system
uses \textsc{pgf} and not TikZ). This style is called |standard| and that's
the initial value of the parameter |xdots/line-style|.

However (when TikZ is loaded) it's possible to use for |xdots/line-style| any style
provided by TikZ, that is to say any sequence of options provided by TikZ for
the TikZ pathes (with the exception of ``|color|'', ``|shorten >|'' and
``|shorten <|'').

\medskip
Here is for example a tridiagonal matrix with the style |loosely dotted|:\par\nobreak

\medskip
\begin{Code}
$\begin{pNiceMatrix}[nullify-dots,\emph{xdots/line-style=loosely dotted}]
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{Code}


\[\begin{pNiceMatrix}[nullify-dots,xdots/line-style=loosely dotted]
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}\]


\subsection{The dotted lines and the rules}

\label{dotted-and-rules}

The dotted lines determine virtual blocks which have the same behaviour
regarding the rules (the rules specified by the specifier \verb+|+ in the
preamble, by the command |\Hline|, by the keys |hlines|, |vlines|,
|hvlines| and |hvlines-except-borders| and by the tools created by
|custom-line| are not drawn within the
blocks).\footnote{On the other side, the command |\line| in the
|\CodeAfter| (cf.~p.~\pageref{line-in-code-after}) does \emph{not} create
block.}

\medskip
\begin{Code}[width=10.6cm]
$\begin{bNiceMatrix}[margin,\emph{hvlines}]
\Block{3-3}<\LARGE>{A} & & & 0 \\
& \hspace*{1cm} & & \Vdots \\
& & & 0 \\
0 & \Cdots& 0 & 0
\end{bNiceMatrix}$
\end{Code}
$\begin{bNiceMatrix}[margin,hvlines]
\Block{3-3}<\LARGE>{A} & & & 0 \\
& \hspace*{1cm} & & \Vdots \\
& & & 0 \\
0 & \Cdots& 0 & 0
\end{bNiceMatrix}$


\index{dotted@\textbf{Dotted lines}|)}

\section{Delimiters in the preamble of the environment}

\index{blkarray@\pkg{blkarray} (package)}

\index{delimiters@delimiters in the preambles}

\label{delimiters-in-preamble}

In the environments with preamble (|{NiceArray}|, |{pNiceArray}|, etc.), it's
possible to put vertical delimiters directly in the preamble of the
environment.\footnote{This syntax is inspired by the extension \pkg{blkarray}.}

\smallskip
\index{left@\texttt{\textbackslash left} : used by \pkg{nicematrix} for\newline 
  delimiters in the preambles}
\index{right@\texttt{\textbackslash right} : used by \pkg{nicematrix} for\newline 
  delimiters in the preambles}
The opening delimiters should be prefixed by the keyword |\left| and the
closing delimiters by the keyword |\right|. It's not mandatory to use
|\left| and |\right| pair-wise.

\smallskip
All the vertical extensible delimiters of LaTeX are allowed.

\medskip
Here is a example which uses the delimiters |\lgroup| and |\rgroup|.

\smallskip
\begin{Code}
$\begin{NiceArray}{\emph{\left\lgroup} ccc\emph{\right\rgroup} l}
1 & 2 & 3 &  
4 & 1 & 6 & 
7 & 8 & 9 & \scriptstyle L_3 \gets L_3 + L_1 + L_2
\end{NiceArray}$
\end{Code}

\[\begin{NiceArray}{\left\lgroup ccc\right\rgroup l}
1 & 2 & 3 &  \\
4 & 1 & 6 &  \\
7 & 8 & 9 & \scriptstyle L_3 \gets L_3 + L_1 + L_2
\end{NiceArray}\]

\medskip
For this example, it would also have been possible to use the environment
|{NiceArrayWithDelims}| (cf. the section \ref{NiceArrayWithDelims},
p.~\pageref{NiceArrayWithDelims}) and the key |last-col| (cf. p.~\pageref{exterior}).

\bigskip
There is a particular case: for the delimiters |(|, |[| and |\{|\footnote{For
  the braces, the protection by a backslash is mandatory (that's why we have
  written |\{|).},
and the corresponding closing delimiters, the prefixes |\left| et |\right| are
optional.\footnote{For the delimiters |[| and |]|, the prefixes remain mandatory
when there is a conflict of notation with the square brackets for the options
of some descriptors of columns.}

\bigskip
Here is an example with a left delimiter |\{| in a |{NiceTabular}| (remark the
compatibility with the key |t|).

\smallskip
\begin{Verbatim}
We define $f$ with\quad
\begin{NiceTabular}[t]{\{ll}
$f(x) = 0$ & if $x$ is non positive \\
$f(x) = 1-e^x$ & if $x$ is positive
\end{Verbatim}

\smallskip
\begin{center}
On définit $f$ par\quad
\begin{NiceTabular}[t]{\{ll}
$f(x) = 0$ & if $x$ is non positive\\
$f(x) = 1-e^x$ & if $x$ is positive
\end{NiceTabular}
\end{center}


\bigskip
When there are two successive delimiters (necessarily a closing one following by
an opening one for another submatrix), a space equal to |\enskip| is
automatically inserted.

\medskip
\begin{Code}
$\begin{pNiceArray}{\emph{(c)(c)(c)}}
a_{11} & a_{12}                                     & a_{13} \\
a_{21} & \displaystyle \int_0^1\dfrac{1}{x^2+1}\,dx & a_{23} \\
a_{31} & a_{32}                                     & a_{33} 
\end{pNiceArray}$
\end{Code}

\[\begin{pNiceArray}{(c)(c)(c)}
a_{11} & a_{12}                                     & a_{13} \\
a_{21} & \displaystyle \int_0^1\dfrac{1}{x^2+1}\,dx & a_{23} \\
a_{31} & a_{32}                                     & a_{33} 
\end{pNiceArray}\]


\bigskip
For more complex constructions, in particular with delimiters spanning only a
\emph{subset} of the rows of the array, one should consider the command
|\SubMatrix| available in the |\CodeAfter| (and the |\CodeBefore|). See the
section~\ref{sub-matrix}, p.~\pageref{sub-matrix}.  

\section{The \textbackslash CodeAfter}

\index{CodeAfter@\texttt{\textbackslash CodeAfter}|(}
\index{code-after}

\label{code-after}
The option |code-after| may be used to give some code that will be executed
\emph{after} the construction of the matrix.\footnote{There is also a key
|code-before| described p.~\pageref{code-before}.}

\medskip
\index{sub-matrix (key of \texttt{\textbackslash CodeAfter}, with subkeys)}
For the legibility of the code, an alternative syntax is provided: it's
possible to give the instructions of the |code-after| at the end of the
environment, after the keyword |\CodeAfter|. Although |\CodeAfter| is a
keyword, it takes in an optional argument (between square
brackets).\footnote{Here are the keys accepted in that argument:
|delimiters/color|, |rules| and its sub-keys, |sub-matrix| (linked to the
command |\SubMatrix|) and its sub-keys and |xdots| (for the command |\line|) and
its sub-keys.} 


\medskip
The experienced users may, for instance, use the PGF/TikZ nodes created by
\pkg{nicematrix} in the |\CodeAfter|. These nodes are described further
beginning on p.~\pageref{PGF-nodes}.

\medskip
Moreover, several special commands are available in the |\CodeAfter|: |line|, 
|\SubMatrix|, |\OverBrace|, |\UnderBrace| and |\TikzEveryCell|. We will now
present these commands. 

\subsection{The command \textbackslash line in the \textbackslash CodeAfter}

\label{line-in-code-after}
\index{line@\texttt{\textbackslash line} (command of \texttt{\textbackslash CodeAfter})}
The command |\line| draws directly dotted lines between cells or blocks. It takes in two
arguments for the cells or blocks to link. Both argument may be:
\begin{itemize}
\item a specification of cell of the form  $i$-$j$ where is the
number of the row and $j$ is the number of the column;
\item the name of a block (created by the command |\Block| with the key |name|
of that command).
\end{itemize}
The options available for the customisation of the dotted lines created by
|\Cdots|, |\Vdots|, etc. are also available for this command (cf.
p.~\pageref{customisation}).

\bigskip
This command may be used, for example, to draw a dotted line between two
adjacent cells.

\medskip
\begin{Code}[width=11cm]
\NiceMatrixOptions{xdots/shorten = 0.6 em}
\begin{pNiceMatrix}
I       & 0      & \Cdots  &0     \\
0       & I      & \Ddots  &\Vdots\\
\Vdots  &\Ddots  & I       &0     \\
0       &\Cdots  & 0       &I
\emph{\CodeAfter \line{2-2}{3-3}}
\end{pNiceMatrix}
\end{Code}
\begin{scope}
\NiceMatrixOptions{xdots/shorten = 0.6 em}
$\begin{pNiceMatrix}
I       & 0      & \Cdots  &0     \\
0       & I      & \Ddots  &\Vdots\\
\Vdots  &\Ddots  & I       &0     \\
0       &\Cdots  & 0       &I
\CodeAfter \line{2-2}{3-3}
\end{pNiceMatrix}$
\end{scope}

\bigskip
It can also be used to draw a diagonal line not parallel to the other diagonal
lines (by default, the dotted lines drawn by |\Ddots| are ``parallelized'':
cf.~p.~\pageref{parallelization}).

\medskip
\begin{Code}
\begin{bNiceMatrix}
1      & \Cdots &   & 1      & 2      & \Cdots          & 2      \\
0      & \Ddots &   & \Vdots & \Vdots & \hspace*{2.5cm} & \Vdots \\
\Vdots & \Ddots &   &        &        &                 &        \\
0      & \Cdots & 0 & 1      & 2      & \Cdots          & 2 
\emph{\CodeAfter \line[shorten=6pt]{1-5}{4-7}}
\end{bNiceMatrix}
\end{Code}
\[\begin{bNiceMatrix}
1      & \Cdots &   & 1      & 2      & \Cdots          & 2     \\
0      & \Ddots &   & \Vdots & \Vdots & \hspace*{2.5cm} & \Vdots \\
\Vdots & \Ddots &   &        &        &                 &        \\
0      & \Cdots & 0 & 1      & 2      & \Cdots          & 2 
\CodeAfter \line[shorten=6pt]{1-5}{4-7}
\end{bNiceMatrix}\]




\subsection{The command \textbackslash SubMatrix in the \textbackslash
CodeAfter (and the \textbackslash CodeBefore)}

\label{sub-matrix}
\index{SubMatrix@\texttt{\textbackslash SubMatrix} (command of 
\texttt{\textbackslash CodeAfter}\newline and 
\texttt{\textbackslash CodeBefore})|textbf}


The command |\SubMatrix| provides a way to put delimiters on a portion
of the array considered as a submatrix. The command |\SubMatrix| takes in five
arguments:
\begin{itemize}
\item the first argument is the left delimiter, which may be any extensible delimiter
provided by LaTeX : |(|, |[|, |\{|, |\langle|, |\lgroup|, |\lfloor|, etc. but also
the null delimiter |.|;
\item the second argument is the upper-left corner of the submatrix with the
syntax $i$|-|$j$ where $i$ the number of row and $j$ the number of column;
\item the third argument is the lower-right corner with the same syntax;
\item the fourth argument is the right delimiter;
\item the last argument, which is optional, is a list of \textsl{key=value}
pairs.\footnote{There is no optional argument between square brackets in first
position because a square bracket just after |\SubMatrix| must be interpreted
as the first (mandatory) argument of the command |\SubMatrix|: that bracket is
the left delimiter of the sub-matrix to construct (eg.:
|\SubMatrix[{2-2}{4-7}]|).} 
\end{itemize}

One should remark that the command |\SubMatrix| draws the delimiters \emph{after} the
construction of the array: no space is inserted by the command |\SubMatrix|
itself. That's why, in the following example, we have used the key |margin|
and you have added by hand some space between the third and fourth column with
|@{\hspace{1.5em}}| in the preamble of the array.

\medskip
\begin{Code}[width=15cm]
\[\begin{NiceArray}{ccc\emph{@{\hspace{1.5em}}}c}[cell-space-limits=2pt,\emph{margin}]
 1           & 1            & 1            & x \\
\dfrac{1}{4} & \dfrac{1}{2} & \dfrac{1}{4} & y \\
 1           & 2            & 3            & z 
\CodeAfter
  \emph{\SubMatrix({1-1}{3-3})
  \SubMatrix({1-4}{3-4})}
\end{NiceArray}\]
\end{Code}
\hspace{-4cm}
$\begin{NiceArray}{ccc@{\hspace{1.5em}}c}[cell-space-limits=2pt,margin]
 1          & 1           & 1           & x \\
\dfrac{1}{4} & \dfrac{1}{2} & \dfrac{1}{4} & y \\
 1          & 2           & 3           & z 
\CodeAfter
  \SubMatrix({1-1}{3-3})
  \SubMatrix({1-4}{3-4})
\end{NiceArray}$

\medskip
Eventually, in this example, it would probably have been easier to put the
delimiters directly in the preamble of |{NiceArray}| (see
section~\ref{delimiters-in-preamble}, p.~\pageref{delimiters-in-preamble})
with the following construction.

\medskip
\begin{scope}
\hfuzz=15cm
\begin{Code}[width=11cm]
$\begin{NiceArray}{\emph{(ccc)(c)}}[cell-space-limits=2pt]
 1          & 1           & 1           & x \\
\dfrac{1}{4} & \dfrac{1}{2} & \dfrac{1}{4} & y \\
 1          & 2           & 3           & z 
\end{NiceArray}$
\end{Code}
\end{scope}
$\begin{NiceArray}{(ccc)(c)}[cell-space-limits=2pt]
 1          & 1           & 1           & x \\
\dfrac{1}{4} & \dfrac{1}{2} & \dfrac{1}{4} & y \\
 1          & 2           & 3           & z 
\end{NiceArray}$

\bigskip
In fact, the command |\SubMatrix| also takes in two optional arguments
specified by the traditional symbols |^| and |_| for material in superscript
and subscript.

\medskip
\begin{scope}
\hfuzz=15cm
\begin{Code}[width=11cm]
$\begin{bNiceMatrix}[right-margin=1em]
1 & 1 & 1 \\
1 & a & b \\
1 & c & d 
\CodeAfter
  \emph{\SubMatrix[{2-2}{3-3}]^{T}}
\end{bNiceMatrix}$
\end{Code}
$\begin{bNiceMatrix}[right-margin=1em]
1 & 1 & 1 \\
1 & a & b \\
1 & c & d 
\CodeAfter
  \SubMatrix[{2-2}{3-3}]^{T}
\end{bNiceMatrix}$
\end{scope}


\bigskip
The options of the command |\SubMatrix| are as follows:
\begin{itemize}
\item 
\index{left-xshift (key of \texttt{\textbackslash SubMatrix})}
\index{right-xshift (key of \texttt{\textbackslash SubMatrix})}
\index{xshift (key of \texttt{\textbackslash SubMatrix})}
\Definition{left-xshift} and \Definition{right-xshift} shift
horizontally the delimiters (there exists also the key \Definition{xshift}
which fixes both parameters);
\item \index{extra-height (key of \texttt{\textbackslash SubMatrix})}
\Definition{extra-height} adds a quantity to the total height of the
delimiters (height |\ht| + depth |\dp|);
\item \index{delimiters!---/color pour \texttt{\textbackslash SubMatrix}}
\Definition{delimiters/color} fixes the color of the delimiters (also
available in |\NiceMatrixOptions|, in the environments with delimiters and as
option of the keyword |\CodeAfter|);
\item \index{slim (key of \texttt{\textbackslash SubMatrix})}
\Definition{slim} is a boolean key: when that key is in force, the horizontal
position of the delimiters is computed by using only the contents of the cells
of the submatrix whereas, in the general case, the position is computed by
taking into account the cells of the whole columns implied in the submatrix
(see example below). ;
\item \index{vlines!key of \texttt{\textbackslash SubMatrix}}
\Definition{vlines} contents a list of numbers of vertical rules that
will be drawn in the sub-matrix (if this key is used without value, all the
vertical rules of the sub-matrix are drawn);
\item \index{hlines!key of \texttt{\textbackslash SubMatrix}}
\Definition{hlines} is similar to |vlines| but for the horizontal rules;
\item \index{hvlines!key of \texttt{\textbackslash SubMatrix}}
\Definition{hvlines}, which must be used without value, draws all the
vertical and horizontal rules;
\item \index{code (key of \texttt{\textbackslash SubMatrix})}
\Definition{code} insert code, especially TikZ code, after the
construcion of the submatrix. That key is detailed below.
\end{itemize}
One should remark that the keys add their rules after the construction of
the main matrix: no space is added between the rows and the columns of the
array for theses rules.

\bigskip 
All these keys are also available in |\NiceMatrixOptions|, at the level of the
environments of \pkg{nicematrix} or as option of the command |\CodeAfter| with
the prefix |sub-matrix| which means that their names are therefore
|sub-matrix/left-xshift|, |sub-matrix/right-xshift|, |sub-matrix/xshift|, etc.

\bigskip

\begin{Code}[width=15cm]
$\begin{NiceArray}{cc@{\hspace{5mm}}l}[cell-space-limits=2pt]
  &   & \frac{1}{2} \\
  &   & \frac{1}{4} \\[1mm]
a & b & \frac{1}{2}a+\frac{1}{4}b \\
c & d & \frac{1}{2}c+\frac{1}{4}d \\
\CodeAfter 
  \SubMatrix({1-3}{2-3}) 
  \SubMatrix({3-1}{4-2}) 
  \SubMatrix({3-3}{4-3})
\end{NiceArray}$
\end{Code}
\hspace{-4cm}
$\begin{NiceArray}{cc@{\hspace{5mm}}l}[cell-space-limits=2pt]
         &   & \frac12 \\
         &      & \frac14 \\[1mm]
a & b & \frac12a+\frac14b \\
c & d & \frac12c+\frac14d \\
\CodeAfter
  \SubMatrix({1-3}{2-3})
  \SubMatrix({3-1}{4-2})
  \SubMatrix({3-3}{4-3})
\end{NiceArray}$

\medskip
Here is the same example with the key |slim| used for one of the submatrices.

\medskip
\begin{Code}[width=15cm]
$\begin{NiceArray}{cc@{\hspace{5mm}}l}[cell-space-limits=2pt]
  &   & \frac12 \\
  &   & \frac14 \\[1mm]
a & b & \frac12a+\frac14b \\
c & d & \frac12c+\frac14d \\
\CodeAfter
  \SubMatrix({1-3}{2-3})[\emph{slim}]
  \SubMatrix({3-1}{4-2})
  \SubMatrix({3-3}{4-3})
\end{NiceArray}$
\end{Code}
\hspace{-4cm}
$\begin{NiceArray}{cc@{\hspace{5mm}}l}[cell-space-limits=2pt]
         &   & \frac12 \\
         &      & \frac14 \\[1mm]
a & b & \frac12a+\frac14b \\
c & d & \frac12c+\frac14d \\
\CodeAfter
  \SubMatrix({1-3}{2-3})[slim]
  \SubMatrix({3-1}{4-2})
  \SubMatrix({3-3}{4-3})
\end{NiceArray}$


\bigskip
There is also a key |name| which gives a name to the submatrix created by
|\SubMatrix|. That name is used to create PGF/TikZ nodes: cf
p.~\pageref{node-sub-matrix}. 


\bigskip
Despite its name, the command |\SubMatrix| may also be used within a 
|{NiceTabular}|. Here is an example (which uses |\bottomrule| and
|\toprule| of \pkg{booktabs}). 

\medskip
\begin{Code}[width=8cm]
\begin{NiceTabular}{@{}ll@{}}
\toprule
Part A              & the first part \\
\Block{2-1}{Part B} & a first sub-part \\
                    & a second sub-part \\
\bottomrule
\CodeAfter
  \emph{\SubMatrix{\{}{2-2}{3-2}{.}}
\end{NiceTabular}
\end{Code}
\hspace{2cm}
\begin{NiceTabular}{@{}ll@{}}
\toprule
Part A              & the first part \\
\Block{2-1}{Part B} & a first sub-part \\
                    & a second sub-part \\
\bottomrule
\CodeAfter
  \SubMatrix{\{}{2-2}{3-2}{.}
\end{NiceTabular} 

\bigskip
The command |\SubMatrix| is, in fact, also available in the |\CodeBefore|. By
using |\SubMatrix| in the |\CodeBefore|, the delimiters drawn by those
commands |\SubMatrix| are taken into account to limit the continuous dotted
lines (drawn by |\Cdots|, |\Vdots|, etc.) which have an open extremity.

For an example, see voir \ref{submatrix-in-codebefore} 
p.~\pageref{submatrix-in-codebefore}.


\vspace{1cm}
\emph{Caution} : The following functionnality is fragile and does not work with
|latex|--|dvips|--|ps2pdf|.\par\nobreak

The key |code| of the command |\SubMatrix| allows the insertion of code after
the construction of the submatrix. It's meant to be used to insert TikZ
instructions because, in the TikZ instructions inserted by that code, the
nodes of the form \verb+i-|j+ are interpreted with |i| and |j| as
numbers of row and columns \emph{relative to the submatrix}.\footnote{Be
careful: the syntax \verb+j|-i+ is \emph{not} allowed.}

\medskip
\begin{Code}
$\begin{NiceArray}{ccc@{}w{c}{5mm}@{}ccc}
    &   &   && -1 & 1  & 2  \\
    &   &   &&  0 & 3  & 4  \\
    &   &   &&  0 & 0  & 5  \\
  1 & 2 & 3 && -1 & 7  & 25 \\
  0 & 4 & 5 && 0  & 12 & 41 \\
  0 & 0 & 6 && 0  & 0  & 30  
\CodeAfter
  \emph{\NewDocumentCommand{\MyDraw}{}{\tikz \draw [blue] (2-|1) -| (3-|2) -|
      (4-|3) ;}}
  \SubMatrix({1-5}{3-7})[\emph{code = \MyDraw} ]
  \SubMatrix({4-1}{6-3})[\emph{code = \MyDraw} ]
  \SubMatrix({4-5}{6-7})[\emph{code = \MyDraw} ]
\end{NiceArray}$
\end{Code}%



\[\begin{NiceArray}{ccc@{}w{c}{5mm}@{}ccc}
    &   &   && -1 & 1  & 2  \\
    &   &   &&  0 & 3  & 4  \\
    &   &   &&  0 & 0  & 5  \\
  1 & 2 & 3 && -1 & 7  & 25 \\
  0 & 4 & 5 && 0  & 12 & 41 \\
  0 & 0 & 6 && 0  & 0  & 30  
\CodeAfter
  \NewDocumentCommand{\MyDraw}{}{\tikz \draw [blue] (2-|1) -| (3-|2) -| (4-|3) ;}
  \SubMatrix({1-5}{3-7})[code = \MyDraw ]
  \SubMatrix({4-1}{6-3})[code = \MyDraw ]
  \SubMatrix({4-5}{6-7})[code = \MyDraw ]
\end{NiceArray}\]

\medskip
As we see, the drawing done by our command |\MyDraw| is \emph{relative} to the
submatrix to which it is applied.

\subsection{The commands \textbackslash OverBrace and \textbackslash
UnderBrace in the \textbackslash CodeAfter}

\index{UncerBrace@\texttt{\textbackslash UnderBrace} (command of 
\texttt{\textbackslash CodeAfter}\newline and
\texttt{\textbackslash CodeBefore})}
\index{OverBrace@\texttt{\textbackslash OverBrace} (command of 
\texttt{\textbackslash CodeAfter}\newline and
\texttt{\textbackslash CodeBefore})}

The commands |\OverBrace| and |\UnderBrace| provide a way to put
horizontal braces on a part of the array. These commands take in three
arguments:
\begin{itemize}
\item the first argument is the upper-left corner of the submatrix with the
syntax $i$|-|$j$ where $i$ the number of row and $j$ the number of column;
\item the second argument is the lower-right corner with the same syntax;
\item the third argument is the label of the brace that will be put by
\pkg{nicematrix} (with \textsc{pgf}) above the brace (for the command
|\OverBrace|) or under the brace (for |\UnderBrace|).
\end{itemize}

\bigskip
\begin{Code}[width=9cm]
\begin{pNiceMatrix}
1  & 2  & 3  & 4  & 5  & 6  \\
11 & 12 & 13 & 14 & 15 & 16 \\
\CodeAfter
  \emph{\OverBrace{1-1}{2-3}{A}
  \OverBrace{1-4}{2-6}{B}}
\end{pNiceMatrix}
\end{Code}
$\begin{pNiceMatrix}
1  & 2  & 3  & 4  & 5  & 6  \\
11 & 12 & 13 & 14 & 15 & 16 \\
\CodeAfter
  \OverBrace{1-1}{2-3}{A}
  \OverBrace{1-4}{2-6}{B}
\end{pNiceMatrix}$

\bigskip
Caution : There is no vertical space reserved for those braces and their labels.\footnote{See:
  \url{https://tex.stackexchange.com/questions/685755}} 


\bigskip
\index{color!key of \texttt{\textbackslash OverBrace} and \texttt{\textbackslash
  UnderBrace}}
\index{yshift (key of \texttt{\textbackslash OverBrace} and \texttt{\textbackslash
  UnderBrace})}
\index{left-shorten (key of \texttt{\textbackslash OverBrace} and\newline \texttt{\textbackslash
  UnderBrace})}
\index{right-shorten (key of \texttt{\textbackslash OverBrace} and\newline \texttt{\textbackslash
  UnderBrace})}

In fact, the commands |\OverBrace| and |\UnderBrace| take in an optional
argument (in first position and between square brackets) for a list of
\textsl{key=value} pairs. The available keys are:
\begin{itemize}
\item \Definition{left-shorten} and \Definition{right-shorten} which do not take
in value; when the key |left-shorten| is used, the abscissa of the left
extremity of the brace is computed with the contents of the cells of the
involved sub-array, otherwise, the position of the potential vertical rule is
used (idem for |right-shorten|).

\item \Definition{shorten}, which is the conjunction of the keys |left-shorten|
and |right-shorten|;

\item \Definition{yshift}, which shifts vertically the brace (and its label);

\item \Definition{color}, which sets the color of the brace (and its label).
\end{itemize}

\bigskip
\begin{Code}[width=9cm]
\begin{pNiceMatrix}
1  & 2  & 3  & 4  & 5  & 6  \\
11 & 12 & 13 & 14 & 15 & 16 \\
\CodeAfter
  \OverBrace[\emph{shorten,yshift=3pt}]{1-1}{2-3}{A}
  \OverBrace[\emph{shorten,yshift=3pt}]{1-4}{2-6}{B}
\end{pNiceMatrix}
\end{Code}
$\begin{pNiceMatrix}
1  & 2  & 3  & 4  & 5  & 6  \\
11 & 12 & 13 & 14 & 15 & 16 \\
\CodeAfter
  \OverBrace[shorten,yshift=3pt]{1-1}{2-3}{A}
  \OverBrace[shorten,yshift=3pt]{1-4}{2-6}{B}
\end{pNiceMatrix}$


\subsection{The command \textbackslash TikzEveryCell in the \textbackslash
  CodeAfter}


\index{SubMatrix@\texttt{\textbackslash TikzEveryCell} (command of 
\texttt{\textbackslash CodeAfter}\newline and 
\texttt{\textbackslash CodeBefore})|textbf}
\label{TikzEveryCell}
\index{empty (key of \texttt{\textbackslash TikzEveryCell})}
\index{non empty (key of \texttt{\textbackslash TikzEveryCell})}

The command |\TikzEveryCell|
executes with TikZ the rectangular path corresponding to each cell of the tabular
with parameters of TikZ the argument of |\TikzEveryCell|. That argument must be
a list of \textsl{key=value} pairs which may be applied to a TikZ path. In fact,
the command applies to each of the tabular, except those in the exterior rows
and columns (cf.~p.~\pageref{exterior}) and those in the empty corners (when the
key |corners| is used: cf.~p.~\pageref{corners}). It applies in fact to each
block (excepted those with the key |transparent|) and does not apply to the
individual cells located within these blocks. 

\medskip
In fact, in the list of keys provided as argument of |\TikzEveryCell|, it's
possible to put a key |offset|. That key is not provided by TikZ but by
\pkg{nicematrix}. It will narrow the rectangular frame corresponding to the
block by a margin (horizontally and vertically) equal to the value (of that key
|offset|). That new frame, a bit narrower, will be executed by TikZ with options
which are the other keys in the argument of |\TikzEveryCell|.

\medskip
\begingroup
\bigskip
\begin{Code}[width=9cm]
\renewcommand{\arraystretch}{1.3}
\begin{NiceTabular}{ccc}[corners]
  & \Block{1-2}{columns} \\
  \Block{2-1}{rows}
  & cell 1 1 & cell 1 2 \\
  & cell 2 1 & cell 2 2
\CodeAfter
  \emph{\TikzEveryCell{offset=1pt,draw}}
\end{NiceTabular}
\end{Code}
\renewcommand{\arraystretch}{1.3}
\begin{NiceTabular}{ccc}[corners]
  & \Block{1-2}{columns} \\
  \Block{2-1}{rows}
  & cell 1 1 & cell 1 2 \\
  & cell 2 1 & cell 2 2
\CodeAfter
  \TikzEveryCell{offset=1pt,draw}
\end{NiceTabular}
\endgroup

\bigskip
The command |\TikzEveryCell| has two keys:
\begin{itemize}
\item with the key \Definition{empty}, the command only acts on the empty cells;

\item with key \Definition{non-empty}, the command only acts on the non-empty cells.
\end{itemize}

\medskip
The commmand |\TikzEveryCell| is, in fact, also available in the |\CodeBefore|.


\index{CodeAfter@\texttt{\textbackslash CodeAfter}|)}

\section{Captions and notes in the tabulars}

\label{s:notes}

\subsection{Caption of a tabular}

\label{s:caption}

\index{caption (key of \texttt{\{NiceTabular\}})}
\index{short-caption}
\index{label (key of \texttt{\{NiceTabular\}})}
\index{caption-above}
\index{caption@\textbf{Captions of the tabulars}}

\smallskip
The environment |{NiceTabular}| provides the keys |caption|, |short-caption|
and |label| which may be used when the tabular is inserted in a floating
environment (typically the environment |{table}|).

\smallskip
With the key |caption|, the caption, when it is long, is wrapped at the width of
the tabular (except the potential exterior columns specified by |first-col|
and |last-col|: cf.~\ref{exterior}, p.~\pageref{exterior}), without the use of
the package \pkg{threeparttable} or the package \pkg{floatrow}.

\smallskip
By default, the caption is composed below the tabular. With the key
|caption-above|, available in |\NiceMatrixOptions|, the caption will be
composed above the tabular.

\smallskip
The key |short-caption| corresponds to the optional argument of the clasical
command |\caption| and the key |label| corresponds, of course, to the command
|\label|. 

\smallskip
See table \ref{t:tabularnote}, p.~\pageref{t:tabularnote}, for an example of
use the keys |caption| and |label|.

\smallskip
These functionnalities are compatible with the extension \pkg{caption}.

\subsection{The footnotes}

\index{footnote@\pkg{footnote} (package)}
\index{footnote (key)}
\index{footnotehyper@\pkg{footnotehyper} (package)}
\index{footnotehyper (key)}

\smallskip
The package \pkg{nicematrix} allows, by using \pkg{footnote} or
\pkg{footnotehyper}, the extraction of the notes inserted by |\footnote| in the
environments of \pkg{nicematrix} and their composition in the foot of the page
with the other notes of the document.

\smallskip
If \pkg{nicematrix} is loaded with the option |footnote| (with
|\usepackage[footnote]{nicematrix}| or with |\PassOptionsToPackage|), the
package \pkg{footnote} is loaded (if it is not yet loaded) and it is used to
extract the footnotes.

\smallskip
If \pkg{nicematrix} is loaded with the option |footnotehyper|, the package
\pkg{footnotehyper} is loaded (if it is not yet loaded) ant it is used to
extract footnotes.

\smallskip
Caution: The packages \pkg{footnote} and \pkg{footnotehyper} are incompatible.
The package \pkg{footnotehyper} is the successor of the package \pkg{footnote}
and should be used preferently. The package \pkg{footnote} has some drawbacks,
in particular: it must be loaded after the package \pkg{xcolor} and it is not
perfectly compatible with \pkg{hyperref}.


\subsection{The notes of tabular}

\index{nota@\textbf{Notes in the tabulars}|(}
\index{tabularnote@\texttt{\textbackslash tabularnote}}


The package \pkg{nicematrix} also provides a command |\tabularnote| which gives
the ability to specify notes that will be composed at the end of the array with
a width of line equal to the width of the array (except the potential exterior
columns specified by |first-col| and |last-col|: cf.~\ref{exterior},
p.~\pageref{exterior}). With no surprise, that command is available only in the
environments |{NiceTabular}|, |{NiceTabular*}| and |{NiceTabularX}|.

In fact, this command is available only if the extension \pkg{enumitem}
\index{enumitem@\pkg{enumitem} (package required to use\newline \texttt{\textbackslash tabularnote})} has
been loaded (before or after \pkg{nicematrix}). Indeed, the notes are composed
at the end of the array with a type of list provided by the package
\pkg{enumitem}. 



\begin{Code}
\begin{NiceTabular}{@{}llr@{}}
\toprule \RowStyle{\bfseries}
Last name & First name & Birth day \\
\midrule
Achard\emph{\tabularnote{Achard is an old family of the Poitou.}}
& Jacques & June 5, 2005 \\
Lefebvre\emph{\tabularnote{The name Lefebvre is an alteration of the name Lefebure.}} 
& Mathilde & January 23, 1975 \\
Vanesse & Stephany & October 30, 1994 \\
Dupont & Chantal & January 15, 1998 \\
\bottomrule
\end{NiceTabular}
\end{Code}


\begin{center}
\begin{NiceTabular}{@{}llr@{}}
\toprule \RowStyle{\bfseries}
Last name & First name & Birth day \\
\midrule
Achard\tabularnote{Achard is an old family of the Poitou.} 
& Jacques & June 5, 2005 \\
Lefebvre\tabularnote{The name Lefebvre is an alteration of the name Lefebure.} 
& Mathilde & January 23, 1975 \\
Vanesse & Stephany & October 30, 1994 \\
Dupont & Chantal & January 15, 1998 \\
\bottomrule
\end{NiceTabular}
\end{center}


\bigskip
\begin{itemize}
\item If you have several successive commands |\tabularnote{...}| \emph{with no
space at all between them}, the labels of the corresponding notes are composed
together, separated by commas (this is similar to the option |multiple| of
\pkg{footmisc} for the footnotes).

\item If a command |\tabularnote{...}| is exactly at the end of a cell (with
no space at all after), the label of the note is composed in an overlapping
position (towards the right). This structure may provide a better alignment of
the cells of a given column. However, since the version 6.20a, that behaviour is
in force only when the horizontal alignment mode of the corresponding column is
|c| or |r|.

\item If the key |notes/para| is used, the notes are composed at the end of
the array in a single paragraph (as with the key |para| of \pkg{threeparttable}).

\item \index{tabularnote (key of \texttt{\{NiceTabular\}})}
There is a key |tabularnote| which provides a way to insert some text in
the zone of the notes before the numbered tabular notes.

\index{tabularnote@\texttt{\{TabularNote\}}}
An alternative syntax is available with the environment |{TabularNote}|. That
environment should be used at the end of the environment |{NiceTabular}| (but
\emph{before} a potential instruction |\CodeAfter|).

\item If the package \pkg{booktabs} has been loaded (before or after
\pkg{nicematrix}), the key |notes/bottomrule| draws a |\bottomrule| of
\pkg{booktabs} \emph{after} the notes. 

\item The command |\tabularnote| may be used \emph{before}
the environment of \pkg{nicematrix}. Thus, it's possible to use it on the
title inserted by |\caption| in an environment |{table}| of LaTeX (or in a
command |\captionof| of the package \pkg{caption}). It's also possible, as
expected, to use the command |\tabularnote| in the caption provided by the
\emph{key} |caption| of the environment |{NiceTabaular}|.

If several commands |\tabularnote| are used in a tabular with the same
argument, only one note is inserted at the end of the tabular (but all the
labels are composed, of course). It's possible to control that feature with
the key |notes/detect-duplicates|.\footnote{For technical reasons, the final
user is not allowed to put several commands |\tabularnote| with exactly the
same argument in the caption of the tabular.}

\item It's possible to create a reference to a tabular note created by |\tabularnote|
(with the usual command |\label| used after the |\tabularnote|).

\item The command |\tabularnote| has an optional argument (between square
brackets) to change the symbol of the reference of the note.

\emph{Example}: |\tabularnote[$\star$]{A footnote...}|
\end{itemize}
%
For an illustration of some of those remarks, see table
\ref{t:tabularnote}, p.~\pageref{t:tabularnote}. This table has been composed
with the following code (the package \pkg{caption} has been loaded in this document).

\begin{center}
\small
\begin{Code}
\begin{table}
\centering
\NiceMatrixOptions{caption-above}
\begin{NiceTabular}{@{}llc@{}
  [
    caption = A tabular whose caption has been specified by the key
      \texttt{caption}\emph{\tabularnote[$\star$]{It's possible to put a tabular note in the caption.}} ,
    label = t:tabularnote ,
    tabularnote = Some text before the notes. ,
    notes/bottomrule
  ]
\toprule
Last name & First name & Length of life \\
\midrule
Churchill & Wiston &  91\\
Nightingale\emph{\tabularnote{Considered as the first nurse of history}}%
\emph{\tabularnote{Nicknamed ``the Lady with the Lamp''.}}
& Florence\emph{\tabularnote{This note is shared by two references.}} & 90 \\
Schoelcher & Victor & 89\emph{\tabularnote{The label of the note is overlapping.}}\\
Touchet & Marie\emph{\tabularnote{This note is shared by two references.}} & 89 \\
Wallis & John & 87 \\
\bottomrule
\end{NiceTabular}
\end{table}
\end{Code}%
\end{center}


\begin{table}[hbt]
\centering
\NiceMatrixOptions{caption-above}
\begin{NiceTabular}{@{}llc@{}}[
    caption = A tabular whose caption has been specified by the key
    \texttt{caption}\tabularnote[$\star$]{It's possible to put a tabular note in the caption} ,
    label = t:tabularnote ,
    tabularnote = Some text before the notes. ,
    notes/bottomrule
  ]
\toprule
Last name & First name & Length of life \\
\midrule
Churchill & Wiston &  91\\
Nightingale\tabularnote{Considered as the first nurse of
history.}\tabularnote{Nicknamed ``the Lady with the Lamp''.} 
& Florence\tabularnote{This note is shared by two references.} & 90 \\
Schoelcher & Victor & 89\tabularnote{The label of the note is overlapping.}\\
Touchet & Marie\tabularnote{This note is shared by two references.} & 89 \\
Wallis & John & 87 \\
\bottomrule
\end{NiceTabular}
\end{table}


\subsection{Customisation of the tabular notes}

\index{para (subkey of ``notes'')}
\index{bottomrule (subkey of ``notes'')}
\index{style (subkey of ``notes'')}
\index{label-in-tabular (subkey of ``notes'')}
\index{label-in-list (subkey of ``notes'')}
\index{enumitem-keys (subkey of ``notes'')}
\index{enumitem-keys-para (subkey of ``notes'')}
\index{code-before!subkey of ``notes''}
\index{detect-duplicates (subkey of ``notes'')}


The tabular notes can be customized with a set of keys available in
|\NiceMatrixOptions|. The name of these keys is prefixed by |notes|.
\begin{itemize}
\item |notes/para| 
\item |notes/bottomrule| 
\item |notes/style| 
\item |notes/label-in-tabular| 
\item |notes/label-in-list| 
\item |notes/enumitem-keys| 
\item |notes/enumitem-keys-para| 
\item |notes/code-before|
\end{itemize}
For sake of commodity, it is also possible to set these keys in
|\NiceMatrixOptions| via a key |notes| which takes in as value a list of 
pairs \textsl{key=value} where the name of the keys need no longer be
prefixed by |notes|:
\begin{center}
\begin{BVerbatim}[formatcom = \small \color{gray}]
\NiceMatrixOptions
  {
    notes = 
     {
       bottomrule ,
       style = ... ,
       label-in-tabular = ... ,
       enumitem-keys = 
        {
          labelsep = ... ,
          align = ... ,
          ...
        }
     }
  }
\end{BVerbatim}
\end{center}


\bigskip
We detail these keys.

\begin{itemize}[itemsep=\medskipamount]
\item The key |notes/para| requires the composition of the notes (at the end of
the tabular) in a single paragraph.

Initial value: |false|

That key is also available within a given environment.

\item The key |notes/bottomrule| adds a |\bottomrule| of \pkg{booktabs}
\emph{after} the notes. Of course, that rule is drawn only if there is really
notes in the tabular. The package \pkg{booktabs} must have been loaded (before
or after the package \pkg{nicematrix}). If it is not, an error is raised.

Initial value: |false|

That key is also available within a given environment.

\item The key |notes/style| is a command whose argument is specified by |#1|
and which gives the style of numerotation of the notes. That style will be
used by |\ref| when referencing a tabular note marked with a command |\label|.
The labels formatted by that style are used, separated by commas, when the user
puts several consecutive commands |\tabularnote|. The marker |#1| is meant to
be the name of a LaTeX counter.

Initial value: |\textit{\alph{#1}}|

Another possible value should be a mere |\arabic{#1}|

\item The key |notes/label-in-tabular| is a command whose argument is
specified by |#1| which is used when formatting the label of a note in the
tabular. Internally, this number of note has already been formatted by
|notes/style| before sent to that command.

Initial value: |\textsuperscript{#1}|

In French, it's a tradition of putting a small space before the label of note.
That tuning could be acheived by the following code:
%
\begin{Verbatim}
\NiceMatrixOptions{notes/label-in-tabular = \,\textsuperscript{~#1}}
\end{Verbatim}


\item The key |notes/label-in-list| is a command whose argument is specified
by |#1| which is used when formatting the label in the list of notes at the
end of the tabular. Internally, this number of note has already been formatted by
|notes/style| before sent to that command.

Initial value: |\textsuperscript{#1}|

In French, the labels of notes are not composed in upper position when
composing the notes. Such behaviour could be acheived by:
\begin{Verbatim}
\NiceMatrixOptions{notes/label-in-list = ~#1.\nobreak\hspace{0.25em}}
\end{Verbatim}
The command |\nobreak| is for the event that the option |para| is used.


\item The notes are composed at the end of the tabular by using internally a
style of list of \pkg{enumitem}. This style of list is defined as follows (with, of
course, keys of \pkg{enumitem}):

|noitemsep , leftmargin = * , align = left , labelsep = 0pt|

The specification |align = left| in that style requires a
composition of the label leftwards in the box affected to that label.
With that tuning, the notes are composed flush left, which is pleasant when
composing tabulars in the spirit of \pkg{booktabs} (see for example the 
table \ref{t:tabularnote}, p.~\pageref{t:tabularnote}).

\medskip
The key |notes/enumitem-keys| specifies a list of pairs 
\textsl{key=value} (following the specifications of \pkg{enumitem}) to
customize that style of list (it uses internally the command |\setlist*| of 
\pkg{enumitem}). 


\item The key |notes/enumitem-keys-para| is similar to the previous one but
corresponds to the type of list used when the option |para| is in force. Of
course, when the option |para| is used, a list of type |inline| (as called by
\pkg{enumitem}) is used and the pairs \textsl{key=value} should correspond to
such a list of type |inline|. 

Initially, the style of list is defined by:\quad 
|afterlabel = \nobreak, itemjoin = \quad|


\item The key |notes/code-before| is a token list inserted by \pkg{nicematrix}
just before the composition of the notes at the end of the tabular.

Initial value: \textsl{empty}

For example, if one wishes to compose all the notes in gray and |\footnotesize|,
he should use that key:
\begin{Verbatim}
\NiceMatrixOptions{notes/code-before = \footnotesize \color{gray}}
\end{Verbatim}
It's also possible to add |\raggedright| or |\RaggedRight| in that key (|\RaggedRight|
is a command of \pkg{ragged2e}).

\item The key |notes/detect-duplicates| activates the detection of the commands
|\tabularnotes| with the same argument.

Initial value : |true|
\end{itemize}

\index{nota@\textbf{Notes in the tabulars}|)}

\bigskip
For an example of customisation of the tabular notes, see p.~\pageref{ex:notes}.


\subsection{Use of \{NiceTabular\} with threeparttable}

\index{threeparttable@\pkg{threeparttable} (package)}

If you wish to use an environment |{NiceTabular}|, |{NiceTabular*}| or
|{NiceTabularX}| in an environment |{threeparttable}| of the eponymous package,
you have to patch |{threeparttable}| with the following code.

\begin{Code}
\makeatletter
\AddToHook{env/threeparttable/begin}
  {\TPT@hookin{NiceTabular}\TPT@hookin{NiceTabular*}\TPT@hookin{NiceTabularX}}
\makeatother
\end{Code}

Nevertheless, the use of \pkg{threeparttable} in conjonction with
\pkg{nicematrix} seems rather point-less because of the functionalities
provided by \pkg{nicematrix} (see the key |caption| in the section
\ref{s:caption}, p.~\pageref{s:caption}).


\section{Other features}

\subsection{The key rounded-corners}

\label{tabular-rounded-corners}
\index{rounded-corners!key of \texttt{\{NiceTabular\}}}
\index{Corners (rounded ---)!for a tabular}

The key |rounded-corners| that we will describe now has no direct link with
the key |corners| (which is used to specify ``empty corners'') described in
the part~\ref{corners}, p.~\pageref{corners}.

\smallskip
The key |rounded-corners| specifies that the tabular should have rounded corners
with a radius equal to the value of that key (the default value is
4~pt\footnote{This value is the initial value of the \emph{rounded corners} of
  Tikz.}). More precisely, that key has two effects that we describe now.
\begin{itemize}
\item All the commands for coloring the cells, columns and rows (in the
|\CodeBefore| but also directly in the array when the key |color-inside| is
used) will respect those rounded corners.

\item When the key |hvlines| is used, the exterior rules will be drawn with
rounded corners.\footnote{Of course, when used in an environment with delimiters
(|{pNiceMatrix}|, |{bNiceArray}|, etc.), the key |hvlines| does not draw the
exterior rules.}
\end{itemize}


That key is available in all the environments and commands (e.g.
|\pAutoNiceMatrix|) of \pkg{nicematrix} and also in the command
|\NiceMatrixOptions|.

\bigskip
\begin{Code}[width=9cm]
\begin{NiceTabular}
  [hvlines,\emph{rounded-corners}]
  {ccc}
\CodeBefore
  \rowcolor{red!15}{1}
\Body
Last name & First name & Profession \\
Arvy & Jacques & Physicist \\
Jalon & Amandine & Physicist
\end{NiceTabular}
\end{Code}
\begin{NiceTabular}{ccc}[hvlines,rounded-corners]
\CodeBefore
  \rowcolor{red!15}{1}
\Body
Last name & First name & Profession \\
Arvy & Jacques & Physicist \\
Jalon & Amandine & Physicist
\end{NiceTabular}


\subsection{Command \textbackslash ShowCellNames}

\index{ShowCellNames@\texttt{\textbackslash ShowCellNames} (command of 
\texttt{\textbackslash CodeAfter}\newline and 
\texttt{\textbackslash CodeBefore})}


The command |\ShowCellNames|, which may be used in the |\CodeBefore| and in
the |\CodeAfter| displays the name (with the form $i$-$j$) of each cell. When
used in the |\CodeAfter|, that command applies a semi-transparent white
rectangle to fade the array (caution: some \textsc{pdf} readers don't support
transparency). 

\medskip
\begin{Code}[width=10.6cm]
\begin{NiceTabular}{ccc}[hvlines,cell-space-limits=3pt]
  \Block{2-2}{} &           & test \\
                &           & blabla \\
                & some text & nothing 
\emph{\CodeAfter \ShowCellNames}
\end{NiceTabular}
\end{Code}
\begin{NiceTabular}{ccc}[hvlines,cell-space-limits=3pt]
  \Block{2-2}{} &           & test \\
                &           & blabla \\
                & some text & nothing 
\CodeAfter \ShowCellNames
\end{NiceTabular}


\subsection{Use of the column type S of siunitx}

\index{S (the columns S of \pkg{siunitx})}
\index{siunitx@\pkg{siunitx} (package)}

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{Code}[width = 11cm]
$\begin{pNiceArray}{\emph{S}cW{c}{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{Code}
$\begin{pNiceArray}{ScW{c}{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}$

\medskip
On the other hand, the |d| columns of the package \pkg{dcolumn} are not
supported by \pkg{nicematrix}.


\subsection{Default column type in \{NiceMatrix\}}

\label{columns-width}
\index{columns-type (key of \texttt{\{NiceMatrix\}}, etc.)}

The environments without preamble (|{NiceMatrix}|, |{pNiceMatrix}|,
|{bNiceMatrix}|, etc.) and the commande |\pAutoNiceMatrix| (and its variants)
provide an option |columns-type| to specify the type of column which will be
used (the initial value is, of course, |c|).

The keys |l| and |r| are shortcuts for |columns-type=l| and |columns-type=r|.


\medskip
\begin{Code}[width=10cm]
$\begin{bNiceMatrix}\emph{[r]}
\cos x & - \sin x \\
\sin x & \cos x 
\end{bNiceMatrix}$
\end{Code}
$\begin{bNiceMatrix}[r]
\cos x & - \sin x \\
\sin x & \cos x 
\end{bNiceMatrix}$

\medskip
The key |columns-type| is available in |\NiceMatrixOptions| but with the
prefix |matrix|, which means that its name is, within |\NiceMatrixOptions| :
|matrix/columns-type|. 

\subsection{The command \textbackslash rotate}

\label{rotate}
\index{rotate@\texttt{\textbackslash rotate}}

The package \pkg{nicematrix} provides a command |\rotate|. When used in the
beginning of a cell, this command composes the contents of the cell after a
rotation of 90° in the direct sens.

In the following command, we use that command in the
|code-for-first-row|.\footnote{It can also be used in |\RowStyle|
(cf.~p.~\pageref{RowStyle}.)} 

\bigskip

\begin{Code}[width=12cm]
\NiceMatrixOptions%
 {code-for-first-row = \scriptstyle \emph{\rotate} \text{image of },
  code-for-last-col = \scriptstyle }
$A = \begin{pNiceMatrix}[first-row,last-col=4]
e_1 & e_2 & e_3       \\
1   & 2   & 3   & e_1 \\
4   & 5   & 6   & e_2 \\
7   & 8   & 9   & e_3 
\end{pNiceMatrix}$
\end{Code}
\begin{varwidth}{10cm}
\NiceMatrixOptions%
 {code-for-first-row = \scriptstyle\rotate \text{image of },
  code-for-last-col = \scriptstyle }
$ A = \begin{pNiceMatrix}[first-row,last-col=4]
e_1 & e_2 & e_3 \\
1   & 2   & 3  & e_1 \\
4   & 5   & 6  & e_2 \\
7   & 8   & 9  & e_3 
\end{pNiceMatrix}$
\end{varwidth}

\bigskip
If the command |\rotate| is used in the ``last row'' (exterior to the matrix),
the corresponding elements are aligned upwards as shown below.

\bigskip
\index{first-row|textit}
\index{last-row|textit}
\index{code-for-first-row|textit}
\index{code-for-last-row|textit}
\index{last-col|textit}
\index{code-for-last-col|textit}

\begin{Code}[width=12cm]
\NiceMatrixOptions%
 {code-for-last-row = \scriptstyle \emph{\rotate} ,
  code-for-last-col = \scriptstyle }
$A = \begin{pNiceMatrix}[last-row=4,last-col=4]
1   & 2   & 3   & e_1 \\
4   & 5   & 6   & e_2 \\
7   & 8   & 9   & e_3 \\
\text{image of } e_1 & e_2 & e_3 
\end{pNiceMatrix}$
\end{Code}
\begin{varwidth}{10cm}
\NiceMatrixOptions%
 {code-for-last-row = \scriptstyle\rotate ,
  code-for-last-col = \scriptstyle }%
$A = \begin{pNiceMatrix}[last-row=4,last-col=4]
1   & 2   & 3  & e_1 \\
4   & 5   & 6  & e_2 \\
7   & 8   & 9  & e_3 \\
\text{image of } e_1 & e_2 & e_3 
\end{pNiceMatrix}$
\end{varwidth}

\bigskip
The command |\rotate| has a key |c|: |\rotate[c]| (spaces are deleted after
|\rotate[c]|). When that key is used, the content is composed in a |\vcenter|
and, therefore, in most cases, we will have a vertical alignment.

\bigskip
Caution: the command |\rotate| is designed to be used in a |\Block| or in
columns of type |l|, |r|, |c|, |w| ou |W|; if it is used in other column types
(such as |p{...}|), the result will maybe differ from what is expected. 

\subsection{The option small}

\label{small}
\index{small (key for an environment)}
\index{smallmatrix@\texttt{\{smallmatrix\}} (environment of \pkg{amsmath})}


With the option |small|, the environments of the package \pkg{nicematrix}
are composed in a way similar to the environment |{smallmatrix}| of the
package \pkg{amsmath} (and the environments |{psmallmatrix}|,
|{bsmallmatrix}|, etc. of the package \pkg{mathtools}).

\bigskip
\begin{Code}
$\begin{bNiceArray}{cccc|c}[\emph{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{Code}
%
\[\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
package \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 |\scriptstyle|; 
\item |\arraystretch| is set to $0.47$; 
\item |\arraycolsep| is set to $1.45$~pt; 
\item the characteristics of the dotted lines are also modified.
\end{itemize}

\medskip
When the key |small| is in force, some functionalities of \pkg{nicematrix} are
no longer available: for example, it's no longer possible to put vertical
delimiters directly in the preamble of an environment with preamble (cf. 
section \ref{delimiters-in-preamble}, p.~\pageref{delimiters-in-preamble}).


\subsection{The counters iRow and jCol}

\label{iRow}
\index{iRow (LaTeX counter)}
\index{jCol (LaTeX counter)}

In the cells of the array, it's possible to use the LaTeX counters |iRow| and
|jCol|\footnote{There counters are actual LaTeX counters: the underlying TeX
  counters are |\c@iRow| and |\c@jCol|} which represent the number of the
current row and the number of the current column. We recall that the exterior
``first row'' (if it exists) has the number~$0$ and that the exterior ``first
column'' (if it exists) has also the number~$0$. Of course, the user must not
change the value of these counters |iRow| and |jCol| which are used internally
by \pkg{nicematrix}.

In the |\CodeBefore| (cf. p. \pageref{code-before}) and in the |\CodeAfter| (cf.
p. \pageref{code-after}), |iRow| represents the total number of rows (except the
potential exterior rows: cf. p.~\pageref{exterior}) and |jCol| represents the
total number of columns (except the potential exterior columns).

\medskip
\begin{Code}[width=10.6cm]
$\begin{pNiceMatrix}% don’t forget the %
    [first-row,
     first-col,
     code-for-first-row = \mathbf{\emph{\alph{jCol}}} ,
     code-for-first-col = \mathbf{\emph{\arabic{iRow}}} ]
&   &    &    &   \\
& 1 & 2  & 3  & 4 \\
& 5 & 6  & 7  & 8 \\
& 9 & 10 & 11 & 12
\end{pNiceMatrix}$
\end{Code}
$\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}$

\medskip
If LaTeX counters called |iRow| and |jCol| are defined in the document by
packages other than \pkg{nicematrix} (or by the final user), they are shadowed
in the environments of \pkg{nicematrix}.

\bigskip
\indexcommand{AutoNiceMatrix}
\indexcommand{pAutoNiceMatrix}
\indexcommand{bAutoNiceMatrix}
\indexcommand{vAutoNiceMatrix}
\indexcommand{VAutoNiceMatrix}
\indexcommand{BAutoNiceMatrix}
The package \pkg{nicematrix} also provides commands in order to compose
automatically matrices from a general pattern. These commands are
|\AutoNiceMatrix|, |\pAutoNiceMatrix|, |\bAutoNiceMatrix|, |\vAutoNiceMatrix|,
|\VAutoNiceMatrix| and |\BAutoNiceMatrix|.

These commands take in two mandatory arguments. The first is the format of the
matrix, with the syntax $n$-$p$ where $n$ is the number of rows and $p$ the
number of columns. The second argument is the pattern (it's a list of tokens
which are inserted in each cell of the constructed matrix).

\medskip
\begin{Code}
$C = \emph{\pAutoNiceMatrix}{3-3}{C_{\arabic{iRow},\arabic{jCol}}}$
\end{Code}


\[C = \pAutoNiceMatrix{3-3}{C_{\arabic{iRow},\arabic{jCol}}}\]


\subsection{The key light-syntax}

\label{light-syntax}
\index{light-syntax}

The option |light-syntax| (inpired by the package \pkg{spalign}) allows the
user to compose the arrays with a lighter syntax, which gives a better
legibility of the TeX source.

When this option is used, one should use the semicolon for the end of a row
and spaces or tabulations to separate the columns. However, as usual in the
TeX world, the spaces after a control sequence are discarded and the elements
between curly braces are considered as a whole.


\medskip
\begin{Code}[width=10cm]
$\begin{bNiceMatrix}[\emph{light-syntax},first-row,first-col]
{} a             b                 ;
a  2\cos a       {\cos a + \cos b} ;
b \cos a+\cos b  { 2 \cos b }
\end{bNiceMatrix}$
\end{Code}
$\begin{bNiceMatrix}[light-syntax,first-row,first-col]
{} a             b                 ;
a  2\cos a       {\cos a + \cos b} ;
b \cos a+\cos b  { 2 \cos b }
\end{bNiceMatrix}$

\medskip
\index{end-of-row (to be used with light-syntax)}
It's possible to change the character used to mark the end of rows with the
option |end-of-row|. As said before, the initial value is a semicolon.

\medskip
When the option |light-syntax| is used, it is not possible to put verbatim
material (for example with the command |\verb|) in the cells of the
array.\footnote{The reason is that, when the option |light-syntax| is used,
the whole content of the environment is loaded as a TeX argument to be
analyzed. The environment doesn't behave in that case as a standard
environment of LaTeX which only put TeX commands before and after the content.}

\medskip
\index{light-syntax-expanded}

The key |light-syntax-expanded| has the same behaviour as the key |light-syntax|
but the body of the environment is expanded (in the TeX sens\footnote{More precisely, it's a
expansion of type |e| of L3.}) before being splitted in lines (but
after the extraction of a potential |\CodeAfter|).


\subsection{Color of the delimiters}

\index{delimiters!---/color for an environment}
\index{color!for the delimiters of the matrices}
\index{Colour!of the delimiters of the matrices}


For the environments with delimiters (|{pNiceArray}|, |{pNiceMatrix}|, etc.),
it's possible to change the color of the delimiters with the key
|delimiters/color|.

\medskip
\begin{Code}[width=12cm]
$\begin{bNiceMatrix}[delimiters/color=red]
1 & 2 \\
3 & 4 
\end{bNiceMatrix}$
\end{Code}
$\begin{bNiceMatrix}[delimiters/color=red]
1 & 2 \\
3 & 4 
\end{bNiceMatrix}$

\medskip
This color also applies to the delimiters drawn by the command |\SubMatrix|
(cf.~p.~\pageref{sub-matrix}) and for the delimiters directly specified in the
preamble of the environments with preamble
(cf.~p.~\pageref{delimiters-in-preamble}). 

\subsection{The environment \{NiceArrayWithDelims\}}

\label{NiceArrayWithDelims}
\index{NiceArrayWithDelims@\texttt{\{NiceArrayWithDelims\}}}

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 or
asymetrical delimiters.

\medskip
\begin{Code}[width=11cm]
$\begin{\emph{NiceArrayWithDelims}}
   {\downarrow}{\uparrow}{ccc}[margin]
1 & 2 & 3 \\
4 & 5 & 6 \\
7 & 8 & 9 
\end{\emph{NiceArrayWithDelims}}$
\end{Code}
$\begin{NiceArrayWithDelims}
   {\downarrow}{\uparrow}{ccc}[margin]
1 & 2 & 3 \\
4 & 5 & 6 \\
7 & 8 & 9 
\end{NiceArrayWithDelims}$

\subsection{The command \textbackslash OnlyMainNiceMatrix}

\indexcommand{OnlyMainNiceMatrix}

The command |\OnlyMainNiceMatrix| executes its argument only when it is in the
main part of the array, that is to say when it is not in one of the exterior
rows or one of the exterior columns. If it is used outside an environment of
\pkg{nicematrix}, that command is no-op.

For an example of utilisation, see \url{tex.stackexchange.com/questions/488566}

\section{Use of TikZ with nicematrix}

\label{name}
\label{PGF-nodes}
\index{tikza@TikZ (utilisation with \pkg{nicematrix})}
\index{node@\textbf{Nodes of PGF/TikZ}|(}

\subsection{The nodes corresponding to the contents of the cells}

\index{no-cell-nodes}

The package \pkg{nicematrix} creates a PGF/TikZ node\footnote{We recall that TikZ
is a layer over PGF. The extension \pkg{nicematrix} loads PGF but does not
load TikZ. We speak of PGF/TikZ nodes to emphase the fact that the PGF nodes
created by \pkg{nicematrix} may be used with PGF but also with TikZ. The final
user will probably prefer to use TikZ rather than PGF.} for each (non-empty) cell
of the considered array. These nodes are used to draw the dotted lines between
the cells of the matrix (inter alia).


\smallskip
\textbf{Caution} : By default, no node is created in a empty cell.

\smallskip
However, it's possible to impose the creation of a node with the command
|\NotEmpty|. \footnote{One should note that, with that command, the cell is
considered as non-empty, which has consequencies for the continuous dotted
lines (cf. p.~\pageref{Cdots}) and the computation of the ``corners''
(cf.~p.~\pageref{corners}).}

\medskip
The creation of those nodes needs time and memory. It's possible to desactive
ponctually the creation of those nodes with the key |no-cell-nodes| in order to
speed up the compilations.

\medskip
The nodes of a document must have distinct names. That's why the names of the
nodes created by \pkg{nicematrix} contains the number of the current
environment. Indeed, the environments of \pkg{nicematrix} are numbered by a
internal global counter. 

\smallskip
In the environment with the number $n$, the node of the row $i$ and
column~$j$ has for name |nm-|$n$|-|$i$|-|$j$. 

\smallskip
The command |\NiceMatrixLastEnv| provides the number of the last environment
of \pkg{nicematrix} (for LaTeX, it's a ``fully expandable'' command and not a
counter).

\smallskip
\index{name!key for an environment}
However, it's advisable to use instead the key |name|\footnote{Since the version
  6.20a, the value of that key is \emph{expanded} (in the TeX sens).}. This key
gives a name to the current environment. When the environment has a name, the
nodes are accessible with the name ``\textsl{name}-$i$-$j$'' where \textsl{name}
is the name given to the array and $i$ and $j$ the numbers of row and column.
It's possible to use these nodes with \textsc{pgf} but the final user will
probably prefer to use TikZ (which is a convenient layer upon \textsc{pgf}).
However, one should remind that \pkg{nicematrix} doesn't load TikZ by default.
In the following examples, we assume that TikZ has been loaded.

\bigskip
\begin{Code}[width=11cm]
$\begin{pNiceMatrix}[name=\emph{mymatrix}]
1 & 2 & 3 \\
4 & 5 & 6 \\
7 & 8 & 9 
\end{pNiceMatrix}$
\tikz[remember picture,overlay] 
     \draw \emph{(mymatrix-2-2)} circle (2mm) ; 
\end{Code}
$\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 |\CodeAfter|, the things are easier : one must refer to the nodes with
the form $i$-$j$ (we don't have to indicate the environment which is of
course the current environment).


\medskip
\begin{Code}[width=11cm]
$\begin{pNiceMatrix}
1 & 2 & 3 \\
4 & 5 & 6 \\
7 & 8 & 9 
\CodeAfter
  \tikz \draw \emph{(2-2)} circle (2mm) ; 
\end{pNiceMatrix}$
\end{Code}
$\begin{pNiceMatrix}
1 & 2 & 3 \\
4 & 5 & 6 \\
7 & 8 & 9 
\CodeAfter
  \tikz \draw (2-2) circle (2mm) ; 
\end{pNiceMatrix}$

\medskip
The nodes of the last column (except the potential ``last column'' specified
by |last-col|\footnote{For the exterior columns, cf. part~\ref{exterior},
p.~\pageref{exterior}.}) may also be indicated by $i$-|last|. Similarly, the
nodes of the last row may be indicated by |last|-$j$.

\bigskip
In the following example, we have underlined all the nodes of the matrix.

\[
\NiceMatrixOptions
  { 
    pgf-node-code = 
     { 
       \pgfsetfillcolor{red!15}%
       \pgfusepathqfill
     } 
  }
\begin{pNiceMatrix}
a & a + b & a + b + c \\
a & a     & a + b  \\
a & a     & a
\end{pNiceMatrix}\]


\bigskip
Since those nodes are PGF nodes, one won't be surprised to learn that they are
drawn by using a specific PGF style. That style is called |nicematrix/cell-node|
and its definition in the source file |nicematrix.sty| is as follows:

\begin{Code}
\pgfset 
  { 
    \emph{nicematrix / cell-node} /.style = 
     {
       inner sep = 0 pt ,
       minimum width = 0 pt
     }
  }
\end{Code}

The final user may modify that style by changing the values of the keys |text/rotate|,
|inner xsep|, |inner ysep|, |inner sep|, |outer xsep|, |outer ysep|, |outer sep|,
|minimum width|, |minimum height| and |minimum size|.

\medskip
For an example of utilisation, see part~\ref{triangular}, p.~\pageref{triangular}.


\subsubsection{The key pgf-node-code}

\index{pgf-node-code}

\textbf{For the experienced users}, \pkg{nicematrix} provides the key
|pgf-node-code| which corresponds to some PGF node that will be executed at the
creation, by PGF, of the nodes corresponding to the cells of the array. More
pricisely, the value given to the key |pgf-node-code| will be passed in the
fifth argument of the command |\pgfnode|. That value should contain at least an
instruction such as |\pgfusepath|, |\pgfusepathqstroke|, |\pgfusepathqfill|,
etc.

\subsubsection{The columns V of varwidth}

\label{node-V}
\index{V (the columns V of \pkg{varwidth})}
\index{varwidth@\pkg{varwidth} (package)}

When the extension \pkg{varwidth} is loaded, the columns of the type |V|
defined by \pkg{varwidth} are supported by \pkg{nicematrix}. It may be
interessant to notice that, for a cell of a column of type |V|, the PGF/TikZ
node created by \pkg{nicematrix} for the content of that cell has a width
adjusted to the content of the cell. This is in contrast to the case of the
columns of type |p|, |m| or |b| for which the nodes have always a width equal
to the width of the column. In the following example, the command |\lipsum| is
provided by the eponymous package.

\begin{Verbatim}
\begin{NiceTabular}{V{10cm}}
\bfseries \large 
Titre \\
\lipsum[1][1-4] 
\CodeAfter 
  \tikz \draw [rounded corners] (1-1) -| (last-|2) -- (last-|1) |- (1-1) ; 
\end{NiceTabular}
\end{Verbatim}


\begin{center}
\begin{NiceTabular}{V{10cm}}
\bfseries \large 
Titre \\
\lipsum[1][1-4] 
\CodeAfter 
  \tikz \draw [rounded corners] (1-1) -| (last-|2) -- (last-|1) |- (1-1) ; 
\end{NiceTabular}
\end{center}

We have used the nodes corresponding to the position of the potential rules,
which are described below (cf. p.~\pageref{nodes-i}).


\subsection[The medium nodes and the large nodes]{The ``medium nodes'' and the ``large nodes''}

\index{create-medium-nodes}
\index{create-large-nodes}
\index{create-extra-nodes}

In fact, the package \pkg{nicematrix} can create ``extra nodes'': the ``medium
nodes'' and the ``large nodes''. The first ones 
are created with the option |create-medium-nodes| and the second ones with the
option |create-large-nodes|.\footnote{There is also an option
|create-extra-nodes| which is an alias for the conjonction of
|create-medium-nodes| and |create-large-nodes|.}

\medskip
These nodes are not used by \pkg{nicematrix} by default, and that's why they
are not created by default.

\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-medium-nodes]
\CodeBefore [create-cell-nodes]
   \begin{tikzpicture} 
      [every node/.style = {fill = red!15, inner sep = 0 pt},
       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}
\Body
a & a + b & a + b + c \\
a & a     & a + b  \\
a & a     & a 
\end{pNiceMatrix}\]


\medskip
\index{left-margin}
\index{right-margin}
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-large-nodes]
\CodeBefore [create-cell-nodes]
   \begin{tikzpicture}
      [every node/.style = { inner sep = 0 pt} ,
       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}
\Body
a & a + b & a + b + c \\
a & a     & a + b  \\
a & a     & a 
\end{pNiceMatrix}\]



\medskip
\index{extra-left-margin}
\index{extra-right-margin}
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-large-nodes,left-margin,right-margin]
\CodeBefore [create-cell-nodes]
    \begin{tikzpicture}
       [every node/.style = {inner sep = 0 pt},
        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}
\Body
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-large-nodes,left-margin,right-margin,extra-right-margin=3pt,extra-left-margin=3pt]
\CodeBefore [create-cell-nodes]
    \begin{tikzpicture}
       [every node/.style = {inner sep = 0 pt},
        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}
\Body
a & a + b & a + b + c \\
a & a     & a + b  \\
a & a     & a 
\end{pNiceMatrix}\]



\bigskip
\textbf{Be careful} : These nodes are reconstructed from the contents of the
contents cells of the array. Usually, they do not correspond to the cells
delimited by the rules (if we consider that these rules are drawn).

\bigskip
\begin{minipage}[c]{7.6cm}
Here is an array composed with the following code:

\medskip
\begin{BVerbatim}
\large
\begin{NiceTabular}{wl{2cm}ll}[hvlines]
fraise & amande & abricot \\
prune & pêche & poire  \\[1ex]
noix & noisette & brugnon
\end{NiceTabular}
\end{BVerbatim}
\end{minipage}
\hspace{0.9cm}
\begin{scope}
\large
\begin{NiceTabular}[c]{wl{2cm}ll}[hvlines]
fraise & amande & abricot \\
prune & pêche & poire  \\[1ex]
noix & noisette & brugnon
\end{NiceTabular}
\end{scope}

\vspace{1cm}
\begin{minipage}[c]{7cm}
Here, we have colored all the cells of the array with |\chessboardcolors|.
\end{minipage}
\hspace{1.5cm}
\begin{scope}
\large
\begin{NiceTabular}[c]{wl{2cm}ll}[hvlines,code-before = \chessboardcolors{red!15}{blue!15}]
fraise & amande & abricot \\
prune & pêche & poire  \\[1ex]
noix & noisette & brugnon
\end{NiceTabular}
\end{scope}


\vspace{1cm}
\begin{minipage}[c]{7cm}
Here are the ``large nodes'' of this array (without use of |margin|
nor |extra-margin|).
\end{minipage}
\hspace{1.5cm}
\begin{scope}
\large
\begin{NiceTabular}[c]{w{l}{2cm}ll}[hvlines,create-large-nodes]
\CodeBefore [create-cell-nodes]
    \begin{tikzpicture}
       [every node/.style = {inner sep = 0 pt},
        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}
\Body
fraise & amande & abricot \\
prune & pêche & poire  \\[1ex]
noix & noisette & brugnon
\end{NiceTabular}
\end{scope}


\vspace{1cm}
The nodes we have described are not available by default in the |\CodeBefore|
(described p.~\pageref{code-before}).\par\nobreak

\index{create-cell-nodes (key of \texttt{\textbackslash CodeBefore})}
It's possible to have these nodes available in the |\CodeBefore| by using the
key |create-cell-nodes| of the keyword |\CodeBefore| (in that case, the nodes
are created first before the construction of the array by using informations
written on the |aux| file and created a second time during the contruction of
the array itself).

\bigskip
Here is an example which uses these nodes in the |\CodeAfter|.

\begin{center}
\begin{Code}
\begin{NiceArray}{c@{\;}c@{\;}c@{\;}c@{\;}c}[create-medium-nodes]
    u_1 &-& u_0 &=& r     \\
    u_2 &-& u_1 &=& r     \\
    u_3 &-& u_2 &=& r     \\
    u_4 &-& u_3 &=& r     \\
    \phantom{u_5} & &  \phantom{u_4}    &\smash{\vdots} &       \\
    u_n &-& u_{n-1} &=& r \\[3pt]
    \hline
    u_n &-& u_0 &=& nr \\
\CodeAfter
    \tikz[very thick, red, opacity=0.4, name suffix = -medium]
    \draw (1-1.north west) -- (2-3.south east)
    (2-1.north west) -- (3-3.south east)
    (3-1.north west) -- (4-3.south east)
    (4-1.north west) -- (5-3.south east)
    (5-1.north west) -- (6-3.south east) ;
\end{NiceArray}
\end{Code}
\end{center}

\[\begin{NiceArray}{c@{\;}c@{\;}c@{\;}c@{\;}c}[create-medium-nodes]
    u_1 &-& u_0 &=& r     \\
    u_2 &-& u_1 &=& r     \\
    u_3 &-& u_2 &=& r     \\
    u_4 &-& u_3 &=& r     \\
    \phantom{u_5} & &  \phantom{u_4}    &\smash{\vdots} &       \\
    u_n &-& u_{n-1} &=& r \\[3pt]
    \hline
    u_n &-& u_0 &=& nr \\
    \CodeAfter
    \tikz[very thick, red, opacity=0.4, name suffix = -medium]
    \draw (1-1.north west) -- (2-3.south east)
    (2-1.north west) --(3-3.south east)
    (3-1.north west) -- (4-3.south east)
    (4-1.north west) -- (5-3.south east)
    (5-1.north west) -- (6-3.south east) ;
\end{NiceArray}\]



\subsection{The nodes which indicate the position of the rules}

\label{nodes-i}
The package \pkg{nicematrix} creates a PGF/TikZ node merely called $i$ (with
the classical prefix) at the intersection of the horizontal rule of number~$i$
and the vertical rule of number~$i$ (more specifically the potential position
of those rules because maybe there are not actually drawn). The last node has
also an alias called |last|. 

\smallskip
\colorbox{yellow!50}{\bfseries Modification 6.28}\enskip There are also nodes
called $i$|.1|, $i$|.2|, … , $i$|.9| between the node~$i$ and the node~$i+1$
(before the version 6.28, there was only the node $i$|.5|).

\smallskip
These nodes are available in the |\CodeBefore| and the |\CodeAfter|.

\begin{center}
\begin{NiceTabular}{ccc}[hvlines,rules/width=1pt,rules/color=gray]
     & tulipe   & lys \\
arum &          & violette mauve \\
muguet & dahlia 
\CodeAfter
  \tiny
  \begin{tikzpicture}
  \foreach \i in {1,1.5,2,2.5,3,3.5,4}
    { 
      \fill [red] (\i) circle (0.5mm) ; 
      \node [red,above right] at (\i) {\i} ; 
    } 
  \end{tikzpicture}
\end{NiceTabular}
\end{center}

\bigskip
If we use TikZ (we remind that \pkg{nicematrix} does not load TikZ by default,
by only \textsc{pgf}, which is a sub-layer of TikZ), we can access, in the
|\CodeAfter| but also in the |\CodeBefore|, to the intersection of the
(potential) horizontal rule~$i$ and the (potential) vertical rule~$j$ with the
syntax |(|$i$\verb+-|+$j$|)|. 

\medskip
\begin{Code}
\begin{NiceMatrix}
\CodeBefore
  \emph{\tikz \draw [fill=red!15] (7-|4) |- (8-|5) |- (9-|6) |- cycle ;}
\Body
1 \\
1 & 1 \\
1 & 2 &  1 \\
1 & 3 &  3 &  1 \\
1 & 4 &  6 &  4 &  1 \\
1 & 5 & 10 & 10 &  5 &  1 \\
1 & 6 & 15 & 20 & 15 &  6 &  1 \\
1 & 7 & 21 & 35 & 35 & 21 &  7 & 1 \\
1 & 8 & 28 & 56 & 70 & 56 & 28 & 8 & 1
\end{NiceMatrix}
\end{Code}
% 
\[\begin{NiceMatrix}
\CodeBefore
  \tikz \draw [fill=red!15] (7-|4) |- (8-|5) |- (9-|6) |- cycle ;
\Body
1 \\
1 & 1 \\
1 & 2 &  1 \\
1 & 3 &  3 &  1 \\
1 & 4 &  6 &  4 &  1 \\
1 & 5 & 10 & 10 &  5 &  1 \\
1 & 6 & 15 & 20 & 15 &  6 &  1 \\
1 & 7 & 21 & 35 & 35 & 21 &  7 & 1 \\
1 & 8 & 28 & 56 & 70 & 56 & 28 & 8 & 1
\end{NiceMatrix}\]


\bigskip
The nodes of the form $i$|.5| may be used, for example to cross a row of a
matrix (if TikZ is loaded).

\smallskip
\begin{Code}[width=11cm]
$\begin{pNiceArray}{ccc|c}
2 & 1 & 3 & 0 \\
3 & 3 & 1 & 0 \\
3 & 3 & 1 & 0 
\CodeAfter 
  \tikz \draw [red] (\emph{3.5}-|1) -- (\emph{3.5}-|last) ;
\end{pNiceArray}$
\end{Code}
$\begin{pNiceArray}{ccc|c}
2 & 1 & 3 & 0 \\
3 & 3 & 1 & 0 \\
3 & 3 & 1 & 0 
\CodeAfter 
  \tikz \draw [red] (3.5-|1) -- (3.5-|last) ;
\end{pNiceArray}$

\subsection{The nodes corresponding to the command  \textbackslash SubMatrix}

\label{node-sub-matrix}
\index{SubMatrix@\texttt{\textbackslash SubMatrix} (command of 
\texttt{\textbackslash CodeAfter}\newline and 
\texttt{\textbackslash CodeBefore})}
\index{name!key of \texttt{\textbackslash SubMatrix}}


The command |\SubMatrix| available in the |\CodeAfter| has been described
p.~\pageref{sub-matrix}.  

\smallskip
If a command |\SubMatrix| has been used with the key |name| with an expression
such as |name=|\textsl{\ttfamily MyName} three PGF/TikZ nodes are created
with the names \textsl{\ttfamily MyName}|-left|, \textsl{\ttfamily MyName} and
\textsl{\ttfamily MyName}|-right|.

\smallskip
The nodes \textsl{\ttfamily MyName}|-left| and \textsl{\ttfamily
MyName}|-right| correspond to the delimiters left and right and the node 
\textsl{\ttfamily MyName} correspond to the submatrix itself.

\medskip
In the following example, we have highlighted these nodes (the submatrix itself has
been created with |\SubMatrix\{{2-2}{3-3}\}|). 

\[\begin{pNiceMatrix}
121 & 23 & 345 & 345\\
45 & 346 & 863 & 444\\
3462 & 38458 & 34 & 294 \\
34 & 7 & 78 & 309 \\
\CodeAfter
  \SubMatrix\{{2-2}{3-3}\}[name=A]
  \begin{tikzpicture}
     [every node/.style = {blend mode = multiply,
                           inner sep = 0 pt}]
  \node [fit = (A),fill = red!15] {} ;
  \node [fit = (A-left),fill = blue!15] {} ;
  \node [fit = (A-right),fill = blue!15] {} ;
  \end{tikzpicture}
\end{pNiceMatrix}\]

\index{node@\textbf{Nodes of PGF/TikZ}|)}

\section{API for the developers}

The package \pkg{nicematrix} provides two variables which are internal but
public\footnote{According to the LaTeX3 conventions,
each variable with name beginning with |\g_nicematrix| ou |\l_nicematrix| is
public and each variable with name beginning with |\g__nicematrix| or
|\l__nicematrix| is private.}: 
\begin{itemize}
\item |\g_nicematrix_code_before_tl| ;
\item |\g_nicematrix_code_after_tl|.
\end{itemize}


\medskip
These variables contain the code of what we have called the ``|code-before|''
(usually specified at the beginning of the environment with the syntax using
the keywords |\CodeBefore| and |\Body|) and the ``|code-after|'' (usually
specified at the end of the environment after the keyword |\CodeAfter|). The
developer can use them to add code from a cell of the array (the affectation
must be global, allowing to exit the cell, which is a TeX group).

\medskip
One should remark that the use of |\g_nicematrix_code_before_tl| needs one
compilation more (because the instructions are written on the |aux| file to be
used during the next run).

\bigskip
\emph{Example} : We want to write a command |\crossbox| to draw a cross in the
current cell. This command will take in an optional argument between square
brackets for a list of pairs \textsl{key}-\textsl{value} which will be given to
TikZ before the drawing.

It's possible to program such command |\crossbox| as follows, explicitely
using the public variable |\g_nicematrix_code_before_tl|.

\index{crossbox@\texttt{\textbackslash crossbox} (defined in an example)|textit}


\begin{Code}
\ExplSyntaxOn
\cs_new_protected:Nn \__pantigny_crossbox:nnn
  {
    \tikz \draw [ #3 ] 
          ( #1 -| \int_eval:n { #2 + 1 } ) -- ( \int_eval:n { #1 + 1 } -| #2 ) 
          ( #1 -| #2 ) -- ( \int_eval:n { #1 + 1 } -| \int_eval:n { #2 + 1 } ) ; 
  }

\NewDocumentCommand \crossbox { ! O { } }
  {
    \tl_gput_right:Nx \emph{\g_nicematrix_code_before_tl}
      { 
        \__pantigny_crossbox:nnn 
          { \int_use:c { c@iRow } } 
          { \int_use:c { c@jCol } }
          { \exp_not:n { #1 } }
      }
  }
\ExplSyntaxOff
\end{Code}%



\ExplSyntaxOn
\cs_new_protected:Nn \__pantigny_crossbox:nnn
  {
    \tikz \draw [ #3 ] 
          ( #1 -| \int_eval:n { #2 + 1 } ) -- ( \int_eval:n { #1 + 1 } -| #2 ) 
          ( #1 -| #2 ) -- ( \int_eval:n { #1 + 1 } -| \int_eval:n { #2 + 1 } ) ; 
  }


\NewDocumentCommand \crossbox { ! O { } }
  {
    \tl_gput_right:Nx \g_nicematrix_code_before_tl
      { 
        \__pantigny_crossbox:nnn 
          { \int_use:c { c@iRow } } 
          { \int_use:c { c@jCol } }
          { \exp_not:n { #1 } }
      }
  }
\ExplSyntaxOff

\medskip
We have used the  LaTeX |counters iRow| and |jCol| provided by \pkg{nicematrix} (cf.~p.~\pageref{iRow}).

\bigskip
Here is an example of utilisation:

\medskip
\begin{Code}[width=9cm]
\begin{NiceTabular}{ccc}[hvlines]
\CodeBefore
  \arraycolor{gray!10}
\Body
merlan & requin & cabillaud \\
baleine & \emph{\crossbox[red]} & morue \\
mante & raie & poule 
\end{NiceTabular}
\end{Code}
\begin{NiceTabular}{ccc}[hvlines]
\CodeBefore
  \arraycolor{gray!10}
\Body
merlan & requin & cabillaud \\
baleine & \crossbox[red] & morue \\
mante & raie & poule 
\end{NiceTabular}



\section{Technical remarks}

First remark: the package \pkg{underscore} must be loaded before
\pkg{nicematrix}. If it is loaded after, an error will be raised.

\subsection{Diagonal lines} 

\label{parallelization}
\index{parallelize-diags}
\index{Ddots@\texttt{\textbackslash Ddots}}
\index{Iddots@\texttt{\textbackslash Iddots}}

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 the |\CodeAfter|.} 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.

\begin{scope}
\begin{minipage}{9.5cm}
Example with parallelization (default):
\begin{Code}
$A = \begin{pNiceMatrix}
1      & \Cdots &        & 1      \\
a+b    & \emph{\Ddots} &        & \Vdots \\
\Vdots & \Ddots &        &        \\
a+b    & \Cdots & a+b    & 1
\end{pNiceMatrix}$
\end{Code}
\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{Code}
$A = \begin{pNiceMatrix}
1      & \Cdots &        & 1      \\
a+b    &        &        & \Vdots \\
\Vdots & \emph{\Ddots} & \Ddots &        \\
a+b    & \Cdots & a+b    & 1
\end{pNiceMatrix}$
\end{Code}
\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}

It's possible to specify the instruction |\Ddots| which will be drawn first
(and which will be used to draw the other diagonal dotted lines when the
parallelization is in force) with the key |draw-first|: |\Ddots[draw-first]|.

\subsection[The empty cells]{The ``empty'' cells}

\label{empty-cells}
An instruction like |\Ldots|, |\Cdots|, etc. tries to determine the first
non-empty cell on both sides. When the key |corners| is used
(cf.~p.~\pageref{corners}), \pkg{nicematrix} computes corners consisting of
empty cells. 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~|&|).
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 For the columns of type |p|, |m|, |b|, |V|\footnote{The columns of type
  |V| are provided by \pkg{varwidth}, which must be loaded:
  cf.~p.~\pageref{varwidth}.} and |X|\footnote{See p.~\pageref{X-columns}}, the
cell is empty if (and only if) its content in the TeX code is empty (there is
only spaces between the ampersands |&|).

\medskip
\item For the columns of type |c|, |l|, |r| and |w{...}{...}|, the cell is
empty if (and only if) its TeX output has a width equal to zero.

\medskip
\item \indexcommand{NotEmpty}
A cell containing the command |\NotEmpty| is not empty (and a PGF/TikZ
node is created in that cell).

\medskip
\item A cell with only 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}

\index{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
\pkg{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).}}. 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|\footnote{And not by inserting |@{}| on both sides of the
preamble of the array. As a consequence, the length of the |\hline| is not
modified and may appear too long, in particular when using square brackets.}.
The package \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{Incompatibilities}

\index{Incompatibilities}

The package \pkg{nicematrix} is not compatible with the class \cls{ieeeaccess}
because that class is not compatible with PGF/TikZ. However, there is a simple
workaround by writing:\footnote{See
 \url{https://tex.stackexchange.com/questions/528975/error-loading-tikz-in-ieeeaccess-class}}\par\nobreak 

\begin{Code}
\let\TeXyear\year
\documentclass{IEEEaccess}
\let\year\TeXyear
\end{Code}



\bigskip
% the following requirement is still in force on April 23, 2024
In order to use \pkg{nicematrix} with the class \cls{aastex631}
(of the \emph{American Astronomical Society}), you have to
add the following lines in the preamble of your document :

\begin{Verbatim}
\BeforeBegin{NiceTabular}{\let\begin\BeginEnvironment\let\end\EndEnvironment}
\BeforeBegin{NiceArray}{\let\begin\BeginEnvironment}
\BeforeBegin{NiceMatrix}{\let\begin\BeginEnvironment}
\end{Verbatim}

\bigskip
In order to use \pkg{nicematrix} with the class \cls{sn-jnl} (of
\emph{Springer Nature}), \pkg{pgf} must
be loaded before the |\documentclass| with |\RequirePackage|:

\begin{Verbatim}
\RequirePackage{pgf}
\documentclass{sn-jnl}
\end{Verbatim}

However, it seems that this is no longer mandatory with the recent versions of
\cls{sn-jnl}. 

\bigskip
The package \pkg{nicematrix} is not fully compatible with the packages and classes
of LuaTeX-ja: the detection of the empty corners (cf. p.~\pageref{corners})
may be wrong in some circonstances.

\bigskip
The package \pkg{nicematrix} is not fully compatible with the package
\pkg{arydshln} (because this package redefines many internals of \pkg{array})
and does not support the columns~|V| of \pkg{boldline} (because the letter |V| is
reserved for the columns~|V| of \pkg{varwidth}). By any means, \pkg{nicematrix}
provides, with the key |custom-line| (cf. part~\ref{custom-line},
p.~\pageref{custom-line}), tools to draw dashed rules and rules of different
widths. 

\bigskip
The columns |d| of \pkg{dcolumn} are not supported (but it's possible to use
the colums |S| of \pkg{siunitx}).

\section{Examples}

\subsection[{Utilisation of the key 'tikz' of the command \textbackslash
Block}]{Utilisation of the key ``tikz'' of the command \textbackslash Block} 
\label{tikz-key-examples}

\index{tikzz@tikz!key of \texttt{\textbackslash Block}|textit}

The key |TikZ| of the command |\Block| is available only when TikZ is
loaded.\footnote{By default, \pkg{nicematrix} only loads \textsc{pgf}, which is
a sub-layer of TikZ.}

For the following example, we also need the TikZ library |patterns|.

\begin{Verbatim}
\usetikzlibrary{patterns}
\end{Verbatim}


\begin{Code}
\ttfamily \small
\begin{NiceTabular}{X[m]X[m]X[m]}[hvlines,cell-space-limits=3pt,rounded-corners]
  \Block[\emph{tikz={pattern=grid,pattern color=lightgray}}]{}
    {pattern = grid,\\ pattern color = lightgray}
& \Block[\emph{tikz={pattern = north west lines,pattern color=blue}}]{}
    {pattern = north west lines,\\ pattern color = blue}
& \Block[\emph{tikz={outer color = red!50, inner color=white }}]{2-1}
    {outer color = red!50,\\ inner color = white} \\
  \Block[\emph{tikz={pattern = sixpointed stars, pattern color = blue!15}}]{}
    {pattern = sixpointed stars,\\ pattern color = blue!15}
& \Block[\emph{tikz={left color = blue!50}}]{}
    {left color = blue!50} \\
\end{NiceTabular}
\end{Code}

\begin{center}
\ttfamily \small
\begin{NiceTabular}{X[m]X[m]X[m]}[hvlines,cell-space-limits=3pt,rounded-corners]
  \Block[tikz={pattern=grid,pattern color=lightgray}]{}
    {pattern = grid,\\ pattern color = lightgray}
& \Block[tikz={pattern = north west lines,pattern color=blue}]{}
    {pattern = north west lines,\\ pattern color = blue}
& \Block[tikz={outer color = red!50, inner color=white }]{2-1}
    {outer color = red!50,\\ inner color = white} \\
  \Block[tikz={pattern = sixpointed stars, pattern color = blue!15}]{}
    {pattern = sixpointed stars,\\ pattern color = blue!15}
& \Block[tikz={left color = blue!50}]{}
    {left color = blue!50} \\
\end{NiceTabular}
\end{center}

\bigskip
In the following example, we use the key |tikz| to hatch a row of the tabular.
Remark that you use the key |transparent| of the command |\Block| in order to
have the rules drawn in the block.\footnote{By default, the rules are not
drawn in the blocks created by the command |\Block|: cf.~section~\ref{rules}
p.~\pageref{rules}} 

\index{transparent (key of \texttt{\textbackslash Block})|textit}
\index{columncolor@\texttt{\textbackslash columncolor}!command of
  \texttt{\textbackslash CodeBefore}|textit}


\begin{Code}
\begin{NiceTabular}{ccc}[hvlines]
\CodeBefore
  \columncolor[RGB]{169,208,142}{2}
\Body
one & two & three \\
\Block[\emph{transparent, tikz={pattern = north west lines, pattern color = gray}}]{1-*}{}
four & five & six \\
seven & eight & nine
\end{NiceTabular}
\end{Code}

\begin{center}
\begin{NiceTabular}{ccc}[hvlines]
\CodeBefore
  \columncolor[RGB]{169,208,142}{2}
\Body
one & two & three \\
\Block[transparent, tikz={pattern = north west lines, pattern color = gray}]{1-*}{}
four & five & six \\
seven & eight & nine
\end{NiceTabular}
\end{center}

\subsection{Use with tcolorbox}

\label{tcolorbox}
\index{tcolorbox@\pkg{tcolorbox} (package)|textit}

Here is an example of use of |{NiceTabular}| within a command |\tcbox| of 
\pkg{tcolorbox}. We have used the key |hvlines-except-borders| in order all
the rules except on the borders (which are, of course, added by \pkg{tcolorbox})

\medskip
\begin{Code}
\tcbset
  {
    colframe = blue!50!black ,
    colback = white ,
    fonttitle = \bfseries ,
    nobeforeafter ,
    center title
  }

\tcbox
  [
    left = 0mm ,
    right = 0mm ,
    top = 0mm ,
    bottom = 0mm ,
    boxsep = 0mm ,
    toptitle = 0.5mm ,
    bottomtitle = 0.5mm ,
    title = My table
  ]
  {
    \renewcommand{\arraystretch}{1.2}% <-- the % is mandatory here
    \begin{NiceTabular}{rcl}[\emph{hvlines-except-borders},rules/color=blue!50!black]
    \CodeBefore
      \rowcolor{red!15}{1}
    \Body
      One & Two & Three \\
      Men & Mice & Lions \\
      Upper & Middle & Lower
    \end{NiceTabular}
  }
\end{Code}


\index{hvlines-except-borders|textit}
\index{rules (key for an environment)|textit}
\index{rowcolor@\texttt{\textbackslash rowcolor}!command of \texttt{\textbackslash CodeBefore}|textit}

\medskip
\begin{center}
\tcbset
  {
    colframe = blue!50!black ,
    colback = white ,
    fonttitle = \bfseries ,
    nobeforeafter ,
    center title
  }

\tcbox
  [
    left = 0mm ,
    right = 0mm ,
    top = 0mm ,
    bottom = 0mm ,
    boxsep = 0mm ,
    toptitle = 0.5mm ,
    bottomtitle = 0.5mm ,
    title = My table
  ]
  {
    \renewcommand{\arraystretch}{1.2}\begin{NiceTabular}{rcl}[hvlines-except-borders,rules/color=blue!50!black]
    \CodeBefore
      \rowcolor{red!15}{1}
    \Body
      One & Two & Three \\
      Men & Mice & Lions \\
      Upper & Middle & Lower
    \end{NiceTabular}
  }
\end{center}


\subsection{Notes in the tabulars}

\index{nota@\textbf{Notes in the tabulars}|textit}
\index{tabularnote@\texttt{\textbackslash tabularnote}|textit}
\index{notes (key to customize the notes of a\newline tabular)|textit}
\index{style (subkey of ``notes'')|textit}
\index{enumitem-keys (subkey of ``notes'')|textit}
\index{enumitem@\pkg{enumitem} (package required to use\newline \texttt{\textbackslash tabularnote})|textit}


\label{ex:notes}

The tools provided by \pkg{nicematrix} for the composition of the tabular
notes have been presented in the section \ref{s:notes} p.~\pageref{s:notes}.

\medskip
Let's consider that we wish to number the notes of a tabular with
stars.\footnote{Of course, it's realistic only when there is very few notes in
the tabular.}

\medskip
First, we write a command |\stars| similar the well-known commands 
|\arabic|, |\alph|, |\Alph|, etc. which produces a number of stars equal to
its argument\footnote{In fact: the value of its argument.}.
\begin{Code}
\ExplSyntaxOn
\NewDocumentCommand { \emph{\stars} } { m }
  { \prg_replicate:nn { \value { #1 } } { \( \star \) } } 
\ExplSyntaxOff
\end{Code}
%
Of course, we change the style of the labels with the key |notes/style|.
However, it would be interesting to change also some parameters in the type of
list used to compose the notes at the end of the tabular.
First, we required a composition flush right for the labels with the setting
|align=right|.
Moreover, we want the labels to be composed on a width equal to the width of
the widest label. The widest label is, of course, the label with the greatest
number of stars. We know that number: it is equal to |\value{tabularnote}|
(because |tabularnote| is the LaTeX counter used by |\tabularnote| and,
therefore, at the end of the tabular, its value is equal to the total number
of tabular notes). We use the key |widest*| of \pkg{enumitem} in order to
require a width equal to that value: |widest*=\value{tabularnote}|. 

\begin{Code}
\NiceMatrixOptions 
  {
    notes = 
     {
       \emph{style = \stars{#1} , 
       enumitem-keys = 
        { 
          widest* = \value{tabularnote} ,
          align = right 
        } }
     }
  }
\end{Code}



\begin{scope}
\ExplSyntaxOn
\NewDocumentCommand \stars { m }
  { \prg_replicate:nn { \value { #1 } } { \( \star \) } } 
\NiceMatrixOptions 
  {
    notes = 
     {
       style = \stars{#1} ,
       enumitem-keys = 
        {
          widest* = \value{tabularnote} ,
          align = right 
        }
     }
  }
\ExplSyntaxOff
\begin{Code}
\begin{NiceTabular}{@{}llr@{}}
\toprule \RowStyle{\bfseries}
Last name & First name & Birth day \\
\midrule
Achard\tabularnote{\emph{Achard is an old family of the Poitou.}} 
& Jacques & 5 juin 1962 \\
Lefebvre\tabularnote{\emph{The name Lefebvre is an alteration of the name Lefebure.}} 
& Mathilde & 23 mai 1988 \\
Vanesse & Stephany & 30 octobre 1994 \\
Dupont & Chantal & 15 janvier 1998 \\
\bottomrule
\end{NiceTabular}
\end{Code}

\begin{center}
\begin{NiceTabular}{@{}llr@{}}
\toprule \RowStyle{\bfseries}
Last name & First name & Birth day \\
\midrule
Achard\tabularnote{Achard is an old family of the Poitou.} 
& Jacques & June 5, 2005 \\
Lefebvre\tabularnote{The name Lefebvre is an alteration of the name Lefebure.} 
& Mathilde & January 23, 1975 \\
Vanesse & Stephany & October 30, 1994 \\
Dupont & Chantal & January 15, 1998 \\
\bottomrule
\end{NiceTabular}
\end{center}
\end{scope}



\subsection{Dotted lines}

\index{dotted@\textbf{Dotted lines}|textit}

An example with 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
\index{Ddots@\texttt{\textbackslash Ddots}|textit}

\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:\par\nobreak

\index{last-col|textit}
\index{code-for-last-col|textit}

\begin{Verbatim}
$\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}$
\end{Verbatim}


\[\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}\]



\subsection{Dotted lines which are no longer dotted}

The option |line-style| controls the style of the lines drawn by |\Ldots|,
|\Cdots|, etc. Thus, it's possible with these commands to draw lines which are
not longer dotted (TikZ should be loaded).

\index{line-style (key for the dotted rules)|textit}

\begin{Verbatim}[formatcom=\small\color{gray}]
\NiceMatrixOptions{code-for-first-row = \scriptstyle,code-for-first-col = \scriptstyle }
\setcounter{MaxMatrixCols}{12}
\newcommand{\blue}{\color{blue}}
\[\begin{pNiceMatrix}[last-row,last-col,nullify-dots,xdots/line-style={dashed,blue}]
1& & & \Vdots & & & & \Vdots \\
& \Ddots[line-style=standard] \\
& & 1 \\
\Cdots & & & \blue 0 & \Cdots & & & \blue 1 & & & \Cdots & \blue \leftarrow i \\
& & & & 1 \\
& & &\Vdots & & \Ddots[line-style=standard] & & \Vdots \\
& & & & & & 1 \\
\Cdots & & & \blue 1 & \Cdots & & \Cdots & \blue 0 & & & \Cdots & \blue \leftarrow j \\
& & & & & & & & 1 \\
& & & & & & & & & \Ddots[line-style=standard] \\
& & & \Vdots & & & & \Vdots & & & 1 \\
& & & \blue \overset{\uparrow}{i} & & & & \blue \overset{\uparrow}{j} \\
\end{pNiceMatrix}\]
\end{Verbatim}

\index{code-for-first-row|textit}
\index{code-for-last-col|textit}


\begin{scope}
\NiceMatrixOptions{code-for-first-row = \scriptstyle,code-for-first-col = \scriptstyle }
\setcounter{MaxMatrixCols}{12}
\newcommand{\blue}{\color{blue}}
\[\begin{pNiceMatrix}[last-row,last-col,nullify-dots,xdots/line-style={dashed,blue}]
1& & & \Vdots & & & & \Vdots \\
& \Ddots[line-style=standard] \\
& & 1 \\
\Cdots & & & \blue 0 & \Cdots & & & \blue 1 & & & \Cdots & \blue \leftarrow i \\
& & & & 1 \\
& & &\Vdots & & \Ddots[line-style=standard] & & \Vdots \\
& & & & & & 1 \\
\Cdots & & & \blue 1 & \Cdots & & \Cdots & \blue 0 & & & \Cdots & \blue \leftarrow j \\
& & & & & & & & 1 \\
& & & & & & & & & \Ddots[line-style=standard] \\
& & & \Vdots & & & & \Vdots & & & 1 \\
& & & \blue \overset{\uparrow}{i} & & & & \blue \overset{\uparrow}{j} \\
\end{pNiceMatrix}\]
\end{scope}

\interitem
In fact, it's even possible to draw solid lines with the commands |\Cdots|,
|\Vdots|, etc.\footnote{In this document, the TikZ library \pkg{arrows.meta}
has been loaded, which impacts the shape of the arrow tips.}

\begin{Verbatim}
\NiceMatrixOptions{xdots={horizontal-labels,line-style = <->}}
$\begin{pNiceArray}{ccc|cc}[first-row,last-col,margin]
\Hdotsfor{3}^{3} & \Hdotsfor{2}^{2} \\
2 & 1 & 1 & 1 & 1 & \Vdotsfor{3}^{3}\\
1 & 1 & 1 & 1 & 1 \\
1 & 1 & 1 & 1 & 1 \\
\Hline
1 & 1 & 1 & 1 & 1 & \Vdotsfor{2}^{2}\\
1 & 1 & 1 & 1 & 1 \\
\end{pNiceArray}$
\end{Verbatim}


\begin{center}
\NiceMatrixOptions{xdots={horizontal-labels,line-style = <->}}
$\begin{pNiceArray}{ccc|cc}[first-row,last-col,margin]
\Hdotsfor{3}^{3} & \Hdotsfor{2}^{2} \\
2 & 1 & 1 & 1 & 1 & \Vdotsfor{3}^{3}\\
1 & 1 & 1 & 1 & 1 \\
1 & 1 & 1 & 1 & 1 \\
\Hline
1 & 1 & 1 & 1 & 1 & \Vdotsfor{2}^{2}\\
1 & 1 & 1 & 1 & 1 \\
\end{pNiceArray}$
\end{center}

\interitem
\label{ex:colon}
If you want the label \emph{on the line}, you should use the special token~``|:|'':

\begin{Verbatim}
\NiceMatrixOptions{xdots={horizontal-labels,line-style = <->}}
$\begin{pNiceArray}{ccc|cc}[first-row,last-col,margin]
\Hdotsfor{3}:{3} & \Hdotsfor{2}:{2} \\
2 & 1 & 1 & 1 & 1 & \Vdotsfor{3}:{3}\\
1 & 1 & 1 & 1 & 1 \\
1 & 1 & 1 & 1 & 1 \\
\Hline
1 & 1 & 1 & 1 & 1 & \Vdotsfor{2}:{2}\\
1 & 1 & 1 & 1 & 1 \\
\end{pNiceArray}$
\end{Verbatim}


\begin{center}
\NiceMatrixOptions{xdots={horizontal-labels,line-style = <->}}
$\begin{pNiceArray}{ccc|cc}[first-row,last-col,margin]
\Hdotsfor{3}:{3} & \Hdotsfor{2}:{2} \\
2 & 1 & 1 & 1 & 1 & \Vdotsfor{3}:{3}\\
1 & 1 & 1 & 1 & 1 \\
1 & 1 & 1 & 1 & 1 \\
\Hline
1 & 1 & 1 & 1 & 1 & \Vdotsfor{2}:{2}\\
1 & 1 & 1 & 1 & 1 \\
\end{pNiceArray}$
\end{center}




\subsection{Dashed rules}
\label{dashed}
\index{tikzz@tikz!key of ``borders'' de \texttt{\textbackslash Block}|textit}

In the following example, we use the command |\Block| to draw dashed rules.
For that example, TikZ should be loaded (by |\usepackage{tikz}|).


\begin{Code}
\begin{pNiceMatrix}
\emph{\Block[borders={bottom,right,tikz=dashed}]{2-2}{}}
1 & 2 & 0  & 0 & 0 & 0 \\
4 & 5 & 0  & 0 & 0 & 0 \\
0 & 0 & \emph{\Block[borders={bottom,top,right,left,tikz=dashed}]{2-2}{}}
        7  & 1 & 0 & 0 \\
0 & 0 & -1 & 2 & 0 & 0 \\
0 & 0 & 0  & 0 & \emph{\Block[borders={left,top,tikz=dashed}]{2-2}{}}
                 3 & 4 \\
0 & 0 & 0  & 0 & 1 & 4 
\end{pNiceMatrix}
\end{Code}


\[\begin{pNiceMatrix}
\Block[borders={bottom,right,tikz=dashed}]{2-2}{}
1 & 2 & 0  & 0 & 0 & 0 \\
4 & 5 & 0  & 0 & 0 & 0 \\
0 & 0 & \Block[borders={bottom,top,right,left,tikz=dashed}]{2-2}{}
        7  & 1 & 0 & 0 \\
0 & 0 & -1 & 2 & 0 & 0 \\
0 & 0 & 0  & 0 & \Block[borders={left,top,tikz=dashed}]{2-2}{}
                 3 & 4 \\
0 & 0 & 0  & 0 & 1 & 4 
\end{pNiceMatrix}\]


\subsection{Stacks of matrices}

\index{NiceMatrixBlock@\texttt{\{NiceMatrixBlock\}}|textit}

We often need to compose mathematical matrices on top on each other (for
example for the resolution of linear systems).

\medskip
In order to have the columns aligned one above the other, it's possible to
fix a width for all the columns. That's what is done in the following example
with the environment |{NiceMatrixBlock}| and its option |auto-columns-width|.

\begin{small}
\begin{Code}
\emph{\begin{NiceMatrixBlock}[auto-columns-width]}
\NiceMatrixOptions
  {
    light-syntax,
    last-col, code-for-last-col = \color{blue}\scriptstyle,
    vlines = 5 ,
    matrix/columns-type = r ,
    no-cell-nodes % only for speedup
  }
\setlength{\extrarowheight}{1mm}

\quad $\begin{pNiceMatrix}
12  -8  7  5   3 {} ;
 3 -18 12  1   4    ;
-3 -46 29 -2 -15    ;
 9  10 -5  4   7
\end{pNiceMatrix}$

\smallskip
\quad $\begin{pNiceMatrix}
12  -8   7  5   3 ;
0   64 -41  1  19  { L_2 \gets L_1-4L_2  } ;
0 -192 123 -3 -57  { L_3 \gets L_1+4L_3  } ;
0 -64   41 -1 -19  { L_4 \gets 3L_1-4L_4 } ;
\end{pNiceMatrix}$

\smallskip
\quad $\begin{pNiceMatrix}
12 -8   7 5  3 ;
0  64 -41 1 19 ;
0   0   0 0  0 { L_3 \gets 3 L_2 + L_3 }
\end{pNiceMatrix}$

\smallskip
\quad $\begin{pNiceMatrix}
12 -8   7 5  3 {} ;
0  64 -41 1 19    ;
\end{pNiceMatrix}$
\emph{\end{NiceMatrixBlock}}
\end{Code}%
\end{small}

\medskip
\index{auto-columns-width!(clé de \texttt{\{NiceMatrixBlock\}})|textit}
\begin{NiceMatrixBlock}[auto-columns-width]
\NiceMatrixOptions
  {
    light-syntax,
    last-col, code-for-last-col = \color{blue}\scriptstyle,
    vlines = 5 ,
    matrix/columns-type = r ,
    no-cell-nodes
  }
\setlength{\extrarowheight}{1mm}

\quad $\begin{pNiceMatrix}
12  -8  7  5   3 {} ;
 3 -18 12  1   4    ;
-3 -46 29 -2 -15    ;
 9  10 -5  4   7
\end{pNiceMatrix}$

\smallskip
\quad $\begin{pNiceMatrix}
12  -8   7  5   3                      ;
0   64 -41  1  19  { L_2 \gets L_1-4L_2  } ;
0 -192 123 -3 -57  { L_3 \gets L_1+4L_3  } ;
0 -64   41 -1 -19  { L_4 \gets 3L_1-4L_4 } ;
\end{pNiceMatrix}$

\smallskip
\quad $\begin{pNiceMatrix}
12 -8   7 5  3 ;
0  64 -41 1 19 ;
0   0   0 0  0 { L_3 \gets 3 L_2 + L_3 }
\end{pNiceMatrix}$

\smallskip
\quad $\begin{pNiceMatrix}
12 -8   7 5  3 {} ;
0  64 -41 1 19    ;
\end{pNiceMatrix}$
\end{NiceMatrixBlock}

\bigskip
However, one can see that the last matrix is not perfectly aligned with
others. That's why, in LaTeX, the parenthesis have not exactly the same width
(smaller parenthesis are a bit slimer).

\medskip
\index{max-width (subkey of ``delimiters'')}
\index{delimiters!---/max-width}
In order the solve that problem, it's possible to require the delimiters to be
composed with the maximal width, thanks to the boolean key
|delimiters/max-width|.

\begin{small}
\begin{Code}
\emph{\begin{NiceMatrixBlock}[auto-columns-width]}
\NiceMatrixOptions
  {
    \emph{delimiters/max-width},
    light-syntax,
    last-col, code-for-last-col = \color{blue}\scriptstyle,
    vlines = 5 ,
    matrix/columns-type = r ,
    no-cell-nodes % only for speedup
  }
\setlength{\extrarowheight}{1mm}

\quad $\begin{pNiceMatrix}
12  -8  7  5   3 {} ;
 3 -18 12  1   4    ;
-3 -46 29 -2 -15    ;
 9  10 -5  4   7
\end{pNiceMatrix}$
...
\emph{\end{NiceMatrixBlock}}
\end{Code}%
\end{small}

\medskip
\begin{NiceMatrixBlock}[auto-columns-width]
\NiceMatrixOptions
  {
    delimiters/max-width,
    light-syntax,
    last-col, code-for-last-col = \color{blue}\scriptstyle,
    vlines = 5 ,
    matrix/columns-type = r ,
    no-cell-nodes
  }
\setlength{\extrarowheight}{1mm}

\quad $\begin{pNiceMatrix}
12  -8  7  5   3 {} ;
 3 -18 12  1   4    ;
-3 -46 29 -2 -15    ;
 9  10 -5  4   7
\end{pNiceMatrix}$

\smallskip
\quad $\begin{pNiceMatrix}
12  -8   7  5   3                      ;
0   64 -41  1  19  { L_2 \gets L_1-4L_2  } ;
0 -192 123 -3 -57  { L_3 \gets L_1+4L_3  } ;
0 -64   41 -1 -19  { L_4 \gets 3L_1-4L_4 } ;
\end{pNiceMatrix}$

\smallskip
\quad $\begin{pNiceMatrix}
12 -8   7 5  3 ;
0  64 -41 1 19 ;
0   0   0 0  0 { L_3 \gets 3 L_2 + L_3 }
\end{pNiceMatrix}$

\smallskip
\quad $\begin{pNiceMatrix}
12 -8   7 5  3 {} ;
0  64 -41 1 19    ;
\end{pNiceMatrix}$
\end{NiceMatrixBlock}


\interitem
If you wish an alignment of the different matrices without the same width
for all the columns, you can construct a unique array and place the
parenthesis with commands |\SubMatrix| in the |\CodeAfter|. Of course, that
array can't be broken by a page break.

\medskip
\index{SubMatrix@\texttt{\textbackslash SubMatrix} (command of 
\texttt{\textbackslash CodeAfter}\newline and 
\texttt{\textbackslash CodeBefore})|textit}

\begin{Code}
\setlength{\extrarowheight}{1mm}
\[\begin{NiceMatrix}[r, last-col=6, code-for-last-col = \scriptstyle \color{blue}]
12 &  -8  &  7 & 5 &  3 \\
 3 & -18  & 12 & 1 &  4 \\
-3 & -46  & 29 &-2 &-15 \\
 9 & 10   &-5  &4  & 7 \\[1mm]
12 & -8   & 7  &5  & 3 \\
0  & 64   &-41 & 1 & 19 & L_2 \gets L_1-4L_2  \\
0  & -192 &123 &-3 &-57 & L_3 \gets L_1+4L_3  \\
0  & -64  & 41 &-1 &-19 & L_4 \gets 3L_1-4L_4 \\[1mm]
12 & -8   &7   &5  & 3 \\
0  & 64   &-41 &1  &19 \\
0  &  0   &0   &0  & 0  & L_3 \gets 3L_2+L_3 \\[1mm]
12 & -8   &7   &5  & 3 \\
0  & 64   &-41 & 1 & 19 \\
\emph{\CodeAfter [sub-matrix/vlines=4]
   \SubMatrix({1-1}{4-5})
   \SubMatrix({5-1}{8-5})
   \SubMatrix({9-1}{11-5})
   \SubMatrix({12-1}{13-5})}
\end{NiceMatrix}\]
\end{Code}

\medskip
\begin{scope}
\setlength{\extrarowheight}{1mm}
\[\begin{NiceMatrix}[ r, last-col=6, code-for-last-col = \scriptstyle \color{blue} ]
12 &  -8  &  7 & 5 &  3 \\
 3 & -18  & 12 & 1 &  4 \\
-3 & -46  & 29 &-2 &-15 \\
 9 & 10   &-5  &4  & 7 \\[1mm]
12 & -8   & 7  &5  & 3 \\
0  & 64   &-41 & 1 & 19 & L_2 \gets L_1-4L_2  \\
0  & -192 &123 &-3 &-57 & L_3 \gets L_1+4L_3  \\
0  & -64  & 41 &-1 &-19 & L_4 \gets 3L_1-4L_4 \\[1mm]
12 & -8   &7   &5  & 3 \\
0  & 64   &-41 &1  &19 \\
0  &  0   &0   &0  & 0 & L_3 \gets 3L_2+L_3 \\[1mm]
12 & -8   &7   &5  & 3 \\
0  & 64   &-41 & 1 & 19 \\
\CodeAfter [sub-matrix/vlines=4]
   \SubMatrix({1-1}{4-5})
   \SubMatrix({5-1}{8-5})
   \SubMatrix({9-1}{11-5})
   \SubMatrix({12-1}{13-5})
\end{NiceMatrix}\]
\end{scope}

\bigskip
In this tabular, the instructions |\SubMatrix| are executed after the
composition of the tabular and, thus, the vertical rules are drawn without
adding space between the columns.


\bigskip
In fact, it's possible, with the key |vlines-in-sub-matrix|, to choice a
letter in the preamble of the array to specify vertical rules which will be
drawn in the |\SubMatrix| only (by adding space between the columns).

\index{vlines-in-sub-matrix}
\medskip
\begin{Code}
\setlength{\extrarowheight}{1mm}
\[\begin{NiceArray}
   [ 
     \emph{vlines-in-sub-matrix=I},
     last-col, 
     code-for-last-col = \scriptstyle \color{blue} 
   ]
  {rrrrIr}
12 &  -8  &  7 & 5 &  3 \\
 3 & -18  & 12 & 1 &  4 \\
-3 & -46  & 29 &-2 &-15 \\
 9 & 10   &-5  &4  & 7 \\[1mm]
12 & -8   & 7  &5  & 3 \\
0  & 64   &-41 & 1 & 19 & L_2 \gets L_1-4L_2  \\
0  & -192 &123 &-3 &-57 & L_3 \gets L_1+4L_3  \\
0  & -64  & 41 &-1 &-19 & L_4 \gets 3L_1-4L_4 \\[1mm]
12 & -8   &7   &5  & 3 \\
0  & 64   &-41 &1  &19 \\
0  &  0   &0   &0  & 0 & L_3 \gets 3L_2+L_3 \\[1mm]
12 & -8   &7   &5  & 3 \\
0  & 64   &-41 & 1 & 19 \\
\CodeAfter 
   \SubMatrix({1-1}{4-5})
   \SubMatrix({5-1}{8-5})
   \SubMatrix({9-1}{11-5})
   \SubMatrix({12-1}{13-5})
\end{NiceArray}\]
\end{Code}


\medskip
\begin{scope}
\setlength{\extrarowheight}{1mm}
\[\begin{NiceArray}
   [ 
     vlines-in-sub-matrix=I,
     last-col, 
     code-for-last-col = \scriptstyle \color{blue} 
   ]
  {rrrrIr}
12 &  -8  &  7 & 5 &  3 \\
 3 & -18  & 12 & 1 &  4 \\
-3 & -46  & 29 &-2 &-15 \\
 9 & 10   &-5  &4  & 7 \\[1mm]
12 & -8   & 7  &5  & 3 \\
0  & 64   &-41 & 1 & 19 & L_2 \gets L_1-4L_2  \\
0  & -192 &123 &-3 &-57 & L_3 \gets L_1+4L_3  \\
0  & -64  & 41 &-1 &-19 & L_4 \gets 3L_1-4L_4 \\[1mm]
12 & -8   &7   &5  & 3 \\
0  & 64   &-41 &1  &19 \\
0  &  0   &0   &0  & 0 & L_3 \gets 3L_2+L_3 \\[1mm]
12 & -8   &7   &5  & 3 \\
0  & 64   &-41 & 1 & 19 \\
\CodeAfter 
   \SubMatrix({1-1}{4-5})
   \SubMatrix({5-1}{8-5})
   \SubMatrix({9-1}{11-5})
   \SubMatrix({12-1}{13-5})
\end{NiceArray}\]
\end{scope}





\subsection{How to highlight cells of a matrix}


\label{highlight}
\index{draw (key of \texttt{\textbackslash Block})|textit}

\medskip
In order to highlight a cell of a matrix, it's possible to ``draw'' that cell
with the key |draw| of the command |\Block| (this is one of the uses of a
mono-cell block\footnote{We recall that, if the first mandatory argument of
the command |\Block| is left empty, that means that the block is a mono-cell block}).

\label{example-CodeAfter}


\begin{Code}
$\begin{pNiceArray}{>{\strut}cccc}[margin,rules/color=blue,no-cell-nodes]
\emph{\Block[draw]{}{a_{11}}} & a_{12} & a_{13} & a_{14} \\
a_{21} & \Block[draw]{}{a_{22}} & a_{23} & a_{24} \\
a_{31} & a_{32} & \Block[draw]{}{a_{33}} & a_{34} \\
a_{41} & a_{42} & a_{43} & \Block[draw]{}{a_{44}} \\
\end{pNiceArray}$
\end{Code}
\[\begin{pNiceArray}{>{\strut}cccc}[margin,rules/color=blue,no-cell-nodes]
\Block[draw]{}{a_{11}} & a_{12} & a_{13} & a_{14} \\
a_{21} & \Block[draw]{}{a_{22}} & a_{23} & a_{24} \\
a_{31} & a_{32} & \Block[draw]{}{a_{33}} & a_{34} \\
a_{41} & a_{42} & a_{43} & \Block[draw]{}{a_{44}} \\
\end{pNiceArray}\]

We should remark that the rules we have drawn are drawn \emph{after} the
construction of the array and thus, they don't spread the cells of the array.
We recall that, on the other side, the commands |\hline| and |\Hline|, the
specifier ``\verb+|+'' and the options |hlines|, |vlines|, |hvlines| and
|hvlines-except-borders| spread the cells.\footnote{For the command |\cline|,
see the remark p.~\pageref{remark-cline}.}


\vspace{1cm}
It's possible to color a row with |\rowcolor| in the |code-before| (or with
|\rowcolor| in the first cell of the row if the key |color-inside| is
used−even when \pkg{colortbl} is not loaded).

\index{color-inside|textit}
\index{rowcolor@\texttt{\textbackslash rowcolor}!command in tabular|textit}


\medskip
\begin{Code}
\begin{pNiceArray}{>{\strut}cccc}% <-- % mandatory
   [margin, extra-margin=2pt,color-inside,no-cell-nodes]
  \emph{\rowcolor{red!15}}A_{11} & A_{12} & A_{13} & A_{14} \\
  A_{21} & \emph{\rowcolor{red!15}}A_{22} & A_{23} & A_{24} \\
  A_{31} & A_{32} & \emph{\rowcolor{red!15}}A_{33} & A_{34} \\
  A_{41} & A_{42} & A_{43} & \emph{\rowcolor{red!15}}A_{44}  
\end{pNiceArray}
\end{Code}

\[\begin{pNiceArray}{>{\strut}cccc}[margin, extra-margin=2pt,color-inside,no-cell-nodes]
  \rowcolor{red!15}A_{11} & A_{12} & A_{13} & A_{14} \\
  A_{21} & \rowcolor{red!15}A_{22} & A_{23} & A_{24} \\
  A_{31} & A_{32} & \rowcolor{red!15}A_{33} & A_{34} \\
  A_{41} & A_{42} & A_{43} & \rowcolor{red!15}A_{44}  
\end{pNiceArray}\]

\bigskip
However, it's not possible to do a fine tuning. That's why we describe now a
method to highlight a row of the matrix. 

\medskip
That example and the following ones require TikZ (by default, \pkg{nicematrix}
only loads \textsc{pgf}, which is a sub-layer of TikZ) and the TikZ library
|fit|. The following lines in the preamble of your document do the job:
\begin{verbatim}
\usepackage{tikz}
\usetikzlibrary{fit}
\end{verbatim}

\medskip 
We create a rectangular TikZ node which encompasses the nodes of the second
row by using the tools of the TikZ library \pkg{fit}. Those nodes are not
available by default in the |\CodeBefore| (for efficiency). We have to require
their creation with the key |create-cell-nodes| of the keyword |\CodeBefore|.

\tikzset{highlight/.style={rectangle,
                           fill=red!15,
                           rounded corners = 0.5 mm, 
                           inner sep=1pt,
                           fit = #1}}

\medskip
\index{highlight (TikZ style defined in\newline an example)|textit}
\begin{Code}
\tikzset{highlight/.style={rectangle,
                           fill=red!15,
                           rounded corners = 0.5 mm, 
                           inner sep=1pt,
                           fit=#1}}

$\begin{bNiceMatrix}
\emph{\CodeBefore [create-cell-nodes] 
  \tikz \node [highlight = (2-1) (2-3)] {} ; 
\Body}
0 & \Cdots & 0 \\
1 & \Cdots & 1 \\
0 & \Cdots & 0 \\
\end{bNiceMatrix}$
\end{Code}
\index{create-cell-nodes (key of \texttt{\textbackslash CodeBefore})|textit}
\index{CodeBefore@\texttt{\textbackslash CodeBefore}...\texttt{\textbackslash Body}|textit}

\[\begin{bNiceMatrix}
\CodeBefore [create-cell-nodes] 
  \tikz \node [highlight = (2-1) (2-3)] {} ;
\Body
0 & \Cdots & 0 \\
1 & \Cdots & 1 \\
0 & \Cdots & 0 \\
\end{bNiceMatrix}\]


\vspace{1cm}
We consider now the following matrix. If we want to highlight each row of
this matrix, we can use the previous technique three times.

\begin{Code}
\begin{pNiceArray}{ccc}[last-col, margin = 2pt]
\CodeBefore [create-cell-nodes]
  \begin{tikzpicture}
  \emph{\node [highlight = (1-1) (1-3)] {} ;
  \node [highlight = (2-1) (2-3)] {} ;
  \node [highlight = (3-1) (3-3)] {} ;}
  \end{tikzpicture}
\Body
a & a + b & a + b + c & L_1 \\
a & a     & a + b     & L_2 \\
a & a     & a         & L_3
\end{pNiceArray}
\end{Code}


\[\begin{pNiceArray}{ccc}[last-col, margin = 2pt]
\CodeBefore [create-cell-nodes]
  \begin{tikzpicture}
  \node [highlight = (1-1) (1-3)] {} ;
  \node [highlight = (2-1) (2-3)] {} ;
  \node [highlight = (3-1) (3-3)] {} ;
  \end{tikzpicture}
\Body
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''. 

\index{create-medium-nodes|textit}
\index{create-cell-nodes (key of \texttt{\textbackslash CodeBefore})|textit}


\begin{Code}
\[\begin{pNiceArray}{ccc}[last-col, margin = 2pt, create-medium-nodes]
\CodeBefore [create-cell-nodes]
  \begin{tikzpicture} \emph{[name suffix = -medium]}
  \node [highlight = (1-1) (1-3)] {} ;
  \node [highlight = (2-1) (2-3)] {} ;
  \node [highlight = (3-1) (3-3)] {} ;
  \end{tikzpicture}
\Body
a & a + b & a + b + c & L_1 \\
a & a     & a + b     & L_2 \\
a & a     & a         & L_3
\end{pNiceArray}\]
\end{Code}


\[\begin{pNiceArray}{ccc}[last-col, margin = 2pt, create-medium-nodes]
\CodeBefore [create-cell-nodes]
  \begin{tikzpicture} [name suffix = -medium]
  \node [highlight = (1-1) (1-3)] {} ;
  \node [highlight = (2-1) (2-3)] {} ;
  \node [highlight = (3-1) (3-3)] {} ;
  \end{tikzpicture}
\Body
a & a + b & a + b + c & L_1 \\
a & a     & a + b     & L_2 \\
a & a     & a         & L_3
\end{pNiceArray}\]




\subsection{Utilisation of \textbackslash SubMatrix in the \textbackslash CodeBefore}

\label{submatrix-in-codebefore}

\index{SubMatrix@\texttt{\textbackslash SubMatrix} (command of 
\texttt{\textbackslash CodeAfter}\newline and 
\texttt{\textbackslash CodeBefore})|textit}
\index{CodeBefore@\texttt{\textbackslash CodeBefore}...\texttt{\textbackslash Body}|textit}
\index{CodeAfter@\texttt{\textbackslash CodeAfter}|textit}
\index{create-cell-nodes (key of \texttt{\textbackslash CodeBefore})|textit}


In the following example, we illustrate the mathematical product of two
matrices. 

The whole figure is an environment |{NiceArray}| and the three pairs of
parenthesis have been added with |\SubMatrix| in the |\CodeBefore|.

\tikzset{highlight/.style={rectangle,
                           fill=red!15,
                           rounded corners = 0.5 mm, 
                           inner sep=1pt,
                           fit=#1}}%
\[\begin{NiceArray}{*{6}{c}@{\hspace{6mm}}*{5}{c}}[nullify-dots]
\CodeBefore [create-cell-nodes]
  \SubMatrix({2-7}{6-last})
  \SubMatrix({7-2}{last-6})
  \SubMatrix({7-7}{last-last})
  \begin{tikzpicture}
    \node [highlight = (9-2) (9-6)] { } ; 
    \node [highlight = (2-9) (6-9)] { } ;
  \end{tikzpicture}
\Body
    &        &        &        &        &        &        &        & \color{blue}\scriptstyle C_j \\
    &        &        &        &        &        & b_{11} & \Cdots & b_{1j} & \Cdots & b_{1n} \\
    &        &        &        &        &        & \Vdots &        & \Vdots &        & \Vdots \\
    &        &        &        &        &        &        &        & b_{kj} \\
    &        &        &        &        &        &        &        & \Vdots \\
    &        &        &        &        &        & b_{n1} & \Cdots & b_{nj} & \Cdots & b_{nn} \\[3mm]
    & a_{11} & \Cdots &        &        & a_{1n} \\
    & \Vdots &        &        &        & \Vdots &        &        & \Vdots \\
\color{blue}\scriptstyle L_i 
    & a_{i1} & \Cdots & a_{ik} & \Cdots & a_{in} & \Cdots &        & c_{ij} \\
    & \Vdots &        &        &        & \Vdots \\
    & a_{n1} & \Cdots &        &        & a_{nn}  \\
\CodeAfter
\tikz \draw [gray,shorten > = 1mm, shorten < = 1mm] (9-4.north) to [bend left] (4-9.west) ;
\end{NiceArray}\]


\vspace{1cm}
\begin{Verbatim}
\tikzset{highlight/.style={rectangle,
                           fill=red!15,
                           rounded corners = 0.5 mm, 
                           inner sep=1pt,
                           fit=~#1}}
\end{Verbatim}

\begin{footnotesize}
\begin{Code}
\[\begin{NiceArray}{*{6}{c}@{\hspace{6mm}}*{5}{c}}[nullify-dots]
\CodeBefore [create-cell-nodes]
  \SubMatrix({2-7}{6-last})
  \SubMatrix({7-2}{last-6})
  \SubMatrix({7-7}{last-last})
  \begin{tikzpicture}
    \node [highlight = (9-2) (9-6)] { } ; 
    \node [highlight = (2-9) (6-9)] { } ;
  \end{tikzpicture}
\Body
    &        &        &        &        &        &        &        & \color{blue}\scriptstyle C_j \\
    &        &        &        &        &        & b_{11} & \Cdots & b_{1j} & \Cdots & b_{1n} \\
    &        &        &        &        &        & \Vdots &        & \Vdots &        & \Vdots \\
    &        &        &        &        &        &        &        & b_{kj} \\
    &        &        &        &        &        &        &        & \Vdots \\
    &        &        &        &        &        & b_{n1} & \Cdots & b_{nj} & \Cdots & b_{nn} \\[3mm]
    & a_{11} & \Cdots &        &        & a_{1n} \\
    & \Vdots &        &        &        & \Vdots &        &        & \Vdots \\
\color{blue}\scriptstyle L_i 
    & a_{i1} & \Cdots & a_{ik} & \Cdots & a_{in} & \Cdots &        & c_{ij} \\
    & \Vdots &        &        &        & \Vdots \\
    & a_{n1} & \Cdots &        &        & a_{nn}  \\
\CodeAfter
\tikz \draw [gray,shorten > = 1mm, shorten < = 1mm] (9-4.north) to [bend left] (4-9.west) ;
\end{NiceArray}\]
\end{Code}%
\end{footnotesize}



\subsection{A triangular tabular}

\label{triangular}

\index{pgf-node-code|textit}
\index{Corners (the empty ---)|textit}
\index{chessboardcolors@\texttt{\textbackslash chessboardcolors}!(commande
  du \texttt{\textbackslash CodeBefore})|textit}
\index{CodeBefore@\texttt{\textbackslash CodeBefore}...\texttt{\textbackslash Body}|textit}

In the following example, we use the style PGF/TikZ |nicematrix/cell-node|
to rotate the contents of the cells (and, then, we compensate that rotation by
a rotation of the whole tabular with the command |\adjustbox| of the eponymous
package, which must be loaded previously).


\medskip
\begin{Code}
\pgfset 
  { 
    \emph{nicematrix/cell-node}/.append style = 
      { text/rotate = 45, minimum size = 6 mm }
  }

\setlength{\tabcolsep}{0pt}

\emph{\adjustbox}{rotate = -45, set depth = 6mm + 1.414 \arrayrulewidth}
  {\begin{NiceTabular} [ hvlines, corners=SE, baseline = line-9 ] { cccccccc }
   \CodeBefore
     \chessboardcolors{red!15}{blue!15}
   \Body
     1 & 1 & 1  & 1  & 1  & 1 & 1 & 1 \\
     1 & 2 & 3  & 4  & 5  & 6 & 7 \\
     1 & 3 & 6  & 10 & 15 & 21 \\
     1 & 4 & 10 & 20 & 35 \\
     1 & 5 & 15 & 35 \\
     1 & 6 & 21 \\
     1 & 7 \\
     1 
   \end{NiceTabular}}
\end{Code}%


\begin{center}
\pgfset 
  { 
    nicematrix/cell-node/.append style = 
      { text/rotate = 45, minimum size = 6 mm }
  }%
\setlength{\tabcolsep}{0pt}%
\adjustbox{rotate = -45, set depth = 6mm + 1.414 \arrayrulewidth}
  {\begin{NiceTabular} [ hvlines, corners=SE, baseline = line-9 ] { cccccccc }
   \CodeBefore
     \chessboardcolors{red!15}{blue!15}
   \Body
     1 & 1 & 1  & 1  & 1  & 1 & 1 & 1 \\
     1 & 2 & 3  & 4  & 5  & 6 & 7 \\
     1 & 3 & 6  & 10 & 15 & 21 \\
     1 & 4 & 10 & 20 & 35 \\
     1 & 5 & 15 & 35 \\
     1 & 6 & 21 \\
     1 & 7 \\
     1 
   \end{NiceTabular}}
\end{center}


\newpage
\vspace{1cm}
\section{History}

The successive versions of the file |nicematrix.sty| provided by TeXLive are available on the
\textsc{svn} server of TeXLive:\par\nobreak

\smallskip
{
\small
\nolinkurl{https:www.tug.org/svn/texlive/trunk/Master/texmf-dist/tex/latex/nicematrix/nicematrix.sty}
}

\subsection*{Changes between version 6.27 and 6.28}

Sub-blocks with the character |&| (when the key |ampersand-in-block| is in
force).

Keys |p| and |j| for the command |\Block|.

PGF nodes i.1, i.2, i.3, etc.

\subsection*{Changes between version 6.26 and 6.27}

New key |light-syntax-expanded|.

\subsection*{Changes between version 6.25 and 6.26}

Special color |nocolor|.

\subsection*{Changes between version 6.24 and 6.25}

Correction of several bugs.

An instruction |\rowlistcolors| in the tabular stops the effect of a previous
|\rowlistcolors|.


\subsection*{Changes between version 6.23 and 6.24}

New command |\TikzEveryCell| available in the |\CodeAfter| and the |\CodeBefore|
to apply the same TikZ instruction to all the cells and blocks of the array.

New key |offset| in the key |tikz| of a command |\Block|.


\subsection*{Changes between version 6.22 and 6.23}

The specifier ``\verb+|+'' in the preambles of the environments has now an
optional argument.

Correction of several bugs.

\subsection*{Changes between version 6.21 and 6.22}

Key |opacity| for the command |\Block|.

It's now possible to put a label on a ``continuous dotted line'' with the
specifier ``|:|''.


\subsection*{Changes between version 6.20a and 6.21}

Key |c| for the command |\tabularnote|.

New commands |\rowcolors| and |\rowlistcolors| available in the array itself
(previously, there were only two commands |\rowcolors| and |\rowlistcolors|
available in the |\CodeBefore|.


\subsection*{Changes between version 6.20 and 6.20a}

The value of the key |name| of an environment of \pkg{nicematrix} is expanded
(in the TeX sens).

The labels of the tabular notes (created by the command |\tabularnote|) are now
composed in an overlapping position \emph{only} when the horizontal alignment
mode of the column is |c| or |r|.

\subsection*{Changes between version 6.19 and 6.20}

New key |xdots/horizontal-labels|.

\subsection*{Changes between version 6.18 and 6.19}

The command |\tabularnote| now supports an optional argument (between square
brackets) to change the symbol of the reference of the note.

\subsection*{Changes between version 6.17 and 6.18}

New key |opacity| in the commands to color cells, rows and columns.

New key |rounded-corners| for a whole tabular.


\subsection*{Changes between version 6.16 and 6.17}

New PGF/TikZ style |nicematrix/cell-node|.

New key |pgf-node-code|

\subsection*{Changes between version 6.15 and 6.16}

It's now possible to put any LaTeX extensible delimiter (|\lgroup|, |\langle|,
etc.) in the preamble of an environment with preamble (such as |{NiceArray}|)
by prefixing them by |\left| and |\right|.

New key |code| for the command |\SubMatrix| in the |\CodeAfter|.

\subsection*{Changes between version 6.14 and 6.15}

New key |transparent| for the command |\Block| (with that key, the rules are
drawn within the block).

\subsection*{Changes between version 6.13 and 6.14}

New keys for the command |\Block| for the vertical position of the content of
that block.

\subsection*{Changes between version 6.12 and 6.13}

New environment |{TabularNote}| in |{NiceTabular}| with the same semantic as
the key |tabularnote| (for legibility).

The command |\Hline| nows accepts options (between square brackets).

\subsection*{Changes between version 6.11 and 6.12}

New keys |caption|, |short-caption| and |label| in the environment
|{NiceTabular}|. 

In |{NiceTabular}|, a caption specified by the key |caption| is wrapped to the 
width of the tabular.

Correction of a bug: it's now possible to use |\OverBrace| and |\UnderBrace|
with \pkg{unicode-math} (with XeLaTeX or LuaLaTeX).

\subsection*{Changes between version 6.10 and 6.11}

New key |matrix/columns-type| to specify the type of columns of the matrices.

New key |ccommand| in |custom-line| and new command |\cdottedline|.

\subsection*{Changes between version 6.9 and 6.10}

New keys |xdots/shorten-start| and |xdots/shorten-end|.

It's possible to use |\line| in the |\CodeAfter| between two blocks (and not
only two cells).

\subsection*{Changes between version 6.8 and 6.9}

New keys |xdots/radius| and |xdots/inter| for customisation of the continuous
dotted lines.

New command |\ShowCellNames| available in the |\CodeBefore| and in the |\CodeAfter|.

\subsection*{Changes between version 6.7 and 6.8}

In the notes of a tabular (with the command |\tabularnote|), the duplicates
are now detected: when several commands |\tabularnote| are used with the same
argument, only one note is created at the end of the tabular (but all the
labels are present, of course).

\subsection*{Changes between version 6.6 and 6.7}

Key |color| for |\OverBrace| and |\UnderBrace| in the |\CodeAfter|

Key |tikz| in the key |borders| of a command |\Block|

\subsection*{Changes between version 6.5 and 6.6}

Keys |tikz| and |width| in |custom-line|.

\subsection*{Changes between versions 6.4 and 6.5}

Key |custom-line| in |\NiceMatrixOptions|.

Key |respect-arraystretch|.

\subsection*{Changes between versions 6.3 and 6.4}

New commands |\UnderBrace| and |\OverBrace| in the |\CodeAfter|.

Correction of a bug of the key |baseline| (cf. question 623258 on TeX StackExchange).

Correction of a bug with the columns |V| of \pkg{varwidth}.

Correction of a bug: the use of |\hdottedline| and |:| in the preamble of the
array (of another letter specified by |letter-for-dotted-lines|) was
incompatible with the key |xdots/line-style|.

\subsection*{Changes between versions 6.2 and 6.3}

Keys |nb-rows|, |rowcolor| and |bold| for the command |\RowStyle|

Key |name| for the command |\Block|.

Support for the columns |V| of \pkg{varwidth}.

\subsection*{Changes between versions 6.1 and 6.2}

Better compatibility with the classes \cls{revtex4-1} and \cls{revtex4-2}.

Key |vlines-in-sub-matrix|.

\subsection*{Changes between versions 6.0 and 6.1}

Better computation of the widths of the |X| columns.

Key |\color| for the command |\RowStyle|.

\subsection*{Changes between versions 5.19 and 6.0}

Columns |X| and environment |{NiceTabularX}|.

Command |\rowlistcolors| available in the |\CodeBefore|.

In columns with fixed width, the blocks are composed as paragraphs (wrapping
of the lines).

The key |define-L-C-R| has been deleted.

\subsection*{Changes between versions 5.18 and 5.19}

New key |tikz| for the command |\Block|.

\subsection*{Changes between versions 5.17 and 5.18}

New command |\RowStyle|

\subsection*{Changes between versions 5.16 and 5.17}

The key |define-L-C-R| (only available at load-time) now raises a (non fatal)
error.

Keys |L|, |C| and |R| for the command |\Block|.

Key |hvlines-except-borders|.

It's now possible to use a key |l|, |r| or |c| with the command
|\pAutoNiceMatrix| (and the similar ones).

\subsection*{Changes between versions 5.15 and 5.16}

It's now possible to use the cells corresponding to the contents of the nodes
(of the form |i-j|) in the |\CodeBefore| when the key |create-cell-nodes| of
that |\CodeBefore| is used. The medium and the large nodes are also available
if the corresponding keys are used.

\subsection*{Changes between versions 5.14 and 5.15}

Key |hvlines| for the command |\Block|.

The commands provided by \pkg{nicematrix} to color cells, rows and columns
don't color the cells which are in the ``corners'' (when the key |corner| is
used).

It's now possible to specify delimiters for submatrices in the preamble of an
environment. 

The version 5.15b is compatible with the version 3.0+ of \pkg{siunitx}
(previous versions were not).

\subsection*{Changes between versions 5.13 and 5.14}

Nodes of the form |(1.5)|, |(2.5)|, |(3.5)|, etc. 

Keys |t| and |b| for the command |\Block|.

Key |corners|. 

\subsection*{Changes between versions 5.12 and 5.13}

New command |\arraycolor| in the |\CodeBefore| (with its key
|except-corners|).

New key |borders| for the command |\Block|.

New command |\Hline| (for horizontal rules not drawn in the blocks).

The keys |vlines| and |hlines| takes in as value a (comma-separated) list of
numbers (for the rules to draw).

\subsection*{Changes between versions 5.11 and 5.12}

Keywords |\CodeBefore| and |\Body| (alternative syntax to the key
|code-before|). 

New key |delimiters/max-width|.

New keys |hlines|, |vlines| and |hvlines| for the command |\SubMatrix| in the
|\CodeAfter|. 

New key |rounded-corners| for the command |\Block|.

\subsection*{Changes between versions 5.10 and 5.11}

It's now possible, in the |code-before| and in the |\CodeAfter|, to use the
syntax \verb+|(i-|j)+ for the TikZ node at the intersection of the (potential)
horizontal rule number~$i$ and the (potential) vertical rule number~$j$.

\subsection*{Changes between versions 5.9 and 5.10}

New command |\SubMatrix| available in the |\CodeAfter|.

It's possible to provide options (between brackets) to the keyword |\CodeAfter|.

\subsection*{Changes between versions 5.8 and 5.9}

Correction of a bug: in the previous versions, it was not possible to use the
key |line-style| for the continuous dotted lines when the TikZ library |babel|
was loaded.

New key |cell-space-limits|.

\subsection*{Changes between versions 5.7 and 5.8}

Keys |cols| and |restart| of the command |\rowcolors| in the |code-before|.

Modification of the behaviour of |\\| in the columns of type |p|, |m| or |b|
(for a behaviour similar to the environments of \pkg{array}).

Better error messages for the command |\Block|.

\subsection*{Changes between versions 5.6 and 5.7}

New key |delimiters-color|

Keys |fill|, |draw| and |line-width| for the command |\Block|.

\subsection*{Changes between versions 5.5 and 5.6}

Different behaviour for the mono-row blocks.

New command |\NotEmpty|.

\subsection*{Changes between versions 5.4 and 5.5}

The user must never put |\omit| before |\CodeAfter|.

Correction of a bug: the tabular notes |\tabularnotes| were not composed when
present in a block (except a mono-column block).

\subsection*{Changes between versions 5.3 and 5.4}

Key |tabularnote|.

Different behaviour for the mono-column blocks.

\subsection*{Changes between versions 5.2 and 5.3}

Keys |c|, |r| and |l| for the command |\Block|.

It's possible to use the key |draw-first| with |\Ddots| and |\Iddots| to
specify which dotted line will be drawn first (the other lines will be drawn
parallel to that one if parallelization is activated).

\subsection*{Changes between versions 5.1 and 5.2}

The vertical rules specified by \verb+|+ or \verb+||+ in the preamble respect
the blocks.

Key |respect-blocks| for |\rowcolors| (with a \emph{s}) in the |code-before|.

The variable |\g_nicematrix_code_before_tl| is now public.

The key |baseline| may take in as value an expression of the form
\textsl{line-i} to align the |\hline| in the row \textsl{i}.

The key |hvlines-except-corners| may take in as value a list of corners (eg: NW,SE).

\subsection*{Changes between versions 5.0 and 5.1}

The vertical rules specified by \verb+|+ in the preamble are not broken by
|\hline\hline| (and other).

Environment |{NiceTabular*}|

Command |\Vdotsfor| similar to |\Hdotsfor|

The variable |\g_nicematrix_code_after_tl| is now public.

\subsection*{Changes between versions 4.4 and 5.0}

Use of the standard column types |l|, |c| and |r| instead of |L|, |C| and |R|.

It's now possible to use the command |\diagbox| in a |\Block|.

Command |\tabularnote|

\subsection*{Changes between versions 4.3 and 4.4}

New key |hvlines-except-corners| (now deprecated).

\subsection*{Changes between versions 4.2 and 4.3}

The horizontal centering of the content of a |\Block| is correct even when an
instruction such as |!{\qquad}| is used in the preamble of the array.

It's now possible to use the command |\Block| in the ``last row''.

\subsection*{Changes between versions 4.1 and 4.2}

It's now possible to write |\begin{pNiceMatrix}a&b\\c&d\end{pNiceMatrix}^2|
with the expected result.

\subsection*{Changes between versions 4.0 and 4.1}

New keys |cell-space-top-limit| and |cell-space-bottom-limit|

New command |\diagbox|

The key |hvline| don't draw rules in the blocks (commands |\Block|) and in the
virtual blocks corresponding to the dotted lines.

\subsection*{Changes between versions 3.15 and 4.0}

New environment |{NiceTabular}|

Commands to color cells, rows and columns with a perfect result in the \textsc{pdf}.

\subsection*{Changes between versions 3.14 and 3.15}

It's possible to put labels on the dotted lines drawn by |\Ldots|, |\Cdots|,
|\Vdots|, |\Ddots|, |\Iddots|, |\Hdotsfor| and the command |\line| in the
|code-after| with the tokens |_| and |^|.

The option |baseline| is now available in all the environments of
\pkg{nicematrix}. Before, it was available only in |{NiceArray}|.

New keyword |\CodeAfter| (in the environments of \pkg{nicematrix}).

\subsection*{Changes between versions 3.13 and 3.14}

Correction of a bug (question 60761504 on |stackoverflow|).

Better error messages when the user uses |&| or |\\| when |light-syntax| is in
force. 

\subsection*{Changes between versions 3.12 and 3.13}

The behaviour of the command |\rotate| is improved when used in the ``last
row''.

The option |dotted-lines-margin| has been renamed in |xdots/shorten| and the
options |xdots/color| and |xdots/line-style| have been added for a complete
customisation of the dotted lines.

In the environments without preamble (|{NiceMatrix}|, |{pNiceMatrix}|, etc.),
it's possible to use the options |l| (=|L|) or |r| (=|R|) to specify the type
of the columns.

The code of \pkg{nicematrix} no longer uses TikZ but only \textsc{pgf}. By
default, TikZ is \emph{not} loaded by \pkg{nicematrix}.

\subsection*{Changes between versions 3.11 and 3.12}

Command |\rotate| in the cells of the array.

Options |vlines|, |hlines| and |hvlines|.

Option |baseline| pour |{NiceArray}| (not for the other environments).

The name of the TikZ nodes created by the command |\Block| has changed: when
the command has been issued in the cell $i$|-|$j$, the name is
$i$|-|$j$|-block| and, if the creation of the ``medium nodes'' is required, a
node $i$|-|$j$|-block-medium| is created.

If the user tries to use more columns than allowed by its environment, an error
is raised by nicematrix (instead of a low-level error).

The package must be loaded with the option |obsolete-environments| if we want
to use the deprecated environments.

\subsection*{Changes between versions 3.10 and 3.11}

Correction of a bug linked to |first-row| and |last-row|.

\subsection*{Changes between version 3.9 and 3.10} 

New option |light-syntax| (and |end-of-row|).

New option |dotted-lines-margin| for fine tuning of the dotted lines.

\subsection*{Changes between version 3.8 and 3.9} 

New commands |\NiceMatrixLastEnv| and |\OnlyMainNiceMatrix|.

New options |create-medium-nodes| and |create-large-nodes|.

\subsection*{Changes between version 3.7 and 3.8} 

New programmation for the command |\Block| when the block has only one row. 
With this programmation, the vertical rules drawn by the specifier
``\verb+|+'' at the end of the block is actually drawn. In previous versions,
they were not because the block of one row was constructed with
|\multicolumn|. 

An error is raised when an obsolete environment is used.

\subsection*{Changes between version 3.6 and 3.7} 

The four ``corners'' of the matrix are correctly protected against the four
codes: |code-for-first-col|, |code-for-last-col|, |code-for-first-row| and
|code-for-last-row|. 

New command |\pAutoNiceMatrix| and its variants (suggestion of Christophe
Bal).

\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}. 

\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.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.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.

\subsection*{Changes between version 3.1 and 3.2 (and 3.2a)}

Option |small|.

\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|.

The vertical rules in the matrices (drawn by ``\verb+|+'') 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 2.3 and 3.0}

Modification of |\Hdotsfor|. Now |\Hdotsfor| erases the |\vlines| (of ``\verb+|+'')
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 2.2.1 and 2.3}

Compatibility with the column type |S| of \pkg{siunitx}.

Option |hlines|.

\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.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
``\verb+|+'' and the specifier ``|:|'' of \pkg{arydshln}).

\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.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.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 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
package \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.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 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 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.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 versions 1.1 and 1.2}

New environment |{NiceArray}| with column types |L|, |C| and |R|.

\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). 


\cleardoublepage

\phantomsection
\addcontentsline{toc}{section}{Index}

\printindex


\newpage
\tableofcontents

\end{document}

% \endinput
% Local Variables:
% TeX-fold-mode: t
% TeX-fold-preserve-comments: nil
% fill-column: 80
% End: