diff --git a/stdlib/int32.gr b/stdlib/int32.gr index b88a8fe5c..de9020b47 100644 --- a/stdlib/int32.gr +++ b/stdlib/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) => { diff --git a/stdlib/int32.md b/stdlib/int32.md index 72c0b78f8..384569a86 100644 --- a/stdlib/int32.md +++ b/stdlib/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**
@@ -117,6 +131,16 @@ Returns: |----|-----------| |`Int32`|The incremented value| +Examples: + +```grain +Int32.incr(1l) == 2l +``` + +```grain +Int32.incr(-2l) == -1l +``` + ### Int32.**decr**
@@ -142,6 +166,16 @@ Returns: |----|-----------| |`Int32`|The decremented value| +Examples: + +```grain +Int32.decr(2l) == 1l +``` + +```grain +Int32.decr(0l) == -1l +``` + ### Int32.**(+)**
@@ -175,6 +209,13 @@ Returns: |----|-----------| |`Int32`|The sum of the two operands| +Examples: + +```grain +use Int32.{ (+) } +assert 1l + 1l == 2l +``` + ### Int32.**(-)**
@@ -208,6 +249,13 @@ Returns: |----|-----------| |`Int32`|The difference of the two operands| +Examples: + +```grain +use Int32.{ (-) } +assert 2l - 1l == 1l +``` + ### Int32.**(*)**
@@ -241,6 +289,13 @@ Returns: |----|-----------| |`Int32`|The product of the two operands| +Examples: + +```grain +use Int32.{ (*) } +assert 2l * 2l == 4l +``` + ### Int32.**(/)**
@@ -274,6 +329,13 @@ Returns: |----|-----------| |`Int32`|The quotient of its operands| +Examples: + +```grain +use Int32.{ (/) } +assert 8l / 2l == 4l +``` + ### Int32.**rem**
@@ -300,6 +362,12 @@ Returns: |----|-----------| |`Int32`|The remainder of its operands| +Examples: + +```grain +Int32.rem(8l, 3l) == 2l +``` + ### Int32.**(%)**
@@ -340,6 +408,13 @@ Throws: * When `y` is zero +Examples: + +```grain +use Int32.{ (%) } +assert -5l % 3l == 1l +``` + ### Int32.**rotl**
@@ -366,6 +441,16 @@ Returns: |----|-----------| |`Int32`|The rotated value| +Examples: + +```grain +Int32.rotl(1l, 1l) == 2l +``` + +```grain +Int32.rotl(1l, 2l) == 4l +``` + ### Int32.**rotr**
@@ -392,6 +477,16 @@ Returns: |----|-----------| |`Int32`|The rotated value| +Examples: + +```grain +Int32.rotr(2l, 1l) == 1l +``` + +```grain +Int32.rotr(4l, 2l) == 1l +``` + ### Int32.**(<<)**
@@ -425,6 +520,13 @@ Returns: |----|-----------| |`Int32`|The shifted value| +Examples: + +```grain +use Int32.{ (<<) } +assert (5l << 1l) == 10l +``` + ### Int32.**(>>)**
@@ -458,6 +560,13 @@ Returns: |----|-----------| |`Int32`|The shifted value| +Examples: + +```grain +use Int32.{ (>>) } +assert (5l >> 1l) == 2l +``` + ### Int32.**(==)**
@@ -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.**(!=)**
@@ -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**
@@ -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.**(<)**
@@ -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.**(>)**
@@ -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.**(<=)**
@@ -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.**(>=)**
@@ -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**
@@ -706,6 +877,12 @@ Returns: |----|-----------| |`Int32`|Containing the inverted bits of the given value| +Examples: + +```grain +Int32.lnot(-5l) == 4l +``` + ### Int32.**(&)**
@@ -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.**(|)**
@@ -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.**(^)**
@@ -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**
@@ -830,6 +1028,16 @@ Returns: |----|-----------| |`Int32`|The amount of leading zeros| +Examples: + +```grain +Int32.clz(1l) == 31l +``` + +```grain +Int32.clz(4l) == 29l +``` + ### Int32.**ctz**
@@ -855,6 +1063,16 @@ Returns: |----|-----------| |`Int32`|The amount of trailing zeros| +Examples: + +```grain +Int32.ctz(1l) == 0l +``` + +```grain +Int32.ctz(4l) == 2l +``` + ### Int32.**popcnt**
@@ -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.**(\*\*)**
@@ -906,3 +1134,10 @@ Returns: |----|-----------| |`Int32`|The base raised to the given power| +Examples: + +```grain +from Int32 use { (**) } +assert 2l ** 3l == 8l +``` +