l3kernel (7dec18)

git-svn-id: svn://tug.org/texlive/trunk@49348 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 28 insertions, 1 deletions

diff --git a/Master/texmf-dist/source/latex/l3kernel/l3seq.dtx b/Master/texmf-dist/source/latex/l3kernel/l3seq.dtx
index 0eaadc78d50..12a347955d7 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3seq.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3seq.dtx
@@ -41,7 +41,7 @@
 %    }^^A
 % }
 %
-% \date{Released 2018-11-19}
+% \date{Released 2018-12-06}
 %
 % \maketitle
 %
@@ -289,6 +289,21 @@
 %   \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}
+%
 % \section{Recovering values from sequences with branching}
 %
 % The functions in this section combine tests for non-empty sequences
@@ -1702,6 +1717,18 @@
 % \end{macro}
 % \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}
+%
 % \subsection{Mapping to sequences}
 %
 % \begin{macro}{\seq_map_break:}