[2.x] Fix dimensional quirk in the `heading()` method of `p5.Vector`

[GregStanton]

Problem

The documentation defines the concept of heading for 2D vectors specifically.

• In 1.x, there are no true 2D vectors, in that z is always defined. As a result, heading() produces output for fully 3D vectors, even when z is nonzero. It also produces output for “1D” vectors, since createVector(1) could be used as a shortcut for createVector(1, 0).
• In 2.x, we have an opportunity to resolve these unintended quirks.

Solution

Supporting only 2D input and adding errors for other dimensions would allow the simplest and clearest feature specification, and it’s how users expect this feature to be used. This could be considered a bug fix: users who accidentally provide a 3D vector can now be notified of this mistake, rather than silently allowing it. In practice, it appears that this change would cause zero (or near zero) disruption.

Disruption estimate: 0%

I used the Google search phrase site:https://editor.p5js.org/ "createVector" "heading" to find 50 sketches using the heading() method. Zero of them would break if we were to implement the proposed solution.

(I did exclude a few sketches, meaning I didn’t count them toward the numerator or denominator. One case used 4D vectors in 1.x, which is not supported, and the sketch appeared to be broken already. I also excluded three sketches that used createVector() with zero arguments somewhere in their heading calculations, since it’s not 100% clear what effect this will have in 2.x. But the goal is to prevent errors from arising in this case.)

Blocking issues (foundational issues for all of p5.Vector)

If you're interested in helping to move the current issue along, you can add a comment on the current issue to indicate whether you support the proposed solution. After that, you could add a comment on the following issues to indicate whether you support the proposals they contain, along with a brief rationale.

• #8153: Consensus would clarify the meaning of 2D. In 1.x, this meant $z=0$, but according to the proposal, in 2.x it'd mean the vector has exactly two defined elements (this would resolve an inconsistency with the current implementations of .z and toString()).
• #8155: Consensus on a user-facing API for checking dimension size would enable a more stable implementation of heading(). Adding a comment on the current leading proposal (.shape), either in support of the proposal or against it, would be helpful. The exact format of this API depends on the outcome of an ongoing review of getter/setter patterns in p5, so any comments can focus on the "shape" concept.

[reshma045]

Hi @GregStanton, I would like to work on this. Can you please assign this issue to me?

[justAnotherAnotherUser]

Hi @GregStanton I would like to start work on this as mentioned in the parent issue