diff --git a/accepted/random-with-units.changes.md b/accepted/random-with-units.changes.md new file mode 100644 index 00000000..4b6f3771 --- /dev/null +++ b/accepted/random-with-units.changes.md @@ -0,0 +1,9 @@ +## Draft 1.1 + +* Replace floating-point wording for simply "number". + +* Update integer return value range from `[1, $limit)` to `[1, $limit]`. + +## Draft 1 + +* Initial draft. diff --git a/proposal/random-with-units.md b/accepted/random-with-units.md similarity index 91% rename from proposal/random-with-units.md rename to accepted/random-with-units.md index 47706264..e28c7a86 100644 --- a/proposal/random-with-units.md +++ b/accepted/random-with-units.md @@ -1,6 +1,6 @@ -# Random With Units: Draft 1 +# Random With Units: Draft 1.1 -*([Issue](https://github.com/sass/sass/issues/1890))* +*([Issue](https://github.com/sass/sass/issues/1890), [Changelog](random-with-units.changes.md))* This proposal modifies the behavior of the built-in [`math.random()`][random] function to return a number with matching units to the numeric argument it @@ -72,14 +72,14 @@ unit-based arithmetic. The `math.random()` function can take an optional parameter `$limit` which defaults to `null`. -* If `$limit` is `null` then return a pseudo-random floating-point number in the - range `[0, 1)`. +* If `$limit` is `null` then return a pseudo-random unitless number whose value + is in the range `[0, 1)`. > Example: `math.random() => 0.1337001337` * If `$limit` is an **integer** [number] greater than zero: - * Return a pseudo-random integer in the range `[1, $limit)` with the same + * Return a pseudo-random integer in the range `[1, $limit]` with the same [units] as `$limit`. > Examples: diff --git a/spec/built-in-modules/math.md b/spec/built-in-modules/math.md index 535bf735..48aadfe5 100644 --- a/spec/built-in-modules/math.md +++ b/spec/built-in-modules/math.md @@ -487,3 +487,23 @@ random($limit: null) ``` This function is also available as a global function named `random()`. + +* If `$limit` is `null` then return a pseudo-random unitless number whose value + is in the range `[0, 1)`. + + > Example: `math.random() => 0.1337001337` + +* If `$limit` is an **integer** [number] greater than zero: + + * Return a pseudo-random integer in the range `[1, $limit]` with the same + [units] as `$limit`. + + > Examples: + > - `math.random(123) => 87` + > - `math.random(123px) => 43px` + > - `math.random(500%) => 238%` + +* Otherwise throw an error. + +[number]: https://sass-lang.com/documentation/values/numbers +[units]: https://sass-lang.com/documentation/values/numbers#units