summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/l3kernel/l3tl.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/l3kernel/l3tl.dtx')
-rw-r--r--macros/latex/contrib/l3kernel/l3tl.dtx822
1 files changed, 416 insertions, 406 deletions
diff --git a/macros/latex/contrib/l3kernel/l3tl.dtx b/macros/latex/contrib/l3kernel/l3tl.dtx
index 13625c2542..bda39b5cf0 100644
--- a/macros/latex/contrib/l3kernel/l3tl.dtx
+++ b/macros/latex/contrib/l3kernel/l3tl.dtx
@@ -43,7 +43,7 @@
% }^^A
% }
%
-% \date{Released 2021-10-18}
+% \date{Released 2021-11-12}
%
% \maketitle
%
@@ -205,159 +205,6 @@
% \meta{tl~var}.
% \end{function}
%
-% \section{Modifying token list variables}
-%
-% \begin{function}[updated = 2011-08-11]
-% {
-% \tl_replace_once:Nnn, \tl_replace_once:cnn,
-% \tl_greplace_once:Nnn, \tl_greplace_once:cnn
-% }
-% \begin{syntax}
-% \cs{tl_replace_once:Nnn} \meta{tl~var} \Arg{old tokens} \Arg{new tokens}
-% \end{syntax}
-% Replaces the first (leftmost) occurrence of \meta{old tokens} in the
-% \meta{tl~var} with \meta{new tokens}. \meta{Old tokens}
-% cannot contain |{|, |}| or |#|
-% (more precisely, explicit character tokens with category code $1$
-% (begin-group) or $2$ (end-group), and tokens with category code $6$).
-% \end{function}
-%
-% \begin{function}[updated = 2011-08-11]
-% {
-% \tl_replace_all:Nnn, \tl_replace_all:cnn,
-% \tl_greplace_all:Nnn, \tl_greplace_all:cnn
-% }
-% \begin{syntax}
-% \cs{tl_replace_all:Nnn} \meta{tl~var} \Arg{old tokens} \Arg{new tokens}
-% \end{syntax}
-% Replaces all occurrences of \meta{old tokens} in the
-% \meta{tl~var} with \meta{new tokens}. \meta{Old tokens}
-% cannot contain |{|, |}| or |#|
-% (more precisely, explicit character tokens with category code $1$
-% (begin-group) or $2$ (end-group), and tokens with category code $6$).
-% As this function
-% operates from left to right, the pattern \meta{old tokens}
-% may remain after the replacement (see \cs{tl_remove_all:Nn}
-% for an example).
-% \end{function}
-%
-% \begin{function}[updated = 2011-08-11]
-% {
-% \tl_remove_once:Nn, \tl_remove_once:cn,
-% \tl_gremove_once:Nn, \tl_gremove_once:cn
-% }
-% \begin{syntax}
-% \cs{tl_remove_once:Nn} \meta{tl~var} \Arg{tokens}
-% \end{syntax}
-% Removes the first (leftmost) occurrence of \meta{tokens} from the
-% \meta{tl~var}. \meta{Tokens} cannot contain |{|, |}| or |#|
-% (more precisely, explicit character tokens with category code $1$
-% (begin-group) or $2$ (end-group), and tokens with category code $6$).
-% \end{function}
-%
-% \begin{function}[updated = 2011-08-11]
-% {
-% \tl_remove_all:Nn, \tl_remove_all:cn,
-% \tl_gremove_all:Nn, \tl_gremove_all:cn
-% }
-% \begin{syntax}
-% \cs{tl_remove_all:Nn} \meta{tl~var} \Arg{tokens}
-% \end{syntax}
-% Removes all occurrences of \meta{tokens} from the
-% \meta{tl~var}. \meta{Tokens} cannot contain |{|, |}| or |#|
-% (more precisely, explicit character tokens with category code $1$
-% (begin-group) or $2$ (end-group), and tokens with category code $6$).
-% As this function
-% operates from left to right, the pattern \meta{tokens}
-% may remain after the removal, for instance,
-% \begin{quote}
-% \cs{tl_set:Nn} \cs{l_tmpa_tl} |{abbccd}|
-% \cs{tl_remove_all:Nn} \cs{l_tmpa_tl} |{bc}|
-% \end{quote}
-% results in \cs{l_tmpa_tl} containing \texttt{abcd}.
-% \end{function}
-%
-% \section{Reassigning token list category codes}
-%
-% These functions allow the rescanning of tokens: re-apply \TeX{}'s
-% tokenization process to apply category codes different from those
-% in force when the tokens were absorbed. Whilst this functionality is
-% supported, it is often preferable to find alternative approaches
-% to achieving outcomes rather than rescanning tokens (for example
-% construction of token lists token-by-token with intervening category
-% code changes or using \cs{char_generate:nn}).
-%
-% \begin{function}[updated = 2015-08-11]
-% {
-% \tl_set_rescan:Nnn, \tl_set_rescan:Nno, \tl_set_rescan:Nnx,
-% \tl_set_rescan:cnn, \tl_set_rescan:cno, \tl_set_rescan:cnx,
-% \tl_gset_rescan:Nnn, \tl_gset_rescan:Nno, \tl_gset_rescan:Nnx,
-% \tl_gset_rescan:cnn, \tl_gset_rescan:cno, \tl_gset_rescan:cnx
-% }
-% \begin{syntax}
-% \cs{tl_set_rescan:Nnn} \meta{tl~var} \Arg{setup} \Arg{tokens}
-% \end{syntax}
-% Sets \meta{tl~var} to contain \meta{tokens}, applying the category
-% code r\'{e}gime specified in the \meta{setup} before carrying out
-% the assignment. (Category codes applied to tokens not explicitly covered
-% by the \meta{setup} are those in force at the point of use of
-% \cs{tl_set_rescan:Nnn}.)
-% This allows the \meta{tl~var} to contain material
-% with category codes other than those that apply when \meta{tokens}
-% are absorbed. The \meta{setup} is run within a group and may
-% contain any valid input, although only changes in category codes,
-% such as uses of \cs{cctab_select:N},
-% are relevant. See also \cs{tl_rescan:nn}.
-% \begin{texnote}
-% The \meta{tokens} are first turned into a string (using
-% \cs{tl_to_str:n}). If the string contains one or more characters
-% with character code \tn{newlinechar} (set equal to
-% \tn{endlinechar} unless that is equal to $32$, before the user
-% \meta{setup}), then it is split into lines at these characters,
-% then read as if reading multiple lines from a file, ignoring
-% spaces (catcode $10$) at the beginning and spaces and tabs
-% (character code $32$ or $9$) at the end of every line.
-% Otherwise, spaces (and tabs) are retained at both ends of the
-% single-line string, as if it appeared in the middle of a line
-% read from a file.
-% \end{texnote}
-% \end{function}
-%
-% \begin{function}[updated = 2015-08-11]{\tl_rescan:nn}
-% \begin{syntax}
-% \cs{tl_rescan:nn} \Arg{setup} \Arg{tokens}
-% \end{syntax}
-% Rescans \meta{tokens} applying the category code r\'{e}gime
-% specified in the \meta{setup}, and leaves the resulting tokens in
-% the input stream. (Category codes applied to tokens not explicitly covered
-% by the \meta{setup} are those in force at the point of use of
-% \cs{tl_rescan:nn}.)
-% The \meta{setup} is run within a group and may
-% contain any valid input, although only changes in category codes,
-% such as uses of \cs{cctab_select:N},
-% are relevant. See also \cs{tl_set_rescan:Nnn}, which is more
-% robust than using \cs{tl_set:Nn} in the \meta{tokens} argument of
-% \cs{tl_rescan:nn}.
-% \begin{texnote}
-% The \meta{tokens} are first turned into a string (using
-% \cs{tl_to_str:n}). If the string contains one or more characters
-% with character code \tn{newlinechar} (set equal to
-% \tn{endlinechar} unless that is equal to $32$, before the user
-% \meta{setup}), then it is split into lines at these characters,
-% then read as if reading multiple lines from a file, ignoring
-% spaces (catcode $10$) at the beginning and spaces and tabs
-% (character code $32$ or $9$) at the end of every line.
-% Otherwise, spaces (and tabs) are retained at both ends of the
-% single-line string, as if it appeared in the middle of a line
-% read from a file.
-%
-% Contrarily to the \tn{scantokens} primitive, \cs{tl_rescan:nn}
-% tokenizes the whole string in the same category code regime rather
-% than one token at a time, so that directives such as \tn{verb}
-% that rely on changing category codes will not function properly.
-% \end{texnote}
-% \end{function}
-%
% \section{Token list conditionals}
%
% \begin{function}[EXP,pTF, updated = 2019-09-04]
@@ -473,7 +320,7 @@
% \cs{tl_if_single_p:N} \meta{tl~var}
% \cs{tl_if_single:NTF} \meta{tl~var} \Arg{true code} \Arg{false code}
% \end{syntax}
-% Tests if the content of the \meta{tl~var} consists of a single item,
+% Tests if the content of the \meta{tl~var} consists of a single \meta{item},
% \emph{i.e.}~is a single normal token (neither an explicit space
% character nor a begin-group character) or a single brace group,
% surrounded by optional spaces on both sides. In other words, such a
@@ -485,7 +332,7 @@
% \cs{tl_if_single_p:n} \Arg{token list}
% \cs{tl_if_single:nTF} \Arg{token list} \Arg{true code} \Arg{false code}
% \end{syntax}
-% Tests if the \meta{token list} has exactly one item, \emph{i.e.}~is
+% Tests if the \meta{token list} has exactly one \meta{item}, \emph{i.e.}~is
% a single normal token (neither an explicit space character nor a
% begin-group character) or a single brace group, surrounded by
% optional spaces on both sides. In other words, such a token list has
@@ -498,7 +345,7 @@
% \cs{tl_if_single_token:nTF} \Arg{token list} \Arg{true code} \Arg{false code}
% \end{syntax}
% Tests if the token list consists of exactly one token, \emph{i.e.}~is
-% either a single space character or a single \enquote{normal} token.
+% either a single space character or a single normal token.
% Token groups (|{|\ldots|}|) are not single tokens.
% \end{function}
%
@@ -526,152 +373,93 @@
% available.
% \end{function}
%
-% \section{Mapping over token lists}
+% \subsection{Testing the first token}
%
-% All mappings are done at the current group level, \emph{i.e.}~any
-% local assignments made by the \meta{function} or \meta{code} discussed
-% below remain in effect after the loop.
-%
-% \begin{function}[updated = 2012-06-29, rEXP]
-% {\tl_map_function:NN, \tl_map_function:cN}
-% \begin{syntax}
-% \cs{tl_map_function:NN} \meta{tl~var} \meta{function}
-% \end{syntax}
-% Applies \meta{function} to every \meta{item} in the \meta{tl~var}.
-% The \meta{function} receives one argument for each iteration.
-% This may be a number of tokens if the \meta{item} was stored within
-% braces. Hence the \meta{function} should anticipate receiving
-% \texttt{n}-type arguments. See also \cs{tl_map_function:nN}.
-% \end{function}
-%
-% \begin{function}[updated = 2012-06-29, rEXP]{\tl_map_function:nN}
-% \begin{syntax}
-% \cs{tl_map_function:nN} \Arg{token list} \meta{function}
-% \end{syntax}
-% Applies \meta{function} to every \meta{item} in the \meta{token list},
-% The \meta{function} receives one argument for each iteration.
-% This may be a number of tokens if the \meta{item} was stored within
-% braces. Hence the \meta{function} should anticipate receiving
-% \texttt{n}-type arguments. See also \cs{tl_map_function:NN}.
-% \end{function}
-%
-% \begin{function}[updated = 2012-06-29]
-% {\tl_map_inline:Nn, \tl_map_inline:cn}
+% \begin{function}[updated = 2012-07-09, EXP, pTF]
+% {\tl_if_head_eq_catcode:nN, \tl_if_head_eq_catcode:oN}
% \begin{syntax}
-% \cs{tl_map_inline:Nn} \meta{tl~var} \Arg{inline function}
+% \cs{tl_if_head_eq_catcode_p:nN} \Arg{token list} \meta{test token}
+% \cs{tl_if_head_eq_catcode:nNTF} \Arg{token list} \meta{test token}
+% ~~\Arg{true code} \Arg{false code}
% \end{syntax}
-% Applies the \meta{inline function} to every \meta{item} stored within the
-% \meta{tl~var}. The \meta{inline function} should consist of code which
-% receives the \meta{item} as |#1|. See also \cs{tl_map_function:NN}.
+% Tests if the first \meta{token} in the \meta{token list} has the
+% same category code as the \meta{test token}. In the case where the
+% \meta{token list} is empty, the test is always \texttt{false}.
% \end{function}
%
-% \begin{function}[updated = 2012-06-29]{\tl_map_inline:nn}
+% \begin{function}[updated = 2012-07-09, EXP, pTF]
+% {\tl_if_head_eq_charcode:nN, \tl_if_head_eq_charcode:fN}
% \begin{syntax}
-% \cs{tl_map_inline:nn} \Arg{token list} \Arg{inline function}
+% \cs{tl_if_head_eq_charcode_p:nN} \Arg{token list} \meta{test token}
+% \cs{tl_if_head_eq_charcode:nNTF} \Arg{token list} \meta{test token}
+% ~~\Arg{true code} \Arg{false code}
% \end{syntax}
-% Applies the \meta{inline function} to every \meta{item} stored within the
-% \meta{token list}. The \meta{inline function} should consist of code which
-% receives the \meta{item} as |#1|. See also \cs{tl_map_function:nN}.
+% Tests if the first \meta{token} in the \meta{token list} has the
+% same character code as the \meta{test token}. In the case where the
+% \meta{token list} is empty, the test is always \texttt{false}.
% \end{function}
%
-% \begin{function}[rEXP, added = 2019-09-02]
-% {\tl_map_tokens:Nn, \tl_map_tokens:cn, \tl_map_tokens:nn}
+% \begin{function}[updated = 2012-07-09, EXP, pTF]{\tl_if_head_eq_meaning:nN}
% \begin{syntax}
-% \cs{tl_map_tokens:Nn} \meta{tl~var} \Arg{code}
-% \cs{tl_map_tokens:nn} \Arg{tokens} \Arg{code}
+% \cs{tl_if_head_eq_meaning_p:nN} \Arg{token list} \meta{test token}
+% \cs{tl_if_head_eq_meaning:nNTF} \Arg{token list} \meta{test token}
+% ~~\Arg{true code} \Arg{false code}
% \end{syntax}
-% Analogue of \cs{tl_map_function:NN} which maps several tokens
-% instead of a single function. The \meta{code} receives each item in
-% the \meta{tl~var} or in \meta{tokens} as a trailing brace group. For
-% instance,
-% \begin{verbatim}
-% \tl_map_tokens:Nn \l_my_tl { \prg_replicate:nn { 2 } }
-% \end{verbatim}
-% expands to twice each item in the \meta{tl~var}: for each item in
-% \cs[no-index]{l_my_tl} the function \cs{prg_replicate:nn} receives |2| and
-% \meta{item} as its two arguments. The function
-% \cs{tl_map_inline:Nn} is typically faster but is not expandable.
+% Tests if the first \meta{token} in the \meta{token list} has the
+% same meaning as the \meta{test token}. In the case where
+% \meta{token list} is empty, the test is always \texttt{false}.
% \end{function}
%
-% \begin{function}[updated = 2012-06-29]
-% {\tl_map_variable:NNn, \tl_map_variable:cNn}
+% \begin{function}[added = 2012-07-08, EXP, pTF]{\tl_if_head_is_group:n}
% \begin{syntax}
-% \cs{tl_map_variable:NNn} \meta{tl~var} \meta{variable} \Arg{code}
+% \cs{tl_if_head_is_group_p:n} \Arg{token list}
+% \cs{tl_if_head_is_group:nTF} \Arg{token list} \Arg{true code} \Arg{false code}
% \end{syntax}
-% Stores each \meta{item} of the \meta{tl~var} in turn in the (token
-% list) \meta{variable} and applies the \meta{code}. The \meta{code}
-% will usually make use of the \meta{variable}, but this is not
-% enforced. The assignments to the \meta{variable} are local. Its
-% value after the loop is the last \meta{item} in the \meta{tl~var},
-% or its original value if the \meta{tl~var} is blank. See also
-% \cs{tl_map_inline:Nn}.
+% Tests if the first \meta{token} in the \meta{token list}
+% is an explicit begin-group character (with category code~$1$
+% and any character code), in other words, if the \meta{token list}
+% starts with a brace group. In particular, the test is \texttt{false}
+% if the \meta{token list} starts with an implicit token such as
+% \cs{c_group_begin_token}, or if it is empty.
+% This function is useful to implement actions on token lists on
+% a token by token basis.
% \end{function}
%
-% \begin{function}[updated = 2012-06-29]{\tl_map_variable:nNn}
+% \begin{function}[added = 2012-07-08, EXP, pTF]{\tl_if_head_is_N_type:n}
% \begin{syntax}
-% \cs{tl_map_variable:nNn} \Arg{token list} \meta{variable} \Arg{code}
+% \cs{tl_if_head_is_N_type_p:n} \Arg{token list}
+% \cs{tl_if_head_is_N_type:nTF} \Arg{token list} \Arg{true code} \Arg{false code}
% \end{syntax}
-% Stores each \meta{item} of the \meta{token list} in turn in the
-% (token list) \meta{variable} and applies the \meta{code}. The
-% \meta{code} will usually make use of the \meta{variable}, but this
-% is not enforced. The assignments to the \meta{variable} are local.
-% Its value after the loop is the last \meta{item} in the
-% \meta{tl~var}, or its original value if the \meta{tl~var} is blank.
-% See also \cs{tl_map_inline:nn}.
+% Tests if the first \meta{token} in the \meta{token list}
+% is a normal \texttt{N}-type argument. In other words,
+% it is neither an explicit space character
+% (explicit token with character code~$32$ and category code~$10$)
+% nor an explicit begin-group character
+% (with category code~1 and any character code). An empty
+% argument yields \texttt{false}, as it does not have a normal
+% first token.
+% This function is useful to implement actions on token lists on
+% a token by token basis.
% \end{function}
%
-% \begin{function}[updated = 2012-06-29, rEXP]{\tl_map_break:}
+% \begin{function}[updated = 2012-07-08, EXP, pTF]{\tl_if_head_is_space:n}
% \begin{syntax}
-% \cs{tl_map_break:}
+% \cs{tl_if_head_is_space_p:n} \Arg{token list}
+% \cs{tl_if_head_is_space:nTF} \Arg{token list} \Arg{true code} \Arg{false code}
% \end{syntax}
-% Used to terminate a \cs[no-index]{tl_map_\ldots} function before all
-% entries in the \meta{token list variable} have been processed. This
-% normally takes place within a conditional statement, for example
-% \begin{verbatim}
-% \tl_map_inline:Nn \l_my_tl
-% {
-% \str_if_eq:nnT { #1 } { bingo } { \tl_map_break: }
-% % Do something useful
-% }
-% \end{verbatim}
-% See also \cs{tl_map_break:n}.
-% Use outside of a \cs[no-index]{tl_map_\ldots} scenario leads to low
-% level \TeX{} errors.
-% \begin{texnote}
-% When the mapping is broken, additional tokens may be inserted
-% before the \meta{tokens} are
-% inserted into the input stream.
-% This depends on the design of the mapping function.
-% \end{texnote}
+% Tests if the first \meta{token} in the \meta{token list}
+% is an explicit space character
+% (explicit token with character code~$12$ and category code~$10$).
+% In particular, the test is \texttt{false} if the \meta{token list}
+% starts with an implicit token such as \cs{c_space_token}, or if it
+% is empty.
+% This function is useful to implement actions on token lists on
+% a token by token basis.
% \end{function}
%
-% \begin{function}[updated = 2012-06-29, rEXP]{\tl_map_break:n}
-% \begin{syntax}
-% \cs{tl_map_break:n} \Arg{code}
-% \end{syntax}
-% Used to terminate a \cs[no-index]{tl_map_\ldots} function before all
-% entries in the \meta{token list variable} have been processed, inserting
-% the \meta{code} after the mapping has ended. This
-% normally takes place within a conditional statement, for example
-% \begin{verbatim}
-% \tl_map_inline:Nn \l_my_tl
-% {
-% \str_if_eq:nnT { #1 } { bingo }
-% { \tl_map_break:n { <code> } }
-% % Do something useful
-% }
-% \end{verbatim}
-% Use outside of a \cs[no-index]{tl_map_\ldots} scenario leads to low
-% level \TeX{} errors.
-% \begin{texnote}
-% When the mapping is broken, additional tokens may be inserted
-% before the \meta{code} is
-% inserted into the input stream.
-% This depends on the design of the mapping function.
-% \end{texnote}
-% \end{function}
+% \section{Working with token lists as a whole}
%
-% \section{Using token lists}
+% \subsection{Using token lists}
%
% \begin{function}[EXP]{\tl_to_str:n, \tl_to_str:V}
% \begin{syntax}
@@ -733,7 +521,7 @@
% a \meta{tl~var} directly without an accessor function.
% \end{function}
%
-% \section{Working with the content of token lists}
+% \subsection{Counting and reversing token lists}
%
% \begin{function}[added = 2012-05-13, EXP]
% {\tl_count:n, \tl_count:V, \tl_count:o}
@@ -752,7 +540,7 @@
% \begin{syntax}
% \cs{tl_count:N} \meta{tl~var}
% \end{syntax}
-% Counts the number of token groups in the \meta{tl~var}
+% Counts the number of \meta{items} in the \meta{tl~var}
% and leaves this information in the input stream. Unbraced tokens
% count as one element as do each token group (|{|\ldots|}|). This
% process ignores any unprotected spaces within the \meta{tl~var}.
@@ -867,36 +655,194 @@
% \emph{resets} the content of the variable.
% \end{function}
%
-% \begin{function}[added = 2017-02-06]
-% {\tl_sort:Nn, \tl_sort:cn, \tl_gsort:Nn, \tl_gsort:cn}
+% \subsection{Viewing token lists}
+%
+% \begin{function}[updated = 2021-04-29]{\tl_show:N, \tl_show:c}
% \begin{syntax}
-% \cs{tl_sort:Nn} \meta{tl var} \Arg{comparison code}
+% \cs{tl_show:N} \meta{tl~var}
% \end{syntax}
-% Sorts the items in the \meta{tl var} according to the
-% \meta{comparison code}, and assigns the result to
-% \meta{tl var}. The details of sorting comparison are
-% described in Section~\ref{sec:l3sort:mech}.
+% Displays the content of the \meta{tl~var} on the terminal.
+% \begin{texnote}
+% This is similar to the \TeX{} primitive \tn{show}, wrapped to a
+% fixed number of characters per line.
+% \end{texnote}
% \end{function}
%
-% \begin{function}[added = 2017-02-06, EXP]{\tl_sort:nN}
+% \begin{function}[updated = 2015-08-07]{\tl_show:n}
% \begin{syntax}
-% \cs{tl_sort:nN} \Arg{token list} \meta{conditional}
+% \cs{tl_show:n} \Arg{token list}
% \end{syntax}
-% Sorts the items in the \meta{token list}, using the
-% \meta{conditional} to compare items, and leaves the result in the
-% input stream. The \meta{conditional} should have signature |:nnTF|,
-% and return \texttt{true} if the two items being compared should be
-% left in the same order, and \texttt{false} if the items should be
-% swapped. The details of sorting comparison are
-% described in Section~\ref{sec:l3sort:mech}.
+% Displays the \meta{token list} on the terminal.
% \begin{texnote}
-% The result is returned within \cs{exp_not:n}, which means that the
-% token list does not expand further when appearing in an
-% \texttt{x}-type or \texttt{e}-type argument expansion.
+% This is similar to the \eTeX{} primitive \tn{showtokens}, wrapped
+% to a fixed number of characters per line.
+% \end{texnote}
+% \end{function}
+%
+% \begin{function}[added = 2014-08-22, updated = 2021-04-29]{\tl_log:N, \tl_log:c}
+% \begin{syntax}
+% \cs{tl_log:N} \meta{tl~var}
+% \end{syntax}
+% Writes the content of the \meta{tl~var} in the log file. See also
+% \cs{tl_show:N} which displays the result in the terminal.
+% \end{function}
+%
+% \begin{function}[added = 2014-08-22, updated = 2015-08-07]{\tl_log:n}
+% \begin{syntax}
+% \cs{tl_log:n} \Arg{token list}
+% \end{syntax}
+% Writes the \meta{token list} in the log file. See also
+% \cs{tl_show:n} which displays the result in the terminal.
+% \end{function}
+%
+% \section{Manipulating items in token lists}
+%
+% \subsection{Mapping over token lists}
+%
+% All mappings are done at the current group level, \emph{i.e.}~any
+% local assignments made by the \meta{function} or \meta{code} discussed
+% below remain in effect after the loop.
+%
+% \begin{function}[updated = 2012-06-29, rEXP]
+% {\tl_map_function:NN, \tl_map_function:cN}
+% \begin{syntax}
+% \cs{tl_map_function:NN} \meta{tl~var} \meta{function}
+% \end{syntax}
+% Applies \meta{function} to every \meta{item} in the \meta{tl~var}.
+% The \meta{function} receives one argument for each iteration.
+% This may be a number of tokens if the \meta{item} was stored within
+% braces. Hence the \meta{function} should anticipate receiving
+% \texttt{n}-type arguments. See also \cs{tl_map_function:nN}.
+% \end{function}
+%
+% \begin{function}[updated = 2012-06-29, rEXP]{\tl_map_function:nN}
+% \begin{syntax}
+% \cs{tl_map_function:nN} \Arg{token list} \meta{function}
+% \end{syntax}
+% Applies \meta{function} to every \meta{item} in the \meta{token list},
+% The \meta{function} receives one argument for each iteration.
+% This may be a number of tokens if the \meta{item} was stored within
+% braces. Hence the \meta{function} should anticipate receiving
+% \texttt{n}-type arguments. See also \cs{tl_map_function:NN}.
+% \end{function}
+%
+% \begin{function}[updated = 2012-06-29]
+% {\tl_map_inline:Nn, \tl_map_inline:cn}
+% \begin{syntax}
+% \cs{tl_map_inline:Nn} \meta{tl~var} \Arg{inline function}
+% \end{syntax}
+% Applies the \meta{inline function} to every \meta{item} stored within the
+% \meta{tl~var}. The \meta{inline function} should consist of code which
+% receives the \meta{item} as |#1|. See also \cs{tl_map_function:NN}.
+% \end{function}
+%
+% \begin{function}[updated = 2012-06-29]{\tl_map_inline:nn}
+% \begin{syntax}
+% \cs{tl_map_inline:nn} \Arg{token list} \Arg{inline function}
+% \end{syntax}
+% Applies the \meta{inline function} to every \meta{item} stored within the
+% \meta{token list}. The \meta{inline function} should consist of code which
+% receives the \meta{item} as |#1|. See also \cs{tl_map_function:nN}.
+% \end{function}
+%
+% \begin{function}[rEXP, added = 2019-09-02]
+% {\tl_map_tokens:Nn, \tl_map_tokens:cn, \tl_map_tokens:nn}
+% \begin{syntax}
+% \cs{tl_map_tokens:Nn} \meta{tl~var} \Arg{code}
+% \cs{tl_map_tokens:nn} \Arg{tokens} \Arg{code}
+% \end{syntax}
+% Analogue of \cs{tl_map_function:NN} which maps several tokens
+% instead of a single function. The \meta{code} receives each \meta{item} in
+% the \meta{tl~var} or in \meta{tokens} as a trailing brace group. For
+% instance,
+% \begin{verbatim}
+% \tl_map_tokens:Nn \l_my_tl { \prg_replicate:nn { 2 } }
+% \end{verbatim}
+% expands to twice each \meta{item} in the \meta{tl~var}: for each \meta{item} in
+% \cs[no-index]{l_my_tl} the function \cs{prg_replicate:nn} receives |2| and
+% \meta{item} as its two arguments. The function
+% \cs{tl_map_inline:Nn} is typically faster but is not expandable.
+% \end{function}
+%
+% \begin{function}[updated = 2012-06-29]
+% {\tl_map_variable:NNn, \tl_map_variable:cNn}
+% \begin{syntax}
+% \cs{tl_map_variable:NNn} \meta{tl~var} \meta{variable} \Arg{code}
+% \end{syntax}
+% Stores each \meta{item} of the \meta{tl~var} in turn in the (token
+% list) \meta{variable} and applies the \meta{code}. The \meta{code}
+% will usually make use of the \meta{variable}, but this is not
+% enforced. The assignments to the \meta{variable} are local. Its
+% value after the loop is the last \meta{item} in the \meta{tl~var},
+% or its original value if the \meta{tl~var} is blank. See also
+% \cs{tl_map_inline:Nn}.
+% \end{function}
+%
+% \begin{function}[updated = 2012-06-29]{\tl_map_variable:nNn}
+% \begin{syntax}
+% \cs{tl_map_variable:nNn} \Arg{token list} \meta{variable} \Arg{code}
+% \end{syntax}
+% Stores each \meta{item} of the \meta{token list} in turn in the
+% (token list) \meta{variable} and applies the \meta{code}. The
+% \meta{code} will usually make use of the \meta{variable}, but this
+% is not enforced. The assignments to the \meta{variable} are local.
+% Its value after the loop is the last \meta{item} in the
+% \meta{tl~var}, or its original value if the \meta{tl~var} is blank.
+% See also \cs{tl_map_inline:nn}.
+% \end{function}
+%
+% \begin{function}[updated = 2012-06-29, rEXP]{\tl_map_break:}
+% \begin{syntax}
+% \cs{tl_map_break:}
+% \end{syntax}
+% Used to terminate a \cs[no-index]{tl_map_\ldots} function before all
+% entries in the \meta{token list variable} have been processed. This
+% normally takes place within a conditional statement, for example
+% \begin{verbatim}
+% \tl_map_inline:Nn \l_my_tl
+% {
+% \str_if_eq:nnT { #1 } { bingo } { \tl_map_break: }
+% % Do something useful
+% }
+% \end{verbatim}
+% See also \cs{tl_map_break:n}.
+% Use outside of a \cs[no-index]{tl_map_\ldots} scenario leads to low
+% level \TeX{} errors.
+% \begin{texnote}
+% When the mapping is broken, additional tokens may be inserted
+% before the \meta{tokens} are
+% inserted into the input stream.
+% This depends on the design of the mapping function.
% \end{texnote}
% \end{function}
%
-% \section{The first token from a token list}
+% \begin{function}[updated = 2012-06-29, rEXP]{\tl_map_break:n}
+% \begin{syntax}
+% \cs{tl_map_break:n} \Arg{code}
+% \end{syntax}
+% Used to terminate a \cs[no-index]{tl_map_\ldots} function before all
+% entries in the \meta{token list variable} have been processed, inserting
+% the \meta{code} after the mapping has ended. This
+% normally takes place within a conditional statement, for example
+% \begin{verbatim}
+% \tl_map_inline:Nn \l_my_tl
+% {
+% \str_if_eq:nnT { #1 } { bingo }
+% { \tl_map_break:n { <code> } }
+% % Do something useful
+% }
+% \end{verbatim}
+% Use outside of a \cs[no-index]{tl_map_\ldots} scenario leads to low
+% level \TeX{} errors.
+% \begin{texnote}
+% When the mapping is broken, additional tokens may be inserted
+% before the \meta{code} is
+% inserted into the input stream.
+% This depends on the design of the mapping function.
+% \end{texnote}
+% \end{function}
+%
+% \subsection{Head and tail of token lists}
%
% Functions which deal with either only the very first item (balanced
% text or single normal token) in a token list, or the remaining tokens.
@@ -979,89 +925,7 @@
% \end{texnote}
% \end{function}
%
-% \begin{function}[updated = 2012-07-09, EXP, pTF]
-% {\tl_if_head_eq_catcode:nN, \tl_if_head_eq_catcode:oN}
-% \begin{syntax}
-% \cs{tl_if_head_eq_catcode_p:nN} \Arg{token list} \meta{test token}
-% \cs{tl_if_head_eq_catcode:nNTF} \Arg{token list} \meta{test token}
-% ~~\Arg{true code} \Arg{false code}
-% \end{syntax}
-% Tests if the first \meta{token} in the \meta{token list} has the
-% same category code as the \meta{test token}. In the case where the
-% \meta{token list} is empty, the test is always \texttt{false}.
-% \end{function}
-%
-% \begin{function}[updated = 2012-07-09, EXP, pTF]
-% {\tl_if_head_eq_charcode:nN, \tl_if_head_eq_charcode:fN}
-% \begin{syntax}
-% \cs{tl_if_head_eq_charcode_p:nN} \Arg{token list} \meta{test token}
-% \cs{tl_if_head_eq_charcode:nNTF} \Arg{token list} \meta{test token}
-% ~~\Arg{true code} \Arg{false code}
-% \end{syntax}
-% Tests if the first \meta{token} in the \meta{token list} has the
-% same character code as the \meta{test token}. In the case where the
-% \meta{token list} is empty, the test is always \texttt{false}.
-% \end{function}
-%
-% \begin{function}[updated = 2012-07-09, EXP, pTF]{\tl_if_head_eq_meaning:nN}
-% \begin{syntax}
-% \cs{tl_if_head_eq_meaning_p:nN} \Arg{token list} \meta{test token}
-% \cs{tl_if_head_eq_meaning:nNTF} \Arg{token list} \meta{test token}
-% ~~\Arg{true code} \Arg{false code}
-% \end{syntax}
-% Tests if the first \meta{token} in the \meta{token list} has the
-% same meaning as the \meta{test token}. In the case where
-% \meta{token list} is empty, the test is always \texttt{false}.
-% \end{function}
-%
-% \begin{function}[added = 2012-07-08, EXP, pTF]{\tl_if_head_is_group:n}
-% \begin{syntax}
-% \cs{tl_if_head_is_group_p:n} \Arg{token list}
-% \cs{tl_if_head_is_group:nTF} \Arg{token list} \Arg{true code} \Arg{false code}
-% \end{syntax}
-% Tests if the first \meta{token} in the \meta{token list}
-% is an explicit begin-group character (with category code~$1$
-% and any character code), in other words, if the \meta{token list}
-% starts with a brace group. In particular, the test is \texttt{false}
-% if the \meta{token list} starts with an implicit token such as
-% \cs{c_group_begin_token}, or if it is empty.
-% This function is useful to implement actions on token lists on
-% a token by token basis.
-% \end{function}
-%
-% \begin{function}[added = 2012-07-08, EXP, pTF]{\tl_if_head_is_N_type:n}
-% \begin{syntax}
-% \cs{tl_if_head_is_N_type_p:n} \Arg{token list}
-% \cs{tl_if_head_is_N_type:nTF} \Arg{token list} \Arg{true code} \Arg{false code}
-% \end{syntax}
-% Tests if the first \meta{token} in the \meta{token list}
-% is a normal \texttt{N}-type argument. In other words,
-% it is neither an explicit space character
-% (explicit token with character code~$32$ and category code~$10$)
-% nor an explicit begin-group character
-% (with category code~1 and any character code). An empty
-% argument yields \texttt{false}, as it does not have a \enquote{normal}
-% first token.
-% This function is useful to implement actions on token lists on
-% a token by token basis.
-% \end{function}
-%
-% \begin{function}[updated = 2012-07-08, EXP, pTF]{\tl_if_head_is_space:n}
-% \begin{syntax}
-% \cs{tl_if_head_is_space_p:n} \Arg{token list}
-% \cs{tl_if_head_is_space:nTF} \Arg{token list} \Arg{true code} \Arg{false code}
-% \end{syntax}
-% Tests if the first \meta{token} in the \meta{token list}
-% is an explicit space character
-% (explicit token with character code~$12$ and category code~$10$).
-% In particular, the test is \texttt{false} if the \meta{token list}
-% starts with an implicit token such as \cs{c_space_token}, or if it
-% is empty.
-% This function is useful to implement actions on token lists on
-% a token by token basis.
-% \end{function}
-%
-% \section{Using a single item}
+% \subsection{Items and ranges in token lists}
%
% \begin{function}[added = 2014-07-17, EXP]
% {\tl_item:nn, \tl_item:Nn, \tl_item:cn}
@@ -1172,44 +1036,190 @@
% \end{texnote}
% \end{function}
%
-% \section{Viewing token lists}
+% \subsection{Sorting token lists}
%
-% \begin{function}[updated = 2021-04-29]{\tl_show:N, \tl_show:c}
+% \begin{function}[added = 2017-02-06]
+% {\tl_sort:Nn, \tl_sort:cn, \tl_gsort:Nn, \tl_gsort:cn}
% \begin{syntax}
-% \cs{tl_show:N} \meta{tl~var}
+% \cs{tl_sort:Nn} \meta{tl var} \Arg{comparison code}
% \end{syntax}
-% Displays the content of the \meta{tl~var} on the terminal.
-% \begin{texnote}
-% This is similar to the \TeX{} primitive \tn{show}, wrapped to a
-% fixed number of characters per line.
-% \end{texnote}
+% Sorts the items in the \meta{tl var} according to the
+% \meta{comparison code}, and assigns the result to
+% \meta{tl var}. The details of sorting comparison are
+% described in Section~\ref{sec:l3sort:mech}.
% \end{function}
%
-% \begin{function}[updated = 2015-08-07]{\tl_show:n}
+% \begin{function}[added = 2017-02-06, EXP]{\tl_sort:nN}
% \begin{syntax}
-% \cs{tl_show:n} \Arg{token list}
+% \cs{tl_sort:nN} \Arg{token list} \meta{conditional}
% \end{syntax}
-% Displays the \meta{token list} on the terminal.
+% Sorts the items in the \meta{token list}, using the
+% \meta{conditional} to compare items, and leaves the result in the
+% input stream. The \meta{conditional} should have signature |:nnTF|,
+% and return \texttt{true} if the two items being compared should be
+% left in the same order, and \texttt{false} if the items should be
+% swapped. The details of sorting comparison are
+% described in Section~\ref{sec:l3sort:mech}.
% \begin{texnote}
-% This is similar to the \eTeX{} primitive \tn{showtokens}, wrapped
-% to a fixed number of characters per line.
+% The result is returned within \cs{exp_not:n}, which means that the
+% token list does not expand further when appearing in an
+% \texttt{x}-type or \texttt{e}-type argument expansion.
% \end{texnote}
% \end{function}
%
-% \begin{function}[added = 2014-08-22, updated = 2021-04-29]{\tl_log:N, \tl_log:c}
+% \section{Manipulating tokens in token lists}
+%
+% \subsection{Replacing tokens}
+%
+% \begin{function}[updated = 2011-08-11]
+% {
+% \tl_replace_once:Nnn, \tl_replace_once:cnn,
+% \tl_greplace_once:Nnn, \tl_greplace_once:cnn
+% }
% \begin{syntax}
-% \cs{tl_log:N} \meta{tl~var}
+% \cs{tl_replace_once:Nnn} \meta{tl~var} \Arg{old tokens} \Arg{new tokens}
% \end{syntax}
-% Writes the content of the \meta{tl~var} in the log file. See also
-% \cs{tl_show:N} which displays the result in the terminal.
+% Replaces the first (leftmost) occurrence of \meta{old tokens} in the
+% \meta{tl~var} with \meta{new tokens}. \meta{Old tokens}
+% cannot contain |{|, |}| or |#|
+% (more precisely, explicit character tokens with category code $1$
+% (begin-group) or $2$ (end-group), and tokens with category code $6$).
% \end{function}
%
-% \begin{function}[added = 2014-08-22, updated = 2015-08-07]{\tl_log:n}
+% \begin{function}[updated = 2011-08-11]
+% {
+% \tl_replace_all:Nnn, \tl_replace_all:cnn,
+% \tl_greplace_all:Nnn, \tl_greplace_all:cnn
+% }
% \begin{syntax}
-% \cs{tl_log:n} \Arg{token list}
+% \cs{tl_replace_all:Nnn} \meta{tl~var} \Arg{old tokens} \Arg{new tokens}
% \end{syntax}
-% Writes the \meta{token list} in the log file. See also
-% \cs{tl_show:n} which displays the result in the terminal.
+% Replaces all occurrences of \meta{old tokens} in the
+% \meta{tl~var} with \meta{new tokens}. \meta{Old tokens}
+% cannot contain |{|, |}| or |#|
+% (more precisely, explicit character tokens with category code $1$
+% (begin-group) or $2$ (end-group), and tokens with category code $6$).
+% As this function
+% operates from left to right, the pattern \meta{old tokens}
+% may remain after the replacement (see \cs{tl_remove_all:Nn}
+% for an example).
+% \end{function}
+%
+% \begin{function}[updated = 2011-08-11]
+% {
+% \tl_remove_once:Nn, \tl_remove_once:cn,
+% \tl_gremove_once:Nn, \tl_gremove_once:cn
+% }
+% \begin{syntax}
+% \cs{tl_remove_once:Nn} \meta{tl~var} \Arg{tokens}
+% \end{syntax}
+% Removes the first (leftmost) occurrence of \meta{tokens} from the
+% \meta{tl~var}. \meta{Tokens} cannot contain |{|, |}| or |#|
+% (more precisely, explicit character tokens with category code $1$
+% (begin-group) or $2$ (end-group), and tokens with category code $6$).
+% \end{function}
+%
+% \begin{function}[updated = 2011-08-11]
+% {
+% \tl_remove_all:Nn, \tl_remove_all:cn,
+% \tl_gremove_all:Nn, \tl_gremove_all:cn
+% }
+% \begin{syntax}
+% \cs{tl_remove_all:Nn} \meta{tl~var} \Arg{tokens}
+% \end{syntax}
+% Removes all occurrences of \meta{tokens} from the
+% \meta{tl~var}. \meta{Tokens} cannot contain |{|, |}| or |#|
+% (more precisely, explicit character tokens with category code $1$
+% (begin-group) or $2$ (end-group), and tokens with category code $6$).
+% As this function
+% operates from left to right, the pattern \meta{tokens}
+% may remain after the removal, for instance,
+% \begin{quote}
+% \cs{tl_set:Nn} \cs{l_tmpa_tl} |{abbccd}|
+% \cs{tl_remove_all:Nn} \cs{l_tmpa_tl} |{bc}|
+% \end{quote}
+% results in \cs{l_tmpa_tl} containing \texttt{abcd}.
+% \end{function}
+%
+% \subsection{Reassigning category codes}
+%
+% These functions allow the rescanning of tokens: re-apply \TeX{}'s
+% tokenization process to apply category codes different from those
+% in force when the tokens were absorbed. Whilst this functionality is
+% supported, it is often preferable to find alternative approaches
+% to achieving outcomes rather than rescanning tokens (for example
+% construction of token lists token-by-token with intervening category
+% code changes or using \cs{char_generate:nn}).
+%
+% \begin{function}[updated = 2015-08-11]
+% {
+% \tl_set_rescan:Nnn, \tl_set_rescan:Nno, \tl_set_rescan:Nnx,
+% \tl_set_rescan:cnn, \tl_set_rescan:cno, \tl_set_rescan:cnx,
+% \tl_gset_rescan:Nnn, \tl_gset_rescan:Nno, \tl_gset_rescan:Nnx,
+% \tl_gset_rescan:cnn, \tl_gset_rescan:cno, \tl_gset_rescan:cnx
+% }
+% \begin{syntax}
+% \cs{tl_set_rescan:Nnn} \meta{tl~var} \Arg{setup} \Arg{tokens}
+% \end{syntax}
+% Sets \meta{tl~var} to contain \meta{tokens}, applying the category
+% code r\'{e}gime specified in the \meta{setup} before carrying out
+% the assignment. (Category codes applied to tokens not explicitly covered
+% by the \meta{setup} are those in force at the point of use of
+% \cs{tl_set_rescan:Nnn}.)
+% This allows the \meta{tl~var} to contain material
+% with category codes other than those that apply when \meta{tokens}
+% are absorbed. The \meta{setup} is run within a group and may
+% contain any valid input, although only changes in category codes,
+% such as uses of \cs{cctab_select:N},
+% are relevant. See also \cs{tl_rescan:nn}.
+% \begin{texnote}
+% The \meta{tokens} are first turned into a string (using
+% \cs{tl_to_str:n}). If the string contains one or more characters
+% with character code \tn{newlinechar} (set equal to
+% \tn{endlinechar} unless that is equal to $32$, before the user
+% \meta{setup}), then it is split into lines at these characters,
+% then read as if reading multiple lines from a file, ignoring
+% spaces (catcode $10$) at the beginning and spaces and tabs
+% (character code $32$ or $9$) at the end of every line.
+% Otherwise, spaces (and tabs) are retained at both ends of the
+% single-line string, as if it appeared in the middle of a line
+% read from a file.
+% \end{texnote}
+% \end{function}
+%
+% \begin{function}[updated = 2015-08-11]{\tl_rescan:nn}
+% \begin{syntax}
+% \cs{tl_rescan:nn} \Arg{setup} \Arg{tokens}
+% \end{syntax}
+% Rescans \meta{tokens} applying the category code r\'{e}gime
+% specified in the \meta{setup}, and leaves the resulting tokens in
+% the input stream. (Category codes applied to tokens not explicitly covered
+% by the \meta{setup} are those in force at the point of use of
+% \cs{tl_rescan:nn}.)
+% The \meta{setup} is run within a group and may
+% contain any valid input, although only changes in category codes,
+% such as uses of \cs{cctab_select:N},
+% are relevant. See also \cs{tl_set_rescan:Nnn}, which is more
+% robust than using \cs{tl_set:Nn} in the \meta{tokens} argument of
+% \cs{tl_rescan:nn}.
+% \begin{texnote}
+% The \meta{tokens} are first turned into a string (using
+% \cs{tl_to_str:n}). If the string contains one or more characters
+% with character code \tn{newlinechar} (set equal to
+% \tn{endlinechar} unless that is equal to $32$, before the user
+% \meta{setup}), then it is split into lines at these characters,
+% then read as if reading multiple lines from a file, ignoring
+% spaces (catcode $10$) at the beginning and spaces and tabs
+% (character code $32$ or $9$) at the end of every line.
+% Otherwise, spaces (and tabs) are retained at both ends of the
+% single-line string, as if it appeared in the middle of a line
+% read from a file.
+%
+% Contrarily to the \tn{scantokens} primitive, \cs{tl_rescan:nn}
+% tokenizes the whole string in the same category code regime rather
+% than one token at a time, so that directives such as \tn{verb}
+% that rely on changing category codes will not function properly.
+% \end{texnote}
% \end{function}
%
% \section{Constant token lists}
@@ -1442,7 +1452,7 @@
% By using \cs{exp_not:n} token list variables can contain |#| tokens,
% which makes the token list registers provided by \TeX{}
% more or less redundant. The \cs{tl_set:No} version is done
-% \enquote{by hand} as it is used quite a lot.
+% by hand as it is used quite a lot.
% \begin{macrocode}
\cs_new_protected:Npn \tl_set:Nn #1#2
{ \__kernel_tl_set:Nx #1 { \__kernel_exp_not:w {#2} } }
@@ -2289,7 +2299,7 @@
% The \cs{if_false:} constructions are a faster way to do
% \cs{group_align_safe_begin:} and \cs{group_align_safe_end:}.
% The \cs{scan_stop:} ensures that \texttt{f}-expanding
-% \cs{tl_if_in:nn} does not lead to unbalanced braces.
+% \cs{tl_if_in:nnTF} does not lead to unbalanced braces.
% \begin{macrocode}
\prg_new_protected_conditional:Npnn \tl_if_in:nn #1#2 { T , F , TF }
{
@@ -2335,7 +2345,7 @@
% \end{macro}
%
% \begin{macro}[EXP,pTF]{\tl_if_single:N}
-% Expand the token list and feed it to \cs{tl_if_single:n}.
+% Expand the token list and feed it to \cs{tl_if_single:nTF}.
% \begin{macrocode}
\cs_new:Npn \tl_if_single_p:N { \exp_args:No \tl_if_single_p:n }
\cs_new:Npn \tl_if_single:NT { \exp_args:No \tl_if_single:nT }