tally: implement tally_total()
[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_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 */