@creejs/commons-lang 2.1.9 → 2.1.10

package/dist/cjs/index-dev.cjs

@@ -1972,7 +1972,8 @@ function equals (src, target) {
 
 var ArrayBufferUtils = {
   readString,
-  writeString
+  writeString,
+  writeArrayBuffer
 };
 
 // module vars
@@ -2032,6 +2033,67 @@ function writeString (buffer, str, offset = 0) {
   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.