Sean, I agree with your points on (B), and this would be personally least surprising to me, given the other existing methods (it is mutable, after all :) I'm just a sample size of one, though. Cheers, Dr Matthew Berryman Defence and Systems Institute SPRI Building University of South Australia Mawson Lakes SA 5095 t +61 8 8302 5882 f +61 8 8302 5344 m +61 413 458 594 CRICOS Provider Number: 00121B On 29/10/2009, at 7:40 PM, Sean Luke wrote: > Not hearing a peep from the peanut gallery :-( I'm inclined to make > the (B) modifications. Going once, going twice? > > Sean > > On Oct 27, 2009, at 7:41 PM, Sean Luke wrote: > >> 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 >> >>