Skip to content

Commit

Permalink
chore(stdlib): Add examples to Int32 docs (#2121)
Browse files Browse the repository at this point in the history
  • Loading branch information
@spotandjake
spotandjake authored Jul 28, 2024
1 parent 651caa6 commit 24d2d93
Show file tree
Hide file tree
Showing 2 changed files with 342 additions and 0 deletions.
107 changes: 107 additions & 0 deletions stdlib/int32.gr
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@
*
* @example from "int32" include Int32
*
* @example 1l
* @example -1l
*
* @since v0.2.0
*/
module Int32
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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`
*/
Expand All @@ -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`
*/
Expand All @@ -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`
*/
Expand All @@ -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`
*/
Expand All @@ -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
Expand Down Expand Up @@ -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`
*/
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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`
*/
Expand All @@ -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`
*/
Expand All @@ -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`
*/
Expand All @@ -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`
*/
Expand All @@ -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
Expand All @@ -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`
*/
Expand All @@ -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`
*/
Expand All @@ -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`
*/
Expand All @@ -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`
*/
Expand All @@ -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
Expand All @@ -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`
*/
Expand All @@ -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`
*/
Expand All @@ -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`
*/
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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) => {
Expand Down
Loading

0 comments on commit 24d2d93

Please sign in to comment.