[2.0] Stabilize the `set()` method of `p5.Vector`

[GregStanton]

[2.0] Stabilize the set() method of p5.Vector

The set() method of p5.Vector behaves confusingly in the context of p5.js 2.x, and this behavior is the result of undocumented breaking changes. General stabilization to align with the rest of 2.x is likely warranted.

Confusing 1.x behavior

The 1.x version of set() actively modifies components that are left unspecified, in contrast with how methods like add() and mult() behave under similar circumstances.

function setup() {
  let v = createVector(1.01, 1.01, 5);
  v.set(1, 1);

  // Plausible output: `p5.Vector Object : [1, 1, 5]`
  // Actual output: `p5.Vector Object : [1, 1, 0]`
  console.log(v.toString());
}

Confusing 2.x behavior

The 2.x version is still documented as maintaining the 1.x behavior, although it does not behave that way. Instead, it mutates the dimension of the vector whenever dimensions do not match. This will often be an unintended side effect, since the name set suggests the method sets existing properties (including x, y, and z), rather than eliminating or defining new properties.

function setup() {
  let v = createVector(1.01, 1.01, 5);
  v.set(1, 1);

  // Plausible output: `[1, 1, 5]`
  // Actual output: `[1, 1]`
  console.log(v.toString());
}

The unintended side effect above is likely to occur, since users accustomed to the behavior of add() in 1.x may assume the unspecified components will be unchanged.

In addition to accidentally cropping the vector in place, it's also possible to accidentally promote the vector to a higher dimension.

function setup() {
  let v = createVector(1.01, 1.01);
  let w = createVector(1, 1, 0);
  v.set(w);

  // Plausible output: `[1, 1]`
  // Actual output: `[1, 1, 0]`
  console.log(v.toString());
}

The unintended side effect above is also reasonably likely, as users may expect only existing components to be set.

Proposed solution: Standard broadcasting rules

A simple, useful, and extensible approach is to have set() adhere to the standard broadcasting rules proposed in #8159 for other elementwise operations (set() may be viewed as an elementwise assignment operation). This will work equally well for vectors, matrices, and tensors.¹

function setup() {
  let v = createVector(1.01, 1.01, 5);
  v.set(1, 1);

  /* Error: A 3D vector can only be set in two possible ways:
  (a) with exactly 3 elements (as a list of numbers, an array, or a `p5.Vector` object)
  (b) with a single element (its value will be used for all 3 components). 
  To fix this error, extra elements may be passed directly to `set()`, 
  or if a `p5.Vector` object is passed, it may be extended with `pad()`.
  */
}

function setup() {
  let v = createVector(1.01, 1.01);
  v.set(1, 1, 0);

  /* Error: A 2D vector can only be set in two possible ways:
  (a) with exactly 2 elements (as a list of numbers, an array, or a `p5.Vector` object)
  (b) with a single element (its value will be used for all 2 components). 
  To fix this error, fewer elements may be passed directly to `set()`, 
  or if a `p5.Vector` object is passed, it may be cropped with `crop()`.
  */
}

The examples above prevent unintended side effects, in favor of more useful methods that unambiguously mutate dimension, such as crop() and pad(), which have already been proposed as a convenient "repair toolkit" to help users fix errors.

Standard broadcasting also facilitates a new, very common use case:

function setup() {
  let v = createVector(0, 0, 0, 0, 0);
  v.set(1);

  // Output: `[1, 1, 1, 1, 1]`
  console.log(v.toString());
}

Next steps (blocking issues)

• Reach a consensus on the general broadcasting policy proposed in #8159.
• Reach consensus on the API proposed in #8152, as it includes the set() method.
• Reach a consensus on applying the broadcasting policy to set(), as proposed here.

The error messages indicated above also reference pad() and crop() methods, which do not exist yet. However, that doesn't necessarily need to block progress on set(); a separate issue could be opened to update the error messages at a later time.

Edit: Added "Next steps" section.

Footnotes

1. This approach is also similar to the set() method of p5.Image, which can set a single pixel or the whole image. However, the single pixel is not broadcast. In a future 3.0 release, we could potentially create a more intuitive API by providing e.g. setPixel() for the one-pixel case to match the setElement() method of vectors, matrices, tensors, series, and sheets. (Here, setElement() is a proposed API for setting an individual element.) The set() method of p5.Image could then support broadcasting like the other set() methods. ↩

[harishbit]

I understand the problem statement. Can I start working on it ? @GregStanton

[GregStanton]

Hi @harishbit! Thank you very much for offering to help. I can assign this to you once the community reaches a consensus on how to proceed. You can assist with that process by adding a comment indicating whether or not you support the proposed solution, along with perhaps a sentence or two explaining your reasons.

This issue is also currently blocked by #8159, since it would likely be best to reach agreement on the larger API pattern before we implement it in this specific case. If you can add a comment there, to indicate whether or not you support a standard broadcasting policy in general, then that will also help us to move this forward. Thanks again!

[MRKrinetic]

I have caught up till #8159 and I understand the discussion about partial vs standard broadcasting. Partial broadcasting introduces a lot of complexity with multiple edge cases and unpredictable behaviors, which could confuse users and make debugging harder. On the other hand, standard broadcasting is simple, consistent, and easy to understand. It ensures that operations between vectors of different dimensions are predictable and intuitive for creative coding and sketching purposes, without adding unnecessary overhead or forcing users to write extra helper functions.

Feature	Standard	Partial
Predictable results	✅ Yes	❌ No
Automatic padding	❌ No	✅ Yes
User-friendly for sketches	✅ Yes	❌ Confusing
Performance overhead	✅ Minimal	⚠ Can increase if many rules checked

@GregStanton As I am aligned with Standard Broadcasting, I believe implementing this approach will make addressing the issue in #8189 more straightforward. I’m confident I can contribute effectively to the implementation

Stabilizing set() with Standard Broadcasting

Current Problem

• In 1.x: set() modified unspecified components to 0, which was confusing.
• In 2.x: set() can unexpectedly crop or extend vectors if dimensions don’t match, causing unintended side effects.

How Standard Broadcasting Helps

• Operations work if dimensions match, or if a single scalar is provided.
• Otherwise, an error is thrown.

Example:

let v = createVector(1.01, 1.01, 5);
v.set(1, 1); 
// ❌ Error: 3D vector requires exactly 3 elements or 1 scalar also 

Setting a 2D vector with 3 elements also throws a clear error instead of silently changing dimensions.

New Use Case Enabled

• Fill a vector with a single value easily:

let v = createVector(0, 0, 0, 0, 0);
v.set(1); // [1, 1, 1, 1, 1]

[GregStanton]

Thanks @MRKrinetic for offering to help! You're next in line after @harishbit. Would you mind sharing a short comment on #8159 to indicate your support for standard broadcasting? We need to reach a general consensus on that issue first, and that requires contributors like you to weigh in, either in support of the proposal or against it.