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

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