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 --- */
/* --- 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)$% */
#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@ --- *