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

[GregStanton]

Problem

• In 1.x, any heading can be applied to a vector made with createVector(1), as this is just a shorthand for creating the vector [1, 0, 0].
• In 2.x, rotating a 1D vector by a value like HALF_PI would require its dimension to be mutated, which would likely be an unintended side effect.

Solution

The simplest solution is to have setHeading() support only 2D vectors in 2.x, adding error messages for vectors of other dimensions. This conforms to the documented definition of “heading” as an angle in the $xy$-plane, and fixes a quirk of the 1.x feature. It's also consistent with the proposed fix for heading() in #8214.

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 setHeading(). 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.

[Homaid]

I agree that restricting setHeading() to 2D vectors is the most straightforward and consistent solution for 2.x. i was thinking it might be useful if we keep the current behavior strict (only 2D vectors allowed by default, with a clear error message) and optionally, allow an extra parameter like setHeading(angle, plane) so advanced users can specify which plane ("xy", "xz", "yz", or [0,2]) to rotate within for ndimensional vectors.

[reshma045]

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

[GregStanton]

Thanks @Homaid! I appreciate you sharing your thoughts about the proposed solution. Regarding rotation in other planes, I'm really glad you mentioned this! It's an interesting idea. I actually just published a proposal to support this in the rotate() function (see #8218). That might be a good place to offer the functionality you described, since it's necessary for consistency with the standalone rotate() function anyway, and it'd allow us to continue documenting the "heading" concept in the simplest way possible: it's the angle a vector makes with the positive $x$-axis, measured clockwise.

[GregStanton]

Hi @reshma045! Thank you so much for offering to help. I'd like to assign this issue to you, but I should make a couple notes first.

First, there's an ongoing discussion about supporting true 1D/2D vectors in 2.x. For example, there's currently a PR (#8203) that would block this, but it hasn't been approved just yet, and the options are being discussed. This proposal assumes the existence of true 1D/2D vectors (i.e. a true 1D vector has exactly one element, rather than having $y$ and $z$ elements equal to zero).

Second, the related heading() issue contains a proposal that still needs to be approved, since that contains a breaking change, although evidence suggests it wouldn't break anyone's code in practice.

Although you volunteered just before @justAnotherAnotherUser on the heading() issue, they had already offered to help previously, and had been patiently waiting for me to post the sub-issue. Since these two issues are closely related, it might make sense for one person to tackle both, but would the two of you be interested to collaborate, perhaps by reviewing each other's PRs? That might be ideal. In that case, I can assign this setHeading() issue to @reshma045 and the heading() issue to @justAnotherAnotherUser.

If that sounds good, then we can talk about next steps. The first thing would be to comment on the blocking issues, if you haven't already, as noted in the top of this issue. Thanks again to you both!