@grain/stdlib 0.7.0 → 0.7.1

package/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.
  *
@@ -591,8 +626,11 @@ provide let getInt8 = (index, buffer) => {
  * Buffer.setInt8(0, 3s, buf)
  * assert Buffer.getInt8(0, buf) == 3s
  *
+ * @deprecated Use `Bytes` instead of `Buffer` for set operations.
+ *
  * @since v0.4.0
  * @history v0.6.0: `value` argument type changed to `Int8`
+ * @history v0.7.1: Deprecated in favor of `Bytes.setInt8`
  */
 provide let setInt8 = (index, value, buffer) => {
   checkIsIndexInBounds(index, _8BIT_LEN, buffer)
@@ -658,7 +696,10 @@ provide let getUint8 = (index, buffer) => {
  * Buffer.setUint8(4us, buf)
  * assert Buffer.getUint8(0, buf) == 4us
  *
+ * @deprecated Use `Bytes` instead of `Buffer` for set operations.
+ *
  * @since v0.6.0
+ * @history v0.7.1: Deprecated in favor of `Bytes.setUint8`
  */
 provide let setUint8 = (index, value, buffer) => {
   checkIsIndexInBounds(index, _8BIT_LEN, buffer)
@@ -723,8 +764,11 @@ provide let getInt16 = (index, buffer) => {
  * Buffer.setInt16(5, 1S, buf)
  * assert Buffer.getInt16(5, buf) == 1S
  *
+ * @deprecated Use `Bytes` instead of `Buffer` for set operations.
+ *
  * @since v0.4.0
  * @history v0.6.0: `value` argument type changed to `Int16`
+ * @history v0.7.1: Deprecated in favor of `Bytes.setInt16`
  */
 provide let setInt16 = (index, value, buffer) => {
   checkIsIndexInBounds(index, _16BIT_LEN, buffer)
@@ -790,7 +834,10 @@ provide let getUint16 = (index, buffer) => {
  * Buffer.setUint16(0, 1uS, buf)
  * assert Buffer.getUint16(0, buf) == 1uS
  *
+ * @deprecated Use `Bytes` instead of `Buffer` for set operations.
+ *
  * @since v0.6.0
+ * @history v0.7.1: Deprecated in favor of `Bytes.setUint16`
  */
 provide let setUint16 = (index, value, buffer) => {
   checkIsIndexInBounds(index, _16BIT_LEN, buffer)
@@ -854,7 +901,10 @@ provide let getInt32 = (index, buffer) => {
  * Buffer.setInt32(3, 1l, buf)
  * assert Buffer.getInt32(3, buf) == 1l
  *
+ * @deprecated Use `Bytes` instead of `Buffer` for set operations.
+ *
  * @since v0.4.0
+ * @history v0.7.1: Deprecated in favor of `Bytes.setInt32`
  */
 provide let setInt32 = (index, value, buffer) => {
   checkIsIndexInBounds(index, _32BIT_LEN, buffer)
@@ -918,7 +968,10 @@ provide let getUint32 = (index, buffer) => {
  * Buffer.setUint32(0, 1ul, buf)
  * assert Buffer.getUint32(0, buf) == 1ul
  *
+ * @deprecated Use `Bytes` instead of `Buffer` for set operations.
+ *
  * @since v0.6.0
+ * @history v0.7.1: Deprecated in favor of `Bytes.setUint32`
  */
 provide let setUint32 = (index, value, buffer) => {
   checkIsIndexInBounds(index, _32BIT_LEN, buffer)
@@ -982,7 +1035,10 @@ provide let getFloat32 = (index, buffer) => {
  * Buffer.setFloat32(0, 1.0f, buf)
  * assert Buffer.getFloat32(0, buf) == 1.0f
  *
+ * @deprecated Use `Bytes` instead of `Buffer` for set operations.
+ *
  * @since v0.4.0
+ * @history v0.7.1: Deprecated in favor of `Bytes.setFloat32`
  */
 provide let setFloat32 = (index, value, buffer) => {
   checkIsIndexInBounds(index, _32BIT_LEN, buffer)
@@ -1049,7 +1105,10 @@ provide let getInt64 = (index, buffer) => {
  * Buffer.setInt64(0, 1L, buf)
  * assert Buffer.getInt64(0, buf) == 1L
  *
+ * @deprecated Use `Bytes` instead of `Buffer` for set operations.
+ *
  * @since v0.4.0
+ * @history v0.7.1: Deprecated in favor of `Bytes.setInt64
  */
 provide let setInt64 = (index, value, buffer) => {
   checkIsIndexInBounds(index, _64BIT_LEN, buffer)
@@ -1116,7 +1175,10 @@ provide let getUint64 = (index, buffer) => {
  * Buffer.setUint64(0, 1uL, buf)
  * assert Buffer.getUint64(0, buf) == 1uL
  *
+ * @deprecated Use `Bytes` instead of `Buffer` for set operations.
+ *
  * @since v0.6.0
+ * @history v0.7.1: Deprecated in favor of `Bytes.setUint64`
  */
 provide let setUint64 = (index, value, buffer) => {
   checkIsIndexInBounds(index, _64BIT_LEN, buffer)
@@ -1183,7 +1245,10 @@ provide let getFloat64 = (index, buffer) => {
  * Buffer.setFloat64(0, 1.0F, buf)
  * assert Buffer.getFloat64(0, buf) == 1.0F
  *
+ * @deprecated Use `Bytes` instead of `Buffer` for set operations.
+ *
  * @since v0.4.0
+ * @history v0.7.1: Deprecated in favor of `Bytes.setFloat64`
  */
 provide let setFloat64 = (index, value, buffer) => {
   checkIsIndexInBounds(index, _64BIT_LEN, buffer)