P5.js: remove array methods?

[lmccart]

At a recent contributor meetup, the question was raised whether we really needed the array methods (append, concat, splice, etc), since they are such close aliases of existing JS array methods. There is the added complication with native JS methods of requiring the dot operator to use them, but by the time someone is using arrays, is it safe to assume they would be able to comprehend the dot? Is there another reason for keeping them in?

cc @shiffman

[shiffman]

I am in favor of removing them! I think we could consider leaving our own "documentation" in the p5.js reference for the most common methods like push(), splice(), . . .

This is similar to what we did with String in Processing.

https://processing.org/reference/String.html
https://processing.org/reference/String_toLowerCase_.html

The array methods made sense in the Processing API since users would otherwise have to learn about ArrayLists, but here since the methods are simply duplicates of native JS I don't think it makes sense for us to re-implement them. When it's time for one of these functions, it's a good time for a user to learn about how an array is an object.

[limzykenneth]

If we decided to remove our implementation in p5.js, I would prefer as @shiffman suggest, to leave the "documentation" (albeit edit to fit native implementation) behind as even I'm also sometimes confused as to which of the array functions mutates the array while which of them return a new array.

[meiamsome]

Would this be a deprecation initially? Perhaps add an error to them from FES when they are first used in sketches.

[Spongman]

i vote we keep the legacy methods for backwards compatibility, but just mark them with @deprecated attributes in their docs and have those comments rendered prominently in the reference docs.

````
/**

• @method reverse
• @deprecated Use Array.reverse() instead.
  */
  ````

[shiffman]

Would it make sense to do as @Spongman suggests but when there is a major release (0.7.0? 1.0.0?) remove them permanently?

[ghost]

@shiffman I think it makes perfect sense, but only when changing version. Of course, the choice between changing version, release or level becomes very important at that moment.

I'm in favour of the idea of @Spongman since backward compatibility is very important, especially for beginners and non-programmers/artists/... who don't like to redo the programming they already did.

Below, I'm using the terminology version.release.level I'm in favour of the following:

• A new version is like a new library or program - no supposed backward compatibility
• A new release comes with substantial new functionality and backward compatibility.
• A new level comes with a substantial number of bug fixes and backward compatibility.

Of course, with some documentation (keep the used version of the p5js library with your code, possibility to download a specific old version), backward compatibility will also be guaranteed for a longer period.

[Spongman]

Fwiw https://semver.org/ is pretty much the standard for this.

[kjhollen]

+1 for deprecation and eventual removal. this was confusing for students in my class last fall; I'd been showing them the Mozilla developer docs and they wanted to know if p5 arrays were different from javascript arrays.

My gut says that with a version number like 0.x.y it's ok to break things, but I'm not sure most of our audience is that attuned to version number meanings—so good to be more generous with backwards compatibility. (so, also a +1 to eventually adopting semantic versioning, maybe post 1.0?)

[Spongman]

ok, now that #2755 is merged, it just remains to enumerate those methods to be deprecated and augment the docs similarly to append():

/**
 * @method append
 * @deprecated Use <code class='language-javascript'>array.push(value)</code> instead.

[aparrish]

I agree with the thinking here but I wish you'd keep shuffle()—maybe reclassify it in the Math/Random section of the reference? There's no easy single-expression equivalent for shuffle() in JavaScript and I find myself using it in teaching and projects fairly frequently (way easier than copy/pasting whichever ramshackle fisher-yates implementation has floated to the top of a stack overflow thread).

[limzykenneth]

I agree shuffle should be kept in some form as it isn't a duplicate of native js array function. @aparrish Maybe open a new issue for it?

[lmccart]

yes this seems reasonable