summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3str.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3str.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3str.dtx116
1 files changed, 61 insertions, 55 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3str.dtx b/Master/texmf-dist/source/latex/l3kernel/l3str.dtx
index 2a0b175bfee..10d4fa865e4 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3str.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3str.dtx
@@ -43,7 +43,7 @@
% }^^A
% }
%
-% \date{Released 2021-02-18}
+% \date{Released 2021-05-07}
%
% \maketitle
%
@@ -401,74 +401,41 @@
% not be used within this string.
% \end{function}
%
-% \section{Mapping to strings}
+% \section{Mapping over strings}
%
% All mappings are done at the current group level, \emph{i.e.}~any
% local assignments made by the \meta{function} or \meta{code} discussed
% below remain in effect after the loop.
%
% \begin{function}[added = 2017-11-14, rEXP]
-% {\str_map_function:NN, \str_map_function:cN}
-% \begin{syntax}
-% \cs{str_map_function:NN} \meta{str~var} \meta{function}
-% \end{syntax}
-% Applies \meta{function} to every \meta{character} in the
-% \meta{str~var} including spaces.
-% See also \cs{str_map_function:nN}.
-% \end{function}
-%
-% \begin{function}[added = 2017-11-14, rEXP]
-% {\str_map_function:nN}
+% {\str_map_function:nN, \str_map_function:NN, \str_map_function:cN}
% \begin{syntax}
% \cs{str_map_function:nN} \Arg{token list} \meta{function}
+% \cs{str_map_function:NN} \meta{str~var} \meta{function}
% \end{syntax}
% Converts the \meta{token list} to a \meta{string} then
% applies \meta{function} to every \meta{character} in the
% \meta{string} including spaces.
-% See also \cs{str_map_function:NN}.
-% \end{function}
-%
-% \begin{function}[added = 2017-11-14]
-% {\str_map_inline:Nn, \str_map_inline:cn}
-% \begin{syntax}
-% \cs{str_map_inline:Nn} \meta{str~var} \Arg{inline function}
-% \end{syntax}
-% Applies the \meta{inline function} to every \meta{character} in the
-% \meta{str~var} including spaces.
-% The \meta{inline function} should consist of code which
-% receives the \meta{character} as |#1|. See also \cs{str_map_function:NN}.
% \end{function}
%
% \begin{function}[added = 2017-11-14]
-% {\str_map_inline:nn}
+% {\str_map_inline:nn, \str_map_inline:Nn, \str_map_inline:cn}
% \begin{syntax}
% \cs{str_map_inline:nn} \Arg{token list} \Arg{inline function}
+% \cs{str_map_inline:Nn} \meta{str~var} \Arg{inline function}
% \end{syntax}
% Converts the \meta{token list} to a \meta{string} then
% applies the \meta{inline function} to every \meta{character} in the
-% \meta{string} including spaces.
+% \meta{str~var} including spaces.
% The \meta{inline function} should consist of code which
-% receives the \meta{character} as |#1|. See also \cs{str_map_function:NN}.
-% \end{function}
-%
-% \begin{function}[added = 2017-11-14]
-% {\str_map_variable:NNn, \str_map_variable:cNn}
-% \begin{syntax}
-% \cs{str_map_variable:NNn} \meta{str~var} \meta{variable} \Arg{code}
-% \end{syntax}
-% Stores each \meta{character} of the \meta{string} (including spaces)
-% in turn in the (string or token list) \meta{variable} and applies
-% the \meta{code}. The \meta{code} will usually make use of the
-% \meta{variable}, but this is not enforced. The assignments to the
-% \meta{variable} are local. Its value after the loop is the last
-% \meta{character} in the \meta{string}, or its original value if the
-% \meta{string} is empty. See also \cs{str_map_inline:Nn}.
+% receives the \meta{character} as |#1|.
% \end{function}
%
% \begin{function}[added = 2017-11-14]
-% {\str_map_variable:nNn}
+% {\str_map_variable:nNn, \str_map_variable:NNn, \str_map_variable:cNn}
% \begin{syntax}
% \cs{str_map_variable:nNn} \Arg{token list} \meta{variable} \Arg{code}
+% \cs{str_map_variable:NNn} \meta{str~var} \meta{variable} \Arg{code}
% \end{syntax}
% Converts the \meta{token list} to a \meta{string} then stores each
% \meta{character} in the \meta{string} (including spaces) in turn in
@@ -480,6 +447,19 @@
% \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:}
@@ -797,7 +777,7 @@
%
% \section{Viewing strings}
%
-% \begin{function}[added = 2015-09-18]
+% \begin{function}[added = 2015-09-18, updated = 2021-04-29]
% {\str_show:N, \str_show:c, \str_show:n}
% \begin{syntax}
% \cs{str_show:N} \meta{str~var}
@@ -805,7 +785,7 @@
% Displays the content of the \meta{str~var} on the terminal.
% \end{function}
%
-% \begin{function}[added = 2019-02-15]
+% \begin{function}[added = 2019-02-15, updated = 2021-04-29]
% {\str_log:N, \str_log:c, \str_log:n}
% \begin{syntax}
% \cs{str_log:N} \meta{str~var}
@@ -815,7 +795,7 @@
%
% \section{Constant token lists}
%
-% \begin{variable}[added = 2015-09-19,updated=2020-12-22]
+% \begin{variable}[added = 2015-09-19, updated = 2020-12-22, module = str]
% {
% \c_ampersand_str,
% \c_atsign_str,
@@ -1201,7 +1181,7 @@
% \begin{macro}[EXP]{\@@_case:nnTF, \@@_case_e:nnTF}
% \begin{macro}[EXP]
% {\@@_case:nw, \@@_case_e:nw, \@@_case_end:nw}
-% Much the same as \cs[index=tl_case:nn]{tl_case:nn(TF)} here:
+% Much the same as \cs{tl_case:nnTF} here:
% just a change in the internal comparison.
% \begin{macrocode}
\cs_new:Npn \str_case:nn #1#2
@@ -1270,7 +1250,7 @@
% \end{macro}
% \end{macro}
%
-% \subsection{Mapping to strings}
+% \subsection{Mapping over strings}
%
% \begin{macro}[rEXP]{\str_map_function:NN, \str_map_function:cN}
% \begin{macro}[rEXP]{\str_map_function:nN}
@@ -1280,7 +1260,7 @@
% \begin{macro}{\str_map_variable:nNn}
% \begin{macro}{\str_map_break:}
% \begin{macro}{\str_map_break:n}
-% \begin{macro}[rEXP]{\@@_map_function:w, \@@_map_function:Nn}
+% \begin{macro}[rEXP]{\@@_map_function:w, \@@_map_function:nn}
% \begin{macro}{\@@_map_inline:NN, \@@_map_variable:NnN}
% The inline and variable mappings are similar to the usual token list
% mappings but start out by turning the argument to an ``other
@@ -1288,7 +1268,7 @@
% require \cs{__kernel_str_to_other:n}, quadratic in the string length. To deal
% with spaces in that case, \cs{@@_map_function:w} replaces the
% following space by a braced space and a further call to itself.
-% These are received by \cs{@@_map_function:Nn}, which passes
+% These are received by \cs{@@_map_function:nn}, which passes
% the space to |#1| and calls \cs{@@_map_function:w} to deal with the
% next space. The space before the braced space allows to optimize
% the \cs{q_@@_recursion_tail} test. Of course we need to include a
@@ -1306,7 +1286,7 @@
\cs_new:Npn \str_map_function:nN #1#2
{
\exp_after:wN \@@_map_function:w
- \exp_after:wN \@@_map_function:Nn \exp_after:wN #2
+ \exp_after:wN \@@_map_function:nn \exp_after:wN #2
\__kernel_tl_to_str:w {#1}
\q_@@_recursion_tail ? ~
\prg_break_point:Nn \str_map_break: { }
@@ -1315,12 +1295,12 @@
{ \exp_args:No \str_map_function:nN }
\cs_new:Npn \@@_map_function:w #1 ~
{ #1 { ~ { ~ } \@@_map_function:w } }
-\cs_new:Npn \@@_map_function:Nn #1#2
+\cs_new:Npn \@@_map_function:nn #1#2
{
\if_meaning:w \q_@@_recursion_tail #2
\exp_after:wN \str_map_break:
\fi:
- #1 #2 \@@_map_function:Nn #1
+ #1 #2 \@@_map_function:nn {#1}
}
\cs_generate_variant:Nn \str_map_function:NN { c }
\cs_new_protected:Npn \str_map_inline:nn #1#2
@@ -1383,6 +1363,24 @@
% \end{macro}
% \end{macro}
%
+% \begin{macro}[rEXP]{\str_map_tokens:Nn, \str_map_tokens:cn}
+% \begin{macro}[rEXP]{\str_map_tokens:nn}
+% Uses an auxiliary of \cs{str_map_function:NN}.
+% \begin{macrocode}
+\cs_new:Npn \str_map_tokens:nn #1#2
+ {
+ \exp_args:Nno \use:nn
+ { \@@_map_function:w \@@_map_function:nn {#2} }
+ { \__kernel_tl_to_str:w {#1} }
+ \q_@@_recursion_tail ? ~
+ \prg_break_point:Nn \str_map_break: { }
+ }
+\cs_new:Npn \str_map_tokens:Nn { \exp_args:No \str_map_tokens:nn }
+\cs_generate_variant:Nn \str_map_tokens:Nn { c }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
% \subsection{Accessing specific characters in a string}
%
% \begin{macro}[EXP]{\__kernel_str_to_other:n}
@@ -1983,10 +1981,18 @@
% Displays a string on the terminal.
% \begin{macrocode}
\cs_new_eq:NN \str_show:n \tl_show:n
-\cs_new_eq:NN \str_show:N \tl_show:N
+\cs_new_protected:Npn \str_show:N #1
+ {
+ \__kernel_chk_tl_type:NnnT #1 { str } { \tl_to_str:N #1 }
+ { \tl_show:N #1 }
+ }
\cs_generate_variant:Nn \str_show:N { c }
\cs_new_eq:NN \str_log:n \tl_log:n
-\cs_new_eq:NN \str_log:N \tl_log:N
+\cs_new_protected:Npn \str_log:N #1
+ {
+ \__kernel_chk_tl_type:NnnT #1 { str } { \tl_to_str:N #1 }
+ { \tl_log:N #1 }
+ }
\cs_generate_variant:Nn \str_log:N { c }
% \end{macrocode}
% \end{macro}