smsmslib 1.0.59 → 1.0.64

package/javascr/system/matnew.js

@@ -21,6 +21,24 @@ from "./array.js";
  * Functions.
  * --------------------------------------------------------------------------- */
 
+/**
+ * Creates a multi-dimensional array (matrix) with specified dimensions.
+ * This function constructs a nested array structure based on the provided 
+ * dimension arguments. 
+ *
+ * @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 
+ * must be positive integers.
+ *
+ * @returns {Array | null}
+ * A new multi-dimensional array initialized with 0 at the deepest level. 
+ * Returns `null` if any dimension is invalid or if allocation fails.
+ *
+ * @see mat_new_init
+ * @see mat_new_push
+ * @see mat_new_pop
+ */
 export function sj_mat_new(...ai_dim)
 {
   let   a_mat    = null;
@@ -48,6 +66,20 @@ export function sj_mat_new(...ai_dim)
 }
 
 
+/**
+ * Validates matrix dimensions and initializes the root array.
+ * This function ensures that `ai_dim` contains only positive integers.
+ * If valid, it creates and returns the first-order (root) array.
+ *
+ * @param {number[]} ai_dim [in]
+ * An array where `ai_dim[n]` represents the size of the n-th order dimension.
+ * Must contain at least one element, and all elements must be positive integers.
+ *
+ * @returns {Array | null}
+ * A new empty array for the first dimension if validation passes. 
+ * Returns `null` if `ai_dim` is empty, contains invalid dimensions, 
+ * or if array allocation fails.
+ */
 function mat_new_init(ai_dim)
 {
   let a_mat = null;
@@ -67,6 +99,22 @@ 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.
+ *
+ * @param {Array<Array>} aa_stack [in/out]
+ * A stack used to store parent array references as the construction
+ * moves to deeper dimensions.
+ *
+ * @param {Array} a_mat [in]
+ * The current array level that will now act as a parent to the 
+ * newly created array.
+ *
+ * @returns {Array | null}
+ * The newly created array instance (the new current level). 
+ * Returns `null` if array creation or pushing fails.
+ */
 function mat_new_push(aa_stack, a_mat)
 {
   const a_push = sj_array_new(0, 0);
@@ -90,6 +138,27 @@ function mat_new_push(aa_stack, a_mat)
 }
 
 
+/**
+ * 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;

package/package.json

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