@creejs/commons-lang 2.1.8 → 2.1.10

package/dist/umd/index.dev.js

@@ -155,7 +155,8 @@
     isFloat64Array,
     isBigInt64Array,
     isBigUint64Array,
-    isTypedArray
+    isTypedArray,
+    isArrayBuffer
   };
   /**
      * Checks if the given value is an array.
@@ -485,7 +486,7 @@
   function isUint32Array (value) {
     return value instanceof Uint32Array
   }
-  // export function isFloat16Array (value) {
+  // function isFloat16Array (value) {
   //   return value instanceof Float16Array
   // }
   /**
@@ -521,6 +522,15 @@
     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
@@ -559,7 +569,8 @@
     assertFloat64Array,
     assertBigInt64Array,
     assertBigUint64Array,
-    assertTypedArray
+    assertTypedArray,
+    assertArrayBuffer
   };
   /**
      * if value is not Array, throw error
@@ -913,6 +924,18 @@
     }
   }
 
+  /**
+   * 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
@@ -1949,6 +1972,130 @@
     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.
@@ -1968,9 +2115,11 @@
     ClassProxyUtils,
     InstanceProxyUtils,
     ReflectUtils,
-    TypedArrayUtils
+    TypedArrayUtils,
+    ArrayBufferUtils
   };
 
+  exports.ArrayBufferUtils = ArrayBufferUtils;
   exports.ClassProxyUtils = ClassProxyUtils;
   exports.Exec = ExecUtils;
   exports.ExecUtils = ExecUtils;