[Commit] nickle nickle.1.in,1.16,1.17 prng.5c,1.8,1.9

[Bart Massey]

Committed by: bart

Update of /local/src/CVS/nickle
In directory home.keithp.com:/tmp/cvs-serv2684

Modified Files:
	nickle.1.in prng.5c 
Log Message:
Added shuffle(), and documented PRNG.



Index: nickle.1.in
===================================================================
RCS file: /local/src/CVS/nickle/nickle.1.in,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -d -r1.16 -r1.17
--- nickle.1.in	2 Jun 2003 03:31:02 -0000	1.16
+++ nickle.1.in	2 Jun 2003 04:10:21 -0000	1.17
@@ -1120,6 +1120,31 @@
 the substring will consist of characters preceding
 rather than succeeding i.
 .PP
+.IP PRNG
+The PRNG namespace provides pseudo-random number generation
+and manipulation.  The core generator is the RC4 stream
+cipher generator, properly bootstrapped.  This provide a stream of
+cryptographically-secure pseudo-random bits at reasonable amortized cost.
+(But beware, initialization is somewhat expensive.)
+.IP "void function srandom(int s)"
+Initialize the generator, using the (arbitrarily-large) integer as
+a seed.
+.IP "void function dev_srandom(int nbits)"
+Initialize the generator, using nbits bits of entropy obtained
+from some reasonable entropy source.  On UNIX systems, this
+source is /dev/urandom.  Asking for more initial entropy than
+the system has may lead either to bootstrapping (as on UNIX) or to
+hanging, so use cautiously.
+.IP "int function randbits(int n)"
+Returns an n-\fBbit\fP pseudo-random number, in
+the range \fI0..(2**n)-1\fP.  Useful for things
+like RSA.
+.IP "int function randint(int n)"
+Returns a pseudo-random number in the range \fI0..n-1\fP.
+.IP "void function shuffle(*(poly[*]) a)"
+Performs an efficient in-place true shuffle (c.f. Knuth) of
+the array a.
+.PP
 .IP Command
 The Command namespace is used by the top-level commands
 as described below.  It is also occasionally useful in

Index: prng.5c
===================================================================
RCS file: /local/src/CVS/nickle/prng.5c,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -d -r1.8 -r1.9
--- prng.5c	2 Jun 2003 03:31:02 -0000	1.8
+++ prng.5c	2 Jun 2003 04:10:21 -0000	1.9
@@ -48,4 +48,14 @@
     return randbits(32 + bit_width (n)) % n;
   }
 
+  public void shuffle(&poly[*] a) {
+    int na = dim(a);
+    for (int i = 0; i < na - 1; i++) {
+      int j = randint(na - i) + i;
+      int tmp = a[i];
+      a[i] = a[j];
+      a[j] = tmp;
+    }
+  }
+
 }