@grain/stdlib 0.5.12 → 0.6.0

package/char.gr

@@ -1,41 +1,36 @@
 /**
- * @module Char: Utilities for working with the Char type.
+ * Utilities for working with the Char type.
  *
  * The Char type represents a single [Unicode scalar value](https://www.unicode.org/glossary/#unicode_scalar_value).
  *
- * @example import Char from "char"
+ * @example from "char" include Char
  *
- * @since 0.3.0
+ * @example 'a'
+ * @example '1'
+ * @example '🌾'
+ *
+ * @since v0.3.0
  */
+module Char
 
-import WasmI32 from "runtime/unsafe/wasmi32"
-import Errors from "runtime/unsafe/errors"
-import Tags from "runtime/unsafe/tags"
-import {
-  tagSimpleNumber,
-  tagChar,
-  untagChar,
-  allocateString,
-} from "runtime/dataStructures"
+from "runtime/unsafe/wasmi32" include WasmI32
+from "runtime/dataStructures" include DataStructures
+use DataStructures.{ tagSimpleNumber, tagChar, untagChar, allocateString }
 
 exception MalformedUtf8
 
-/**
- * @section Values: Functions and constants included in the Char module.
- */
-
 /**
  * The minimum valid Unicode scalar value.
  *
- * @since 0.3.0
+ * @since v0.3.0
  */
-export let min = 0x0000
+provide let min = 0x0000
 /**
  * The maximum valid Unicode scalar value.
  *
- * @since 0.3.0
+ * @since v0.3.0
  */
-export let max = 0x10FFFF
+provide let max = 0x10FFFF
 
 /**
  * Determines whether the given character code is a valid Unicode scalar value.
@@ -43,9 +38,12 @@ export 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
  */
-export let isValid = charCode => {
+provide let isValid = charCode => {
   charCode >= min &&
     (charCode <= 0xD7FF || charCode >= 0xE000) &&
     charCode <= max
@@ -57,10 +55,13 @@ export 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
-export let code = (char: Char) => {
+provide let code = (char: Char) => {
   let usv = untagChar(char)
 
   // This could save an instruction by combining the two tagging operations,
@@ -76,12 +77,14 @@ export 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
-export let fromCode = (usv: Number) => {
-  let (-) = WasmI32.sub
-  let (<<) = WasmI32.shl
+provide let fromCode = (usv: Number) => {
+  use WasmI32.{ (-), (<<) }
 
   if (!isValid(usv)) {
     throw InvalidArgument("Invalid character code")
@@ -92,10 +95,10 @@ export let fromCode = (usv: Number) => {
 
   // Here we use a math trick to avoid fully untagging and retagging.
   // Simple numbers are represented as 2n + 1 and chars are represented as
-  // 8n + 2. Quick reminder that shifting left is the equivalent of multiplying
-  // by 2, and that _GRAIN_CHAR_TAG_TYPE is equal to 2:
-  // 4(2n + 1) - 2 = 8n + 2
-  let char = (usv << 2n) - Tags._GRAIN_CHAR_TAG_TYPE
+  // (2^8)n + 2. Quick reminder that shifting left is the equivalent of multiplying
+  // by 2
+  // 2^7(2n + 1) - (2^7 - 2) = (2^8)n + 2
+  let char = (usv << 7n) - 126n
 
   WasmI32.toGrain(char): Char
 }
@@ -108,9 +111,12 @@ export 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
  */
-export let succ = char => {
+provide let succ = char => {
   let codePoint = code(char)
   if (codePoint == max) {
     fail "no valid Unicode scalar value past U+10FFF"
@@ -129,9 +135,12 @@ export 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
  */
-export let pred = char => {
+provide let pred = char => {
   let codePoint = code(char)
   if (codePoint == min) {
     fail "no valid Unicode scalar value below U+0000"
@@ -148,19 +157,24 @@ export 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
-export let toString = (char: Char) => {
-  let (+) = WasmI32.add
-  let (-) = WasmI32.sub
-  let (*) = WasmI32.mul
-  let (&) = WasmI32.and
-  let (|) = WasmI32.or
-  let (>>>) = WasmI32.shrU
-  let (<) = WasmI32.ltU
-  let (>) = WasmI32.gtU
-  let (<=) = WasmI32.leU
+provide let toString = (char: Char) => {
+  use WasmI32.{
+    (+),
+    (-),
+    (*),
+    (&),
+    (|),
+    (>>>),
+    ltU as (<),
+    gtU as (>),
+    leU as (<=),
+  }
 
   let usv = untagChar(char)
 
@@ -182,12 +196,12 @@ export let toString = (char: Char) => {
       offset = 0xF0n
     }
     let string = allocateString(count + 1n)
-    WasmI32.store8(string, (usv >>> 6n * count) + offset, 8n)
+    WasmI32.store8(string, (usv >>> (6n * count)) + offset, 8n)
 
     let mut n = 0n
     while (count > 0n) {
       n += 1n
-      let temp = usv >>> 6n * (count - 1n)
+      let temp = usv >>> (6n * (count - 1n))
       WasmI32.store8(string + n, 0x80n | temp & 0x3Fn, 8n)
       count -= 1n
     }
@@ -197,3 +211,168 @@ export let toString = (char: Char) => {
 
   result
 }
+
+/**
+ * Checks if the first character is less than the second character by Unicode scalar value.
+ *
+ * @param x: The first character
+ * @param y: The second character
+ * @returns `true` if the first character is less than the second character or `false` otherwise
+ *
+ * @example
+ * use Char.{ (<) }
+ * assert 'a' < 'b'
+ * @example
+ * use Char.{ (<) }
+ * assert '1' < '2'
+ *
+ * @since v0.6.0
+ */
+@unsafe
+provide let (<) = (x: Char, y: Char) => {
+  use WasmI32.{ (<) }
+  let x = WasmI32.fromGrain(x)
+  let y = WasmI32.fromGrain(y)
+  x < y
+}
+
+/**
+ * Checks if the first character is less than or equal to the second character by Unicode scalar value.
+ *
+ * @param x: The first character
+ * @param y: The second character
+ * @returns `true` if the first character is less than or equal to the second character or `false` otherwise
+ *
+ * @example
+ * use Char.{ (<=) }
+ * assert 'a' <= 'b'
+ * @example
+ * use Char.{ (<=) }
+ * assert '1' <= '2'
+ * @example
+ * use Char.{ (<=) }
+ * assert 'a' <= 'a'
+ *
+ * @since v0.6.0
+ */
+@unsafe
+provide let (<=) = (x: Char, y: Char) => {
+  use WasmI32.{ (<=) }
+  let x = WasmI32.fromGrain(x)
+  let y = WasmI32.fromGrain(y)
+  x <= y
+}
+
+/**
+ * Checks if the first character is greater than the second character by Unicode scalar value.
+ *
+ * @param x: The first character
+ * @param y: The second character
+ * @returns `true` if the first character is greater than the second character or `false` otherwise
+ *
+ * @example
+ * use Char.{ (>) }
+ * assert 'b' > 'a'
+ * @example
+ * use Char.{ (>) }
+ * assert '2' > '1'
+ *
+ * @since v0.6.0
+ */
+@unsafe
+provide let (>) = (x: Char, y: Char) => {
+  use WasmI32.{ (>) }
+  let x = WasmI32.fromGrain(x)
+  let y = WasmI32.fromGrain(y)
+  x > y
+}
+
+/**
+ * Checks if the first character is greater than or equal to the second character by Unicode scalar value.
+ *
+ * @param x: The first character
+ * @param y: The second character
+ * @returns `true` if the first character is greater than or equal to the second character or `false` otherwise
+ *
+ * @example
+ * use Char.{ (>=) }
+ * assert 'b' >= 'a'
+ * @example
+ * use Char.{ (>=) }
+ * assert '2' >= '1'
+ * @example
+ * use Char.{ (>=) }
+ * assert 'a' >= 'a'
+ *
+ * @since v0.6.0
+ */
+@unsafe
+provide let (>=) = (x: Char, y: Char) => {
+  use WasmI32.{ (>=) }
+  let x = WasmI32.fromGrain(x)
+  let y = WasmI32.fromGrain(y)
+  x >= y
+}
+
+/**
+ * Checks if the character is an ASCII digit.
+ *
+ * @param char: The character to check
+ * @returns `true` if the character is an ASCII digit or `false` otherwise
+ * 
+ * @example assert Char.isAsciiDigit('1')
+ * @example assert !Char.isAsciiDigit('a')
+ *
+ * @since v0.6.0
+ */
+provide let isAsciiDigit = char => char >= '0' && char <= '9'
+
+/**
+ * Checks if the character is an ASCII alphabetical character.
+ *
+ * @param char: The character to check
+ * @returns `true` if the character is an ASCII alphabetical or `false` otherwise
+ *
+ * @example assert Char.isAsciiAlpha('a')
+ * @example assert !Char.isAsciiAlpha('1')
+ *
+ * @since v0.6.0
+ */
+provide let isAsciiAlpha = char =>
+  char >= 'a' && char <= 'z' || char >= 'A' && char <= 'Z'
+
+/**
+ * Converts the character to ASCII lowercase if it is an ASCII uppercase character.
+ * 
+ * @param char: The character to convert
+ * @returns The lowercased character
+ * 
+ * @example assert Char.toAsciiLowercase('B') == 'b'
+ * 
+ * @since v0.6.0
+ */
+provide let toAsciiLowercase = char => {
+  if (char >= 'A' && char <= 'Z') {
+    fromCode(code(char) + 0x20)
+  } else {
+    char
+  }
+}
+
+/**
+ * Converts the character to ASCII uppercase if it is an ASCII lowercase character.
+ * 
+ * @param char: The character to convert
+ * @returns The uppercased character
+ * 
+ * @example assert Char.toAsciiUppercase('b') == 'B'
+ * 
+ * @since v0.6.0
+ */
+provide let toAsciiUppercase = char => {
+  if (char >= 'a' && char <= 'z') {
+    fromCode(code(char) - 0x20)
+  } else {
+    char
+  }
+}