X-Git-Url: https://git.ladys.computer/Pisces/blobdiff_plain/32ed653b76c0cb255c7ba8f0152740e39d951846..HEAD:/binary.js

diff --git a/binary.js b/binary.js
index f6d8cab..c149daf 100644
--- a/binary.js
+++ b/binary.js
@@ -24,6 +24,7 @@ const View = DataView;
 const TypedArray = Object.getPrototypeOf(Uint8Array);
 const { prototype: arrayPrototype } = Array;
 const { prototype: bufferPrototype } = Buffer;
+const { prototype: sharedBufferPrototype } = SharedArrayBuffer;
 const { prototype: rePrototype } = RegExp;
 const { prototype: typedArrayPrototype } = TypedArray;
 const { prototype: viewPrototype } = View;
@@ -56,16 +57,44 @@ const binaryCodeUnitIterablePrototype = {
 };
 
 const { exec: reExec } = rePrototype;
+const { slice: bufferSlice } = bufferPrototype;
 const getBufferByteLength =
   Object.getOwnPropertyDescriptor(bufferPrototype, "byteLength").get;
+const { slice: sharedBufferSlice } = sharedBufferPrototype;
+const getSharedBufferByteLength =
+  Object.getOwnPropertyDescriptor(sharedBufferPrototype, "byteLength")
+    .get;
 const getTypedArrayBuffer =
   Object.getOwnPropertyDescriptor(typedArrayPrototype, "buffer").get;
+const getTypedArrayByteLength =
+  Object.getOwnPropertyDescriptor(typedArrayPrototype, "byteLength")
+    .get;
+const getTypedArrayByteOffset =
+  Object.getOwnPropertyDescriptor(typedArrayPrototype, "byteOffset")
+    .get;
 const getViewBuffer =
   Object.getOwnPropertyDescriptor(viewPrototype, "buffer").get;
+const getViewByteLength =
+  Object.getOwnPropertyDescriptor(viewPrototype, "byteLength").get;
+const getViewByteOffset =
+  Object.getOwnPropertyDescriptor(viewPrototype, "byteOffset").get;
 const {
+  getBigInt64: viewGetInt64,
+  getBigUint64: viewGetUint64,
+  getFloat32: viewGetFloat32,
+  getFloat64: viewGetFloat64,
+  getInt8: viewGetInt8,
+  getInt16: viewGetInt16,
+  getInt32: viewGetInt32,
   getUint8: viewGetUint8,
+  getUint16: viewGetUint16,
+  getUint32: viewGetUint32,
+  setFloat32: viewSetFloat32,
+  setFloat64: viewSetFloat64,
   setUint8: viewSetUint8,
   setUint16: viewSetUint16,
+  setUint32: viewSetUint32,
+  setBigUint64: viewSetUint64,
 } = viewPrototype;
 
 /**
@@ -557,6 +586,26 @@ const sourceFromArgs = ($, $s) =>
     "",
   );
 
+/**
+ * Returns a slice of the provided value according to the algorithm of
+ * `ArrayBuffer::slice` (or `SharedArrayBuffer::slice`).
+ *
+ * ☡ This function throws if the provided value is not an array buffer.
+ */
+export const arrayBufferSlice = ($, start, end, ...args) =>
+  call(
+    isSharedArrayBuffer($) ? sharedBufferSlice : bufferSlice,
+    $,
+    [
+      start,
+      end,
+      ...objectCreate(
+        argumentIterablePrototype,
+        { args: { value: args } },
+      ),
+    ],
+  );
+
 /**
  * Returns an ArrayBuffer generated from the provided base16 string.
  *
@@ -646,6 +695,514 @@ export const filenameSafeBase64Binary = ($, ...$s) =>
 export const filenameSafeBase64String = ($, ...$s) =>
   encodeBase64(bufferFromArgs($, $s), true);
 
+export const {
+  /**
+   * Returns the signed 8‐bit integral value in the provided array
+   * buffer or array buffer view at the provided byte offset.
+   *
+   * ※ The retrieved value will be big·endian unless a third argument
+   * is specified and truthy.
+   *
+   * ※ This is similar to `DataView::getInt8`, but works on all array
+   * buffers and array buffer views and returns a big·int.
+   *
+   * ☡ This function throws if the first argument is not an array
+   * buffer, data view, or typed array.
+   */
+  get8BitSignedIntegralItem,
+
+  /**
+   * Returns the unsigned 8‐bit integral value in the provided array
+   * buffer or array buffer view at the provided byte offset.
+   *
+   * ※ The retrieved value will be big·endian unless a third argument
+   * is specified and truthy.
+   *
+   * ※ This is similar to `DataView::getUint8`, but works on all array
+   * buffers and array buffer views and returns a big·int.
+   *
+   * ☡ This function throws if the first argument is not an array
+   * buffer, data view, or typed array.
+   */
+  get8BitUnsignedIntegralItem,
+
+  /**
+   * Returns the signed 16‐bit integral value in the provided array
+   * buffer or array buffer view at the provided byte offset.
+   *
+   * ※ The retrieved value will be big·endian unless a third argument
+   * is specified and truthy.
+   *
+   * ※ This is similar to `DataView::getInt16`, but works on all array
+   * buffers and array buffer views and returns a big·int.
+   *
+   * ☡ This function throws if the first argument is not an array
+   * buffer, data view, or typed array.
+   */
+  get16BitSignedIntegralItem,
+
+  /**
+   * Returns the unsigned 16‐bit integral value in the provided array
+   * buffer or array buffer view at the provided byte offset.
+   *
+   * ※ The retrieved value will be big·endian unless a third argument
+   * is specified and truthy.
+   *
+   * ※ This is similar to `DataView::getUint16`, but works on all
+   * array buffers and array buffer views and returns a big·int.
+   *
+   * ☡ This function throws if the first argument is not an array
+   * buffer, data view, or typed array.
+   */
+  get16BitUnsignedIntegralItem,
+
+  /**
+   * Returns the 32‐bit floating point value in the provided array
+   * buffer or array buffer view at the provided byte offset.
+   *
+   * ※ The retrieved value will be big·endian unless a third argument
+   * is specified and truthy.
+   *
+   * ※ This is similar to `DataView::getFloat32`, but works on all
+   * array buffers and array buffer views.
+   *
+   * ☡ This function throws if the first argument is not an array
+   * buffer, data view, or typed array.
+   */
+  get32BitFloatingPointItem,
+
+  /**
+   * Returns the signed 32‐bit integral value in the provided array
+   * buffer or array buffer view at the provided byte offset.
+   *
+   * ※ The retrieved value will be big·endian unless a third argument
+   * is specified and truthy.
+   *
+   * ※ This is similar to `DataView::getInt32`, but works on all array
+   * buffers and array buffer views and returns a big·int.
+   *
+   * ☡ This function throws if the first argument is not an array
+   * buffer, data view, or typed array.
+   */
+  get32BitSignedIntegralItem,
+
+  /**
+   * Returns the unsigned 32‐bit integral value in the provided array
+   * buffer or array buffer view at the provided byte offset.
+   *
+   * ※ The retrieved value will be big·endian unless a third argument
+   * is specified and truthy.
+   *
+   * ※ This is similar to `DataView::getUint32`, but works on all
+   * array buffers and array buffer views and returns a big·int.
+   *
+   * ☡ This function throws if the first argument is not an array
+   * buffer, data view, or typed array.
+   */
+  get32BitUnsignedIntegralItem,
+
+  /**
+   * Returns the 64‐bit floating point value in the provided array
+   * buffer or array buffer view at the provided byte offset.
+   *
+   * ※ The retrieved value will be big·endian unless a third argument
+   * is specified and truthy.
+   *
+   * ※ This is similar to `DataView::getFloat64`, but works on all
+   * array buffers and array buffer views.
+   *
+   * ☡ This function throws if the first argument is not an array
+   * buffer, data view, or typed array.
+   */
+  get64BitFloatingPointItem,
+
+  /**
+   * Returns the signed 64‐bit integral value in the provided array
+   * buffer or array buffer view at the provided byte offset.
+   *
+   * ※ The retrieved value will be big·endian unless a third argument
+   * is specified and truthy.
+   *
+   * ※ This is similar to `DataView::getBigInt64`, but works on all
+   * array buffers and array buffer views.
+   *
+   * ☡ This function throws if the first argument is not an array
+   * buffer, data view, or typed array.
+   */
+  get64BitSignedIntegralItem,
+
+  /**
+   * Returns the unsigned 64‐bit integral value in the provided array
+   * buffer or array buffer view at the provided byte offset.
+   *
+   * ※ The retrieved value will be big·endian unless a third argument
+   * is specified and truthy.
+   *
+   * ※ This is similar to `DataView::getBigUint64`, but works on all
+   * array buffers and array buffer views.
+   *
+   * ☡ This function throws if the first argument is not an array
+   * buffer, data view, or typed array.
+   */
+  get64BitUnsignedIntegralItem,
+
+  /**
+   * Sets the 8‐bit integral value in the provided array buffer or
+   * array buffer view at the provided byte offset to the provided
+   * value.
+   *
+   * ※ The value will be set as big·endian unless a fourth argument is
+   * specified and truthy.
+   *
+   * ※ This is similar to `DataView::setInt8`, but works on all array
+   * buffers and array buffer views and accepts both numeric and
+   * big·int values.
+   *
+   * ※ It doesn’t matter whether the provided value is signed or
+   * unsigned, as the algorithm will cast one to the other.
+   *
+   * ☡ This function throws if the first argument is not an array
+   * buffer, data view, or typed array.
+   */
+  set8BitIntegralItem,
+
+  /**
+   * Sets the 16‐bit integral value in the provided array buffer or
+   * array buffer view at the provided byte offset to the provided
+   * value.
+   *
+   * ※ The value will be set as big·endian unless a fourth argument is
+   * specified and truthy.
+   *
+   * ※ This is similar to `DataView::setInt16`, but works on all array
+   * buffers and array buffer views and accepts both numeric and
+   * big·int values.
+   *
+   * ※ It doesn’t matter whether the provided value is signed or
+   * unsigned, as the algorithm will cast one to the other.
+   *
+   * ☡ This function throws if the first argument is not an array
+   * buffer, data view, or typed array.
+   */
+  set16BitIntegralItem,
+
+  /**
+   * Sets the 32‐bit floating point value in the provided array buffer
+   * or array buffer view at the provided byte offset to the provided
+   * value.
+   *
+   * ※ The value will be set as big·endian unless a fourth argument is
+   * specified and truthy.
+   *
+   * ※ This is similar to `DataView::setFloat32`, but works on all
+   * array buffers and array buffer views.
+   *
+   * ☡ This function throws if the first argument is not an array
+   * buffer, data view, or typed array.
+   */
+  set32BitFloatingPointItem,
+
+  /**
+   * Sets the 32‐bit integral value in the provided array buffer or
+   * array buffer view at the provided byte offset to the provided
+   * value.
+   *
+   * ※ The value will be set as big·endian unless a fourth argument is
+   * specified and truthy.
+   *
+   * ※ This is similar to `DataView::setInt32`, but works on all array
+   * buffers and array buffer views and accepts both numeric and
+   * big·int values.
+   *
+   * ※ It doesn’t matter whether the provided value is signed or
+   * unsigned, as the algorithm will cast one to the other.
+   *
+   * ☡ This function throws if the first argument is not an array
+   * buffer, data view, or typed array.
+   */
+  set32BitIntegralItem,
+
+  /**
+   * Sets the 64‐bit floating point value in the provided array buffer
+   * or array buffer view at the provided byte offset to the provided
+   * value.
+   *
+   * ※ The value will be set as big·endian unless a fourth argument is
+   * specified and truthy.
+   *
+   * ※ This is similar to `DataView::setFloat64`, but works on all
+   * array buffers and array buffer views.
+   *
+   * ☡ This function throws if the first argument is not an array
+   * buffer, data view, or typed array.
+   */
+  set64BitFloatingPointItem,
+
+  /**
+   * Sets the 64‐bit integral value in the provided array buffer or
+   * array buffer view at the provided byte offset to the provided
+   * value.
+   *
+   * ※ The value will be set as big·endian unless a fourth argument is
+   * specified and truthy.
+   *
+   * ※ This is similar to `DataView::setInt32`, but works on all array
+   * buffers and array buffer views.
+   *
+   * ※ It doesn’t matter whether the provided value is signed or
+   * unsigned, as the algorithm will cast one to the other.
+   *
+   * ☡ This function throws if the first argument is not an array
+   * buffer, data view, or typed array, or if the third argument is not
+   * a big·int.
+   */
+  set64BitIntegralItem,
+} = (() => {
+  const makeBigInt = BigInt;
+  const { asUintN } = BigInt;
+  const makeNumber = Number;
+
+  const viewMap = new WeakMap();
+  const view = ($) => {
+    const buffer = toArrayBuffer($);
+    if (viewMap.has(buffer)) {
+      // A view has already been allocated for this buffer; use it.
+      return viewMap.get(buffer);
+    } else {
+      // No view has been created for this buffer yet.
+      const result = new View(buffer);
+      viewMap.set(buffer, result);
+      return result;
+    }
+  };
+
+  return {
+    get8BitSignedIntegralItem: ($, byteOffset, ...args) =>
+      makeBigInt(
+        call(viewGetInt8, view($), [
+          getByteOffset($) + byteOffset,
+          ...objectCreate(
+            argumentIterablePrototype,
+            { args: { value: args } },
+          ),
+        ]),
+      ),
+    get8BitUnsignedIntegralItem: ($, byteOffset, ...args) =>
+      makeBigInt(
+        call(viewGetUint8, view($), [
+          getByteOffset($) + byteOffset,
+          ...objectCreate(
+            argumentIterablePrototype,
+            { args: { value: args } },
+          ),
+        ]),
+      ),
+    get16BitSignedIntegralItem: ($, byteOffset, ...args) =>
+      makeBigInt(
+        call(viewGetInt16, view($), [
+          getByteOffset($) + byteOffset,
+          ...objectCreate(
+            argumentIterablePrototype,
+            { args: { value: args } },
+          ),
+        ]),
+      ),
+    get16BitUnsignedIntegralItem: ($, byteOffset, ...args) =>
+      makeBigInt(
+        call(viewGetUint16, view($), [
+          getByteOffset($) + byteOffset,
+          ...objectCreate(
+            argumentIterablePrototype,
+            { args: { value: args } },
+          ),
+        ]),
+      ),
+    get32BitFloatingPointItem: ($, byteOffset, ...args) =>
+      call(viewGetFloat32, view($), [
+        getByteOffset($) + byteOffset,
+        ...objectCreate(
+          argumentIterablePrototype,
+          { args: { value: args } },
+        ),
+      ]),
+    get32BitSignedIntegralItem: ($, byteOffset, ...args) =>
+      makeBigInt(
+        call(viewGetInt32, view($), [
+          getByteOffset($) + byteOffset,
+          ...objectCreate(
+            argumentIterablePrototype,
+            { args: { value: args } },
+          ),
+        ]),
+      ),
+    get32BitUnsignedIntegralItem: ($, byteOffset, ...args) =>
+      makeBigInt(
+        call(viewGetUint32, view($), [
+          getByteOffset($) + byteOffset,
+          ...objectCreate(
+            argumentIterablePrototype,
+            { args: { value: args } },
+          ),
+        ]),
+      ),
+    get64BitFloatingPointItem: ($, byteOffset, ...args) =>
+      call(viewGetFloat64, view($), [
+        getByteOffset($) + byteOffset,
+        ...objectCreate(
+          argumentIterablePrototype,
+          { args: { value: args } },
+        ),
+      ]),
+    get64BitSignedIntegralItem: ($, byteOffset, ...args) =>
+      call(viewGetInt64, view($), [
+        getByteOffset($) + byteOffset,
+        ...objectCreate(
+          argumentIterablePrototype,
+          { args: { value: args } },
+        ),
+      ]),
+    get64BitUnsignedIntegralItem: ($, byteOffset, ...args) =>
+      call(viewGetUint64, view($), [
+        getByteOffset($) + byteOffset,
+        ...objectCreate(
+          argumentIterablePrototype,
+          { args: { value: args } },
+        ),
+      ]),
+    set8BitIntegralItem: ($, byteOffset, value, ...args) =>
+      call(viewSetUint8, view($), [
+        getByteOffset($) + byteOffset,
+        makeNumber(value),
+        ...objectCreate(
+          argumentIterablePrototype,
+          { args: { value: args } },
+        ),
+      ]),
+    set16BitIntegralItem: ($, byteOffset, value, ...args) =>
+      call(viewSetUint16, view($), [
+        getByteOffset($) + byteOffset,
+        makeNumber(value),
+        ...objectCreate(
+          argumentIterablePrototype,
+          { args: { value: args } },
+        ),
+      ]),
+    set32BitFloatingPointItem: ($, byteOffset, value, ...args) =>
+      call(viewSetFloat32, view($), [
+        getByteOffset($) + byteOffset,
+        value,
+        ...objectCreate(
+          argumentIterablePrototype,
+          { args: { value: args } },
+        ),
+      ]),
+    set32BitIntegralItem: ($, byteOffset, value, ...args) =>
+      call(viewSetUint32, view($), [
+        getByteOffset($) + byteOffset,
+        makeNumber(value),
+        ...objectCreate(
+          argumentIterablePrototype,
+          { args: { value: args } },
+        ),
+      ]),
+    set64BitFloatingPointItem: ($, byteOffset, value, ...args) =>
+      call(viewSetFloat64, view($), [
+        getByteOffset($) + byteOffset,
+        value,
+        ...objectCreate(
+          argumentIterablePrototype,
+          { args: { value: args } },
+        ),
+      ]),
+    set64BitIntegralItem: ($, byteOffset, value, ...args) =>
+      call(viewSetUint64, view($), [
+        getByteOffset($) + byteOffset,
+        asUintN(64, value),
+        ...objectCreate(
+          argumentIterablePrototype,
+          { args: { value: args } },
+        ),
+      ]),
+  };
+})();
+
+/**
+ * Returns the byte length for the provided array buffer or array
+ * buffer view.
+ *
+ * ☡ This function throws if the provided value is not an array buffer,
+ * data view, or typed array.
+ */
+export const getByteLength = ($) => {
+  try {
+    // Attempt to get the byte length from the provided value as an
+    // `ArrayBuffer`.
+    return call(getBufferByteLength, $, []);
+  } catch {
+    // The provided value is not an `ArrayBuffer`.
+    /* do nothing */
+  }
+  try {
+    // Attempt to get the byte length from the provided value as a
+    // `SharedArrayBuffer`.
+    return call(getSharedBufferByteLength, $, []);
+  } catch {
+    // The provided value is not a `SharedArrayBuffer`.
+    /* do nothing */
+  }
+  try {
+    // Attempt to get the byte length from the provided value as a
+    // data view.
+    return call(getViewByteLength, $, []);
+  } catch {
+    // The provided value is not a data view.
+    /* do nothing */
+  }
+  try {
+    // Attempt to get the byte length from the provided value as a
+    // typed array.
+    return call(getTypedArrayByteLength, $, []);
+  } catch {
+    // The provided value is not a typed array.
+    /* do nothing */
+  }
+  throw new TypeError(`Piscēs: Not an array buffer or view: ${$}.`);
+};
+
+/**
+ * Returns the byte offset for the provided array buffer or array
+ * buffer view.
+ *
+ * ※ This function always returns `0` for array buffers.
+ *
+ * ☡ This function throws if the provided value is not an array buffer,
+ * data view, or typed array.
+ */
+export const getByteOffset = ($) => {
+  if (isArrayBuffer($)) {
+    // The provided value is an array buffer.
+    return 0;
+  } else {
+    try {
+      // Attempt to get the byte offset from the provided value as a
+      // data view.
+      return call(getViewByteOffset, $, []);
+    } catch {
+      // The provided value is not a data view.
+      /* do nothing */
+    }
+    try {
+      // Attempt to get the byte offset from the provided value as a
+      // typed array.
+      return call(getTypedArrayByteOffset, $, []);
+    } catch {
+      // The provided value is not a typed array.
+      /* do nothing */
+    }
+    throw new TypeError(`Piscēs: Not an array buffer or view: ${$}.`);
+  }
+};
+
 /**
  * Returns whether the provided value is a view on an underlying array
  * buffer.
@@ -654,7 +1211,12 @@ export const filenameSafeBase64String = ($, ...$s) =>
  */
 export const { isView: isArrayBufferView } = Buffer;
 
-/** Returns whether the provided value is an array buffer. */
+/**
+ * Returns whether the provided value is an array buffer.
+ *
+ * ※ This function returns true for both `ArrayBuffer`s and
+ * `SharedArrayBuffer`s.
+ */
 export const isArrayBuffer = ($) => {
   try {
     // Try to see if the provided argument has array buffer internal
@@ -664,6 +1226,14 @@ export const isArrayBuffer = ($) => {
     // The provided argument does not have array buffer internal slots.
     /* do nothing */
   }
+  try {
+    // Try to see if the provided argument has array buffer internal
+    // slots and return true if so.
+    return call(getSharedBufferByteLength, $, []), true;
+  } catch {
+    // The provided argument does not have array buffer internal slots.
+    /* do nothing */
+  }
   return false;
 };
 
@@ -727,18 +1297,6 @@ export const isBase64 = ($) => {
   }
 };
 
-/** Returns whether the provided value is a data view. */
-export const isDataView = ($) => {
-  try {
-    // Try to see if the provided argument has data view internal slots
-    // and return true if so.
-    return call(getViewBuffer, $, []), true;
-  } catch {
-    // The provided argument does not have data view internal slots.
-    return false;
-  }
-};
-
 /**
  * Returns whether the provided value is a filename‐safe base64 string.
  *
@@ -760,6 +1318,18 @@ export const isFilenameSafeBase64 = ($) => {
   }
 };
 
+/** Returns whether the provided value is a shared array buffer. */
+export const isSharedArrayBuffer = ($) => {
+  try {
+    // Try to see if the provided argument has shared array buffer
+    // internal slots and return true if so.
+    return call(getSharedBufferByteLength, $, []), true;
+  } catch {
+    // The provided argument does not have data view internal slots.
+    return false;
+  }
+};
+
 /** Returns whether the provided value is a typed array. */
 export const isTypedArray = ($) => {
   try {