@grain/stdlib 0.6.4 → 0.6.6

package/int32.md

@@ -13,6 +13,14 @@ No other changes yet.
 from "int32" include Int32
 ```
 
+```grain
+1l
+```
+
+```grain
+-1l
+```
+
 ## Values
 
 Functions and constants included in the Int32 module.
@@ -92,6 +100,12 @@ Returns:
 |----|-----------|
 |`Int32`|The Uint32 represented as an Int32|
 
+Examples:
+
+```grain
+Int32.fromUint32(1ul) == 1l
+```
+
 ### Int32.**incr**
 
 <details disabled>
@@ -117,6 +131,16 @@ Returns:
 |----|-----------|
 |`Int32`|The incremented value|
 
+Examples:
+
+```grain
+Int32.incr(1l) == 2l
+```
+
+```grain
+Int32.incr(-2l) == -1l
+```
+
 ### Int32.**decr**
 
 <details disabled>
@@ -142,6 +166,16 @@ Returns:
 |----|-----------|
 |`Int32`|The decremented value|
 
+Examples:
+
+```grain
+Int32.decr(2l) == 1l
+```
+
+```grain
+Int32.decr(0l) == -1l
+```
+
 ### Int32.**(+)**
 
 <details>
@@ -175,6 +209,13 @@ Returns:
 |----|-----------|
 |`Int32`|The sum of the two operands|
 
+Examples:
+
+```grain
+use Int32.{ (+) }
+assert 1l + 1l == 2l
+```
+
 ### Int32.**(-)**
 
 <details>
@@ -208,6 +249,13 @@ Returns:
 |----|-----------|
 |`Int32`|The difference of the two operands|
 
+Examples:
+
+```grain
+use Int32.{ (-) }
+assert 2l - 1l == 1l
+```
+
 ### Int32.**(*)**
 
 <details>
@@ -241,6 +289,13 @@ Returns:
 |----|-----------|
 |`Int32`|The product of the two operands|
 
+Examples:
+
+```grain
+use Int32.{ (*) }
+assert 2l * 2l == 4l
+```
+
 ### Int32.**(/)**
 
 <details>
@@ -274,6 +329,13 @@ Returns:
 |----|-----------|
 |`Int32`|The quotient of its operands|
 
+Examples:
+
+```grain
+use Int32.{ (/) }
+assert 8l / 2l == 4l
+```
+
 ### Int32.**rem**
 
 <details disabled>
@@ -300,6 +362,12 @@ Returns:
 |----|-----------|
 |`Int32`|The remainder of its operands|
 
+Examples:
+
+```grain
+Int32.rem(8l, 3l) == 2l
+```
+
 ### Int32.**(%)**
 
 <details>
@@ -340,6 +408,13 @@ Throws:
 
 * When `y` is zero
 
+Examples:
+
+```grain
+use Int32.{ (%) }
+assert -5l % 3l == 1l
+```
+
 ### Int32.**rotl**
 
 <details disabled>
@@ -366,6 +441,16 @@ Returns:
 |----|-----------|
 |`Int32`|The rotated value|
 
+Examples:
+
+```grain
+Int32.rotl(1l, 1l) == 2l
+```
+
+```grain
+Int32.rotl(1l, 2l) == 4l
+```
+
 ### Int32.**rotr**
 
 <details disabled>
@@ -392,6 +477,16 @@ Returns:
 |----|-----------|
 |`Int32`|The rotated value|
 
+Examples:
+
+```grain
+Int32.rotr(2l, 1l) == 1l
+```
+
+```grain
+Int32.rotr(4l, 2l) == 1l
+```
+
 ### Int32.**(<<)**
 
 <details>
@@ -425,6 +520,13 @@ Returns:
 |----|-----------|
 |`Int32`|The shifted value|
 
+Examples:
+
+```grain
+use Int32.{ (<<) }
+assert (5l << 1l) == 10l
+```
+
 ### Int32.**(>>)**
 
 <details>
@@ -458,6 +560,13 @@ Returns:
 |----|-----------|
 |`Int32`|The shifted value|
 
+Examples:
+
+```grain
+use Int32.{ (>>) }
+assert (5l >> 1l) == 2l
+```
+
 ### Int32.**(==)**
 
 <details>
@@ -491,6 +600,13 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is equal to the second value or `false` otherwise|
 
+Examples:
+
+```grain
+use Int32.{ (==) }
+assert 1l == 1l
+```
+
 ### Int32.**(!=)**
 
 <details>
@@ -524,6 +640,13 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is not equal to the second value or `false` otherwise|
 
+Examples:
+
+```grain
+use Int32.{ (!=) }
+assert 1l != 2l
+```
+
 ### Int32.**eqz**
 
 <details disabled>
@@ -549,6 +672,16 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is equal to zero or `false` otherwise|
 
+Examples:
+
+```grain
+Int32.eqz(0l) == true
+```
+
+```grain
+Int32.eqz(1l) == false
+```
+
 ### Int32.**(<)**
 
 <details>
@@ -582,6 +715,13 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is less than the second value or `false` otherwise|
 
+Examples:
+
+```grain
+use Int32.{ (<) }
+assert 1l < 2l
+```
+
 ### Int32.**(>)**
 
 <details>
@@ -615,6 +755,13 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is greater than the second value or `false` otherwise|
 
+Examples:
+
+```grain
+use Int32.{ (>) }
+assert 2l > 1l
+```
+
 ### Int32.**(<=)**
 
 <details>
@@ -648,6 +795,18 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is less than or equal to the second value or `false` otherwise|
 
+Examples:
+
+```grain
+use Int32.{ (<=) }
+assert 1l <= 2l
+```
+
+```grain
+use Int32.{ (<=) }
+assert 1l <= 1l
+```
+
 ### Int32.**(>=)**
 
 <details>
@@ -681,6 +840,18 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is greater than or equal to the second value or `false` otherwise|
 
+Examples:
+
+```grain
+use Int32.{ (>=) }
+assert 2l >= 1l
+```
+
+```grain
+use Int32.{ (>=) }
+assert 1l >= 1l
+```
+
 ### Int32.**lnot**
 
 <details disabled>
@@ -706,6 +877,12 @@ Returns:
 |----|-----------|
 |`Int32`|Containing the inverted bits of the given value|
 
+Examples:
+
+```grain
+Int32.lnot(-5l) == 4l
+```
+
 ### Int32.**(&)**
 
 <details>
@@ -739,6 +916,13 @@ Returns:
 |----|-----------|
 |`Int32`|Containing a `1` in each bit position for which the corresponding bits of both operands are `1`|
 
+Examples:
+
+```grain
+use Int32.{ (&) }
+assert (3l & 4l) == 0l
+```
+
 ### Int32.**(|)**
 
 <details>
@@ -772,6 +956,13 @@ Returns:
 |----|-----------|
 |`Int32`|Containing a `1` in each bit position for which the corresponding bits of either or both operands are `1`|
 
+Examples:
+
+```grain
+use Int32.{ (|) }
+assert (3l | 4l) == 7l
+```
+
 ### Int32.**(^)**
 
 <details>
@@ -805,6 +996,13 @@ Returns:
 |----|-----------|
 |`Int32`|Containing a `1` in each bit position for which the corresponding bits of either but not both operands are `1`|
 
+Examples:
+
+```grain
+use Int32.{ (^) }
+assert (3l ^ 5l) == 6l
+```
+
 ### Int32.**clz**
 
 <details disabled>
@@ -830,6 +1028,16 @@ Returns:
 |----|-----------|
 |`Int32`|The amount of leading zeros|
 
+Examples:
+
+```grain
+Int32.clz(1l) == 31l
+```
+
+```grain
+Int32.clz(4l) == 29l
+```
+
 ### Int32.**ctz**
 
 <details disabled>
@@ -855,6 +1063,16 @@ Returns:
 |----|-----------|
 |`Int32`|The amount of trailing zeros|
 
+Examples:
+
+```grain
+Int32.ctz(1l) == 0l
+```
+
+```grain
+Int32.ctz(4l) == 2l
+```
+
 ### Int32.**popcnt**
 
 <details disabled>
@@ -880,6 +1098,16 @@ Returns:
 |----|-----------|
 |`Int32`|The amount of 1-bits in its operand|
 
+Examples:
+
+```grain
+Int32.popcnt(1l) == 1l
+```
+
+```grain
+Int32.popcnt(3l) == 2l
+```
+
 ### Int32.**(\*\*)**
 
 <details disabled>
@@ -906,3 +1134,10 @@ Returns:
 |----|-----------|
 |`Int32`|The base raised to the given power|
 
+Examples:
+
+```grain
+from Int32 use { (**) }
+assert 2l ** 3l == 8l
+```
+

package/int64.gr

@@ -3,6 +3,9 @@
  *
  * @example from "int64" include Int64
  *
+ * @example 1L
+ * @example -1L
+ *
  * @since v0.2.0
  */
 module Int64
@@ -29,6 +32,8 @@ provide { fromNumber, toNumber }
  * @param number: The value to convert
  * @returns The Uint64 represented as an Int64
  *
+ * @example Int64.fromUint64(1uL) == 1L
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -44,6 +49,9 @@ provide let fromUint64 = (number: Uint64) => {
  * @param value: The value to increment
  * @returns The incremented value
  *
+ * @example Int64.incr(1L) == 2L
+ * @example Int64.incr(-2L) == -1L
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -60,6 +68,9 @@ provide let incr = (value: Int64) => {
  * @param value: The value to decrement
  * @returns The decremented value
  *
+ * @example Int64.decr(2L) == 1L
+ * @example Int64.decr(0L) == -1L
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -77,6 +88,10 @@ provide let decr = (value: Int64) => {
  * @param y: The second operand
  * @returns The sum of the two operands
  *
+ * @example
+ * use Int64.{ (+) }
+ * assert 1L + 1L == 2L
+ *
  * @since v0.6.0
  * @history v0.2.0: Originally named `add`
  */
@@ -96,6 +111,10 @@ provide let (+) = (x: Int64, y: Int64) => {
  * @param y: The second operand
  * @returns The difference of the two operands
  *
+ * @example
+ * use Int64.{ (-) }
+ * assert 2L - 1L == 1L
+ *
  * @since v0.6.0
  * @history v0.2.0: Originally named `sub`
  */
@@ -115,6 +134,10 @@ provide let (-) = (x: Int64, y: Int64) => {
  * @param y: The second operand
  * @returns The product of the two operands
  *
+ * @example
+ * use Int64.{ (*) }
+ * assert 2L * 2L == 4L
+ *
  * @since v0.6.0
  * @history v0.2.0: Originally named `*`
  */
@@ -134,6 +157,10 @@ provide let (*) = (x: Int64, y: Int64) => {
  * @param y: The second operand
  * @returns The quotient of its operands
  *
+ * @example
+ * use Int64.{ (/) }
+ * assert 8L / 2L == 4L
+ *
  * @since v0.6.0
  * @history v0.2.0: Originally named `div`
  */
@@ -153,6 +180,8 @@ provide let (/) = (x: Int64, y: Int64) => {
  * @param y: The second operand
  * @returns The remainder of its operands
  *
+ * @example Int64.rem(8L, 3L) == 2L
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -180,6 +209,10 @@ let abs = n => {
  *
  * @throws ModuloByZero: When `y` is zero
  *
+ * @example
+ * use Int64.{ (%) }
+ * assert -5L % 3L == 1L
+ *
  * @since v0.6.0
  * @history v0.2.0: Originally named `mod`
  */
@@ -212,6 +245,9 @@ provide let (%) = (x: Int64, y: Int64) => {
  * @param amount: The number of bits to rotate by
  * @returns The rotated value
  *
+ * @example Int64.rotl(1L, 1L) == 2L
+ * @example Int64.rotl(1L, 2L) == 4L
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -229,6 +265,9 @@ provide let rotl = (value: Int64, amount: Int64) => {
  * @param amount: The number of bits to rotate by
  * @returns The rotated value
  *
+ * @example Int64.rotr(2L, 1L) == 1L
+ * @example Int64.rotr(4L, 2L) == 1L
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -246,6 +285,10 @@ provide let rotr = (value: Int64, amount: Int64) => {
  * @param amount: The number of bits to shift by
  * @returns The shifted value
  *
+ * @example
+ * use Int64.{ (<<) }
+ * assert (5L << 1L) == 10L
+ *
  * @since v0.6.0
  * @history v0.2.0: Originally named `shl`
  */
@@ -264,6 +307,10 @@ provide let (<<) = (value: Int64, amount: Int64) => {
  * @param amount: The amount to shift by
  * @returns The shifted value
  *
+ * @example
+ * use Int64.{ (>>) }
+ * assert (5L >> 1L) == 2L
+ *
  * @since v0.6.0
  * @history v0.2.0: Originally named `shr`
  */
@@ -282,6 +329,10 @@ provide let (>>) = (value: Int64, amount: Int64) => {
  * @param y: The second value
  * @returns `true` if the first value is equal to the second value or `false` otherwise
  *
+ * @example
+ * use Int64.{ (==) }
+ * assert 1L == 1L
+ *
  * @since v0.6.0
  * @history v0.4.0: Originally named `eq`
  */
@@ -299,6 +350,10 @@ provide let (==) = (x: Int64, y: Int64) => {
  * @param y: The second value
  * @returns `true` if the first value is not equal to the second value or `false` otherwise
  *
+ * @example
+ * use Int64.{ (!=) }
+ * assert 1L != 2L
+ *
  * @since v0.6.0
  * @history v0.4.0: Originally named `ne`
  */
@@ -315,6 +370,9 @@ provide let (!=) = (x: Int64, y: Int64) => {
  * @param value: The value to inspect
  * @returns `true` if the first value is equal to zero or `false` otherwise
  *
+ * @example Int64.eqz(0L) == true
+ * @example Int64.eqz(1L) == false
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -330,6 +388,10 @@ provide let eqz = (value: Int64) => {
  * @param y: The second value
  * @returns `true` if the first value is less than the second value or `false` otherwise
  *
+ * @example
+ * use Int64.{ (<) }
+ * assert 1L < 2L
+ *
  * @since v0.6.0
  * @history v0.2.0: Originally named `lt`
  */
@@ -347,6 +409,10 @@ provide let (<) = (x: Int64, y: Int64) => {
  * @param y: The second value
  * @returns `true` if the first value is greater than the second value or `false` otherwise
  *
+ * @example
+ * use Int64.{ (>) }
+ * assert 2L > 1L
+ *
  * @since v0.6.0
  * @history v0.2.0: Originally named `gt`
  */
@@ -364,6 +430,13 @@ provide let (>) = (x: Int64, y: Int64) => {
  * @param y: The second value
  * @returns `true` if the first value is less than or equal to the second value or `false` otherwise
  *
+ * @example
+ * use Int64.{ (<=) }
+ * assert 1L <= 2L
+ * @example
+ * use Int64.{ (<=) }
+ * assert 1L <= 1L
+ *
  * @since v0.6.0
  * @history v0.2.0: Originally named `lte`
  */
@@ -381,6 +454,13 @@ provide let (<=) = (x: Int64, y: Int64) => {
  * @param y: The second value
  * @returns `true` if the first value is greater than or equal to the second value or `false` otherwise
  *
+ * @example
+ * use Int64.{ (>=) }
+ * assert 2L >= 1L
+ * @example
+ * use Int64.{ (>=) }
+ * assert 1L >= 1L
+ *
  * @since v0.6.0
  * @history v0.2.0: Originally named `gte`
  */
@@ -397,6 +477,8 @@ provide let (>=) = (x: Int64, y: Int64) => {
  * @param value: The given value
  * @returns Containing the inverted bits of the given value
  *
+ * @example Int64.lnot(-5L) == 4L
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -413,6 +495,10 @@ provide let lnot = (value: Int64) => {
  * @param y: The second operand
  * @returns Containing a `1` in each bit position for which the corresponding bits of both operands are `1`
  *
+ * @example
+ * use Int64.{ (&) }
+ * assert (3L & 4L) == 0L
+ *
  * @since v0.6.0
  * @history v0.2.0: Originally named `land`
  */
@@ -431,6 +517,10 @@ provide let (&) = (x: Int64, y: Int64) => {
  * @param y: The second operand
  * @returns Containing a `1` in each bit position for which the corresponding bits of either or both operands are `1`
  *
+ * @example
+ * use Int64.{ (|) }
+ * assert (3L | 4L) == 7L
+ *
  * @since v0.6.0
  * @history v0.2.0: Originally named `lor`
  */
@@ -449,6 +539,10 @@ provide let (|) = (x: Int64, y: Int64) => {
  * @param y: The second operand
  * @returns Containing a `1` in each bit position for which the corresponding bits of either but not both operands are `1`
  *
+ * @example
+ * use Int64.{ (^) }
+ * assert (3L ^ 5L) == 6L
+ *
  * @since v0.6.0
  * @history v0.2.0: Originally named `lxor`
  */
@@ -466,6 +560,9 @@ provide let (^) = (x: Int64, y: Int64) => {
  * @param value: The value to inspect
  * @returns The amount of leading zeros
  *
+ * @example Int64.clz(1L) == 63L
+ * @example Int64.clz(4L) == 61L
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -481,6 +578,9 @@ provide let clz = (value: Int64) => {
  * @param value: The value to inspect
  * @returns The amount of trailing zeros
  *
+ * @example Int64.ctz(1L) == 0L
+ * @example Int64.ctz(4L) == 2L
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -496,6 +596,9 @@ provide let ctz = (value: Int64) => {
  * @param value: The value to inspect
  * @returns The amount of 1-bits in its operand
  *
+ * @example Int64.popcnt(1L) == 1L
+ * @example Int64.popcnt(3L) == 2L
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -525,6 +628,10 @@ let rec expBySquaring = (y, x, n) => {
  * @param power: The exponent number
  * @returns The base raised to the given power
  *
+ * @example
+ * from Int64 use { (**) }
+ * assert 2L ** 3L == 8L
+ *
  * @since v0.6.0
  */
 provide let (**) = (base, power) => {