This library probably isn't much use to anyone but myself but read on if you're curious!
fd-geom-test is a helper library I've been using to test my recent spate of geometry libraries such as
fd-rect, and so-on.
Geometry code often involves manipulating lots of temporary intermediate data, and since these are usually composite values such as points and rectangles it's necessary to represent them using objects. Rapidly allocating these temporary values, however, can be inefficient, so sometimes it makes sense ease GC pressure by reusing previously-allocated objects rather than creating new ones. On the flip-side, unfortunately, this style of programming often results in a more verbose and somewhat opaque API. Compare:
var v1 = ;var v2 = ;var v3 = ;return v1;
var v1 = ;var v2 = ;var v3 = ;// v1 <- v1 + v2vec2;// v1 <- v1 + v3vec2;return v1;
The second example creates fewer temporary objects but the price is that its API is less intuitive. Most of the time, however, we're not worried about efficiency so the code in the more readable first example should be fine.
All of my geometry libraries expose their operations through three "flavours" of API, allowing readable code to be used the majority of the time, with the option to drop down to more memory-efficient methods as necessary. The three API flavours are:
v1.add(v2). These operations always return brand new instances and should perform deep-cloning as necessary.
v1.add_(v2). These operations modify the receiver in-place.
outparameter which receives the result value which should must be pre-initialised with an instance of the correct type. All operations must function correctly if the same object is passed in multiple argument positions e.g.
vec2.add(v1, v2, v1), which adds
v1and stores the result in
Additionally, each object class obeys the following contract:
clone()method which returns a new instance with the same value(s)
eq()method for testing equality with other instances
Based on this contract,
fd-geom-test exposes a set of helper fucntions to simultaneously test all three API variants. For example:
var tape = ;var vec2 = ;tape vec2;
The above code tests that all three variants of the
add calculate the same result.