[latex3-commits] [latex3/latex3] main: Add comment of deprecated `\tl_case:Nn(TF)` to `\str_case:nn(TF)` (f708f65e3)

[github at latex-project.org]

Repository : https://github.com/latex3/latex3
On branch  : main
Link       : https://github.com/latex3/latex3/commit/f708f65e3312f7082c1139346d00623935c8eb69

>---------------------------------------------------------------

commit f708f65e3312f7082c1139346d00623935c8eb69
Author: Yukai Chou <muzimuzhi at gmail.com>
Date:   Sat Nov 4 19:37:32 2023 +0800

    Add comment of deprecated `\tl_case:Nn(TF)` to `\str_case:nn(TF)`
    
    That's the only copy of comment explaining case implementation.
    
    See commit abae0829 (Deprecate \tl_case:Nn(TF), 2023-05-23).


>---------------------------------------------------------------

f708f65e3312f7082c1139346d00623935c8eb69
 l3kernel/l3int.dtx            |  2 +-
 l3kernel/l3prg.dtx            |  2 +-
 l3kernel/l3str.dtx            | 21 +++++++++++++++++++--
 l3trial/l3bigint/l3bigint.dtx |  2 +-
 4 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/l3kernel/l3int.dtx b/l3kernel/l3int.dtx
index b658aedd8..8889194e4 100644
--- a/l3kernel/l3int.dtx
+++ b/l3kernel/l3int.dtx
@@ -1761,7 +1761,7 @@
 % \begin{macro}{\@@_case:nw, \@@_case_end:nw}
 %   For integer cases, the first task to fully expand the check
 %   condition. The over all idea is then much the same as for
-%   \cs{tl_case:nnTF} as described in \pkg{l3tl}.
+%   \cs{str_case:nnTF} as described in \pkg{l3str}.
 %    \begin{macrocode}
 \cs_new:Npn \int_case:nnTF #1
   {
diff --git a/l3kernel/l3prg.dtx b/l3kernel/l3prg.dtx
index f57c433fd..328ec1911 100644
--- a/l3kernel/l3prg.dtx
+++ b/l3kernel/l3prg.dtx
@@ -1546,7 +1546,7 @@
 % \begin{macro}{\@@_case:NnTF}
 % \begin{macro}{\@@_case:w,a\@@_case_end:nw}
 %   For boolean cases the overall idea is the same as for
-%   \cs{tl_case:nnTF} as described in \pkg{l3tl}.
+%   \cs{str_case:nnTF} as described in \pkg{l3str}.
 %    \begin{macrocode}
 \cs_new:Npn \bool_case:nTF
   { \exp:w \@@_case:nTF }
diff --git a/l3kernel/l3str.dtx b/l3kernel/l3str.dtx
index 2727dab88..05a6b3aae 100644
--- a/l3kernel/l3str.dtx
+++ b/l3kernel/l3str.dtx
@@ -1240,8 +1240,13 @@
 % \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
   {
@@ -1308,6 +1313,18 @@
       { \@@_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}
diff --git a/l3trial/l3bigint/l3bigint.dtx b/l3trial/l3bigint/l3bigint.dtx
index 9e54406f3..db35c2710 100644
--- a/l3trial/l3bigint/l3bigint.dtx
+++ b/l3trial/l3bigint/l3bigint.dtx
@@ -2501,7 +2501,7 @@
 %   comparison is not done with \cs{bigint_compare:nNnTF} because it
 %   would repeatedly parse the number to compare.  Instead, we rely on
 %   uniqueness of the decimal representation.
-%   This code is inspired from the code of \cs{tl_case:Nn}(TF).
+%   This code is inspired from the code of \cs{str_case:nnTF}.
 %    \begin{macrocode}
 \cs_new:Npn \bigint_case:nnTF #1
   {