@grain/stdlib 0.4.4 → 0.5.0

package/char.gr

@@ -1,210 +1,196 @@
+/**
+ * @module Char: 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"
+ * 
+ * @since 0.3.0
+ */
+
 import WasmI32 from "runtime/unsafe/wasmi32"
-import Memory from "runtime/unsafe/memory"
 import Errors from "runtime/unsafe/errors"
-import { tagSimpleNumber, allocateChar, allocateString } from "runtime/dataStructures"
-
-export *
+import Tags from "runtime/unsafe/tags"
+import {
+  tagSimpleNumber,
+  tagChar,
+  untagChar,
+  allocateString,
+} from "runtime/dataStructures"
 
 exception MalformedUtf8
 
-// The minimum value of Unicode characters
-// Number
-let min = 0x0000
-
-// The maximum value of Unicode characters
-// Number
-let max = 0x10FFFF
-
-// Returns true if the given number is a valid Unicode scalar value.
-// @param n: Number - the value to check
-// @returns Bool
-let isValid = (n) => {
-  n >= min && (n <= 0xD7FF || n >= 0xE000) && n <= max
+/**
+ * @section Values: Functions and constants included in the Char module.
+ */
+
+/**
+ * The minimum valid Unicode scalar value.
+ * 
+ * @since 0.3.0
+ */
+export let min = 0x0000
+/**
+ * The maximum valid Unicode scalar value.
+ * 
+ * @since 0.3.0
+ */
+export let max = 0x10FFFF
+
+/**
+ * Determines whether the given character code is a valid Unicode scalar value.
+ * 
+ * @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
+ */
+export let isValid = charCode => {
+  charCode >= min &&
+  (charCode <= 0xD7FF || charCode >= 0xE000) &&
+  charCode <= max
 }
 
-// Returns the Unicode code point for the character
-// @param char: Char - the input character
-// @returns Number
-@disableGC
-let rec code = (c: Char) => {
-  // Algorithm from https://encoding.spec.whatwg.org/#utf-8-decoder
-
-  let c = WasmI32.fromGrain(c)
+/**
+ * Determines the Unicode scalar value for a character.
+ * 
+ * @param char: The character
+ * @returns The Unicode scalar value for the given character
+ * 
+ * @since 0.3.0
+ */
+@unsafe
+export let code = (char: Char) => {
+  let usv = untagChar(char)
+
+  // This could save an instruction by combining the two tagging operations,
+  // though we stick with tagSimpleNumber for simplicity.
+  tagSimpleNumber(usv)
+}
 
-  let (+) = WasmI32.add
-  let (==) = WasmI32.eq
-  let (>=) = WasmI32.geU
-  let (<=) = WasmI32.leU
+/**
+ * Creates a character from the given Unicode scalar value.
+ * Throws an exception if the Unicode scalar value is invalid.
+ * 
+ * @param usv: The Unicode scalar value
+ * @returns The character for the given Unicode scalar value
+ * 
+ * @since 0.3.0
+ */
+@unsafe
+export let fromCode = (usv: Number) => {
+  let (-) = WasmI32.sub
   let (<<) = WasmI32.shl
-  let (&) = WasmI32.and
-  let (|) = WasmI32.or
 
-  let mut codePoint = 0n
-  let mut bytesSeen = 0n
-  let mut bytesNeeded = 0n
-  let mut lowerBoundary = 0x80n
-  let mut upperBoundary = 0xBFn
-
-  let mut offset = 0n
-
-  let mut result = 0n
-
-  while (true) {
-    let byte = WasmI32.load8U(c + offset, 4n)
-    offset += 1n
-    if (bytesNeeded == 0n) {
-      if (byte >= 0x00n && byte <= 0x7Fn) {
-        result = byte
-        break
-      } else if (byte >= 0xC2n && byte <= 0xDFn) {
-        bytesNeeded = 1n
-        codePoint = byte & 0x1Fn
-      } else if (byte >= 0xE0n && byte <= 0xEFn) {
-        if (byte == 0xE0n) lowerBoundary = 0xA0n
-        if (byte == 0xEDn) upperBoundary = 0x9Fn
-        bytesNeeded = 2n
-        codePoint = byte & 0xFn
-      } else if (byte >= 0xF0n && byte <= 0xF4n) {
-        if (byte == 0xF0n) lowerBoundary = 0x90n
-        if (byte == 0xF4n) upperBoundary = 0x8Fn
-        bytesNeeded = 3n
-        codePoint = byte & 0x7n
-      } else {
-        throw MalformedUtf8
-      }
-      continue
-    }
-    if (!(lowerBoundary <= byte && byte <= upperBoundary)) {
-      throw MalformedUtf8
-    }
-    lowerBoundary = 0x80n
-    upperBoundary = 0xBFn
-    codePoint = (codePoint << 6n) | (byte & 0x3Fn)
-    bytesSeen += 1n
-    if (bytesSeen == bytesNeeded) {
-      result = codePoint
-      break
-    }
+  if (!isValid(usv)) {
+    throw InvalidArgument("Invalid character code")
   }
 
-  Memory.decRef(c)
-  Memory.decRef(WasmI32.fromGrain(code))
-  tagSimpleNumber(result)
+  // usv is now guaranteed to be a simple number
+  let usv = WasmI32.fromGrain(usv)
+
+  // 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
+
+  WasmI32.toGrain(char): Char
+}
+
+/**
+ * Returns the next valid character by Unicode scalar value.
+ * Throws if the input character is the max valid Unicode scalar value.
+ * 
+ * @param char: The character
+ * @returns The next valid character by Unicode scalar value
+ * 
+ * @since 0.3.0
+ */
+export let succ = char => {
+  let codePoint = code(char)
+  if (codePoint == max) {
+    fail "no valid Unicode scalar value past U+10FFF"
+  } else if (codePoint == 0xD7FF) {
+    fromCode(0xE000)
+  } else {
+    fromCode(codePoint + 1)
+  }
 }
 
-// Returns the Char for the given code point. Fails if the code point is invalid.
-// @param codePoint: Number - the Unicode code point
-// @returns Char
-@disableGC
-let rec fromCode = (code: Number) => {
-  // Algorithm from https://encoding.spec.whatwg.org/#utf-8-encoder
+/**
+ * Returns the previous valid character by Unicode scalar value.
+ * Throws if the input character is the min valid Unicode scalar value.
+ * 
+ * @param char: The character
+ * @returns The previous valid character by Unicode scalar value
+ * 
+ * @since 0.3.0
+ */
+export let pred = char => {
+  let codePoint = code(char)
+  if (codePoint == min) {
+    fail "no valid Unicode scalar value below U+0000"
+  } else if (codePoint == 0xE000) {
+    fromCode(0xD7FF)
+  } else {
+    fromCode(codePoint - 1)
+  }
+}
 
+/**
+ * Converts the given character to a string.
+ * 
+ * @param char: The character to convert
+ * @returns A string containing the given character
+ * 
+ * @since 0.3.0
+ */
+@unsafe
+export let toString = (char: Char) => {
   let (+) = WasmI32.add
   let (-) = WasmI32.sub
   let (*) = WasmI32.mul
-  let (==) = WasmI32.eq
-  let (>) = WasmI32.gtU
-  let (<=) = WasmI32.leU
-  let (<) = WasmI32.ltU
-  let (>>>) = WasmI32.shrU
   let (&) = WasmI32.and
   let (|) = WasmI32.or
+  let (>>>) = WasmI32.shrU
+  let (<) = WasmI32.ltU
+  let (>) = WasmI32.gtU
+  let (<=) = WasmI32.leU
 
-  let code = WasmI32.fromGrain(code)
-  if ((code & 1n) == 0n) {
-    throw InvalidArgument("Invalid character code")
-  }
+  let usv = untagChar(char)
 
-  let code = code >>> 1n
-  let result = if (code < 0x80n) {
-    let char = allocateChar()
-    WasmI32.store8(char, code, 4n)
-    WasmI32.toGrain(char): Char
+  let result = if (usv < 0x80n) {
+    let string = allocateString(1n)
+    WasmI32.store8(string, usv, 8n)
+    WasmI32.toGrain(string): String
   } else {
     let mut count = 0n
     let mut offset = 0n
-    if (code <= 0x07FFn) {
+    if (usv <= 0x07FFn) {
       count = 1n
       offset = 0xC0n
-    } else if (code <= 0xFFFFn) {
+    } else if (usv <= 0xFFFFn) {
       count = 2n
       offset = 0xE0n
     } else {
       count = 3n
       offset = 0xF0n
     }
-    let char = allocateChar()
-    WasmI32.store8(char, (code >>> (6n * count)) + offset, 4n)
+    let string = allocateString(count + 1n)
+    WasmI32.store8(string, (usv >>> 6n * count) + offset, 8n)
 
     let mut n = 0n
     while (count > 0n) {
       n += 1n
-      let temp = code >>> (6n * (count - 1n))
-      WasmI32.store8(char + n, 0x80n | (temp & 0x3Fn), 4n)
+      let temp = usv >>> 6n * (count - 1n)
+      WasmI32.store8(string + n, 0x80n | temp & 0x3Fn, 8n)
       count -= 1n
     }
 
-    WasmI32.toGrain(char): Char
+    WasmI32.toGrain(string): String
   }
 
-  // We've asserted that the original `code` was a stack allocated number so
-  // no need to decRef it
-  Memory.decRef(WasmI32.fromGrain(fromCode))
   result
 }
-
-// Returns the next valid Unicode character by code point. Fails if the input character is U+10FFFF.
-// @param char: Char - the input character
-// @returns Char
-let succ = (c) => {
-  let codePoint = code(c)
-  if (codePoint == max) {
-    fail "no valid Unicode code point past U+10FFF"
-  } else if (codePoint == 0xD7FF) {
-    fromCode(0xE000)
-  } else {
-    fromCode(codePoint + 1)
-  }
-}
-
-// Returns the previous valid Unicode character by code point. Fails if the input character is U+0000.
-// @param char: Char - the input character
-// @returns Char
-let pred = (c) => {
-  let codePoint = code(c)
-  if (codePoint == min) {
-    fail "no valid Unicode code point below U+0000"
-  } else if (codePoint == 0xE000) {
-    fromCode(0xD7FF)
-  } else {
-    fromCode(codePoint - 1)
-  }
-}
-
-// Creates a new string containing the character.
-// @param char: Char - the character to convert
-// @returns String
-@disableGC
-export let rec toString = (c: Char) => {
-  let (+) = WasmI32.add
-  let (&) = WasmI32.and
-  let (==) = WasmI32.eq
-
-  let c = WasmI32.fromGrain(c)
-  let byte = WasmI32.load8U(c, 4n)
-  let n = if ((byte & 0x80n) == 0x00n) {
-    1n
-  } else if ((byte & 0xF0n) == 0xF0n) {
-    4n
-  } else if ((byte & 0xE0n) == 0xE0n) {
-    3n
-  } else {
-    2n
-  }
-  let str = allocateString(n)
-  Memory.copy(str + 8n, c + 4n, n)
-  let ret = WasmI32.toGrain(str): String
-  Memory.decRef(WasmI32.fromGrain(c))
-  Memory.decRef(WasmI32.fromGrain(toString))
-  ret
-}

package/char.md

@@ -0,0 +1,200 @@
+---
+title: Char
+---
+
+Utilities for working with the Char type.
+
+The Char type represents a single [Unicode scalar value](https://www.unicode.org/glossary/#unicode_scalar_value).
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.3.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+import Char from "char"
+```
+
+## Values
+
+Functions and constants included in the Char module.
+
+### Char.**min**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.3.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+min : Number
+```
+
+The minimum valid Unicode scalar value.
+
+### Char.**max**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.3.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+max : Number
+```
+
+The maximum valid Unicode scalar value.
+
+### Char.**isValid**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.3.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+isValid : Number -> Bool
+```
+
+Determines whether the given character code is a valid Unicode scalar value.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`charCode`|`Number`|The number to check|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the number refers to a valid Unicode scalar value or `false` otherwise|
+
+### Char.**code**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.3.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+code : Char -> Number
+```
+
+Determines the Unicode scalar value for a character.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`char`|`Char`|The character|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Number`|The Unicode scalar value for the given character|
+
+### Char.**fromCode**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.3.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+fromCode : Number -> Char
+```
+
+Creates a character from the given Unicode scalar value.
+Throws an exception if the Unicode scalar value is invalid.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`usv`|`Number`|The Unicode scalar value|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Char`|The character for the given Unicode scalar value|
+
+### Char.**succ**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.3.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+succ : Char -> Char
+```
+
+Returns the next valid character by Unicode scalar value.
+Throws if the input character is the max valid Unicode scalar value.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`char`|`Char`|The character|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Char`|The next valid character by Unicode scalar value|
+
+### Char.**pred**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.3.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+pred : Char -> Char
+```
+
+Returns the previous valid character by Unicode scalar value.
+Throws if the input character is the min valid Unicode scalar value.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`char`|`Char`|The character|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Char`|The previous valid character by Unicode scalar value|
+
+### Char.**toString**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.3.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+toString : Char -> String
+```
+
+Converts the given character to a string.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`char`|`Char`|The character to convert|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`String`|A string containing the given character|
+

package/exception.md

@@ -0,0 +1,6 @@
+### Exception.**registerPrinter**
+
+```grain
+registerPrinter : (Exception -> Option<String>) -> Void
+```
+