Eddy's sundry library

The sundry library began as a provision of various `basic necessities of a half-way decent programming language which were omitted by the ANSII X3J11 committee in inventing its standard for the programming language C', as the file sundry.h announces itself. It subsequently grew to include all manner of things which I find I use in my programs: then contracted when I split off the linear algebra and text manipulation fragments as separate libraries in their own right. It is the home of all the C tools that I do not regard as pertaining to any particular application: expect it to include temporary fragments like the linear and text pieces as they evolve into coherent forms warranting separate libraries.

The components of the sundry utility package are:

sundry

itself, defining (apart from some backwards-compatibility dross)

• types logical, sign, count_t, and anonymous_p,
• macros until(), skip, null (and the Null pointer) and local_fn
• Assertion macros (to which others might prefer those in <assert.h>) and
• (inline) functions on int and count_t values to return maximum and minimum values and to perform comparison returning the type sign. These serve as an example of how to arrange to use inline functions while leaving your code compilable by a plain ANSI compiler (just don't -DCanInline).

memory

as an interface to standard memory allocation functions; this interface, if used consistently, can be switched over to work via a variant which checks that memory allocation and release is being done consistently. If you hate memory leaks (and worse abuses) you'll understand why I have never regretted the few days' work this cost me: it has repayed me for the trouble many times over.

heap

provides a flexible system for managing (optionally sorted) binary trees to carry burdens of arbitrary structure-pointer type.

sums

provides low-level functionality for operations on floating-point values, including comparisons returning sign and the standard casts to integer (note that floor and ciel don't give you a cast to integer: they give you a rounding to an integral floating point value). Wrappers are also provided for certain standard library functions.

uniform

provides a simple chaotic number generator for the uniform distribution, along with a `session' key system to enable disjoint components of an application to use independent keying (seeds) for their chaotic number generators.

chaos

provides a variety of chaotic number generators built on the low-level functionality of uniform. The distributions supported are:

• integer-valued uniform (ie arbitrary die-roll);
• arbitrary probability conditional (arbitrarily weighted coin-toss);
• Poisson;
• Gaussian (aka Normal);
• gamma and its special case, negative exponential; and
• an implementation of the `ratio method' for generating values chaotically according to a distribution in bounded ratio to that of some available generator.

In all of these functions, I am deeply endebted to (now Professor) B. D. Ripley, whose paper `Computer Generation of Random Variables: A Tutorial' in the International Statistical Review [issue 51 (1983), pp. 301-319; page 311 in particular - section 4.3] introduced me to the methods used.

The memory-management code is used consistently throughout all other parts of the sundry library and all my other libraries. One convention which it sets and the rest follow is that a destruction function always returns a null pointer of the same type as it destroyed, suitable for assignment into the memory which held the pointer destroyed. This simplifies a lot of pieces of code and makes it a lot easier to abide by the discipline of setting a pointer variable to null after freeing the pointer. For comparison, you should also note various functions (eg text_list_kill in the text manipulation library; contrast with text_list_destroy) which delete an item of a recursive type and return another item of that type.

Chaos rather than Randomness.

The functions and details in the `uniform' and `chaos' modules speak of chaotically generated numbers or chaotic values, rather than using the common parlance of `random' numbers. This is prompted by my friend Nicko van Sommeren pointing out that the generation of what are formally `pseudo-random' numbers is really a piece of applied chaos theory: the iteration function of a good generator maps its internal state chaotically, in the sense that arbitrarily small variations in the initial state may induce arbitrary variation, within the feasible scope, in the final state. This has then to be tuned such that one may say something useful about the distribution of the variate extracted during the iteration, of course; and all of the language of random processes may sensibly be applied to variates thus obtained.