smsmslib 1.0.55 → 1.0.59

package/javascr/system/array.js

@@ -1,132 +1,199 @@
 /**
  * @file
- * A collection of utility functions for **safely modifying and manipulating**
- * JavaScript Array instances.
- *
- * These functions wrap native Array methods (`push`, `splice`, etc.) to
- * ensure the target variable is a true Array instance before execution
- * and to gracefully handle potential runtime errors during the operation.
+ * Provides core utility functions for **safe inspection and property modification** 
+ * of Array instances.
  *
  * @module src/array
  */
 
-
 /** ---------------------------------------------------------------------------
  * Imports.
  * --------------------------------------------------------------------------- */
 
+import
+{
+  go_typeof
+}
+from "./type.js"
+
+import
+{
+  sj_set_new
+}
+from "./set.js"
+
 
 /** ---------------------------------------------------------------------------
  * Functions.
  * --------------------------------------------------------------------------- */
 
 /**
- * Safely executes Array.prototype.splice() to change the contents of an array by
- * removing or replacing existing elements and/or adding new elements.
+ * Safely searches for the first occurrence of the element specified by `old_any` 
+ * in the array `a_dst` and replaces it with `new_any`.
+ *
+ * The replacement operation is performed only if the target variable `a_dst` 
+ * is a true Array instance and the element is found within it using indexOf().
  *
- * @param {any} a_any [in]
+ * @param {any} a_dst [in/out]
  * The array to be modified. Must be a true Array instance.
  *
- * @param {number} i_start [in]
- * The zero-based index at which to start changing the array.
+ * @param {any} old_any [in] 
+ * The value to search for and replace (the element currently in the array).
  *
- * @param {number} i_remove [in]
- * The number of elements to remove from the starting index.
+ * @param {any} new_any [in]
+ * The value to replace the target element with.
  *
- * @param {...any} insert [in]
- * The element(s) to add to the array, starting at `i_start`.
- * 
- * @returns {Array<any> | null}
- * An array containing the deleted elements if the operation was successful
- * (may be an empty array []).
- * Returns `null` if the target variable is not an array or if a runtime error occurred
- * during the splice operation.
+ * @returns {boolean}
+ * `true` if the `old_any` was found and successfully replaced, otherwise `false`.
+ */
+export function sj_array_replace(a_dst, old_any, new_any)
+{
+  let b_replaced = Array.isArray(a_dst);
+
+  if (b_replaced)
+  {
+    const i_ret   = a_dst.indexOf(old_any);
+    const b_found = (- 1 < i_ret);
+
+    if (b_found)
+    {
+      a_dst[i_ret] = new_any;
+    }
+
+    b_replaced = b_found
+  }
+
+  return b_replaced;
+}
+
+
+/**
+ * Safely modifies the length of an array and optionally fills new slots.
+ *
+ * @param {any} a_dst [in/out]
+ * The array to modify. Must be a true Array instance.
+ *
+ * @param {number} i_dst_len [in]
+ * The new length. Must be a non-negative integer.
+ *
+ * @param {any} initial [in, optional]
+ * The value to fill the newly created slots with.
+ *
+ * @returns {number}
+ * The new length of the array, or -1 if the operation failed.
  */
-export function sj_array_splice(a_any, i_start, i_remove, ...insert)
+export function sj_array_lengthen(a_dst, i_dst_len, initial = undefined)
 {
-  const b_array   = Array.isArray(a_any);
-  let   a_spliced = null;
+  const b_array = Array.isArray(a_dst);
+  let   i_result = - 1;
 
-  if (b_array)
+  if (b_array && (- 1 < i_dst_len))
   {
     try
     {
-      a_spliced = a_any.splice(i_start, i_remove, ...insert);
+      const i_src_len = a_dst.length;
+
+      a_dst.length = i_dst_len;
+      i_result = a_dst.length;
+
+      if (sj_array_lengthen.length < arguments.length)
+      {
+        for (let i_idx = i_src_len; i_idx < i_dst_len; i_idx++)
+        {
+          a_dst[i_idx] = initial;
+        }
+      }
     }
     catch (o_err)
     {
-      console.error(`${sj_array_splice.name}: ${o_err.message}`);
+      console.error(`${sj_array_lengthen.name}: ${o_err.message}`);
     }
   }
 
-  return a_spliced;
+  return i_result;
 }
 
 
 /**
- * Safely adds one or more elements to the end of an array using
- * Array.prototype.push().
+ * Safely executes Array.prototype.filter().
  *
- * @param {any} a_any [in]
- * The array to which the element(s) should be pushed. Must be a true Array instance.
+ * @param {any} a_src [in]
+ * The source array to filter.
  *
- * @param {...any} push [in]
- * The element(s) to add to the array.
+ * @param {function} f_filter [in]
+ * The predicate function to test each element, following the 
+ * `Array.prototype.filter` callback signature: `(value, index, array) => boolean`.
  * 
- * @returns {number}
- * The new length of the array if the operation was successful
- * (equivalent to native push).
- * Returns -1 if the target variable is not an array or
- * if a runtime error occurred during the push operation.
+ * @returns {Array<any> | null}
+ * A new array with the elements that pass the test. 
+ * Returns `null` if the input is not an array, f_filter is not a function, 
+ * or if a runtime error occurs.
  */
-export function sj_array_push(a_any, ...push)
+export function sj_array_filter(a_src, f_filter)
 {
-  const b_array = Array.isArray(a_any);
-  let   i_len   = - 1;
+  let a_result = null;
 
-  if (b_array)
+  const b_valid = Array.isArray(a_src) && (typeof f_filter === go_typeof.s_function);
+
+  if (b_valid)
   {
     try
     {
-      i_len = a_any.push(...push);
+      a_result = a_src.filter(f_filter);
     }
     catch (o_err)
     {
-      console.error(`${sj_array_push.name}: ${o_err.message}`);
+      console.error(`${sj_array_filter.name}: ${o_err.message}`);
+      a_result = null;
     }
   }
 
-  return i_len;
+  return a_result;
 }
 
 
 /**
- * Safely creates a new Array instance with a specified length.
- *
- * @param {number} i_len [in]
- * The length of the new array. Must be a non-negative integer.
+ * Checks if all elements in the array are unique.
  *
- * @param {any} initial [in, optional]
- * The value to fill each element with.
+ * @param {Array} a_src [in]
+ * The array to be checked.
  *
- * @returns {Array<any> | null}
- * A new array of the specified length filled with `initial`.
- * Returns `null` if the length is invalid or a runtime error occurs.
+ * @returns {number}
+ * Returns one of the following codes:
+ * -  1: Success. The input is an array and all elements are unique.
+ * -  0: Success. The input is an array but contains duplicate elements.
+ * - -1: Failure. The input is not an array or an internal error occurred.
  */
-export function sj_array_new(i_len, initial)
+export function sj_array_is_unique(a_src)
 {
-  let a_any = null;
+  let i_result    = - 1;
+  let b_src_array = Array.isArray(a_src);
 
-  try
+  if (b_src_array)
   {
-    a_any = new Array(i_len).fill(initial);
-  }
-  catch (o_err)
-  {
-    console.error(`${sj_array_new.name}: ${o_err.message}`);
+    if (1 < a_src.length)
+    {
+      const o_set = sj_set_new(a_src);
+
+      if (o_set)
+      {
+        if (a_src.length === o_set.size)
+        {
+          i_result = 1;
+        }
+        else
+        {
+          i_result = 0;
+        }
+      }
+    }
+    else
+    {
+      i_result = 1;
+    }
   }
 
-  return a_any;
+  return i_result;
 }
 
 

package/javascr/system/arrayconcat.js

@@ -0,0 +1,104 @@
+ /**
+ * @file
+ * Provides utility functions for **safely merging and concatenating** 
+ * Array instances.
+ *
+ * @module src/arrayconcat
+ */
+
+/** ---------------------------------------------------------------------------
+ * Imports.
+ * --------------------------------------------------------------------------- */
+
+import
+{
+  sj_array_lengthen,
+}
+from "./array.js";
+
+import
+{
+  sj_set_new,
+}
+from "./set.js";
+
+
+/** ---------------------------------------------------------------------------
+ * Functions.
+ * --------------------------------------------------------------------------- */
+
+/**
+ * Concatenates elements to an array only if both the source and target 
+ * contain no overlapping elements and the source itself is unique.
+ *
+ * @param {Array} a_dst - The target array to append to.
+ * @param {Array} a_src - The source array containing elements to add.
+ * @returns {number} - The new length of the array after the push, 
+ * or -1 if validation fails or elements are not disjoint.
+ */
+export function sj_array_concat_new(a_dst, a_src)
+{
+  let   i_len = - 1;
+  const b_dst = Array.isArray(a_dst);
+  const b_cat = Array.isArray(a_src);
+
+  if (b_dst && b_cat)
+  {
+    const o_set_dst = sj_set_new(a_dst);
+    const o_set_cat = sj_set_new(a_src);
+
+    if (o_set_dst && o_set_cat &&
+      (a_src.length === o_set_cat.size)) /* if all elements in a_src are unique */
+    {
+      const b_disjoint = o_set_dst.isDisjointFrom(o_set_cat);
+
+      if (b_disjoint)
+      {
+        i_len = sj_array_concat(a_dst, a_src);
+      }
+    }
+  }
+
+  return i_len;
+}
+
+
+/**
+ * Safely concatenates elements from the source array to the destination array.
+ * Uses a loop to prevent stack overflow errors that can occur with 
+ * large arrays when using spread syntax.
+ *
+ * @param {Array} a_dst [in/out]
+ * The target array to append to. Must be a true Array instance.
+ *
+ * @param {Array} a_src [in]
+ * The source array containing elements to add. Must be a true Array instance.
+ *
+ * @returns {number}
+ * The new length of the destination array, or -1 if an error occurred.
+ */
+export function sj_array_concat(a_dst, a_src)
+{
+  const b_dst_array = Array.isArray(a_dst);
+  const b_src_array = Array.isArray(a_src);
+  let   i_dst_len   = - 1;
+
+  if (b_dst_array && b_src_array)
+  {
+    const i_org_dst_len = a_dst.length;
+
+    i_dst_len = sj_array_lengthen(a_dst, a_dst.length + a_src.length);
+
+    if (- 1 < i_dst_len)
+    {
+      for (let i_src = 0; i_src < a_src.length; i_src++)
+      {
+        a_dst[i_org_dst_len + i_src] = a_src[i_src];
+      }
+    }
+  }
+
+  return i_dst_len;
+}
+
+

package/javascr/system/arraynew.js

@@ -0,0 +1,91 @@
+/**
+ * @file
+ * Provides utility functions for **creating and initializing** Array instances
+ * safely.
+ *
+ * @module src/arraynew
+ */
+
+/** ---------------------------------------------------------------------------
+ * Imports.
+ * --------------------------------------------------------------------------- */
+
+
+/** ---------------------------------------------------------------------------
+ * Functions.
+ * --------------------------------------------------------------------------- */
+
+/**
+ * Creates a shallow copy of the source array.
+ *
+ * @param {any} a_src [in]
+ * The source array to be copied.
+ *
+ * @returns {Array<any> | null}
+ * A new array instance containing the same elements as `a_src`.
+ * Returns `null` if the input is not an array or if the new array 
+ * allocation fails.
+ */
+export function sj_array_new_copy(a_src)
+{
+  let   a_dst = null;
+  const b_src_is_array = Array.isArray(a_src);
+
+  if (b_src_is_array)
+  {
+    a_dst = sj_array_new(a_src.length);
+  }
+
+  if (a_dst)
+  {
+    for (let i_cnt = 0; i_cnt < a_src.length; i_cnt++)
+    {
+      a_dst[i_cnt] = a_src[i_cnt];
+    }
+  }
+
+  return a_dst;
+}
+
+
+/**
+ * Safely creates a new Array instance with a specified length.
+ *
+ * @param {number} i_len [in]
+ * The length of the new array. Must be a non-negative integer.
+ *
+ * @param {any} initial [in, optional]
+ * The value to fill each element with. If omitted, the array elements 
+ * remain uninitialized (empty slots) for better performance.
+ *
+ * @returns {Array<any> | null}
+ * A new array of the specified length. 
+ * - If `initial` is provided, each element is filled with that value.
+ * - If `initial` is omitted, the array is returned with uninitialized slots.
+ * Returns `null` if the length is invalid or a runtime error occurs.
+ */
+export function sj_array_new(i_len, initial = undefined)
+{
+  let a_new = null;
+
+  if (- 1 < i_len)
+  {
+    try
+    {
+      a_new = new Array(i_len);
+
+      if (sj_array_new.length < arguments.length)
+      {
+        a_new.fill(initial);
+      }
+    }
+    catch (o_err)
+    {
+      console.error(`${sj_array_new.name}: ${o_err.message}`);
+    }
+  }
+
+  return a_new;
+}
+
+

package/javascr/system/arraypush.js

@@ -0,0 +1,90 @@
+/**
+ * @file
+ * Provides utility functions for **safely adding elements** to the end of 
+ * Array instances.
+ *
+ * @module src/arraypush
+ */
+
+
+/** ---------------------------------------------------------------------------
+ * Imports.
+ * --------------------------------------------------------------------------- */
+
+
+/** ---------------------------------------------------------------------------
+ * Functions.
+ * --------------------------------------------------------------------------- */
+
+/**
+ * Adds an element to the end of an array only if it is not already present.
+ *
+ * @param {Array} a_dst [in/out]
+ * The target array to be modified.
+ *
+ * @param {any} any [in]
+ * The element to add (uses strict equality for the uniqueness check).
+ *
+ * @returns {number}
+ * Returns the new length of the array if the element was added.
+ * Returns -1 if the element already exists, the input is not an array, 
+ * or the push operation failed.
+ */
+export function sj_array_push_new(a_dst, any)
+{
+  let i_len   = - 1;
+  let b_added = Array.isArray(a_dst);
+
+  if (b_added)
+  {
+    let i_ret = a_dst.indexOf(any);
+
+    if (i_ret < 0)
+    {
+      i_len = sj_array_push(a_dst, any);
+    }
+  }
+
+  return i_len;
+}
+
+
+/**
+ * Safely adds one or more elements to the end of an array using
+ * Array.prototype.push().
+ *
+ * @param {any} a_dst [in]
+ * The array to which the element(s) should be pushed. Must be a true Array instance.
+ *
+ * @param {any} push [in]
+ * The element to add to the array.
+ * 
+ * @returns {number}
+ * The new length of the array if the operation was successful
+ * (equivalent to native push).
+ * Returns -1 if the target variable is not an array or
+ * if a runtime error occurred during the push operation.
+ *
+ * @see sj_array_concat
+ */
+export function sj_array_push(a_dst, push)
+{
+  const b_array = Array.isArray(a_dst);
+  let   i_len   = - 1;
+
+  if (b_array)
+  {
+    try
+    {
+      i_len = a_dst.push(push);
+    }
+    catch (o_err)
+    {
+      console.error(`${sj_array_push.name}: ${o_err.message}`);
+    }
+  }
+
+  return i_len;
+}
+
+

package/javascr/system/arraysplice.js

@@ -0,0 +1,168 @@
+/**
+ * @file
+ * Provides utility functions for **safely modifying array contents** through 
+ * splicing, removal, and replacement.
+ *
+ * @module src/arraysplice
+ */
+
+/** ---------------------------------------------------------------------------
+ * Imports.
+ * --------------------------------------------------------------------------- */
+
+import
+{
+  sj_array_concat,
+}
+from "./arrayconcat.js";
+
+import
+{
+  sj_array_new,
+}
+from "./arraynew.js";
+
+
+/** ---------------------------------------------------------------------------
+ * Functions.
+ * --------------------------------------------------------------------------- */
+
+/**
+ * Removes all occurrences of a specific element from an array.
+ *
+ * @param {Array} a_dst [in/out]
+ * The target array to be filtered in-place.
+ *
+ * @param {any} rem [in]
+ * The specific element to remove (uses strict equality).
+ *
+ * @returns {boolean}
+ * Returns true if the splice operation succeeded.
+ */
+export function sj_array_splice_element_all(a_dst, rem)
+{
+  let b_spliced = false;
+  let b_ret     = Array.isArray(a_dst);
+
+  if (b_ret)
+  {
+    let a_rem = sj_array_new(0);
+
+    for (let i_cnt = a_dst.length - 1; (- 1 < i_cnt) && (a_rem !== null); i_cnt--)
+    {
+      if (a_dst[i_cnt] === rem)
+      {
+        a_rem = sj_array_splice(a_dst, i_cnt, 1, null);
+      }
+    }
+
+    b_spliced = (a_rem !== null);
+  }
+
+  return b_spliced;
+}
+
+
+/**
+ * Replaces a specific element in an array with new elements provided as an array.
+ *
+ * @param {Array} a_dst [in/out]
+ * The target array to be modified.
+ *
+ * @param {any} rem [in]
+ * The specific element to search for (uses strict equality(===)).
+ *
+ * @param {Array<any> | null} a_ins [in]
+ * An array of elements to insert in place of the found element. 
+ * If null or not an array, no elements are inserted after removal.
+ *
+ * @returns {boolean}
+ * Returns true if the element was found and the replacement operation succeeded, 
+ * false otherwise.
+ */
+export function sj_array_splice_element(a_dst, rem, a_ins)
+{
+  let b_spliced = false;
+  let b_ret     = Array.isArray(a_dst);
+
+  if (b_ret)
+  {
+    const i_ret = a_dst.indexOf(rem);
+
+    if (- 1 < i_ret)
+    {
+      const a_ret = sj_array_splice(a_dst, i_ret, 1, a_ins);
+
+      b_spliced = (a_ret !== null);
+    }
+  }
+
+  return b_spliced;
+}
+
+
+/**
+ * Safely executes a splice-like operation to change the contents of an array.
+ * This implementation avoids stack overflow errors by using manual iteration 
+ * instead of spread syntax for the elements to be inserted.
+ *
+ * @param {any} a_dst [in/out]
+ * The array to be modified. Must be a true Array instance.
+ *
+ * @param {number} i_start [in]
+ * The zero-based index at which to start changing the array.
+ *
+ * @param {number} i_remove [in]
+ * The number of elements to remove from `i_start`.
+ *
+ * @param {Array<any> | null} a_insert [in]
+ * An array of elements to insert at `i_start`. If `null` or not an array, 
+ * no elements are inserted.
+ *
+ * @returns {Array<any> | null}
+ * A new array containing the removed elements if the operation succeeded 
+ * (returns an empty array `[]` if no elements were removed).
+ * Returns `null` if `a_dst` is not an array, or if an internal concatenation 
+ * error occurs.
+ */
+export function sj_array_splice(a_dst, i_start, i_remove, a_insert)
+{
+  const b_array_dst = Array.isArray(a_dst);
+  let   a_remove    = null;
+
+  if (b_array_dst)
+  {
+    try
+    {
+      const b_array_ins = Array.isArray(a_insert);
+      const a_tail      = a_dst.splice(i_start, a_dst.length - i_start);
+      let   i_dst_len   = a_dst.length;
+
+      a_remove = a_tail.splice(0, i_remove);
+
+      if (b_array_ins)
+      {
+        i_dst_len = sj_array_concat(a_dst, a_insert);
+      }
+
+      if (- 1 < i_dst_len)
+      {
+        i_dst_len = sj_array_concat(a_dst, a_tail);
+      }
+
+      if (i_dst_len < 0)
+      {
+        a_remove = null;
+      }
+    }
+    catch (o_err)
+    {
+      console.error(`${sj_array_splice.name}: ${o_err.message}`);
+      a_remove = null;
+    }
+  }
+
+  return a_remove;
+}
+
+

package/javascr/system/index.js

@@ -11,7 +11,11 @@ export * from "./Observer_t.js";
 export * from "./SubjectSet_t.js";
 export * from "./Subject_t.js";
 export * from "./array.js";
-export * from "./arrayapp.js";
+export * from "./arraynew.js";
+export * from "./arraypush.js";
+export * from "./arraysplice.js";
+export * from "./arrayconcat.js";
+export * from "./matnew.js";
 export * from "./dataset.js";
 export * from "./document.js";
 export * from "./error.js";

package/javascr/system/matnew.js

@@ -0,0 +1,104 @@
+ /**
+ * @file
+ *
+ * @module src/matnew
+ */
+
+/** ---------------------------------------------------------------------------
+ * Imports.
+ * --------------------------------------------------------------------------- */
+
+import
+{
+  sj_array_new,
+  sj_array_push,
+  sj_array_lengthen,
+}
+from "./array.js";
+
+
+/** ---------------------------------------------------------------------------
+ * Functions.
+ * --------------------------------------------------------------------------- */
+
+export function sj_mat_new(...ai_dim)
+{
+  let   a_mat    = null;
+  const aa_stack = sj_array_new(0);
+
+  if (aa_stack)
+  {
+    a_mat = mat_new_init(ai_dim);
+  }
+
+  while (a_mat && (a_mat.length < ai_dim[aa_stack.length]))
+  {
+    if (aa_stack.length < (ai_dim.length - 1))
+    {
+      a_mat = mat_new_push(aa_stack, a_mat);
+    }
+    else
+    {
+      sj_array_lengthen(a_mat, ai_dim[aa_stack.length], 0);
+      a_mat = mat_new_pop(aa_stack, a_mat, ai_dim);
+    }
+  }
+
+  return a_mat;
+}
+
+
+function mat_new_init(ai_dim)
+{
+  let a_mat = null;
+
+  if (0 < ai_dim.length)
+  {
+    const b_every_ok =
+      ai_dim.every(i_dim => Number.isInteger(i_dim) && (0 < i_dim));
+
+    if (b_every_ok)
+    {
+      a_mat = sj_array_new(0);
+    }
+  }
+
+  return a_mat;
+}
+
+
+function mat_new_push(aa_stack, a_mat)
+{
+  const a_push = sj_array_new(0, 0);
+
+  if (a_push)
+  {
+    let i_len = sj_array_push(a_mat, a_push);
+
+    if (0 < i_len)
+    {
+      i_len = sj_array_push(aa_stack, a_mat);
+    }
+
+    if (i_len < 1)
+    {
+      a_push = null;
+    }
+  }
+
+  return a_push;
+}
+
+
+function mat_new_pop(aa_stack, a_mat, ai_dim)
+{
+  let a_mat_now = a_mat;
+
+  while ((0 < aa_stack.length) && (ai_dim[aa_stack.length] <= a_mat_now.length))
+  {
+    a_mat_now = aa_stack.pop();
+  }
+
+  return a_mat_now;
+}
+

package/javascr/system/set.js

@@ -0,0 +1,42 @@
+/**
+ * @file
+ * Set utility functions.
+ * Provides helper functions for creating and managing Set objects.
+ *
+ * @module src/set
+ */
+
+/** ---------------------------------------------------------------------------
+ * Imports.
+ * --------------------------------------------------------------------------- */
+
+
+/** ---------------------------------------------------------------------------
+ * Functions.
+ * --------------------------------------------------------------------------- */
+
+/**
+ * Creates a new Set object from the provided source.
+ *
+ * @param {Iterable|null|undefined} src [in]
+ * An iterable object (such as an Array, String, or another Set).
+ *
+ * @returns {Set|null}
+ * A new Set containing the source elements, or null if instantiation fails.
+ */
+export function sj_set_new(src)
+{
+  let o_set = null;
+
+  try
+  {
+    o_set = new Set(src);
+  }
+  catch (o_err)
+  {
+    console.error(`${sj_set_new.name}: ${o_err.message}`);
+  }
+
+  return o_set;
+}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smsmslib",
-  "version": "1.0.55",
+  "version": "1.0.59",
   "description": "Reusable functions for me.",
   "files": [
     "javascr/**/*.js",
@@ -19,6 +19,6 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "smsmslib": "^1.0.55"
+    "smsmslib": "^1.0.59"
   }
 }

package/javascr/system/arrayapp.js

@@ -1,223 +0,0 @@
-/**
- * @file
- * A collection of utility functions for safe and unique array manipulations.
- * Provides enhanced array operations including disjoint concatenation, uniqueness
- * checks, and safe in-place modifications (push, replace, and splice).
- *
- * Key Features:
- * - Integrity: Validates array types before execution.
- * - Uniqueness: Supports operations that prevent duplicate entries.
- * - Safety: Wraps native methods to prevent runtime exceptions in critical flows.
- *
- * @module src/arrayapp
- */
-
-
-/** ---------------------------------------------------------------------------
- * Imports.
- * --------------------------------------------------------------------------- */
-
-import {sj_array_push} from "./array.js";
-
-
-/** ---------------------------------------------------------------------------
- * Functions.
- * --------------------------------------------------------------------------- */
-
-/**
- * Concatenates elements to an array only if both the source and target 
- * contain no overlapping elements and the source itself is unique.
- *
- * @param {any} a_any - The target array to append to.
- * @param {any} a_cat - The source array containing elements to add.
- * @returns {number} - The new length of the array after the push, 
- * or -1 if validation fails or elements are not disjoint.
- */
-export function sj_array_concat_new(a_any, a_cat)
-{
-  let   i_len = - 1;
-  const b_any = Array.isArray(a_any);
-  const b_cat = Array.isArray(a_cat);
-
-  if (b_any && b_cat)
-  {
-    const o_set_any = new Set(a_any);
-    const o_set_cat = new Set(a_cat);
-
-    if (a_cat.length === o_set_cat.size) /* if all elements in a_cat are unique */
-    {
-      const b_disjoint = o_set_any.isDisjointFrom(o_set_cat);
-
-      if (b_disjoint)
-      {
-        i_len = sj_array_push(a_any, ...a_cat);
-      }
-    }
-  }
-
-  return i_len;
-}
-
-
-/**
- * Checks if all elements in the array are unique.
- *
- * @param {any} a_any [i]
- * The target to check.
- *
- * @returns {boolean}
- * Returns true if the input is an array with no duplicates.
- */
-export function sj_array_is_unique(a_any)
-{
-  let b_ret = Array.isArray(a_any);
-
-  if (b_ret && (1 < a_any.length))
-  {
-    const o_set = new Set(a_any);
-
-    b_ret = (a_any.length === o_set.size);
-  }
-
-  return b_ret;
-}
-
-
-/**
- * Adds an element to the end of an array only if it is not already present.
- *
- * @param {Array} a_any [in/out]
- * The target array to be modified.
- *
- * @param {any} any [in]
- * The element to add (uses strict equality for the uniqueness check).
- *
- * @returns {number}
- * Returns the new length of the array if the element was added.
- * Returns -1 if the element already exists, the input is not an array, 
- * or the push operation failed.
- */
-export function sj_array_push_new(a_any, any)
-{
-  let i_len   = - 1;
-  let b_added = Array.isArray(a_any);
-
-  if (b_added)
-  {
-    let i_ret = a_any.indexOf(any);
-
-    if (i_ret < 0)
-    {
-      i_len = sj_array_push(a_any, any);
-    }
-  }
-
-  return i_len;
-}
-
-
-/**
- * Removes all occurrences of a specific element from an array.
- *
- * @param {Array} a_any [in/out]
- * The target array to be filtered in-place.
- *
- * @param {any} any [in]
- * The specific element to remove (uses strict equality).
- *
- * @returns {boolean}
- * Returns true if the splice operation succeeded.
- */
-export function sj_array_splice_element_all(a_any, any)
-{
-  let a_ret;
-  let b_spliced = Array.isArray(a_any);
-
-  if (b_spliced)
-  {
-    const a_insert = a_any.filter(item => (item !== any));
-
-    a_ret = sj_array_splice(a_any, 0, a_any.length, ...a_insert);
-    b_spliced = (a_ret !== null);
-  }
-
-  return b_spliced;
-}
-
-
-/**
- * Replaces a specific element in an array with new elements.
- *
- * @param {Array} a_any [in/out]
- * The target array to be modified.
- *
- * @param {any} old_any [in]
- * The specific element to search for (uses strict equality).
- *
- * @param {...any} insert [in]
- * The elements to insert in place of the found element.
- *
- * @returns {boolean}
- * Returns true if the element was found and spliced, false otherwise.
- */
-export function sj_array_splice_element(a_any, old_any, ...insert)
-{
-  let b_spliced = false;
-  let b_ret     = Array.isArray(a_any);
-
-  if (b_ret)
-  {
-    const i_ret = a_any.indexOf(old_any);
-
-    if (- 1 < i_ret)
-    {
-      const a_ret = sj_array_splice(a_any, i_ret, 1, ...insert);
-
-      b_spliced = (a_ret !== null);
-    }
-  }
-
-  return b_spliced;
-}
-
-
-/**
- * Safely searches for the first occurrence of the element specified by `old_any` 
- * in the array `a_any` and replaces it with `new_any`.
- *
- * The replacement operation is performed only if the target variable `a_any` 
- * is a true Array instance and the element is found within it using indexOf().
- *
- * @param {any} a_any [in/out]
- * The array to be modified. Must be a true Array instance.
- *
- * @param {any} old_any [in] 
- * The value to search for and replace (the element currently in the array).
- *
- * @param {any} new_any [in]
- * The value to replace the target element with.
- *
- * @returns {boolean}
- * `true` if the `old_any` was found and successfully replaced, otherwise `false`.
- */
-export function sj_array_replace(a_any, old_any, new_any)
-{
-  let b_replaced = Array.isArray(a_any);
-
-  if (b_replaced)
-  {
-    const i_ret   = a_any.indexOf(old_any);
-    const b_found = (- 1 < i_ret);
-
-    if (b_found)
-    {
-      a_any[i_ret] = new_any;
-    }
-
-    b_replaced = b_found
-  }
-
-  return b_replaced;
-}
-
-