-
-
Notifications
You must be signed in to change notification settings - Fork 3.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add a clamp() alias for constrain() or mention clamp in the docs #7191
Comments
can you please assign me this issue |
Happy to do solve this issue @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. |
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 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. |
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 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. |
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 😅 But yeah, that does make a lot of sense. |
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. |
I also wouldn't suggest adding alias for 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 |
The note in the documentation could be made really inconspicuous, like "constrain() - Clamps a number, constraining it between ...". As for |
adding also it could be in the FES: 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 |
@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! |
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! |
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?
Feature enhancement details
The typical name for the
constrain(x, min, max)
function in p5.js, used across the math and computing world, isclamp
. 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 toconstrain()
(ideal for me, as I always end up reaching for "clamp" before realizing it's different in p5), or to add a note inconstrain()
's documentation that explains it's also known asclamp()
elsewhere (which, together with processing/p5.js-website#493 would allow people like me to findconstrain()
faster).The text was updated successfully, but these errors were encountered: