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