diff options
Diffstat (limited to 'macros/latex/contrib/l3kernel/l3str.dtx')
-rw-r--r-- | macros/latex/contrib/l3kernel/l3str.dtx | 44 |
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} |