[latex3-commits] [git/LaTeX3-latex3-latex3] master: Document \seq_shuffle:N (bed64db)

[Bruno Le Floch]

Repository : https://github.com/latex3/latex3
On branch  : master
Link       : https://github.com/latex3/latex3/commit/bed64db1daecc2ed56f9dbb05d5caeea9cdd19a4

>---------------------------------------------------------------

commit bed64db1daecc2ed56f9dbb05d5caeea9cdd19a4
Author: Bruno Le Floch <bruno at le-floch.fr>
Date:   Sun Apr 29 16:46:22 2018 -0400

    Document \seq_shuffle:N


>---------------------------------------------------------------

bed64db1daecc2ed56f9dbb05d5caeea9cdd19a4
 l3kernel/l3candidates.dtx |   17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/l3kernel/l3candidates.dtx b/l3kernel/l3candidates.dtx
index ca3146b..c620c91 100644
--- a/l3kernel/l3candidates.dtx
+++ b/l3kernel/l3candidates.dtx
@@ -660,6 +660,23 @@
 %   mappings.
 % \end{function}
 %
+% \begin{function}[added = 2018-04-29]{\seq_shuffle:N, \seq_gshuffle:N}
+%   \begin{syntax}
+%     \cs{seq_shuffle:N} \meta{seq~var}
+%   \end{syntax}
+%   Sets the \meta{seq~var} to the result of placing the items of the
+%   \meta{seq~var} in a random order.  Each item is (roughly) as likely
+%   to end up in any given position.
+%   \begin{texnote}
+%     For sequences with more than $13$ items or so, only a small
+%     proportion of all possible permutations can be reached, because
+%     the random seed \cs{sys_rand_seed:} only has $28$-bits.  The use
+%     of \tn{toks} internally means that sequences with more than
+%     $32767$ or $65535$ items (depending on the engine) cannot be
+%     shuffled.
+%   \end{texnote}
+% \end{function}
+%
 % \section{Additions to \pkg{l3skip}}
 %
 % \begin{function}{\skip_split_finite_else_action:nnNN}