git.ozlabs.org Git - ccan/blob - ccan/tally/tally.h

   1 #ifndef CCAN_TALLY_H
   2 #define CCAN_TALLY_H
   3 #include "config.h"
   4 #include <sys/types.h>
   5
   6 struct tally;
   7
   8 /**
   9  * tally_new - allocate the tally structure.
  10  * @buckets: the number of frequency buckets.
  11  *
  12  * This allocates a tally structure using malloc().  The greater the value
  13  * of @buckets, the more accurate tally_approx_median() and tally_approx_mode()
  14  * and tally_histogram() will be, but more memory is consumed.  If you want
  15  * to use tally_histogram(), the optimal bucket value is the same as that
  16  * @height argument.
  17  */
  18 struct tally *tally_new(unsigned int buckets);
  19
  20 /**
  21  * tally_add - add a value.
  22  * @tally: the tally structure.
  23  * @val: the value to add.
  24  */
  25 void tally_add(struct tally *tally, ssize_t val);
  26
  27 /**
  28  * tally_num - how many times as tally_add been called?
  29  * @tally: the tally structure.
  30  */
  31 size_t tally_num(const struct tally *tally);
  32
  33 /**
  34  * tally_min - the minimum value passed to tally_add.
  35  * @tally: the tally structure.
  36  *
  37  * Undefined if tally_num() == 0.
  38  */
  39 ssize_t tally_min(const struct tally *tally);
  40
  41 /**
  42  * tally_max - the maximum value passed to tally_add.
  43  * @tally: the tally structure.
  44  *
  45  * Undefined if tally_num() == 0.
  46  */
  47 ssize_t tally_max(const struct tally *tally);
  48
  49 /**
  50  * tally_mean - the mean value passed to tally_add.
  51  * @tally: the tally structure.
  52  *
  53  * Undefined if tally_num() == 0, but will not crash.
  54  */
  55 ssize_t tally_mean(const struct tally *tally);
  56
  57 /**
  58  * tally_total - the total value passed to tally_add.
  59  * @tally: the tally structure.
  60  * @overflow: the overflow value (or NULL).
  61  *
  62  * If your total can't overflow a ssize_t, you don't need @overflow.
  63  * Otherwise, @overflow is the upper ssize_t, and the return value should
  64  * be treated as the lower size_t (ie. the sign bit is in @overflow).
  65  */
  66 ssize_t tally_total(const struct tally *tally, ssize_t *overflow);
  67
  68 /**
  69  * tally_approx_median - the approximate median value passed to tally_add.
  70  * @tally: the tally structure.
  71  * @err: the error in the returned value (ie. real median is +/- @err).
  72  *
  73  * Undefined if tally_num() == 0, but will not crash.  Because we
  74  * don't reallocate, we don't store all values, so this median cannot be
  75  * exact.
  76  */
  77 ssize_t tally_approx_median(const struct tally *tally, size_t *err);
  78
  79 /**
  80  * tally_approx_mode - the approximate mode value passed to tally_add.
  81  * @tally: the tally structure.
  82  * @err: the error in the returned value (ie. real mode is +/- @err).
  83  *
  84  * Undefined if tally_num() == 0, but will not crash.  Because we
  85  * don't reallocate, we don't store all values, so this mode cannot be
  86  * exact.  It could well be a value which was never passed to tally_add!
  87  */
  88 ssize_t tally_approx_mode(const struct tally *tally, size_t *err);
  89
  90 #define TALLY_MIN_HISTO_WIDTH 8
  91 #define TALLY_MIN_HISTO_HEIGHT 3
  92
  93 /**
  94  * tally_graph - return an ASCII image of the tally_add distribution
  95  * @tally: the tally structure.
  96  * @width: the maximum string width to use (>= TALLY_MIN_HISTO_WIDTH)
  97  * @height: the maximum string height to use (>= TALLY_MIN_HISTO_HEIGHT)
  98  *
  99  * Returns a malloc()ed string which draws a multi-line graph of the
 100  * distribution of values.  On out of memory returns NULL.
 101  */
 102 char *tally_histogram(const struct tally *tally,
 103                       unsigned width, unsigned height);
 104 #endif /* CCAN_TALLY_H */