summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/l3kernel/l3str.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/l3kernel/l3str.dtx')
-rw-r--r--macros/latex/contrib/l3kernel/l3str.dtx44
1 files changed, 32 insertions, 12 deletions
diff --git a/macros/latex/contrib/l3kernel/l3str.dtx b/macros/latex/contrib/l3kernel/l3str.dtx
index 6aca45dae0..4ebc1af703 100644
--- a/macros/latex/contrib/l3kernel/l3str.dtx
+++ b/macros/latex/contrib/l3kernel/l3str.dtx
@@ -43,7 +43,7 @@
% }^^A
% }
%
-% \date{Released 2023-11-01}
+% \date{Released 2023-11-09}
%
% \maketitle
%
@@ -299,7 +299,7 @@
% ~~\Arg{false code}
% \end{syntax}
% Compares the \meta{test string} in turn with each
-% of the \meta{string cases} (all token lists are converted to strings).
+% of the \meta{string case}s (all token lists are converted to strings).
% If the two are equal (as described for
% \cs{str_if_eq:nnTF}) then the associated \meta{code} is left in the
% input stream and other cases are discarded. If any of the
@@ -312,11 +312,12 @@
% This set of functions performs no expansion on each
% \meta{string~case} argument, so any variable in there will be
% compared as a string. If expansion is needed in the
-% \meta{string~cases}, then \cs[no-index]{str_case_e:nn(TF)} should
+% \meta{string~case}s, then \cs[no-index]{str_case_e:nn(TF)} should
% be used instead.
% \end{function}
%
-% \begin{function}[added = 2018-06-19, EXP, noTF]{\str_case_e:nn}
+% \begin{function}[added = 2018-06-19, EXP, noTF]
+% {\str_case_e:nn, \str_case_e:en}
% \begin{syntax}
% \cs{str_case_e:nnTF} \Arg{test string} \\
% ~~|{| \\
@@ -329,9 +330,9 @@
% ~~\Arg{false code}
% \end{syntax}
% Compares the full expansion of the \meta{test string}
-% in turn with the full expansion of the \meta{string cases}
+% in turn with the full expansion of the \meta{string case}s
% (all token lists are converted to strings). If the two
-% full expansions are equal (as described for \cs{str_if_eq:nnTF}) then the
+% full expansions are equal (as described for \cs{str_if_eq:eeTF}) then the
% associated \meta{code} is left in the input stream
% and other cases are discarded. If any of the
% cases are matched, the \meta{true code} is also inserted into the
@@ -339,9 +340,9 @@
% match then the \meta{false code} is inserted. The function
% \cs{str_case_e:nn}, which does nothing if there is no match, is also
% available.
-% The \meta{test string} is expanded in each comparison, and must
-% always yield the same result: for example, random numbers must
-% not be used within this string.
+% In \cs[index=str_case_e:nnTF]{str_case_e:nn(TF)}, the \meta{test string}
+% is expanded in each comparison, and must always yield the same result:
+% for example, random numbers must not be used within this string.
% \end{function}
%
% \begin{function}[EXP, pTF, added = 2021-05-17]{\str_compare:nNn, \str_compare:eNe}
@@ -1234,13 +1235,18 @@
% \begin{macro}[EXP, noTF]
% {
% \str_case:nn, \str_case:Vn, \str_case:Nn, \str_case:on, \str_case:en, \str_case:nV, \str_case:nv,
-% \str_case_e:nn
+% \str_case_e:nn, \str_case_e:en
% }
% \begin{macro}[EXP]{\@@_case:nnTF, \@@_case_e:nnTF}
% \begin{macro}[EXP]
% {\@@_case:nw, \@@_case_e:nw, \@@_case_end:nw}
-% Much the same as \cs{tl_case:nnTF} here:
-% just a change in the internal comparison.
+% The aim here is to allow the case statement to be evaluated
+% using a known number of expansion steps (two), and without
+% needing to use an explicit \enquote{end of recursion} marker.
+% That is achieved by using the test input as the final case,
+% as this is always true. The trick is then to tidy up
+% the output such that the appropriate case code plus either
+% the \texttt{true} or \texttt{false} branch code is inserted.
% \begin{macrocode}
\cs_new:Npn \str_case:nn #1#2
{
@@ -1299,12 +1305,26 @@
}
\cs_new:Npn \@@_case_e:nnTF #1#2#3#4
{ \@@_case_e:nw {#1} #2 {#1} { } \s_@@_mark {#3} \s_@@_mark {#4} \s_@@_stop }
+\cs_generate_variant:Nn \str_case_e:nn { e }
+\prg_generate_conditional_variant:Nnn \str_case_e:nn { e } { T , F , TF }
\cs_new:Npn \@@_case_e:nw #1#2#3
{
\str_if_eq:eeTF {#1} {#2}
{ \@@_case_end:nw {#3} }
{ \@@_case_e:nw {#1} }
}
+% \end{macrocode}
+% To tidy up the recursion, there are two outcomes. If there was a hit to
+% one of the cases searched for, then |#1| is the code to insert,
+% |#2| is the \emph{next} case to check on and |#3| is all of
+% the rest of the cases code. That means that |#4| is the \texttt{true}
+% branch code, and |#5| tidies up the spare \cs{s_@@_mark} and the
+% \texttt{false} branch. On the other hand, if none of the cases matched
+% then we arrive here using the \enquote{termination} case of comparing
+% the search with itself. That means that |#1| is empty, |#2| is
+% the first \cs{s_@@_mark} and so |#4| is the \texttt{false} code (the
+% \texttt{true} code is mopped up by |#3|).
+% \begin{macrocode}
\cs_new:Npn \@@_case_end:nw #1#2#3 \s_@@_mark #4#5 \s_@@_stop
{ \exp_end: #1 #4 }
% \end{macrocode}