diff --git a/css-values-4/Overview.bs b/css-values-4/Overview.bs index 636205943e60..2bf75e78fb94 100644 --- a/css-values-4/Overview.bs +++ b/css-values-4/Overview.bs @@ -2573,6 +2573,101 @@ Comparison Functions: ''min()'', ''max()'', and ''clamp()'' +

+Rounding Values: ''round()''

+ + 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 round(<>?, A, B) 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 <>, <>, or <>, + but must have the same [=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 <>s dictate how to choose between them: + +
+ : nearest + :: 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|. + : up + :: Choose |upper B|. + : down + :: Choose |lower B|. + : to-zero + :: Choose whichever of |lower B| and |upper B| + that has the smallest absolute difference from 0. +
+ + 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 <> is omitted, + it defaults to ''nearest''. + +
+ 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)''. +
+ + Note: JavaScript and other programming languages + sometimes separate out the rounding strategies into separate rounding functions. + JS’s Math.floor() + is equivalent to CSS's ''round(down, ...)''; + JS’s Math.ceil() + is equivalent to CSS's ''round(up, ...)''; + JS’s Math.trunc() + is equivalent to CSS's ''round(to-zero, ...)''; + and JS’s Math.round() + is equivalent to CSS's ''round(nearest, ...)'', + or just ''round(...)''. + + +

+Argument Ranges

+ + 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. + + +

Trigonometric Functions: ''sin()'', ''cos()'', ''tan()'', ''asin()'', ''acos()'', ''atan()'', and ''atan2()''

@@ -3171,6 +3266,7 @@ Syntax <> = min( <># ) <> = max( <># ) <> = clamp( <>#{3} ) + <> = round( <>?, <>, <> ) <> = sin( <> ) <> = cos( <> ) <> = tan( <> ) @@ -3310,7 +3406,7 @@ Type Checking 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=].