@grain/stdlib 0.5.12 → 0.6.0

package/char.md

@@ -12,7 +12,19 @@ No other changes yet.
 </details>
 
 ```grain
-import Char from "char"
+from "char" include Char
+```
+
+```grain
+'a'
+```
+
+```grain
+'1'
+```
+
+```grain
+'🌾'
 ```
 
 ## Values
@@ -53,7 +65,7 @@ No other changes yet.
 </details>
 
 ```grain
-isValid : Number -> Bool
+isValid : (charCode: Number) => Bool
 ```
 
 Determines whether the given character code is a valid Unicode scalar value.
@@ -70,6 +82,16 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the number refers to a valid Unicode scalar value or `false` otherwise|
 
+Examples:
+
+```grain
+Char.isValid(0) == true
+```
+
+```grain
+Char.isValid(-1) == false
+```
+
 ### Char.**code**
 
 <details disabled>
@@ -78,7 +100,7 @@ No other changes yet.
 </details>
 
 ```grain
-code : Char -> Number
+code : (char: Char) => Number
 ```
 
 Determines the Unicode scalar value for a character.
@@ -95,6 +117,16 @@ Returns:
 |----|-----------|
 |`Number`|The Unicode scalar value for the given character|
 
+Examples:
+
+```grain
+Char.code('a') == 97
+```
+
+```grain
+Char.code('🌾') == 127806
+```
+
 ### Char.**fromCode**
 
 <details disabled>
@@ -103,7 +135,7 @@ No other changes yet.
 </details>
 
 ```grain
-fromCode : Number -> Char
+fromCode : (usv: Number) => Char
 ```
 
 Creates a character from the given Unicode scalar value.
@@ -126,6 +158,16 @@ Throws:
 
 * When the Unicode scalar value is invalid
 
+Examples:
+
+```grain
+Char.fromCode(97) == 'a'
+```
+
+```grain
+Char.fromCode(127806) == '🌾'
+```
+
 ### Char.**succ**
 
 <details disabled>
@@ -134,7 +176,7 @@ No other changes yet.
 </details>
 
 ```grain
-succ : Char -> Char
+succ : (char: Char) => Char
 ```
 
 Returns the next valid character by Unicode scalar value.
@@ -157,6 +199,16 @@ Throws:
 
 * When the input character is the maximum valid Unicode scalar value
 
+Examples:
+
+```grain
+Char.succ('a') == 'b'
+```
+
+```grain
+Char.succ('1') == '2'
+```
+
 ### Char.**pred**
 
 <details disabled>
@@ -165,7 +217,7 @@ No other changes yet.
 </details>
 
 ```grain
-pred : Char -> Char
+pred : (char: Char) => Char
 ```
 
 Returns the previous valid character by Unicode scalar value.
@@ -188,6 +240,16 @@ Throws:
 
 * When the input character is the minimum valid Unicode scalar value
 
+Examples:
+
+```grain
+Char.pred('b') == 'a'
+```
+
+```grain
+Char.pred('2') == '1'
+```
+
 ### Char.**toString**
 
 <details disabled>
@@ -196,7 +258,7 @@ No other changes yet.
 </details>
 
 ```grain
-toString : Char -> String
+toString : (char: Char) => String
 ```
 
 Converts the given character to a string.
@@ -213,3 +275,307 @@ Returns:
 |----|-----------|
 |`String`|A string containing the given character|
 
+Examples:
+
+```grain
+Char.toString('a') == "a"
+```
+
+```grain
+Char.toString('🌾') == "🌾"
+```
+
+### Char.**(<)**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+(<) : (x: Char, y: Char) => Bool
+```
+
+Checks if the first character is less than the second character by Unicode scalar value.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`x`|`Char`|The first character|
+|`y`|`Char`|The second character|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the first character is less than the second character or `false` otherwise|
+
+Examples:
+
+```grain
+use Char.{ (<) }
+assert 'a' < 'b'
+```
+
+```grain
+use Char.{ (<) }
+assert '1' < '2'
+```
+
+### Char.**(<=)**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+(<=) : (x: Char, y: Char) => Bool
+```
+
+Checks if the first character is less than or equal to the second character by Unicode scalar value.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`x`|`Char`|The first character|
+|`y`|`Char`|The second character|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the first character is less than or equal to the second character or `false` otherwise|
+
+Examples:
+
+```grain
+use Char.{ (<=) }
+assert 'a' <= 'b'
+```
+
+```grain
+use Char.{ (<=) }
+assert '1' <= '2'
+```
+
+```grain
+use Char.{ (<=) }
+assert 'a' <= 'a'
+```
+
+### Char.**(>)**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+(>) : (x: Char, y: Char) => Bool
+```
+
+Checks if the first character is greater than the second character by Unicode scalar value.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`x`|`Char`|The first character|
+|`y`|`Char`|The second character|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the first character is greater than the second character or `false` otherwise|
+
+Examples:
+
+```grain
+use Char.{ (>) }
+assert 'b' > 'a'
+```
+
+```grain
+use Char.{ (>) }
+assert '2' > '1'
+```
+
+### Char.**(>=)**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+(>=) : (x: Char, y: Char) => Bool
+```
+
+Checks if the first character is greater than or equal to the second character by Unicode scalar value.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`x`|`Char`|The first character|
+|`y`|`Char`|The second character|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the first character is greater than or equal to the second character or `false` otherwise|
+
+Examples:
+
+```grain
+use Char.{ (>=) }
+assert 'b' >= 'a'
+```
+
+```grain
+use Char.{ (>=) }
+assert '2' >= '1'
+```
+
+```grain
+use Char.{ (>=) }
+assert 'a' >= 'a'
+```
+
+### Char.**isAsciiDigit**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+isAsciiDigit : (char: Char) => Bool
+```
+
+Checks if the character is an ASCII digit.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`char`|`Char`|The character to check|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the character is an ASCII digit or `false` otherwise|
+
+Examples:
+
+```grain
+assert Char.isAsciiDigit('1')
+```
+
+```grain
+assert !Char.isAsciiDigit('a')
+```
+
+### Char.**isAsciiAlpha**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+isAsciiAlpha : (char: Char) => Bool
+```
+
+Checks if the character is an ASCII alphabetical character.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`char`|`Char`|The character to check|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the character is an ASCII alphabetical or `false` otherwise|
+
+Examples:
+
+```grain
+assert Char.isAsciiAlpha('a')
+```
+
+```grain
+assert !Char.isAsciiAlpha('1')
+```
+
+### Char.**toAsciiLowercase**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+toAsciiLowercase : (char: Char) => Char
+```
+
+Converts the character to ASCII lowercase if it is an ASCII uppercase character.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`char`|`Char`|The character to convert|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Char`|The lowercased character|
+
+Examples:
+
+```grain
+assert Char.toAsciiLowercase('B') == 'b'
+```
+
+### Char.**toAsciiUppercase**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+toAsciiUppercase : (char: Char) => Char
+```
+
+Converts the character to ASCII uppercase if it is an ASCII lowercase character.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`char`|`Char`|The character to convert|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Char`|The uppercased character|
+
+Examples:
+
+```grain
+assert Char.toAsciiUppercase('b') == 'B'
+```
+

package/exception.gr

@@ -1,20 +1,20 @@
 /**
- * @module Exception: Utilities for working with the Exception type.
+ * Utilities for working with the Exception type.
  *
- * The Exception type represents an error that has occured during computation.
+ * The Exception type represents an error that has occurred during computation.
  *
- * @example import Exception from "exception"
+ * @example from "exception" include Exception
  *
- * @since 0.3.0
+ * @example exception ExampleError(Number)
+ * @example exception ExampleError
+ *
+ * @since v0.3.0
  */
+module Exception
 
-import WasmI32 from "runtime/unsafe/wasmi32"
-import Memory from "runtime/unsafe/memory"
-import Exception from "runtime/exception"
-
-/**
- * @section Values: Functions included in the Exception module.
- */
+from "runtime/unsafe/wasmi32" include WasmI32
+from "runtime/unsafe/memory" include Memory
+from "runtime/exception" include Exception
 
 /**
  * Registers an exception printer. When an exception is thrown, all registered
@@ -23,10 +23,24 @@ import Exception from "runtime/exception"
  * used as the exception's string value.
  *
  * @param printer: The exception printer to register
+ *
+ * @example
+ * exception ExampleError(Number)
+ *
+ * Exception.registerPrinter(e => {
+ *   match (e) {
+ *     ExampleError(lineNumber) =>
+ *       Some("Error found on line: " ++ toString(lineNumber)),
+ *     _ => None,
+ *   }
+ * })
+ *
+ * throw ExampleError(1) // Error found on line: 1
+ *
  * @since v0.3.0
  */
 @disableGC
-export let rec registerPrinter = (printer: Exception -> Option<String>) => {
+provide let rec registerPrinter = (printer: Exception => Option<String>) => {
   // This function _must_ be @disableGC because the printer list uses
   // unsafe types. Not really a memory leak as this list is never collected
 

package/exception.md

@@ -4,7 +4,7 @@ title: Exception
 
 Utilities for working with the Exception type.
 
-The Exception type represents an error that has occured during computation.
+The Exception type represents an error that has occurred during computation.
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.3.0</code></summary>
@@ -12,12 +12,20 @@ No other changes yet.
 </details>
 
 ```grain
-import Exception from "exception"
+from "exception" include Exception
+```
+
+```grain
+exception ExampleError(Number)
+```
+
+```grain
+exception ExampleError
 ```
 
 ## Values
 
-Functions included in the Exception module.
+Functions and constants included in the Exception module.
 
 ### Exception.**registerPrinter**
 
@@ -27,7 +35,7 @@ No other changes yet.
 </details>
 
 ```grain
-registerPrinter : (Exception -> Option<String>) -> Void
+registerPrinter : (printer: (Exception => Option<String>)) => Void
 ```
 
 Registers an exception printer. When an exception is thrown, all registered
@@ -39,5 +47,21 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`printer`|`Exception -> Option<String>`|The exception printer to register|
+|`printer`|`Exception => Option<String>`|The exception printer to register|
+
+Examples:
+
+```grain
+exception ExampleError(Number)
+
+Exception.registerPrinter(e => {
+  match (e) {
+    ExampleError(lineNumber) =>
+      Some("Error found on line: " ++ toString(lineNumber)),
+    _ => None,
+  }
+})
+
+throw ExampleError(1) // Error found on line: 1
+```