"Best" implementation of math operator methods?

[rgrant222]

What do you guys think the "best" implementation for a Vector2D class would be? Basically, the question I have is whether methods like add, scale, normalize, etc., should return a new instance or not. At the moment, my class behaves just like the java.math.BigInteger class. For example, the output of

Vector2D v1 = new Vector2D(3, 0);
Vector2D v2 = new Vector2D(0, 4);
Vector2D v3 = new Vector2D(1, 1);
v1.add(v2).add(v3);
System.console().format("(%.0f, %.0f)", v1.x, v1.y);

would be "(4, 5)". In other words, the add method (and others) alters the object on which it was called and then returns a self-reference (this).

I'm using Vector2D objects as instance variables in another class. The problem is that when I want to add vectors together (for example) without affecting either operand I have to call a static version of add. For example,

Vector2D result = Vector2D.add(v1, v2, v3);

instead of

Vector2D result = v1.add(v2).add(v3);

because the latter code just causes result to become an alias for v1 (changes made to result are also made to v1).

Calling the static methods clutters up my code because in many cases I need to pass altered Vector2D objects to other methods without actually altering the Vector2D objects I'm passing in as arguments.

What do Java programmer's usually expect (if anything) with math operator methods, or what is the common practice? In other words, would it be "better" to write the add method like this:

public Vector2D add(Vector2D v) {
	this.x += v.x;
	this.y += v.y;
	return this;
}

or like this:

public Vector2D add(Vector2D v) {
	Vector2D result = new Vector2D();
	result.x = this.x + v.x;
	result.y = this.y + v.y;
	return result;
}

?

[Zack]

You're probably better off using the second method. Having said this, it's personal preference for the coder. Neither is technically right or wrong, simply which one you think will be more useful in the program. However consider this:

Vector2D x = new Vector2D(5,5);
Vector2D y = x.add(new Vector2D(7,7));

Now both x and y are the same, so what's the point of even having y? If you want to keep those separate, you have to use the second implementation.

If you want my explicit opinion on what I'd expect, I can't answer that. I'd assume that the programmer working before me provided some documentation, or at the very least provided his source for me to see. That way I can tell for myself what the best way to use it. Never assume.

[JosAH]

What do Java programmer's usually expect (if anything) with math operator methods, or what is the common practice? In other words, would it be "better" to write the add method like this:

public Vector2D add(Vector2D v) {
	this.x += v.x;
	this.y += v.y;
	return this;
}

or like this:

public Vector2D add(Vector2D v) {
	Vector2D result = new Vector2D();
	result.x = this.x + v.x;
	result.y = this.y + v.y;
	return result;
}

?

Don't change the vectors; imagine what would happen if you did v.add(v).add(v). The result would not be what you expected. Make a copy constructor and operators that change the vector itself. You'll end up with things like this:

public Vector2D add(Vector2D that) {
   Vector2D copy= Vector2D(this); // create a copy
   return copy.addThis(that); // do the real addition
}
public Vector2D addThis(Vector2D that) {
   this.x+= that.x;
   this.y+= that.y;
   return this;
}

kind regards,

Jos