From 3e06a10d4583cf0550d958d682c12e1a64172be5 Mon Sep 17 00:00:00 2001 From: Josh Vlk Date: Thu, 13 Mar 2025 08:33:29 -0400 Subject: [PATCH 1/2] Add BigInt docs --- runtime/Stdlib_BigInt.res | 60 ++----------------- runtime/Stdlib_BigInt.resi | 119 +++++++++++++++++++++++++++++++++++++ 2 files changed, 123 insertions(+), 56 deletions(-) create mode 100644 runtime/Stdlib_BigInt.resi diff --git a/runtime/Stdlib_BigInt.res b/runtime/Stdlib_BigInt.res index ddceef99b3..4ac0b02614 100644 --- a/runtime/Stdlib_BigInt.res +++ b/runtime/Stdlib_BigInt.res @@ -1,76 +1,24 @@ -/** -Type representing a bigint. -*/ type t = bigint -@val external asIntN: (~width: int, bigint) => bigint = "BigInt.asIntN" +@val +external asIntN: (~width: int, bigint) => bigint = "BigInt.asIntN" @val external asUintN: (~width: int, bigint) => bigint = "BigInt.asUintN" -@val external fromString: string => bigint = "BigInt" - @val -/** -Parses the given `string` into a `bigint` using JavaScript semantics. Return the -number as a `bigint` if successfully parsed. Uncaught syntax exception otherwise. - -## Examples - -```rescript -/* returns 123n */ -BigInt.fromStringExn("123") - -/* returns 0n */ -BigInt.fromStringExn("") - -/* returns 17n */ -BigInt.fromStringExn("0x11") +external fromString: string => bigint = "BigInt" -/* returns 3n */ -BigInt.fromStringExn("0b11") - -/* returns 9n */ -BigInt.fromStringExn("0o11") - -/* catch exception */ -try { - BigInt.fromStringExn("a") -} catch { -| Exn.Error(_error) => 0n -} -``` -*/ +@val @raises(Exn.Error) external fromStringExn: string => bigint = "BigInt" @val external fromInt: int => bigint = "BigInt" @val external fromFloat: float => bigint = "BigInt" @send -/** -Formats a `bigint` as a string. Return a `string` representing the given value. -See [`toString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toString) on MDN. - -## Examples - -```rescript -/* prints "123" */ -BigInt.toString(123n)->Console.log -``` -*/ external toString: (bigint, ~radix: int=?) => string = "toString" @deprecated("Use `toString` with `~radix` instead") @send external toStringWithRadix: (bigint, ~radix: int) => string = "toString" @send -/** -Returns a string with a language-sensitive representation of this BigInt value. - -## Examples - -```rescript -/* prints "123" */ -BigInt.toString(123n)->Console.log -``` -*/ external toLocaleString: bigint => string = "toLocaleString" @val external toFloat: bigint => float = "Number" diff --git a/runtime/Stdlib_BigInt.resi b/runtime/Stdlib_BigInt.resi new file mode 100644 index 0000000000..b9ff685d24 --- /dev/null +++ b/runtime/Stdlib_BigInt.resi @@ -0,0 +1,119 @@ +/** +Type representing a BigInt. +*/ +type t = bigint + +/** +Interprets the low bits (set by `~width`) of a BigInt as a 2's-complement signed integer. All higher bits are discarded. + + + */ +@val +external asIntN: (~width: int, bigint) => bigint = "BigInt.asIntN" + +@val external asUintN: (~width: int, bigint) => bigint = "BigInt.asUintN" + +/** + Creates a BigInt from a string. + + ## Examples + + ```rescript + /* returns 123n */ + BigInt.fromString("123") + */ +@val +external fromString: string => bigint = "BigInt" + +/** +Parses the given `string` into a `bigint` using JavaScript semantics. Return the +number as a `bigint` if successfully parsed. Uncaught syntax exception otherwise. + +## Examples + +```rescript +/* returns 123n */ +BigInt.fromStringExn("123") + +/* returns 0n */ +BigInt.fromStringExn("") + +/* returns 17n */ +BigInt.fromStringExn("0x11") + +/* returns 3n */ +BigInt.fromStringExn("0b11") + +/* returns 9n */ +BigInt.fromStringExn("0o11") + +/* catch exception */ +try { + BigInt.fromStringExn("a") +} catch { +| Exn.Error(_error) => 0n +} +``` +*/ +@val +@raises(Exn.Error) +external fromStringExn: string => bigint = "BigInt" +@val external fromInt: int => bigint = "BigInt" +@val external fromFloat: float => bigint = "BigInt" + +/** +Formats a `bigint` as a string. Return a `string` representing the given value. +See [`toString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toString) on MDN. + +## Examples + +```rescript +/* prints "123" */ +BigInt.toString(123n)->Console.log +``` +*/ +@send +external toString: (bigint, ~radix: int=?) => string = "toString" +@deprecated("Use `toString` with `~radix` instead") @send +external toStringWithRadix: (bigint, ~radix: int) => string = "toString" + +/** +Returns a string with a language-sensitive representation of this BigInt value. + +## Examples + +```rescript +/* prints "123" */ +BigInt.toString(123n)->Console.log +``` +*/ +@send +external toLocaleString: bigint => string = "toLocaleString" + +@val external toFloat: bigint => float = "Number" + +let toInt: bigint => int + +external \"+": (bigint, bigint) => bigint = "%addbigint" +external \"-": (bigint, bigint) => bigint = "%subbigint" +external \"*": (bigint, bigint) => bigint = "%mulbigint" +external \"/": (bigint, bigint) => bigint = "%divbigint" +external \"~-": bigint => bigint = "%negbigint" +external \"~+": bigint => bigint = "%identity" +external \"**": (bigint, bigint) => bigint = "%powbigint" + +external add: (bigint, bigint) => bigint = "%addfloat" +external sub: (bigint, bigint) => bigint = "%subfloat" +external mul: (bigint, bigint) => bigint = "%mulfloat" +external div: (bigint, bigint) => bigint = "%divfloat" + +external mod: (bigint, bigint) => bigint = "%modbigint" + +external land: (bigint, bigint) => bigint = "%andbigint" +external lor: (bigint, bigint) => bigint = "%orbigint" +external lxor: (bigint, bigint) => bigint = "%xorbigint" + +external lsl: (bigint, bigint) => bigint = "%lslbigint" +external asr: (bigint, bigint) => bigint = "%asrbigint" + +let lnot: bigint => bigint From e8f21d290e844e074d0c52c939c3c7fccf303c01 Mon Sep 17 00:00:00 2001 From: Josh Vlk Date: Thu, 13 Mar 2025 10:12:10 -0400 Subject: [PATCH 2/2] more docs --- runtime/Stdlib_BigInt.resi | 95 +++++++++++++++++++++++++++++++++----- 1 file changed, 84 insertions(+), 11 deletions(-) diff --git a/runtime/Stdlib_BigInt.resi b/runtime/Stdlib_BigInt.resi index b9ff685d24..5d9893d8d8 100644 --- a/runtime/Stdlib_BigInt.resi +++ b/runtime/Stdlib_BigInt.resi @@ -6,29 +6,52 @@ type t = bigint /** Interprets the low bits (set by `~width`) of a BigInt as a 2's-complement signed integer. All higher bits are discarded. +--- +## Examples +```rescript +let i64_CEIL = BigInt.\"**"(2n, 63n) +Console.log(i64_CEIL->BigInt.asIntN(~width=64)) +``` */ @val external asIntN: (~width: int, bigint) => bigint = "BigInt.asIntN" -@val external asUintN: (~width: int, bigint) => bigint = "BigInt.asUintN" - /** - Creates a BigInt from a string. +Interprets the low bits (setBy `~width`) of a BigInt as an unsigned integer. All higher bits are discarded. - ## Examples +--- - ```rescript - /* returns 123n */ - BigInt.fromString("123") +## Examples +```rescript +let u64_CEIL = BigInt.\"**"(2n, 63n) +Console.log(u64_CEIL->BigInt.asUintN(~width=64)) +/* returns 9223372036854775808n */ +``` */ @val +external asUintN: (~width: int, bigint) => bigint = "BigInt.asUintN" + +/** +Creates a BigInt from a string. + +--- + +## Examples + +```rescript +/* returns 123n */ +BigInt.fromString("123") +*/ +@val external fromString: string => bigint = "BigInt" /** Parses the given `string` into a `bigint` using JavaScript semantics. Return the number as a `bigint` if successfully parsed. Uncaught syntax exception otherwise. +--- + ## Examples ```rescript @@ -58,8 +81,30 @@ try { @val @raises(Exn.Error) external fromStringExn: string => bigint = "BigInt" -@val external fromInt: int => bigint = "BigInt" -@val external fromFloat: float => bigint = "BigInt" + +/** +Creates a BigInt from an int. + +--- + +## Examples +BigInt.fromInt(1000 * 1000) +/* returns 1000000n */ + */ +@val +external fromInt: int => bigint = "BigInt" + +/** +Creates a BigInt from a float. + +--- + +## Examples +BigInt.fromFloat(1000.00 *. 1000.00) +/* returns 1000000n */ + */ +@val +external fromFloat: float => bigint = "BigInt" /** Formats a `bigint` as a string. Return a `string` representing the given value. @@ -74,7 +119,12 @@ BigInt.toString(123n)->Console.log */ @send external toString: (bigint, ~radix: int=?) => string = "toString" -@deprecated("Use `toString` with `~radix` instead") @send + +/** +Deprecated: Use `toString` with `~radix` instead. +*/ +@deprecated("Use `toString` with `~radix` instead") +@send external toStringWithRadix: (bigint, ~radix: int) => string = "toString" /** @@ -90,8 +140,31 @@ BigInt.toString(123n)->Console.log @send external toLocaleString: bigint => string = "toLocaleString" -@val external toFloat: bigint => float = "Number" +/** +Converts a BigInt to a float. + +--- +## Examples +```rescript +/* prints 10000 */ +10000n->BigInt.toFloat->Console.log +``` +*/ +@val +external toFloat: bigint => float = "Number" + +/** +Converts a BigInt to an int. + +--- + +## Examples +```rescript +/* prints 10000 */ +10000n->BigInt.toInt->Console.log +``` +*/ let toInt: bigint => int external \"+": (bigint, bigint) => bigint = "%addbigint"