% !TeX TXS-program:compile = txs:///arara
% arara: pdflatex: {shell: no, synctex: no, interaction: batchmode}
% arara: pdflatex: {shell: no, synctex: no, interaction: batchmode}

\documentclass[11pt,a4paper]{ltxdoc}
\usepackage{bera}
\usepackage{inconsolata}
\usepackage[T1]{fontenc}
\usepackage[scale=0.875]{cabin}
\usepackage{commalists-tools-l3}
\usepackage{listofitems}
\usepackage{fancyvrb}
\usepackage{fancyhdr}
\usepackage{tabularray}
\usepackage{fontawesome5}
\fancyhf{}
\renewcommand{\headrulewidth}{0pt}
\lfoot{\sffamily\small [commalists-tools-l3]}
\cfoot{\sffamily\small - \thepage{} -}
\rfoot{\hyperlink{matoc}{\small\faArrowAltCircleUp[regular]}}
\usepackage{hologo}
\providecommand\tikzlogo{Ti\textit{k}Z}
\providecommand\TeXLive{\TeX{}Live\xspace}
\let\TikZ\tikzlogo

\usepackage{hyperref}
\urlstyle{same}
\hypersetup{pdfborder=0 0 0}
\usepackage[margin=2cm]{geometry}
\setlength{\parindent}{0pt}
\def\TPversion{0.1.6}
\def\TPdate{27/08/2025}
\usepackage{tcolorbox}
\usepackage{pgffor}
\tcbuselibrary{breakable,skins,hooks,listingsutf8}
%\usepackage{soul}
%\sethlcolor{lightgray!25}

\lstset{
	language=[LaTeX]TeX,%
	basicstyle=\ttfamily,%
	keywordstyle={\color{blue}},%
	classoffset=0,%
	keywords={},%
	alsoletter={-},%
	keywordstyle={\color{blue}},%
	classoffset=1,%
	alsoletter={-},%
	morekeywords={commalists-tools-l3},%
	keywordstyle={\color{violet}},%
	classoffset=2,%
	alsoletter={-},%
	morekeywords={\ctshowlist,\ctsortasclist,\ctsortdeslist,\ctaddvalinlist,\ctremovevalinlist,\ctboolvalinlist,\cttestifvalinlist,\ctcountvalinlist,\ctminoflist,\ctmaxoflist,\ctmeanoflist,\ctsumoflist,\ctprodoflist,\ctreverselist,\ctgetvaluefromlist,\ctlenoflist},%
	keywordstyle={\color{green!50!black}},%
	classoffset=3,%
	morekeywords={},%
	keywordstyle={\color{orange}}
}

\newtcblisting{DemoCode}[1]{%
	enhanced,width=\linewidth,%
	bicolor,size=title,%
	colback=cyan!10!white,%
	colbacklower=cyan!5!white,%
	colframe=cyan!75!black,%
	listing options={%
		breaklines=true,%
		breakatwhitespace=true,%
		style=tcblatex,basicstyle=\small\ttfamily,%
		tabsize=4,%
		commentstyle={\itshape\color{gray}},
		keywordstyle={\color{blue}},%
		classoffset=0,%
		keywords={\usepackage,\includegraphics,xstring,listofitems,\readlist,\showitems,\xintFor,\xintSeq},%
		alsoletter={-},%
		keywordstyle={\color{blue}},%
		classoffset=1,%
		alsoletter={-},%
		morekeywords={commalists-tools-l3},%
		keywordstyle={\color{violet}},%
		classoffset=2,%
		alsoletter={-},%
		morekeywords={\ctshowlist,\ctsortasclist,\ctsortdeslist,\ctaddvalinlist,\ctremovevalinlist,\ctboolvalinlist,\cttestifvalinlist,\ctcountvalinlist,\ctminoflist,\ctmaxoflist,\ctmeanoflist,\ctsumoflist,\ctprodoflist,\ctreverselist,\ctgetvaluefromlist,\ctlenoflist},%
		keywordstyle={\color{green!50!black}},%
		classoffset=3,%
		morekeywords={},%
		keywordstyle={\color{orange}}
	},%
	#1
}

\newtcbinputlisting\DemoCodeFile[1]{%
	enhanced,width=\linewidth,%
	bicolor,size=title,%
	colback=lightgray!10!white,%
	colbacklower=lightgray!5!white,%
	colframe=lightgray!75!black,%
	listing options={%
		breaklines=true,%
		breakatwhitespace=true,%
		style=tcblatex,
		basicstyle=\scriptsize\ttfamily,%
		tabsize=4,%
		commentstyle={\itshape\color{gray}},%
		%lastline=148
	},%
	breakable,
	listing only,%
	listing file={#1}
}

\NewDocumentCommand\ShowCode{ m }{%
	\lstinline{#1}%
}

\begin{document}

\thispagestyle{empty}

\begin{center}
	\begin{minipage}{0.88\linewidth}
		\begin{tcolorbox}[colframe=yellow,colback=yellow!15]
			\begin{center}
				\renewcommand{\arraystretch}{1.25}%
				\begin{tabular}{c}
					{\Huge \texttt{commalists-tools-l3}}\\
					\\
					{\large\hologo{LaTeX3}}\\
					\\
					{\LARGE Macros for manipulating numeral} \\
					{\LARGE comma separated lists:} \\
					{\LARGE sorting, adding, removing, etc} \\
					\\
					{\small \texttt{Version \TPversion{} -- \TPdate}}
				\end{tabular}
			\end{center}
		\end{tcolorbox}
	\end{minipage}
\end{center}

\begin{center}
	\begin{tabular}{c}
		\texttt{Cédric Pierquet}\\
		{\ttfamily c pierquet -- at -- outlook . fr}\\
		\texttt{\url{https://github.com/cpierquet/latex-packages/tree/main//commalists-tools}} \\
	\end{tabular}
\end{center}

\hrule

\vfill

\begin{tcblisting}{colframe=lightgray,colback=lightgray!5,listing only}
\def\mytestlist{14,10,15,11,9,10}
\ctlenoflist*{\mytestlist}
\ctminoflist*{\mytestlist}
\ctmaxoflist*{14,10,15,11,9,10}
\ctsortasclist*{\mytestlist}
\ctmeanoflist*{\mytestlist}
\ctremovevalinlist*{10}{\mytestlist}
\cttestifvalinlist{15}{\mytestlist}{true}{false}
\ctgetvaluefromlist*{\mytestlist}{3}
\end{tcblisting}

\begin{tcolorbox}[colframe=lightgray,colback=lightgray!5]
\def\mytestlist{14,10,15,11,9,10}
We consider the list: \mytestlist\par\smallskip
There's \ctlenoflist*{\mytestlist} values in the list\par\smallskip
The minimum value is \ctminoflist*{\mytestlist} and the maximum is \ctmaxoflist*{14,10,15,11,9,10}\par\smallskip
Ascending sorted list is \ctsortasclist*{\mytestlist}\par\smallskip
Meaning value of the list is \ctmeanoflist*{\mytestlist}\par\smallskip
If we remove the value 10, then the list is \ctremovevalinlist*{10}{\mytestlist}\par\smallskip
We test if 15 is in the list: \cttestifvalinlist{15}{\mytestlist}{true}{false}\par\smallskip
The third value of the list is \ctgetvaluefromlist*{\mytestlist}{3}
\end{tcolorbox}

\vfill~

%\hrule
%
%\medskip

%\emph{%
%	The \textsf{luarandom} package do the same things, but with the obligation to compile with \hologo{LuaLaTeX}.
%}
%
%\medskip

\hrule

\vspace*{5mm}

\pagebreak

\phantomsection

\hypertarget{matoc}{}

\tableofcontents

\vspace*{5mm}

%\hrule

\pagebreak

\section{Loading, useful packages}

In order to load \texttt{randintlist}, simply use:

\begin{DemoCode}{listing only}
\usepackage{commalists-tools-l3}
\end{DemoCode}

All code is written in \hologo{LaTeX3}, so no extra packages are needed.

\section{The individual macros}

\subsection{Global usage}

Package \texttt{commalists-tools-l3} supports (basic) manipulations on numeral comma separated lists:

\begin{itemize}
	\item sorting;
	\item adding values;
	\item removing values;
	\item counting values;
	\item mean, sum, product;
	\item get value, get length;
	\item etc.
\end{itemize}

Starred versions only print the result, whereas non starred versions store the result into a macro.

\medskip

{\small\faLightbulb} Macros are prefixed with \ShowCode{\\ct...} (for \textsf{\textbf{\underline{c}}ommalists-\textbf{\underline{t}}ools}).

\subsection{The macro for printing}

\begin{DemoCode}{listing only}
%just printing, with optional separator
\ctshowlist[sep]{list}
\end{DemoCode}

\begin{DemoCode}{}
\ctshowlist{1,   2,3, 4, 6}
\end{DemoCode}

\begin{DemoCode}{}
\def\mytmplist{12, -4,   5,7 ,8, 9, 0}
\ctshowlist[\,/\,]{\mytmplist}
\end{DemoCode}

\subsection{The macros for calculating}

\begin{DemoCode}{listing only}
%getting length of list, only printing
\ctlenoflist*{list}
%storing length of list into macro (\resmylen by default)
\ctlenoflist{list}
%getting min of list, only printing
\ctminoflist*{list}
%storing min of list into \macro (\resmin by default)
\ctminoflist{list}[\macro]
%getting max of list, only printing
\ctmaxoflist*{list}
%storing max of list into \macro (\resmax by default)
\ctmaxoflist{list}[\macro]
\end{DemoCode}

\begin{DemoCode}{}
%only printing
\ctlenoflist*{14,10,15,11,9,10}\\
%only printing
\ctminoflist*{14,10,15,11,9,10} and \ctmaxoflist*{14,10,15,11,9,10}
\end{DemoCode}

\begin{DemoCode}{}
%storing len/min/max of list
\def\mytestlist{10,14.5,20,12,8.5}
\ctlenoflist{\mytestlist}[\mylen]Length of list is \mylen\ \&
\ctminoflist{\mytestlist}[\mymin]Min of list is \mymin\ \&
\ctmaxoflist{\mytestlist}[\mymax]Max of list is \mymax
\end{DemoCode}

\begin{DemoCode}{listing only}
%getting mean of list, only printing
\ctmeanoflist*{list}
%storing mean of list into \macro (\resmean by default)
\ctmeanoflist{list}[\macro]
%getting sum of list, only printing
\ctsumoflist*{list}
%storing max of list into \macro (\ressum by default)
\ctsumoflist{list}[\macro]
%getting prod of list, only printing
\ctprodoflist*{list}
%storing max of list into \macro (\resprod by default)
\ctprodoflist{list}[\macro]
\end{DemoCode}

\begin{DemoCode}{}
%only printing
\ctmeanoflist*{14,10,15,11,9,10} \\
%storing
\ctmeanoflist{14,10,15,11,9,10}[\mymean]\mymean \\
%only printing
\ctsumoflist*{14,10,15,11,9,10} and \ctprodoflist*{14,10,15,11,9,10} \\
%storing
\ctsumoflist{14,10,15,11,9,10}[\mysum]\ctprodoflist{14,10,15,11,9,10}[\myprod]
The sum is \mysum\ and the prod is \myprod
\end{DemoCode}

\subsection{Macros for manipulating}

\begin{DemoCode}{listing only}
%sorting (asc), only printing
\ctsortasclist*{list}
%sorting (asc) and storing (overwrite)
\ctsortasclist{list}
%sorting (des), only printing
\ctsortdeslist*{list}
%sorting (des) and storing (overwrite)
\ctsortdeslist{list}
\end{DemoCode}

\begin{DemoCode}{}
%sorting (asc), only printing
\ctsortasclist*{14,10,15,11.5,9,10}\\
%sorting (asc) and storing (overwrite)
\def\tmpsortlist{14,10,15,11.5,9,10}
\ctsortasclist{\tmpsortlist}\tmpsortlist\\
%analysing
\readlist*\tmpSORTlist{\tmpsortlist}
\showitems{\tmpSORTlist}
\end{DemoCode}

\begin{DemoCode}{listing only}
%extract value, only printing
\ctgetvaluefromlist*{list}{index}
%extract value and storing into macro (\myelt by default)
\ctgetvaluefromlist{list}{index}[\macro]
\end{DemoCode}

\begin{DemoCode}{}
%extract value, only printing
\def\listtmp{1,2,3,6,3,1,5,7,3}%
\ctgetvaluefromlist*{\listtmp}{4}\par\smallskip
%storing
\ctgetvaluefromlist{\listtmp}{-1}[\mylastelt]The last element is \mylastelt
\end{DemoCode}

\begin{DemoCode}{}
%sorting (des), only printing
\ctsortdeslist*{14,10,15,11.5,9,10}\\
%sorting (asc) and storing (overwrite)
\def\tmpsortlist{14,10,15,11.5,9,10}
\ctsortdeslist{\tmpsortlist}\tmpsortlist\\
%analysing
\readlist*\tmpSORTlist{\tmpsortlist}
\showitems{\tmpSORTlist}
\end{DemoCode}

\begin{DemoCode}{listing only}
%adding, only printing
\ctaddvalinlist*{values}{list}
%adding and storing (overwrite)
\ctaddvalinlist{values}{list}
%removing, only printing
\ctremovevalinlist*{value}{list}
%removing and storing (overwrite)
\ctremovevalinlist{value}{list}
\end{DemoCode}

\begin{DemoCode}{}
%only printing
\ctaddvalinlist*{3}{1,2,5,6}\\
%defining and adding
\def\tmpaddlist{1,2,4,5,6}
\ctaddvalinlist{3}{\tmpaddlist}\tmpaddlist\\
%analysing
\readlist*\tmpADDlist{\tmpaddlist}
\showitems{\tmpADDlist}
\end{DemoCode}

\begin{DemoCode}{}
%only printing
\ctremovevalinlist*{3}{1,2,3,6,3,1,5,7,3}\\
%defining and removing
\def\tmpremlist{1,2,3,6,3,1,5,7,3}
\ctremovevalinlist{3}{\tmpremlist}\tmpremlist\\
%analysing
\readlist*\tmpREMlist{\tmpremlist}
\showitems{\tmpREMlist}
\end{DemoCode}

\begin{DemoCode}{listing only}
%reversing, only printing
\ctreverselist*{list}
%reversing and storing (overwrite)
\ctreverselist{list}
\end{DemoCode}

\begin{DemoCode}{}
%only printing
\ctreverselist*{14,10,15,11,9,10}\\
%reversing and storing
%storing
\ctreverselist{14,10,15,11,9,10}[\myreverse]\myreverse\\
%analysing
\readlist*\tmpREVERSElist{\myreverse}
\showitems{\tmpREVERSElist}
\end{DemoCode}

\subsection{Macros with testing}

\begin{DemoCode}{listing only}
%testing if value is in list, with boolean result in \macro (\resisinlist by default)
\ctboolvalinlist{value}{list}[\macro]
%conditionnal test if value is in list, according to xint syntax
\cttestifvalinlist{3}{0,1,2,3}{true}{false}
\end{DemoCode}

\begin{DemoCode}{}
%test with xint syntax
\cttestifvalinlist{-1}{0,1,2,3}{true}{false}\\
%test with xint syntax
\cttestifvalinlist{3}{0,1,2,3}{true}{false}\\
%boolean macro
\def\myteslist{0,5,10,5,6,9,7,8}
\ctboolvalinlist{5}{\myteslist}[\resisinlist]\resisinlist
\end{DemoCode}

\begin{DemoCode}{listing only}
%counting value, only printing
\ctcountvalinlist*{value}{list}
%counting value, with result in \macro (\rescount by default)
\ctcountvalinlist{value}{list}[\macro]
\end{DemoCode}

\begin{DemoCode}{}
%only printing
\ctcountvalinlist*{8}{1,2,3,4,5,6,6,7,8,8,8,9}\\
%storing
\def\tmpcountlist{1,2,3,4,5,6,6,7,8,8,8,9}
\ctcountvalinlist{6}{\tmpcountlist}[\rescountsix]\rescountsix\\
\ctcountvalinlist{10}{\tmpcountlist}[\rescountten]\rescountten
\end{DemoCode}

\pagebreak

\section{History}

\texttt{0.1.6: Initial version,code written in \hologo{LaTeX3}}

\section{The code}

\DemoCodeFile{commalists-tools-l3.sty}

\end{document}