I'm facing a tough decision on Double2D which could affect the entire  
community and so I'm interested in some feedback.

I've been going through the physics2d engine and doing some cleanup  
and one thing that could really help in that cleanup is to add some  
functions to Double2D which are presently only in MutableDouble2D, but  
to do so in such a way that Double2D's version would have somewhat  
different semantics.

MutableDouble2D has four kinds of ways of "adding":

MutableDouble2D m1, m2, m3;  // 2d vectors
double v;  // a scalar

m1.addIn(m2);   // m1 <- m1 + m2, return m1
m1.addIn(v);    // m1 <- m1 + v (at all slots in m1), return m1

m1.add(m2, m3); // m1 <- m2 + m3, return m1
m1.add(m2, v);  // m1 <- m2 + v (at all slots in m1), return m1

The use of "add" in this context is unfortunate, I know.  It's going  
to cause problems in a second.  But originally my idea was to enable  
stuff like this:

m1 = new MutableDouble2D().add(m2, m3).multiplyIn(v).normalize();

Which does
	m1 <- normalize((m2 + m3) * v)

... but doesn't do any new allocations at all, because at each step we  
just overwrite the variables inside the MutableDouble2D we created.

Okay, so that's cute.  The problem comes when I want to add similar  
functionality to Double2D.  I can't implement an "addIn" method  
because Double2D is IMMUTABLE.  Instead, I'd do something like this:

Double2D d1, d2, d3;
double v;

d1 = d2.add(d3).mutiply(v).normalize();

This does the same thing but at each step a new Double2D is created.   
For example,

d1.add(d2);	// new d <- d1 + d2, return d

That's a good, easy to understand functional style which is much less  
convoluted than the MutableDouble2D approach, BUT it allocates lots of  
Double2Ds, which isn't particularly efficient, though it's not  
horrible.  So it's a useful functionality to have in Double2D.

The problem is that the semantics are somewhat different than  
MutableDouble2D's semantics, in which the original object is  
OVERWRITTEN.  This is particularly obvious in the normalize() method,  
which in MutableDouble2D normalizes the actual MutableDouble2D, but  
for Double2D would produce a new Double2D (it's have to).

Also MutableDouble2D's add(...) method, for example, takes two  
arguments and has totally different semantics than Double2D's add(...)  
method would.

I'm trying to nail down what options I have.  One choice I have been  
mulling over is to add methods to Double2D like add(d) [note one  
argument], multiply(v), etc., and then also create similar  
MutableDouble2D methods with the same names.  But the question is how  
the MutableDouble2D methods should work.  Should they (A) produce NEW  
MutableDouble2D instances or (B) overwrite the existing  
MutableDouble2D instance, like other MutableDouble2D methods presently  
do?

(A) is more semantically consistent with the proposed new Double2D  
methods.

(B) is semantically consistent with the existing MutableDouble2D  
methods.

I'm trying to follow the principle of least surprise but I don't know  
which of these would have less surprise.   normalize() in particular  
will *have* to be case (B).  There's no way around it.  Which has been  
nudging me to wards doing (B).   A third option would be to just  
create Double2D methods and not create ANY equivalent MutableDouble2D  
methods.

The decision made here will have a long-standing effect on use of  
these classes, and they're so integral to MASON that I want to be very  
very careful.  Backward compatability will be retained but I am  
concerned about making things weird in the future.

So I'd really appreciate some opinions on the matter.

Sean