diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx | 200 |
1 files changed, 54 insertions, 146 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx b/Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx index 4c1c05e531a..da296d1d685 100644 --- a/Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx +++ b/Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx @@ -42,7 +42,7 @@ % }^^A % } % -% \date{Released 2018-11-19} +% \date{Released 2018-12-06} % % \maketitle % @@ -193,25 +193,6 @@ % group level. % \end{function} % -% \section{Additions to \pkg{l3clist}} -% -% \begin{function}[EXP, added = 2016-12-06] -% {\clist_rand_item:N, \clist_rand_item:n, \clist_rand_item:c} -% \begin{syntax} -% \cs{clist_rand_item:N} \meta{clist~var} -% \cs{clist_rand_item:n} \Arg{comma list} -% \end{syntax} -% Selects a pseudo-random item of the \meta{comma list}. If the -% \meta{comma list} has no item, the result is empty. This not -% yet available in \XeTeX{}. -% \begin{texnote} -% The result is returned within the \tn{unexpanded} -% primitive (\cs{exp_not:n}), which means that the \meta{item} -% does not expand further when appearing in an \texttt{x}-type -% argument expansion. -% \end{texnote} -% \end{function} -% % \section{Additions to \pkg{l3coffins}} % % \begin{function}{\coffin_resize:Nnn, \coffin_resize:cnn} @@ -439,15 +420,6 @@ % % \section{Additions to \pkg{l3int}} % -% \begin{function}[EXP, added = 2018-05-05]{\int_rand:n} -% \begin{syntax} -% \cs{int_rand:n} \Arg{intexpr} -% \end{syntax} -% Evaluates the \meta{integer expression} then produces a -% pseudo-random number between $1$ and the \meta{intexpr} (included). -% This is not yet available in \XeTeX{}. -% \end{function} -% % \begin{function}[EXP, added = 2018-11-03]{\int_sign:n} % \begin{syntax} % \cs{int_sign:n} \Arg{intexpr} @@ -458,15 +430,6 @@ % % \section{Additions to \pkg{l3intarray}} % -% \begin{function}[EXP, added = 2018-05-05]{\intarray_rand_item:N} -% \begin{syntax} -% \cs{intarray_rand_item:N} \meta{intarray~var} -% \end{syntax} -% Selects a pseudo-random item of the \meta{integer array}. If the -% \meta{integer array} is empty, produce an error. This is not yet -% available in \XeTeX{}. -% \end{function} -% % \begin{function}[added = 2018-05-05]{\intarray_gset_rand:Nnn, \intarray_gset_rand:Nn} % \begin{syntax} % \cs{intarray_gset_rand:Nnn} \meta{intarray~var} \Arg{minimum} \Arg{maximum} @@ -752,21 +715,6 @@ % \end{texnote} % \end{function} % -% \begin{function}[EXP, added = 2016-12-06]{\seq_rand_item:N, \seq_rand_item:c} -% \begin{syntax} -% \cs{seq_rand_item:N} \meta{seq~var} -% \end{syntax} -% Selects a pseudo-random item of the \meta{sequence}. If the -% \meta{sequence} is empty the result is empty. This is not yet -% available in \XeTeX{}. -% \begin{texnote} -% The result is returned within the \tn{unexpanded} -% primitive (\cs{exp_not:n}), which means that the \meta{item} -% does not expand further when appearing in an \texttt{x}-type -% argument expansion. -% \end{texnote} -% \end{function} -% % \begin{function}[added = 2017-11-28] % {\seq_const_from_clist:Nn, \seq_const_from_clist:cn} % \begin{syntax} @@ -1288,23 +1236,6 @@ % \meta{shell command}. % \end{function} % -% \begin{function}[EXP, added = 2016-12-06] -% {\tl_rand_item:N, \tl_rand_item:c, \tl_rand_item:n} -% \begin{syntax} -% \cs{tl_rand_item:N} \meta{tl~var} -% \cs{tl_rand_item:n} \Arg{token list} -% \end{syntax} -% Selects a pseudo-random item of the \meta{token list}. If the -% \meta{token list} is blank, the result is empty. This is not yet -% available in \XeTeX{}. -% \begin{texnote} -% The result is returned within the \tn{unexpanded} -% primitive (\cs{exp_not:n}), which means that the \meta{item} -% does not expand further when appearing in an \texttt{x}-type -% argument expansion. -% \end{texnote} -% \end{function} -% % \begin{function}[EXP, added = 2017-02-17, updated = 2017-07-15] % {\tl_range:Nnn, \tl_range:nnn} % \begin{syntax} @@ -1313,28 +1244,63 @@ % \end{syntax} % Leaves in the input stream the items from the \meta{start index} to the % \meta{end index} inclusive. Spaces and braces are preserved between -% the items returned (but never at either end of the list). Positive -% \meta{indices} are counted -% from the start of the \meta{token list}, $1$~being the first item, and -% negative \meta{indices} are counted from the end of the token list, -% $-1$~being the last item. If either of \meta{start index} or -% \meta{end index} is~$0$, the result is empty. For instance, +% the items returned (but never at either end of the list). +% +% Here \meta{start index} and \meta{end index} should be integer denotations. +% For describing in detail the functions' behavior, let $m$ and $n$ be the start +% and end index respectively. If either is $0$, the result is empty. A positive +% index means `start counting from the left end', a negative index means +% `start counting from the right end'. Let $l$ be the count of the token list. +% +% The \emph{actual start point} is determined as $M=m$ if~$m>0$ and as $M=l+m+1$ +% if~$m<0$. Similarly the \emph{actual end point} is $N=n$ if~$n>0$ and $N=l+n+1$ +% if~$n<0$. If $M>N$, the result is empty. Otherwise it consists of all items from +% position $M$ to position $N$ inclusive; for the purpose of this rule, we can +% imagine that the token list extends at infinity on either side, with void items +% at positions $s$ for $s\le0$ or $s>l$. + +% Spaces in between items in the actual range are preserved. Spaces at either end +% of the token list will be removed anyway (think to the token list being passed to +% |\tl_trim_spaces:n| to begin with. +% +% Thus, with $l=7$ as in the examples below, all of the following are equivalent +% and result in the whole token list +% \begin{verbatim} +% \tl_range:nnn { abcd~{e{}}fg } { 1 } { 7 } +% \tl_range:nnn { abcd~{e{}}fg } { 1 } { 12 } +% \tl_range:nnn { abcd~{e{}}fg } { -7 } { 7 } +% \tl_range:nnn { abcd~{e{}}fg } { -12 } { 7 } +% \end{verbatim} +% Here are some more interesting examples. The calls +% \begin{verbatim} +% \iow_term:x { \tl_range:nnn { abcd{e{}}fg } { 2 } { 5 } } +% \iow_term:x { \tl_range:nnn { abcd{e{}}fg } { 2 } { -3 } } +% \iow_term:x { \tl_range:nnn { abcd{e{}}fg } { -6 } { 5 } } +% \iow_term:x { \tl_range:nnn { abcd{e{}}fg } { -6 } { -3 } } +% \end{verbatim} +% are all equivalent and will print |bcd{e{}}| on the terminal; similarly % \begin{verbatim} -% \iow_term:x { \tl_range:nnn { abcd~{e{}}f } { 2 } { 5 } } -% \iow_term:x { \tl_range:nnn { abcd~{e{}}f } { -4 } { -1 } } -% \iow_term:x { \tl_range:nnn { abcd~{e{}}f } { -2 } { -1 } } -% \iow_term:x { \tl_range:nnn { abcd~{e{}}f } { 0 } { -1 } } +% \iow_term:x { \tl_range:nnn { abcd~{e{}}fg } { 2 } { 5 } } +% \iow_term:x { \tl_range:nnn { abcd~{e{}}fg } { 2 } { -3 } } +% \iow_term:x { \tl_range:nnn { abcd~{e{}}fg } { -6 } { 5 } } +% \iow_term:x { \tl_range:nnn { abcd~{e{}}fg } { -6 } { -3 } } % \end{verbatim} -% prints \verb*|bcd {e{}}|, \verb*|cd {e{}}f|, \verb*|{e{}}f| and an empty -% line to the terminal. The \meta{start index} must always be smaller than -% or equal to the \meta{end index}: if this is not the case then no output -% is generated. Thus +% are all equivalent and will print |bcd {e{}}| on the +% terminal (note the space in the middle). To the contrary, % \begin{verbatim} -% \iow_term:x { \tl_range:nnn { abcd~{e{}}f } { 5 } { 2 } } -% \iow_term:x { \tl_range:nnn { abcd~{e{}}f } { -1 } { -4 } } +% \tl_range:nnn { abcd~{e{}}f } { 2 } { 4 } % \end{verbatim} -% both yield empty token lists. For improved performance, see -% \cs{tl_range_braced:nnn} and \cs{tl_range_unbraced:nnn}. +% will discard the space after `d`. +% +% If we want to get the items from the third to the last, the call +% is |\tl_range:nnn { <tl> } { 3 } { -1 }|. Similarly, for discarding +% the last item, we can do |\tl_range:nnn { <tl> } { 1 } { -2 }|. +% +% The behavior of \cs{tl_range:Nnn} is exactly the same, acting on the +% contents of the tl variable. +% +% For improved performance, see \cs{tl_range_braced:nnn} and +% \cs{tl_range_unbraced:nnn}. % \begin{texnote} % The result is returned within the \tn{unexpanded} % primitive (\cs{exp_not:n}), which means that the \meta{item} @@ -1720,39 +1686,6 @@ % \end{macrocode} % \end{macro} % -% \subsection{Additions to \pkg{l3clist}} -% -% \begin{macrocode} -%<@@=clist> -% \end{macrocode} -% -% \begin{macro}{\clist_rand_item:n, \clist_rand_item:N, \clist_rand_item:c} -% \begin{macro}{\@@_rand_item:nn} -% The |N|-type function is not implemented through the |n|-type -% function for efficiency: for instance comma-list variables do not -% require space-trimming of their items. Even testing for emptyness -% of an |n|-type comma-list is slow, so we count items first and use -% that both for the emptyness test and the pseudo-random integer. -% Importantly, \cs{clist_item:Nn} and \cs{clist_item:nn} only evaluate -% their argument once. -% \begin{macrocode} -\cs_new:Npn \clist_rand_item:n #1 - { \exp_args:Nf \@@_rand_item:nn { \clist_count:n {#1} } {#1} } -\cs_new:Npn \@@_rand_item:nn #1#2 - { - \int_compare:nNnF {#1} = 0 - { \clist_item:nn {#2} { \int_rand:nn { 1 } {#1} } } - } -\cs_new:Npn \clist_rand_item:N #1 - { - \clist_if_empty:NF #1 - { \clist_item:Nn #1 { \int_rand:nn { 1 } { \clist_count:N #1 } } } - } -\cs_generate_variant:Nn \clist_rand_item:N { c } -% \end{macrocode} -% \end{macro} -% \end{macro} -% % \subsection{Additions to \pkg{l3coffins}} % % \begin{macrocode} @@ -2740,18 +2673,6 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}{\seq_rand_item:N, \seq_rand_item:c} -% Importantly, \cs{seq_item:Nn} only evaluates its argument once. -% \begin{macrocode} -\cs_new:Npn \seq_rand_item:N #1 - { - \seq_if_empty:NF #1 - { \seq_item:Nn #1 { \int_rand:nn { 1 } { \seq_count:N #1 } } } - } -\cs_generate_variant:Nn \seq_rand_item:N { c } -% \end{macrocode} -% \end{macro} -% % \begin{macro}{\seq_const_from_clist:Nn, \seq_const_from_clist:cn} % Almost identical to \cs{seq_set_from_clist:Nn}. % \begin{macrocode} @@ -5099,19 +5020,6 @@ % % \subsubsection{Other additions to \pkg{l3tl}} % -% \begin{macro}{\tl_rand_item:n, \tl_rand_item:N, \tl_rand_item:c} -% Importantly \cs{tl_item:nn} only evaluates its argument once. -% \begin{macrocode} -\cs_new:Npn \tl_rand_item:n #1 - { - \tl_if_blank:nF {#1} - { \tl_item:nn {#1} { \int_rand:nn { 1 } { \tl_count:n {#1} } } } - } -\cs_new:Npn \tl_rand_item:N { \exp_args:No \tl_rand_item:n } -\cs_generate_variant:Nn \tl_rand_item:N { c } -% \end{macrocode} -% \end{macro} -% % Some preliminary code is needed for the \cs{tl_range:nnn} family of functions. % % \begin{macro}{\tl_range:Nnn, \tl_range:cnn, \tl_range:nnn} |