tally: new module for tallying numbers.

ccan/tally/_info

+#include <stdio.h>
+#include <string.h>
+#include "config.h"
+
+/**
+ * tally - running tally of integers
+ *
+ * The tally module implements simple analysis of a stream of integers.
+ * Numbers are fed in via tally_add(), and then the mean, median, mode and
+ * a histogram can be read out.
+ *
+ * Example:
+ *	#include <stdio.h>
+ *	#include <err.h>
+ *	#include <ccan/tally/tally.h>
+ *
+ *	int main(int argc, char *argv[])
+ *	{
+ *		struct tally *t;
+ *		unsigned int i;
+ *		size_t err;
+ *		ssize_t val;
+ *		char *histogram;
+ *
+ *		if (argc < 2)
+ *			errx(1, "Usage: %s <number>...\n", argv[0]);
+ *
+ *		t = tally_new(100);
+ *		for (i = 1; i < argc; i++)
+ *			tally_add(t, atol(argv[i]));
+ *
+ *		printf("Mean = %zi\n", tally_mean(t));
+ *		val = tally_approx_median(t, &err);
+ *		printf("Median = %zi (+/- %zu)\n", val, err);
+ *		val = tally_approx_mode(t, &err);
+ *		printf("Mode = %zi (+/- %zu)\n", val, err);
+ *		histogram = tally_histogram(t, 50, 10);
+ *		printf("Histogram:\n%s", histogram);
+ *		free(histogram);
+ *		return 0;
+ *	}
+ *
+ * Licence: LGPL (3 or any later version)
+ * Author: Rusty Russell <rusty@rustcorp.com.au>
+ */
+int main(int argc, char *argv[])
+{
+	if (argc != 2)
+		return 1;
+
+	if (strcmp(argv[1], "depends") == 0) {
+		printf("ccan/build_assert\n");
+		printf("ccan/likely\n");
+		return 0;
+	}
+
+	return 1;
+}

ccan/tally/tally.h

+#ifndef CCAN_TALLY_H
+#define CCAN_TALLY_H
+#include <stdlib.h>
+
+struct tally;
+
+/**
+ * tally_new - allocate the tally structure.
+ * @buckets: the number of frequency buckets.
+ *
+ * This allocates a tally structure using malloc().  The greater the value
+ * of @buckets, the more accurate tally_approx_median() and tally_approx_mode()
+ * and tally_graph() will be, but more memory is consumed.
+ */
+struct tally *tally_new(size_t buckets);
+
+/**
+ * tally_add - add a value.
+ * @tally: the tally structure.
+ * @val: the value to add.
+ */
+void tally_add(struct tally *tally, ssize_t val);
+
+/**
+ * tally_num - how many times as tally_add been called?
+ * @tally: the tally structure.
+ */
+size_t tally_num(const struct tally *tally);
+
+/**
+ * tally_min - the minimum value passed to tally_add.
+ * @tally: the tally structure.
+ *
+ * Undefined if tally_num() == 0.
+ */
+ssize_t tally_min(const struct tally *tally);
+
+/**
+ * tally_max - the maximum value passed to tally_add.
+ * @tally: the tally structure.
+ *
+ * Undefined if tally_num() == 0.
+ */
+ssize_t tally_max(const struct tally *tally);
+
+/**
+ * tally_mean - the mean value passed to tally_add.
+ * @tally: the tally structure.
+ *
+ * Undefined if tally_num() == 0, but will not crash.
+ */
+ssize_t tally_mean(const struct tally *tally);
+
+/**
+ * tally_approx_median - the approximate median value passed to tally_add.
+ * @tally: the tally structure.
+ * @err: the error in the returned value (ie. real median is +/- @err).
+ *
+ * Undefined if tally_num() == 0, but will not crash.  Because we
+ * don't reallocate, we don't store all values, so this median cannot be
+ * exact.
+ */
+ssize_t tally_approx_median(const struct tally *tally, size_t *err);
+
+/**
+ * tally_approx_mode - the approximate mode value passed to tally_add.
+ * @tally: the tally structure.
+ * @err: the error in the returned value (ie. real mode is +/- @err).
+ *
+ * Undefined if tally_num() == 0, but will not crash.  Because we
+ * don't reallocate, we don't store all values, so this mode cannot be
+ * exact.  It could well be a value which was never passed to tally_add!
+ */
+ssize_t tally_approx_mode(const struct tally *tally, size_t *err);
+
+#define TALLY_MIN_HISTO_WIDTH 8
+#define TALLY_MIN_HISTO_HEIGHT 3
+
+/**
+ * tally_graph - return an ASCII image of the tally_add distribution
+ * @tally: the tally structure.
+ * @width: the maximum string width to use (>= TALLY_MIN_HISTO_WIDTH)
+ * @height: the maximum string height to use (>= TALLY_MIN_HISTO_HEIGHT)
+ *
+ * Returns a malloc()ed string which draws a multi-line graph of the
+ * distribution of values.  On out of memory returns NULL.
+ */
+char *tally_histogram(const struct tally *tally,
+		      unsigned width, unsigned height);
+#endif /* CCAN_TALLY_H */

ccan/tally/test/run-bucket_of.c

+#include <ccan/tally/tally.c>
+#include <ccan/tap/tap.h>
+
+int main(void)
+{
+	unsigned int i, max_step;
+	ssize_t min, max;
+
+	max = (ssize_t)~(1ULL << (sizeof(max)*CHAR_BIT - 1));
+	min = (ssize_t)(1ULL << (sizeof(max)*CHAR_BIT - 1));
+	max_step = sizeof(max)*CHAR_BIT;
+
+	plan_tests(2 + 100 + 10 + 5
+		   + 2 + 100 + 5 + 4
+		   + (1 << 7) * (max_step - 7));
+
+	/* Single step, single bucket == easy. */ 
+	ok1(bucket_of(0, 0, 0) == 0);
+
+	/* Double step, still in first bucket. */
+	ok1(bucket_of(0, 1, 0) == 0);
+
+	/* Step 8. */
+	for (i = 0; i < 100; i++)
+		ok1(bucket_of(0, 3, i) == i >> 3);
+
+	/* 10 values in 5 buckets, step 2. */
+	for (i = 0; i < 10; i++)
+		ok1(bucket_of(0, 1, i) == i >> 1);
+
+	/* Extreme cases. */
+	ok1(bucket_of(min, 0, min) == 0);
+	ok1(bucket_of(min, max_step-1, min) == 0);
+	ok1(bucket_of(min, max_step-1, max) == 1);
+	ok1(bucket_of(min, max_step, min) == 0);
+	ok1(bucket_of(min, max_step, max) == 0);
+
+	/* Now, bucket_min() should match: */
+	ok1(bucket_min(0, 0, 0) == 0);
+
+	/* Double step, val in first bucket still 0. */
+	ok1(bucket_min(0, 1, 0) == 0);
+
+	/* Step 8. */
+	for (i = 0; i < 100; i++)
+		ok1(bucket_min(0, 3, i) == i << 3);
+
+	/* 10 values in 5 buckets, step 2. */
+	for (i = 0; i < 5; i++)
+		ok1(bucket_min(0, 1, i) == i << 1);
+
+	/* Extreme cases. */
+	ok1(bucket_min(min, 0, 0) == min);
+	ok1(bucket_min(min, max_step-1, 0) == min);
+	ok1(bucket_min(min, max_step-1, 1) == 0);
+	ok1(bucket_min(min, max_step, 0) == min);
+
+	/* Now, vary step and number of buckets, but bucket_min and bucket_of
+	 * must agree. */
+	for (i = 0; i < (1 << 7); i++) {
+		unsigned int j;
+		for (j = 0; j < max_step - 7; j++) {
+			ssize_t val;
+
+			val = bucket_min(-(ssize_t)i, j, i);
+			ok1(bucket_of(-(ssize_t)i, j, val) == i);
+		}
+	}
+
+	return exit_status();
+}

ccan/tally/test/run-divlu64.c

+#include <ccan/tally/tally.c>
+#include <ccan/tap/tap.h>
+
+int main(void)
+{
+	unsigned int i, j;
+
+	plan_tests(5985);
+	/* Simple tests. */
+	for (i = 0; i < 127; i++) {
+		uint64_t u1, u0;
+		if (i < 64) {
+			u1 = 0;
+			u0 = 1ULL << i;
+			j = 0;
+		} else {
+			u1 = 1ULL << (i - 64);
+			u0 = 0;
+			j = i - 63;
+		}
+		for (; j < 63; j++) {
+			uint64_t answer;
+			if (j > i)
+				answer = 0;
+			else
+				answer = 1ULL << (i - j);
+			ok1(divlu64(u1, u0, 1ULL << j) == answer);
+		}
+	}
+	return exit_status();
+}

ccan/tally/test/run-histogram.c

+#include <ccan/tally/tally.c>
+#include <ccan/tap/tap.h>
+
+int main(void)
+{
+	int i;
+	struct tally *tally;
+	char *graph, *p;
+	bool trunc;
+
+	plan_tests(100 + 1 + 10 + 1 + 100 + 1 + 10 + 1 + 10 + 2 + 1);
+
+	/* Uniform distribution, easy. */
+	tally = tally_new(100);
+	for (i = 0; i < 100; i++)
+		tally_add(tally, i);
+
+	/* 1:1 height. */
+	graph = p = tally_histogram(tally, 20, 100);
+	for (i = 0; i < 100; i++) {
+		char *eol = strchr(p, '\n');
+
+		/* We expect it filled all way to the end. */
+		ok1(eol - p == 20);
+		p = eol + 1;
+	}
+	ok1(!*p);
+	free(graph);
+
+	/* Reduced height. */
+	trunc = false;
+	graph = p = tally_histogram(tally, 20, 10);
+	for (i = 0; i < 10; i++) {
+		char *eol = strchr(p, '\n');
+
+		/* Last once can be truncated (bucket aliasing) */
+		if (eol) {
+			if (eol - p < 20) {
+				ok1(!trunc);
+				trunc = true;
+			} else if (eol - p == 20) {
+				ok1(!trunc);
+			} else {
+				fail("Overwidth line %s", p);
+			}
+		} else
+			/* We should, at worst, half-fill graph */
+			ok1(i > 5);
+
+		if (eol)
+			p = eol + 1;
+	}
+	ok1(!*p);
+	free(graph);
+
+	/* Enlarged height (gets capped). */
+	graph = p = tally_histogram(tally, 20, 1000);
+	for (i = 0; i < 100; i++) {
+		char *eol = strchr(p, '\n');
+		/* We expect it filled all way to the end. */
+		ok1(eol - p == 20);
+		p = eol + 1;
+	}
+	ok1(!*p);
+	free(graph);
+	free(tally);
+
+	/* Distinctive increasing pattern. */
+	tally = tally_new(10);
+	for (i = 0; i < 10; i++) {
+		unsigned int j;
+		for (j = 0; j <= i; j++)
+			tally_add(tally, i);
+	}
+
+	graph = p = tally_histogram(tally, 10, 10);
+	for (i = 0; i < 10; i++) {
+		char *eol = strchr(p, '\n');
+		ok1(eol - p == i+1);
+		p = eol + 1;
+	}
+	ok1(!*p);
+	diag("Here's the pretty: %s", graph);
+	free(graph);
+	free(tally);
+
+	/* With negative values. */
+	tally = tally_new(10);
+	for (i = 0; i < 10; i++) {
+		tally_add(tally, i - 5);
+	}
+
+	graph = p = tally_histogram(tally, 10, 10);
+	for (i = 0; i < 10; i++) {
+		char *eol = strchr(p, '\n');
+
+		/* We expect it filled all way to the end. */
+		ok1(eol - p == 10);
+
+		/* Check min/max labels. */
+		if (i == 0)
+			ok1(strncmp(p, "-5*", 3) == 0);
+		if (i == 9)
+			ok1(strncmp(p, "4*", 2) == 0);
+		p = eol + 1;
+	}
+	ok1(!*p);
+	free(graph);
+	free(tally);
+
+	return exit_status();
+}

ccan/tally/test/run-mean.c

+#include <ccan/tally/tally.c>
+#include <ccan/tap/tap.h>
+
+int main(void)
+{
+	int i;
+	struct tally *tally = tally_new(0);
+	ssize_t min, max;
+
+	max = (ssize_t)~(1ULL << (sizeof(max)*CHAR_BIT - 1));
+	min = (ssize_t)(1ULL << (sizeof(max)*CHAR_BIT - 1));
+
+	plan_tests(100 + 100);
+	/* Simple mean test: should always be 0. */
+	for (i = 0; i < 100; i++) {
+		tally_add(tally, i);
+		tally_add(tally, -i);
+		ok1(tally_mean(tally) == 0);
+	}
+
+	/* Works for big values too... */
+	for (i = 0; i < 100; i++) {
+		tally_add(tally, max - i);
+		tally_add(tally, min + 1 + i);
+		ok1(tally_mean(tally) == 0);
+	}
+
+	return exit_status();
+}

ccan/tally/test/run-median.c

+#include <ccan/tally/tally.c>
+#include <ccan/tap/tap.h>
+
+int main(void)
+{
+	int i;
+	struct tally *tally = tally_new(100);
+	ssize_t min, max, median;
+	size_t err;
+
+	max = (ssize_t)~(1ULL << (sizeof(max)*CHAR_BIT - 1));
+	min = (ssize_t)(1ULL << (sizeof(max)*CHAR_BIT - 1));
+
+	plan_tests(100*2 + 100*2 + 100*2);
+	/* Simple median test: should always be around 0. */
+	for (i = 0; i < 100; i++) {
+		tally_add(tally, i);
+		tally_add(tally, -i);
+		median = tally_approx_median(tally, &err);
+		ok1(err <= 4);
+		ok1(median - (ssize_t)err <= 0 && median + (ssize_t)err >= 0);
+	}
+
+	/* Works for big values too... */
+	for (i = 0; i < 100; i++) {
+		tally_add(tally, max - i);
+		tally_add(tally, min + 1 + i);
+		median = tally_approx_median(tally, &err);
+		/* Error should be < 100th of max - min. */
+		ok1(err <= max / 100 * 2);
+		ok1(median - (ssize_t)err <= 0 && median + (ssize_t)err >= 0);
+	}
+	free(tally);
+
+	tally = tally_new(10);
+	for (i = 0; i < 100; i++) {
+		tally_add(tally, i);
+		median = tally_approx_median(tally, &err);
+		ok1(err <= i / 10 + 1);
+		ok1(median - (ssize_t)err <= i/2
+		    && median + (ssize_t)err >= i/2);
+	}
+
+	return exit_status();
+}

ccan/tally/test/run-min-max.c

+#include <ccan/tally/tally.c>
+#include <ccan/tap/tap.h>
+
+int main(void)
+{
+	int i;
+	struct tally *tally = tally_new(0);
+
+	plan_tests(100 * 4);
+	/* Test max, min and num. */
+	for (i = 0; i < 100; i++) {
+		tally_add(tally, i);
+		ok1(tally_num(tally) == i*2 + 1);
+		tally_add(tally, -i);
+		ok1(tally_num(tally) == i*2 + 2);
+		ok1(tally_max(tally) == i);
+		ok1(tally_min(tally) == -i);
+	}
+	return exit_status();
+}

ccan/tally/test/run-mode.c

+#include <ccan/tally/tally.c>
+#include <ccan/tap/tap.h>
+
+int main(void)
+{
+	int i;
+	struct tally *tally = tally_new(100);
+	ssize_t min, max, mode;
+	size_t err;
+
+	max = (ssize_t)~(1ULL << (sizeof(max)*CHAR_BIT - 1));
+	min = (ssize_t)(1ULL << (sizeof(max)*CHAR_BIT - 1));
+
+	plan_tests(100 + 50 + 100 + 100 + 10);
+	/* Simple mode test: should always be around 0 (we add that twice). */
+	for (i = 0; i < 100; i++) {
+		tally_add(tally, i);
+		tally_add(tally, -i);
+		mode = tally_approx_mode(tally, &err);
+		if (i < 50)
+			ok1(err == 0);
+		ok1(mode - (ssize_t)err <= 0 && mode + (ssize_t)err >= 0);
+	}
+
+	/* Works for big values too... */
+	for (i = 0; i < 100; i++) {
+		tally_add(tally, max - i);
+		tally_add(tally, min + 1 + i);
+		mode = tally_approx_mode(tally, &err);
+		ok1(mode - (ssize_t)err <= 0 && mode + (ssize_t)err >= 0);
+	}
+	free(tally);
+
+	tally = tally_new(10);
+	tally_add(tally, 0);
+	for (i = 0; i < 100; i++) {
+		tally_add(tally, i);
+		mode = tally_approx_mode(tally, &err);
+		if (i < 10)
+			ok1(err == 0);
+		ok1(mode - (ssize_t)err <= 0 && mode + (ssize_t)err >= 0);
+	}
+
+	return exit_status();
+}

ccan/tally/test/run-renormalize.c

+#include <ccan/tally/tally.c>
+#include <ccan/tap/tap.h>
+
+int main(void)
+{
+	struct tally *tally = tally_new(1);
+
+	plan_tests(4);
+	tally->min = 0;
+	tally->max = 0;
+	tally->counts[0] = 1;
+
+	/* This renormalize should do nothing. */
+	renormalize(tally, 0, 1);
+	ok1(tally->counts[0] == 1);
+	ok1(tally->counts[1] == 0);
+	tally->counts[1]++;
+
+	/* This renormalize should collapse both into bucket 0. */
+	renormalize(tally, 0, 3);
+	ok1(tally->counts[0] == 2);
+	ok1(tally->counts[1] == 0);
+
+	return exit_status();
+}