chore(stdlib): Add examples to Char module (#1951)

stdlib/char.gr

@@ -5,7 +5,11 @@
  *
  * @example include "char"
  *
- * @since 0.3.0
+ * @example 'a'
+ * @example '1'
+ * @example '🌾'
+ *
+ * @since v0.3.0
  */
 
 module Char
@@ -19,13 +23,13 @@ exception MalformedUtf8
 /**
  * The minimum valid Unicode scalar value.
  *
- * @since 0.3.0
+ * @since v0.3.0
  */
 provide let min = 0x0000
 /**
  * The maximum valid Unicode scalar value.
  *
- * @since 0.3.0
+ * @since v0.3.0
  */
 provide let max = 0x10FFFF
 
@@ -35,7 +39,10 @@ provide let max = 0x10FFFF
  * @param charCode: The number to check
  * @returns `true` if the number refers to a valid Unicode scalar value or `false` otherwise
  *
- * @since 0.3.0
+ * @example Char.isValid(0) == true
+ * @example Char.isValid(-1) == false
+ *
+ * @since v0.3.0
  */
 provide let isValid = charCode => {
   charCode >= min &&
@@ -49,7 +56,10 @@ provide let isValid = charCode => {
  * @param char: The character
  * @returns The Unicode scalar value for the given character
  *
- * @since 0.3.0
+ * @example Char.code('a') == 97
+ * @example Char.code('🌾') == 127806
+ *
+ * @since v0.3.0
  */
 @unsafe
 provide let code = (char: Char) => {
@@ -68,7 +78,10 @@ provide let code = (char: Char) => {
  *
  * @throws InvalidArgument(String): When the Unicode scalar value is invalid
  *
- * @since 0.3.0
+ * @example Char.fromCode(97) == 'a'
+ * @example Char.fromCode(127806) == '🌾'
+ *
+ * @since v0.3.0
  */
 @unsafe
 provide let fromCode = (usv: Number) => {
@@ -99,7 +112,10 @@ provide let fromCode = (usv: Number) => {
  *
  * @throws Failure(String): When the input character is the maximum valid Unicode scalar value
  *
- * @since 0.3.0
+ * @example Char.succ('a') == 'b'
+ * @example Char.succ('1') == '2'
+ *
+ * @since v0.3.0
  */
 provide let succ = char => {
   let codePoint = code(char)
@@ -120,7 +136,10 @@ provide let succ = char => {
  *
  * @throws Failure(String): When the input character is the minimum valid Unicode scalar value
  *
- * @since 0.3.0
+ * @example Char.pred('b') == 'a'
+ * @example Char.pred('2') == '1'
+ *
+ * @since v0.3.0
  */
 provide let pred = char => {
   let codePoint = code(char)
@@ -139,7 +158,10 @@ provide let pred = char => {
  * @param char: The character to convert
  * @returns A string containing the given character
  *
- * @since 0.3.0
+ * @example Char.toString('a') == "a"
+ * @example Char.toString('🌾') == "🌾"
+ *
+ * @since v0.3.0
  */
 @unsafe
 provide let toString = (char: Char) => {
@@ -198,6 +220,13 @@ provide let toString = (char: Char) => {
  * @param y: The second character
  * @returns `true` if the first character is less than the second character or `false` otherwise
  *
+ * @example
+ * from Char use { (<) }
+ * assert 'a' < 'b'
+ * @example
+ * from Char use { (<) }
+ * assert '1' < '2'
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -215,6 +244,16 @@ provide let (<) = (x: Char, y: Char) => {
  * @param y: The second character
  * @returns `true` if the first character is less than or equal to the second character or `false` otherwise
  *
+ * @example
+ * from Char use { (<=) }
+ * assert 'a' <= 'b'
+ * @example
+ * from Char use { (<=) }
+ * assert '1' <= '2'
+ * @example
+ * from Char use { (<=) }
+ * assert 'a' <= 'a'
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -232,6 +271,13 @@ provide let (<=) = (x: Char, y: Char) => {
  * @param y: The second character
  * @returns `true` if the first character is greater than the second character or `false` otherwise
  *
+ * @example
+ * from Char use { (>) }
+ * assert 'b' > 'a'
+ * @example
+ * from Char use { (>) }
+ * assert '2' > '1'
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -249,6 +295,16 @@ provide let (>) = (x: Char, y: Char) => {
  * @param y: The second character
  * @returns `true` if the first character is greater than or equal to the second character or `false` otherwise
  *
+ * @example
+ * from Char use { (>=) }
+ * assert 'b' >= 'a'
+ * @example
+ * from Char use { (>=) }
+ * assert '2' >= '1'
+ * @example
+ * from Char use { (>=) }
+ * assert 'a' >= 'a'
+ *
  * @since v0.6.0
  */
 @unsafe

stdlib/char.md

@@ -15,6 +15,18 @@ No other changes yet.
 include "char"
 ```
 
+```grain
+'a'
+```
+
+```grain
+'1'
+```
+
+```grain
+'🌾'
+```
+
 ## Values
 
 Functions and constants included in the Char module.
@@ -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>
@@ -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>
@@ -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>
@@ -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>
@@ -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>
@@ -213,6 +275,16 @@ Returns:
 |----|-----------|
 |`String`|A string containing the given character|
 
+Examples:
+
+```grain
+Char.toString('a') == "a"
+```
+
+```grain
+Char.toString('🌾') == "🌾"
+```
+
 ### Char.**(<)**
 
 <details disabled>
@@ -239,6 +311,18 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first character is less than the second character or `false` otherwise|
 
+Examples:
+
+```grain
+from Char use { (<) }
+assert 'a' < 'b'
+```
+
+```grain
+from Char use { (<) }
+assert '1' < '2'
+```
+
 ### Char.**(<=)**
 
 <details disabled>
@@ -265,6 +349,23 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first character is less than or equal to the second character or `false` otherwise|
 
+Examples:
+
+```grain
+from Char use { (<=) }
+assert 'a' <= 'b'
+```
+
+```grain
+from Char use { (<=) }
+assert '1' <= '2'
+```
+
+```grain
+from Char use { (<=) }
+assert 'a' <= 'a'
+```
+
 ### Char.**(>)**
 
 <details disabled>
@@ -291,6 +392,18 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first character is greater than the second character or `false` otherwise|
 
+Examples:
+
+```grain
+from Char use { (>) }
+assert 'b' > 'a'
+```
+
+```grain
+from Char use { (>) }
+assert '2' > '1'
+```
+
 ### Char.**(>=)**
 
 <details disabled>
@@ -317,3 +430,20 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first character is greater than or equal to the second character or `false` otherwise|
 
+Examples:
+
+```grain
+from Char use { (>=) }
+assert 'b' >= 'a'
+```
+
+```grain
+from Char use { (>=) }
+assert '2' >= '1'
+```
+
+```grain
+from Char use { (>=) }
+assert 'a' >= 'a'
+```
+