[latex3-commits] [git/LaTeX3-latex3-latex3] main: Implement \str_compare:nNnTF (fixes #927) (b6c8f74df)

[Bruno Le Floch]

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

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

commit b6c8f74df70f298203cfb5ce8cf71b8cd659fcbc
Author: Bruno Le Floch <blflatex at gmail.com>
Date:   Mon May 17 23:53:03 2021 +0200

    Implement \str_compare:nNnTF (fixes #927)


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

b6c8f74df70f298203cfb5ce8cf71b8cd659fcbc
 l3kernel/CHANGELOG.md           |  1 +
 l3kernel/l3str.dtx              | 47 +++++++++++++++++++++++++++++++++++++++++
 l3kernel/testfiles/m3str001.lvt | 21 ++++++++++++++++++
 l3kernel/testfiles/m3str001.tlg | 16 ++++++++++++++
 4 files changed, 85 insertions(+)

diff --git a/l3kernel/CHANGELOG.md b/l3kernel/CHANGELOG.md
index 5b3140012..964d49bc8 100644
--- a/l3kernel/CHANGELOG.md
+++ b/l3kernel/CHANGELOG.md
@@ -8,6 +8,7 @@ this project uses date-based 'snapshot' version identifiers.
 ## [Unreleased]
 
 ### Added
+- `\str_compare:nNnTF` (issue #927)
 - `\sys_timer:`
 - `\prop_concat:NNN`, `\prop_put_from_keyval:Nn` (issue #924)
 - Functions to show and log various datatypes (issue #241):
diff --git a/l3kernel/l3str.dtx b/l3kernel/l3str.dtx
index aecd6d3c0..49ee60b33 100644
--- a/l3kernel/l3str.dtx
+++ b/l3kernel/l3str.dtx
@@ -401,6 +401,34 @@
 %   not be used within this string.
 % \end{function}
 %
+% \begin{function}[EXP, pTF, added = 2021-05-17]{\str_compare:nNn, \str_compare:eNe}
+%   \begin{syntax}
+%     \cs{str_compare_p:nNn} \Arg{tl_1} \meta{relation} \Arg{tl_2}
+%     \cs{str_compare:nNnTF} \Arg{tl_1} \meta{relation} \Arg{tl_2} \Arg{true code} \Arg{false code}
+%   \end{syntax}
+%   Compares the two \meta{token lists} on a character by character
+%   basis (namely after converting them to strings) in a lexicographic
+%   order according to the character codes of the characters.  The
+%   \meta{relation} can be |<|, |=|, or~|>| and the test is
+%   \texttt{true} under the following conditions:
+%   \begin{itemize}
+%     \item for |<|, if the first string is earlier than the second in lexicographic order;
+%     \item for |=|, if the two strings have exactly the same characters;
+%     \item for |>|, if the first string is later than the second in lexicographic order.
+%   \end{itemize}
+%   Thus for example the following is logically \texttt{true}:
+%   \begin{verbatim}
+%     \str_compare_p:nNn { ab } < { abc }
+%   \end{verbatim}
+%   \begin{texnote}
+%     This is a wrapper around the \TeX{} primitive
+%     \cs[index=pdfstrcmp]{(pdf)strcmp}.  It is meant for programming
+%     and not for sorting textual contents, as it simply considers
+%     character codes and not more elaborate considerations of grapheme
+%     clusters, locale, etc.
+%   \end{texnote}
+% \end{function}
+%
 % \section{Mapping over strings}
 %
 % All mappings are done at the current group level, \emph{i.e.}~any
@@ -1109,6 +1137,25 @@
 %    \end{macrocode}
 % \end{macro}
 %
+% \begin{macro}[pTF, EXP]{\str_compare:nNn, \str_compare:eNe}
+%   Simply rely on \cs{@@_if_eq:nn}, which expands to |-1|, |0|
+%   or~|1|.  The |ee| version is created directly because it is more efficient.
+%    \begin{macrocode}
+\prg_new_conditional:Npnn \str_compare:nNn #1#2#3 { p , T , F , TF }
+  {
+    \if_int_compare:w
+      \@@_if_eq:nn { \exp_not:n {#1} } { \exp_not:n {#3} }
+      #2 0 \exp_stop_f:
+      \prg_return_true: \else: \prg_return_false: \fi:
+  }
+\prg_new_conditional:Npnn \str_compare:eNe #1#2#3 { p , T , F , TF }
+  {
+    \if_int_compare:w \@@_if_eq:nn {#1} {#3} #2 0 \exp_stop_f:
+      \prg_return_true: \else: \prg_return_false: \fi:
+  }
+%    \end{macrocode}
+% \end{macro}
+%
 % \begin{macro}[pTF, EXP]
 %   {
 %     \str_if_eq:nn, \str_if_eq:Vn, \str_if_eq:on, \str_if_eq:nV,
diff --git a/l3kernel/testfiles/m3str001.lvt b/l3kernel/testfiles/m3str001.lvt
index 1158414ab..d434d4541 100644
--- a/l3kernel/testfiles/m3str001.lvt
+++ b/l3kernel/testfiles/m3str001.lvt
@@ -127,5 +127,26 @@
     \TYPE { \g_tmpa_str }
   }
 
+\tl_set:Nn \l_tmpa_tl { abc }
+\TESTEXP { str_compare:nNnTF }
+  {
+    \str_compare:nNnTF { ab }         < { abc } { \TRUE  } { \ERROR } \NEWLINE
+    \str_compare:nNnTF { \l_tmpa_tl } = { abc } { \ERROR } { \FALSE } \NEWLINE
+    \str_compare:nNnTF { \par }       > { abc } { \ERROR } { \FALSE } \NEWLINE
+    \str_compare:nNnTF { # }          < { # }   { \ERROR } { \FALSE } \NEWLINE
+    \SEPARATOR
+    \NEWLINE
+    \str_compare:eNeT { abc }        = { abc } { \TRUE  }  \NEWLINE
+    \str_compare:eNeT { \l_tmpa_tl } > { abc } { \ERROR } \NEWLINE
+    \str_compare:eNeT { \par }       < { abc } { \TRUE  } \NEWLINE
+    \str_compare:eNeT { # }          = { # }   { \TRUE  } \NEWLINE
+    \SEPARATOR
+    \NEWLINE
+    \str_compare:nNnF { abc }        > { abc } { \FALSE } \NEWLINE
+    \str_compare:nNnF { \l_tmpa_tl } < { abc } { \ERROR } \NEWLINE
+    \str_compare:nNnF { \par }       = { abc } { \FALSE } \NEWLINE
+    \str_compare:nNnF { # }          > { # }   { \FALSE } \NEWLINE
+  }
+
 \END
 
diff --git a/l3kernel/testfiles/m3str001.tlg b/l3kernel/testfiles/m3str001.tlg
index 6ba5d6788..d697f32a4 100644
--- a/l3kernel/testfiles/m3str001.tlg
+++ b/l3kernel/testfiles/m3str001.tlg
@@ -67,3 +67,19 @@ a{bb}cc dd zzyy \xx ##\q_mark \q_stop \par \par ####cdzyx{y}
 a{bb}cc dd zzyy \xx ##=/mark=\q_stop \par \par ####cdzyx{y}
 a{bb}cc dd zzyy \xx ##=/mark=\q_stop  ##{}\par /  ##{}\par / ####cdzyx{y}
 ============================================================
+============================================================
+TEST 8: str_compare:nNnTF
+============================================================
+TRUE
+FALSE
+FALSE
+FALSE
+============================================================
+TRUE
+TRUE
+TRUE
+============================================================
+FALSE
+FALSE
+FALSE
+============================================================