[css-values-4] Define 'numeric functions'. #13978

Author: tabatkins

css-values-4/Overview.bs

@@ -3018,7 +3018,63 @@ Functional Notations</h2>
 	Other [=functional notations=] are defined in their own modules;
 	for example the <<color>> functions are defined in [[CSS-COLOR-4]] and [[CSS-COLOR-5]].
 
-<h3 id="fuctional-serialization">
+
+
+<h3 id='functional-numeric'>
+Numeric Functions</h3>
+
+	Any [=functional notation=] that resolves solely to a [=numeric data type=]
+	is a <dfn export>numeric function</dfn>.
+
+	As the value of a [=numeric function=] can't, generally,
+	be known at parse time when range restrictions are enforced,
+	[=numeric functions=] returning out-of-range values
+	never cause a declaration to become invalid.
+	Instead, the value of a [=numeric function=] 
+	is clamped to the range allowed in the context it is used
+	at [=computed value=] time if possible,
+	and at [=used value=] time otherwise.
+
+	Similarly,
+	if a [=numeric function=] returns a non-integer value,
+	but is used in a position that expects an <<integer>>,
+	the [=computed value=] and [=used value=]
+	are [=rounded to the nearest integer=].
+
+	Note: All [=math functions=] are [=numeric functions=],
+	but functions like ''sibling-index()'' are also [=numeric functions=]
+	without being [=math functions=].
+
+	<div class=example>
+		Since widths smaller than 0px are not allowed,
+		these three declarations are equivalent:
+
+		<pre>
+		width: calc(5px - 10px);
+		width: calc(-5px);
+		width: 0px;
+		</pre>
+
+		Note however that ''width: -5px'' is not equivalent to ''width: calc(-5px)''!
+		Out-of-range values specified <em>literally</em> are invalid at parse-time,
+		and cause the entire declaration to be dropped.
+	</div>
+
+	Note: While CSS intentionally leaves numeric precision/range UA-defined,
+	extremely large values (including, notably, ±∞)
+	will clamp to the minimum/maximum value allowed.
+	Even properties that can explicitly represent infinity as a keyword value,
+	such as 'animation-iteration-count',
+	will end up clamping ±∞,
+	as [=math functions=] can't resolve to keyword values;
+	the <em>numeric</em> part of the property's syntax still has an implicit minimum/maximum value.
+
+	<wpt>
+	css/css-values/calc-integer.html
+	css/css-values/calc-z-index-fractions-001.html
+	</wpt>
+
+<h3 id="functional-serialization">
 Serialization of Functional Notations</h3>
 
 	<div algorithm="serialize a functional notation">
@@ -3106,6 +3162,11 @@ Mathematical Expressions</h2>
 	...or the <<length-percentage>>/etc mixed types,
 	and can be used wherever such a value would be valid.
 
+	Note: [=Math functions=] differ from the more general [=numeric functions=]
+	because they automatically inherit the [=calculation context=] where they're used,
+	letting you use all the values you could use "normally" in that position,
+	with the same meaning they'd normally have.
+
 <!-- Big Text: calc()
 
  ███▌   ███▌  █▌     ███▌    ██ ██
@@ -5154,53 +5215,11 @@ Computed Value</h3>
 <h3 id='calc-range'>
 Range Checking</h3>
 
-	Parse-time range-checking of values is not performed within [=math functions=],
-	and therefore out-of-range values do not cause the declaration to become invalid.
-	However, the value resulting from a [=top-level calculation=]
-	must be clamped to the range allowed in the target context.
-	Clamping is performed on <a>computed values</a> to the extent possible,
-	and also on <a>used values</a>
-	if computation was unable to sufficiently simplify the expression
-	to allow range-checking.
-	(Clamping is not performed on <a>specified values</a>.)
-
-	Note: This requires all contexts accepting ''calc()''
-	to define any range restrictions as closed (not open) interval endpoints:
-	"greater than or equal to 0px", not "greater than 0px" or "positive lengths".
-
-	Note: While CSS intentionally leaves numeric precision/range UA-defined,
-	extremely large values (including, notably, ±∞)
-	will clamp to the minimum/maximum value allowed.
-	Even properties that can explicitly represent infinity as a keyword value,
-	such as 'animation-iteration-count',
-	will end up clamping ±∞,
-	as [=math functions=] can't resolve to keyword values;
-	the <em>numeric</em> part of the property's syntax still has an implicit minimum/maximum value.
-
-	Additionally, if a [=math function=] that resolves to <<number>>
-	is used somewhere that only accepts <<integer>>,
-	the [=computed value=] and [=used value=] are [=rounded to the nearest integer=],
-	in the same manner as clamping, above.
-
-	<div class=example>
-		Since widths smaller than 0px are not allowed,
-		these three declarations are equivalent:
-
-		<pre>
-		width: calc(5px - 10px);
-		width: calc(-5px);
-		width: 0px;
-		</pre>
-
-		Note however that ''width: -5px'' is not equivalent to ''width: calc(-5px)''!
-		Out-of-range values <em>outside</em> ''calc()'' are syntactically invalid,
-		and cause the entire declaration to be dropped.
-	</div>
-
-	<wpt>
-	css/css-values/calc-integer.html
-	css/css-values/calc-z-index-fractions-001.html
-	</wpt>
+	The clamping/rounding behavior of [=numeric functions=]
+	is, for [=math functions=],
+	only performed on the results of a [=top-level calculation=].
+	Nested [=math functions=] forming a [=calculation tree=]
+	neither clamp nor round.
 
 
 <!-- Big Text: serial
@@ -5221,6 +5240,12 @@ Serialization</h3>
 		To <dfn export>serialize a math function</dfn> |fn|:
 
 		1. If the root of the [=calculation tree=] |fn| represents
+			is an unresolved [=numeric function=]
+			that is not a [=math function=],
+			serialize that function as normal
+			and return the result.
+
+		2. If the root of the [=calculation tree=] |fn| represents
 			is a numeric value
 			(number, percentage, or dimension),
 			and the serialization being produced is of a [=computed value=] or later,
@@ -5229,7 +5254,7 @@ Serialization</h3>
 			then serialize the value as normal
 			and return the result.
 
-		2. If |fn| represents an infinite or NaN value:
+		3. If |fn| represents an infinite or NaN value:
 			1. Let |s| be the [=string=] "calc(".
 			2. Serialize the keyword ''infinity'', ''-infinity'', or ''NaN'',
 				as appropriate to represent the value,
@@ -5245,7 +5270,7 @@ Serialization</h3>
 				and append it to |s|.
 			4. Append ")" to |s|, then return it.
 
-		3. If the [=calculation tree’s=] root node is a numeric value,
+		4. If the [=calculation tree’s=] root node is a numeric value,
 			or a [=calc-operator node=],
 			let |s| be a string initially containing "calc(".
 
@@ -5255,7 +5280,7 @@ Serialization</h3>
 			(such as "sin" or "max"),
 			followed by a "(" (open parenthesis).
 
-		4. For each child of the root node,
+		5. For each child of the root node,
 			[=serialize the calculation tree=].
 			If a result of this serialization starts with a "(" (open parenthesis)
 			and ends with a ")" (close parenthesis),
@@ -5264,9 +5289,9 @@ Serialization</h3>
 			using ", " (comma followed by space),
 			then append the result to |s|.
 
-		5. Append ")" (close parenthesis) to |s|.
+		6. Append ")" (close parenthesis) to |s|.
 
-		6. Return |s|.
+		7. Return |s|.
 	</div>
 
 	<div algorithm>