/* -*-c-*-
*
- * $Id: maurer.h,v 1.1 2000/06/17 11:29:49 mdw Exp $
+ * $Id: maurer.h,v 1.2 2000/08/11 21:34:59 mdw Exp $
*
* Maurer's universal statistical test
*
/*----- Revision history --------------------------------------------------*
*
* $Log: maurer.h,v $
+ * Revision 1.2 2000/08/11 21:34:59 mdw
+ * New restartable interface to Maurer testing.
+ *
* Revision 1.1 2000/06/17 11:29:49 mdw
* Maurer's universal statistical test.
*
#include <mLib/bits.h>
+/*----- Data structures ---------------------------------------------------*/
+
+typedef struct maurer_ctx {
+ unsigned l; /* Chunk size, in bits */
+ uint32 a; /* Bitscanner accumulator */
+ unsigned b; /* Number of bits in accumulator */
+ unsigned long n; /* Number of chunks read so far */
+ double x; /* Statistic value */
+ unsigned long *t; /* Offset table */
+} maurer_ctx;
+
/*----- Functions provided ------------------------------------------------*/
+/* --- @maurer_init@ --- *
+ *
+ * Arguments: @maurer_ctx *m@ = pointer to a context to initialize
+ * @unsigned l@ = number of bits to take at a time
+ *
+ * Returns: Minimum recommended amount of data to test.
+ *
+ * Use: Initializes a Maurer testing context. Note that @l@ values
+ * larger than 16 are not supported, and values less than 6 can
+ * give bizarre results.
+ */
+
+extern unsigned long maurer_init(maurer_ctx */*m*/, unsigned /*l*/);
+
+/* --- @maurer_test@ --- *
+ *
+ * Arguments: @maurer_ctx *m@ = pointer to a Maurer testing context
+ * @const void *buf@ = pointer to a buffer of data
+ * @size_t sz@ = size of the buffer
+ *
+ * Returns: ---
+ *
+ * Use: Scans a buffer of data and updates the testing context.
+ */
+
+extern void maurer_test(maurer_ctx */*m*/,
+ const void */*buf*/, size_t /*sz*/);
+
+/* --- @maurer_done@ --- *
+ *
+ * Arguments: @maurer_ctx *m@ = pointer to a Maurer testing context
+ *
+ * Returns: The statistic %$Z_u = (X_u - \mu)/\sigma$%, which should be
+ * normally distributed with a mean of 0 and variance of 1.
+ *
+ * Use: Returns the result of Maurer's universal statistical test.
+ * Also frees the memory allocated during initialization.
+ *
+ * If insufficient data was received, the value @HUGE_VAL@ is
+ * returned.
+ */
+
+extern double maurer_done(maurer_ctx */*m*/);
+
/* --- @maurer@ --- *
*
* Arguments: @const octet *p@ = pointer to a buffer of data
* @size_t sz@ = size of the buffer
* @unsigned l@ = number of bits to take at a time
*
- * Returns: The statistic %$Z_u = (X_u - \mu)/\sigma$%, which should be
- * normally distributed with a mean of zero and standard
- * deviation of 1.
- *
- * Use: Performs Maurer's universal statistical test on a buffer of
- * data. You must ensure that the buffer size @sz@ is larger
- * than %$11 l \cdot 2^l$% bits long, and ideally much larger.
+ * Returns: The statistic %$Z_u$%.
*
- * Note that, under Unix systems, this function requires the
- * maths library.
+ * Use: Simple interface to Maurer's universal statistical test. For
+ * large %$l$% you should use the more complicated restartable
+ * interface.
*/
extern double maurer(const octet */*p*/, size_t /*sz*/, unsigned /*l*/);