/* Histogram.h
   Specification of a Histogram Class
   [Taken from requirements found at
    http://ciips.ee.uwa.edu.au/~morris/clp110/hist_req.html.]
   Author: J Morris
   Date Last Modified: 5 October, 1997
*/

typedef struct histogram *Histogram;

#ifndef TRUE
#define TRUE	1
#define FALSE	0
#endif

Histogram ConsHistogram( int max_bins, double reduce_factor );
/* Construct a new histogram -
   max_bins is the number of 'bins' or points in the histogram
   reduce_factor is a factor which will convert the data points integers
              in the range 0..max_bins-1
   Pre-cond: max_bins > 0
             reduce_factor != 0
   Post-cond: returns a newly constructed Histogram 
               or
              NULL if insufficient memory
*/

Histogram ConsHistRange( int max_bins, double min, double max );
/* Construct a histogram given a range (min,max)
   Pre-cond: max_bins > 0
             max > min
   Post-cond: as ConsHistogram
*/

int DeleteHistogram( Histogram h );
/* Delete a histogram.
   Pre-cond: h is a valid Histogram
   Post-cond: space used by d has been freed
              returns TRUE if no errors, FALSE on error
*/

int ClearHistogram( Histogram h );
/* Reset the Histogram h
   (allows the same space to be re-used, without 
   Pre-cond: h is a valid Histogram
   Post-cond: entries in h have all been cleared,
              max_bins and reduce_factor unaltered
*/

int Bins( Histogram h );
/* Return the number of bins in the histogram
   Pre-cond: h is a valid Histogram
   Post-cond: returns the maximum bin count
*/

int TotalPoints( Histogram h );
/* Count total points in the histogram
   Pre-cond: h is a valid Histogram
   Post-cond: returns count of points added to the Histogram
*/

int AddDatum( Histogram h, double x );
/* Add a new translation to the histogram
   Pre-cond: h is a valid Histogram
             x is in the defined range
   Post-cond: TotPoints( h ) = old TotPoints( h ) + 1
              h[floor(x*reduce_factor)] incremented by 1
*/
   
int BinCount( Histogram h, int index );
/* Return the count of items in bin index 
   Pre-cond: h is a valid Histogram and
             index >= 0 and index < max_bins
*/

double SampleMean( Histogram h );
/* Return the sample mean
   Pre-cond: h is a valid Histogram
   Post-cond: returns the mean of the data points added so far
*/ 

double SampleMedian( Histogram h, int *index );
/* Return the sample median
   Pre-cond: h is a valid Histogram
   Post-cond: returns the mean of the data points added so far
              index points to the bin in which the median was found
*/ 

int MaxFrequency( Histogram h, int *index );
/* Return the maximum bin frequency and the bin that it occurs in
   Pre-cond: h is a valid Histogram
   Post-cond: returns the maximum frequency
              index points to the bin in which the max freq occurs
*/ 

double BinSize( Histogram h );
/* Return the size of a single bin 
   Pre-cond: h is a valid Histogram
   Post-cond: return the bin size
*/