lib/ccan/tally/tally.h

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