summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2018-12-07 22:52:08 +0000
committerKarl Berry <karl@freefriends.org>2018-12-07 22:52:08 +0000
commit01651bbd8c05e990ab60754f83cca88670045846 (patch)
treef562463d39d6e408d2ee5f025089f62b09da21f2 /Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx
parentb15665291da56772687808588be2d9dee0d24094 (diff)
l3kernel (7dec18)
git-svn-id: svn://tug.org/texlive/trunk@49348 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx200
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}