@creejs/commons-lang 2.1.8 → 2.1.10

package/dist/cjs/index-dev.cjs

@@ -153,7 +153,8 @@ var TypeUtils = {
   isFloat64Array,
   isBigInt64Array,
   isBigUint64Array,
-  isTypedArray
+  isTypedArray,
+  isArrayBuffer
 };
 /**
    * Checks if the given value is an array.
@@ -483,7 +484,7 @@ function isInt32Array (value) {
 function isUint32Array (value) {
   return value instanceof Uint32Array
 }
-// export function isFloat16Array (value) {
+// function isFloat16Array (value) {
 //   return value instanceof Float16Array
 // }
 /**
@@ -519,6 +520,15 @@ function isBigUint64Array (value) {
   return value instanceof BigUint64Array
 }
 
+/**
+ * Checks if the given value is an ArrayBuffer.
+ * @param {*} value - The value to check.
+ * @returns {boolean} True if the value is an ArrayBuffer, false otherwise.
+ */
+function isArrayBuffer (value) {
+  return value instanceof ArrayBuffer
+}
+
 // 3rd
 // internal
 // owned
@@ -557,7 +567,8 @@ var TypeAssert = {
   assertFloat64Array,
   assertBigInt64Array,
   assertBigUint64Array,
-  assertTypedArray
+  assertTypedArray,
+  assertArrayBuffer
 };
 /**
    * if value is not Array, throw error
@@ -911,6 +922,18 @@ function assertBigUint64Array (value, paramName) {
   }
 }
 
+/**
+ * Asserts that the given value is an ArrayBuffer.
+ * @param {*} value - The value to check.
+ * @param {string} [paramName] - Optional parameter name for error message.
+ * @throws {Error} Throws an error if the value is not an ArrayBuffer.
+ */
+function assertArrayBuffer (value, paramName) {
+  if (!isArrayBuffer(value)) {
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not ArrayBuffer`)
+  }
+}
+
 // 3rd
 // internal
 // owned
@@ -1947,6 +1970,130 @@ function equals (src, target) {
   return true
 }
 
+var ArrayBufferUtils = {
+  readString,
+  writeString,
+  writeArrayBuffer
+};
+
+// module vars
+const textDecoder = new TextDecoder();
+const textEncoder = new TextEncoder();
+/**
+ * Reads a string from an ArrayBuffer at the specified offset and length.
+ * 1. if offset >= buffer.byteLength, return undefined
+ * 2. if length is not specified, read all bytes from offset to the end of buffer
+ * 3. if length is specified
+ *   * if offset + length >= buffer.byteLength, return a Uint8Array from offset to the end of buffer
+ *   * if offset + length < buffer.byteLength, return a Uint8Array from offset to offset + length
+ * @param {ArrayBuffer} buffer - The buffer to read from.
+ * @param {number} [offset=0] - The offset in bytes to start reading from.
+ * @param {number} [length] - The number of bytes to read.
+ * @returns {string|undefined} The decoded string.
+ */
+function readString (buffer, offset = 0, length) {
+  assertArrayBuffer(buffer);
+  assertNotNegative(offset);
+  if (offset >= buffer.byteLength) {
+    return undefined
+  }
+  let uint8Array = null;
+  if (length != null) {
+    assertPositive(length);
+    if (offset + length >= buffer.byteLength) {
+      uint8Array = new Uint8Array(buffer, offset);
+    } else {
+      uint8Array = new Uint8Array(buffer, offset, length);
+    }
+  } else {
+    uint8Array = new Uint8Array(buffer, offset);
+  }
+
+  // An ArrayBuffer, a TypedArray, or a DataView object containing the encoded text to decode.
+  return textDecoder.decode(uint8Array)
+}
+
+/**
+ * Writes a string to an ArrayBuffer at the specified offset.
+ * @param {ArrayBuffer} buffer - The buffer to write to
+ * @param {string} str - The string to write
+ * @param {number} [offset=0] - The offset in bytes to start writing
+ * @returns {void}
+ */
+function writeString (buffer, str, offset = 0) {
+  assertArrayBuffer(buffer, 'buffer');
+  assertString(str, 'str');
+  assertNotNegative(offset, 'offset');
+  const uint8Array = textEncoder.encode(str);
+  const strByteLength = uint8Array.byteLength;
+  if (offset + strByteLength > buffer.byteLength) {
+    throw new Error(`offset + str.byteLength > buffer.byteLength:${offset + strByteLength} > ${buffer.byteLength}`)
+  }
+  const dataView = new Uint8Array(buffer, offset, uint8Array.byteLength);
+  dataView.set(uint8Array);
+}
+
+/**
+ * Writes an ArrayBuffer into a target ArrayBuffer at the specified offset.
+ * 1. targetOffset
+ *    * Negative index counts back from the end of the buffer
+ *      * if -target.length <= targetOffset < 0, start + target.length is used.
+ *    * If targetOffset < -buffer.length or targetOffset is omitted, 0 is used.
+ *    * If targetOffset >= buffer.length, throw "Out of target Bounds" Error
+ * 2. dataOffset
+ *    * Negative index counts back from the end of the buffer
+ *      * if -dataArrayBuffer.length <= dataOffset < 0, start + dataArrayBuffer.length is used.
+ *    * If dataOffset < -buffer.length or dataOffset is omitted, 0 is used.
+ *    * If dataOffset >= buffer.length, throw "Out of data Bounds" Error
+ * 3. dataLength
+ *    * if dataLength <= 0, throw "Not Positive" Error
+ *    * if dataLength is omitted, read all bytes from dataOffset to the end of dataArrayBuffer
+ *    * if dataLength + dataOffset > dataArrayBuffer.length, read all bytes from dataOffset to the end of dataArrayBuffer
+ * @param {ArrayBuffer} target - The target buffer to write into.
+ * @param {ArrayBuffer} dataArrayBuffer - The data ArrayBuffer to write.
+ * @param {number} [targetOffset=0] - Zero-based index at which to start write.
+ * @param {number} [dataOffset=0] - The offset in the dataArrayBuffer
+ * @param {number} [dataLength] - how many bytes extract from dataArrayBuffer
+ * @returns {void}
+ */
+function writeArrayBuffer (target, dataArrayBuffer, targetOffset = 0, dataOffset = 0, dataLength) {
+  assertArrayBuffer(target);
+  assertArrayBuffer(dataArrayBuffer);
+  assertNumber(targetOffset);
+  assertNumber(dataOffset);
+  const targetLength = target.byteLength;
+  if (targetOffset < -1 * targetLength) { // targetOffset < -buffer.length
+    targetOffset = 0;
+  } else if (targetOffset < 0) { // -target.length <= targetOffset < 0
+    targetOffset += targetLength;
+  } else if (targetOffset >= targetLength) {
+    throw new Error(`Out of target Bounds: targetOffset(${targetOffset}) >= targetLength(${targetLength})`)
+  }
+
+  const dataArrayBufferLength = dataArrayBuffer.byteLength;
+  if (dataOffset < -1 * dataArrayBufferLength) {
+    dataOffset = 0;
+  } else if (dataOffset < 0) {
+    dataOffset += dataArrayBufferLength;
+  } else if (dataOffset >= dataArrayBufferLength) {
+    throw new Error(`Out of data Bounds: dataOffset(${dataOffset}) >= dataArrayBufferLength(${dataArrayBufferLength})`)
+  }
+
+  if (dataLength != null) {
+    assertPositive(dataLength, 'dataLength');
+    // offset+dataLengt out of dataArrayBuffer bounds, treat as no limitation, read to end
+    if (dataOffset + dataLength > dataArrayBufferLength) {
+      dataLength = undefined;
+    }
+  }
+  const dataView = new Uint8Array(dataArrayBuffer, dataOffset, dataLength);
+  if (dataView.byteLength > targetLength - targetOffset) {
+    throw new Error(`Out of target Bounds: from targetOffset(${targetOffset}), No Space to store dataArrayBuffer(${dataOffset}, ${dataLength ?? 'NoLimit'})`)
+  }
+  const targetView = new Uint8Array(target);
+  targetView.set(dataView, targetOffset);
+}
+
 /**
  * @module Lang
  * @description Core language utilities for type checking, string manipulation, and common operations.
@@ -1966,9 +2113,11 @@ var index = {
   ClassProxyUtils,
   InstanceProxyUtils,
   ReflectUtils,
-  TypedArrayUtils
+  TypedArrayUtils,
+  ArrayBufferUtils
 };
 
+exports.ArrayBufferUtils = ArrayBufferUtils;
 exports.ClassProxyUtils = ClassProxyUtils;
 exports.Exec = ExecUtils;
 exports.ExecUtils = ExecUtils;