[css-values-4] The rest of the JS math functions #4688
Description
Here's the list of all the properties on the JS Math object:
abs: ƒ abs()acos: ƒ acos()acosh: ƒ acosh()asin: ƒ asin()asinh: ƒ asinh()atan: ƒ atan()atanh: ƒ atanh()atan2: ƒ atan2()ceil: ƒ ceil() cbrt: ƒ cbrt() expm1: ƒ expm1() clz32: ƒ clz32()cos: ƒ cos()cosh: ƒ cosh() exp: ƒ exp() floor: ƒ floor() fround: ƒ fround()hypot: ƒ hypot()imul: ƒ imul() log: ƒ log() log1p: ƒ log1p() log2: ƒ log2() log10: ƒ log10()max: ƒ max()min: ƒ min()pow: ƒ pow()random: ƒ random() round: ƒ round() sign: ƒ sign()sin: ƒ sin()sinh: ƒ sinh()sqrt: ƒ sqrt()tan: ƒ tan()tanh: ƒ tanh() trunc: ƒ trunc() E: 2.718281828459045 LN10: 2.302585092994046 LN2: 0.6931471805599453 LOG10E: 0.4342944819032518 LOG2E: 1.4426950408889634 PI: 3.141592653589793 SQRT1_2: 0.7071067811865476 SQRT2: 1.4142135623730951
I've crossed out the things we already have in the spec. Of the leftovers, I think we can break them into a few categories:
General Algebra
- abs()
- cbrt()
- sign()
I'm happy to add sign() (#4673). I'd be fine with adding cbrt() too; it's lower-value than sqrt(), but sure, might as well. abs() can be done with single-argument hypot(), but might as well have the better-named version as well. So these are all plausible additions.
Hyperbolic Trig
- sinh()
- cosh()
- tanh()
- asin()
- acos()
- atanh()
I've never had to use the hyperbolic functions in my life. If there's a reasonable argument for them being useful, I'm fine with adding them, but until then I consider these something we can safely skip.
Logs
- log()
- log1p() (literally
x=>Math.log(1+x)) - log2()
- log10()
- exp()
- expm1() (literally
x=>Math.exp(x) - 1)
In general I think we could add these reasonably. exp() is currently handleable with pow(), if you write in e explicitly, but that's clumsy.
Logs seem useful, but we should just have a single function with an optional second arg for the base, rather than introduce three differently-named variants. Other than precision issues, log2(x) is exactly equivalent to log(x) / log(2), after all.
I don't think we should add log1p() and expm1(); I suspect they're just things we pulled in from Java? You can just use math, dang: log(1 + x) and calc(exp(x) - 1).
So in conclusion I think log(val, base?) (with base defaulting to e) and exp() are reasonable to add.
Rounding
- ceil()
- floor()
- fround()
- round()
- trunc()
Covered in #2513. Current proposal is to add a round() function, with keywords distinguishing between ceil/floor/round/trunc behavior. fround() is ignored due to lack of use-cases.
Constants
- E: 2.718281828459045
- LN10: 2.302585092994046
- LN2: 0.6931471805599453
- LOG10E: 0.4342944819032518
- LOG2E: 1.4426950408889634
- PI: 3.141592653589793
- SQRT1_2: 0.7071067811865476
- SQRT2: 1.4142135623730951
Pi and E might have reasonable cases. E can be written as exp(1), which might be reasonable to just stick with (with a note calling it out). Pi is calc(2 * acos(0)), or a few other possibilities, which is a lot less reasonable, but a lot of places that need Pi take angles already. Unclear if it's needed or not.
If we did add them, I guess they'd be added as zero-arg functions e() and pi()? Weird, but at least functions are already fine grammatically in calc expressions.
The rest of the constants are just existing easy expressions, with their values baked into constants for speed in hot loops. I don't think we need them.
Stuff We Probably Don't Want
- random()
- clz32()
- imul()
random() can't be done; it's a totally different topic.
clz32() (round to a 32-bit integer, count number of leading zeros in the binary representation) and imul() (do a C-like 32-bit integer multiply) are both odd things that I don't think we have any usecases for.
So in conclusion, beyond the things already discussed in #4673 (sign()) and #2513 (round()), we might want to add:
- abs()
- cbrt()
- log()
- exp() (unless we add e())
- maybe e() and pi()
...and then we're done, I think.