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