feat(stdlib): Add Buffer.getChar (#2262)

Author: spotandjake

compiler/test/stdlib/buffer.test.gr

@@ -303,6 +303,15 @@ let b = Buffer.make(0)
 Buffer.addString(str, b)
 assert Buffer.toBytes(a) == Buffer.toBytes(b)
 
+// Buffer.getChar
+let buff = Buffer.make(32)
+Buffer.addString("ab©✨🍞", buff)
+assert Buffer.getChar(0, buff) == 'a'
+assert Buffer.getChar(1, buff) == 'b'
+assert Buffer.getChar(2, buff) == '©'
+assert Buffer.getChar(4, buff) == '✨'
+assert Buffer.getChar(7, buff) == '🍞'
+
 // 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,41 @@ 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 buffer size
+ * @throws MalformedUnicode: When the bytes at the index are not a valid UTF-8 sequence
+ *
+ * @example
+ * let buf = Buffer.make(32)
+ * Buffer.addString("Hello World 🌾", buf)
+ * assert Buffer.getChar(12, buf) == '🌾'
+ *
+ * @since v0.7.1
+ */
+@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)
+}
+
 /**
  * Appends the bytes of a character to a buffer.
  *

stdlib/buffer.md

@@ -415,6 +415,51 @@ 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 buffer size
+
+`MalformedUnicode`
+
+* When the bytes at the index are not a valid UTF-8 sequence
+
+Examples:
+
+```grain
+let buf = Buffer.make(32)
+Buffer.addString("Hello World 🌾", buf)
+assert Buffer.getChar(12, buf) == '🌾'
+```
+
 ### 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`