@grain/stdlib 0.6.5 → 0.7.0

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.
@@ -25,7 +33,7 @@ No other changes yet.
 </details>
 
 ```grain
-fromNumber : (number: Number) => Uint8
+fromNumber: (number: Number) => Uint8
 ```
 
 Converts a Number to a Uint8.
@@ -50,7 +58,7 @@ No other changes yet.
 </details>
 
 ```grain
-toNumber : (value: Uint8) => Number
+toNumber: (value: Uint8) => Number
 ```
 
 Converts a Uint8 to a Number.
@@ -75,7 +83,7 @@ No other changes yet.
 </details>
 
 ```grain
-fromInt8 : (number: Int8) => Uint8
+fromInt8: (number: Int8) => Uint8
 ```
 
 Converts an Int8 to a Uint8.
@@ -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>
@@ -100,7 +118,7 @@ No other changes yet.
 </details>
 
 ```grain
-incr : (value: Uint8) => Uint8
+incr: (value: Uint8) => Uint8
 ```
 
 Increments the value by one.
@@ -117,6 +135,12 @@ Returns:
 |----|-----------|
 |`Uint8`|The incremented value|
 
+Examples:
+
+```grain
+Uint8.incr(1us) == 2us
+```
+
 ### Uint8.**decr**
 
 <details disabled>
@@ -125,7 +149,7 @@ No other changes yet.
 </details>
 
 ```grain
-decr : (value: Uint8) => Uint8
+decr: (value: Uint8) => Uint8
 ```
 
 Decrements the value by one.
@@ -142,6 +166,16 @@ Returns:
 |----|-----------|
 |`Uint8`|The decremented value|
 
+Examples:
+
+```grain
+Uint8.decr(1us) == 0us
+```
+
+```grain
+Uint8.decr(0us) == 255us
+```
+
 ### Uint8.**(+)**
 
 <details disabled>
@@ -150,7 +184,7 @@ No other changes yet.
 </details>
 
 ```grain
-(+) : (x: Uint8, y: Uint8) => Uint8
+(+): (x: Uint8, y: Uint8) => Uint8
 ```
 
 Computes the sum of its operands.
@@ -168,6 +202,13 @@ Returns:
 |----|-----------|
 |`Uint8`|The sum of the two operands|
 
+Examples:
+
+```grain
+use Uint8.{ (+) }
+assert 1us + 1us == 2us
+```
+
 ### Uint8.**(-)**
 
 <details disabled>
@@ -176,7 +217,7 @@ No other changes yet.
 </details>
 
 ```grain
-(-) : (x: Uint8, y: Uint8) => Uint8
+(-): (x: Uint8, y: Uint8) => Uint8
 ```
 
 Computes the difference of its operands.
@@ -194,6 +235,13 @@ Returns:
 |----|-----------|
 |`Uint8`|The difference of the two operands|
 
+Examples:
+
+```grain
+use Uint8.{ (-) }
+assert 2us - 1us == 1us
+```
+
 ### Uint8.**(*)**
 
 <details disabled>
@@ -202,7 +250,7 @@ No other changes yet.
 </details>
 
 ```grain
-(*) : (x: Uint8, y: Uint8) => Uint8
+(*): (x: Uint8, y: Uint8) => Uint8
 ```
 
 Computes the product of its operands.
@@ -220,6 +268,13 @@ Returns:
 |----|-----------|
 |`Uint8`|The product of the two operands|
 
+Examples:
+
+```grain
+use Uint8.{ (*) }
+assert 2us * 2us == 4us
+```
+
 ### Uint8.**(/)**
 
 <details disabled>
@@ -228,7 +283,7 @@ No other changes yet.
 </details>
 
 ```grain
-(/) : (x: Uint8, y: Uint8) => Uint8
+(/): (x: Uint8, y: Uint8) => Uint8
 ```
 
 Computes the quotient of its operands.
@@ -246,6 +301,13 @@ Returns:
 |----|-----------|
 |`Uint8`|The quotient of its operands|
 
+Examples:
+
+```grain
+use Uint8.{ (/) }
+assert 5us / 2us == 2us
+```
+
 ### Uint8.**rem**
 
 <details disabled>
@@ -254,7 +316,7 @@ No other changes yet.
 </details>
 
 ```grain
-rem : (x: Uint8, y: Uint8) => Uint8
+rem: (x: Uint8, y: Uint8) => Uint8
 ```
 
 Computes the remainder of the division of its operands.
@@ -272,6 +334,12 @@ Returns:
 |----|-----------|
 |`Uint8`|The remainder of its operands|
 
+Examples:
+
+```grain
+Uint8.rem(5us, 2us) == 1us
+```
+
 ### Uint8.**(<<)**
 
 <details disabled>
@@ -280,7 +348,7 @@ No other changes yet.
 </details>
 
 ```grain
-(<<) : (value: Uint8, amount: Uint8) => Uint8
+(<<): (value: Uint8, amount: Uint8) => Uint8
 ```
 
 Shifts the bits of the value left by the given number of bits.
@@ -298,6 +366,13 @@ Returns:
 |----|-----------|
 |`Uint8`|The shifted value|
 
+Examples:
+
+```grain
+use Uint8.{ (<<) }
+assert (5us << 1us) == 10us
+```
+
 ### Uint8.**(>>>)**
 
 <details disabled>
@@ -306,7 +381,7 @@ No other changes yet.
 </details>
 
 ```grain
-(>>>) : (value: Uint8, amount: Uint8) => Uint8
+(>>>): (value: Uint8, amount: Uint8) => Uint8
 ```
 
 Shifts the bits of the value right by the given number of bits.
@@ -324,6 +399,13 @@ Returns:
 |----|-----------|
 |`Uint8`|The shifted value|
 
+Examples:
+
+```grain
+use Uint8.{ (>>>) }
+assert (5us >>> 1us) == 2us
+```
+
 ### Uint8.**(==)**
 
 <details disabled>
@@ -332,7 +414,7 @@ No other changes yet.
 </details>
 
 ```grain
-(==) : (x: Uint8, y: Uint8) => Bool
+(==): (x: Uint8, y: Uint8) => Bool
 ```
 
 Checks if the first value is equal to the second value.
@@ -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>
@@ -358,7 +447,7 @@ No other changes yet.
 </details>
 
 ```grain
-(!=) : (x: Uint8, y: Uint8) => Bool
+(!=): (x: Uint8, y: Uint8) => Bool
 ```
 
 Checks if the first value is not equal to the second value.
@@ -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>
@@ -384,7 +480,7 @@ No other changes yet.
 </details>
 
 ```grain
-(<) : (x: Uint8, y: Uint8) => Bool
+(<): (x: Uint8, y: Uint8) => Bool
 ```
 
 Checks if the first value is less than the second value.
@@ -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>
@@ -410,7 +513,7 @@ No other changes yet.
 </details>
 
 ```grain
-(>) : (x: Uint8, y: Uint8) => Bool
+(>): (x: Uint8, y: Uint8) => Bool
 ```
 
 Checks if the first value is greater than the second value.
@@ -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>
@@ -436,7 +546,7 @@ No other changes yet.
 </details>
 
 ```grain
-(<=) : (x: Uint8, y: Uint8) => Bool
+(<=): (x: Uint8, y: Uint8) => Bool
 ```
 
 Checks if the first value is less than or equal to the second value.
@@ -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>
@@ -462,7 +584,7 @@ No other changes yet.
 </details>
 
 ```grain
-(>=) : (x: Uint8, y: Uint8) => Bool
+(>=): (x: Uint8, y: Uint8) => Bool
 ```
 
 Checks if the first value is greater than or equal to the second value.
@@ -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>
@@ -488,7 +622,7 @@ No other changes yet.
 </details>
 
 ```grain
-lnot : (value: Uint8) => Uint8
+lnot: (value: Uint8) => Uint8
 ```
 
 Computes the bitwise NOT of the given value.
@@ -505,6 +639,12 @@ Returns:
 |----|-----------|
 |`Uint8`|Containing the inverted bits of the given value|
 
+Examples:
+
+```grain
+Uint8.lnot(5us) == 250us
+```
+
 ### Uint8.**(&)**
 
 <details disabled>
@@ -513,7 +653,7 @@ No other changes yet.
 </details>
 
 ```grain
-(&) : (x: Uint8, y: Uint8) => Uint8
+(&): (x: Uint8, y: Uint8) => Uint8
 ```
 
 Computes the bitwise AND (`&`) on the given operands.
@@ -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>
@@ -539,7 +686,7 @@ No other changes yet.
 </details>
 
 ```grain
-(|) : (x: Uint8, y: Uint8) => Uint8
+(|): (x: Uint8, y: Uint8) => Uint8
 ```
 
 Computes the bitwise OR (`|`) on the given operands.
@@ -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>
@@ -565,7 +719,7 @@ No other changes yet.
 </details>
 
 ```grain
-(^) : (x: Uint8, y: Uint8) => Uint8
+(^): (x: Uint8, y: Uint8) => Uint8
 ```
 
 Computes the bitwise XOR (`^`) on the given operands.
@@ -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
+```
+