[css-values-4] Add trig and exponent functions, as resolved at the F2F. Fixes #2331.

Author: tabatkins

css-values-4/Overview.bs

@@ -2465,6 +2465,247 @@ Comparison Functions: ''min()'', ''max()'', and ''clamp()''</h3>
 	</div>
 
 
+<h3 id=trig-funcs>
+Trigonometric Functions: ''sin()'', ''cos()'', ''tan()'', ''asin()'', ''acos()'', ''atan()'', and ''atan2()''</h3>
+
+	The trigonometric functions--
+	''sin()'', ''cos()'', ''tan()'', ''asin()'', ''acos()'', ''atan()'', and ''atan2()''--
+	compute the various basic trigonometric relationships.
+
+	The <dfn lt="sin()">sin(A)</dfn>, <dfn lt="cos(A)">cos()</dfn>, and <dfn lt="tan()">tan(A)</dfn> functions
+	all contain a single [=calculation=]
+	which must resolve to either a <<number>>
+	or an <<angle>>,
+	and compute their corresponding function
+	by interpreting the result of their argument as radians.
+	(That is, ''sin(45deg)'', ''sin(.125)'', and ''sin(3.14159 / 4 * 1rad)''
+	all represent the same value,
+	approximately ''.707''.)
+	They all represent a <<number>>;
+	''sin()'' and ''cos()'' will always return a number between 0 and 1,
+	while ''tan()'' can return any number between +∞ and −∞.
+	(See [[#calc-type-checking]] for details on how [=math functions=] handle ∞.)
+
+	The <dfn lt="asin()">asin(A)</dfn>, <dfn lt="acos()">acos(A)</dfn>, and <dfn lt="atan()">atan(A)</dfn> functions
+	are the "arc" or "inverse" trigonometric functions,
+	representing the inverse function to their corresponding "normal" trig functions.
+	All of them contain a single [=calculation=]
+	which must resolve to a <<number>>,
+	and compute their corresponding function,
+	interpreting their result as a number of radians,
+	representing an <<angle>>.
+	The angle returned by ''asin()'' must be normalized to the range [''-90deg'', ''90deg''];
+	the angle returned by ''acos()'' to the range [''0deg'', ''180deg''];
+	and the angle returned by ''atan()'' to the range [''-90deg'', ''90deg''].
+
+	The <dfn lt="atan2()">atan2(A, B)</dfn> function
+	contains two comma-separated [=calculations=] A and B
+	that must resolve to <<number>>s,
+	and returns the <<angle>>
+	between the positive X-axis and the point (B,A).
+	The returned angle must be normalized to the interval (''-180deg'', ''180deg'']
+	(that is, greater than ''-180deg'', and less than or equal to ''180deg'').
+
+	Note: ''atan2(Y, X)'' is <em>generally</em> equivalent to ''atan(Y / X)'',
+	but it gives a better answer when the point in question is in the second (NW) or third (SW) quadrants of the plane.
+	''atan2(1, -1)'', corresponding to the point (-1, 1) in the NW of the plane,
+	returns ''135deg'',
+	distinct from ''atan2(-1, 1)'', corresponding to the point (1, -1) in the SE of the plane,
+	which returns ''-45deg''.
+	However, as ''1 / -1'' and ''-1 / 1'' both resolve to ''-1'',
+	''atan()'' returns the same ''-45deg'' for both points.
+
+
+<h4 id="trig-infinities">
+Argument Ranges</h4>
+
+	In ''sin(A)'', ''cos(A)'', or ''tan(A)'',
+	if A is infinite,
+	the result is NaN.
+	(See [[#calc-type-checking]] for details on how [=math functions=] handle NaN.)
+
+	In ''asin(A)'' or ''acos(A)'',
+	if A is less than -1 or greater than 1,
+	the result is NaN.
+
+	In ''atan(A)'',
+	if A is +∞,
+	the result is ''90deg'';
+	if A is -∞,
+	the result is ''-90deg''.
+
+	In ''atan2(A, B)'',
+	if A and B are both zero,
+	the result is ''0deg''.
+	If either or both [=calculations=] are infinite,
+	the function must return an angle
+	as if the infinite value was replaced by ''1'' (for +∞) or ''-1'' (for -∞)
+	and the finite value was replaced by ''0'':
+	''atan2(finite, ∞)'' must return ''0deg'', as if it were ''atan2(0, 1)'';
+	''atan2(∞, ∞)'' must return ''45deg'', as if it were ''atan2(1, 1)'';
+	and so on around the circle.
+
+	Note: All of these behaviors are intended to match the "standard" definitions of these functions
+	as implemented by most programming languages,
+	in particular as implemented in JS.
+
+
+<h3 id=exponent-funcs>
+Exponential  Functions: ''pow()'', ''sqrt()'', ''hypot()''</h3>
+
+	The exponential functions--
+	''pow()'', ''sqrt()'', and ''hypot()''--
+	compute various exponential functions with their arguments.
+
+	The <dfn lt="pow()">pow(A, B)</dfn> function
+	contains two comma-separated [=calculations=] A and B,
+	both of which must resolve to <<number>>s,
+	and returns the result of raising A to the power of B,
+	returning the value as a <<number>>.
+
+	The <dfn lt="sqrt()">sqrt(A)</dfn> function
+	contains a single [=calculation=]
+	which must resolve to a <<number>>,
+	and returns the square root of the value
+	as a <<number>>.
+	(''sqrt(X)'' and ''pow(X, .5)'' are equivalent;
+	''sqrt()'' is a common enough function
+	that it is provided as a convenience.)
+
+	The <dfn lt="hypot()">hypot(A,B)</dfn> function
+	contains two comma-separated [=calculations=] A and B,
+	and returns the length of the hypotenuse of a right-angled triangle
+	with legs equal to A and B.
+	A and B can resolve to any <<number>>, <<dimension>>, or <<percentage>>,
+	but must have the <em>same</em> [=determine the type of a calculation|type=],
+	or else the function is invalid;
+	the result will have the same [=CSSNumericValue/type=] as the arguments.
+
+	<details class=note>
+		<summary>Why does ''hypot()'' allow dimensions (values with units), but ''pow()'' and ''sqrt()'' only work on numbers?</summary>
+
+		You are allowed to write expressions like ''hypot(30px, 40px)'',
+		which resolves to ''50px'',
+		but you aren't allowed to write the expression
+		''sqrt(pow(30px, 2) + pow(40px, 2))'',
+		despite the two being equivalent in most mathematical systems.
+
+		There are two reasons for this:
+		numeric precision in the exponents,
+		and clashing expectations from authors.
+
+		First, numerical precision.
+		For a [=CSSNumericValue/type=] to [=CSSNumericValue/match=] a CSS production like <<length>>,
+		it needs to have a single unit with its exponent set to exactly 1.
+		Theoretically, expressions like ''pow(pow(30px, 3), 1/3)'' should result in exactly that:
+		the inner ''pow(30px, 3)'' would resolve to a value of 27000 with a [=CSSNumericValue/type=] of «[ "length" → 3 ]»
+		(aka <<length>>³),
+		and then the ''pow(X, 1/3)'' would cube-root the value back down to 30 and multiply the exponent by 1/3,
+		giving «[ "length" → 1 ]»,
+		which [=CSSNumericValue/matches=] <<length>>.
+		In the realm of pure mathematics, that's guaranteed to work out;
+		in the real-world of computers using binary floating-point arithmetic,
+		in some cases the powers might not exactly cancel out,
+		leaving you with an invalid [=math function=]
+		for confusing, hard-to-track-down reasons.
+		(For a JS example,
+		evaluate <code>Math.pow(Math.pow(30, 10/3), .1+.1+.1)</code>;
+		the result is not exactly 30,
+		because <code>.1+.1+.1</code> is not exactly 3/10.
+		Instead, <code>(10/3) * (.1 + .1 + .1)</code> is <em>slightly greater</em> than 1.)
+
+		Requiring authors to cast their value down into a number,
+		do all the math on the raw number,
+		then finally send it back to the desired unit,
+		while inconvenient,
+		ensures that numerical precision won't bite anyone:
+		''calc(pow(pow(30px / 1px, 3), 1/3) * 1px)'' is guaranteed to resolve to a <<length>>,
+		with a value that, if not exactly 30, is at least very close to 30,
+		even if numerical precision actually prevents the powers from exactly canceling.
+
+		Second, clashing expectations.
+		It's not uncommon for authors to expect ''pow(30px, 2)''
+		to result in ''900px''
+		(such as in <a href="https://github.com/sass/sass/issues/684">this Sass issue</a>);
+		that is,
+		just squaring the numerical value
+		and leaving the unit alone.
+		This, however, means the result is dependent on what unit you're expressing the argument in;
+		if ''1em'' is ''16px'',
+		then ''pow(1em, 2)'' would give ''1em'',
+		while ''pow(16px, 2)'' would give ''256px'', or ''16em'',
+		which are very different values for what should otherwise be identical input arguments!
+		This sort of input dependency is troublesome for CSS,
+		which generally allows values to be [=canonical unit|canonicalized=] freely;
+		it also makes more complex expressions like ''pow(2em + 10px, 2)'' difficult to interpret.
+
+		Again, requiring authors to cast their value down into a number
+		and then back up again into the desired unit
+		sidesteps these issues;
+		''pow(30, 2)'' is indeed ''900'',
+		and the author can interpret that however they wish.
+
+		<hr>
+
+		On the other hand, ''hypot()'' doesn't suffer from these problems.
+		Numerical precision in units isn't a concern,
+		as the inputs and output all have the same type.
+		The result isn't unit-dependent, either,
+		due to the nature of the operation;
+		''hypot(3em, 4em)'' and ''hypot(48px, 64px)'' give the same result in both cases:
+		''5em'' or ''80px''.
+		Thus it's fine to let author use dimensions directly in ''hypot()''.
+	</details>
+
+<h4 id="exponent-infinities">
+Argument Ranges</h4>
+
+	In ''pow(A, B)'':
+
+	<dl class=switch>
+		: if A is ±∞ and B is 0
+		:: the result is 1
+		: if A is +∞ and B is greater than 0
+		:: the result is +∞
+		: if A is +∞ and B is less than 0
+		:: the result is 0
+		: if A is -∞ and B is greater than 0
+		:: the result is -∞ if B is an odd integer, +∞ otherwise
+		: if A is -∞ and B is less than 0
+		:: the result is 0⁻ if B is an odd integer, 0⁺ otherwise
+
+		: if A is in the (exclusive) range (-1, 1) and B is +∞
+		:: the result is 0⁺
+		: if A is 1 or -1 and B is +∞
+		:: the result is NaN
+		: if A is less than -1 or greater than 1, and B is +∞
+		:: the result is +∞
+
+		: if A is in the (exclusive) range (-1, 1) and B is -∞
+		:: the result is +∞
+		: if A is 1 or -1 and B is -∞
+		:: the result is NaN
+		: if A is less than -1 or greater than 1, and B is -∞
+		:: the result is 0⁺
+	</dl>
+
+	In ''sqrt(A)'',
+	if A is +∞,
+	the result is +∞.
+	If A is less than 0,
+	the result is NaN.
+
+	In ''hypot(A, B)'',
+	if either or both values are infinite,
+	the result is +∞.
+
+	(See [[#calc-type-checking]] for details on how [=math functions=] handle NaN and infinities.)
+
+	Note: All of these behaviors are intended to match the "standard" definitions of these functions
+	as implemented by most programming languages,
+	in particular as implemented in JS.
+
+
 <h3 id='calc-syntax'>
 Syntax</h3>