@grain/stdlib 0.6.3 → 0.6.5

package/int32.gr

@@ -3,6 +3,9 @@
  *
  * @example from "int32" include Int32
  *
+ * @example 1l
+ * @example -1l
+ *
  * @since v0.2.0
  */
 module Int32
@@ -48,6 +51,8 @@ provide { fromNumber, toNumber }
  * @param number: The value to convert
  * @returns The Uint32 represented as an Int32
  *
+ * @example Int32.fromUint32(1ul) == 1l
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -63,6 +68,9 @@ provide let fromUint32 = (number: Uint32) => {
  * @param value: The value to increment
  * @returns The incremented value
  *
+ * @example Int32.incr(1l) == 2l
+ * @example Int32.incr(-2l) == -1l
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -78,6 +86,9 @@ provide let incr = (value: Int32) => {
  * @param value: The value to decrement
  * @returns The decremented value
  *
+ * @example Int32.decr(2l) == 1l
+ * @example Int32.decr(0l) == -1l
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -94,6 +105,10 @@ provide let decr = (value: Int32) => {
  * @param y: The second operand
  * @returns The sum of the two operands
  *
+ * @example
+ * use Int32.{ (+) }
+ * assert 1l + 1l == 2l
+ *
  * @since v0.6.0
  * @history v0.2.0: Originally named `add`
  */
@@ -112,6 +127,10 @@ provide let (+) = (x: Int32, y: Int32) => {
  * @param y: The second operand
  * @returns The difference of the two operands
  *
+ * @example
+ * use Int32.{ (-) }
+ * assert 2l - 1l == 1l
+ *
  * @since v0.6.0
  * @history v0.2.0: Originally named `sub`
  */
@@ -130,6 +149,10 @@ provide let (-) = (x: Int32, y: Int32) => {
  * @param y: The second operand
  * @returns The product of the two operands
  *
+ * @example
+ * use Int32.{ (*) }
+ * assert 2l * 2l == 4l
+ *
  * @since v0.6.0
  * @history v0.2.0: Originally named `mul`
  */
@@ -148,6 +171,10 @@ provide let (*) = (x: Int32, y: Int32) => {
  * @param y: The second operand
  * @returns The quotient of its operands
  *
+ * @example
+ * use Int32.{ (/) }
+ * assert 8l / 2l == 4l
+ *
  * @since v0.6.0
  * @history v0.2.0: Originally named `div`
  */
@@ -166,6 +193,8 @@ provide let (/) = (x: Int32, y: Int32) => {
  * @param y: The second operand
  * @returns The remainder of its operands
  *
+ * @example Int32.rem(8l, 3l) == 2l
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -193,6 +222,10 @@ let abs = n => {
  *
  * @throws ModuloByZero: When `y` is zero
  *
+ * @example
+ * use Int32.{ (%) }
+ * assert -5l % 3l == 1l
+ *
  * @since v0.6.0
  * @history v0.2.0: Originally named `mod`
  */
@@ -225,6 +258,9 @@ provide let (%) = (x: Int32, y: Int32) => {
  * @param amount: The number of bits to rotate by
  * @returns The rotated value
  *
+ * @example Int32.rotl(1l, 1l) == 2l
+ * @example Int32.rotl(1l, 2l) == 4l
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -242,6 +278,9 @@ provide let rotl = (value: Int32, amount: Int32) => {
  * @param amount: The number of bits to rotate by
  * @returns The rotated value
  *
+ * @example Int32.rotr(2l, 1l) == 1l
+ * @example Int32.rotr(4l, 2l) == 1l
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -259,6 +298,10 @@ provide let rotr = (value: Int32, amount: Int32) => {
  * @param amount: The number of bits to shift by
  * @returns The shifted value
  *
+ * @example
+ * use Int32.{ (<<) }
+ * assert (5l << 1l) == 10l
+ *
  * @since v0.6.0
  * @history v0.2.0: Originally named `shl`
  */
@@ -277,6 +320,10 @@ provide let (<<) = (value: Int32, amount: Int32) => {
  * @param amount: The amount to shift by
  * @returns The shifted value
  *
+ * @example
+ * use Int32.{ (>>) }
+ * assert (5l >> 1l) == 2l
+ *
  * @since v0.6.0
  * @history v0.2.0: Originally named `shr`
  */
@@ -295,6 +342,10 @@ provide let (>>) = (value: Int32, amount: Int32) => {
  * @param y: The second value
  * @returns `true` if the first value is equal to the second value or `false` otherwise
  *
+ * @example
+ * use Int32.{ (==) }
+ * assert 1l == 1l
+ *
  * @since v0.6.0
  * @history v0.4.0: Originally named `eq`
  */
@@ -312,6 +363,10 @@ provide let (==) = (x: Int32, y: Int32) => {
  * @param y: The second value
  * @returns `true` if the first value is not equal to the second value or `false` otherwise
  *
+ * @example
+ * use Int32.{ (!=) }
+ * assert 1l != 2l
+ *
  * @since v0.6.0
  * @history v0.4.0: Originally named `ne`
  */
@@ -328,6 +383,9 @@ provide let (!=) = (x: Int32, y: Int32) => {
  * @param value: The value to inspect
  * @returns `true` if the first value is equal to zero or `false` otherwise
  *
+ * @example Int32.eqz(0l) == true
+ * @example Int32.eqz(1l) == false
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -343,6 +401,10 @@ provide let eqz = (value: Int32) => {
  * @param y: The second value
  * @returns `true` if the first value is less than the second value or `false` otherwise
  *
+ * @example
+ * use Int32.{ (<) }
+ * assert 1l < 2l
+ *
  * @since v0.6.0
  * @history v0.2.0: Originally named `lt`
  */
@@ -360,6 +422,10 @@ provide let (<) = (x: Int32, y: Int32) => {
  * @param y: The second value
  * @returns `true` if the first value is greater than the second value or `false` otherwise
  *
+ * @example
+ * use Int32.{ (>) }
+ * assert 2l > 1l
+ *
  * @since v0.6.0
  * @history v0.2.0: Originally named `gt`
  */
@@ -377,6 +443,13 @@ provide let (>) = (x: Int32, y: Int32) => {
  * @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 Int32.{ (<=) }
+ * assert 1l <= 2l
+ * @example
+ * use Int32.{ (<=) }
+ * assert 1l <= 1l
+ *
  * @since v0.6.0
  * @history v0.2.0: Originally named `lte`
  */
@@ -394,6 +467,13 @@ provide let (<=) = (x: Int32, y: Int32) => {
  * @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 Int32.{ (>=) }
+ * assert 2l >= 1l
+ * @example
+ * use Int32.{ (>=) }
+ * assert 1l >= 1l
+ *
  * @since v0.6.0
  * @history v0.2.0: Originally named `gte`
  */
@@ -410,6 +490,8 @@ provide let (>=) = (x: Int32, y: Int32) => {
  * @param value: The given value
  * @returns Containing the inverted bits of the given value
  *
+ * @example Int32.lnot(-5l) == 4l
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -426,6 +508,10 @@ provide let lnot = (value: Int32) => {
  * @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 Int32.{ (&) }
+ * assert (3l & 4l) == 0l
+ *
  * @since v0.6.0
  * @history v0.2.0: Originally named `land`
  */
@@ -444,6 +530,10 @@ provide let (&) = (x: Int32, y: Int32) => {
  * @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 Int32.{ (|) }
+ * assert (3l | 4l) == 7l
+ *
  * @since v0.6.0
  * @history v0.2.0: Originally named `lor`
  */
@@ -462,6 +552,10 @@ provide let (|) = (x: Int32, y: Int32) => {
  * @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 Int32.{ (^) }
+ * assert (3l ^ 5l) == 6l
+ *
  * @since v0.6.0
  * @history v0.2.0: Originally named `lxor`
  */
@@ -479,6 +573,9 @@ provide let (^) = (x: Int32, y: Int32) => {
  * @param value: The value to inspect
  * @returns The amount of leading zeros
  *
+ * @example Int32.clz(1l) == 31l
+ * @example Int32.clz(4l) == 29l
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -494,6 +591,9 @@ provide let clz = (value: Int32) => {
  * @param value: The value to inspect
  * @returns The amount of trailing zeros
  *
+ * @example Int32.ctz(1l) == 0l
+ * @example Int32.ctz(4l) == 2l
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -509,6 +609,9 @@ provide let ctz = (value: Int32) => {
  * @param value: The value to inspect
  * @returns The amount of 1-bits in its operand
  *
+ * @example Int32.popcnt(1l) == 1l
+ * @example Int32.popcnt(3l) == 2l
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -538,6 +641,10 @@ let rec expBySquaring = (y, x, n) => {
  * @param power: The exponent number
  * @returns The base raised to the given power
  *
+ * @example
+ * from Int32 use { (**) }
+ * assert 2l ** 3l == 8l
+ *
  * @since v0.6.0
  */
 provide let (**) = (base, power) => {

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
+```
+