tally: new module for tallying numbers.
[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_approx_median - the approximate median value passed to tally_add.
56  * @tally: the tally structure.
57  * @err: the error in the returned value (ie. real median is +/- @err).
58  *
59  * Undefined if tally_num() == 0, but will not crash.  Because we
60  * don't reallocate, we don't store all values, so this median cannot be
61  * exact.
62  */
63 ssize_t tally_approx_median(const struct tally *tally, size_t *err);
64
65 /**
66  * tally_approx_mode - the approximate mode value passed to tally_add.
67  * @tally: the tally structure.
68  * @err: the error in the returned value (ie. real mode 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 mode cannot be
72  * exact.  It could well be a value which was never passed to tally_add!
73  */
74 ssize_t tally_approx_mode(const struct tally *tally, size_t *err);
75
76 #define TALLY_MIN_HISTO_WIDTH 8
77 #define TALLY_MIN_HISTO_HEIGHT 3
78
79 /**
80  * tally_graph - return an ASCII image of the tally_add distribution
81  * @tally: the tally structure.
82  * @width: the maximum string width to use (>= TALLY_MIN_HISTO_WIDTH)
83  * @height: the maximum string height to use (>= TALLY_MIN_HISTO_HEIGHT)
84  *
85  * Returns a malloc()ed string which draws a multi-line graph of the
86  * distribution of values.  On out of memory returns NULL.
87  */
88 char *tally_histogram(const struct tally *tally,
89                       unsigned width, unsigned height);
90 #endif /* CCAN_TALLY_H */