[css-values-4] Add the round() function.

css-values-4/Overview.bs

@@ -2573,6 +2573,101 @@ Comparison Functions: ''min()'', ''max()'', and ''clamp()''</h3>
 	</div>
 
 
+<h3 id=round-func>
+Rounding Values: ''round()''</h3>
+
+	The rounding function ''round()''
+	adjusts the value of a [=calculation=]
+	to a nearby multiple of a given precision [=calculation=],
+	giving several options for choosing which nearby multiple to use.
+
+	The <dfn lt="round()">round(<<rounding-strategy>>?, A, B)</dfn> function
+	contains an optional rounding strategy,
+	and two [=calculations=] A and B,
+	and returns the value of A,
+	rounded according to the rounding strategy,
+	to the nearest integer multiple of B either above or below A.
+	The argument [=calculations=] 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.
+
+	If A is exactly equal to an integer multiple of B,
+	''round()'' resolves to A exactly
+	(preserving whether A is 0⁻	or 0⁺, if relevant).
+	Otherwise, there are two integer multiples of B that are potentially "closest" to A,
+	|lower B| which is closer to −∞
+	and |upper B| which is closer to +∞.
+	The following <dfn><<rounding-strategy>></dfn>s dictate how to choose between them:
+
+	<dl dfn-type=value dfn-for="<rounding-strategy>">
+		: <dfn>nearest</dfn>
+		:: Choose whichever of |lower B| and |upper B|
+			that has the smallest absolute difference from A.
+			If both have an equal difference
+			(A is exactly between the two values),
+			choose |upper B|.
+		: <dfn>up</dfn>
+		:: Choose |upper B|.
+		: <dfn>down</dfn>
+		:: Choose |lower B|.
+		: <dfn>to-zero</dfn>
+		:: Choose whichever of |lower B| and |upper B|
+			that has the smallest absolute difference from 0.
+	</dl>
+
+	If |lower B| would be zero,
+	it is specifically equal to 0⁺;
+	if |upper B| would be zero,
+	it is specifically equal to 0⁻.
+
+	If <<rounding-strategy>> is omitted,
+	it defaults to ''nearest''.
+
+	<div class=example>
+		Unlike languages like JavaScript
+		which have a natural "precision" to round to
+		(integers),
+		CSS values have no such precision
+		because values can be written in many different compatible units.
+		As such, the precision has to be given exactly;
+		to round a width to the nearest ''50px'',
+		one can write ''round(var(--width), 50px)''.
+	</div>
+
+	Note: JavaScript and other programming languages
+	sometimes separate out the rounding strategies into separate rounding functions.
+	JS’s <code highlight=JS>Math.floor()</code>
+	is equivalent to CSS's ''round(down, ...)'';
+	JS’s <code highlight=JS>Math.ceil()</code>
+	is equivalent to CSS's ''round(up, ...)'';
+	JS’s <code highlight=JS>Math.trunc()</code>
+	is equivalent to CSS's ''round(to-zero, ...)'';
+	and JS’s <code highlight=JS>Math.round()</code>
+	is equivalent to CSS's ''round(nearest, ...)'',
+	or just ''round(...)''.
+
+
+<h4 id=round-infinities>
+Argument Ranges</h4>
+
+	In ''round(A, B)'',
+	if B is 0,
+	the result is NaN.
+
+	If A is +∞,
+	the result is +∞.
+	If A is −∞,
+	the result is −∞.
+
+	If A is finite
+	and B is infinite,
+	the result is 0⁺
+	if A is 0⁺ or positive finite,
+	and 0⁻ if A is 0⁻ or negative finite.
+
+
+
 <h3 id=trig-funcs>
 Trigonometric Functions: ''sin()'', ''cos()'', ''tan()'', ''asin()'', ''acos()'', ''atan()'', and ''atan2()''</h3>
 
@@ -3171,6 +3266,7 @@ Syntax</h3>
 	<<min()>>   = min( <<calc-sum>># )
 	<<max()>>   = max( <<calc-sum>># )
 	<<clamp()>> = clamp( <<calc-sum>>#{3} )
+	<<round()>> = round( <<rounding-strategy>>?, <<calc-sum>>, <<calc-sum>> )
 	<<sin()>>   = sin( <<calc-sum>> )
 	<<cos()>>   = cos( <<calc-sum>> )
 	<<tan()>>   = tan( <<calc-sum>> )
@@ -3310,7 +3406,7 @@ Type Checking</h3>
 		is «[ "angle" → 1 ]».
 	* The [=CSSNumericValue/type=] of a ''pow()'', ''sqrt()'', ''log()'', or ''exp()'' expression
 		is «[ "number" → 1 ]».
-	* The [=CSSNumericValue/type=] of a ''hypot()'' expression
+	* The [=CSSNumericValue/type=] of a ''hypot()'' or ''round()'' expression
 		is the result of [=add two types|adding the types=]
 		of its comma-separated [=calculations=].