Skip to content

Commit f99cf1d

Browse files
committed
[css-values-5] Clarify that stepped values are uniformly random.
1 parent 8c708ac commit f99cf1d

File tree

1 file changed

+16
-2
lines changed

1 file changed

+16
-2
lines changed

css-values-5/Overview.bs

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -575,7 +575,9 @@ Generating a Random Numeric Value: the ''random()'' function</h3>
575575
specifies a step value:
576576
the values the function can resolve to
577577
are further restricted to the form <code>min + (N * step)</code>,
578-
where N is a non-negative integer.
578+
where N is a non-negative integer
579+
chosen uniformly randomly from the possible values
580+
that result in an in-range value.
579581

580582
<div class=example>
581583
For example, ''random(100px, 300px, by 50px)''
@@ -597,7 +599,6 @@ Generating a Random Numeric Value: the ''random()'' function</h3>
597599
To be safe, you can put the maximum value
598600
<em>slightly above</em> where you expect the final step to land,
599601
like ''random(100px, 201px, by 100px / 3)''.
600-
601602
</div>
602603

603604
<div class=example>
@@ -611,6 +612,15 @@ Generating a Random Numeric Value: the ''random()'' function</h3>
611612
is restricted to resolving only to integers;
612613
etc.
613614
</div>
615+
616+
Note: The definition of the step <em>does not</em> allow
617+
for naively generating a random value in the range
618+
and then rounding it to the nearest step value,
619+
as that can result in the values not appearing with the same weights.
620+
For example, ''random(100px, 200px, by 50px)''
621+
has to generate the three possible values each with a 1/3 chance;
622+
a naive rounding-based method will instead incorrectly generate ''150px''
623+
twice as often as the boundary values.
614624
</dl>
615625

616626
All of the [=calculation=] arguments can resolve to any <<number>>, <<dimension>>, or <<percentage>>,
@@ -650,6 +660,10 @@ Argument Ranges</h4>
650660
If C is infinite,
651661
the result is A.
652662

663+
(If C is zero or negative,
664+
the result is A,
665+
but that falls out of the standard definition.)
666+
653667
Note: As usual for [=math functions=],
654668
if any argument calculation is NaN,
655669
the result is NaN.

0 commit comments

Comments
 (0)