From d2e44bfa8b54ad16b84a29ff963f12e577a62da9 Mon Sep 17 00:00:00 2001
From: Eric Fahlgren <ericfahlgren@gmail.com>
Date: Mon, 10 Jun 2024 11:15:01 -0700
Subject: core-lib: improved documentation

- document optional 'base' parameter on 'int' function
- add description of 'fn' parameter call sequence to 'map'
- add several usage examples to both 'int' and 'map'
- reference similarity between 'map' and 'filter' use of 'fn'
- fix a few typos

Signed-off-by: Eric Fahlgren <ericfahlgren@gmail.com>
---
 lib.c | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 55 insertions(+), 4 deletions(-)

diff --git a/lib.c b/lib.c
index 5a6c934..e814f49 100644
--- a/lib.c
+++ b/lib.c
@@ -894,7 +894,10 @@ uc_getenv(uc_vm_t *vm, size_t nargs)
  * 2. The current index
  * 3. The array being filtered
  *
- * Returns a new array containing only retainted items, in the same order as
+ * (Note that the `map` function behaves similarly to `filter` with respect
+ * to its `fn` parameters.)
+ *
+ * Returns a new array containing only retained items, in the same order as
  * the input array.
  *
  * @function module:core#filter
@@ -989,7 +992,7 @@ uc_hex(uc_vm_t *vm, size_t nargs)
 }
 
 /**
- * Converts the given value to an integer.
+ * Converts the given value to an integer, using an optional base.
  *
  * Returns `NaN` if the value is not convertible.
  *
@@ -998,7 +1001,23 @@ uc_hex(uc_vm_t *vm, size_t nargs)
  * @param {*} x
  * The value to be converted to an integer.
  *
+ * @param {int} [base]
+ * The base into which the value is to be converted, the default is 10.
+ * Note that the base parameter is ignored if the `x` value is already numeric.
+ *
  * @returns {number}
+ *
+ * @example
+ * int("123")         // Returns 123
+ * int("123", 10)     // 123
+ * int("10 or more")  // 10
+ * int("12.3")        // 12
+ * int("123", 7)      // 66
+ * int("abc", 16)     // 2748
+ * int("xyz", 36)     // 44027
+ * int(10.10, "2")    // 10, the invalid base is ignored
+ * int("xyz", 16)     // NaN, bad value
+ * int("1010", "2")   // NaN, bad base
  */
 static uc_value_t *
 uc_int(uc_vm_t *vm, size_t nargs)
@@ -1138,6 +1157,16 @@ uc_lc(uc_vm_t *vm, size_t nargs)
  * Transform the array passed as the first argument by invoking the function
  * specified in the second argument for each array item.
  *
+ * The mapping function is invoked with three arguments (see examples, below,
+ * for some possibly counterintuitive usage):
+ *
+ * 1. The array value
+ * 2. The current index
+ * 3. The array being filtered
+ *
+ * (Note that the `filter` function behaves similarly to `map` with respect
+ * to its `fn` parameters.)
+ *
  * Returns a new array of the same length as the input array containing the
  * transformed values.
  *
@@ -1159,6 +1188,28 @@ uc_lc(uc_vm_t *vm, size_t nargs)
  * // map to type names:
  * a = map(["foo", 1, true, null, 2.2], type);
  * // a = ["string", "int", "bool", null, "double"]
+ *
+ * // attempt to naively use built-in 'int' to map an array:
+ * a = map(["x", "2", "11", "7"], int)
+ * // a = [NaN, NaN, 3, NaN]
+ * //
+ * // This is a direct result of 'int' being provided the second, index parameter
+ * // for its base value in the conversion.
+ * //
+ * // The resulting calls to 'int' are as follows:
+ * //  int("x",  0, [...]) - convert "x"  to base 0, 'int' ignores the third value
+ * //  int("2",  1, [...]) - convert "2"  to base 1, digit out of range, so NaN
+ * //  int("11", 2, [...]) - convert "11" to base 2, produced unexpected 3
+ * //  int("7",  3, [...]) - convert "7"  to base 3, digit out of range, NaN again
+ *
+ * // remedy this by using an arrow function to ensure the proper base value
+ * // (in this case, the default of 10) is passed to 'int':
+ * a = map(["x", "2", "1", "7"], (x) => int(x))
+ * // a = [NaN, 2, 1, 7]
+ *
+ * // convert base-2 values:
+ * a = map(["22", "1010", "0001", "0101"], (x) => int(x, 2))
+ * // a = [NaN, 10, 1, 5]
  */
 static uc_value_t *
 uc_map(uc_vm_t *vm, size_t nargs)
@@ -2864,7 +2915,7 @@ uc_require(uc_vm_t *vm, size_t nargs)
  * Convert the given IP address string to an array of byte values.
  *
  * IPv4 addresses result in arrays of 4 integers while IPv6 ones in arrays
- * containing 16 intergers. The resulting array can be turned back into IP
+ * containing 16 integers. The resulting array can be turned back into IP
  * address strings using the inverse `arrtoip()` function.
  *
  * Returns an array containing the address byte values.
@@ -5341,7 +5392,7 @@ uc_gc(uc_vm_t *vm, size_t nargs)
  * @typedef {Object} module:core.ParseConfig
  *
  * @property {boolean} lstrip_blocks
- * Whether to strip whitespace preceeding template directives.
+ * Whether to strip whitespace preceding template directives.
  * See {@link tutorial-02-syntax.html#whitespace-handling|Whitespace handling}.
  *
  * @property {boolean} trim_blocks
-- 
cgit v1.2.3