@grain/stdlib 0.6.5 → 0.7.0

package/bytes.md

@@ -33,7 +33,7 @@ No other changes yet.
 </details>
 
 ```grain
-make : (size: Number) => Bytes
+make: (size: Number) => Bytes
 ```
 
 Creates a new byte sequence of the input size.
@@ -68,7 +68,7 @@ No other changes yet.
 </details>
 
 ```grain
-empty : Bytes
+empty: Bytes
 ```
 
 An empty byte sequence.
@@ -87,7 +87,7 @@ No other changes yet.
 </details>
 
 ```grain
-fromString : (string: String) => Bytes
+fromString: (string: String) => Bytes
 ```
 
 Creates a new byte sequence from the input string.
@@ -118,7 +118,7 @@ No other changes yet.
 </details>
 
 ```grain
-toString : (bytes: Bytes) => String
+toString: (bytes: Bytes) => String
 ```
 
 Creates a new string from the input bytes.
@@ -153,7 +153,7 @@ No other changes yet.
 </details>
 
 ```grain
-length : (bytes: Bytes) => Number
+length: (bytes: Bytes) => Number
 ```
 
 Returns the length of a byte sequence.
@@ -188,7 +188,7 @@ No other changes yet.
 </details>
 
 ```grain
-copy : (bytes: Bytes) => Bytes
+copy: (bytes: Bytes) => Bytes
 ```
 
 Creates a new byte sequence that contains the same bytes as the input byte sequence.
@@ -219,7 +219,7 @@ No other changes yet.
 </details>
 
 ```grain
-slice : (start: Number, length: Number, bytes: Bytes) => Bytes
+slice: (start: Number, length: Number, bytes: Bytes) => Bytes
 ```
 
 Returns a copy of a subset of the input byte sequence.
@@ -260,7 +260,7 @@ No other changes yet.
 </details>
 
 ```grain
-resize : (left: Number, right: Number, bytes: Bytes) => Bytes
+resize: (left: Number, right: Number, bytes: Bytes) => Bytes
 ```
 
 Returns a copy of a byte sequence with bytes added or removed from the beginning and/or end.
@@ -301,7 +301,7 @@ No other changes yet.
 </details>
 
 ```grain
-move :
+move:
   (srcIndex: Number, dstIndex: Number, length: Number, src: Bytes, dst: Bytes) =>
    Void
 ```
@@ -342,7 +342,7 @@ No other changes yet.
 </details>
 
 ```grain
-concat : (bytes1: Bytes, bytes2: Bytes) => Bytes
+concat: (bytes1: Bytes, bytes2: Bytes) => Bytes
 ```
 
 Creates a new byte sequence that contains the bytes of both byte sequences.
@@ -383,7 +383,7 @@ assert Bytes.toString(Bytes.concat(helloBytes, worldBytes)) == "Hello World"
 </details>
 
 ```grain
-fill : (value: Uint8, bytes: Bytes) => Void
+fill: (value: Uint8, bytes: Bytes) => Void
 ```
 
 Replaces all bytes in a byte sequnce with the new value provided.
@@ -411,7 +411,7 @@ No other changes yet.
 </details>
 
 ```grain
-clear : (bytes: Bytes) => Void
+clear: (bytes: Bytes) => Void
 ```
 
 Replaces all bytes in a byte sequence with zeroes.
@@ -431,6 +431,85 @@ Bytes.clear(bytes)
 assert bytes == b"\x00\x00\x00\x00\x00"
 ```
 
+### Bytes.**getChar**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.7.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+getChar: (index: Number, bytes: Bytes) => Char
+```
+
+Gets the UTF-8 encoded character at the given byte index.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`index`|`Number`|The byte index to access|
+|`bytes`|`Bytes`|The byte sequence to access|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Char`|The character that starts at the given index|
+
+Throws:
+
+`IndexOutOfBounds`
+
+* When `index` is negative
+
+`MalformedUnicode`
+
+* When the requested character is not a valid UTF-8 sequence
+
+Examples:
+
+```grain
+let bytes = Bytes.fromString("Hello")
+assert Bytes.getChar(0, bytes) == 'H'
+```
+
+### Bytes.**setChar**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.7.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+setChar: (index: Number, value: Char, bytes: Bytes) => Void
+```
+
+UTF-8 encodes a character starting at the given byte index.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`index`|`Number`|The byte index to update|
+|`value`|`Char`|The value to set|
+|`bytes`|`Bytes`|The byte sequence to mutate|
+
+Throws:
+
+`IndexOutOfBounds`
+
+* When `index` is negative
+* When `index + charSize` is greater than the bytes size, `charSize` is the number of bytes in the character ranging from 1 to 4
+
+Examples:
+
+```grain
+let bytes = Bytes.make(1)
+Bytes.setChar(0, 'a', bytes)
+assert Bytes.getChar(0, bytes) == 'a'
+```
+
 ### Bytes.**getInt8**
 
 <details>
@@ -446,7 +525,7 @@ assert bytes == b"\x00\x00\x00\x00\x00"
 </details>
 
 ```grain
-getInt8 : (index: Number, bytes: Bytes) => Int8
+getInt8: (index: Number, bytes: Bytes) => Int8
 ```
 
 Gets a signed 8-bit integer starting at the given byte index.
@@ -494,7 +573,7 @@ assert Bytes.getInt8(0, bytes) == 1s
 </details>
 
 ```grain
-setInt8 : (index: Number, value: Int8, bytes: Bytes) => Void
+setInt8: (index: Number, value: Int8, bytes: Bytes) => Void
 ```
 
 Sets a signed 8-bit integer starting at the given byte index.
@@ -537,7 +616,7 @@ assert Bytes.getInt8(0, bytes) == 2s
 </details>
 
 ```grain
-getUint8 : (index: Number, bytes: Bytes) => Uint8
+getUint8: (index: Number, bytes: Bytes) => Uint8
 ```
 
 Gets an unsigned 8-bit integer starting at the given byte index.
@@ -578,7 +657,7 @@ No other changes yet.
 </details>
 
 ```grain
-setUint8 : (index: Number, value: Uint8, bytes: Bytes) => Void
+setUint8: (index: Number, value: Uint8, bytes: Bytes) => Void
 ```
 
 Sets an unsigned 8-bit integer starting at the given byte index.
@@ -621,7 +700,7 @@ assert Bytes.getUint8(1, bytes) == 2us
 </details>
 
 ```grain
-getInt16 : (index: Number, bytes: Bytes) => Int16
+getInt16: (index: Number, bytes: Bytes) => Int16
 ```
 
 Gets a signed 16-bit integer starting at the given byte index.
@@ -669,7 +748,7 @@ assert Bytes.getInt16(0, bytes) == -2S
 </details>
 
 ```grain
-setInt16 : (index: Number, value: Int16, bytes: Bytes) => Void
+setInt16: (index: Number, value: Int16, bytes: Bytes) => Void
 ```
 
 Sets a signed 16-bit integer starting at the given byte index.
@@ -712,7 +791,7 @@ assert Bytes.getInt16(0, bytes) == -1S
 </details>
 
 ```grain
-getUint16 : (index: Number, bytes: Bytes) => Uint16
+getUint16: (index: Number, bytes: Bytes) => Uint16
 ```
 
 Gets an unsigned 16-bit integer starting at the given byte index.
@@ -753,7 +832,7 @@ No other changes yet.
 </details>
 
 ```grain
-setUint16 : (index: Number, value: Uint16, bytes: Bytes) => Void
+setUint16: (index: Number, value: Uint16, bytes: Bytes) => Void
 ```
 
 Sets an unsigned 16-bit integer starting at the given byte index.
@@ -789,7 +868,7 @@ No other changes yet.
 </details>
 
 ```grain
-getInt32 : (index: Number, bytes: Bytes) => Int32
+getInt32: (index: Number, bytes: Bytes) => Int32
 ```
 
 Gets a signed 32-bit integer starting at the given byte index.
@@ -830,7 +909,7 @@ No other changes yet.
 </details>
 
 ```grain
-setInt32 : (index: Number, value: Int32, bytes: Bytes) => Void
+setInt32: (index: Number, value: Int32, bytes: Bytes) => Void
 ```
 
 Sets a signed 32-bit integer starting at the given byte index.
@@ -866,7 +945,7 @@ No other changes yet.
 </details>
 
 ```grain
-getUint32 : (index: Number, bytes: Bytes) => Uint32
+getUint32: (index: Number, bytes: Bytes) => Uint32
 ```
 
 Gets an unsigned 32-bit integer starting at the given byte index.
@@ -907,7 +986,7 @@ No other changes yet.
 </details>
 
 ```grain
-setUint32 : (index: Number, value: Uint32, bytes: Bytes) => Void
+setUint32: (index: Number, value: Uint32, bytes: Bytes) => Void
 ```
 
 Sets an unsigned 32-bit integer starting at the given byte index.
@@ -943,7 +1022,7 @@ No other changes yet.
 </details>
 
 ```grain
-getFloat32 : (index: Number, bytes: Bytes) => Float32
+getFloat32: (index: Number, bytes: Bytes) => Float32
 ```
 
 Gets a 32-bit float starting at the given byte index.
@@ -984,7 +1063,7 @@ No other changes yet.
 </details>
 
 ```grain
-setFloat32 : (index: Number, value: Float32, bytes: Bytes) => Void
+setFloat32: (index: Number, value: Float32, bytes: Bytes) => Void
 ```
 
 Sets a 32-bit float starting at the given byte index.
@@ -1020,7 +1099,7 @@ No other changes yet.
 </details>
 
 ```grain
-getInt64 : (index: Number, bytes: Bytes) => Int64
+getInt64: (index: Number, bytes: Bytes) => Int64
 ```
 
 Gets a signed 64-bit integer starting at the given byte index.
@@ -1061,7 +1140,7 @@ No other changes yet.
 </details>
 
 ```grain
-setInt64 : (index: Number, value: Int64, bytes: Bytes) => Void
+setInt64: (index: Number, value: Int64, bytes: Bytes) => Void
 ```
 
 Sets a signed 64-bit integer starting at the given byte index.
@@ -1097,7 +1176,7 @@ No other changes yet.
 </details>
 
 ```grain
-getUint64 : (index: Number, bytes: Bytes) => Uint64
+getUint64: (index: Number, bytes: Bytes) => Uint64
 ```
 
 Gets an unsigned 64-bit integer starting at the given byte index.
@@ -1138,7 +1217,7 @@ No other changes yet.
 </details>
 
 ```grain
-setUint64 : (index: Number, value: Uint64, bytes: Bytes) => Void
+setUint64: (index: Number, value: Uint64, bytes: Bytes) => Void
 ```
 
 Sets an unsigned 64-bit integer starting at the given byte index.
@@ -1174,7 +1253,7 @@ No other changes yet.
 </details>
 
 ```grain
-getFloat64 : (index: Number, bytes: Bytes) => Float64
+getFloat64: (index: Number, bytes: Bytes) => Float64
 ```
 
 Gets a 64-bit float starting at the given byte index.
@@ -1215,7 +1294,7 @@ No other changes yet.
 </details>
 
 ```grain
-setFloat64 : (index: Number, value: Float64, bytes: Bytes) => Void
+setFloat64: (index: Number, value: Float64, bytes: Bytes) => Void
 ```
 
 Sets a 64-bit float starting at the given byte index.

package/char.gr

@@ -16,8 +16,8 @@ module Char
 from "runtime/unsafe/wasmi32" include WasmI32
 from "runtime/dataStructures" include DataStructures
 use DataStructures.{ tagSimpleNumber, tagChar, untagChar, allocateString }
-
-exception MalformedUtf8
+from "runtime/utf8" include Utf8
+use Utf8.{ usvEncodeLength, writeUtf8CodePoint }
 
 /**
  * The minimum valid Unicode scalar value.
@@ -44,9 +44,9 @@ provide let max = 0x10FFFF
  * @since v0.3.0
  */
 provide let isValid = charCode => {
-  charCode >= min &&
-    (charCode <= 0xD7FF || charCode >= 0xE000) &&
-    charCode <= max
+  charCode >= min
+    && (charCode <= 0xD7FF || charCode >= 0xE000)
+    && charCode <= max
 }
 
 /**
@@ -164,52 +164,48 @@ provide let pred = char => {
  */
 @unsafe
 provide let toString = (char: Char) => {
-  use WasmI32.{
-    (+),
-    (-),
-    (*),
-    (&),
-    (|),
-    (>>>),
-    ltU as (<),
-    gtU as (>),
-    leU as (<=),
-  }
-
+  use WasmI32.{ (+) }
   let usv = untagChar(char)
+  let byteCount = usvEncodeLength(usv)
+  let string = allocateString(byteCount)
+  writeUtf8CodePoint(string + 8n, usv)
+  WasmI32.toGrain(string): String
+}
 
-  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 (usv <= 0x07FFn) {
-      count = 1n
-      offset = 0xC0n
-    } else if (usv <= 0xFFFFn) {
-      count = 2n
-      offset = 0xE0n
-    } else {
-      count = 3n
-      offset = 0xF0n
-    }
-    let string = allocateString(count + 1n)
-    WasmI32.store8(string, (usv >>> (6n * count)) + offset, 8n)
-
-    let mut n = 0n
-    while (count > 0n) {
-      n += 1n
-      let temp = usv >>> (6n * (count - 1n))
-      WasmI32.store8(string + n, 0x80n | temp & 0x3Fn, 8n)
-      count -= 1n
-    }
+/**
+ * Byte encodings
+ *
+ * @since v0.7.0
+ */
+provide enum Encoding {
+  UTF8,
+  UTF16,
+  UTF32,
+}
 
-    WasmI32.toGrain(string): String
+/**
+ * Returns the byte count of a character if encoded in the given encoding.
+ *
+ * @param encoding: The encoding to check
+ * @param char: The character
+ * @returns The byte count of the character in the given encoding
+ *
+ * @example Char.encodedLength(Char.UTF8, 'a') == 1
+ * @example Char.encodedLength(Char.UTF8, '🌾') == 4
+ * @example Char.encodedLength(Char.UTF16, '©') == 1
+ *
+ * @since v0.7.0
+ */
+@unsafe
+provide let encodedLength = (encoding, char: Char) => {
+  let usv = untagChar(char)
+  let utf8ByteCount = usvEncodeLength(usv)
+  let utf8ByteCount = tagSimpleNumber(utf8ByteCount)
+  match (encoding) {
+    UTF32 => 4,
+    UTF16 => if (utf8ByteCount == 4) 2 else 1,
+    UTF8 => utf8ByteCount,
   }
-
-  result
 }
 
 /**
@@ -315,64 +311,170 @@ provide let (>=) = (x: Char, y: Char) => {
 }
 
 /**
- * Checks if the character is an ASCII digit.
+ * Utilities for working with ASCII characters.
  *
- * @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')
+ * @example Char.Ascii.isAscii('1')
  *
- * @since v0.6.0
+ * @since v0.7.0
  */
-provide let isAsciiDigit = char => char >= '0' && char <= '9'
+provide module Ascii {
+  /**
+   * The minimum valid ASCII character code.
+   *
+   * @since v0.7.0
+   */
+  provide let min = 0x00
 
-/**
- * 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'
+  /**
+   * The maximum valid ASCII character code.
+   *
+   * @since v0.7.0
+   */
+  provide let max = 0x7F
 
-/**
- * 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
+  /**
+   * Checks if the character is a valid ASCII character.
+   *
+   * @param char: The character to check
+   * @returns `true` if the character is an ASCII character or `false` otherwise
+   *
+   * @example assert Char.Ascii.isValid('1')
+   * @example assert Char.Ascii.isValid('a')
+   * @example assert !Char.Ascii.isValid('🌾')
+   *
+   * @since v0.7.0
+   */
+  provide let isValid = char => char <= '\u{007F}'
+
+  /**
+   * 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.Ascii.isDigit('1')
+   * @example assert !Char.Ascii.isDigit('a')
+   *
+   * @since v0.7.0
+   * @history v0.6.0: Originally `Char.isAsciiDigit`
+   */
+  provide let isDigit = 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.Ascii.isAlpha('a')
+   * @example assert !Char.Ascii.isAlpha('1')
+   *
+   * @since v0.7.0
+   * @history v0.6.0: Originally `Char.isAsciiAlpha`
+   */
+  provide let isAlpha = char =>
+    char >= 'a' && char <= 'z' || char >= 'A' && char <= 'Z'
+
+  /**
+  * Checks if the character is an ASCII control character.
+  *
+  * @param char: The character to check
+  * @returns `true` if the character is an ASCII control character or `false` otherwise
+  *
+  * @example assert Char.Ascii.isControl('\t')
+  * @example assert Char.Ascii.isControl('\n')
+  * @example assert !Char.Ascii.isControl('1')
+  * @example assert !Char.Ascii.isControl('a')
+  *
+  * @since v0.7.0
+  */
+  provide let isControl = char => char <= '\u{001F}' || char == '\u{007F}'
+
+  /**
+   * Checks if the character is an ASCII whitespace character.
+   *
+   * @param char: The character to check
+   * @returns `true` if the character is an ASCII whitespace character or `false` otherwise
+   *
+   * @example assert Char.isWhitespace('\t')
+   * @example assert Char.isWhitespace('\n')
+   * @example assert !Char.isWhitespace('1')
+   * @example assert !Char.isWhitespace('a')
+   *
+   * @since v0.7.0
+   */
+  provide let isWhitespace = char => {
+    match (char) {
+      '\t' | '\n' | '\x0C' | '\r' | ' ' => true,
+      _ => false,
+    }
   }
-}
 
-/**
- * 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
+  /**
+   * Checks if the character is an ASCII punctuation character.
+   *
+   * @param char: The character to check
+   * @returns `true` if the character is an ASCII punctuation character or `false` otherwise
+   *
+   * @example assert Char.Ascii.isPunctuation('!')
+   * @example assert !Char.Ascii.isPunctuation('1')
+   *
+   * @since v0.7.0
+   */
+  provide let isPunctuation = char =>
+    char >= '!' && char <= '/'
+      || char >= ':' && char <= '@'
+      || char >= '[' && char <= '`'
+      || char >= '{' && char <= '~'
+
+  /**
+   * Checks if the character is an ASCII graphic character.
+   *
+   * @param char: The character to check
+   * @returns `true` if the character is an ASCII graphic character or `false` otherwise
+   *
+   * @example assert Char.Ascii.isGraphic('!')
+   * @example assert !Char.Ascii.isGraphic('\t')
+   *
+   * @since v0.7.0
+   */
+  provide let isGraphic = char => char >= '!' && char <= '~'
+
+  /**
+   * 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.Ascii.toLowercase('B') == 'b'
+   *
+   * @since v0.7.0
+   * @history v0.6.0: Originally `Char.toAsciiLowercase`
+   */
+  provide let toLowercase = 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.Ascii.toUppercase('b') == 'B'
+   *
+   * @since v0.7.0
+   * @history v0.6.0: Originally `Char.toAsciiUppercase`
+   */
+  provide let toUppercase = char => {
+    if (char >= 'a' && char <= 'z') {
+      fromCode(code(char) - 0x20)
+    } else {
+      char
+    }
   }
 }