Deprecated \tl_sort:nN for \tl_sort_use:nN

See #914
latex3 · May 19, 2023 · 106c200 · 106c200
1 parent e72de1e
commit 106c200
Show file tree

Hide file tree

Showing 6 changed files with 26 additions and 14 deletions.
diff --git a/l3kernel/CHANGELOG.md b/l3kernel/CHANGELOG.md
@@ -13,10 +13,14 @@ this project uses date-based 'snapshot' version identifiers.
 - `\coffin_(g)reset_poles:N`
 - `\int_if_zero:n(TF)`
 - `\str_mdfive_hash:n`
+-  `\tl_sort_use:nN` (was `\tl_sort:nN`)
 
 ### Changed
 - Remove `\noexpand` inside math mode in `\text_expand:n`
 
+## Deprecated
+- `\tl_sort:nN`, replaced by `\tl_sort_use:nN` (issue \#914)
+
 ### Fixed
 - Omit `0123456789` from URL escaping (issue \#838)
 - Leave implicit chars unchanged in `\text_expand:n` (issue \#874)

diff --git a/l3kernel/doc/l3obsolete.txt b/l3kernel/doc/l3obsolete.txt
@@ -57,6 +57,7 @@ Function                            Date deprecated
 \tl_lower_case:nn                        2020-01-03
 \tl_mixed_case:n                         2020-01-03
 \tl_mixed_case:nn                        2020-01-03
+\tl_sort:nN                              2023-05-19
 \tl_upper_case:n                         2020-01-03
 \tl_upper_case:nn                        2020-01-03
 ---------------------------------------------------

diff --git a/l3kernel/l3deprecation.dtx b/l3kernel/l3deprecation.dtx
@@ -583,6 +583,13 @@
 %    \end{macrocode}
 % \end{macro}
 %
+% \begin{macro}{\tl_sort:nN}
+%    \begin{macrocode}
+\__kernel_patch_deprecation:nnNNpn { 2023-05-19 } { \tl_sort_use:nN }
+\cs_gset:Npn \tl_sort:nN { \tl_sort_use:nN }
+%    \end{macrocode}
+% \end{macro}
+%
 % \subsection{Deprecated \pkg{l3token} functions}
 %
 % \begin{macro}[EXP]{\char_to_utfviii_bytes:n}

diff --git a/l3kernel/l3sort.dtx b/l3kernel/l3sort.dtx
@@ -691,12 +691,12 @@
 % greater or equal to |#4|, 3.~comparison, 4.~pivot, 5.~next item to
 % test.  If |#5| is the tail of the list, call \cs{tl_sort:nN} on |#1|
 % and on |#2|, placing |#4| in between; |\use:ff| expands the parts to
-% make \cs{tl_sort:nN} \texttt{f}-expandable.  Otherwise, compare |#4|
+% make \cs{tl_sort_use:nN} \texttt{f}-expandable.  Otherwise, compare |#4|
 % and |#5| using |#3|.  If they are ordered, place |#5| amongst the
 % \enquote{greater} items, otherwise amongst the \enquote{lesser} items,
 % and continue partitioning.
 % \begin{verbatim}
-% \cs_new:Npn \tl_sort:nN #1#2
+% \cs_new:Npn \tl_sort_use:nN #1#2
 %   {
 %     \tl_if_blank:nF {#1}
 %       {
@@ -707,7 +707,7 @@
 % \cs_new:Npn \__sort:nnNnn #1#2#3#4#5
 %   {
 %     \quark_if_recursion_tail_stop_do:nn {#5}
-%       { \use:ff { \tl_sort:nN {#1} #3 {#4} } { \tl_sort:nN {#2} #3 } }
+%       { \use:ff { \tl_sort_use:nN {#1} #3 {#4} } { \tl_sort_use:nN {#2} #3 } }
 %     #3 {#4} {#5}
 %       { \__sort:nnNnn {#1} { #2 {#5} } #3 {#4} }
 %       { \__sort:nnNnn { #1 {#5} } {#2} #3 {#4} }
@@ -790,7 +790,7 @@
 % after code that sorts the smaller items, and after the (braced)
 % \meta{pivot}.
 %
-% The fourth speed up is avoid the recursive call to \cs{tl_sort:nN}
+% The fourth speed up is avoid the recursive call to \cs{tl_sort_use:nN}
 % with an empty first argument.  For this, we introduce functions
 % similar to the \cs{@@_i:nnnnNn} of the last example, but aware of
 % whether the list of \meta{conditional} \Arg{item} read so far that are
@@ -821,7 +821,7 @@
 % sorting lists of more than a few thousand items would exhaust a
 % typical \TeX{}'s memory.
 %
-% \begin{macro}[EXP]{\tl_sort:nN}
+% \begin{macro}[EXP]{\tl_sort_use:nN}
 % \begin{macro}[EXP]
 %   {
 %     \@@_quick_prepare:Nnnn,
@@ -844,7 +844,7 @@
 %   \cs{s_@@_stop} and leaving \cs{exp_stop_f:} to stop
 %   \texttt{f}-expansion.
 %    \begin{macrocode}
-\cs_new:Npn \tl_sort:nN #1#2
+\cs_new:Npn \tl_sort_use:nN #1#2
   {
     \exp_not:f
       {

diff --git a/l3kernel/l3tl.dtx b/l3kernel/l3tl.dtx
@@ -1069,9 +1069,9 @@
 %   described in Section~\ref{sec:l3sort:mech}.
 % \end{function}
 %
-% \begin{function}[added = 2017-02-06, EXP]{\tl_sort:nN}
+% \begin{function}[added = 2023-05-19, EXP]{\tl_sort_use:nN}
 %   \begin{syntax}
-%     \cs{tl_sort:nN} \Arg{token list} \meta{conditional}
+%     \cs{tl_sort_use:nN} \Arg{token list} \meta{conditional}
 %   \end{syntax}
 %   Sorts the items in the \meta{token list}, using the
 %   \meta{conditional} to compare items, and leaves the result in the
@@ -2866,7 +2866,7 @@
 % \end{macro}
 %
 % \begin{macro}
-%   {\tl_sort:Nn, \tl_sort:cn, \tl_gsort:Nn, \tl_gsort:cn, \tl_sort:nN}
+%   {\tl_sort:Nn, \tl_sort:cn, \tl_gsort:Nn, \tl_gsort:cn, \tl_sort_use:nN}
 %   Implemented in \pkg{l3sort}.
 % \end{macro}
 %

diff --git a/l3kernel/testfiles/m3sort002.lvt b/l3kernel/testfiles/m3sort002.lvt
@@ -25,13 +25,13 @@
 
 \TESTEXP { Sort~expandably }
   {
-    | \tl_sort:nN { } \ERROR |
+    | \tl_sort_use:nN { } \ERROR |
     \NEWLINE
-    \tl_sort:nN { {a\par b} } \ERROR
+    \tl_sort_use:nN { {a\par b} } \ERROR
     \NEWLINE
-    \tl_sort:nN { 8{+2}3461{-0}2{00}3748 } \test_compare:nnTF
+    \tl_sort_use:nN { 8{+2}3461{-0}2{00}3748 } \test_compare:nnTF
     \NEWLINE
-    \exp_args:Nf \tl_sort:nN
+    \exp_args:Nf \tl_sort_use:nN
       { \prg_replicate:nn { 10 } { 8{+2}3461{-0}2{00}3748 } }
       \test_compare:nnTF
   }
@@ -50,7 +50,7 @@
 \TIMO
 
 \TESTEXP { More~expandable~sorting }
-  { \exp_args:No \tl_sort:nN \l_tmpa_tl \test_compare:nnTF }
+  { \exp_args:No \tl_sort_use:nN \l_tmpa_tl \test_compare:nnTF }
 
 
 \END