[latex3-commits] [latex3/latex3] tl-build: Deprecate \tl_build_(g)clear:N (b0a255425)

[github at latex-project.org]

Repository : https://github.com/latex3/latex3
On branch  : tl-build
Link       : https://github.com/latex3/latex3/commit/b0a25542547bee81aa9080edb1ab0ef04246f0d5

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

commit b0a25542547bee81aa9080edb1ab0ef04246f0d5
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Wed Oct 18 20:15:32 2023 +0100

    Deprecate \tl_build_(g)clear:N
    
    Done formally as these are in wider use.


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

b0a25542547bee81aa9080edb1ab0ef04246f0d5
 l3kernel/CHANGELOG.md       |  1 +
 l3kernel/doc/l3obsolete.txt |  2 ++
 l3kernel/l3candidates.dtx   | 23 -----------------------
 l3kernel/l3deprecation.dtx  |  9 +++++++++
 l3kernel/l3regex.dtx        |  6 +++---
 5 files changed, 15 insertions(+), 26 deletions(-)

diff --git a/l3kernel/CHANGELOG.md b/l3kernel/CHANGELOG.md
index 800fef972..de7c82eb6 100644
--- a/l3kernel/CHANGELOG.md
+++ b/l3kernel/CHANGELOG.md
@@ -19,6 +19,7 @@ this project uses date-based 'snapshot' version identifiers.
 
 ### Deprecated
 - `\text_titlecase:n(n)` as ambiguous: replaced by `\text_titlecase_all:n(n)`
+- `\tl_build_(g)clear:N` in favour of `\tl_build_(g)begin:N`
 
 ### Fixed
 - Support arbitrary BCP-47 locales for case-changing overrides (issue \#1239)
diff --git a/l3kernel/doc/l3obsolete.txt b/l3kernel/doc/l3obsolete.txt
index 7b9c808e5..a5d93edc6 100644
--- a/l3kernel/doc/l3obsolete.txt
+++ b/l3kernel/doc/l3obsolete.txt
@@ -58,6 +58,8 @@ Function                            Date deprecated
 \sys_load_deprecation:                   2021-01-11
 \text_titlecase:n                        2023-07-08
 \text_titlecase:nn                       2023-07-08
+\tl_build_clear:N                        2023-10-18
+\tl_build_gclear:N                       2023-10-18
 \tl_case:cn                              2023-05-23
 \tl_case:cnF                             2023-05-23
 \tl_case:cnT                             2023-05-23
diff --git a/l3kernel/l3candidates.dtx b/l3kernel/l3candidates.dtx
index 9d6b9df65..6668a18c9 100644
--- a/l3kernel/l3candidates.dtx
+++ b/l3kernel/l3candidates.dtx
@@ -103,16 +103,6 @@
 %
 % \section{Additions to \pkg{l3tl}}
 %
-% \begin{function}[added = 2018-04-01]{\tl_build_clear:N, \tl_build_gclear:N}
-%   \begin{syntax}
-%     \cs{tl_build_clear:N} \meta{tl~var}
-%   \end{syntax}
-%   Clears the \meta{tl~var} and sets it up to support other
-%   \cs[no-index]{tl_build_\ldots{}} functions.  The |clear| and
-%   |gclear| functions must be used for local and global \meta{tl~var}
-%   respectively.
-% \end{function}
-%
 % \begin{function}[added = 2018-04-01]{\tl_build_get:NN}
 %   \begin{syntax}
 %     \cs{tl_build_get:NN} \meta{tl~var_1} \meta{tl~var_2}
@@ -172,19 +162,6 @@
 %<@@=tl>
 %    \end{macrocode}
 %
-% \begin{macro}{\tl_build_clear:N, \tl_build_gclear:N}
-%   The |begin| and |gbegin| functions already clear enough to make the
-%   token list variable effectively empty.  Eventually the |begin| and
-%   |gbegin| functions should check that |#1'| is empty or undefined,
-%   while the |clear| and |gclear| functions ought to empty |#1'|,
-%   |#1''| and so on, similar to \cs{tl_build_end:N}.  This only affects
-%   memory usage.
-%    \begin{macrocode}
-\cs_new_eq:NN \tl_build_clear:N \tl_build_begin:N
-\cs_new_eq:NN \tl_build_gclear:N \tl_build_gbegin:N
-%    \end{macrocode}
-% \end{macro}
-%
 % \begin{macro}{\tl_build_get:NN}
 %    \begin{macrocode}
 \cs_new_protected:Npn \tl_build_get:NN
diff --git a/l3kernel/l3deprecation.dtx b/l3kernel/l3deprecation.dtx
index a05e4725f..7436fa246 100644
--- a/l3kernel/l3deprecation.dtx
+++ b/l3kernel/l3deprecation.dtx
@@ -614,6 +614,15 @@
 %    \end{macrocode}
 % \end{macro}
 %
+% \begin{macro}{\tl_build_clear:N, \tl_build_gclear:N}
+%    \begin{macrocode}
+\__kernel_patch_deprecation:nnNNpn { 2023-10-18 } { \tl_build_begin:N }
+\cs_new_protected:Npn \tl_build_clear:N { \tl_build_begin:N }
+\__kernel_patch_deprecation:nnNNpn { 2023-10-18 } { \tl_build_gbegin:N }
+\cs_new_protected:Npn \tl_build_gclear:N { \tl_build_gbegin:N }
+%    \end{macrocode}
+% \end{macro}
+%
 % \subsection{Deprecated \pkg{l3token} functions}
 %
 % \begin{macro}[EXP]{\char_to_utfviii_bytes:n}
diff --git a/l3kernel/l3regex.dtx b/l3kernel/l3regex.dtx
index 87dfcec47..65421db08 100644
--- a/l3kernel/l3regex.dtx
+++ b/l3kernel/l3regex.dtx
@@ -5363,7 +5363,7 @@
   }
 \cs_new_protected:Npn \@@_match_once_init_aux:
   {
-    \tl_build_clear:N \l_@@_matched_analysis_tl
+    \tl_build_begin:N \l_@@_matched_analysis_tl
     \tl_clear:N \l_@@_curr_analysis_tl
   }
 %    \end{macrocode}
@@ -5663,7 +5663,7 @@
           \l_@@_fresh_thread_bool
         \int_set_eq:NN \l_@@_success_pos_int \l_@@_curr_pos_int
         \int_set_eq:NN \l_@@_last_char_success_int \l_@@_last_char_int
-        \tl_build_clear:N \l_@@_matched_analysis_tl
+        \tl_build_begin:N \l_@@_matched_analysis_tl
         \tl_set_eq:NN \l_@@_success_submatches_tl
           \l_@@_curr_submatches_tl
         \prg_break:
@@ -7476,7 +7476,7 @@
       \@@_single_match:
       #1
       \@@_match_init:
-      \tl_build_clear:N \l_@@_input_tl
+      \tl_build_begin:N \l_@@_input_tl
       \@@_match_once_init:
       \peek_analysis_map_inline:n
         {