[2.0] Stabilize behavior of `createVector()` with zero arguments

[GregStanton]

[2.0] Stabilize behavior of createVector() with zero arguments

This issue addresses, but does not fully resolve, #8117.

Documentation

Although the reference page for 1.x and the reference page for 2.0 both indicate that it's possible to use createVector() with no arguments, neither reference page specifies the behavior in that case.

Current behavior

Currently, the actual behavior in both 1.x and 2.0 is that createVector() creates a vector with components [0, 0, 0]. This made sense in 1.x, where all vectors were represented as 3D vectors, but it makes less sense in 2.0, which aims to support vectors of all possible dimensions.

Note: The behavior appears to arise from the Vector constructor, in which [0, 0, 0] is hardcoded.

Desired behavior?

Perhaps the most reasonable option is to create a zero-dimensional vector, i.e. a vector instance with zero components. Those components could be set later with e.g. the x and y fields. This seems like the most logical and predictable behavior.

Compatibility

It appears that it's not uncommon to use createVector() (without arguments) as a shortcut in 1.x, but I suppose we could add the old behavior back in with the compatibility add-on? Do you have any thoughts on this @davepagurek?

Task list

• Decide on desired behavior
• Implement it
• Document it
• Update the compatibility add-on and README if needed.

[davepagurek]

I guess the fully backwards compatible option would be to keep createVector() dimensionless and have it take on the shape of whatever it's operated upon with first? Potentially that could be done with either the addition of a flag, or using a dimension 0 vector (or some other value like -1) as a sentinel value, and then checking if we need to set the shape when doing an operation on the vector?

Another option could be to default to 2D if in a 3D sketch, and default to 3D if in a WebGL sketch, although that's not perfect either (one might do 3D math in a 2D sketch and vice versa) and doesn't extend well to custom renderers in the future.

Removal of argumentless createVector() conceptually feels ok but it might be late for a 2.x breaking change there.

[sidwellr]

I don't really see how a zero-dimensional vector would work. I start with let v = createVector(), so now v is zero-dimensional. If I then do v.x = 4.3, does that make v one-dimensional? And if I then do v.y=-3.2 does it change dimension again? And does v.add(createVector(1,2,3,4,5)) make it now have five dimensions? What if I started with let v = createVector(1) so it starts as a one dimension vector; would the other operations still change its dimension? Besides being quite difficult to implement, I don't think this is very intuitive.

My suggestion is to make createVector() with no arguments create a three dimensional vector [0, 0, 0] like it did in version 1, and does now in version 2. But generate a warning that this behavior might not be what was intended, and suggest giving the desired number of parameters. Then we can remove it in version 3.

[davepagurek]

If we do something for #8159 to allow 3D vectors with z=0 to be used with 2D vectors, then that solution works!

For completeness of that other idea though, I was imagining it as a zero vector that still has a fixed size, like other vectors, but with the specification of that size deferred until it can be inferred. So the idea would be that if you're using it consistently, it just works, and you would only get an error when you have used it in conflicting ways. e.g.:

let v = createVector()
v.set(1, 2, 3) // It's now locked in as 3D
v.add(4, 5, 6, 7) // This would now be an error

and:

let v = createVector()
// This doesn't yet set the dimension, but we know it's got at least x and y,
// so its data array gets set to [0, 5]
v.y = 5
v.add(createVector(1, 2)) // Now we confirm that it's 2D
v.mult(createVector(1, 2, 3)) // This is an error

I definitely agree that this is more complicated than not having to do it, but if we did, I think it's still feasible. I'd imagine the implementation being something part of whatever other size compatibility checks we do. Here's a sketch:

class Vector {
  constructor() {
    this.data = [];
    this.dimension = 0;
    this.minDimension = 0;
  }

  _setDimension(n) {
    if (this.dimension === n) return;
    if (this.dimension) throw new Error(`This vector is already dimension ${this.dimension}!`);
    if (this.minDimension > n) throw new Error(`This vector is already dimension ${this.minDimension}!`);
    this.dimension = n;
    while (this.data.length < n) this.data.push(0);
  }

  _setMinDimension(n) {
    if (this.dimension && this.dimension < n) throw new Error(`This vector is already dimension ${this.dimension}!`);
    this.minDimension = Math.max(this.minDimension, n);
    while (this.data.length < n) this.data.push(0);
  }

  _matchDimensions(other) {
    if (this.dimension) {
      other._setDimension(this.dimension);
    } else if (other.dimension) {
      this._setDimension(other.dimension);
    } else {
      const n = Math.max(this.minDimension, other.minDimension);
      this._setMinDimension(n);
      other._setMinDimension(n);
    }
  }

  set x(val) {
    this._setMinDimension(1);
    this.data[0] = val;
  }
  set y(val) {
    this._setMinDimension(2);
    this.data[1] = val;
  }
  set z(val) {
    this._setMinDimension(3);
    this.data[2] = val;
  }

  add(other) {
    this._matchDimensions(other);
    for (let i = 0; i < this.data.length; i++) this.data[i] += other.data[i];
  }
  sub(other) {
    this._matchDimensions(other);
    for (let i = 0; i < this.data.length; i++) this.data[i] -= other.data[i];
  }
  mult(other) {
    this._matchDimensions(other);
    for (let i = 0; i < this.data.length; i++) this.data[i] *= other.data[i];
  }
  // etc
}