9 * tally_new - allocate the tally structure.
10 * @buckets: the number of frequency buckets.
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
18 struct tally *tally_new(unsigned int buckets);
21 * tally_add - add a value.
22 * @tally: the tally structure.
23 * @val: the value to add.
25 void tally_add(struct tally *tally, ssize_t val);
28 * tally_num - how many times as tally_add been called?
29 * @tally: the tally structure.
31 size_t tally_num(const struct tally *tally);
34 * tally_min - the minimum value passed to tally_add.
35 * @tally: the tally structure.
37 * Undefined if tally_num() == 0.
39 ssize_t tally_min(const struct tally *tally);
42 * tally_max - the maximum value passed to tally_add.
43 * @tally: the tally structure.
45 * Undefined if tally_num() == 0.
47 ssize_t tally_max(const struct tally *tally);
50 * tally_mean - the mean value passed to tally_add.
51 * @tally: the tally structure.
53 * Undefined if tally_num() == 0, but will not crash.
55 ssize_t tally_mean(const struct tally *tally);
58 * tally_total - the total value passed to tally_add.
59 * @tally: the tally structure.
60 * @overflow: the overflow value (or NULL).
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).
66 ssize_t tally_total(const struct tally *tally, ssize_t *overflow);
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).
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
77 ssize_t tally_approx_median(const struct tally *tally, size_t *err);
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).
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!
88 ssize_t tally_approx_mode(const struct tally *tally, size_t *err);
90 #define TALLY_MIN_HISTO_WIDTH 8
91 #define TALLY_MIN_HISTO_HEIGHT 3
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)
99 * Returns a malloc()ed string which draws a multi-line graph of the
100 * distribution of values. On out of memory returns NULL.
102 char *tally_histogram(const struct tally *tally,
103 unsigned width, unsigned height);
104 #endif /* CCAN_TALLY_H */