Int, Float, BigInt: use optional args and deprecate xxxWithRadix, xxxWithPrecision etc. (#209)

* Int, Float, BigInt: use optional args and deprecate xxxWithRadix, xxxWithPrecision etc.

* CHANGELOG

Author: cknitt

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Next version
 
 - BREAKING: Use new native `bigint` type. This requires ReScript compiler version "11.1.0-rc.6" or higher. https://github.com/rescript-association/rescript-core/pull/207
+- `Int`, `Float`, `BigInt`: use optional args and deprecate `xxxWithRadix`, `xxxWithPrecision` etc. https://github.com/rescript-association/rescript-core/pull/209
 
 ## 1.2.0
 

scripts/DocTests.mjs

@@ -306,7 +306,7 @@ async function main() {
             var id = example.id.replaceAll(".", "_");
             var codes = getCodeBlocks(example);
             var results = await Promise.all(codes.map(async function (code, $$int) {
-                      var id$1 = id + "_" + $$int.toString();
+                      var id$1 = id + "_" + $$int.toString(undefined);
                       return await testCode(id$1, code);
                     }));
             return [

src/Core__BigInt.res

@@ -50,8 +50,10 @@ See [`toString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Referen
 Js.BigInt.toString(123n)->Js.log
 ```
 */
-external toString: bigint => string = "toString"
-@send external toStringWithRadix: (bigint, ~radix: int) => string = "toString"
+external toString: (bigint, ~radix: int=?) => string = "toString"
+
+@deprecated("Use `toString` with `~radix` instead") @send
+external toStringWithRadix: (bigint, ~radix: int) => string = "toString"
 
 @send
 /**

src/Core__Dict.resi

@@ -228,7 +228,7 @@ let forEachWithKey: (t<'a>, ('a, string) => unit) => unit
 let dict = Dict.fromArray([("key1", 1), ("key2", 2)])
 
 dict->Dict.mapValues(v => v + 10)->Dict.toArray // [("key1", 11), ("key2", 12)]
-dict->Dict.mapValues(Int.toString)->Dict.toArray // [("key1", "1"), ("key2", "2")]
+dict->Dict.mapValues(v => Int.toString(v))->Dict.toArray // [("key1", "1"), ("key2", "2")]
 ```
 */
 let mapValues: (t<'a>, 'a => 'b) => t<'b>

src/Core__Float.res

@@ -16,20 +16,25 @@ let compare = (a: float, b: float) =>
 @val external isFinite: float => bool = "isFinite"
 @val external parseFloat: 'a => float = "parseFloat"
 // parseInt's return type is a float because it can be NaN
-@val external parseInt: 'a => float = "parseInt"
-@val external parseIntWithRadix: ('a, ~radix: int) => float = "parseInt"
+@val external parseInt: ('a, ~radix: int=?) => float = "parseInt"
+@deprecated("Use `parseInt` instead") @val
+external parseIntWithRadix: ('a, ~radix: int) => float = "parseInt"
 
-@send external toExponential: float => string = "toExponential"
-@send external toExponentialWithPrecision: (float, ~digits: int) => string = "toExponential"
+@send external toExponential: (float, ~digits: int=?) => string = "toExponential"
+@deprecated("Use `toExponential` instead") @send
+external toExponentialWithPrecision: (float, ~digits: int) => string = "toExponential"
 
-@send external toFixed: float => string = "toFixed"
-@send external toFixedWithPrecision: (float, ~digits: int) => string = "toFixed"
+@send external toFixed: (float, ~digits: int=?) => string = "toFixed"
+@deprecated("Use `toFixed` instead") @send
+external toFixedWithPrecision: (float, ~digits: int) => string = "toFixed"
 
-@send external toPrecision: float => string = "toPrecision"
-@send external toPrecisionWithPrecision: (float, ~digits: int) => string = "toPrecision"
+@send external toPrecision: (float, ~digits: int=?) => string = "toPrecision"
+@deprecated("Use `toPrecision` instead") @send
+external toPrecisionWithPrecision: (float, ~digits: int) => string = "toPrecision"
 
-@send external toString: float => string = "toString"
-@send external toStringWithRadix: (float, ~radix: int) => string = "toString"
+@send external toString: (float, ~radix: int=?) => string = "toString"
+@deprecated("Use `toString` instead") @send
+external toStringWithRadix: (float, ~radix: int) => string = "toString"
 @send external toLocaleString: float => string = "toLocaleString"
 
 let fromString = i =>

src/Core__Float.resi

@@ -162,8 +162,11 @@ Float.parseFloat("error")->Float.isNaN // true
 external parseFloat: string => float = "parseFloat"
 
 /**
-`parseInt(v)` parse the given `v` and returns a float. Leading whitespace in
-`v` is ignored. Returns `NaN` if `v` can't be parsed.
+`parseInt(v, ~radix=?)` parse the given `v` and returns a float. Leading
+whitespace in this argument `v`is ignored. `radix` specifies the radix base to
+use for the formatted number. The value must be in the range [2, 36] (inclusive).
+Returns `NaN` if `v` can't be parsed and `radix` is smaller than 2 or bigger
+than 36.
 See [`parseInt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/parseInt) on MDN.
 
 ## Examples
@@ -174,10 +177,14 @@ Float.parseInt("  3.14   ") // 3.0
 Float.parseInt(3) // 3.0
 Float.parseInt("3.14some non-digit characters") // 3.0
 Float.parseInt("error")->Float.isNaN // true
+Float.parseInt("10.0", ~radix=2) // 2.0
+Float.parseInt("15 * 3", ~radix=10) // 15.0
+Float.parseInt("12", ~radix=13) // 15.0
+Float.parseInt("17", ~radix=40)->Float.isNaN // true
 ```
 */
 @val
-external parseInt: 'a => float = "parseInt"
+external parseInt: ('a, ~radix: int=?) => float = "parseInt"
 
 /**
 `parseIntWithRadix(v, ~radix)` parse the given `v` and returns a float. Leading
@@ -196,23 +203,32 @@ Float.parseIntWithRadix("12", ~radix=13) // 15.0
 Float.parseIntWithRadix("17", ~radix=40)->Float.isNaN // true
 ```
 */
+@deprecated("Use `parseInt` instead")
 @val
 external parseIntWithRadix: ('a, ~radix: int) => float = "parseInt"
 
 /**
-`toExponential(v)` return a `string` representing the given value in exponential
-notation.
+`toExponential(v, ~digits=?)` return a `string` representing the given value in
+exponential notation. `digits` specifies how many digits should appear after
+the decimal point.
 See [`Number.toExponential`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toExponential) on MDN.
 
 ## Examples
 
 ```rescript
 Float.toExponential(1000.0) // "1e+3"
 Float.toExponential(-1000.0) // "-1e+3"
+Float.toExponential(77.0, ~digits=2) // "7.70e+1"
+Float.toExponential(5678.0, ~digits=2) // "5.68e+3"
+```
+
+## Exceptions
+
+- `RangeError`: If `digits` less than 0 or greater than 10.
 ```
 */
 @send
-external toExponential: float => string = "toExponential"
+external toExponential: (float, ~digits: int=?) => string = "toExponential"
 
 /**
 `toExponential(v, ~digits)` return a `string` representing the given value in
@@ -231,23 +247,31 @@ Float.toExponentialWithPrecision(5678.0, ~digits=2) // "5.68e+3"
 
 - `RangeError`: If `digits` less than 0 or greater than 10.
 */
+@deprecated("Use `toExponential` instead")
 @send
 external toExponentialWithPrecision: (float, ~digits: int) => string = "toExponential"
 
 /**
-`toFixed(v)` return a `string` representing the given value using fixed-point
-notation.
+`toFixed(v, ~digits=?)` return a `string` representing the given
+value using fixed-point notation. `digits` specifies how many digits should
+appear after the decimal point.
 See [`Number.toFixed`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toFixed) on MDN.
 
 ## Examples
 
 ```rescript
 Float.toFixed(123456.0) // "123456.00"
 Float.toFixed(10.0) // "10.00"
+Float.toFixed(300.0, ~digits=4) // "300.0000"
+Float.toFixed(300.0, ~digits=1) // "300.0"
 ```
+
+## Exceptions
+
+- `RangeError`: If `digits` is less than 0 or larger than 100.
 */
 @send
-external toFixed: float => string = "toFixed"
+external toFixed: (float, ~digits: int=?) => string = "toFixed"
 
 /**
 `toFixedWithPrecision(v, ~digits)` return a `string` representing the given
@@ -266,24 +290,32 @@ Float.toFixedWithPrecision(300.0, ~digits=1) // "300.0"
 
 - `RangeError`: If `digits` is less than 0 or larger than 100.
 */
+@deprecated("Use `toFixed` instead")
 @send
 external toFixedWithPrecision: (float, ~digits: int) => string = "toFixed"
 
 /**
-`toPrecision(v)` return a `string` representing the giver value with precision.
-This function omits the argument that controls precision, so it behaves like
-`toString`. See `toPrecisionWithPrecision` to control precision.
+`toPrecision(v, ~digits=?)` return a `string` representing the giver value with
+precision. `digits` specifies the number of significant digits.
 See [`Number.toPrecision`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toPrecision) on MDN.
 
 ## Examples
 
 ```rescript
 Float.toPrecision(100.0) // "100"
 Float.toPrecision(1.0) // "1"
+Float.toPrecision(100.0, ~digits=2) // "1.0e+2"
+Float.toPrecision(1.0, ~digits=1) // "1"
 ```
+
+## Exceptions
+
+- `RangeError`: If `digits` is not between 1 and 100 (inclusive).
+Implementations are allowed to support larger and smaller values as well.
+ECMA-262 only requires a precision of up to 21 significant digits.
 */
 @send
-external toPrecision: float => string = "toPrecision"
+external toPrecision: (float, ~digits: int=?) => string = "toPrecision"
 
 /**
 `toPrecisionWithPrecision(v, ~digits)` return a `string` representing the giver value with
@@ -304,6 +336,7 @@ Implementations are allowed to support larger and smaller values as well.
 ECMA-262 only requires a precision of up to 21 significant digits.
 
 */
+@deprecated("Use `toPrecision` instead")
 @send
 external toPrecisionWithPrecision: (float, ~digits: int) => string = "toPrecision"
 
@@ -319,7 +352,7 @@ Float.toString(-1000.0) // "-1000"
 ```
 */
 @send
-external toString: float => string = "toString"
+external toString: (float, ~radix: int=?) => string = "toString"
 
 /**
 `toStringWithRadix(v, ~radix)` return a `string` representing the given value.
@@ -338,6 +371,7 @@ Float.toStringWithRadix(123456.0, ~radix=36) // "2n9c"
 
 `RangeError`: if `radix` is less than 2 or greater than 36.
 */
+@deprecated("Use `toString` with `~radix` instead")
 @send
 external toStringWithRadix: (float, ~radix: int) => string = "toString"
 

src/Core__Int.mjs

@@ -17,7 +17,7 @@ function compare(a, b) {
   }
 }
 
-function fromString(radix, x) {
+function fromString(x, radix) {
   var maybeInt = radix !== undefined ? parseInt(x, radix) : parseInt(x);
   if (isNaN(maybeInt) || maybeInt > 2147483647 || maybeInt < -2147483648) {
     return ;
@@ -26,7 +26,8 @@ function fromString(radix, x) {
   }
 }
 
-function rangeWithOptions(start, end, options) {
+function range(start, end, optionsOpt) {
+  var options = optionsOpt !== undefined ? optionsOpt : ({});
   var isInverted = start > end;
   var n = options.step;
   var step;
@@ -48,17 +49,17 @@ function rangeWithOptions(start, end, options) {
   } else if (step === 0) {
     length = options.inclusive === true ? 1 : 0;
   } else {
-    var range = isInverted ? start - end | 0 : end - start | 0;
-    var range$1 = options.inclusive === true ? range + 1 | 0 : range;
-    length = Math.ceil(range$1 / PervasivesU.abs(step)) | 0;
+    var range$1 = isInverted ? start - end | 0 : end - start | 0;
+    var range$2 = options.inclusive === true ? range$1 + 1 | 0 : range$1;
+    length = Math.ceil(range$2 / PervasivesU.abs(step)) | 0;
   }
   return Core__Array.fromInitializer(length, (function (i) {
                 return start + Math.imul(i, step) | 0;
               }));
 }
 
-function range(start, end) {
-  return rangeWithOptions(start, end, {});
+function rangeWithOptions(start, end, options) {
+  return range(start, end, options);
 }
 
 function clamp(min, max, value) {

src/Core__Int.res

@@ -8,27 +8,32 @@ let equal = (a: int, b: int) => a === b
 let compare = (a: int, b: int) =>
   a < b ? Core__Ordering.less : a > b ? Core__Ordering.greater : Core__Ordering.equal
 
-@send external toExponential: int => string = "toExponential"
-@send external toExponentialWithPrecision: (int, ~digits: int) => string = "toExponential"
+@send external toExponential: (int, ~digits: int=?) => string = "toExponential"
+@deprecated("Use `toExponential` instead") @send
+external toExponentialWithPrecision: (int, ~digits: int) => string = "toExponential"
 
-@send external toFixed: int => string = "toFixed"
-@send external toFixedWithPrecision: (int, ~digits: int) => string = "toFixed"
+@send external toFixed: (int, ~digits: int=?) => string = "toFixed"
+@deprecated("Use `toFixed` instead") @send
+external toFixedWithPrecision: (int, ~digits: int) => string = "toFixed"
 
-@send external toPrecision: int => string = "toPrecision"
-@send external toPrecisionWithPrecision: (int, ~digits: int) => string = "toPrecision"
+@send external toPrecision: (int, ~digits: int=?) => string = "toPrecision"
+@deprecated("Use `toPrecision` instead") @send
+external toPrecisionWithPrecision: (int, ~digits: int) => string = "toPrecision"
 
-@send external toString: int => string = "toString"
-@send external toStringWithRadix: (int, ~radix: int) => string = "toString"
+@send external toString: (int, ~radix: int=?) => string = "toString"
+@deprecated("Use `toString` instead") @send
+external toStringWithRadix: (int, ~radix: int) => string = "toString"
 @send external toLocaleString: int => string = "toLocaleString"
 
 external toFloat: int => float = "%identity"
 external fromFloat: float => int = "%intoffloat"
 
-let fromString = (~radix=?, x) => {
+let fromString = (x, ~radix=?) => {
   let maybeInt = switch radix {
-  | Some(radix) => Core__Float.parseIntWithRadix(x, ~radix)
+  | Some(radix) => Core__Float.parseInt(x, ~radix)
   | None => Core__Float.parseInt(x)
   }
+
   if Core__Float.isNaN(maybeInt) {
     None
   } else if maybeInt > Constants.maxValue->toFloat || maybeInt < Constants.minValue->toFloat {
@@ -42,7 +47,8 @@ let fromString = (~radix=?, x) => {
 external mod: (int, int) => int = "%modint"
 
 type rangeOptions = {step?: int, inclusive?: bool}
-let rangeWithOptions = (start, end, options) => {
+
+let range = (start, end, ~options: rangeOptions={}) => {
   let isInverted = start > end
 
   let step = switch options.step {
@@ -65,7 +71,8 @@ let rangeWithOptions = (start, end, options) => {
   Core__Array.fromInitializer(~length, i => start + i * step)
 }
 
-let range = (start, end) => rangeWithOptions(start, end, {})
+@deprecated("Use `range` instead") @send
+let rangeWithOptions = (start, end, options) => range(start, end, ~options)
 
 let clamp = (~min=?, ~max=?, value): int => {
   let value = switch max {