Add BigInt docs

runtime/Stdlib_BigInt.res

@@ -1,68 +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
-BigInt.fromStringExn("123")->assertEqual(123n)
-
-BigInt.fromStringExn("")->assertEqual(0n)
-
-BigInt.fromStringExn("0x11")->assertEqual(17n)
+external fromString: string => bigint = "BigInt"
 
-BigInt.fromStringExn("0b11")->assertEqual(3n)
-
-BigInt.fromStringExn("0o11")->assertEqual(9n)
-
-/* catch exception */
-switch BigInt.fromStringExn("a") {
-| exception Exn.Error(_error) => assert(true)
-| _bigInt => assert(false)
-}
-```
-*/
+@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
-BigInt.toString(123n)->assertEqual("123")
-```
-*/
 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
-BigInt.toString(123n)->assertEqual("123")
-```
-*/
 external toLocaleString: bigint => string = "toLocaleString"
 
 @val external toFloat: bigint => float = "Number"

runtime/Stdlib_BigInt.resi

@@ -0,0 +1,192 @@
+/**
+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.
+
+---
+
+## 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"
+
+/**
+Interprets the low bits (setBy `~width`) of a BigInt as an unsigned integer. All higher bits are discarded.
+
+---
+
+## 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
+/* 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"
+
+/**
+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.
+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.
+*/
+@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"
+
+/**
+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"
+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