@grain/stdlib 0.6.5 → 0.6.6

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.6.6](https://github.com/grain-lang/grain/compare/stdlib-v0.6.5...stdlib-v0.6.6) (2024-08-12)
+
+
+### Miscellaneous Chores
+
+* **stdlib:** Synchronize Grain versions
+
 ## [0.6.5](https://github.com/grain-lang/grain/compare/stdlib-v0.6.4...stdlib-v0.6.5) (2024-07-31)
 
 

package/list.gr

@@ -9,6 +9,10 @@
  */
 module List
 
+from "runtime/unsafe/memory" include Memory
+from "runtime/unsafe/wasmi32" include WasmI32
+from "runtime/dataStructures" include DataStructures
+
 /**
  * Creates a new list of the specified length where each element is
  * initialized with the result of an initializer function. The initializer
@@ -842,6 +846,51 @@ provide let sub = (start, length, list) => {
   take(length, drop(start, list))
 }
 
+// List.join helpers
+@unsafe
+let rec computeJoinSize = (sepSize: WasmI32, size: WasmI32, lst: List<String>) => {
+  use WasmI32.{ (+) }
+  use DataStructures.{ stringSize }
+  match (lst) {
+    [] => size,
+    [hd] => size + stringSize(WasmI32.fromGrain(hd)),
+    [hd, ...tl] => {
+      let size = size + stringSize(WasmI32.fromGrain(hd)) + sepSize
+      ignore(hd)
+      computeJoinSize(sepSize, size, tl)
+    },
+  }
+}
+@unsafe
+let rec buildJoinedString = (
+  strPtr: WasmI32,
+  sepPtr: WasmI32,
+  sepSize: WasmI32,
+  offset: WasmI32,
+  lst: List<String>,
+) => {
+  use WasmI32.{ (+) }
+  use DataStructures.{ stringSize }
+  match (lst) {
+    [] => void,
+    // Last element
+    [hd] => {
+      let ptr = WasmI32.fromGrain(hd)
+      let size = stringSize(ptr)
+      Memory.copy(offset, ptr + 8n, size)
+      ignore(hd)
+    },
+    [hd, ...tl] => {
+      let ptr = WasmI32.fromGrain(hd)
+      let size = stringSize(ptr)
+      Memory.copy(offset, ptr + 8n, size)
+      ignore(hd)
+      let offset = offset + size
+      Memory.copy(offset, sepPtr, sepSize)
+      buildJoinedString(strPtr, sepPtr, sepSize, offset + sepSize, tl)
+    },
+  }
+}
 /**
  * Combine the given list of strings into one string with the specified
  * separator inserted between each item.
@@ -852,25 +901,17 @@ provide let sub = (start, length, list) => {
  *
  * @since v0.4.0
  */
+@unsafe
 provide let join = (separator: String, list: List<String>) => {
-  let rec iter = (sep, acc, rem) => {
-    match (rem) {
-      [] => acc,
-      [hd, ...tl] => {
-        let newAcc = match (acc) {
-          None => Some(hd),
-          Some(s) => Some(hd ++ sep ++ s),
-        }
-        iter(sep, newAcc, tl)
-      },
-    }
-  }
-
-  // Reverse and reduce to take advantage of TCE
-  match (iter(separator, None, reverse(list))) {
-    None => "",
-    Some(s) => s,
-  }
+  use WasmI32.{ (+), (-), (<=) }
+  use DataStructures.{ allocateString, stringSize }
+  let sepPtr = WasmI32.fromGrain(separator)
+  let sepSize = stringSize(sepPtr)
+  let strSize = computeJoinSize(sepSize, 0n, list)
+  let newString = allocateString(strSize)
+  buildJoinedString(newString, sepPtr + 8n, sepSize, newString + 8n, list)
+  ignore(sepPtr)
+  return WasmI32.toGrain(newString): String
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grain/stdlib",
-  "version": "0.6.5",
+  "version": "0.6.6",
   "description": "The standard library for the Grain language.",
   "license": "MIT",
   "homepage": "https://grain-lang.org",

package/uint16.gr

@@ -2,6 +2,9 @@
  * Utilities for working with the Uint16 type.
  * @example from "uint16" include Uint16
  *
+ * @example 1uS
+ * @example 10uS
+ *
  * @since v0.6.0
  */
 module Uint16
@@ -33,6 +36,9 @@ provide { fromNumber, toNumber }
  * @param number: The value to convert
  * @returns The Int16 represented as a Uint16
  *
+ * @example Uint16.fromInt16(1uS) == 1uS
+ * @example Uint16.fromInt16(-1uS) == 65535uS
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -49,6 +55,8 @@ provide let fromInt16 = (number: Int16) => {
  * @param value: The value to increment
  * @returns The incremented value
  *
+ * @example Uint16.incr(1uS) == 2uS
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -65,6 +73,9 @@ provide let incr = (value: Uint16) => {
  * @param value: The value to decrement
  * @returns The decremented value
  *
+ * @example Uint16.decr(1uS) == 0uS
+ * @example Uint16.decr(0uS) == 65535uS
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -82,6 +93,10 @@ provide let decr = (value: Uint16) => {
  * @param y: The second operand
  * @returns The sum of the two operands
  *
+ * @example
+ * use Uint16.{ (+) }
+ * assert 1uS + 1uS == 2uS
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -103,6 +118,10 @@ provide let (+) = (x: Uint16, y: Uint16) => {
  * @param y: The second operand
  * @returns The difference of the two operands
  *
+ * @example
+ * use Uint16.{ (-) }
+ * assert 2uS - 1uS == 1uS
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -121,6 +140,10 @@ provide let (-) = (x: Uint16, y: Uint16) => {
  * @param y: The second operand
  * @returns The product of the two operands
  *
+ * @example
+ * use Uint16.{ (*) }
+ * assert 2uS * 2uS == 4uS
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -138,6 +161,10 @@ provide let (*) = (x: Uint16, y: Uint16) => {
  * @param y: The second operand
  * @returns The quotient of its operands
  *
+ * @example
+ * use Uint16.{ (/) }
+ * assert 5uS / 2uS == 2uS
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -155,6 +182,8 @@ provide let (/) = (x: Uint16, y: Uint16) => {
  * @param y: The second operand
  * @returns The remainder of its operands
  *
+ * @example Uint16.rem(5uS, 2uS) == 1uS
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -172,6 +201,10 @@ provide let rem = (x: Uint16, y: Uint16) => {
  * @param amount: The number of bits to shift by
  * @returns The shifted value
  *
+ * @example
+ * use Uint16.{ (<<) }
+ * assert (5uS << 1uS) == 10uS
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -191,6 +224,10 @@ provide let (<<) = (value: Uint16, amount: Uint16) => {
  * @param amount: The amount to shift by
  * @returns The shifted value
  *
+ * @example
+ * use Uint16.{ (>>>) }
+ * assert (5uS >>> 1uS) == 2uS
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -210,6 +247,10 @@ provide let (>>>) = (value: Uint16, amount: Uint16) => {
  * @param y: The second value
  * @returns `true` if the first value is equal to the second value or `false` otherwise
  *
+ * @example
+ * use Uint16.{ (==) }
+ * assert 1uS == 1uS
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -226,6 +267,10 @@ provide let (==) = (x: Uint16, y: Uint16) => {
  * @param y: The second value
  * @returns `true` if the first value is not equal to the second value or `false` otherwise
  *
+ * @example
+ * use Uint16.{ (!=) }
+ * assert 1uS != 3uS
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -242,6 +287,10 @@ provide let (!=) = (x: Uint16, y: Uint16) => {
  * @param y: The second value
  * @returns `true` if the first value is less than the second value or `false` otherwise
  *
+ * @example
+ * use Uint16.{ (<) }
+ * assert 1uS < 5uS
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -258,6 +307,10 @@ provide let (<) = (x: Uint16, y: Uint16) => {
  * @param y: The second value
  * @returns `true` if the first value is greater than the second value or `false` otherwise
  *
+ * @example
+ * use Uint16.{ (>) }
+ * assert 4uS > 2uS
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -274,6 +327,13 @@ provide let (>) = (x: Uint16, y: Uint16) => {
  * @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 Uint16.{ (<=) }
+ * assert 1uS <= 2uS
+ * @example
+ * use Uint16.{ (<=) }
+ * assert 1uS <= 1uS
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -290,6 +350,13 @@ provide let (<=) = (x: Uint16, y: Uint16) => {
  * @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 Uint16.{ (>=) }
+ * assert 3uS >= 2uS
+ * @example
+ * use Uint16.{ (>=) }
+ * assert 1uS >= 1uS
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -305,6 +372,8 @@ provide let (>=) = (x: Uint16, y: Uint16) => {
  * @param value: The given value
  * @returns Containing the inverted bits of the given value
  *
+ * @example Uint16.lnot(5uS) == 65530uS
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -320,6 +389,10 @@ provide let lnot = (value: Uint16) => {
  * @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 Uint16.{ (&) }
+ * assert (3uS & 4uS) == 0uS
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -338,6 +411,10 @@ provide let (&) = (x: Uint16, y: Uint16) => {
  * @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 Uint16.{ (|) }
+ * assert (3uS | 4uS) == 7uS
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -356,6 +433,10 @@ provide let (|) = (x: Uint16, y: Uint16) => {
  * @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 Uint16.{ (^) }
+ * assert (3uS ^ 5uS) == 6uS
+ *
  * @since v0.6.0
  */
 @unsafe

package/uint16.md

@@ -13,6 +13,14 @@ No other changes yet.
 from "uint16" include Uint16
 ```
 
+```grain
+1uS
+```
+
+```grain
+10uS
+```
+
 ## Values
 
 Functions and constants included in the Uint16 module.
@@ -92,6 +100,16 @@ Returns:
 |----|-----------|
 |`Uint16`|The Int16 represented as a Uint16|
 
+Examples:
+
+```grain
+Uint16.fromInt16(1uS) == 1uS
+```
+
+```grain
+Uint16.fromInt16(-1uS) == 65535uS
+```
+
 ### Uint16.**incr**
 
 <details disabled>
@@ -117,6 +135,12 @@ Returns:
 |----|-----------|
 |`Uint16`|The incremented value|
 
+Examples:
+
+```grain
+Uint16.incr(1uS) == 2uS
+```
+
 ### Uint16.**decr**
 
 <details disabled>
@@ -142,6 +166,16 @@ Returns:
 |----|-----------|
 |`Uint16`|The decremented value|
 
+Examples:
+
+```grain
+Uint16.decr(1uS) == 0uS
+```
+
+```grain
+Uint16.decr(0uS) == 65535uS
+```
+
 ### Uint16.**(+)**
 
 <details disabled>
@@ -168,6 +202,13 @@ Returns:
 |----|-----------|
 |`Uint16`|The sum of the two operands|
 
+Examples:
+
+```grain
+use Uint16.{ (+) }
+assert 1uS + 1uS == 2uS
+```
+
 ### Uint16.**(-)**
 
 <details disabled>
@@ -194,6 +235,13 @@ Returns:
 |----|-----------|
 |`Uint16`|The difference of the two operands|
 
+Examples:
+
+```grain
+use Uint16.{ (-) }
+assert 2uS - 1uS == 1uS
+```
+
 ### Uint16.**(*)**
 
 <details disabled>
@@ -220,6 +268,13 @@ Returns:
 |----|-----------|
 |`Uint16`|The product of the two operands|
 
+Examples:
+
+```grain
+use Uint16.{ (*) }
+assert 2uS * 2uS == 4uS
+```
+
 ### Uint16.**(/)**
 
 <details disabled>
@@ -246,6 +301,13 @@ Returns:
 |----|-----------|
 |`Uint16`|The quotient of its operands|
 
+Examples:
+
+```grain
+use Uint16.{ (/) }
+assert 5uS / 2uS == 2uS
+```
+
 ### Uint16.**rem**
 
 <details disabled>
@@ -272,6 +334,12 @@ Returns:
 |----|-----------|
 |`Uint16`|The remainder of its operands|
 
+Examples:
+
+```grain
+Uint16.rem(5uS, 2uS) == 1uS
+```
+
 ### Uint16.**(<<)**
 
 <details disabled>
@@ -298,6 +366,13 @@ Returns:
 |----|-----------|
 |`Uint16`|The shifted value|
 
+Examples:
+
+```grain
+use Uint16.{ (<<) }
+assert (5uS << 1uS) == 10uS
+```
+
 ### Uint16.**(>>>)**
 
 <details disabled>
@@ -324,6 +399,13 @@ Returns:
 |----|-----------|
 |`Uint16`|The shifted value|
 
+Examples:
+
+```grain
+use Uint16.{ (>>>) }
+assert (5uS >>> 1uS) == 2uS
+```
+
 ### Uint16.**(==)**
 
 <details disabled>
@@ -350,6 +432,13 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is equal to the second value or `false` otherwise|
 
+Examples:
+
+```grain
+use Uint16.{ (==) }
+assert 1uS == 1uS
+```
+
 ### Uint16.**(!=)**
 
 <details disabled>
@@ -376,6 +465,13 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is not equal to the second value or `false` otherwise|
 
+Examples:
+
+```grain
+use Uint16.{ (!=) }
+assert 1uS != 3uS
+```
+
 ### Uint16.**(<)**
 
 <details disabled>
@@ -402,6 +498,13 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is less than the second value or `false` otherwise|
 
+Examples:
+
+```grain
+use Uint16.{ (<) }
+assert 1uS < 5uS
+```
+
 ### Uint16.**(>)**
 
 <details disabled>
@@ -428,6 +531,13 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is greater than the second value or `false` otherwise|
 
+Examples:
+
+```grain
+use Uint16.{ (>) }
+assert 4uS > 2uS
+```
+
 ### Uint16.**(<=)**
 
 <details disabled>
@@ -454,6 +564,18 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is less than or equal to the second value or `false` otherwise|
 
+Examples:
+
+```grain
+use Uint16.{ (<=) }
+assert 1uS <= 2uS
+```
+
+```grain
+use Uint16.{ (<=) }
+assert 1uS <= 1uS
+```
+
 ### Uint16.**(>=)**
 
 <details disabled>
@@ -480,6 +602,18 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is greater than or equal to the second value or `false` otherwise|
 
+Examples:
+
+```grain
+use Uint16.{ (>=) }
+assert 3uS >= 2uS
+```
+
+```grain
+use Uint16.{ (>=) }
+assert 1uS >= 1uS
+```
+
 ### Uint16.**lnot**
 
 <details disabled>
@@ -505,6 +639,12 @@ Returns:
 |----|-----------|
 |`Uint16`|Containing the inverted bits of the given value|
 
+Examples:
+
+```grain
+Uint16.lnot(5uS) == 65530uS
+```
+
 ### Uint16.**(&)**
 
 <details disabled>
@@ -531,6 +671,13 @@ Returns:
 |----|-----------|
 |`Uint16`|Containing a `1` in each bit position for which the corresponding bits of both operands are `1`|
 
+Examples:
+
+```grain
+use Uint16.{ (&) }
+assert (3uS & 4uS) == 0uS
+```
+
 ### Uint16.**(|)**
 
 <details disabled>
@@ -557,6 +704,13 @@ Returns:
 |----|-----------|
 |`Uint16`|Containing a `1` in each bit position for which the corresponding bits of either or both operands are `1`|
 
+Examples:
+
+```grain
+use Uint16.{ (|) }
+assert (3uS | 4uS) == 7uS
+```
+
 ### Uint16.**(^)**
 
 <details disabled>
@@ -583,3 +737,10 @@ Returns:
 |----|-----------|
 |`Uint16`|Containing a `1` in each bit position for which the corresponding bits of either but not both operands are `1`|
 
+Examples:
+
+```grain
+use Uint16.{ (^) }
+assert (3uS ^ 5uS) == 6uS
+```
+

package/uint8.gr

@@ -2,6 +2,9 @@
  * Utilities for working with the Uint8 type.
  * @example from "uint8" include Uint8
  *
+ * @example 1us
+ * @example 10us
+ *
  * @since v0.6.0
  */
 module Uint8
@@ -33,6 +36,9 @@ provide { fromNumber, toNumber }
  * @param number: The value to convert
  * @returns The Int8 represented as a Uint8
  *
+ * @example Uint8.fromInt8(1s) == 1us
+ * @example Uint8.fromInt8(-1s) == 255us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -49,6 +55,8 @@ provide let fromInt8 = (number: Int8) => {
  * @param value: The value to increment
  * @returns The incremented value
  *
+ * @example Uint8.incr(1us) == 2us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -65,6 +73,9 @@ provide let incr = (value: Uint8) => {
  * @param value: The value to decrement
  * @returns The decremented value
  *
+ * @example Uint8.decr(1us) == 0us
+ * @example Uint8.decr(0us) == 255us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -82,6 +93,10 @@ provide let decr = (value: Uint8) => {
  * @param y: The second operand
  * @returns The sum of the two operands
  *
+ * @example
+ * use Uint8.{ (+) }
+ * assert 1us + 1us == 2us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -103,6 +118,10 @@ provide let (+) = (x: Uint8, y: Uint8) => {
  * @param y: The second operand
  * @returns The difference of the two operands
  *
+ * @example
+ * use Uint8.{ (-) }
+ * assert 2us - 1us == 1us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -121,6 +140,10 @@ provide let (-) = (x: Uint8, y: Uint8) => {
  * @param y: The second operand
  * @returns The product of the two operands
  *
+ * @example
+ * use Uint8.{ (*) }
+ * assert 2us * 2us == 4us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -138,6 +161,10 @@ provide let (*) = (x: Uint8, y: Uint8) => {
  * @param y: The second operand
  * @returns The quotient of its operands
  *
+ * @example
+ * use Uint8.{ (/) }
+ * assert 5us / 2us == 2us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -155,6 +182,8 @@ provide let (/) = (x: Uint8, y: Uint8) => {
  * @param y: The second operand
  * @returns The remainder of its operands
  *
+ * @example Uint8.rem(5us, 2us) == 1us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -172,6 +201,10 @@ provide let rem = (x: Uint8, y: Uint8) => {
  * @param amount: The number of bits to shift by
  * @returns The shifted value
  *
+ * @example
+ * use Uint8.{ (<<) }
+ * assert (5us << 1us) == 10us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -191,6 +224,10 @@ provide let (<<) = (value: Uint8, amount: Uint8) => {
  * @param amount: The amount to shift by
  * @returns The shifted value
  *
+ * @example
+ * use Uint8.{ (>>>) }
+ * assert (5us >>> 1us) == 2us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -210,6 +247,10 @@ provide let (>>>) = (value: Uint8, amount: Uint8) => {
  * @param y: The second value
  * @returns `true` if the first value is equal to the second value or `false` otherwise
  *
+ * @example
+ * use Uint8.{ (==) }
+ * assert 1us == 1us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -226,6 +267,10 @@ provide let (==) = (x: Uint8, y: Uint8) => {
  * @param y: The second value
  * @returns `true` if the first value is not equal to the second value or `false` otherwise
  *
+ * @example
+ * use Uint8.{ (!=) }
+ * assert 1us != 3us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -242,6 +287,10 @@ provide let (!=) = (x: Uint8, y: Uint8) => {
  * @param y: The second value
  * @returns `true` if the first value is less than the second value or `false` otherwise
  *
+ * @example
+ * use Uint8.{ (<) }
+ * assert 1us < 5us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -258,6 +307,10 @@ provide let (<) = (x: Uint8, y: Uint8) => {
  * @param y: The second value
  * @returns `true` if the first value is greater than the second value or `false` otherwise
  *
+ * @example
+ * use Uint8.{ (>) }
+ * assert 4us > 2us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -274,6 +327,13 @@ provide let (>) = (x: Uint8, y: Uint8) => {
  * @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 Uint8.{ (<=) }
+ * assert 1us <= 2us
+ * @example
+ * use Uint8.{ (<=) }
+ * assert 1us <= 1us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -290,6 +350,13 @@ provide let (<=) = (x: Uint8, y: Uint8) => {
  * @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 Uint8.{ (>=) }
+ * assert 3us >= 2us
+ * @example
+ * use Uint8.{ (>=) }
+ * assert 1us >= 1us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -305,6 +372,8 @@ provide let (>=) = (x: Uint8, y: Uint8) => {
  * @param value: The given value
  * @returns Containing the inverted bits of the given value
  *
+ * @example Uint8.lnot(5us) == 250us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -320,6 +389,10 @@ provide let lnot = (value: Uint8) => {
  * @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 Uint8.{ (&) }
+ * assert (3us & 4us) == 0us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -338,6 +411,10 @@ provide let (&) = (x: Uint8, y: Uint8) => {
  * @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 Uint8.{ (|) }
+ * assert (3us | 4us) == 7us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -356,6 +433,10 @@ provide let (|) = (x: Uint8, y: Uint8) => {
  * @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 Uint8.{ (^) }
+ * assert (3us ^ 5us) == 6us
+ *
  * @since v0.6.0
  */
 @unsafe

package/uint8.md

@@ -13,6 +13,14 @@ No other changes yet.
 from "uint8" include Uint8
 ```
 
+```grain
+1us
+```
+
+```grain
+10us
+```
+
 ## Values
 
 Functions and constants included in the Uint8 module.
@@ -92,6 +100,16 @@ Returns:
 |----|-----------|
 |`Uint8`|The Int8 represented as a Uint8|
 
+Examples:
+
+```grain
+Uint8.fromInt8(1s) == 1us
+```
+
+```grain
+Uint8.fromInt8(-1s) == 255us
+```
+
 ### Uint8.**incr**
 
 <details disabled>
@@ -117,6 +135,12 @@ Returns:
 |----|-----------|
 |`Uint8`|The incremented value|
 
+Examples:
+
+```grain
+Uint8.incr(1us) == 2us
+```
+
 ### Uint8.**decr**
 
 <details disabled>
@@ -142,6 +166,16 @@ Returns:
 |----|-----------|
 |`Uint8`|The decremented value|
 
+Examples:
+
+```grain
+Uint8.decr(1us) == 0us
+```
+
+```grain
+Uint8.decr(0us) == 255us
+```
+
 ### Uint8.**(+)**
 
 <details disabled>
@@ -168,6 +202,13 @@ Returns:
 |----|-----------|
 |`Uint8`|The sum of the two operands|
 
+Examples:
+
+```grain
+use Uint8.{ (+) }
+assert 1us + 1us == 2us
+```
+
 ### Uint8.**(-)**
 
 <details disabled>
@@ -194,6 +235,13 @@ Returns:
 |----|-----------|
 |`Uint8`|The difference of the two operands|
 
+Examples:
+
+```grain
+use Uint8.{ (-) }
+assert 2us - 1us == 1us
+```
+
 ### Uint8.**(*)**
 
 <details disabled>
@@ -220,6 +268,13 @@ Returns:
 |----|-----------|
 |`Uint8`|The product of the two operands|
 
+Examples:
+
+```grain
+use Uint8.{ (*) }
+assert 2us * 2us == 4us
+```
+
 ### Uint8.**(/)**
 
 <details disabled>
@@ -246,6 +301,13 @@ Returns:
 |----|-----------|
 |`Uint8`|The quotient of its operands|
 
+Examples:
+
+```grain
+use Uint8.{ (/) }
+assert 5us / 2us == 2us
+```
+
 ### Uint8.**rem**
 
 <details disabled>
@@ -272,6 +334,12 @@ Returns:
 |----|-----------|
 |`Uint8`|The remainder of its operands|
 
+Examples:
+
+```grain
+Uint8.rem(5us, 2us) == 1us
+```
+
 ### Uint8.**(<<)**
 
 <details disabled>
@@ -298,6 +366,13 @@ Returns:
 |----|-----------|
 |`Uint8`|The shifted value|
 
+Examples:
+
+```grain
+use Uint8.{ (<<) }
+assert (5us << 1us) == 10us
+```
+
 ### Uint8.**(>>>)**
 
 <details disabled>
@@ -324,6 +399,13 @@ Returns:
 |----|-----------|
 |`Uint8`|The shifted value|
 
+Examples:
+
+```grain
+use Uint8.{ (>>>) }
+assert (5us >>> 1us) == 2us
+```
+
 ### Uint8.**(==)**
 
 <details disabled>
@@ -350,6 +432,13 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is equal to the second value or `false` otherwise|
 
+Examples:
+
+```grain
+use Uint8.{ (==) }
+assert 1us == 1us
+```
+
 ### Uint8.**(!=)**
 
 <details disabled>
@@ -376,6 +465,13 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is not equal to the second value or `false` otherwise|
 
+Examples:
+
+```grain
+use Uint8.{ (!=) }
+assert 1us != 3us
+```
+
 ### Uint8.**(<)**
 
 <details disabled>
@@ -402,6 +498,13 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is less than the second value or `false` otherwise|
 
+Examples:
+
+```grain
+use Uint8.{ (<) }
+assert 1us < 5us
+```
+
 ### Uint8.**(>)**
 
 <details disabled>
@@ -428,6 +531,13 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is greater than the second value or `false` otherwise|
 
+Examples:
+
+```grain
+use Uint8.{ (>) }
+assert 4us > 2us
+```
+
 ### Uint8.**(<=)**
 
 <details disabled>
@@ -454,6 +564,18 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is less than or equal to the second value or `false` otherwise|
 
+Examples:
+
+```grain
+use Uint8.{ (<=) }
+assert 1us <= 2us
+```
+
+```grain
+use Uint8.{ (<=) }
+assert 1us <= 1us
+```
+
 ### Uint8.**(>=)**
 
 <details disabled>
@@ -480,6 +602,18 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is greater than or equal to the second value or `false` otherwise|
 
+Examples:
+
+```grain
+use Uint8.{ (>=) }
+assert 3us >= 2us
+```
+
+```grain
+use Uint8.{ (>=) }
+assert 1us >= 1us
+```
+
 ### Uint8.**lnot**
 
 <details disabled>
@@ -505,6 +639,12 @@ Returns:
 |----|-----------|
 |`Uint8`|Containing the inverted bits of the given value|
 
+Examples:
+
+```grain
+Uint8.lnot(5us) == 250us
+```
+
 ### Uint8.**(&)**
 
 <details disabled>
@@ -531,6 +671,13 @@ Returns:
 |----|-----------|
 |`Uint8`|Containing a `1` in each bit position for which the corresponding bits of both operands are `1`|
 
+Examples:
+
+```grain
+use Uint8.{ (&) }
+assert (3us & 4us) == 0us
+```
+
 ### Uint8.**(|)**
 
 <details disabled>
@@ -557,6 +704,13 @@ Returns:
 |----|-----------|
 |`Uint8`|Containing a `1` in each bit position for which the corresponding bits of either or both operands are `1`|
 
+Examples:
+
+```grain
+use Uint8.{ (|) }
+assert (3us | 4us) == 7us
+```
+
 ### Uint8.**(^)**
 
 <details disabled>
@@ -583,3 +737,10 @@ Returns:
 |----|-----------|
 |`Uint8`|Containing a `1` in each bit position for which the corresponding bits of either but not both operands are `1`|
 
+Examples:
+
+```grain
+use Uint8.{ (^) }
+assert (3us ^ 5us) == 6us
+```
+