Expunge revision histories in files.

[u/mdw/catacomb] / maurer.h

diff --git a/maurer.h b/maurer.h
index cd74e8c..6dbaa67 100644 (file)
--- a/maurer.h
+++ b/maurer.h
@@ -1,6 +1,6 @@
 /* -*-c-*-
  *
- * $Id: maurer.h,v 1.1 2000/06/17 11:29:49 mdw Exp $
+ * $Id: maurer.h,v 1.3 2004/04/08 01:36:15 mdw Exp $
  *
  * Maurer's universal statistical test
  *
@@ -27,14 +27,6 @@
  * MA 02111-1307, USA.
  */
 
-/*----- Revision history --------------------------------------------------* 
- *
- * $Log: maurer.h,v $
- * Revision 1.1  2000/06/17 11:29:49  mdw
- * Maurer's universal statistical test.
- *
- */
-
 #ifndef CATACOMB_MAURER_H
 #define CATACOMB_MAURER_H
 
@@ -46,24 +38,74 @@
 
 #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*/);