summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/l3kernel/l3str.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/l3kernel/l3str.dtx')
-rw-r--r--macros/latex/contrib/l3kernel/l3str.dtx206
1 files changed, 103 insertions, 103 deletions
diff --git a/macros/latex/contrib/l3kernel/l3str.dtx b/macros/latex/contrib/l3kernel/l3str.dtx
index e84e2162a2..40fd7437f0 100644
--- a/macros/latex/contrib/l3kernel/l3str.dtx
+++ b/macros/latex/contrib/l3kernel/l3str.dtx
@@ -43,7 +43,7 @@
% }^^A
% }
%
-% \date{Released 2021-10-18}
+% \date{Released 2021-11-12}
%
% \maketitle
%
@@ -95,7 +95,7 @@
% appropriately.
% \end{itemize}
%
-% \section{Building strings}
+% \section{Creating and initialising string variables}
%
% \begin{function}[added = 2015-09-18]{\str_new:N, \str_new:c}
% \begin{syntax}
@@ -164,6 +164,16 @@
% this function does not convert their contents to a string.
% \end{function}
%
+% \begin{function}[EXP, pTF, added = 2015-09-18]
+% {\str_if_exist:N, \str_if_exist:c}
+% \begin{syntax}
+% \cs{str_if_exist_p:N} \meta{str~var}
+% \cs{str_if_exist:NTF} \meta{str~var} \Arg{true code} \Arg{false code}
+% \end{syntax}
+% Tests whether the \meta{str~var} is currently defined. This does not
+% check that the \meta{str~var} really is a string.
+% \end{function}
+%
% \section{Adding data to string variables}
%
% \begin{function}[added = 2015-09-18, updated = 2018-07-28]
@@ -210,84 +220,8 @@
% var} are not automatically converted to a string.
% \end{function}
%
-% \section{Modifying string variables}
-%
-% \begin{function}[added = 2017-10-08]
-% {
-% \str_replace_once:Nnn, \str_replace_once:cnn,
-% \str_greplace_once:Nnn, \str_greplace_once:cnn
-% }
-% \begin{syntax}
-% \cs{str_replace_once:Nnn} \meta{str~var} \Arg{old} \Arg{new}
-% \end{syntax}
-% Converts the \meta{old} and \meta{new} token lists to strings, then
-% replaces the first (leftmost) occurrence of \meta{old string} in the
-% \meta{str~var} with \meta{new string}.
-% \end{function}
-%
-% \begin{function}[added = 2017-10-08]
-% {
-% \str_replace_all:Nnn, \str_replace_all:cnn,
-% \str_greplace_all:Nnn, \str_greplace_all:cnn
-% }
-% \begin{syntax}
-% \cs{str_replace_all:Nnn} \meta{str~var} \Arg{old} \Arg{new}
-% \end{syntax}
-% Converts the \meta{old} and \meta{new} token lists to strings, then
-% replaces all occurrences of \meta{old string} in the
-% \meta{str~var} with \meta{new string}.
-% As this function
-% operates from left to right, the pattern \meta{old string}
-% may remain after the replacement (see \cs{str_remove_all:Nn}
-% for an example).
-% \end{function}
-%
-% \begin{function}[added = 2017-10-08]
-% {
-% \str_remove_once:Nn, \str_remove_once:cn,
-% \str_gremove_once:Nn, \str_gremove_once:cn
-% }
-% \begin{syntax}
-% \cs{str_remove_once:Nn} \meta{str~var} \Arg{token list}
-% \end{syntax}
-% Converts the \meta{token list} to a \meta{string} then
-% removes the first (leftmost) occurrence of \meta{string} from the
-% \meta{str~var}.
-% \end{function}
-%
-% \begin{function}[added = 2017-10-08]
-% {
-% \str_remove_all:Nn, \str_remove_all:cn,
-% \str_gremove_all:Nn, \str_gremove_all:cn
-% }
-% \begin{syntax}
-% \cs{str_remove_all:Nn} \meta{str~var} \Arg{token list}
-% \end{syntax}
-% Converts the \meta{token list} to a \meta{string} then
-% removes all occurrences of \meta{string} from the
-% \meta{str~var}.
-% As this function
-% operates from left to right, the pattern \meta{string}
-% may remain after the removal, for instance,
-% \begin{quote}
-% \cs{str_set:Nn} \cs{l_tmpa_str} |{abbccd}|
-% \cs{str_remove_all:Nn} \cs{l_tmpa_str} |{bc}|
-% \end{quote}
-% results in \cs{l_tmpa_str} containing \texttt{abcd}.
-% \end{function}
-%
% \section{String conditionals}
%
-% \begin{function}[EXP, pTF, added = 2015-09-18]
-% {\str_if_exist:N, \str_if_exist:c}
-% \begin{syntax}
-% \cs{str_if_exist_p:N} \meta{str~var}
-% \cs{str_if_exist:NTF} \meta{str~var} \Arg{true code} \Arg{false code}
-% \end{syntax}
-% Tests whether the \meta{str~var} is currently defined. This does not
-% check that the \meta{str~var} really is a string.
-% \end{function}
-%
% \begin{function}[EXP,pTF, added = 2015-09-18]
% {\str_if_empty:N, \str_if_empty:c}
% \begin{syntax}
@@ -459,6 +393,19 @@
% receives the \meta{character} as |#1|.
% \end{function}
%
+% \begin{function}[rEXP, added = 2021-05-05]
+% {\str_map_tokens:nn, \str_map_tokens:Nn, \str_map_tokens:cn}
+% \begin{syntax}
+% \cs{str_map_tokens:nn} \Arg{token list} \Arg{code}
+% \cs{str_map_tokens:Nn} \meta{str~var} \Arg{code}
+% \end{syntax}
+% Converts the \meta{token list} to a \meta{string} then applies
+% \meta{code} to every \meta{character} in the \meta{string} including
+% spaces. The \meta{code} receives each character as a trailing brace
+% group. This is equivalent to \cs{str_map_function:nN} if the
+% \meta{code} consists of a single function.
+% \end{function}
+%
% \begin{function}[added = 2017-11-14]
% {\str_map_variable:nNn, \str_map_variable:NNn, \str_map_variable:cNn}
% \begin{syntax}
@@ -475,19 +422,6 @@
% \meta{string} is empty. See also \cs{str_map_inline:Nn}.
% \end{function}
%
-% \begin{function}[rEXP, added = 2021-05-05]
-% {\str_map_tokens:nn, \str_map_tokens:Nn, \str_map_tokens:cn}
-% \begin{syntax}
-% \cs{str_map_tokens:nn} \Arg{token list} \Arg{code}
-% \cs{str_map_tokens:Nn} \meta{str~var} \Arg{code}
-% \end{syntax}
-% Converts the \meta{token list} to a \meta{string} then applies
-% \meta{code} to every \meta{character} in the \meta{string} including
-% spaces. The \meta{code} receives each character as a trailing brace
-% group. This is equivalent to \cs{str_map_function:nN} if the
-% \meta{code} consists of a single function.
-% \end{function}
-%
% \begin{function}[added = 2017-10-08, rEXP]{\str_map_break:}
% \begin{syntax}
% \cs{str_map_break:}
@@ -698,6 +632,72 @@
% instances of |bcde|.
% ^^A\end{function}
%
+% \section{Modifying string variables}
+%
+% \begin{function}[added = 2017-10-08]
+% {
+% \str_replace_once:Nnn, \str_replace_once:cnn,
+% \str_greplace_once:Nnn, \str_greplace_once:cnn
+% }
+% \begin{syntax}
+% \cs{str_replace_once:Nnn} \meta{str~var} \Arg{old} \Arg{new}
+% \end{syntax}
+% Converts the \meta{old} and \meta{new} token lists to strings, then
+% replaces the first (leftmost) occurrence of \meta{old string} in the
+% \meta{str~var} with \meta{new string}.
+% \end{function}
+%
+% \begin{function}[added = 2017-10-08]
+% {
+% \str_replace_all:Nnn, \str_replace_all:cnn,
+% \str_greplace_all:Nnn, \str_greplace_all:cnn
+% }
+% \begin{syntax}
+% \cs{str_replace_all:Nnn} \meta{str~var} \Arg{old} \Arg{new}
+% \end{syntax}
+% Converts the \meta{old} and \meta{new} token lists to strings, then
+% replaces all occurrences of \meta{old string} in the
+% \meta{str~var} with \meta{new string}.
+% As this function
+% operates from left to right, the pattern \meta{old string}
+% may remain after the replacement (see \cs{str_remove_all:Nn}
+% for an example).
+% \end{function}
+%
+% \begin{function}[added = 2017-10-08]
+% {
+% \str_remove_once:Nn, \str_remove_once:cn,
+% \str_gremove_once:Nn, \str_gremove_once:cn
+% }
+% \begin{syntax}
+% \cs{str_remove_once:Nn} \meta{str~var} \Arg{token list}
+% \end{syntax}
+% Converts the \meta{token list} to a \meta{string} then
+% removes the first (leftmost) occurrence of \meta{string} from the
+% \meta{str~var}.
+% \end{function}
+%
+% \begin{function}[added = 2017-10-08]
+% {
+% \str_remove_all:Nn, \str_remove_all:cn,
+% \str_gremove_all:Nn, \str_gremove_all:cn
+% }
+% \begin{syntax}
+% \cs{str_remove_all:Nn} \meta{str~var} \Arg{token list}
+% \end{syntax}
+% Converts the \meta{token list} to a \meta{string} then
+% removes all occurrences of \meta{string} from the
+% \meta{str~var}.
+% As this function
+% operates from left to right, the pattern \meta{string}
+% may remain after the removal, for instance,
+% \begin{quote}
+% \cs{str_set:Nn} \cs{l_tmpa_str} |{abbccd}|
+% \cs{str_remove_all:Nn} \cs{l_tmpa_str} |{bc}|
+% \end{quote}
+% results in \cs{l_tmpa_str} containing \texttt{abcd}.
+% \end{function}
+%
% \section{String manipulation}
%
% \begin{function}[EXP, added = 2019-11-26]
@@ -1163,22 +1163,23 @@
% \str_if_eq:ee
% }
% Modern engines provide a direct way of comparing two token lists,
-% but returning a number. This set of conditionals therefore make life
-% a bit clearer. The \texttt{nn} and \texttt{xx} versions are created
-% directly as this is most efficient.
+% but returning a number. This set of conditionals therefore makes life
+% a bit clearer. The \texttt{nn} and \texttt{ee} versions are created
+% directly as this is most efficient. Since \cs{@@_if_eq:nn} will expand to
+% |0| as an explicit character with category 12 if the two lists match (and
+% either |-1| or |1| if they don't) we can use \cs{if:w} here which is faster
+% than using \cs{if_int_compare:w}.
% \begin{macrocode}
\prg_new_conditional:Npnn \str_if_eq:nn #1#2 { p , T , F , TF }
{
- \if_int_compare:w
- \@@_if_eq:nn { \exp_not:n {#1} } { \exp_not:n {#2} }
- = \c_zero_int
+ \if:w 0 \@@_if_eq:nn { \exp_not:n {#1} } { \exp_not:n {#2} }
\prg_return_true: \else: \prg_return_false: \fi:
}
\prg_generate_conditional_variant:Nnn \str_if_eq:nn
{ V , v , o , nV , no , VV , nv } { p , T , F , TF }
\prg_new_conditional:Npnn \str_if_eq:ee #1#2 { p , T , F , TF }
{
- \if_int_compare:w \@@_if_eq:nn {#1} {#2} = \c_zero_int
+ \if:w 0 \@@_if_eq:nn {#1} {#2}
\prg_return_true: \else: \prg_return_false: \fi:
}
% \end{macrocode}
@@ -1186,14 +1187,13 @@
%
% \begin{macro}[EXP, pTF]
% {\str_if_eq:NN, \str_if_eq:Nc, \str_if_eq:cN, \str_if_eq:cc}
-% Note that \cs{str_if_eq:NN} is different from
-% \cs{tl_if_eq:NN} because it needs to ignore category codes.
+% Note that \cs{str_if_eq:NNTF} is different from
+% \cs{tl_if_eq:NNTF} because it needs to ignore category codes.
% \begin{macrocode}
\prg_new_conditional:Npnn \str_if_eq:NN #1#2 { p , TF , T , F }
{
- \if_int_compare:w
- \@@_if_eq:nn { \tl_to_str:N #1 } { \tl_to_str:N #2 }
- = \c_zero_int \prg_return_true: \else: \prg_return_false: \fi:
+ \if:w 0 \@@_if_eq:nn { \tl_to_str:N #1 } { \tl_to_str:N #2 }
+ \prg_return_true: \else: \prg_return_false: \fi:
}
\prg_generate_conditional_variant:Nnn \str_if_eq:NN
{ c , Nc , cc } { T , F , TF , p }