[css-values-4] Add mod() and rem() per CSSWG resolution. Closes w3c#2513.

Author: tabatkins

css-values-4/Overview.bs

@@ -2574,12 +2574,13 @@ Comparison Functions: ''min()'', ''max()'', and ''clamp()''</h3>
 
 
 <h3 id=round-func>
-Rounding Values: ''round()''</h3>
+Stepped Value Functions: ''round()'', ''mod()'', and ''rem()''</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 stepped-value functions,
+	''round()'', ''mod()'', and ''rem()'',
+	all transform a given value
+	according to another "step value",
+	in different ways.
 
 	The <dfn lt="round()">round(<<rounding-strategy>>?, A, B)</dfn> function
 	contains an optional rounding strategy,
@@ -2654,6 +2655,99 @@ Rounding Values: ''round()''</h3>
 	since block sizes are always non-negative,
 	''to-zero'' and ''down'' would be identical.)
 
+	The modulus functions <dfn lt="mod()">mod(A, B)</dfn>
+	and <dfn lt=rem()>rem(A, B)</dfn>
+	similarly contain two [=calculations=] A and B,
+	and return the difference between A
+	and 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.
+
+	The two functions are very similar,
+	and in fact return identical results
+	if both arguments are positive or both are negative:
+	the value of the function is equal to the value of A
+	shifted by the integer multiple of B
+	that brings the value into the range [0, B)
+	(that is, possibly including zero, but excluding B itself).
+
+	<div class=example>
+		For example, ''mod(18px, 5px)'' resolves to the value ''3px'',
+		because subtracting ''5px * 3'' from ''18px'' yields ''3px'',
+		which is the only such value between ''0px'' and ''3px''.
+
+		Similarly, ''mod(-140deg, -90deg)'' resolves to the value ''-50deg'',
+		because adding ''-90deg * 1'' to ''-140deg'' yields ''-50deg'',
+		which is the only such value between ''0deg'' and ''-90deg''.
+
+		Evaluating either of these examples with ''rem()'' yields the exact same results.
+	</div>
+
+	Their behavior diverges if the A value and the B step
+	are on opposite sides of zero:
+	''mod()'' (short for “modulus”)
+	continues to choose the integer multiple of B
+	that puts the value into the [0, B) range
+	(guaranteeing that the result will either be zero
+	or share the sign of B, not A),
+	while ''rem()'' (short for "remainder")
+	chooses the integer multiple of B
+	that brings the value into the range [0, -B),
+	avoiding changing the sign of the value.
+
+	<div class=example>
+		For example, ''mod(-18px, 5px)'' resolves to the value ''2px'':
+		adding ''5px * 4'' to ''-18px'' yields ''2px'',
+		which is between ''0px'' and ''5px''.
+
+		On the other hand, ''rem(-18px, 5px)'' resolves to the value ''-3px'':
+		adding ''5px * 3'' to ''-18px'' yields ''-3px'',
+		which has the same sign as ''-18px''
+		but is between ''0px'' and ''-5px''.
+
+		Similarly, ''mod(140deg, -90deg)'' resolves to the value ''-40deg''
+		(adding ''-90deg * 2'' to ''140deg'',
+		bringing it to between ''0deg'' and ''-90deg''),
+		but ''rem(140deg, -90deg)'' resolves to the value ''50deg''.
+	</div>
+
+	<details>
+		<summary>When should I choose ''mod()'' vs ''rem()''?</summary>
+
+		Typically, users of this operation
+		are in control of the step value (B),
+		and are modifying an unknown value A.
+		As a result, it's <em>usually</em> more expected
+		that the result is between 0 and B,
+		regardless of A's sign,
+		meaning ''mod()'' should be chosen.
+
+		For example,
+		if an author wants to know whether a length
+		is an even or odd number of pixels,
+		''mod(A, 2px)'' will return either ''0px'' or ''1px''
+		(assuming the value is a whole number of pixels to begin with),
+		regardless of the value of a.
+		''rem(A, 2px)'', on the other hand,
+		will return ''0px'' if A is an even number of pixels,
+		but will return <em>either</em> ''1px'' or ''-1px''
+		if it's odd,
+		depending on whether A is positive or negative.
+
+		The opposite situation does sometimes occur,
+		however,
+		and so ''rem()'' is provided to cater to that.
+		As well, ''rem()'' is the behavior of JavaScript's <code highlight=js>%</code> operator,
+		so if an exact match between CSS and JS code is desired,
+		''rem()'' can be useful.
+	</details>
+
+	Note: ''mod()'' and ''rem()''
+	can also be defined directly in terms of other functions:
+	''mod(A, B)'' is equivalent to ''calc(A - round(down, A, B))'',
+	while ''rem(A, B)'' is equivalent to ''calc(A - round(to-zero, A, B))''.
 
 <h4 id=round-infinities>
 Argument Ranges</h4>
@@ -2673,6 +2767,19 @@ Argument Ranges</h4>
 	if A is 0⁺ or positive finite,
 	and 0⁻ if A is 0⁻ or negative finite.
 
+	In ''mod(A, B)'' or ''rem(A, B)'',
+	if B is 0,
+	the result is NaN.
+	If A is infinite,
+	the result is NaN.
+
+	In ''mod(A, B)'' only,
+	if B is infinite
+	and A is non-zero and has opposite sign to B,
+	the result is NaN.
+
+	Note: All other "infinite B" cases are valid,
+	and just return A immediately.
 
 
 <h3 id=trig-funcs>
@@ -3274,6 +3381,8 @@ Syntax</h3>
 	<<max()>>   = max( <<calc-sum>># )
 	<<clamp()>> = clamp( <<calc-sum>>#{3} )
 	<<round()>> = round( <<rounding-strategy>>?, <<calc-sum>>, <<calc-sum>> )
+	<<mod()>>   = mod( <<calc-sum>>, <<calc-sum>> )
+	<<rem()>>   = rem( <<calc-sum>>, <<calc-sum>> )
 	<<sin()>>   = sin( <<calc-sum>> )
 	<<cos()>>   = cos( <<calc-sum>> )
 	<<tan()>>   = tan( <<calc-sum>> )
@@ -3413,7 +3522,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()'' or ''round()'' expression
+	* The [=CSSNumericValue/type=] of a ''hypot()'', ''round()'', ''mod()'', or ''rem()'' expression
 		is the result of [=add two types|adding the types=]
 		of its comma-separated [=calculations=].