tally: fix FreeBSD compile, memleak in tests.
[ccan] / ccan / tally / tally.h
1 #ifndef CCAN_TALLY_H
2 #define CCAN_TALLY_H
3 #include "config.h"
4 #include <sys/types.h>
5
6 struct tally;
7
8 /**
9  * tally_new - allocate the tally structure.
10  * @buckets: the number of frequency buckets.
11  *
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
16  * @height argument.
17  */
18 struct tally *tally_new(unsigned int buckets);
19
20 /**
21  * tally_add - add a value.
22  * @tally: the tally structure.
23  * @val: the value to add.
24  */
25 void tally_add(struct tally *tally, ssize_t val);
26
27 /**
28  * tally_num - how many times as tally_add been called?
29  * @tally: the tally structure.
30  */
31 size_t tally_num(const struct tally *tally);
32
33 /**
34  * tally_min - the minimum value passed to tally_add.
35  * @tally: the tally structure.
36  *
37  * Undefined if tally_num() == 0.
38  */
39 ssize_t tally_min(const struct tally *tally);
40
41 /**
42  * tally_max - the maximum value passed to tally_add.
43  * @tally: the tally structure.
44  *
45  * Undefined if tally_num() == 0.
46  */
47 ssize_t tally_max(const struct tally *tally);
48
49 /**
50  * tally_mean - the mean value passed to tally_add.
51  * @tally: the tally structure.
52  *
53  * Undefined if tally_num() == 0, but will not crash.
54  */
55 ssize_t tally_mean(const struct tally *tally);
56
57 /**
58  * tally_total - the total value passed to tally_add.
59  * @tally: the tally structure.
60  * @overflow: the overflow value (or NULL).
61  *
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).
65  */
66 ssize_t tally_total(const struct tally *tally, ssize_t *overflow);
67
68 /**
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).
72  *
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
75  * exact.
76  */
77 ssize_t tally_approx_median(const struct tally *tally, size_t *err);
78
79 /**
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).
83  *
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!
87  */
88 ssize_t tally_approx_mode(const struct tally *tally, size_t *err);
89
90 #define TALLY_MIN_HISTO_WIDTH 8
91 #define TALLY_MIN_HISTO_HEIGHT 3
92
93 /**
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)
98  *
99  * Returns a malloc()ed string which draws a multi-line graph of the
100  * distribution of values.  On out of memory returns NULL.
101  */
102 char *tally_histogram(const struct tally *tally,
103                       unsigned width, unsigned height);
104 #endif /* CCAN_TALLY_H */