@grain/stdlib 0.6.5 → 0.7.0

package/runtime/unsafe/wasmi64.md

@@ -9,300 +9,300 @@ Functions and constants included in the WasmI64 module.
 ### WasmI64.**load**
 
 ```grain
-load : (ptr: WasmI32, offset: WasmI32) => WasmI64
+load: (ptr: WasmI32, offset: WasmI32) => WasmI64
 ```
 
 ### WasmI64.**load8S**
 
 ```grain
-load8S : (ptr: WasmI32, offset: WasmI32) => WasmI64
+load8S: (ptr: WasmI32, offset: WasmI32) => WasmI64
 ```
 
 ### WasmI64.**load8U**
 
 ```grain
-load8U : (ptr: WasmI32, offset: WasmI32) => WasmI64
+load8U: (ptr: WasmI32, offset: WasmI32) => WasmI64
 ```
 
 ### WasmI64.**load16S**
 
 ```grain
-load16S : (ptr: WasmI32, offset: WasmI32) => WasmI64
+load16S: (ptr: WasmI32, offset: WasmI32) => WasmI64
 ```
 
 ### WasmI64.**load16U**
 
 ```grain
-load16U : (ptr: WasmI32, offset: WasmI32) => WasmI64
+load16U: (ptr: WasmI32, offset: WasmI32) => WasmI64
 ```
 
 ### WasmI64.**load32S**
 
 ```grain
-load32S : (ptr: WasmI32, offset: WasmI32) => WasmI64
+load32S: (ptr: WasmI32, offset: WasmI32) => WasmI64
 ```
 
 ### WasmI64.**load32U**
 
 ```grain
-load32U : (ptr: WasmI32, offset: WasmI32) => WasmI64
+load32U: (ptr: WasmI32, offset: WasmI32) => WasmI64
 ```
 
 ### WasmI64.**store**
 
 ```grain
-store : (ptr: WasmI32, value: WasmI64, offset: WasmI32) => Void
+store: (ptr: WasmI32, value: WasmI64, offset: WasmI32) => Void
 ```
 
 ### WasmI64.**store8**
 
 ```grain
-store8 : (ptr: WasmI32, value: WasmI64, offset: WasmI32) => Void
+store8: (ptr: WasmI32, value: WasmI64, offset: WasmI32) => Void
 ```
 
 ### WasmI64.**store16**
 
 ```grain
-store16 : (ptr: WasmI32, value: WasmI64, offset: WasmI32) => Void
+store16: (ptr: WasmI32, value: WasmI64, offset: WasmI32) => Void
 ```
 
 ### WasmI64.**store32**
 
 ```grain
-store32 : (ptr: WasmI32, value: WasmI64, offset: WasmI32) => Void
+store32: (ptr: WasmI32, value: WasmI64, offset: WasmI32) => Void
 ```
 
 ### WasmI64.**clz**
 
 ```grain
-clz : (num: WasmI64) => WasmI64
+clz: (num: WasmI64) => WasmI64
 ```
 
 ### WasmI64.**ctz**
 
 ```grain
-ctz : (num: WasmI64) => WasmI64
+ctz: (num: WasmI64) => WasmI64
 ```
 
 ### WasmI64.**popcnt**
 
 ```grain
-popcnt : (num: WasmI64) => WasmI64
+popcnt: (num: WasmI64) => WasmI64
 ```
 
 ### WasmI64.**eqz**
 
 ```grain
-eqz : (num: WasmI64) => Bool
+eqz: (num: WasmI64) => Bool
 ```
 
 ### WasmI64.**(+)**
 
 ```grain
-(+) : (left: WasmI64, right: WasmI64) => WasmI64
+(+): (left: WasmI64, right: WasmI64) => WasmI64
 ```
 
 ### WasmI64.**(-)**
 
 ```grain
-(-) : (left: WasmI64, right: WasmI64) => WasmI64
+(-): (left: WasmI64, right: WasmI64) => WasmI64
 ```
 
 ### WasmI64.**(*)**
 
 ```grain
-(*) : (left: WasmI64, right: WasmI64) => WasmI64
+(*): (left: WasmI64, right: WasmI64) => WasmI64
 ```
 
 ### WasmI64.**(/)**
 
 ```grain
-(/) : (left: WasmI64, right: WasmI64) => WasmI64
+(/): (left: WasmI64, right: WasmI64) => WasmI64
 ```
 
 ### WasmI64.**divU**
 
 ```grain
-divU : (left: WasmI64, right: WasmI64) => WasmI64
+divU: (left: WasmI64, right: WasmI64) => WasmI64
 ```
 
 ### WasmI64.**remS**
 
 ```grain
-remS : (left: WasmI64, right: WasmI64) => WasmI64
+remS: (left: WasmI64, right: WasmI64) => WasmI64
 ```
 
 ### WasmI64.**remU**
 
 ```grain
-remU : (left: WasmI64, right: WasmI64) => WasmI64
+remU: (left: WasmI64, right: WasmI64) => WasmI64
 ```
 
 ### WasmI64.**(&)**
 
 ```grain
-(&) : (left: WasmI64, right: WasmI64) => WasmI64
+(&): (left: WasmI64, right: WasmI64) => WasmI64
 ```
 
 ### WasmI64.**(|)**
 
 ```grain
-(|) : (left: WasmI64, right: WasmI64) => WasmI64
+(|): (left: WasmI64, right: WasmI64) => WasmI64
 ```
 
 ### WasmI64.**(^)**
 
 ```grain
-(^) : (left: WasmI64, right: WasmI64) => WasmI64
+(^): (left: WasmI64, right: WasmI64) => WasmI64
 ```
 
 ### WasmI64.**(<<)**
 
 ```grain
-(<<) : (left: WasmI64, right: WasmI64) => WasmI64
+(<<): (left: WasmI64, right: WasmI64) => WasmI64
 ```
 
 ### WasmI64.**(>>>)**
 
 ```grain
-(>>>) : (left: WasmI64, right: WasmI64) => WasmI64
+(>>>): (left: WasmI64, right: WasmI64) => WasmI64
 ```
 
 ### WasmI64.**(>>)**
 
 ```grain
-(>>) : (left: WasmI64, right: WasmI64) => WasmI64
+(>>): (left: WasmI64, right: WasmI64) => WasmI64
 ```
 
 ### WasmI64.**rotl**
 
 ```grain
-rotl : (left: WasmI64, right: WasmI64) => WasmI64
+rotl: (left: WasmI64, right: WasmI64) => WasmI64
 ```
 
 ### WasmI64.**rotr**
 
 ```grain
-rotr : (left: WasmI64, right: WasmI64) => WasmI64
+rotr: (left: WasmI64, right: WasmI64) => WasmI64
 ```
 
 ### WasmI64.**(==)**
 
 ```grain
-(==) : (left: WasmI64, right: WasmI64) => Bool
+(==): (left: WasmI64, right: WasmI64) => Bool
 ```
 
 ### WasmI64.**(!=)**
 
 ```grain
-(!=) : (left: WasmI64, right: WasmI64) => Bool
+(!=): (left: WasmI64, right: WasmI64) => Bool
 ```
 
 ### WasmI64.**(<)**
 
 ```grain
-(<) : (left: WasmI64, right: WasmI64) => Bool
+(<): (left: WasmI64, right: WasmI64) => Bool
 ```
 
 ### WasmI64.**ltU**
 
 ```grain
-ltU : (left: WasmI64, right: WasmI64) => Bool
+ltU: (left: WasmI64, right: WasmI64) => Bool
 ```
 
 ### WasmI64.**(<=)**
 
 ```grain
-(<=) : (left: WasmI64, right: WasmI64) => Bool
+(<=): (left: WasmI64, right: WasmI64) => Bool
 ```
 
 ### WasmI64.**leU**
 
 ```grain
-leU : (left: WasmI64, right: WasmI64) => Bool
+leU: (left: WasmI64, right: WasmI64) => Bool
 ```
 
 ### WasmI64.**(>)**
 
 ```grain
-(>) : (left: WasmI64, right: WasmI64) => Bool
+(>): (left: WasmI64, right: WasmI64) => Bool
 ```
 
 ### WasmI64.**gtU**
 
 ```grain
-gtU : (left: WasmI64, right: WasmI64) => Bool
+gtU: (left: WasmI64, right: WasmI64) => Bool
 ```
 
 ### WasmI64.**(>=)**
 
 ```grain
-(>=) : (left: WasmI64, right: WasmI64) => Bool
+(>=): (left: WasmI64, right: WasmI64) => Bool
 ```
 
 ### WasmI64.**geU**
 
 ```grain
-geU : (left: WasmI64, right: WasmI64) => Bool
+geU: (left: WasmI64, right: WasmI64) => Bool
 ```
 
 ### WasmI64.**extendI32S**
 
 ```grain
-extendI32S : (num: WasmI32) => WasmI64
+extendI32S: (num: WasmI32) => WasmI64
 ```
 
 ### WasmI64.**extendI32U**
 
 ```grain
-extendI32U : (num: WasmI32) => WasmI64
+extendI32U: (num: WasmI32) => WasmI64
 ```
 
 ### WasmI64.**truncF32S**
 
 ```grain
-truncF32S : (num: WasmF32) => WasmI64
+truncF32S: (num: WasmF32) => WasmI64
 ```
 
 ### WasmI64.**truncF32U**
 
 ```grain
-truncF32U : (num: WasmF32) => WasmI64
+truncF32U: (num: WasmF32) => WasmI64
 ```
 
 ### WasmI64.**truncF64S**
 
 ```grain
-truncF64S : (num: WasmF64) => WasmI64
+truncF64S: (num: WasmF64) => WasmI64
 ```
 
 ### WasmI64.**truncF64U**
 
 ```grain
-truncF64U : (num: WasmF64) => WasmI64
+truncF64U: (num: WasmF64) => WasmI64
 ```
 
 ### WasmI64.**reinterpretF64**
 
 ```grain
-reinterpretF64 : (num: WasmF64) => WasmI64
+reinterpretF64: (num: WasmF64) => WasmI64
 ```
 
 ### WasmI64.**extendS8**
 
 ```grain
-extendS8 : (num: WasmI64) => WasmI64
+extendS8: (num: WasmI64) => WasmI64
 ```
 
 ### WasmI64.**extendS16**
 
 ```grain
-extendS16 : (num: WasmI64) => WasmI64
+extendS16: (num: WasmI64) => WasmI64
 ```
 
 ### WasmI64.**extendS32**
 
 ```grain
-extendS32 : (num: WasmI64) => WasmI64
+extendS32: (num: WasmI64) => WasmI64
 ```
 

package/runtime/utf8.gr

@@ -0,0 +1,189 @@
+@noPervasives
+/**
+ * The `Utf8` module provides functions for working with UTF-8 encoded strings.
+ */
+module Utf8
+
+primitive (!) = "@not"
+primitive (&&) = "@and"
+primitive throw = "@throw"
+
+from "runtime/unsafe/wasmi32" include WasmI32
+
+/**
+ * An exception thrown when a string is not valid UTF-8.
+ */
+provide exception MalformedUnicode
+
+/**
+ * Determines if the given byte is a leading byte in a UTF-8 sequence.
+ *
+ * @param byte: The byte to check
+ *
+ * @returns `true` if the byte is a leading byte, `false` otherwise
+ */
+@unsafe
+provide let isLeadingByte = byte => {
+  use WasmI32.{ (&), (!=) }
+  (byte & 0xC0n) != 0x80n
+}
+
+/**
+ * Returns the total number of bytes for a UTF-8 code point given the first byte.
+ *
+ * @param byte: The first byte of the UTF-8 code point
+ *
+ * @returns The number of bytes in the UTF-8 code point
+ */
+@unsafe
+provide let utf8ByteCount = byte => {
+  use WasmI32.{ (&), (==) }
+  if ((byte & 0x80n) == 0x00n) {
+    1n
+  } else if ((byte & 0xF0n) == 0xF0n) {
+    4n
+  } else if ((byte & 0xE0n) == 0xE0n) {
+    3n
+  } else {
+    2n
+  }
+}
+
+/**
+ * Returns the number of bytes required to encode the given USV as UTF-8.
+ *
+ * @param usv: The Unicode scalar value
+ *
+ * @returns The number of bytes required to encode the given USV as UTF-8
+ */
+@unsafe
+provide let usvEncodeLength = usv => {
+  use WasmI32.{ (<=) }
+  if (usv <= 0x007Fn) {
+    1n
+  } else if (usv <= 0x07FFn) {
+    2n
+  } else if (usv <= 0xFFFFn) {
+    3n
+  } else {
+    4n
+  }
+}
+
+/**
+ * Returns the Unicode code point of the encoded value at the given pointer.
+ *
+ * @param ptr: The pointer to the encoded value in memory
+ *
+ * @returns The Unicode code point of the encoded value at the given pointer
+ *
+ * @throws MalformedUnicode: if the encoded value is not a valid UTF-8 sequence
+ */
+@unsafe
+provide let getCodePoint = (ptr: WasmI32) => {
+  // Algorithm from https://encoding.spec.whatwg.org/#utf-8-decoder
+  use WasmI32.{ (+), (&), (|), (<<), leU as (<=), geU as (>=), (==) }
+
+  let mut codePoint = 0n
+  let mut bytesSeen = 0n
+  let mut bytesNeeded = 0n
+  let mut lowerBoundary = 0x80n
+  let mut upperBoundary = 0xBFn
+
+  let mut offset = 0n
+
+  while (true) {
+    let byte = WasmI32.load8U(ptr + offset, 0n)
+    offset += 1n
+    if (bytesNeeded == 0n) {
+      if (byte >= 0x00n && byte <= 0x7Fn) {
+        return byte
+      } 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 MalformedUnicode
+      }
+      continue
+    }
+    if (!(lowerBoundary <= byte && byte <= upperBoundary)) {
+      throw MalformedUnicode
+    }
+    lowerBoundary = 0x80n
+    upperBoundary = 0xBFn
+    codePoint = codePoint << 6n | byte & 0x3Fn
+    bytesSeen += 1n
+    if (bytesSeen == bytesNeeded) {
+      return codePoint
+    }
+  }
+  return 0n
+}
+
+/**
+ * Writes the given Unicode code point to the given pointer as encoded UTF-8.
+ *
+ * @param ptr: The pointer to write the UTF-8 character to
+ * @param codePoint: The Unicode code point to write
+ *
+ * @returns The number of bytes written
+ */
+@unsafe
+provide let writeUtf8CodePoint = (ptr, codePoint) => {
+  use WasmI32.{ (+), (-), (&), (|), (>>>), ltU as (<), leU as (<=), (==) }
+  if (codePoint <= 0x007Fn) {
+    // Code points in the ASCII range are written as just one byte with the
+    // leading bit equal to zero (0xxxxxxx). Just store the value as one byte
+    // directly. Note that the value is already guaranteed to start with most
+    // significant bit equal to zero because of the check in the if statement
+    // above, so there's no need to bit-mask it.
+    WasmI32.store8(ptr, codePoint, 0n)
+    1n
+  } else if (codePoint <= 0x07FFn) {
+    // Code points in the range 0x0080..0x07FF are written as two bytes.
+    // The first byte has a three bit prefix of 110, followed by 5 bits of the
+    // codepoint. The second byte has a two bit prefix of 10, followed by 6 bits
+    // of the codepoint.
+    let high = codePoint >>> 6n & 0b000_11111n | 0b110_00000n
+    let low = codePoint & 0b00_111111n | 0b10_000000n
+    WasmI32.store8(ptr, high, 0n)
+    WasmI32.store8(ptr, low, 1n)
+    2n
+  } else if (codePoint <= 0xFFFFn) {
+    // Code points in the range 0x0800..0xFFFF are written as three bytes.
+    // The first byte has a four bit prefix of 1110, followed by 4 bits of the
+    // codepoint. Remaining bytes each have a two bit prefix of 10, followed by
+    // 6 bits of the codepoint.
+    let high = codePoint >>> 12n & 0b0000_1111n | 0b1110_0000n
+    let mid = codePoint >>> 6n & 0b00_111111n | 0b10_000000n
+    let low = codePoint & 0b00_111111n | 0b10_000000n
+    WasmI32.store8(ptr, high, 0n)
+    WasmI32.store8(ptr, mid, 1n)
+    WasmI32.store8(ptr, low, 2n)
+    3n
+  } else {
+    // Code points in the range 0x10000..0x10FFFF are written as four bytes.
+    // The first byte has a five bit prefix of 11110, followed by 3 bits of the
+    // codepoint. Remaining bytes each have a two bit prefix of 10, followed by
+    // 6 bits of the codepoint.
+    let high = codePoint >>> 18n & 0b00000_111n | 0b11110_000n
+    let mid1 = codePoint >>> 12n & 0b00_111111n | 0b10_000000n
+    let mid2 = codePoint >>> 6n & 0b00_111111n | 0b10_000000n
+    let low = codePoint & 0b00_111111n | 0b10_000000n
+    WasmI32.store8(ptr, high, 0n)
+    WasmI32.store8(ptr, mid1, 1n)
+    WasmI32.store8(ptr, mid2, 2n)
+    WasmI32.store8(ptr, low, 3n)
+    4n
+  }
+}

package/runtime/utf8.md

@@ -0,0 +1,117 @@
+---
+title: Utf8
+---
+
+The `Utf8` module provides functions for working with UTF-8 encoded strings.
+
+## Values
+
+Functions and constants included in the Utf8 module.
+
+### Utf8.**isLeadingByte**
+
+```grain
+isLeadingByte: (byte: WasmI32) => Bool
+```
+
+Determines if the given byte is a leading byte in a UTF-8 sequence.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`byte`|`WasmI32`|The byte to check|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the byte is a leading byte, `false` otherwise|
+
+### Utf8.**utf8ByteCount**
+
+```grain
+utf8ByteCount: (byte: WasmI32) => WasmI32
+```
+
+Returns the total number of bytes for a UTF-8 code point given the first byte.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`byte`|`WasmI32`|The first byte of the UTF-8 code point|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`WasmI32`|The number of bytes in the UTF-8 code point|
+
+### Utf8.**usvEncodeLength**
+
+```grain
+usvEncodeLength: (usv: WasmI32) => WasmI32
+```
+
+Returns the number of bytes required to encode the given USV as UTF-8.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`usv`|`WasmI32`|The Unicode scalar value|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`WasmI32`|The number of bytes required to encode the given USV as UTF-8|
+
+### Utf8.**getCodePoint**
+
+```grain
+getCodePoint: (ptr: WasmI32) => WasmI32
+```
+
+Returns the Unicode code point of the encoded value at the given pointer.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`ptr`|`WasmI32`|The pointer to the encoded value in memory|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`WasmI32`|The Unicode code point of the encoded value at the given pointer|
+
+Throws:
+
+`MalformedUnicode`
+
+* if the encoded value is not a valid UTF-8 sequence
+
+### Utf8.**writeUtf8CodePoint**
+
+```grain
+writeUtf8CodePoint: (ptr: WasmI32, codePoint: WasmI32) => WasmI32
+```
+
+Writes the given Unicode code point to the given pointer as encoded UTF-8.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`ptr`|`WasmI32`|The pointer to write the UTF-8 character to|
+|`codePoint`|`WasmI32`|The Unicode code point to write|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`WasmI32`|The number of bytes written|
+

package/runtime/wasi.gr

@@ -4,6 +4,8 @@ from "runtime/unsafe/wasmi32" include WasmI32
 from "exception" include Exception
 from "runtime/string" include String
 use String.{ concat as (++), toString }
+from "runtime/dataStructures" include DataStructures
+use DataStructures.{ untagSimpleNumber }
 
 // env
 provide foreign wasm args_get:
@@ -322,9 +324,9 @@ provide let _ENOTCAPABLE = 76n
 provide exception SystemError(Number)
 
 @disableGC
-provide let stringOfSystemError = code => {
+provide let stringOfSystemError = (code: Number) => {
   use WasmI32.{ (==), (>>) }
-  let n = WasmI32.fromGrain(code) >> 1n
+  let n = untagSimpleNumber(code)
   match (n) {
     n when n == _ESUCCESS =>
       "SystemError: No error occurred. System call completed successfully.",