How to use \clist_map_tokens:Nn?

Question

p. 175: \clist_map_tokens:Nn⟨clist var⟩{⟨code⟩} calls ⟨code⟩{⟨item⟩} for every ⟨item⟩stored in the ⟨comma list⟩. If the ⟨code⟩consists of a single function this is equivalent to \clist_map_function:nN. Could someone please show an example?

\documentclass{article}
\begin{document}
\ExplSyntaxOn

%\clist_map_tokens:nn {x,y,x} {(#1)} % ERROR
\clist_map_inline:nn {x,y,x} {(#1)}

\ExplSyntaxOff
\end{document}

Answer 1

When you use \clist_map_inline:Nn or \clist_map_inline:nn you can only use #1 in the second argument, to refer to the current item in the loop.

With \clist_map_tokens:Nn, the second argument should be a function with one fewer argument passed than those it takes; the trailing one will be supplied as the braced current item.

\documentclass{article}
\usepackage{amsmath}

\ExplSyntaxOn

\NewDocumentCommand{\makematrix}{O{0pt}m}
 {
  \begin{bmatrix}
  \clist_map_tokens:nn { #2 } { \erwann_make_row:nn { #1 } }
  \\[\dim_eval:n { -\normalbaselineskip - #1 }]
  \end{bmatrix}
 }
\cs_new:Nn \erwann_make_row:nn { \clist_use:nn { #2 } { & } \\[#1] }

\ExplSyntaxOff

\begin{document}

$\makematrix{{1,2,3},{4,5,6},{7,8,9}}\ne\makematrix[12pt]{{1,2,3},{4,5,6},{7,8,9}}$

\end{document}

Another advantage to \clist_map_inline:nn is that \clist_map_tokens:nn is fully expandable, but notice the hollow star.

Answer 2

Unlike for \clist_map_inline:nn the second argument to the _map_token:nn functions (the same is true for e.g. \prop_map_tokens:Nn etc.) is not a definition for an internal macro, instead it should be called with some tokens in the second argument which expect a following brace group containing the list item. For instance, the following just outputs every item:

\clist_map_tokens:nn { a, b, c } { \use:n }

This is useful if your code needs another argument which just gets forwarded. For instance, what if we want to output only the numeric items in a clist which are bigger than another given number? You could achieve this fully expandable with the following function (that you could then nest in the argument of another clist function with an e-type expansion):

\documentclass[]{article}

\ExplSyntaxOn
\cs_new:Npn \mymodule_filter_numbers:nn #1#2
  {
    \clist_if_empty:nF {#2}
      {
        \exp_args:Ne \exp_not:o
          {
            \exp_not:N \use_none:n
            \clist_map_tokens:nn {#2} { \__mymodule_filter_numbers:nn {#1} }
          }
      }
  }
\cs_new:Npn \__mymodule_filter_numbers:nn #1#2
  {
    \int_compare:nT { (#2) #1 } { , { \exp_not:n {#2} } }
  }
\NewExpandableDocumentCommand \filternumbers { m m }
  {
    \mymodule_filter_numbers:nn {#1} {#2}
  }
\ExplSyntaxOff

\edef\foo{\filternumbers{>5}{1,2,3,4,5,6,7,8,9}}\show\foo

\begin{document}
\filternumbers{>5}{1,2,3,4,5,6,7,8,9}
\end{document}