feat(stdlib): Add Buffer.setChar and Buffer.getChar

compiler/test/stdlib/buffer.test.gr

@@ -303,6 +303,27 @@ let b = Buffer.make(0)
 Buffer.addString(str, b)
 assert Buffer.toBytes(a) == Buffer.toBytes(b)
 
+// Bytes.getChar
+let bytes = Buffer.make(32)
+Buffer.addString("ab©✨🍞", bytes)
+assert Buffer.getChar(0, bytes) == 'a'
+assert Buffer.getChar(1, bytes) == 'b'
+assert Buffer.getChar(2, bytes) == '©'
+assert Buffer.getChar(4, bytes) == '✨'
+assert Buffer.getChar(7, bytes) == '🍞'
+
+// Bytes.setChar
+let bytes = Buffer.make(16)
+Buffer.addBytes(b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", bytes)
+Buffer.setChar(0, 'a', bytes)
+assert Buffer.getChar(0, bytes) == 'a'
+Buffer.setChar(1, '©', bytes)
+assert Buffer.getChar(1, bytes) == '©'
+Buffer.setChar(3, '✨', bytes)
+assert Buffer.getChar(3, bytes) == '✨'
+Buffer.setChar(7, '🍞', bytes)
+assert Buffer.getChar(7, bytes) == '🍞'
+
 // addChar
 let char = 'a' // 1 byte
 let buf = Buffer.make(0)

stdlib/buffer.gr

@@ -24,7 +24,7 @@ from "char" include Char
 from "runtime/numbers" include Numbers
 use Numbers.{ coerceNumberToWasmI32 }
 from "runtime/utf8" include Utf8
-use Utf8.{ usvEncodeLength }
+use Utf8.{ usvEncodeLength, utf8ByteCount, exception MalformedUnicode }
 from "runtime/unsafe/offsets" include Offsets
 use Offsets.{ _BYTES_LEN_OFFSET, _BYTES_DATA_OFFSET }
 
@@ -376,6 +376,68 @@ provide let addString = (string, buffer) => {
   buffer.len += bytelen
 }
 
+/**
+ * Gets the UTF-8 encoded character at the given byte index.
+ *
+ * @param index: The byte index to access
+ * @param buffer: The buffer to access
+ * @returns A character starting at the given index
+ *
+ * @throws IndexOutOfBounds: When `index` is negative
+ * @throws IndexOutOfBounds: When `index + 1` is greater than the bytes size
+ * @throws MalformedUnicode: When the requested character is not a valid UTF-8 sequence
+ *
+ * @example
+ * let buf = Buffer.make(32)
+ * Buffer.addString("Hello World 🌾", buf)
+ * assert Buffer.getChar(12, buf) == 'H'
+ *
+ * @since v0.7.0
+ */
+@unsafe
+provide let getChar = (index, buffer) => {
+  use WasmI32.{ (+), (&), (+), (==), (>) }
+  checkIsIndexInBounds(index, 1, buffer)
+  // Note: We do a raw check as we need the byte length before reading the full char
+  let bytes = buffer.data
+  let ptr = WasmI32.fromGrain(bytes)
+  let offset = coerceNumberToWasmI32(index)
+  let byte = WasmI32.load8U(ptr + offset, _BYTES_DATA_OFFSET)
+  let charSize = utf8ByteCount(byte)
+  if (offset + charSize > coerceNumberToWasmI32(buffer.len)) {
+    throw MalformedUnicode
+  }
+  ignore(bytes)
+  Bytes.getChar(index, bytes)
+}
+
+/**
+ * UTF-8 encodes a character starting at the given byte index.
+ *
+ * @param index: The byte index to update
+ * @param char: The value to set
+ * @param buffer: The buffer to mutate
+ *
+ * @throws IndexOutOfBounds: When `index` is negative
+ * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
+ * @throws IndexOutOfBounds: When `index + charSize` is greater than the bytes size, `charSize` is the number of bytes in the character ranging from 1 to 4
+ *
+ * @example
+ * let buf = Buffer.make(32)
+ * Buffer.addString("Hello World.", buf)
+ * Buffer.setChar(11, '!', buf)
+ * assert Buffer.toString(buf) == "Hello World!"
+ *
+ * @since v0.7.0
+ */
+@unsafe
+provide let setChar = (index, char, buffer) => {
+  let usv = untagChar(char)
+  let byteCount = tagSimpleNumber(usvEncodeLength(usv))
+  checkIsIndexInBounds(index, byteCount, buffer)
+  Bytes.setChar(index, char, buffer.data)
+}
+
 /**
  * Appends the bytes of a character to a buffer.
  *

stdlib/buffer.md

@@ -415,6 +415,89 @@ Buffer.addString("Hello", buf)
 assert Buffer.toString(buf) == "Hello"
 ```
 
+### Buffer.**getChar**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>next</code></summary>
+No other changes yet.
+</details>
+
+```grain
+getChar : (index: Number, buffer: Buffer) => Char
+```
+
+Gets the UTF-8 encoded character at the given byte index.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`index`|`Number`|The byte index to access|
+|`buffer`|`Buffer`|The buffer to access|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Char`|A character starting at the given index|
+
+Throws:
+
+`IndexOutOfBounds`
+
+* When `index` is negative
+* When `index + 1` is greater than the bytes size
+
+`MalformedUnicode`
+
+* When the requested character is not a valid UTF-8 sequence
+
+Examples:
+
+```grain
+let buf = Buffer.make(32)
+Buffer.addString("Hello World 🌾", buf)
+assert Buffer.getChar(12, buf) == 'H'
+```
+
+### Buffer.**setChar**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>next</code></summary>
+No other changes yet.
+</details>
+
+```grain
+setChar : (index: Number, char: Char, buffer: Buffer) => Void
+```
+
+UTF-8 encodes a character starting at the given byte index.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`index`|`Number`|The byte index to update|
+|`char`|`Char`|The value to set|
+|`buffer`|`Buffer`|The buffer to mutate|
+
+Throws:
+
+`IndexOutOfBounds`
+
+* When `index` is negative
+* When `index` is greater than or equal to the buffer size
+* 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 buf = Buffer.make(32)
+Buffer.addString("Hello World.", buf)
+Buffer.setChar(11, '!', buf)
+assert Buffer.toString(buf) == "Hello World!"
+```
+
 ### Buffer.**addChar**
 
 <details disabled>

stdlib/bytes.gr

@@ -416,6 +416,7 @@ provide let clear = (bytes: Bytes) => {
  * @returns The character that starts at the given index
  *
  * @throws IndexOutOfBounds: When `index` is negative
+ * @throws IndexOutOfBounds: When `index + 1` is greater than the bytes size
  * @throws MalformedUnicode: When the requested character is not a valid UTF-8 sequence
  *
  * @example

stdlib/bytes.md

@@ -462,6 +462,7 @@ Throws:
 `IndexOutOfBounds`
 
 * When `index` is negative
+* When `index + 1` is greater than the bytes size
 
 `MalformedUnicode`