smsmslib 1.0.70 → 1.0.72

package/javascr/system/matnew.js

@@ -11,9 +11,15 @@
 
 import
 {
-  sj_array_lengthen,
+  sj_new_lit,
 }
-from "./array.js";
+from "./new.js";
+
+import
+{
+  sj_array_new,
+}
+from "./arraynew.js";
 
 import
 {
@@ -23,9 +29,16 @@ from "./arraypush.js";
 
 import
 {
-  sj_array_new,
+  sj_array_lengthen,
 }
-from "./arraynew.js";
+from "./array.js";
+
+import
+{
+  sj_tree_walk,
+  go_tree_walk_ret,
+}
+from "./tree.js";
 
 
 /** ---------------------------------------------------------------------------
@@ -35,41 +48,36 @@ from "./arraynew.js";
 /**
  * Creates a multi-dimensional array (matrix) with specified dimensions.
  * This function constructs a nested array structure based on the provided 
- * dimension arguments. 
+ * dimension array.
  *
- * @param {...number} ai_dim [in]
- * A variable number of arguments defining the size of each dimension.
- * For example, `sj_mat_new(2, 3)` creates a 2x3 matrix. All arguments 
+ * @param {number[]} ai_dim [in]
+ * An array of integers defining the size of each dimension.
+ * For example, `sj_mat_new([2, 3], 0)` creates a 2x3 matrix. All elements 
  * must be positive integers.
  *
+ * @param {any} initial [in]
+ * The value to fill the deepest level of the newly created array with.
+ *
  * @returns {Array | null}
- * A new multi-dimensional array initialized with 0 at the deepest level. 
+ * A new multi-dimensional array initialized with the `initial` value. 
  * Returns `null` if any dimension is invalid or if allocation fails.
  *
  * @see mat_new_init
- * @see mat_new_push
- * @see mat_new_pop
+ * @see mat_new_cb
  */
-export function sj_mat_new(...ai_dim)
+function sj_mat_new(ai_dim, initial)
 {
-  let   a_mat    = null;
-  const aa_stack = sj_array_new(0);
+  let   a_root = mat_new_init(ai_dim);
+  let   a_mat  = null;
+  const o_user = sj_new_lit(() => ({ai_dim, initial}));
 
-  if (aa_stack)
+  if (a_root && o_user)
   {
-    a_mat = mat_new_init(ai_dim);
-  }
+    const i_ret = sj_tree_walk(mat_new_cb, a_root, o_user);
 
-  while (a_mat && (a_mat.length < ai_dim[aa_stack.length]))
-  {
-    if (aa_stack.length < (ai_dim.length - 1))
+    if (i_ret === go_tree_walk_ret.i_ok)
     {
-      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);
+      a_mat = a_root;
     }
   }
 
@@ -93,9 +101,10 @@ export function sj_mat_new(...ai_dim)
  */
 function mat_new_init(ai_dim)
 {
-  let a_mat = null;
+  let   a_mat   = null;
+  const b_array = Array.isArray(ai_dim);
 
-  if (0 < ai_dim.length)
+  if (b_array && (0 < ai_dim.length))
   {
     const b_every_ok =
       ai_dim.every(i_dim => Number.isInteger(i_dim) && (0 < i_dim));
@@ -111,74 +120,55 @@ function mat_new_init(ai_dim)
 
 
 /**
- * Creates a new empty array for a deeper dimension and pushes the current 
- * array `a_mat` onto the stack.
+ * Callback to initialize a multi-dimensional array structure.
  *
- * @param {Array<Array>} aa_stack [in/out]
- * A stack used to store parent array references as the construction
- * moves to deeper dimensions.
+ * @param {array} ao_TreeStack [in, out]
+ * The current traversal path (stack of `TreeStack_t`).
+ * The callback processes the last element to manage the array's growth.
  *
- * @param {Array} a_mat [in]
- * The current array level that will now act as a parent to the 
- * newly created array.
+ * @param {any} from_child [in]
+ * Data passed back from a child node to the parent.
  *
- * @returns {Array | null}
- * The newly created array instance (the new current level). 
- * Returns `null` if array creation or pushing fails.
+ * @param {object} o_user [in, out]
+ * User-defined context containing:
+ * - ai_dim : Array of integers defining the size of each dimension.
+ * - initial: The initial value used to populate the leaf arrays.
+ *
+ * @returns {boolean}
+ * - true : Successfully processed and continues the traversal.
+ * - false: Failed to create a sub-array or lengthen the array.
  */
-function mat_new_push(aa_stack, a_mat)
+function mat_new_cb(ao_TreeStack, from_child, o_user)
 {
-  let a_push = sj_array_new(0, 0);
-
-  if (a_push)
-  {
-    let i_len = sj_array_push(a_mat, a_push);
+  let   i_ret;
+  let   b_continue  = true;
+  const o_TreeStack = ao_TreeStack.at(- 1);
+  const a_node = o_TreeStack.node;
+  const i_dim  = o_user.ai_dim.at(ao_TreeStack.length - 1);
 
-    if (0 < i_len)
-    {
-      i_len = sj_array_push(aa_stack, a_mat);
-    }
+  o_TreeStack.child = null;
 
-    if (i_len < 1)
+  if (ao_TreeStack.length < o_user.ai_dim.length) /* if not leaf */
+  {
+    if (o_TreeStack.i_child < i_dim)
     {
-      a_push = null;
+      o_TreeStack.child = sj_array_new(0);
+      b_continue = !(!o_TreeStack.child);
+
+      if (b_continue)
+      {
+        i_ret = sj_array_push(a_node, o_TreeStack.child);
+        b_continue = (0 < i_ret);
+      }
     }
   }
-
-  return a_push;
-}
-
-
-/**
- * Pops the stack to find the next available parent level after a_mat
- * has been fully populated.
- *
- * This function repeatedly executes `a_mat = aa_stack.pop()` until the 
- * condition `a_mat.length < ai_dim[aa_stack.length]` is met, ensuring 
- * the returned array has space for the next element at its specific depth.
- *
- * @param {Array<Array>} aa_stack [in/out]
- * A stack containing references to the parent arrays of `a_mat`.
- *
- * @param {Array} a_mat [in]
- * The current array level having been populated.
- *
- * @param {number[]} ai_dim [in]
- * An array where `ai_dim[n]` represents the size of the n-th order dimension.
- *
- * @returns {Array}
- * The parent array of `a_mat` that has available capacity.
- * Returns `a_mat` as is if no popping was necessary.
- */
-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))
+  else /* if leaf */
   {
-    a_mat_now = aa_stack.pop();
+    i_ret = sj_array_lengthen(a_node, i_dim, o_user.initial);
+    b_continue = (0 < i_ret);
   }
 
-  return a_mat_now;
+  return b_continue;
 }
 
+

package/javascr/system/new.js

@@ -0,0 +1,56 @@
+/**
+ * @file
+ * A collection of factory utilities providing **safe and controlled 
+ * initialization** for objects, arrays, and other data structures.
+ *
+ * @module javascr/system/new
+ */
+
+/** ---------------------------------------------------------------------------
+ * Imports.
+ * --------------------------------------------------------------------------- */
+
+import
+{
+  go_typeof,
+}
+from "./type.js";
+
+
+/** ---------------------------------------------------------------------------
+ * Functions.
+ * --------------------------------------------------------------------------- */
+
+/**
+ * Executes a provided initialization function to safely create and return 
+ * an object (literal).
+ *
+ * @param {function} f_init [in]
+ * A callback function that returns the initial object or data. 
+ * Must be of type 'function'.
+ *
+ * @returns {any|null}
+ * - The object returned by f_init.
+ * - null if f_init is not a function or
+ *   if an exception was caught during its execution.
+ */
+export function sj_new_lit(f_init)
+{
+  let o_lit = null;
+
+  try
+  {
+    if (typeof(f_init) === go_typeof.s_function)
+    {
+      o_lit = f_init();
+    }
+  }
+  catch (o_err)
+  {
+    console.error(`${sj_new_lit.name}: ${o_err.message}`);
+  }
+
+  return o_lit;
+}
+
+

package/javascr/system/tree.js

@@ -0,0 +1,274 @@
+/**
+ * @file
+ * Provides a non-recursive tree traversal engine.
+ *
+ * @module javascr/system/tree
+ */
+
+/** ---------------------------------------------------------------------------
+ * Imports.
+ * --------------------------------------------------------------------------- */
+
+import
+{
+  go_typeof,
+}
+from "./type.js";
+
+import
+{
+  sj_array_push,
+}
+from "./arraypush.js";
+
+import
+{
+  sj_array_new,
+}
+from "./arraynew.js";
+
+import
+{
+  sj_new_lit,
+}
+from "./new.js";
+
+
+/** ---------------------------------------------------------------------------
+ * Constants.
+ * --------------------------------------------------------------------------- */
+
+/**
+ * Initial value for the data passed back from a child node to the parent.
+ */
+const GI_FROM_CHILD_INI = 0;
+
+
+/**
+ * Return status codes for the tree traversal process.
+ *
+ * This frozen object defines the possible outcomes and error states 
+ * returned by the `sj_tree_walk` function and its internal components.
+ *
+ * @constant
+ * @readonly
+ * @enum {number}
+ */
+export const go_tree_walk_ret = Object.freeze(
+{
+  i_ok:      0,
+  i_nostack: 1,
+  i_stop:    2,
+  i_noncb:   3,
+}
+);
+
+
+/** ---------------------------------------------------------------------------
+ * Functions.
+ * --------------------------------------------------------------------------- */
+
+/**
+ * Performs a tree traversal using a stack-based approach.
+ *
+ * This function initiates a traversal of the tree starting from the `root` node.
+ * It manages the traversal state using a stack to avoid recursion depth issues
+ * and provides a controlled environment for the user callback.
+ *
+ * @param {function} f_cb [in]
+ * The traversal callback function.
+ * It will be called for each node with the following signature:
+ * `b_continue = f_cb(ao_TreeStack, from_child, user);`
+ * - ao_TreeStack: The current traversal path (stack of `TreeStack_t`).
+ *                 The callback typically processes the last element of this
+ *                 stack (the current node context).
+ * - from_child  : Data passed back from a child node(initially `GI_FROM_CHILD_INI`).
+ * - user        : User-defined data.
+ * - Returns     : true to continue descending/traversing, false to stop.
+ *
+ * @param {any} root [in]
+ * The root node of the tree to start walking from.
+ *
+ * @param {any} user [in, out]
+ * User-defined data passed through to every callback invocation.
+ *
+ * @returns {number}
+ * - go_tree_walk_ret.i_ok     : Traversal completed or processed as intended.
+ * - go_tree_walk_ret.i_noncb  : Provided f_cb is not a function.
+ * - go_tree_walk_ret.i_stop   : Traversal was explicitly stopped by the callback.
+ * - go_tree_walk_ret.i_nostack: Failed to allocate or push to the traversal stack.
+ */
+export function sj_tree_walk(f_cb, root, user)
+{
+  let  i_result;
+
+  if (typeof(f_cb) === go_typeof.s_function)
+  {
+    i_result = tree_walk(f_cb, root, user);
+  }
+  else
+  {
+    i_result = go_tree_walk_ret.i_noncb;
+  }
+
+  return i_result;
+}
+
+
+/**
+ * The core iterative engine for tree traversal.
+ *
+ * This function implements a non-recursive tree walk using a stack-based 
+ * approach to manage depth. It coordinates the descent into child nodes 
+ * and the ascent back to parent nodes, invoking the user callback at 
+ * each step.
+ *
+ * @param {function} f_cb [in]
+ * The traversal callback function.
+ * @see sj_tree_walk. For the detailed callback prototype and behavior.
+ *
+ * @param {any} root [in]
+ * The root node where the traversal begins.
+ *
+ * @param {any} user [in, out]
+ * User-defined data passed to the callback.
+ *
+ * @returns {number}
+ * - go_tree_walk_ret.i_ok     : Traversal completed successfully.
+ * - go_tree_walk_ret.i_stop   : Traversal was stopped by the callback.
+ * - go_tree_walk_ret.i_nostack: Failed to push a node onto the stack.
+ */
+function tree_walk(f_cb, root, user)
+{
+  let   from_child   = GI_FROM_CHILD_INI;
+  const ao_TreeStack = sj_array_new(0);
+  let   i_result     = ao_TreeStack_push(ao_TreeStack, root);
+
+  while ((i_result === go_tree_walk_ret.i_ok) && (0 < ao_TreeStack.length))
+  {
+    let o_TreeStackLast = ao_TreeStack.at(- 1);
+
+    i_result = tree_walk_cb(f_cb, ao_TreeStack, from_child, user);
+
+    while ((i_result === go_tree_walk_ret.i_ok) && o_TreeStackLast.child)
+    {
+      i_result = ao_TreeStack_push(ao_TreeStack, o_TreeStackLast.child); /* Descend */
+
+      if (i_result === go_tree_walk_ret.i_ok)
+      {
+        o_TreeStackLast = ao_TreeStack.at(- 1);
+        i_result = tree_walk_cb(f_cb, ao_TreeStack, GI_FROM_CHILD_INI, user);
+      }
+    }
+
+    from_child = o_TreeStackLast.to_parent;
+    ao_TreeStack.pop(); /* Ascend */
+  }
+
+  return i_result;
+}
+
+
+/**
+ * Creates a new stack frame and pushes it onto the traversal stack.
+ *
+ * @param {array} ao_TreeStack [in, out]
+ * The stack of TreeStack_t objects representing the current traversal path.
+ *
+ * @param {any} node [in]
+ * The tree node to be pushed onto the stack.
+ *
+ * @returns {number}
+ * - go_tree_walk_ret.i_ok     : Successfully pushed the node onto the stack.
+ * - go_tree_walk_ret.i_nostack: Failed to create a stack frame or push it 
+ */
+function ao_TreeStack_push(ao_TreeStack, node)
+{
+  let i_result    = go_tree_walk_ret.i_nostack;
+  let o_TreeStack = TreeStack_t(node);
+
+  if (o_TreeStack)
+  {
+    const i_ret = sj_array_push(ao_TreeStack, o_TreeStack);
+
+    if (0 < i_ret)
+    {
+      i_result = go_tree_walk_ret.i_ok;
+    }
+  }
+
+  return i_result;
+}
+
+
+/**
+ * Invokes the traversal callback and updates the traversal state.
+ *
+ * @param {function} f_cb [in]
+ * The traversal callback function.
+ * @see sj_tree_walk. For the detailed callback prototype and behavior.
+ *
+ * @param {array} ao_TreeStack [in, out]
+ * The stack of TreeStack_t objects representing the current traversal path.
+ *
+ * @param {any} from_child [in]
+ * Information or state passed back from the child node that was just visited.
+ *
+ * @param {any} user [in, out]
+ * User-defined data passed to the callback.
+ *
+ * @returns {number}
+ * - go_tree_walk_ret.i_ok  : Continue traversal.
+ * - go_tree_walk_ret.i_stop: Stop traversal.
+ */
+function tree_walk_cb(f_cb, ao_TreeStack, from_child, user)
+{
+  let   i_result        = go_tree_walk_ret.i_stop;
+  const b_continue      = f_cb(ao_TreeStack, from_child, user);
+  const o_TreeStackLast = ao_TreeStack.at(- 1);
+
+  ++(o_TreeStackLast.i_child);
+
+  if (b_continue) /* If continue */
+  {
+    i_result = go_tree_walk_ret.i_ok;
+  }
+
+  return i_result;
+}
+
+
+/**
+ * Creates a new stack frame object for tree traversal.
+ *
+ * @param {any} node [in]
+ * The tree node to be contained in a new stack frame object.
+ *
+ * @returns {object|null}
+ * A literal object containing:
+ * - node     : node.
+ *              The tree node specified.
+ *              Its child node, if any, will be assigned to `child`.
+ *
+ * - child    : null.
+ *              The i_child-th child node being visited.
+ *
+ * - i_child  : 0.
+ *              0-based index of the child node.
+ *
+ * - to_parent: GI_FROM_CHILD_INI.
+ *              Information or state to be passed back to the parent node.
+ *
+ * Returns null if object creation fails.
+ */
+function TreeStack_t(node)
+{
+  const child     = null;
+  const i_child   = 0;
+  const to_parent = GI_FROM_CHILD_INI;
+
+  const o_lit = sj_new_lit(() => ({node, child, i_child, to_parent}));
+  return o_lit;
+}
+
+

package/package.json

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