diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/nicematrix/nicematrix.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/nicematrix/nicematrix.tex | 7484 |
1 files changed, 7484 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/nicematrix/nicematrix.tex b/Master/texmf-dist/doc/latex/nicematrix/nicematrix.tex new file mode 100644 index 00000000000..6cf322afa9e --- /dev/null +++ b/Master/texmf-dist/doc/latex/nicematrix/nicematrix.tex @@ -0,0 +1,7484 @@ +% -*- 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{xltxtra} + +\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 + +% On utilise \MakeShortVerb de shortvrb et pas \DefineShortVerb de fancyvrb +% car on ne veut pas que le contenu des petits éléments en verbatim soit colorié +% en gris +\usepackage{shortvrb} +\MakeShortVerb{\|} + +\usepackage{fancyvrb} +\fvset{commandchars=\~\#\@,formatcom=\color{gray}} + +\usepackage{titlesec} +\titlespacing*{\section}{0pt}{6.5ex plus 1ex minus .2ex}{4.3ex plus .2ex} +\titlespacing*{\subsection}{0pt}{4.5ex plus 1ex minus .2ex}{2ex plus .2ex} + +\def\LetterAt{@} + +\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}}} + +\usepackage{makeidx} +\makeindex + +\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{BVerbatim}[baseline=c,boxwidth=9cm] +$\begin{pmatrix} +\frac{1}{2} & -\frac{1}{2} \\ +\frac{1}{3} & \frac{1}{4} \\ +\end{pmatrix}$ +\end{BVerbatim} +$\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{Verbatim} +\NiceMatrixOptions{~emphase#cell-space-limits = 1pt@} +\end{Verbatim} + +\begin{BVerbatim}[baseline=c,boxwidth=9cm] +$\begin{pNiceMatrix} +\frac12 & -\frac12 \\ +\frac13 & \frac14 \\ +\end{pNiceMatrix}$ +\end{BVerbatim} +\begin{scope} +\NiceMatrixOptions{cell-space-limits = 1pt} +$\begin{pNiceMatrix} +\frac12 & -\frac12 \\ +\frac13 & \frac14 \\ +\end{pNiceMatrix}$ +\end{scope} + + + + + +\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{BVerbatim}[baseline=c,boxwidth=9cm] +$A = \begin{pNiceMatrix}[~emphase#baseline=2@] +\frac{1}{\sqrt{1+p^2}} & p & 1-p \\ +1 & 1 & 1 \\ +1 & p & 1+p +\end{pNiceMatrix}$ +\end{BVerbatim} +$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{BVerbatim}[baseline=c,boxwidth=9cm] +\begin{enumerate} +\item an item +\smallskip +\item \renewcommand{\arraystretch}{1.2} +$\begin{NiceArray}~emphase#[t]@{lcccccc} +\hline +n & 0 & 1 & 2 & 3 & 4 & 5 \\ +u_n & 1 & 2 & 4 & 8 & 16 & 32 +\hline +\end{NiceArray}$ +\end{enumerate} +\end{BVerbatim} +\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{BVerbatim}[baseline=c,boxwidth=9cm] +\begin{enumerate} +\item an item +\smallskip +\item +$\begin{NiceArray}[t]{lcccccc} +~emphase#\toprule@ +n & 0 & 1 & 2 & 3 & 4 & 5 \\ +~emphase#\midrule@ +u_n & 1 & 2 & 4 & 8 & 16 & 32 +~emphase#\bottomrule@ +\end{NiceArray}$ +\end{enumerate} +\end{BVerbatim} +\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{BVerbatim}[baseline=c,boxwidth=9cm] +$A=\begin{pNiceArray}{cc|cc}~emphase#[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{BVerbatim} +\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 array with +two 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. It's possible to use +|\\| in that content to have a content on several lines. 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{BVerbatim}[baseline=c,boxwidth=10.6cm] +$\begin{bNiceArray}{cw{c}{1cm}c|c}[margin] +~emphase#\Block{3-3}{A}@ & & & 0 \\ +& & & \Vdots \\ +& & & 0 \\ +\hline +0 & \Cdots& 0 & 0 +\end{bNiceArray}$ +\end{BVerbatim} +$\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.} + +\medskip +\begin{BVerbatim}[baseline=c,boxwidth=10.6cm] +$\begin{bNiceArray}{cw{c}{1cm}c|c}[margin] +\Block{3-3}~emphase#<\Large>@{A} & & & 0 \\ +0 & & & \Vdots \\ +& & & 0 \\ +\hline +0 & \Cdots& 0 & 0 +\end{bNiceArray}$ +\end{BVerbatim} +\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}. The available keys are as +follows: +\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{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 +(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.}); +\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). For +examples, cf. p.~\pageref{tikz-key-examples}; +\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{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{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-row and the blocks mono-column 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{BVerbatim} +\begin{NiceTabular}{cw{c}{2cm}w{c}{3cm}c} +rose & tulip & daisy & dahlia \\ +violet +& ~emphase#\Block[draw=red,fill=[RGB]{204,204,255},rounded-corners]{2-2}@ + ~emphase#{\LARGE Some beautiful flowers}@ + & & marigold \\ +iris & & & lis \\ +arum & periwinkle & forget-me-not & hyacinth +\end{NiceTabular} +\end{BVerbatim} + +\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 (but 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{BVerbatim}[baseline=c,boxwidth=12cm] +\begin{NiceTabular}{~LetterAt{}>{\bfseries}lr~LetterAt{}} \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{BVerbatim} +\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). + +\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 |colortbl-like| is +used).} + +\item It's possible to draw one or several borders of the cell with the key |borders|. +\end{itemize} + +\bigskip +\begin{BVerbatim}[baseline=c,boxwidth=10cm] +\begin{NiceTabular}{cc} +\toprule +Writer & ~emphase#\Block[l]{}{year\\ of birth}@ \\ +\midrule +Hugo & 1802 \\ +Balzac & 1799 \\ +\bottomrule +\end{NiceTabular} +\end{BVerbatim} +\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 |l|, |c| and |r| for the horizontal +position of its content. + +\medskip +\begin{BVerbatim}[baseline=c,boxwidth=10.6cm] +$\begin{bNiceArray}{cw{c}{1cm}c|c}[margin] +\Block~emphase#[r]@{3-3}<\LARGE>{A} & & & 0 \\ +& & & \Vdots \\ +& & & 0 \\ +\hline +0 & \Cdots& 0 & 0 +\end{bNiceArray}$ +\end{BVerbatim} +$\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} +\fvset{commandchars=\~\#\+} +\begin{BVerbatim} +\begin{NiceTabular}{@{}c!{\qquad}ccc~emphase#!{\qquad}+ccc@{}} +\toprule +Rank & ~emphase#\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{BVerbatim} +\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 |L|, |R| and |C| of the +command |\Block|. + +\medskip +Here is the same example with the key |C| for the first block. + +\medskip +\begin{center} +\fvset{commandchars=\~\#\+} +\begin{BVerbatim} +\begin{NiceTabular}{@{}c!{\qquad}ccc~emphase#!{\qquad}+ccc@{}} +\toprule +Rank & ~emphase#\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{BVerbatim} +\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} + + +\subsection{Vertical position of the content of the block} + + +For the vertical position, the command |\Blocks| accepts the keys +|v-center|\footnote{That key could not have been named |c| since the key |c| +is used for the horizontal alignement.}, +|t|, |b|, |T| and |B|. + + +\begin{itemize} +\item \index{v-center (key of \texttt{\textbackslash Block})} +With the key |v-center|, the content of the block is vertically centered. +\item With the key |t|, the baseline of the content of the block is aligned +With the basline of the first row concerned by the block). +\item with the key |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 |T|, the content of the block is set upwards. + +\colorbox{yellow!50}{\textbf{Modification 6.18}}\enskip 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). + +\item With the key |B|, the content of the block is set downwards. +\end{itemize} + +When no key is given, the key |v-center| applies (excepted 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{BVerbatim}[baseline=c,boxwidth=10cm] +\begin{NiceTabular}{ccc} +\Block[fill=red!10,~emphase#t@,l]{4-2}{two\\lines} + & & \Huge Un\\ + & & deux \\ + & & trois \\ + & & \Huge quatre \\ +text & text \\ +\end{NiceTabular} +\end{BVerbatim} +\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{BVerbatim}[baseline=c,boxwidth=10cm] +\begin{NiceTabular}{ccc} +\Block[fill=red!10,~emphase#b@,r]{4-2}{two\\lines} + & & \Huge Un\\ + & & deux \\ + & & trois \\ + & & \Huge quatre \\ +text & text \\ +\end{NiceTabular} +\end{BVerbatim} +\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{BVerbatim}[baseline=c,boxwidth=10cm] +\begin{NiceTabular}{ccc} +\Block[fill=red!10,~emphase#T@,l]{4-2}{two\\lines} + & & \Huge Un\\ + & & deux \\ + & & trois \\ + & & \Huge quatre \\ +text & text \\ +\end{NiceTabular} +\end{BVerbatim} +\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{BVerbatim}[baseline=c,boxwidth=10cm] +\begin{NiceTabular}{ccc} +\Block[fill=red!10,~emphase#B@,r]{4-2}{two\\lines} + & & \Huge Un\\ + & & deux \\ + & & trois \\ + & & \Huge quatre \\ +text & text \\ +\end{NiceTabular} +\end{BVerbatim} +\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} + +\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} (excepted |\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{BVerbatim}[baseline=c,boxwidth=10cm] +\begin{NiceTabular}{|c|c|} \hline +First & Second \\ ~emphase#\hline\hline@ +Peter \\ \hline +Mary & George\\ \hline +\end{NiceTabular} +\end{BVerbatim} +\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{BVerbatim}[baseline=c,boxwidth=10.5cm] +$\begin{NiceArray}{~emphase#|cccc|@} \toprule +a & b & c & d \\ \midrule +1 & 2 & 3 & 4 \\ +1 & 2 & 3 & 4 \\ \bottomrule +\end{NiceArray}$ +\end{BVerbatim} +$\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{BVerbatim}[baseline=c,boxwidth=10cm] +\setlength{\arrayrulewidth}{2pt} +\begin{tabular}{cccc} \hline +A&B&C&D \\ ~emphase#\cline{2-2}@ +A&B&C&D \\ \hline +\end{tabular} +\end{BVerbatim} +\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{BVerbatim}[baseline=c,boxwidth=10cm] +\setlength{\arrayrulewidth}{2pt} +\begin{NiceTabular}{cccc} \hline +A&B&C&D \\ ~emphase#\cline{2}@ +A&B&C&D \\ \hline +\end{NiceTabular} +\end{BVerbatim} +\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 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|. The environments of \pkg{nicematrix} also +provide a key |rules/color| to fix the color of the rules in the current +environment. This key sets the value locally (whereas |\arrayrulecolor| acts +globally!). + +\medskip +\begin{scope} +\hfuzz=10cm +\begin{BVerbatim}[baseline=c,boxwidth=9.5cm] +\begin{NiceTabular}{|ccc|}[~emphase#rules/color=[gray]{0.9},rules/width=1pt@] +\hline +rose & tulipe & lys \\ +arum & iris & violette \\ +muguet & dahlia & souci \\ +\hline +\end{NiceTabular} +\end{BVerbatim} +\begin{NiceTabular}{|ccc|}[rules/color=[gray]{0.9},rules/width=1pt] +\hline +rose & tulipe & lys \\ +arum & iris & violette \\ +muguet & dahlia & souci \\ +\hline +\end{NiceTabular} +\end{scope} + + + +\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 explains the difference between the standard +command |\hline| and the command |\Hline| provided by \pkg{nicematrix}. + +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}. + +\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{BVerbatim}[baseline=c,boxwidth=10.6cm] +$\begin{pNiceMatrix}[~emphase#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{BVerbatim} +$\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}$ + + + +\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{Verbatim} +\setlength{\arrayrulewidth}{1pt} +\begin{NiceTabular}{cccc}[~emphase#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{Verbatim} + +\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}{*{6}{c}}[cell-space-top-limit=3pt] +\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{BVerbatim}[boxwidth=11cm,baseline=c] +\NiceMatrixOptions{cell-space-top-limit=3pt} +\begin{NiceTabular}{*{6}{c}}[~emphase#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{BVerbatim} +\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{BVerbatim}[boxwidth=11cm,baseline=c] +\NiceMatrixOptions{cell-space-top-limit=3pt} +\begin{NiceTabular}{*{6}{c}}[~emphase#corners=NE@,hvlines] +1\\ +1&1\\ +1&2&1\\ +1&3&3&1\\ +1&4&6&4&1\\ + & & & & &1 +\end{NiceTabular} +\end{BVerbatim} +\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}). + +\subsection{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{BVerbatim}[baseline=c,boxwidth=10cm] +$\begin{NiceArray}{*{5}{c}}[hvlines] +~emphase#\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{BVerbatim} +$\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|. + + + + +\subsection{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|. + +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|). +\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{Verbatim} +\begin{NiceTabular}{lcIcIc}~emphase#[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{Verbatim} + + +\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 +\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{BVerbatim}[boxwidth=9cm,baseline=c] +\NiceMatrixOptions + { + custom-line = + { + letter = I , + ~emphase#tikz = dotted@ , + ~emphase#total-width = \pgflinewidth@ + } + } + +\begin{NiceTabular}{cIcIc} +one & two & three \\ +four & five & six \\ +seven & eight & nine +\end{NiceTabular} +\end{BVerbatim} +\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 |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 |\hdottedline| and +|\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{BVerbatim} + +\NiceMatrixOptions % ~textsl#present in nicematrix.sty@ + { + custom-line = + { + letter = : , + command = hdottedline , + ccommand = cdottedline , + ~emphase#dotted@ + } + } +\end{BVerbatim} + +Thus, it's possible to use the commands |\hdottedline| and |\cdottedline |to +draw horizontal dotted rules. + +\medskip +\begin{BVerbatim}[baseline=c,boxwidth=9.5cm] +\begin{pNiceMatrix} +1 & 2 & 3 & 4 & 5 \\ +~emphase#\hdottedline@ +6 & 7 & 8 & 9 & 10 \\ +~emphase#\cdottedline{1,4-5}@ +11 & 12 & 13 & 14 & 15 +\end{pNiceMatrix} +\end{BVerbatim} +$\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{BVerbatim}[baseline=c,boxwidth=9.5cm] +\left(\begin{NiceArray}{cccc~emphase#:@c} +1 & 2 & 3 & 4 & 5 \\ +6 & 7 & 8 & 9 & 10 \\ +11 & 12 & 13 & 14 & 15 +\end{NiceArray}\right) +\end{BVerbatim} +$\left(\begin{NiceArray}{cccc:c} +1 & 2 & 3 & 4 & 5 \\ +6 & 7 & 8 & 9 & 10 \\ +11 & 12 & 13 & 14 & 15 +\end{NiceArray}\right)$ + +\end{itemize} + +\index{custom-line|)} +\index{Rules@\textbf{Rules in the tabulars}|)} + + +\section{The color 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 +Since the package \pkg{nicematrix} is based on \pkg{array}, it's possible to +use \pkg{colortbl} with \pkg{nicematrix}. + +\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{Verbatim} +\begin{pNiceArray}{~textsl#preamble@} +~emphase#\CodeBefore [~textsl#options@]@ + ~textsl#instructions of the code-before@ +~emphase#\Body@ + ~textsl#contents of the environment@ +\end{pNiceArray} +\end{Verbatim} + +\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} (command of + \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)}} + +\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.)} +\colorbox{yellow!50}{\textbf{New 6.18}}\par\nobreak +a specification of opacity f the form \texttt{opacity = \textsl{value}}. +\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{BVerbatim}[boxwidth=10cm,baseline=c] +\begin{NiceTabular}{ccc}[hvlines] +\CodeBefore + ~emphase#\cellcolor[HTML]{FFFF88}{3-1,2-2,-3}@ +\Body +a & b & c \\ +e & f & g \\ +h & i & j \\ +\end{NiceTabular} +\end{BVerbatim} +\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{BVerbatim}[boxwidth=10cm,baseline=c] +\begin{NiceTabular}{ccc}[hvlines] +\CodeBefore + ~emphase#\rectanglecolor{blue!15}{2-2}{3-3}@ +\Body +a & b & c \\ +e & f & g \\ +h & i & j \\ +\end{NiceTabular} +\end{BVerbatim} +\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 (excepted 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{BVerbatim}[baseline=c,boxwidth=9cm] +$\begin{pNiceMatrix}[r,margin] +\CodeBefore + ~emphase#\chessboardcolors{red!15}{blue!15}@ +\Body +1 & -1 & 1 \\ +-1 & 1 & -1 \\ +1 & -1 & 1 +\end{pNiceMatrix}$ +\end{BVerbatim} +$\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{BVerbatim}[boxwidth=9cm,baseline=c] +$\begin{NiceArray}{lll}[hvlines] +\CodeBefore + ~emphase#\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{BVerbatim} +$\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. + +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 |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 |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 |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{BVerbatim}[baseline=c,boxwidth=10cm] +\begin{NiceTabular}{clr}[hvlines] +\CodeBefore + ~emphase#\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{BVerbatim} +\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{BVerbatim}[baseline=c,boxwidth=10cm] +\begin{NiceTabular}{lr}[hvlines] +\CodeBefore + ~emphase#\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{BVerbatim} +\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{BVerbatim}[boxwidth=10cm,baseline=c] +\begin{NiceTabular}{c} +\CodeBefore + ~emphase#\rowlistcolors{1}{red!15,blue!15,green!15}@ +\Body +Peter \\ +James \\ +Abigail \\ +Elisabeth \\ +Claudius \\ +Jane \\ +Alexandra \\ +\end{NiceTabular} +\end{BVerbatim} +\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, 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{BVerbatim}[boxwidth=12.5cm,baseline=c] +\begin{NiceTabular}{c} +\CodeBefore + ~emphase#\definecolorseries{BlueWhite}{rgb}{last}{blue}{white}@ + ~emphase#\resetcolorseries{\value{iRow}}{BlueWhite}@ + ~emphase#\rowlistcolors{1}{BlueWhite!!+}@ +\Body +Peter \\ +James \\ +Abigail \\ +Elisabeth \\ +Claudius \\ +Jane \\ +Alexandra \\ +\end{NiceTabular} +\end{BVerbatim} +\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{scope} +\hfuzz=11cm +\begin{BVerbatim}[boxwidth=9cm,baseline=c] +\begin{NiceTabular}{cccccc}[~emphase#corners=NE@,margin,hvlines,first-row,first-col] +\CodeBefore + ~emphase#\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{BVerbatim} +\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} +\end{scope} + + +\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{BVerbatim}[baseline=c,boxwidth=8.5cm] +\begin{NiceTabular}[c]{lSSSS} +\CodeBefore + \rowcolor{red!15}{1-2} + \rowcolors{3}{blue!15}{} +\Body +~emphase#\toprule@ +\Block{2-1}{Product} & +\Block{1-3}{dimensions (cm)} & & & +\Block{2-1}{\rotate Price} \\ +~emphase#\cmidrule(rl){2-4}@ + & L & l & h \\ +~emphase#\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 \\ +~emphase#\bottomrule@ +\end{NiceTabular} +\end{BVerbatim} +\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 with the syntax of colortbl} + +\index{colortbl-like} +\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 |colortbl-like| in the +current environment.\footnote{Up to now, this key is \emph{not} available in |\NiceMatrixOptions|.} + +There are three commands available (they are inspired by \pkg{colortbl} but +are \emph{independent} of \pkg{colortbl}): +\begin{itemize} +\item |\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 |\rowcolor| which must be used in a cell and which colorizes the end of +the row; +\item |\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). +\end{itemize} + +\smallskip +\begin{Verbatim} +\NewDocumentCommand { \Blue } { } { ~emphase#\columncolor{blue!15}@ } +\begin{NiceTabular}[colortbl-like]{>{\Blue}c>{\Blue}cc} +\toprule +~emphase#\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{Verbatim} + + +\begin{center} +\NewDocumentCommand { \Blue } { } { \columncolor{blue!15} } +\begin{NiceTabular}[colortbl-like]{>{\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} + +\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 |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 |cell-space-top-limit|, |cell-space-bottom-limit| and +|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 |rowcolor| sets +the color of the background and the key |color| sets the +color of the text.\footnote{The key |color| uses the command +|\color| but inserts also an instruction |\leavevmode| before. This +instruction prevents a extra vertical space in the cells which belong to +columns of type |p|, |b|, |m|, |X| and |V| (which start in +vertical mode).} +\item \index{bold (key of \texttt{\textbackslash RowStyle})} The key |bold| +enforces bold characters for the cells of the row, both in math and text mode. +\end{itemize} + +\medskip +\begin{BVerbatim}[boxwidth=12cm,baseline=c] +\begin{NiceTabular}{cccc} +\hline +~emphase#\RowStyle[cell-space-limits=3pt]{\rotate}@ +first & second & third & fourth \\ +~emphase#\RowStyle[nb-rows=2,rowcolor=blue!50,color=white]{\sffamily}@ +1 & 2 & 3 & 4 \\ +I & II & III & IV +\end{NiceTabular} +\end{BVerbatim} +\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{BVerbatim}[baseline=c,boxwidth=9cm] +\begin{NiceTabular}{~emphase#W{c}{2cm}@cc}[hvlines] +Paris & New York & Madrid \\ +Berlin & London & Roma \\ +Rio & Tokyo & Oslo +\end{NiceTabular} +\end{BVerbatim} +\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 (excepted the potential exterior columns: cf. p.~\pageref{exterior}) directly +with the key |columns-width|. + +\medskip +\begin{BVerbatim}[baseline=c,boxwidth=10cm] +$\begin{pNiceMatrix}[~emphase#columns-width = 1cm@] +1 & 12 & -123 \\ +12 & 0 & 0 \\ +4 & 1 & 2 +\end{pNiceMatrix}$ +\end{BVerbatim} +$\begin{pNiceMatrix}[columns-width = 1cm] +1 & 12 & -123 \\ +12 & 0 & 0 \\ +4 & 1 & 2 +\end{pNiceMatrix}$ + +\medskip +Note that the space inserted between two columns (equal to 2 |\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{BVerbatim}[baseline=c,boxwidth=10cm] +$\begin{pNiceMatrix}[~emphase#columns-width = auto@] +1 & 12 & -123 \\ +12 & 0 & 0 \\ +4 & 1 & 2 +\end{pNiceMatrix}$ +\end{BVerbatim} +$\begin{pNiceMatrix}[columns-width = auto] +1 & 12 & -123 \\ +12 & 0 & 0 \\ +4 & 1 & 2 +\end{pNiceMatrix}$ + +\bigskip +Without surprise, it's possible to fix the minimal width of the columns of all +the arrays of a current scope with the command +|\NiceMatrixOptions|.\par\nobreak + +\medskip +\begin{BVerbatim}[baseline=c,boxwidth=8.5cm] +~emphase#\NiceMatrixOptions{columns-width=10mm}@ +$\begin{pNiceMatrix} +a & b \\ c & d +\end{pNiceMatrix} += +\begin{pNiceMatrix} +1 & 1245 \\ 345 & 2 +\end{pNiceMatrix}$ +\end{BVerbatim} +\begin{scope} +\NiceMatrixOptions{columns-width=10mm} +$\begin{pNiceMatrix} +a & b \\ +c & d +\end{pNiceMatrix} += +\begin{pNiceMatrix} +1 & 1245 \\ +345 & 2 +\end{pNiceMatrix}$ +\end{scope} + + +\bigskip +\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{BVerbatim}[baseline=c,boxwidth=8.5cm] +~emphase#\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}$ +~emphase#\end{NiceMatrixBlock}@ +\end{BVerbatim} +\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.\footnote{If \pkg{tabularx} is loaded, one +must use |{NiceTabularX}| (and not |{NiceTabular}|) in order to use the +columns |X| (this point comes from a conflict in the definitions of the +specifier |X|).} + +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{Verbatim} +\begin{NiceTabular}~emphase#[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{Verbatim} + +\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{BVerbatim}[baseline=c,boxwidth=6cm] +\fbox{% +\begin{~emphase#varwidth@}{8cm} +\begin{itemize} +\item first item +\item second item +\end{itemize} +\end{~emphase#varwidth@}} +\end{BVerbatim} +\fbox{\begin{varwidth}{8cm} +\begin{itemize} +\item first item +\item second item +\end{itemize} +\end{varwidth}} + +\bigskip +\begin{BVerbatim}[baseline=c,boxwidth=6cm] +\fbox{% +\begin{~emphase#minipage@}{8cm} +\begin{itemize} +\item first item +\item second item +\end{itemize} +\end{~emphase#minipage@}} +\end{BVerbatim} +\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{Verbatim} +\begin{NiceTabular}[corners=NW,hvlines]{~emphase#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{Verbatim} + +\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{Verbatim} +$\begin{pNiceMatrix}[~emphase#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{Verbatim} + +\[\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| (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{Verbatim} +\NiceMatrixOptions{~emphase#code-for-first-row@ = \color{red}, + ~emphase#code-for-first-col@ = \color{blue}, + ~emphase#code-for-last-row@ = \color{green}, + ~emphase#code-for-last-col@ = \color{magenta}} +$\begin{pNiceArray}{cc|cc}[first-row,last-row=5,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 \\ +\hline + & 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{pNiceArray}$ +\end{Verbatim} + +\begin{scope} +\NiceMatrixOptions{code-for-first-row = \color{red}, + code-for-first-col = \color{blue}, + code-for-last-row = \color{green}, + code-for-last-col = \color{magenta}} +\begin{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'' (excepted 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| 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{BVerbatim}[baseline=c,boxwidth=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{BVerbatim} +$\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{BVerbatim}[baseline=c,boxwidth=10cm] +\begin{bNiceMatrix} +0 & \Cdots & 0 \\ +\Vdots & & \Vdots \\ +0 & \Cdots & 0 +\end{bNiceMatrix} +\end{BVerbatim} +$\begin{bNiceMatrix} +0 & \Cdots & 0 \\ +\Vdots & & \Vdots \\ +0 & \Cdots & 0 +\end{bNiceMatrix}$ + +\bigskip +However, one may want a larger matrix. Usually, in such a case, the users of +LaTeX add a new row and a new column. It's possible to use the same method +with \pkg{nicematrix}:\par\nobreak + +\bigskip +\begin{BVerbatim}[baseline=c,boxwidth=10cm] +\begin{bNiceMatrix} +0 & \Cdots & \Cdots & 0 \\ +\Vdots & & & \Vdots \\ +\Vdots & & & \Vdots \\ +0 & \Cdots & \Cdots & 0 +\end{bNiceMatrix} +\end{BVerbatim} +$\begin{bNiceMatrix} +0 & \Cdots & \Cdots & 0 \\ +\Vdots & & & \Vdots \\ +\Vdots & & & \Vdots \\ +0 & \Cdots & \Cdots & 0 +\end{bNiceMatrix}$ + +\bigskip +In the first column of this 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{BVerbatim}[baseline=c,boxwidth=10cm] +\begin{bNiceMatrix} +0 & \Cdots & & 0 \\ +\Vdots & & & \\ + & & & \Vdots \\ +0 & & \Cdots & 0 +\end{bNiceMatrix} +\end{BVerbatim} +$\begin{bNiceMatrix} +0 & \Cdots & & 0 \\ +\Vdots & & & \\ + & & & \Vdots \\ +0 & & \Cdots & 0 +\end{bNiceMatrix}$ + +\bigskip +There are also other means to change the size of the matrix. Someone might +want to use the optional argument of the command~|\\| for the vertical +dimension and a command~|\hspace*| in a cell for the horizontal +dimension.\footnote{In \pkg{nicematrix}, one should use |\hspace*| and not +|\hspace| for such an usage because \pkg{nicematrix} loads \pkg{array}. One +may also remark that it's possible to fix the width of a column by using the +environment |{NiceArray}| (or one of its variants) with a column of type~|w| +or~|W|: see p.~\pageref{width}} + +\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{BVerbatim}[baseline=c,boxwidth=10cm] +\begin{bNiceMatrix} +0 & \Cdots & ~emphase#\Hspace*{1cm}@ & 0 \\ +\Vdots & & & \Vdots \\~emphase#[1cm]@ +0 & \Cdots & & 0 +\end{bNiceMatrix} +\end{BVerbatim} +$\begin{bNiceMatrix} +0 & \Cdots & \Hspace*{1cm} & 0 \\ +\Vdots & & & \Vdots \\[1cm] +0 & \Cdots & & 0 +\end{bNiceMatrix}$ + +\subsection{The option nullify-dots} + +\index{nullify-dots} + +Consider the following matrix composed classicaly with the environment +|{pmatrix}| of \pkg{amsmath}.\par\nobreak + +\medskip +\begin{BVerbatim}[baseline=c,boxwidth=10cm] +$A = \begin{pmatrix} +h & i & j & k & l & m \\ +x & & & & & x +\end{pmatrix}$ +\end{BVerbatim} +$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{BVerbatim}[baseline=c,boxwidth=10cm] +$B = \begin{pmatrix} +h & i & j & k & l & m \\ +x & \ldots & \ldots & \ldots & \ldots & x +\end{pmatrix}$ +\end{BVerbatim} +$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{BVerbatim}[baseline=c,boxwidth=10cm] +$C = \begin{pNiceMatrix} +h & i & j & k & l & m \\ +x & \Ldots & \Ldots & \Ldots & \Ldots & x +\end{pNiceMatrix}$ +\end{BVerbatim} +$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{BVerbatim}[baseline=c,boxwidth=10cm] +$D = \begin{pNiceMatrix}[~emphase#nullify-dots@] +h & i & j & k & l & m \\ +x & \Ldots & & & & x +\end{pNiceMatrix}$ +\end{BVerbatim} +$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. + + + +\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{BVerbatim}[baseline=c,boxwidth=7cm] +$\begin{pNiceMatrix} +1 & 2 & 3 & 4 & 5 \\ +1 & ~emphase#\Hdotsfor{3}@ & 5 \\ +1 & 2 & 3 & 4 & 5 \\ +1 & 2 & 3 & 4 & 5 +\end{pNiceMatrix}$ +\end{BVerbatim} +$\begin{pNiceMatrix} +1 & 2 & 3 & 4 & 5 \\ +1 & \Hdotsfor{3} & 5 \\ +1 & 2 & 3 & 4 & 5 \\ +1 & 2 & 3 & 4 & 5 +\end{pNiceMatrix}$ + +\bigskip +However, if these cells are empty, the dotted line extends only in the cells +specified by the argument of |\Hdotsfor| (by design). + +\medskip +\begin{BVerbatim}[baseline=c,boxwidth=7cm] +$\begin{pNiceMatrix} +1 & 2 & 3 & 4 & 5 \\ + & ~emphase#\Hdotsfor{3}@ \\ +1 & 2 & 3 & 4 & 5 \\ +1 & 2 & 3 & 4 & 5 +\end{pNiceMatrix}$ +\end{BVerbatim} +$\begin{pNiceMatrix} +1 & 2 & 3 & 4 & 5 \\ + & \Hdotsfor{3} \\ +1 & 2 & 3 & 4 & 5 \\ +1 & 2 & 3 & 4 & 5 +\end{pNiceMatrix}$ + +\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|). + +\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|: + +\begin{Verbatim}[formatcom=\small\color{gray}] +\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 + & ~emphase#\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 & ~emphase#\Vdotsfor{1}@ & & \Ddots & & ~emphase#\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 + & ~emphase#\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{Verbatim} + + +\[\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 + +\bigskip +\begin{scope} +\NiceMatrixOptions{renew-dots,renew-matrix} +\begin{BVerbatim}[baseline=c,boxwidth=10cm] +~emphase#\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{BVerbatim} +$\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| and |\Hdotsfor| +(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|. + +\begin{BVerbatim}[baseline=c,boxwidth=10cm] +$\begin{bNiceMatrix} +1 & \hspace*{1cm} & 0 \\[8mm] + & ~emphase#\Ddots^{n \text{ times}}@ & \\ +0 & & 1 +\end{bNiceMatrix}$ +\end{BVerbatim} +$\begin{bNiceMatrix} +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)} + +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 |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/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 +\textbf{The option xdots/color}\par\nobreak + +\smallskip +The option |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 +\textbf{The option xdots/radius}\par\nobreak + +The option |radius| fixes the radius of the dots. The initial value is 0.53~pt. + +\bigskip +\textbf{The option xdots/shorten}\par\nobreak + +\smallskip +The keys |xdots/shorten-start| and |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). + +\bigskip +\textbf{The option xdots/inter}\par\nobreak + +\smallskip +The option |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 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 Tizk 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{BVerbatim}[baseline=c] +$\begin{pNiceMatrix}[nullify-dots,~emphase#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{BVerbatim} + + +\[\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{BVerbatim}[baseline=c,boxwidth=10.6cm] +$\begin{bNiceMatrix}[margin,~emphase#hvlines@] +\Block{3-3}<\LARGE>{A} & & & 0 \\ +& \hspace*{1cm} & & \Vdots \\ +& & & 0 \\ +0 & \Cdots& 0 & 0 +\end{bNiceMatrix}$ +\end{BVerbatim} +$\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)} + +\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{BVerbatim} +$\begin{NiceArray}{~emphase#\left\lgroup@ ccc~emphase#\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{BVerbatim} + +\[\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 |\{| (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 +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{BVerbatim} +$\begin{pNiceArray}{~emphase#(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{BVerbatim} + +\[\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|. 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 and |sub-matrix| (linked to the +command |\SubMatrix|) 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| and |\UnderBrace|. 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{BVerbatim}[baseline=c,boxwidth=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 +~emphase#\CodeAfter \line{2-2}{3-3}@ +\end{pNiceMatrix} +\end{BVerbatim} +\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{BVerbatim} +\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 +~emphase#\CodeAfter \line[shorten=6pt]{1-5}{4-7}@ +\end{bNiceMatrix} +\end{BVerbatim} +\[\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{scope} +\hfuzz=15cm +\fvset{commandchars=\~\#\+}% +\begin{BVerbatim}[boxwidth=11cm,baseline=c] +\[\begin{NiceArray}{ccc~emphase#@{\hspace{1.5em}}+c}[cell-space-limits=2pt,~emphase#margin+] + 1 & 1 & 1 & x \\ +\dfrac{1}{4} & \dfrac{1}{2} & \dfrac{1}{4} & y \\ + 1 & 2 & 3 & z +\CodeAfter + ~emphase#\SubMatrix({1-1}{3-3})+ + ~emphase#\SubMatrix({1-4}{3-4})+ +\end{NiceArray}\] +\end{BVerbatim} +\end{scope} +$\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{BVerbatim}[boxwidth=11cm,baseline=c] +$\begin{NiceArray}{~emphase#(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{BVerbatim} +\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{BVerbatim}[boxwidth=11cm,baseline=c] +$\begin{bNiceMatrix}[right-margin=1em] +1 & 1 & 1 \\ +1 & a & b \\ +1 & c & d +\CodeAfter + ~emphase#\SubMatrix[{2-2}{3-3}]^{T}@ +\end{bNiceMatrix}$ +\end{BVerbatim} +$\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{scope} +\hfuzz=12cm +\fvset{commandchars=\~\#\!}% +\begin{BVerbatim}[baseline=c,boxwidth=11cm] +$\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}$ +\end{BVerbatim} +\end{scope} +$\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{scope} +\hfuzz=12cm +\fvset{commandchars=\~\#\!}% +\begin{BVerbatim}[baseline=c,boxwidth=11cm] +$\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})[~emphase#slim!] + \SubMatrix({3-1}{4-2}) + \SubMatrix({3-3}{4-3}) +\end{NiceArray}$ +\end{BVerbatim} +\end{scope} +$\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{BVerbatim}[baseline=c] +\begin{NiceTabular}{~@{}ll~@{}} +\toprule +Part A & the first part \\ +\Block{2-1}{Part B} & a first sub-part \\ + & a second sub-part \\ +\bottomrule +\CodeAfter + ~emphase#\SubMatrix{\{}{2-2}{3-2}{.}@ +\end{NiceTabular} +\end{BVerbatim} +\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} +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 |i-j| and \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{scope} +\fvset{commandchars=\~\#\!}% +\begin{Verbatim} +$\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 + ~emphase#\NewDocumentCommand{\MyDraw}{}{\tikz \draw [blue] (2-|1) -| (3-|2) -| (4-|3) ;}! + \SubMatrix({1-5}{3-7})[~emphase#code = \MyDraw!] + \SubMatrix({4-1}{6-3})[~emphase#code = \MyDraw!] + \SubMatrix({4-5}{6-7})[~emphase#code = \MyDraw!] +\end{NiceArray}$ +\end{Verbatim} +\end{scope} + + +\[\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{BVerbatim}[baseline=c,boxwidth=9cm] +\begin{pNiceMatrix} +1 & 2 & 3 & 4 & 5 & 6 \\ +11 & 12 & 13 & 14 & 15 & 16 \\ +\CodeAfter + ~emphase#\OverBrace{1-1}{2-3}{A}@ + ~emphase#\OverBrace{1-4}{2-6}{B}@ +\end{pNiceMatrix} +\end{BVerbatim} +$\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.\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 |left-shorten| and |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 |shorten|, which is the conjunction of the keys |left-shorten| and +|right-shorten|; + +\item |yshift|, which shifts vertically the brace (and its label); + +\item |color|, which sets the color of the brace (and its label). +\end{itemize} + +\bigskip +\begin{BVerbatim}[baseline=c,boxwidth=9cm] +\begin{pNiceMatrix} +1 & 2 & 3 & 4 & 5 & 6 \\ +11 & 12 & 13 & 14 & 15 & 16 \\ +\CodeAfter + \OverBrace~emphase#[shorten,yshift=3pt]@{1-1}{2-3}{A} + \OverBrace~emphase#[shorten,yshift=3pt]@{1-4}{2-6}{B} +\end{pNiceMatrix} +\end{BVerbatim} +$\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}$ + +\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 (excepted 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 (excepted 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{scope} +\fvset{commandchars=\~\#\!} +\begin{Verbatim} +\begin{NiceTabular}{@{}llr@{}} +\toprule \RowStyle{\bfseries} +Last name & First name & Birth day \\ +\midrule +Achard\tabularnote{~emphase#Achard is an old family of the Poitou.!} +& Jacques & 5 juin 1962 \\ +Lefebvre\tabularnote{~emphase#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{Verbatim} +\end{scope} + +\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. + +\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 \colorbox{yellow!50}{\textbf{New 6.19}} 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} +\fvset{commandchars=\~\#\!} +\begin{Verbatim}[formatcom=\small\color{gray}] +\begin{table} +\centering +\NiceMatrixOptions{caption-above} +\begin{NiceTabular}{@{}llc@{} + [ + caption = A tabular whose caption has been specified by the key + \texttt{caption}~emphase#\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~emphase#\tabularnote{Considered as the first nurse of history}!% +~emphase#\tabularnote{Nicknamed ``the Lady with the Lamp''.}! +& Florence~emphase#\tabularnote{This note is shared by two references.}! & 90 \\ +Schoelcher & Victor & 89~emphase#\tabularnote{The label of the note is overlapping.}!\\ +Touchet & Marie~emphase#\tabularnote{This note is shared by two references.}! & 89 \\ +Wallis & John & 87 \\ +\bottomrule +\end{NiceTabular} +\end{table} +\end{Verbatim} +\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 (with a version of +LaTeX at least 2020/10/01). +\begin{Verbatim}[commandchars=\~\#\!] +\makeatletter +\AddToHook{env/threeparttable/begin} + {\TPT@hookin{NiceTabular}\TPT@hookin{NiceTabular*}\TPT@hookin{NiceTabularX}} +\makeatother +\end{Verbatim} + +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 of \{NiceTabular\}} + +\label{tabular-rounded-corners} +\index{rounded-corners!key of \texttt{\{NiceTabular\}}} +\index{Corners (rounded ---)!for a tabular} + +\colorbox{yellow!50}{\textbf{New 6.18}}\par\nobreak + +\smallskip +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 environment |{NiceTabular}| provides a key |rounded-corners| which specify +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 |colortbl-like| is +used) will respect those rounded corners. + +\item When the key |hvlines| is used, the exterior rules will be drawn with +rounded corners. +\end{itemize} + +\bigskip +\begin{BVerbatim}[baseline=c,boxwidth=9cm] +\begin{NiceTabular} + [hvlines,~emphase#rounded-corners@] + {ccc} +\CodeBefore + \rowcolor{red!15}{1} +\Body +Last name & First name & Profession \\ +Arvy & Jacques & Physicist \\ +Jalon & Amandine & Physicist +\end{NiceTabular} +\end{BVerbatim} +\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{BVerbatim}[baseline=c,boxwidth=10.6cm] +\begin{NiceTabular}{ccc}[hvlines,cell-space-limits=3pt] + \Block{2-2}{} & & test \\ + & & blabla \\ + & some text & nothing +~emphase#\CodeAfter \ShowCellNames@ +\end{NiceTabular} +\end{BVerbatim} +\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{BVerbatim}[baseline = c, boxwidth = 11cm] +$\begin{pNiceArray}{~emphase#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{BVerbatim} +$\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{BVerbatim}[baseline=c,boxwidth=10cm] +$\begin{bNiceMatrix}[r] +\cos x & - \sin x \\ +\sin x & \cos x +\end{bNiceMatrix}$ +\end{BVerbatim} +$\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{BVerbatim}[baseline=c,boxwidth=12cm] +\NiceMatrixOptions% + {code-for-first-row = \scriptstyle ~emphase#\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{BVerbatim} +\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{BVerbatim}[baseline=c,boxwidth=12cm] +\NiceMatrixOptions% + {code-for-last-row = \scriptstyle ~emphase#\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{BVerbatim} +\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} + + + +\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{Verbatim} +$\begin{bNiceArray}{cccc|c}[~emphase#small@, + last-col, + code-for-last-col = \scriptscriptstyle, + columns-width = 3mm ] +1 & -2 & 3 & 4 & 5 \\ +0 & 3 & 2 & 1 & 2 & L_2 \gets 2 L_1 - L_2 \\ +0 & 1 & 1 & 2 & 3 & L_3 \gets L_1 + L_3 +\end{bNiceArray}$ +\end{Verbatim} +% +\[\begin{bNiceArray}{cccc|c}[small, last-col, + code-for-last-col = \scriptscriptstyle, + columns-width=3mm] +1 & -2 & 3 & 4 & 5 \\ +0 & 3 & 2 & 1 & 2 & L_2 \gets 2 L_1 - L_2 \\ +0 & 1 & 1 & 2 & 3 & L_3 \gets L_1 + L_3 +\end{bNiceArray}\] + + +\bigskip +One should note that the environment |{NiceMatrix}| with the option |small| is +not composed \emph{exactly} as the environment |{smallmatrix}|. Indeed, all +the environments of \pkg{nicematrix} are constructed upon |{array}| (of the +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| which represent the number of the current row and the number of the +current column\footnote{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 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 +(excepted the potential exterior rows) and |jCol| represents the total number +of columns (excepted the potential exterior columns). + +\medskip +\begin{BVerbatim}[baseline=c,boxwidth=10.6cm] +$\begin{pNiceMatrix}% don't forget the % + [first-row, + first-col, + code-for-first-row = \mathbf{~emphase#\alph{jCol}@} , + code-for-first-col = \mathbf{~emphase#\arabic{iRow}@} ] +& & & & \\ +& 1 & 2 & 3 & 4 \\ +& 5 & 6 & 7 & 8 \\ +& 9 & 10 & 11 & 12 +\end{pNiceMatrix}$ +\end{BVerbatim} +$\begin{pNiceMatrix}[first-row, + first-col, + code-for-first-row = \mathbf{\alph{jCol}} , + code-for-first-col = \mathbf{\arabic{iRow}} ] +& & & & \\ +& 1 & 2 & 3 & 4 \\ +& 5 & 6 & 7 & 8 \\ +& 9 & 10 & 11 & 12 +\end{pNiceMatrix}$ + +\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{Verbatim} +$C = ~emphase#\pAutoNiceMatrix@{3-3}{C_{\arabic{iRow},\arabic{jCol}}}$ +\end{Verbatim} + + +\[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{scope} +\begin{BVerbatim}[baseline=c,boxwidth=10cm] +$\begin{bNiceMatrix}[~emphase#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{BVerbatim} +\end{scope} +$\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.} + + +\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{BVerbatim}[boxwidth=12cm,baseline=c] +$\begin{bNiceMatrix}[delimiters/color=red] +1 & 2 \\ +3 & 4 +\end{bNiceMatrix}$ +\end{BVerbatim} +$\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{BVerbatim}[baseline=c,boxwidth=11cm] +$\begin{~emphase#NiceArrayWithDelims@} + {\downarrow}{\uparrow}{ccc}[margin] +1 & 2 & 3 \\ +4 & 5 & 6 \\ +7 & 8 & 9 +\end{~emphase#NiceArrayWithDelims@}$ +\end{BVerbatim} +$\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. 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} + +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 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|. 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{BVerbatim}[baseline=c,boxwidth=11cm] +$\begin{pNiceMatrix}[name=~emphase#mymatrix@] +1 & 2 & 3 \\ +4 & 5 & 6 \\ +7 & 8 & 9 +\end{pNiceMatrix}$ +\tikz[remember picture,overlay] + \draw ~emphase#(mymatrix-2-2)@ circle (2mm) ; +\end{BVerbatim} +$\begin{pNiceMatrix}[name=mymatrix] +1 & 2 & 3 \\ +4 & 5 & 6 \\ +7 & 8 & 9 +\end{pNiceMatrix}$ +\tikz[remember picture,overlay] + \draw (mymatrix-2-2) circle (2mm) ; + +\medskip +Don't forget the options |remember picture| and |overlay|. + +\bigskip +In the |\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{BVerbatim}[baseline=c,boxwidth=11cm] +$\begin{pNiceMatrix} +1 & 2 & 3 \\ +4 & 5 & 6 \\ +7 & 8 & 9 +\CodeAfter + \tikz \draw ~emphase#(2-2)@ circle (2mm) ; +\end{pNiceMatrix}$ +\end{BVerbatim} +$\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 (excepted 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 +\colorbox{yellow!50}{\textbf{New 6.17}}\enskip 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{Verbatim} +\pgfset + { + ~emphase#nicematrix / cell-node@ /.style = + { + inner sep = 0 pt , + minimum width = 0 pt + } + } +\end{Verbatim} + +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} + +\colorbox{yellow!50}{\textbf{New 6.17}}\enskip \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} +\fvset{commandchars=\~\#\+} +\begin{Verbatim} +\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{Verbatim} +\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|. There is also a node called $i$|.5| midway +between the node $i$ and the node $i+1$. + +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{Verbatim} +\begin{NiceMatrix} +\CodeBefore + ~emphase#\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{Verbatim} +% +\[\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{BVerbatim}[boxwidth=11cm,baseline=c] +$\begin{pNiceArray}{ccc|c} +2 & 1 & 3 & 0 \\ +3 & 3 & 1 & 0 \\ +3 & 3 & 1 & 0 +\CodeAfter + \tikz \draw [red] (~emphase#3.5@-|1) -- (~emphase#3.5@-|last) ; +\end{pNiceArray}$ +\end{BVerbatim} +$\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 developpers} + +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 +developper 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{scope} +\fvset{commandchars=\§\¤\μ} +\begin{Verbatim} +\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 §emphase¤\g_nicematrix_code_before_tlμ + { + \__pantigny_crossbox:nnn + { \int_use:c { c@iRow } } + { \int_use:c { c@jCol } } + { \exp_not:n { #1 } } + } + } +\ExplSyntaxOff +\end{Verbatim} +\end{scope} + + +\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 + +\bigskip +Here is an example of utilisation: + +\medskip +\begin{BVerbatim}[baseline=c,boxwidth=9cm] +\begin{NiceTabular}{ccc}[hvlines] +\CodeBefore + \arraycolor{gray!10} +\Body +merlan & requin & cabillaud \\ +baleine & ~emphase#\crossbox[red]@ & morue \\ +mante & raie & poule +\end{NiceTabular} +\end{BVerbatim} +\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: + +% \medskip +\begin{scope} +\begin{minipage}{9.5cm} +Example with parallelization (default): +\begin{Verbatim} +$A = \begin{pNiceMatrix} +1 & \Cdots & & 1 \\ +a+b & ~emphase#\Ddots@~ & & \Vdots \\ +\Vdots & \Ddots & & \\ +a+b & \Cdots & a+b & 1 +\end{pNiceMatrix}$ +\end{Verbatim} +\end{minipage} +$A = \begin{pNiceMatrix} +1 & \Cdots & & 1 \\ +a+b & \Ddots & & \Vdots \\ +\Vdots & \Ddots & & \\ +a+b & \Cdots & a+b & 1 +\end{pNiceMatrix}$ + +\bigskip +\NiceMatrixOptions{parallelize-diags=true}% +\begin{minipage}{9.5cm} +\begin{Verbatim} +$A = \begin{pNiceMatrix} +1 & \Cdots & & 1 \\ +a+b & & & \Vdots \\ +\Vdots & ~emphase#\Ddots@~ & \Ddots & \\ +a+b & \Cdots & a+b & 1 +\end{pNiceMatrix}$ +\end{Verbatim} +\end{minipage} +$A = \begin{pNiceMatrix} +1 & \Cdots & & 1 \\ +a+b & & & \Vdots \\ +\Vdots & \Ddots & \Ddots & \\ +a+b & \Cdots & a+b & 1 +\end{pNiceMatrix}$ + +\bigskip +It's possible to turn off the parallelization with the option +|parallelize-diags| set to |false|: \par\nobreak + +\medskip +\NiceMatrixOptions{parallelize-diags=false}% +\begin{minipage}{9.5cm} +The same example without parallelization: +\end{minipage} +$A = \begin{pNiceMatrix} +1 & \Cdots & & 1 \\ +a+b & \Ddots & & \Vdots \\ +\Vdots & \Ddots & & \\ +a+b & \Cdots & a+b & 1 +\end{pNiceMatrix}$ + +\end{scope} + +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}: 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).\footnote{See + \url{https://tex.stackexchange.com/questions/528975/error-loading-tikz-in-ieeeaccess-class}} + +\bigskip +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} + +\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}). +By any means, in the context of \pkg{nicematrix}, it's recommended to draw +dashed rules with the tools provided by \pkg{nicematrix}, by creating a +customized line style with |custom-line|: cf.~p.~\pageref{custom-line}. + +\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{Verbatim} +\ttfamily \small +\begin{NiceTabular}{X[m]X[m]X[m]}[hvlines,cell-space-limits=3pt] + \Block[~emphase#tikz={pattern=grid,pattern color=lightgray}@]{} + {pattern = grid,\\ pattern color = lightgray} +& \Block[~emphase#tikz={pattern = north west lines,pattern color=blue}@]{} + {pattern = north west lines,\\ pattern color = blue} +& \Block[~emphase#tikz={outer color = red!50, inner color=white }@]{2-1} + {outer color = red!50,\\ inner color = white} \\ + \Block[~emphase#tikz={pattern = sixpointed stars, pattern color = blue!15}@]{} + {pattern = sixpointed stars,\\ pattern color = blue!15} +& \Block[~emphase#tikz={left color = blue!50}@]{} + {left color = blue!50} \\ +\end{NiceTabular} +\end{Verbatim} + +\begin{center} +\ttfamily \small +\begin{NiceTabular}{X[m]X[m]X[m]}[hvlines,cell-space-limits=3pt] + \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{Verbatim} +\begin{NiceTabular}{ccc}[hvlines] +\CodeBefore + \columncolor[RGB]{169,208,142}{2} +\Body +one & two & three \\ +\Block[~emphase#transparent, tikz={pattern = north west lines, pattern color = gray}@]{1-*}{} +four & five & six \\ +seven & eight & nine +\end{Verbatim} + +\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 excepted on the borders (which are, of course, added by \pkg{tcolorbox}) + +\medskip +\begin{BVerbatim} +\tcbset + { + colframe = blue!50!black , + colback = white , + colupper = red!50!black , + 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}[~emphase#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{BVerbatim} + + +\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 , + colupper = red!50!black , + 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} + + + +\vspace{1cm} +That example shows the use of \pkg{nicematrix} in conjunction with +\pkg{tcolorbox}. If one wishes a tabular with an exterior frame with rounded +corners, it's not necessary to use \pkg{tcolorbox}: it's possible to use the +command |\Block| with the key |rounded-corners|. + +\medskip +\begin{BVerbatim}[baseline=c,boxwidth=10.5cm] +\begin{NiceTabular}{rcl}[hvlines-except-borders] +\Block[draw,transparent,~emphase#rounded-corners@]{*-*}{} + One & Two & Three \\ + Men & Mice & Lions \\ + Upper & Middle & Lower +\end{NiceTabular} +\end{BVerbatim} +\begin{NiceTabular}{rcl}[hvlines-except-borders] +\Block[draw,transparent,rounded-corners]{*-*}{} + One & Two & Three \\ + Men & Mice & Lions \\ + Upper & Middle & Lower +\end{NiceTabular} + +\medskip +We have used the key |transparent| to have the rules specified by +|hvlines-except-borders| drawn in the blocks (by default, the rules are not +drawn in the blocks). + +\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{Verbatim} +\ExplSyntaxOn +\NewDocumentCommand ~emphase#\stars@ { m } + { \prg_replicate:nn { \value { ~#1 } } { $ \star $ } } +\ExplSyntaxOff +\end{Verbatim} +% +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{Verbatim} +\NiceMatrixOptions + { + notes = + { + ~emphase#style = \stars{~#1} , @ + ~emphase#enumitem-keys = @ + ~emphase# { @ + ~emphase# widest* = \value{tabularnote} ,@ + ~emphase# align = right @ + ~emphase# } @ + } + } +\end{Verbatim} + + + +\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{Verbatim} +\begin{NiceTabular}{~@{}llr~@{}} +\toprule \RowStyle{\bfseries} +Last name & First name & Birth day \\ +\midrule +Achard\tabularnote{~emphase#Achard is an old family of the Poitou.@} +& Jacques & 5 juin 1962 \\ +Lefebvre\tabularnote{~emphase#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{Verbatim} + +\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. + +\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[color=blue,line-style=dashed]& & & \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[color=blue,line-style=dashed]& & & \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 + {nullify-dots,code-for-first-col = \color{blue},code-for-first-row=\color{blue}} +$\begin{pNiceMatrix}[first-row,first-col] + & & \Ldots[line-style={solid,<->},shorten=0pt]^{n \text{ columns}} \\ + & 1 & 1 & 1 & \Ldots & 1 \\ + & 1 & 1 & 1 & & 1 \\ +\Vdots[line-style={solid,<->}]_{n \text{ rows}} & 1 & 1 & 1 & & 1 \\ + & 1 & 1 & 1 & & 1 \\ + & 1 & 1 & 1 & \Ldots & 1 +\end{pNiceMatrix}$ +\end{Verbatim} + + +\begin{scope} +\NiceMatrixOptions + {nullify-dots,code-for-first-col = \color{blue},code-for-first-row=\color{blue}} +\[\begin{pNiceMatrix}[first-row,first-col] + & & \Ldots[line-style={solid,<->},shorten=0pt]^{n \text{ columns}} \\ + & 1 & 1 & 1 & \Ldots & 1 \\ + & 1 & 1 & 1 & & 1 \\ +\Vdots[line-style={solid,<->}]_{n \text{ rows}} & 1 & 1 & 1 & & 1 \\ + & 1 & 1 & 1 & & 1 \\ + & 1 & 1 & 1 & \Ldots & 1 +\end{pNiceMatrix}\] +\end{scope} + +\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{Verbatim} +\begin{pNiceMatrix} +~emphase#\Block[borders={bottom,right,tikz=dashed}]{2-2}{}@ +1 & 2 & 0 & 0 & 0 & 0 \\ +4 & 5 & 0 & 0 & 0 & 0 \\ +0 & 0 & ~emphase#\Block[borders={bottom,top,right,left,tikz=dashed}]{2-2}{}@ + 7 & 1 & 0 & 0 \\ +0 & 0 & -1 & 2 & 0 & 0 \\ +0 & 0 & 0 & 0 & ~emphase#\Block[borders={left,top,tikz=dashed}]{2-2}{}@ + 3 & 4 \\ +0 & 0 & 0 & 0 & 1 & 4 +\end{pNiceMatrix} +\end{Verbatim} + + +\[\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{Verbatim}[formatcom=\small\color{gray}] +~emphase#\begin{NiceMatrixBlock}[auto-columns-width]@ +\NiceMatrixOptions + { + light-syntax, + last-col, code-for-last-col = \color{blue} \scriptstyle, + } +\setlength{\extrarowheight}{1mm} + +$\begin{pNiceArray}{rrrr|r} +12 -8 7 5 3 {} ; + 3 -18 12 1 4 ; +-3 -46 29 -2 -15 ; + 9 10 -5 4 7 +\end{pNiceArray}$ + +\smallskip +$\begin{pNiceArray}{rrrr|r} +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{pNiceArray}$ + +\smallskip +$\begin{pNiceArray}{rrrr|r} +12 -8 7 5 3 ; +0 64 -41 1 19 ; +0 0 0 0 0 { L_3 \gets 3 L_2 + L_3 } +\end{pNiceArray}$ + +\smallskip +$\begin{pNiceArray}{rrrr|r} +12 -8 7 5 3 {} ; +0 64 -41 1 19 ; +\end{pNiceArray}$ + +~emphase#\end{NiceMatrixBlock}@ +\end{Verbatim} + +\bigskip +\index{auto-columns-width!(key of \texttt{\{NiceMatrixBlock\}})|textit} +\begin{NiceMatrixBlock}[auto-columns-width] +\NiceMatrixOptions + { + light-syntax, + last-col, code-for-last-col = \color{blue} \scriptstyle , + } +\setlength{\extrarowheight}{1mm} + +\quad $\begin{pNiceArray}{rrrr|r} +12 -8 7 5 3 {} ; + 3 -18 12 1 4 ; +-3 -46 29 -2 -15 ; + 9 10 -5 4 7 +\end{pNiceArray}$ + +\smallskip +\quad $\begin{pNiceArray}{rrrr|r} +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{pNiceArray}$ + +\smallskip +\quad $\begin{pNiceArray}{rrrr|r} +12 -8 7 5 3 ; +0 64 -41 1 19 ; +0 0 0 0 0 { L_3 \gets 3 L_2 + L_3 } +\end{pNiceArray}$\par\nobreak + +\smallskip +\quad $\begin{pNiceArray}{rrrr|r} +12 -8 7 5 3 {} ; +0 64 -41 1 19 ; +\end{pNiceArray}$ +\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{Verbatim}[formatcom=\small\color{gray}] +~emphase#\begin{NiceMatrixBlock}[auto-columns-width]@ +\NiceMatrixOptions + { + ~emphase#delimiters/max-width@, + light-syntax, + last-col, code-for-last-col = \color{blue}\scriptstyle, + } +\setlength{\extrarowheight}{1mm} + +$\begin{pNiceArray}{rrrr|r} +12 -8 7 5 3 {} ; + 3 -18 12 1 4 ; +-3 -46 29 -2 -15 ; + 9 10 -5 4 7 +\end{pNiceArray}$ + +... +~emphase#\end{NiceMatrixBlock}@ +\end{Verbatim} + +\bigskip +\begin{NiceMatrixBlock}[auto-columns-width] +\NiceMatrixOptions + { + delimiters/max-width, + light-syntax, + last-col, code-for-last-col = \color{blue}\scriptstyle, + } +\setlength{\extrarowheight}{1mm} + +\quad $\begin{pNiceArray}{rrrr|r} +12 -8 7 5 3 {} ; + 3 -18 12 1 4 ; +-3 -46 29 -2 -15 ; + 9 10 -5 4 7 +\end{pNiceArray}$ + +\smallskip +\quad $\begin{pNiceArray}{rrrr|r} +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{pNiceArray}$ + +\smallskip +\quad $\begin{pNiceArray}{rrrr|r} +12 -8 7 5 3 ; +0 64 -41 1 19 ; +0 0 0 0 0 { L_3 \gets 3 L_2 + L_3 } +\end{pNiceArray}$\par\nobreak + +\smallskip +\quad $\begin{pNiceArray}{rrrr|r} +12 -8 7 5 3 {} ; +0 64 -41 1 19 ; +\end{pNiceArray}$ + +\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{Verbatim} +\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 \\ +~emphase#\CodeAfter [sub-matrix/vlines=4]@ +~emphase# \SubMatrix({1-1}{4-5})@ +~emphase# \SubMatrix({5-1}{8-5})@ +~emphase# \SubMatrix({9-1}{11-5})@ +~emphase# \SubMatrix({12-1}{13-5})@ +\end{NiceMatrix}\] +\end{Verbatim} + +\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{Verbatim} +\setlength{\extrarowheight}{1mm} +\[\begin{NiceArray} + [ + ~emphase#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{Verbatim} + + +\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{Verbatim} +$\begin{pNiceArray}{>{\strut}cccc}[margin,rules/color=blue] +~emphase#\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{Verbatim} +\[\begin{pNiceArray}{>{\strut}cccc}[margin,rules/color=blue] +\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 |colortbl-like| is +used−even when \pkg{colortbl} is not loaded). + +\index{colortbl-like|textit} +\index{rowcolor@\texttt{\textbackslash rowcolor}!command in tabular|textit} + + +\medskip +\begin{Verbatim} +\begin{pNiceArray}{>{\strut}cccc}[margin, extra-margin=2pt,colortbl-like] + ~emphase#\rowcolor{red!15}@A_{11} & A_{12} & A_{13} & A_{14} \\ + A_{21} & ~emphase#\rowcolor{red!15}@A_{22} & A_{23} & A_{24} \\ + A_{31} & A_{32} & ~emphase#\rowcolor{red!15}@A_{33} & A_{34} \\ + A_{41} & A_{42} & A_{43} & ~emphase#\rowcolor{red!15}@A_{44} +\end{pNiceArray} +\end{Verbatim} + + + +\[\begin{pNiceArray}{>{\strut}cccc}[margin, extra-margin=2pt,colortbl-like] + \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{Verbatim} +\tikzset{highlight/.style={rectangle, + fill=red!15, + rounded corners = 0.5 mm, + inner sep=1pt, + fit=~#1}} + +$\begin{bNiceMatrix} +~emphase#\CodeBefore [create-cell-nodes] @ +~emphase# \tikz \node [highlight = (2-1) (2-3)] {} ; @ +~emphase# \Body @ +0 & \Cdots & 0 \\ +1 & \Cdots & 1 \\ +0 & \Cdots & 0 \\ +\end{bNiceMatrix}$ +\end{Verbatim} +\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{Verbatim} +\[\begin{pNiceArray}{ccc}[last-col, margin = 2pt] +\CodeBefore [create-cell-nodes] + \begin{tikzpicture} +~emphase# \node [highlight = (1-1) (1-3)] {} ;@ +~emphase# \node [highlight = (2-1) (2-3)] {} ;@ +~emphase# \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{Verbatim} + + +\[\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{Verbatim} +\[\begin{pNiceArray}{ccc}[last-col, margin = 2pt, create-medium-nodes] +\CodeBefore [create-cell-nodes] + \begin{tikzpicture} ~emphase#[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{Verbatim} + + +\[\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{Verbatim}[formatcom = \small\color{gray}] +\[\begin{NiceArray}{*{6}{c}~LetterAt{\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{Verbatim} + + + +\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{Verbatim} +\pgfset + { + ~emphase#nicematrix/cell-node@/.append style = + { text/rotate = 45, minimum size = 6 mm } + } + +\setlength{\tabcolsep}{0pt} + +~emphase#\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{Verbatim} + + +\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.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). + +Modification of the code which is now twice faster. + + + +\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: + + |