Add a clamp() alias for constrain() or mention clamp in the docs

[bojidar-bg]

Increasing access

People who come from other frameworks and languages will have an easier time finding the relevant function for clamping numbers in p5.js.

Most appropriate sub-area of p5.js?

• [ ] Accessibility
• [ ] Color
• [ ] Core/Environment/Rendering
• [ ] Data
• [ ] DOM
• [ ] Events
• [ ] Image
• [ ] IO
• [X] Math
• [ ] Typography
• [ ] Utilities
• [ ] WebGL
• [ ] Build process
• [ ] Unit testing
• [ ] Internationalization
• [ ] Friendly errors
• [ ] Other (specify if possible)

Feature enhancement details

The typical name for the constrain(x, min, max) function in p5.js, used across the math and computing world, is clamp. E.g. see OpenGL, Godot/Unity, C#, Java, CSS, and C++. In comparision, less popular names include clip, used by Numpy and Octave/Mathematica/Wolphram, and, well, constrain, used by Processing/Arduino/P5.js and MakeCode.

Hence I think that it would make sense to either have clamp() as an alias to constrain() (ideal for me, as I always end up reaching for "clamp" before realizing it's different in p5), or to add a note in constrain()'s documentation that explains it's also known as clamp() elsewhere (which, together with https://github.com/processing/p5.js-website/issues/493 would allow people like me to find constrain() faster).

[msudipta888]

can you please assign me this issue

[RodrigoCastroS]

Happy to do solve this issue @bojidar-bg

[bojidar-bg]

Umm.. guys? There has been no discussion whether a clamp() alias even makes sense—so, implementing anything is premature. Looking at https://github.com/processing/p5.js/tree/main/contributor_docs#source-code-contribution, this issue is somewhere around point 2, and has not yet been approved for a PR.

[RodrigoCastroS]

Hey 👋🏼 ! thanks for the heads up @bojidar-bg since it's a bit hard to know what's the state of each issue.

What I was thinking at first, is just implement on the documentation a reference to clamp() and probably as you mentioned on the issue, it would be easier to find by web crawlers and probably the internal search bar.

Either way, it seems even adding this information to the documentation has to be discussed right? If so, keep us posted so we can work on it when this is approved for PRs.

[davepagurek]

This one is interesting, and probably needs a bit of consideration regardless of how it's addressed. I too sometimes look for clamp() by accident after using other tools so I'm sympathetic to the motivation here, although I'll explain a bit why the decision needs a bit of nuance.

If we add an alias that you can use in the editor, the implementation isn't super complicated, but also I think it'd be the only thing of its kind in p5 so far (I think, anyway -- can you think of anything else @limzykenneth?) Are there other aliases that would make sense, or would this always be a special case? So this option is potentially ok, but will maybe take some thought on whether we want aliases in general in the library.

Another option is to document this method and make it more searchable. This one is pretty easy to accept as a solution, but the implementation might be complicated. If we just add a description to the docs that other tools call this clamp() sometimes, to fully address your points on searchability, we'd also need to update the search functionality on the p5.js-website repo to be able to search that content. The search index is intentionally small because, for maintenance and cost reasons, we don't have a server, it's all static on GitHub pages. This means everything possibly searchable gets put into one file, and the browser has to load the whole thing. A possible compromise there could be to add a new section to the doc comments (maybe we call it @tag?) to specify terms to include in the search index, so that we aren't adding tons of new content. We'd have to coordinate the changes between the two repos.

The other easiest option is... to just do nothing here, and accept that tools will always have some different language. I'm also ok if this ends up being the best compromise.

[bojidar-bg]

I mean... for completeness' sake, there is also a fourth option, which would be to make the p5.js editor automatically highlight "clamp" as a warning and offer "constrain" instead... but I doubt that's even remotely better than the "do nothing" option :sweat_smile:

But yeah, that does make a lot of sense. Didn't realize there were no other aliases in the library so far; clamp would be a rather silly reason to start adding them now, especially given that similar arguments can probably be put forward for any other math function that has a different name in GLSL (length() vs mag(), trunc(), etc.). As for searching... I recall there were a few projects for making more-optimal search indexes (e.g. see hugo's documentation), and it might be the case that one of them would make searching sufficiently cheap that all the documentation would be indexable... but I do get the part about static websites, as I've deployed some myself. (Will also drop that link over in the linked issue in the website repo, just in case)

[davepagurek]

If anyone is interested in looking into the search stuff on the website repo, that could be a productive way to start! it'd be more r&d to investigate options rather than immediately working on the feature so we can understand what kind of size increase we'd be looking at.

[limzykenneth]

I also wouldn't suggest adding alias for clamp() as using constrain() is not semantically incorrect and it being inherited from Processing is an important consideration in terms of ecosystem consistency. Adding aliases also makes things complicated in terms of mental model where two different things behave the same, as a counter example: ellipse() and circle() do very similar things but semantically they are slightly different (or rather ellipse is a superset of circle) and that reflects in their API as well.

Adding a note in documentation can be considered although I personally feel it is a bit redundant especially considering the various things that can have different names in different environment, it's a bit hard to know when to add this note to something and when not to. Eg. to draw a line, p5.js use line(), Paper.js use Path.Line(), drawLine() is also another relatively common one; or for mousePressed/mouseReleased a very common alternative is mouseDown/mouseUp (use by WebAPI in fact).

[bojidar-bg]

The note in the documentation could be made really inconspicuous, like "constrain() - Clamps a number, constraining it between ...". Or, well, if we go with @davepagurek idea for an @tag documentation syntax, then it would be only made available as a search alias, and nothing more.

As for mousedown/mouseup, I would argue those are even more worthy of being mentioned than clamp, as having them would enable users to slowly "graduate" into using vanilla JS for DOM operations, without the training wheels provided by p5.js. Meanwhile, for drawLine and Path.Line, mentioning those is pointless, as they are just variations on a theme.. though perhaps, name-dropping "line segment" somewhere in the documentation would be worth, as it allows for digging deeper into the geometric concepts behind p5.js's lines.

[orrkislev]

adding clamp as an alias in the search on the website could be really good. using any search bar from recent years (moreover in AI era) I expect a much smarted search than simply looking for function name. I am sure this action would offer more enhancements, like mouseup and such.

also it could be in the FES: It seems that you may have accidentally written "clamp" instead of "constrain". Please correct it to constrain if you wish to use the function from p5.js.

and even the idea of highlighting this in the editor could be interesting, although it would probably involve a bigger change, thinking about highlighting as a whole

[computationalmama]

@orrkislev 's suggestion is very nice, during workshop/facilitation sessions for beginners "clamp" will add to extra layer of "oh no another term I don't get". Constrain works well! So the FES would address those coming in from other frameworks without diluting the ease of language p5.js provides!

[davepagurek]

Thanks @orrkislev! The FES idea is cool. I'm not super familiar with the part of the that generates those messages, but if someone is interested in looking into it to see what that would involve, that could be a great place to start!