debian/changelog: Prepare for next minor version.

[catacomb] / rand / grand.h

diff --git a/rand/grand.h b/rand/grand.h
index ec11404..b45f045 100644 (file)
--- a/rand/grand.h
+++ b/rand/grand.h
@@ -51,7 +51,10 @@ typedef struct grand_ops {
 
   const char *name;                    /* Generator's name */
   unsigned f;                          /* Various flags */
-  uint32 max;                          /* Maximum raw output */
+  uint32 max;                          /* Maximum raw output, if nonzero;
+                                        * must be either zero or at least
+                                        * 256
+                                        */
 
   /* --- Maintenance methods --- */
 
@@ -60,9 +63,10 @@ typedef struct grand_ops {
 
   /* --- Output methods --- *
    *
-   * Only one of these operations need actually be implemented.  All the
-   * other operations may be synthesized.  Of course, performance is improved
-   * if more are provided.
+   * Of these, only @raw@ need be implemented directly by the generator: the
+   * others can point to provided @grand_default...@ functions, which will
+   * synthesize the necessary behaviour.  Of course, this comes at an
+   * efficiency penalty.
    */
 
   uint32 (*raw)(grand */*r*/);         /* Uniform over %$[0, max)$% */
@@ -105,6 +109,67 @@ enum {
 
 #define GRAND_BADOP assert(((void)"bad grand_misc op", 0))
 
+/*----- Default operations ------------------------------------------------*/
+
+/* --- @grand_defaultbyte@ --- *
+ *
+ * Arguments:  @grand *r@ = pointet to generic generator
+ *
+ * Returns:    A uniformly-distributed pseudorandom integer in the interval
+ *             %$[0, 256)$%.
+ *
+ * Use:                Default @byte@ output method.  This calls the @range@ method
+ *             to return a uniform random value between 0 and 255.
+ */
+
+extern octet grand_defaultbyte(grand */*r*/);
+
+/* --- @grand_defaultword@ --- *
+ *
+ * Arguments:  @grand *r@ = pointet to generic generator
+ *
+ * Returns:    A uniformly-distributed pseudorandom integer in the interval
+ *             %$[0, 2^{32})$%.
+ *
+ * Use:                Default @word@ output method.  This calls the @fill@ method
+ *             to fill a 4-octet buffer with uniform random bytes, and then
+ *             converts them to an integer.
+ */
+
+extern uint32 grand_defaultword(grand */*r*/);
+
+/* --- @grand_defaultrange@ --- *
+ *
+ * Arguments:  @grand *r@ = pointet to generic generator
+ *             @uint32 l@ = limit for acceptable results
+ *
+ * Returns:    A uniformly-distributed pseudorandom integer in the interval
+ *             %$[0, l)$%.
+ *
+ * Use:                Default @range@ output method.  This falls back to either
+ *             @word@ (if the generator's @max@ is zero, or if @max < l@) or
+ *             @raw@ (otherwise).  This might recurse via @fill@ and @byte@,
+ *             but this is safe because of the constraint on the @raw@
+ *             method.
+ */
+
+extern uint32 grand_defaultrange(grand */*r*/, uint32 /*l*/);
+
+/* --- @grand_defaultfill@ --- *
+ *
+ * Arguments:  @grand *r@ = pointet to generic generator
+ *             @void *p@ = pointer to a buffer
+ *             @size_t sz@ = size of the buffer
+ *
+ * Returns:    ---
+ *
+ * Use:                Fills a buffer with uniformly distributed pseudorandom bytes.
+ *             This calls the @byte@ method repeatedly to fill in the output
+ *             buffer.
+ */
+
+extern void grand_defaultfill(grand */*r*/, void */*p*/, size_t /*sz*/);
+
 /*----- Functions provided ------------------------------------------------*/
 
 /* --- @grand_byte@ --- *