iterable_operate.scad

Go to the documentation of this file.

//! Iterable data type operations.
/***************************************************************************//**
  \file
  \author Roy Allen Sutton
  \date   2015-2026
 
  \copyright
 
    This file is part of [omdl] (https://github.com/royasutton/omdl),
    an OpenSCAD mechanical design library.
 
    The \em omdl is free software; you can redistribute it and/or modify
    it under the terms of the [GNU Lesser General Public License]
    (http://www.gnu.org/licenses/lgpl.html) as published by the Free
    Software Foundation; either version 2.1 of the License, or (at
    your option) any later version.
 
    The \em omdl is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Lesser General Public License for more details.
 
    You should have received a copy of the GNU Lesser General Public
    License along with the \em omdl; if not, write to the Free Software
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
    02110-1301, USA; or see <http://www.gnu.org/licenses/>.
 
  \details
 
    \amu_define group_name  (Iterable Operations)
    \amu_define group_brief (Operations for iterable data types.)
 
  \amu_include (include/amu/doxyg_init_pd_gds_ipg.amu)
*******************************************************************************/
 
// auto-tests (add to test results page)
/***************************************************************************//**
  \amu_include (include/amu/validate_log.amu)
  \amu_include (include/amu/validate_results.amu)
*******************************************************************************/
 
// group(s) begin (test summary and includes-required)
/***************************************************************************//**
  \amu_include (include/amu/doxyg_define_in_parent_open.amu)
  \amu_include (include/amu/validate_summary.amu)
  \amu_include (include/amu/includes_required.amu)
*******************************************************************************/
 
// member-wide reference definitions
/***************************************************************************//**
  \amu_define group_references
  (
    [search]: https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Other_Language_Features#search
  )
*******************************************************************************/
 
// member-wide documentation and conventions
/***************************************************************************//**
  \addtogroup \amu_eval(${group})
  \details
  \anchor \amu_eval(${group})_conventions
  \par Conventions
 
  - The match-value parameter is always \p mv.
  - The match-count parameter is always \p mc. A value of 0 (or any value
    <= 0) means 'match all occurrences'. A positive value \p mc means
    'match at most \p mc occurrences'.
  - The insert-value parameter in shift_ci() is \p iv, not \p i.
    The parameter \p i is reserved for index positions throughout the group.
  - \p mv takes precedence over \p i in functions that accept both: when
    \p mv is defined, the match is by value; \p i provides an optional
    secondary element index for structured-element matching.
  - Functions that return a modified copy of \p v never modify \p v in place.
  - When \p v is not iterable, most functions return \p v unchanged.
    Exceptions are documented individually.
*******************************************************************************/
 
//----------------------------------------------------------------------------//
// members
//----------------------------------------------------------------------------//
 
//! Returns an element from an iterable if it exists, or a default value if not.
/***************************************************************************//**
  \param    v <iterable> An iterable value.
  \param    i <integer> An element index.
  \param    d <value> A default value.
 
  \returns  (1) <value> \c v[i] if it is defined, or \p d otherwise.
*******************************************************************************/
function defined_e_or
(
  v,
  i,
  d
) = !is_iterable(v) ? d
  : !is_undef( v[i] ) ? v[i]
  : d;
 
//! Returns the list element or scalar numeric value if defined, otherwise returns the default value.
/***************************************************************************//**
  \param    v <value> A value.
  \param    i <integer> An element index.
  \param    d <value> A default value.
 
  \returns  (1) <number> \c v if it is a scalar numeric value;
            (2) <value> \c v[i] if it is defined, otherwise the
                default value \p d.
*******************************************************************************/
function defined_eon_or
(
  v,
  i,
  d
) = is_num(v) ? v
  : !is_iterable(v) ? d
  : !is_undef( v[i] ) ? v[i]
  : d;
 
//! Returns the list element or scalar numeric or boolean value if defined, otherwise returns the default value.
/***************************************************************************//**
  \param    v <value> A value.
  \param    i <integer> An element index.
  \param    d <value> A default value.
 
  \returns  (1) <value> \c v if it is a scalar numeric or boolean value;
            (2) <value> \c v[i] if it is defined, otherwise the
                default value \p d.
*******************************************************************************/
function defined_eonb_or
(
  v,
  i,
  d
) = (is_num(v) || is_bool(v)) ? v
  : !is_iterable(v) ? d
  : !is_undef( v[i] ) ? v[i]
  : d;
 
//! Return the first defined specified element in a list of lists, otherwise returns the given default value.
/***************************************************************************//**
  \param    v <value> A list of \p n elements lists.
  \param    i <integer> The specified element index.
  \param    d <value> A default value.
 
  \returns  (1) <value> for the given \p v, a list of \p n lists,
                return the first element v[j][i] that is defined where
                j = [0 : n], otherwise the default value \p d.
*******************************************************************************/
function defined_fle_or
(
  v,
  i,
  d
) = !is_iterable(v) ? d
  : is_empty(v) ? d
  : let ( w = first ( v ) )
    !is_undef( w[i] ) ? w[i]
  : defined_fle_or( v=tailn(v), i=i, d=d );
 
//! Returns an element from an iterable if it exists and is a iterable, otherwise returns a default value.
/***************************************************************************//**
  \param    v <value> A value.
  \param    i <integer> An element index.
  \param    d <value> A default value.
  \param    n <integer> The optional expected element length.
 
  \returns  (1) \c v[i], a <list-n> if the element is iterable of
                length \p n (or <list> if \p n is unspecified),
            (2) or the default value \p d if the element is not defined.
*******************************************************************************/
function defined_ei_or
(
  v,
  i,
  d,
  n
) = !is_iterable(v) ? d
  : is_iterable( v[i] )
    ? is_undef( n ) ? v[i]
    : (len( v[i] ) == n) ? v[i]
      : d
  : d;
 
//! Find all occurrences of a match value in an iterable value.
/***************************************************************************//**
  \param    mv <value> A match value.
  \param    v <iterable> An iterable value.
 
  \returns  (1) <list> A list of indexes where elements match \p mv.
            (2) Returns \b empty_lst when no element of \p v matches
                \p mv or when \p v is not iterable.
*******************************************************************************/
function find_all
(
  mv,
  v
) = !is_iterable(v) ? empty_lst
  : [ for (j = [0 : len(v)-1]) if (v[j] == mv) j ];
 
//! Find the occurrences of a match value in an iterable value.
/***************************************************************************//**
  \param    mv <value> A match value.
  \param    v <iterable> An iterable value.
  \param    c <integer> A match count.
              For `(c >= 1)`, return the first \p c matches.
              For `(c <= 0)`, return all matches.
  \param    i <integer> The secondary element index to match for when
              the elements of \p v are themselves iterable elements.
 
  \param    i1 <integer> The element index of \p v where the search begins.
  \param    i2 <integer> The element index of \p v where the search ends.
 
  \returns  (1) <list> A list of indexes where elements match \p mv.
            (2) Returns \b empty_lst when no element of \p v matches
                \p mv or when \p v is not iterable.
 
  \details
 
    The use-cases for find() and [search]\‍() are summarized in the
    following tables.
 
    \b Find:
 
    | mv / v              | string | list of scalars   | list of iterables   |
    |:-------------------:|:------:|:-----------------:|:-------------------:|
    | scalar              |        | (a)               | (b) see note 1      |
    | string              | (c)    |                   | (b) see note 1      |
    | list of scalars     |        |                   | (b) see note 1      |
    | list of iterables   |        |                   | (b) see note 1      |
 
    \b Search:
 
    | mv / v              | string | list of scalars   | list of iterables   |
    |:-------------------:|:------:|:-----------------:|:-------------------:|
    | scalar              |        | (a)               | (b)                 |
    | string              | (d)    | invalid           | (e) see note 2      |
    | list of scalars     |        | (f)               | (g)                 |
    | list of iterables   |        |                   | (g)                 |
 
    \b Key:
 
    \li (a) Identify each element of \p v that equals \p mv.
    \li (b) Identify each element of \p v where \p mv equals the element at
        the specified column index, \p i, of each iterable value in \p v.
    \li (c) If, and only if, \p mv is a single character, identify each
        character in \p v that equals \p mv.
    \li (d) For each character of \p mv, identify where it exists in \p v.
        \b empty_lst is returned for each character of \p mv absent from \p v.
    \li (e) For each character of \p mv, identify where it exists in \p v
        either as a numeric value or as a character at the specified column
        index, \p i.
        \b empty_lst is returned for each character of \p mv absent from \p v.
    \li (f) For each scalar of \p mv, identify where it exists in \p v.
        \b empty_lst is returned for each scalar of \p mv absent from \p v.
    \li (g) For each element of \p mv, identify where it equals the element
        at the specified column index, \p i, of each iterable value in \p v.
        \b empty_lst is returned for each element of \p mv absent from \p v
        in the specified column index.
 
  \note     \b 1: When \p i is specified, that element column is compared.
            Otherwise, the entire element is compared. Functions find()
            and [search]\‍() behave differently in this regard.
  \note     \b 2: Invalid use combination when any element of \p v is a
            string. However, an element that is a list of one or more
            strings is valid. In which case, only the first character of
            each string element is considered.
 
  \amu_eval (${group_references})
*******************************************************************************/
function find
(
  mv,
  v,
  c = 1,
  i,
  i1 = 0,
  i2
) = !is_iterable(v) ? empty_lst                                   // not iterable
  : (!is_undef(i2) && (i1 > i2)) ? empty_lst                      // at upper index
  : (i1 > len(v)-1) ? empty_lst                                   // at end of list
  : ((is_undef(i) && (v[i1] == mv)) || (v[i1][i] == mv)) ?        // match method
    (
      (c == 1) ? [i1]                                             // one or all
    : concat(i1, find(mv, v, c-1, i, i1+1, i2))                   // add to list
    )
  : find(mv, v, c, i, i1+1, i2);                                  // no match, cont.
 
//! Count all occurrences of a match value in an iterable value.
/***************************************************************************//**
  \param    mv <value> A match value.
  \param    v <iterable> An iterable value.
  \param    s <boolean> Element matching search method.
  \param    i <integer> The secondary element index to match for when
              the elements of \p v are themselves iterable elements.
 
  \returns  (1) <integer> The number of times \p mv occurs in the list.
 
  \details
 
    When \p s == \b true, [search]\‍() is used to match elements. When
    \p s == false, find() is used.
 
  \amu_eval (${group_references})
*******************************************************************************/
function count
(
  mv,
  v,
  s = true,
  i
) = (s == false) ? len(find(mv, v, 0, i))
  : len(merge_s(search(mv, v, 0, i)));
 
//! Check for the existence of a match value in an iterable value.
/***************************************************************************//**
  \param    mv <value> A match value.
  \param    v <iterable> An iterable value.
  \param    s <boolean> Element matching search method.
  \param    i <integer> The secondary element index to match for when
              the elements of \p v are themselves iterable elements.
 
  \returns  (1) <boolean> \b true when \p mv exists in the list and
                \b false otherwise.
 
  \details
 
    When `s == true`, [search]\‍() is used to match elements. When `s ==
    false`, find() is used.
 
  \amu_eval (${group_references})
*******************************************************************************/
function exists
(
  mv,
  v,
  s = true,
  i
) = (s == false) ? (find(mv, v, 1, i) != empty_lst)
  : (strip(search(mv, v, 1, i)) != empty_lst);
 
//! Test if an element exists at a specified index of an iterable value.
/***************************************************************************//**
  \param    i <integer> An element index.
  \param    v <iterable> An iterable value.
 
  \returns  (1) <boolean> \b true when the element \p v[i], exists and
                \b false otherwise.
            (2) Returns \b undef when \p i is not an number.
 
  \note     This functions does not consider the value of the element
            at the index position, but rather if an element exists at
            the index position \p i.
*******************************************************************************/
function exists_e
(
  i,
  v
) = !is_number( i ) ? undef
  : (i < 0) ? false
  : !is_iterable( v ) ? false
  : (len(v) > i);
 
//! Return the first element of an iterable value.
/***************************************************************************//**
  \param    v <iterable> An iterable value.
 
  \returns  (1) <value> The first element of \p v.
            (2) Returns \b undef when \p v is not defined, is not
                iterable, or is empty.
 
  \details
 
  \note     Value may also be a range to obtain its \em start value.
*******************************************************************************/
function first( v ) = v[0];
 
//! Return the second element of an iterable value.
/***************************************************************************//**
  \param    v <iterable> An iterable value.
 
  \returns  (1) <value> The second element of \p v.
            (2) Returns \b undef when \p v is not defined, is not
                iterable, or is empty.
 
  \details
 
  \note     Value may also be a range to obtain its \em step value.
*******************************************************************************/
function second( v ) = v[1];
 
//! Return the third element of an iterable value.
/***************************************************************************//**
  \param    v <iterable> An iterable value.
 
  \returns  (1) <value> The third element of \p v.
            (2) Returns \b undef when \p v is not defined, is not
                iterable, or is empty.
 
  \details
 
  \note     Value may also be a range to obtain its \em end value.
*******************************************************************************/
function third( v ) = v[2];
 
//! Return the last element of an iterable value.
/***************************************************************************//**
  \param    v <iterable> An iterable value.
 
  \returns  (1) <value> The last element of \p v.
            (2) Returns \b undef when \p v is not defined, is not
                iterable, or is empty.
*******************************************************************************/
function last
(
  v
) = !is_iterable(v) ? undef
  : v[len(v)-1];
 
//! Return the middle element of an iterable value.
/***************************************************************************//**
  \param    v <iterable> An iterable value.
 
  \returns  (1) <value> The middle element of \p v.
            (2) Returns \b undef when \p v is not defined, is not
                iterable, or is empty.
*******************************************************************************/
function middle
(
  v
) = !is_iterable(v) ? undef
  : v[len(v)/2];
 
//! Return a list containing the first two elements of an iterable value.
/***************************************************************************//**
  \param    v <iterable> An iterable value.
 
  \returns  (1) <list> A list containing the first two elements of \p v.
            (2) Returns \b undef when \p v is not defined, is not
                iterable, is empty or has less than two elements
 
  \details
 
  \note     Value may also be a range.
*******************************************************************************/
function first2
(
  v
) = !is_iterable(v) ? undef
  : (len(v) < 2) ? undef
  : [v[0], v[1]];
 
//! Return a list containing the first three elements of an iterable value.
/***************************************************************************//**
  \param    v <iterable> An iterable value.
 
  \returns  (1) <list> A list containing the first three elements of \p v.
            (2) Returns \b undef when \p v is not defined, is not
                iterable, is empty, or has less than three elements.
 
  \details
 
  \note     Value may also be a range.
*******************************************************************************/
function first3
(
  v
) = !is_iterable(v) ? undef
  : (len(v) < 3) ? undef
  : [v[0], v[1], v[2]];
 
//! Return a list containing the last two elements of an iterable value.
/***************************************************************************//**
  \param    v <iterable> An iterable value.
 
  \returns  (1) <list> A list containing the last two elements of \p v.
            (2) Returns \b undef when \p v is not defined, is not
                iterable, is empty, or has less than two elements.
*******************************************************************************/
function last2
(
  v
) = !is_iterable(v) ? undef
  : let( l = len(v) )
    (l < 2) ? undef
  : [v[l-2], v[l-1]];
 
//! Return a list containing the last three elements of an iterable value.
/***************************************************************************//**
  \param    v <iterable> An iterable value.
 
  \returns  (1) <list> A list containing the last three elements of \p v.
            (2) Returns \b undef when \p v is not defined, is not
                iterable, is empty, or has less than three elements.
*******************************************************************************/
function last3
(
  v
) = !is_iterable(v) ? undef
  : let( l = len(v) )
    (l < 3) ? undef
  : [v[l-3], v[l-2], v[l-1]];
 
//! Return a list containing the first \p n elements of an iterable value.
/***************************************************************************//**
  \param    v <iterable> An iterable value.
  \param    n <integer> The element count.
 
  \returns  (1) <list> A list containing the first \p n elements of \p v.
            (2) Returns \b undef when \p v is not defined, is not
              iterable, or is empty.
 
  \details
 
    When \p n is greater than the length of the iterable \p v, the list
    will stop at the last element of \p v.
*******************************************************************************/
function firstn
(
  v,
  n = 1
) = !is_iterable(v) ? undef
  : is_empty(v) ? undef
  : n < 1 ? empty_lst
  : let ( s = min(n-1, len(v)-1) )
    [for (i = [0 : s]) v[i]];
 
//! Return a list containing the last \p n elements of an iterable value.
/***************************************************************************//**
  \param    v <iterable> An iterable value.
  \param    n <integer> The element count.
 
  \returns  (1) <list> A list containing the last \p n elements of \p v.
            (2) Returns \b undef when \p v is not defined, is not
                iterable, or is empty.
 
  \details
 
    When \p n is greater than the length of the iterable \p v, the list
    will start at the first element of \p v.
*******************************************************************************/
function lastn
(
  v,
  n = 1
) = !is_iterable(v) ? undef
  : is_empty(v) ? undef
  : n < 1 ? empty_lst
  : let ( s = max(0, len(v)-n) )
    [for (i = [s : len(v)-1]) v[i]];
 
//! Return a list containing all but the last \p n elements of an iterable value.
/***************************************************************************//**
  \param    v <iterable> An iterable value.
  \param    n <integer> The element count.
 
  \returns  (1) <list> A list containing all but the last \p n
                elements of \p v.
            (2) Returns \b empty_lst when \p v contains fewer than \p n
                elements.
            (3) Returns \b undef when \p v is not defined, is not
                iterable, or is empty.
*******************************************************************************/
function headn
(
  v,
  n = 1
) = !is_iterable(v) ? undef
  : is_empty(v) ? undef
  : (n >= len(v)) ? empty_lst
  : let ( s = min(len(v)-1, len(v)-1-n) )
    [for (i = [0 : s]) v[i]];
 
//! Return a list containing all but the first \p n elements of an iterable value.
/***************************************************************************//**
  \param    v <iterable> An iterable value.
  \param    n <integer> The element count.
 
  \returns  (1) <list> A list containing all but the first \p n
                elements of \p v.
            (2) Returns \b empty_lst when \p v contains fewer than \p n
                elements.
            (3) Returns \b undef when \p v is not defined, is not
                iterable, or is empty.
*******************************************************************************/
function tailn
(
  v,
  n = 1
) = !is_iterable(v) ? undef
  : is_empty(v) ? undef
  : (n >= len(v)) ? empty_lst
  : [for (i = [max(0, n) : len(v)-1]) v[i]];
 
//! Reverse the elements of an iterable value.
/***************************************************************************//**
  \param    v <iterable> An iterable value.
 
  \returns  (1) <list> A list containing the elements of \p v in
                reversed order.
            (2) Returns \b empty_lst when \p v is empty.
            (3) Returns \b undef when \p v is not defined or is not iterable.
*******************************************************************************/
function reverse
(
  v
) = !is_iterable(v) ? undef
  : is_empty(v) ? empty_lst
  : [for (i = [len(v)-1 : -1 : 0]) v[i]];
 
//! Circularly shift the elements of an iterable, with an optional element drop.
/***************************************************************************//**
  \param    v <iterable> An iterable value.
  \param    n <integer> The element shift count.
  \param    r <boolean> Shift the elements to the right (or left).
  \param    d <boolean> Drop elements outside of iterable value shift window.
 
  \returns  (1) <list> A list containing the elements of \p v shifted
                by \p n elements.
            (2) Returns \b undef when \p v is not defined or is not iterable.
 
  \details
 
    The shift count \p n may be positive or negative.
*******************************************************************************/
function shift_cd
(
  v,
  n = 0,
  r = true,
  d = false
) = !is_iterable(v) ? undef
  : let
    (
      l = len(v),
      s = abs(n),           // absolute magnitude
      m = s % l,            // circular magnitude
      p = (n > 0) ? r : !r  // shift direction
    )
    // drop-shift and shift magnitude greater than element count
    ( d && s > l-1 ) ? empty_lst
  : ( p ) ?
    // shift right
    [ if (m && !d) for (i = [l-m : l-1]) v[i], for (i = [0 : l-1-m]) v[i] ]
    // shift left
  : [ for (i = [m : l-1]) v[i], if (m && !d) for (i = [0 : m-1]) v[i] ];
 
//! Shift-in a value to the elements of a given iterable value.
/***************************************************************************//**
  \param    v <iterable> The iterable value.
  \param    n <integer> The element shift count.
  \param    r <boolean> Shift the elements to the right (or left).
  \param    i <value> The value to shit-in on the left or right.
 
  \returns  (1) <list> A list containing the elements of \p v shifted
                by \p n elements with the value \p i inserted on the
                left or right side of the given iterable value.
            (2) Returns \b undef when \p v is not defined or is not iterable.
 
  \details
 
    The shift count \p n may be positive or negative.
*******************************************************************************/
function shift_ci
(
  v,
  n = 0,
  r = true,
  i
) = !is_iterable(v) ? undef
  : let
    (
      l = len(v),
      s = abs(n),           // absolute magnitude
      m = s % l,            // circular magnitude
      d = (n > 0) ? r : !r  // shift direction
    )
    // shift greater than elements
    ( s > l-1 ) ? is_undef(i) ? consts(l, u=true) : consts(l, i)
    // shift direction
  : ( d ) ?
    // shift right
    [ if (m) for (j = [0 : s-1]) i, for (j = [0 : l-1-m]) v[j] ]
    // shift left
  : [ for (j = [m : l-1]) v[j], if (m) for (j = [0 : s-1]) i ];
 
//! Select a range of elements from an iterable value.
/***************************************************************************//**
  \param    v <iterable> An iterable value.
  \param    i <range | list | integer> The index selection.
 
  \returns  (1) <list> A list containing the selected elements.
            (2) Returns \b undef when \p v is not defined, is not
                iterable, or when \p i does not map to an element of \p v.
            (3) Returns \b empty_lst when \p v is empty.
*******************************************************************************/
function select_r
(
  v,
  i
) = (!is_iterable(v) || !all_defined(i)) ? undef
  : is_empty(v) ? empty_lst
  : ( !is_number(i) && !is_list(i) && !is_range(i) ) ? undef
  : is_number(i) && !is_between(i, 0, len(v)-1) ? undef
  : is_list(i)  && ((min([for (y=i) y])<0) || (max([for (y=i) y])>(len(v)-1))) ? undef
  : is_range(i) && ((min([for (y=i) y])<0) || (max([for (y=i) y])>(len(v)-1))) ? undef
  : let ( s = is_number(i) ? [i] : i )
    [for (j = [for (k=s) k]) v[j]];
 
//! Return a list of all n-element sequential-subsets of an iterable value.
/***************************************************************************//**
  \param    v <iterable> An iterable value.
  \param    n <integer> The number of elements for each subset.
  \param    s <integer> The iteration step size.
  \param    w <boolean> Use wrap-at-end circular subset selection.
 
  \returns  (1) <list-list> A list of all n-element sequential subsets
                of \p v skipping \p s elements of \p v between each
                subset selection.
            (2) Returns \b empty_lst when \p v is empty, is not defined
                or is not iterable.
 
  \details
 
    \b Example
    \code{.C}
    v = [1, 2, 3, 4];
 
    sequence_ns( v, 3, 1, false ); // [ [1,2,3], [2,3,4] ]
    sequence_ns( v, 3, 1, true );  // [ [1,2,3], [2,3,4], [3,4,1], [4,1,2] ]
    \endcode
*******************************************************************************/
function sequence_ns
(
  v,
  n = 1,
  s = 1,
  w = false
) = is_empty(v) ? empty_lst
  : [
      for (i=[0 : s : (len(v)-((w == true) ? 1 : n)) ])
      [
        for (j=[i : (i+n-1)])
          v[j % len(v)]
      ]
    ];
 
//! Return all n-sized set combinations of iterable value.
/***************************************************************************//**
  \param    v <iterable> An iterable value.
  \param    n <integer> The set size size.
 
  \returns  (1) <list-list> A list of all n-element combinations of \p v.
            (2) Returns \b empty_lst when \p v is not iterable.
*******************************************************************************/
function combine_ns
(
  v,
  n
) =
    !is_iterable(v) ? empty_lst
  : (n == 0) ? [empty_lst]
  : (len(v) < n) ? empty_lst
  : let
    (
      first = v[0],
      rest  = tailn(v),
 
      with_first =
      [
        for (c = combine_ns(rest, n - 1))
          concat([first], c)
      ],
 
      without_first = combine_ns(rest, n)
    )
    concat ( with_first, without_first );
 
//! Return all ordered n-sized set permutations of iterable value.
/***************************************************************************//**
  \param    v <iterable> An iterable value.
  \param    n <integer> The set size size.
 
  \returns  (1) <list-list> A list all ordered n-length permutations of
                \p v without repetition of elements.
            (2) Returns \b empty_lst when \p v is not iterable.
*******************************************************************************/
function permute_ns
(
  v,
  n
) =
    !is_iterable(v) ? empty_lst
  : (n == 0) ? [empty_lst]
  : (len(v) < n) ? empty_lst
  : concat
    (
      [
        for
        (
          i = [0 : len(v) - 1],
          p = let
              (
                first = firstn(v, i),
                rest  = tailn(v, i+1)
              )
              permute_ns ( concat( first, rest ), n - 1 )
        )
        concat([v[i]], p)
      ]
    );
 
//! Return all ordered n-size set permutations of iterable value with repetition allowed.
/***************************************************************************//**
  \param    v <iterable> An iterable value.
  \param    n <integer> The set size size.
 
  \returns  (1) <list-list> A list all ordered n-length permutations of
                \p v with element repetition allowed.
            (2) Returns \b empty_lst when \p v is not iterable.
*******************************************************************************/
function permute_ns_r
(
  v,
  n
) =
    !is_iterable(v) ? empty_lst
  : (n == 0) ? [empty_lst]
  : concat
    (
      [
        for ( i = v, p = permute_ns_r(v, n - 1) )
          concat([i], p)
      ]
    );
 
//! Append a value to each element of an iterable value.
/***************************************************************************//**
  \param    nv <value> A new value to append.
  \param    v <iterable> An iterable value.
 
  \param    r <boolean> Reduce list element before appending.
  \param    j <boolean> Join each appendage as a separate list.
 
  \param    l <boolean> Append new value to last element.
 
  \returns  (1) <list> A list with \p nv appended to each element of \p v.
            (2) Returns \b undef when \p v is not defined or is not iterable.
 
  \details
 
    Appending with `r == true` causes each element of \p nv to be
    appended to the elements of each iterable value. When `r == false`,
    each element of \p nv is appended to the iterable value itself. To
    append a list of elements together as a list to \p v, enclose the
    elements of \p nv with a second set of brackets.
 
    \b Example
    \code{.C}
    v1=[["a"], ["b"], ["c"], ["d"]];
    v2=[1, 2, 3];
 
    echo( append_e( v2, v1 ) );
    echo( append_e( v2, v1, r=false ) );
    echo( append_e( v2, v1, j=false, l=false ) );
    \endcode
 
    \b Result
    \code{.C}
    ECHO: [["a", 1, 2, 3], ["b", 1, 2, 3], ["c", 1, 2, 3], ["d", 1, 2, 3]]
    ECHO: [[["a"], 1, 2, 3], [["b"], 1, 2, 3], [["c"], 1, 2, 3], [["d"], 1, 2, 3]]
    ECHO: ["a", 1, 2, 3, "b", 1, 2, 3, "c", 1, 2, 3, "d"]
    \endcode
 
*******************************************************************************/
function append_e
(
  nv,
  v,
  r = true,
  j = true,
  l = true
) = !is_iterable(v) ? undef
    // when 'v' is empty
  : is_empty(v) ? ((j == true) ? [concat(nv)] : concat(nv))
    // 'v' not empty
  : let
    ( // current element 'ce'
      ce = (r == true) ? first(v) : [first(v)]
    )
    // last element of 'v'
    (len(v) == 1) ?
      (
           (j == true  && l == true ) ? [concat(ce, nv)]
         : (j == true  && l == false) ? [ce]
         : (j == false && l == true ) ?  concat(ce, nv)
         :                               ce
      )
  : (j == true) ? concat( [concat(ce, nv)], append_e(nv, tailn(v), r, j, l) )
  :               concat(  concat(ce, nv) , append_e(nv, tailn(v), r, j, l) );
 
//! Append a value to the end or beginning of an iterable value.
/***************************************************************************//**
  \param    nv <value> The value to append.
  \param    v <iterable> An iterable value.
  \param    n <integer> The element shift count.
  \param    r <boolean> Shift the elements to the right (or left).
 
  \returns  (1) <list> A list containing the elements of \p v shifted
                by \p n elements with the value \p a appended the given
                iterable value as specified.
            (2) Returns \b undef when \p v is not defined or is not iterable.
 
  \details
 
    The shift count \p n may be positive or negative.
*******************************************************************************/
function append_v
(
  nv,
  v,
  n = 0,
  r = false
) = !is_iterable(v) ? undef
  : let
    (
      s = abs(n),           // absolute magnitude
      d = (n > 0) ? r : !r  // shift direction
    )
    ( d ) ?
    // shift right, prepend
    [ for (j = [0 : s-1]) nv, for (j = v) j ]
    // shift left, append
  : [ for (j = v) j, for (j = [0 : s-1]) nv ];
 
//! Insert a new value into an iterable value.
/***************************************************************************//**
  \param    nv <value> A new value to insert.
  \param    v <iterable> An iterable value.
 
  \param    i <integer> The index insert position.
 
  \param    mv <list | string | value> Match value candidates.
  \param    mi <integer> The matched selection index.
 
  \param    s <boolean> Element matching search method.
  \param    si <integer> The search element index when matching.
 
  \returns  (1) <list> The list with \p nv inserted into \p v at the
                specified position.
            (2) Returns \b undef when no value of \p mv exists in
                \p v, when `(mi + 1)` exceeds the matched element
                count, when \p i does not map to an element of \p v, or
                when \p v is not defined or is not iterable.
 
  \details
 
    When `s == true`, [search]\‍() is used to match elements. When `s ==
    false`, find() is used.
 
    The insert position can be specified by an index, an element match
    value, or list of potential match values. When multiple matches
    exists, \p mi indicates the insert position. When more than one
    insert position criteria is specified, the order of precedence is:
    (1) \p mv then (2) \p i. To insert a list of elements together as a
    list to \p v, enclose the elements of \p nv with a second set of
    brackets.
 
  \amu_eval (${group_references})
*******************************************************************************/
function insert
(
  nv,
  v,
  i = 0,
  mv,
  mi = 0,
  s = true,
  si
) = !is_iterable(v) ? undef
    // when 'v' is empty and 'i' or 'mv' specified
  : (is_empty(v) && ( (i != 0) || !is_undef(mv)) ) ? undef
    //  when 'v' is empty, simply return 'nv'
  : is_empty(v) ? concat(nv)
  : let
    ( // identify specified insert position 'p' or return undef
      p = is_defined(mv) ?
        // search for 'mv' in 'v' selecting 'mi'
        ( s == false )  ? find(mv, v, 0, si)[mi]
                        : merge_s(search(mv, v, 0, si), false)[mi]
        // using 'i'; element position 'i' must exists in 'v' or is undef
        : !is_between(i, 0, len(v)) ? undef
        : i,
      // generate result list head 'h'
      h = ( !is_undef(p) && (p>0) ) ? [for (j = [0 : p-1]) v[j]] : empty_lst,
      // generate result list tail 't'
      t = ( is_undef(p) || (p>len(v)-1) ) ? empty_lst : [for (j = [p : len(v)-1]) v[j]]
    )
    // result valid iff a valid insert position was specified
    is_undef(p) ? undef : concat(h, nv, t);
 
//! Delete the first occurrence(s) of a matched value from an iterable value.
/***************************************************************************//**
  \param    v <iterable> The iterable value.
 
  \param    mv <value> The match value.
 
  \param    mc <integer> A match count.
            For `(mc >= 1)`, remove the first \p mc matches.
            For `(mc = 0)`, remove all matches.
 
  \returns  (1) <list> The list with the first \p mc occurrences of the
                match value removed.
            (2) Returns \b undef when \p v is not defined, or is not
                iterable.
*******************************************************************************/
function delete_first
(
  v,
  mv,
  mc = 1
) = !is_iterable(v) ? undef
  : let
    (
      p = find_all(mv, v),
      q = (mc == 0) ? p : firstn(p, mc)
    )
    [
      for (j = [0 : len(v)-1])
        if (is_empty(find_all(j, q)))
          v[j]
    ];
 
//! Delete each match value from an iterable value.
/***************************************************************************//**
  \param    v <iterable> An iterable value.
 
  \param    mv <iterable> The list of match values.
 
  \returns  (1) <list> The list with all occurrence of the match
                value removed.
*******************************************************************************/
function delete_each
(
  v,
  mv
) = is_empty(mv) ? v
  : delete_each( delete_first(v=v, mv=first(mv)), tailn(mv) );
 
//! Delete elements from an iterable value.
/***************************************************************************//**
  \param    v <iterable> An iterable value.
 
  \param    i <range | list | integer> Deletion Indexes.
 
  \param    mv <list | string | value> Match value candidates.
  \param    mc <integer> A match count.
            For `(mc >= 1)`, remove the first \p mc matches.
            For `(mc <= 0)`, remove all matches.
 
  \param    s <boolean> Element matching search method.
  \param    si <integer> The element column index when matching.
 
  \returns  (1) <list> The list with all specified elements removed.
            (2) Returns \b undef when \p i does not map to an element
                of \p v, when \p v is not defined, or is not iterable.
 
 
  \details
 
    When `s == true`, [search]\‍() is used to match elements. When `s ==
    false`, find() is used.
 
    The elements to delete can be specified by an index position, a
    list of index positions, an index range, an element match value, or
    a list of element match values (when using [search]\‍()). When \p mv
    is a list of match values, all values of \p mv that exists in \p v
    are candidates for deletion. For each matching candidate, \p mc
    indicates the quantity to remove. When more than one deletion
    criteria is specified, the order of precedence is: (1) \p mv then
    (2) \p i.
 
  \amu_eval (${group_references})
*******************************************************************************/
function delete
(
  v,
  i,
  mv,
  mc = 1,
  s = true,
  si
) = !is_iterable(v) ? undef
    // nothing to delete
  : is_empty(v) ? empty_lst
    // for 'i' a number, list or range; each indexed position must exists in 'v'
  : is_number(i) && !is_between(i, 0, len(v)-1) ? undef
  : is_list(i)  && ((min([for (y=i) y])<0) || (max([for (y=i) y])>(len(v)-1))) ? undef
  : is_range(i) && ((min([for (y=i) y])<0) || (max([for (y=i) y])>(len(v)-1))) ? undef
  : let
    ( // identify specified deletion position(s) 'p' or return undef
      p = is_defined(mv) ?
        // search for 'mv' in 'v' selecting 'mi'
        ( s == false ) ? find(mv, v, mc, si)
                       : merge_s(search(mv, v, mc, si), false)
        // using 'i'; for single number, format as list
        : is_number(i) ? [i]
        // using 'i';  pass list as specified
        : is_list(i) ? i
        // using 'i';  enumerate range to list
        : is_range(i) ? [for (y=i) y]
        : undef
    )
    [ // output only elements of 'v' that do not exists in 'p'
      for (j = [0 : len(v)-1])
        if (is_empty(find(j, p))) v[j]
    ];
 
//! Replace the first occurrence(s) of a matched value in iterable value.
/***************************************************************************//**
  \param    v <iterable> The iterable value.
 
  \param    mv <value> The match value.
  \param    nv <value> The new value.
 
  \param    mc <integer> A match count.
            For `(mc >= 1)`, replaces the first \p mc matches.
            For `(mc = 0)`, replaces all matches.
 
  \returns  (1) <list> The list with the first \mc occurrences of the
                match value replaced by \p nv.
            (2) Returns \b undef when \p v is not defined, or is not
                iterable.
*******************************************************************************/
function replace_first
(
  v,
  mv,
  nv,
  mc = 1
) = !is_iterable(v) ? undef
  : let
    (
      p = find_all(mv, v),
      q = (mc == 0) ? p : firstn(p, mc)
    )
    [
      for (j = [0 : len(v)-1])
        if (is_empty(find_all(j, q)))
          v[j]
        else
          nv
    ];
 
//! Strip all matching values from an iterable value.
/***************************************************************************//**
  \param    v <iterable> An iterable value.
  \param    mv <value> A match value.
 
  \returns  (1) <list> The list 'v' with all elements equal \p mv removed.
            (2) Returns \b undef when \p v is not defined or is not iterable.
*******************************************************************************/
function strip
(
  v,
  mv = empty_lst
) = !is_iterable(v) ? undef
  : [for (e = v) if (e != mv) e];
 
//! Apply a binary mask to an interable value.
/***************************************************************************//**
  \param    v <iterable> An iterable value.
  \param    m <iterable> A binary mask list (or string) of \p 0 or \p 1.
  \param    r <boolean> Right align the mask to \p v value.
  \param    o <integer> A positive or negative mask offset.
  \param    u <value> The value assigned to elements of the mask that
              does not exists or are undefined in \p v.
  \param    z <value> The value assigned to masked elements.
 
  \returns  (1) <value> A list containing the masked values of \p v.
            (2) Returns \b v as a list when \p m is not defined.
            (3) Returns \p undef when \p m is not iterable or contains
                values other than zero or one.
 
  \details
 
    This mask may be specified as a list or string and is composed of
    ones and zeros. One indicates that an element value of \p v is
    passed and a zero indicates that a value of \p v is to be replaced
    with \p z.
*******************************************************************************/
function mask
(
  v,
  m,
  r = false,
  o = 0,
  u = undef,
  z = 0
) = is_undef(m) ? headn(v, 0)
    // if defined, 'm' must be iterable
  : !is_iterable(m) ? undef
    // string mask may only include "01"
  : is_string(m) && !is_empty(delete(m, mv="01", mc=0)) ? undef
    // list mask may only include [0, 1]
  : is_list(m) && !is_empty(delete(m, mv=[0,1], mc=0)) ? undef
  : let
    ( // calculate the mask base offset
      l = is_iterable(v) ? len(v) : 0,
      j = ((r == true) ? l - len(m) : 0) + o
    )
    [
      for (i = [0 : len(m)-1])
        (m[i] == 1 || m[i] == "1") ? defined_e_or(v, i+j, u)
                                   : exists_e(i+j, v) ? z : u
    ];
 
//! Return a list of the unique elements of an iterable value.
/***************************************************************************//**
  \param    v <iterable> An iterable value.
 
  \returns  (1) <list> A list of unique elements with order preserved.
            (2) Returns \b undef when \p v is not defined or is not
                iterable.
 
  \warning  Any and all list elements of \p v that have the value of \b
            undef are ignored and is not considered to be a unique.
*******************************************************************************/
function unique
(
  v
) = is_undef(v) ? empty_lst
  : !is_iterable(v) ? [v]
    // handled empty list or empty string
  : (len(v) == 0) ? empty_lst
  // last element. filter case where first element of list is [undef]
  : (len(v) == 1) ? (v == [undef]) ? empty_lst : headn(v, 0)
    // set s=false to use find() for single element matching
  : exists(last(v), headn(v), s=false) ? unique(headn(v))
  : concat(unique(headn(v)), lastn(v));
 
//! Return a list of the common elements of two iterable values.
/***************************************************************************//**
  \param    v1 <iterable> The first iterable value.
  \param    v2 <iterable> The second iterable value.
 
  \param    e <iterable> The common elements list (used for recursion
            value tracking or may be initialed by user).
 
  \returns  (1) <list> The list of elements common to both iterable
                values as list intersection with a one-to-one
                correspondence among the elements.
            (2) Returns \b empty_lst when either \p v1 or \p v2 is
                empty.
*******************************************************************************/
function common
(
  v1,
  v2,
  e = empty_lst
) = let( mv = first(v1) )
    is_empty(v1) ? e
  : (find_all(mv, v2) != empty_lst) ?
    common( tailn(v1), delete_first(v=v2, mv=mv), concat(e, [mv]) )
  : common( tailn(v1), delete_first(v=v2, mv=mv), e);
 
//! Return a list of the elements not present in both iterable values.
/***************************************************************************//**
  \param    v1 <iterable> The first iterable value.
  \param    v2 <iterable> The second iterable value.
 
  \returns  (1) <list> The list of elements that do not exists in both
                iterable values as a list difference with a one-to-one
                correspondence among the elements.
            (2) Returns \b empty_lst when \p v1 and \p v2 are
                identical, or when both are empty.
*******************************************************************************/
function not_common
(
  v1,
  v2
) = let
    (
      d1 = delete_each(v1, v2),
      d2 = delete_each(v2, v1)
    )
    concat(d1, d2);
 
 
//! @}
//! @}
 
//----------------------------------------------------------------------------//
// openscad-amu auxiliary scripts
//----------------------------------------------------------------------------//
 
/*
BEGIN_SCOPE validate;
  BEGIN_OPENSCAD;
    include <omdl-base.scad>;
    include <common/validation.scad>;
 
    function fmt( id, td, v1, v2, v3 ) = table_validate_fmt(id, td, v1, v2, v3);
    function v1(db, id) = table_validate_get_v1(db, id);
    t = true; f = false; u = undef; s = validation_skip;
 
    tbl_test_values =
    [
      fmt("t01", "The undefined value",       undef),
      fmt("t02", "The empty list",            empty_lst),
      fmt("t03", "A long range",              [0:0.5:9]),
      fmt("t04", "string = (A string)",       "A string"),
      fmt("t05", "List-4 fruit",              ["orange","apple","grape","banana"]),
      fmt("t06", "List-7 characters",         ["b","a","n","a","n","a","s"]),
      fmt("t07", "List-1 undefined",          [undef]),
      fmt("t08", "List-2 integers-2",         [[1,2],[2,3]]),
      fmt("t09", "List-4 iterable-2",         ["ab",[1,2],[2,3],[4,5]]),
      fmt("t10", "List-4  iterable-3",        [[1,2,3],[4,5,6],[7,8,9],["a","b","c"]]),
      fmt("t11", "List-15 of integers",       [for (i=[0:15]) i])
    ];
 
    tbl_test_answers =
    [
      ["defined_e_or_DE3",
        "default",                                          // t01
        "default",                                          // t02
        "default",                                          // t03
        "t",                                                // t04
        "banana",                                           // t05
        "a",                                                // t06
        "default",                                          // t07
        "default",                                          // t08
        [4,5],                                              // t09
        ["a","b","c"],                                      // t10
        3                                                   // t11
      ],
      ["find_12",
        empty_lst,                                          // t01
        empty_lst,                                          // t02
        empty_lst,                                          // t03
        empty_lst,                                          // t04
        empty_lst,                                          // t05
        empty_lst,                                          // t06
        empty_lst,                                          // t07
        [0],                                                // t08
        [1],                                                // t09
        empty_lst,                                          // t10
        empty_lst                                           // t11
      ],
      ["count_S1",
        0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1
      ],
      ["exists_S1",
        f, f, f, f, f, f, f, t, t, t, t
      ],
      ["exists_e_5",
        f, f, f, t, f, t, f, f, f, f, t
      ],
      ["first",
        undef,                                              // t01
        undef,                                              // t02
        0,                                                  // t03
        "A",                                                // t04
        "orange",                                           // t05
        "b",                                                // t06
        undef,                                              // t07
        [1,2],                                              // t08
        "ab",                                               // t09
        [1,2,3],                                            // t10
        0                                                   // t11
      ],
      ["second",
        undef,                                              // t01
        undef,                                              // t02
        0.5,                                                // t03
        " ",                                                // t04
        "apple",                                            // t05
        "a",                                                // t06
        undef,                                              // t07
        [2,3],                                              // t08
        [1,2],                                              // t09
        [4,5,6],                                            // t10
        1                                                   // t11
      ],
      ["third",
        undef,                                              // t01
        undef,                                              // t02
        9,                                                  // t03
        "s",                                                // t04
        "grape",                                            // t05
        "n",                                                // t06
        undef,                                              // t07
        undef,                                              // t08
        [2,3],                                              // t09
        [7,8,9],                                            // t10
        2                                                   // t11
      ],
      ["last",
        undef,                                              // t01
        undef,                                              // t02
        undef,                                              // t03
        "g",                                                // t04
        "banana",                                           // t05
        "s",                                                // t06
        undef,                                              // t07
        [2,3],                                              // t08
        [4,5],                                              // t09
        ["a","b","c"],                                      // t10
        15                                                  // t11
      ],
      ["middle",
        undef,                                              // t01
        undef,                                              // t02
        undef,                                              // t03
        "r",                                                // t04
        "grape",                                            // t05
        "a",                                                // t06
        undef,                                              // t07
        [2,3],                                              // t08
        [2,3],                                              // t09
        [7,8,9],                                            // t10
        8                                                   // t11
      ],
      ["first2",
        undef,                                              // t01
        undef,                                              // t02
        undef,                                              // t03
        ["A"," "],                                          // t04
        ["orange","apple"],                                 // t05
        ["b","a"],                                          // t06
        undef,                                              // t07
        [[1,2],[2,3]],                                      // t08
        ["ab", [1,2]],                                      // t09
        [[1,2,3],[4,5,6]],                                  // t10
        [0,1]                                               // t11
      ],
      ["first3",
        undef,                                              // t01
        undef,                                              // t02
        undef,                                              // t03
        ["A"," ","s"],                                      // t04
        ["orange","apple","grape"],                         // t05
        ["b","a","n"],                                      // t06
        undef,                                              // t07
        undef,                                              // t08
        ["ab", [1,2],[2,3]],                                // t09
        [[1,2,3],[4,5,6],[7,8,9]],                          // t10
        [0,1,2]                                             // t11
      ],
      ["last2",
        undef,                                              // t01
        undef,                                              // t02
        undef,                                              // t03
        ["n","g"],                                          // t04
        ["grape","banana"],                                 // t05
        ["a","s"],                                          // t06
        undef,                                              // t07
        [[1,2],[2,3]],                                      // t08
        [[2,3], [4,5]],                                     // t09
        [[7,8,9],["a","b","c"]],                            // t10
        [14,15]                                             // t11
      ],
      ["last3",
        undef,                                              // t01
        undef,                                              // t02
        undef,                                              // t03
        ["i","n","g"],                                      // t04
        ["apple","grape","banana"],                         // t05
        ["n","a","s"],                                      // t06
        undef,                                              // t07
        undef,                                              // t08
        [[1,2],[2,3],[4,5]],                                // t09
        [[4,5,6],[7,8,9],["a","b","c"]],                    // t10
        [13,14,15]                                          // t11
      ],
      ["firstn_1",
        undef,                                              // t01
        undef,                                              // t02
        undef,                                              // t03
        ["A"],                                              // t04
        ["orange"],                                         // t05
        ["b"],                                              // t06
        [undef],                                            // t07
        [[1,2]],                                            // t08
        ["ab"],                                             // t09
        [[1,2,3]],                                          // t10
        [0]                                                 // t11
      ],
      ["lastn_1",
        undef,                                              // t01
        undef,                                              // t02
        undef,                                              // t03
        ["g"],                                              // t04
        ["banana"],                                         // t05
        ["s"],                                              // t06
        [undef],                                            // t07
        [[2,3]],                                            // t08
        [[4,5]],                                            // t09
        [["a","b","c"]],                                    // t10
        [15]                                                // t11
      ],
      ["headn_1",
        undef,                                              // t01
        undef,                                              // t02
        undef,                                              // t03
        ["A"," ","s","t","r","i","n"],                      // t04
        ["orange","apple","grape"],                         // t05
        ["b","a","n","a","n","a"],                          // t06
        empty_lst,                                          // t07
        [[1,2]],                                            // t08
        ["ab",[1,2],[2,3]],                                 // t09
        [[1,2,3],[4,5,6],[7,8,9]],                          // t10
        [0,1,2,3,4,5,6,7,8,9,10,11,12,13,14]                // t11
      ],
      ["tailn_1",
        undef,                                              // t01
        undef,                                              // t02
        undef,                                              // t03
        [" ","s","t","r","i","n","g"],                      // t04
        ["apple","grape","banana"],                         // t05
        ["a","n","a","n","a","s"],                          // t06
        empty_lst,                                          // t07
        [[2,3]],                                            // t08
        [[1,2],[2,3],[4,5]],                                // t09
        [[4,5,6],[7,8,9],["a","b","c"]],                    // t10
        [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15]               // t11
      ],
      ["reverse",
        undef,                                              // t01
        empty_lst,                                          // t02
        undef,                                              // t03
        ["g","n","i","r","t","s"," ","A"],                  // t04
        ["banana","grape","apple","orange"],                // t05
        ["s","a","n","a","n","a","b"],                      // t06
        [undef],                                            // t07
        [[2,3],[1,2]],                                      // t08
        [[4,5],[2,3],[1,2],"ab"],                           // t09
        [["a","b","c"],[7,8,9],[4,5,6],[1,2,3]],            // t10
        [15,14,13,12,11,10,9,8,7,6,5,4,3,2,1,0]             // t11
      ],
      ["shift_cd_r1",
        undef,                                              // t01
        empty_lst,                                          // t02
        undef,                                              // t03
        ["g","A"," ","s","t","r","i","n"],                  // t04
        ["banana","orange","apple","grape"],                // t05
        ["s","b","a","n","a","n","a"],                      // t06
        [undef],                                            // t07
        [[2,3],[1,2]],                                      // t08
        [[4,5],"ab",[1,2],[2,3]],                           // t09
        [["a","b","c"],[1,2,3],[4,5,6],[7,8,9]],            // t10
        [15,0,1,2,3,4,5,6,7,8,9,10,11,12,13,14]             // t11
      ],
      ["shift_cd_l1",
        undef,                                              // t01
        empty_lst,                                          // t02
        undef,                                              // t03
        [" ","s","t","r","i","n","g","A"],                  // t04
        ["apple","grape","banana","orange"],                // t05
        ["a","n","a","n","a","s","b"],                      // t06
        [undef],                                            // t07
        [[2,3],[1,2]],                                      // t08
        [[1,2],[2,3],[4,5],"ab"],                           // t09
        [[4,5,6],[7,8,9],["a","b","c"],[1,2,3]],            // t10
        [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,0]             // t11
      ],
      ["select_r_02",
        undef,                                              // t01
        empty_lst,                                          // t02
        undef,                                              // t03
        ["A"," ","s"],                                      // t04
        ["orange","apple","grape"],                         // t05
        ["b","a","n"],                                      // t06
        undef,                                              // t07
        undef,                                              // t08
        ["ab",[1,2],[2,3]],                                 // t09
        [[1,2,3],[4,5,6],[7,8,9]],                          // t10
        [0,1,2]                                             // t11
      ],
      ["sequence_ns_31",
        empty_lst,                                          // t01
        empty_lst,                                          // t02
        empty_lst,                                          // t03
        [
          ["A"," ","s"],[" ","s","t"],["s","t","r"],
          ["t","r","i"],["r","i","n"],["i","n","g"]
        ],                                                  // t04
        [
          ["orange","apple","grape"],
          ["apple","grape","banana"]
        ],                                                  // t05
        [
          ["b","a","n"],["a","n","a"],["n","a","n"],
          ["a","n","a"],["n","a","s"]
        ],                                                  // t06
        empty_lst,                                          // t07
        empty_lst,                                          // t08
        [["ab",[1,2],[2,3]],[[1,2],[2,3],[4,5]]],           // t09
        [
          [[1,2,3],[4,5,6],[7,8,9]],
          [[4,5,6],[7,8,9],["a","b","c"]]
        ],                                                  // t10
        [
          [0,1,2],[1,2,3],[2,3,4],[3,4,5],[4,5,6],[5,6,7],
          [6,7,8],[7,8,9],[8,9,10],[9,10,11],[10,11,12],
          [11,12,13],[12,13,14],[13,14,15]
        ]                                                   // t11
      ],
      ["append_e_T0",
        undef,                                              // t01
        [[0]],                                              // t02
        undef,                                              // t03
        [
          ["A",0],[" ",0],["s",0],["t",0],
          ["r",0],["i",0],["n",0],["g",0]
        ],                                                  // t04
        [
          ["orange",0],["apple",0],
          ["grape",0],["banana",0]
        ],                                                  // t05
        [
          ["b",0],["a",0],["n",0],["a",0],
          ["n",0],["a",0],["s",0]
        ],                                                  // t06
        [[undef,0]],                                        // t07
        [[1,2,0],[2,3,0]],                                  // t08
        [["ab",0],[1,2,0],[2,3,0],[4,5,0]],                 // t09
        [[1,2,3,0],[4,5,6,0],[7,8,9,0],["a","b","c",0]],    // t10
        [
          [0,0],[1,0],[2,0],[3,0],[4,0],[5,0],
          [6,0],[7,0],[8,0],[9,0],[10,0],[11,0],
          [12,0],[13,0],[14,0],[15,0]
        ]                                                   // t11
      ],
      ["insert_T0",
        undef,                                              // t01
        undef,                                              // t02
        undef,                                              // t03
        undef,                                              // t04
        ["orange",0,"apple","grape","banana"],              // t05
        ["b","a","n","a","n","a",0,"s"],                    // t06
        undef,                                              // t07
        [[1,2],0,[2,3]],                                    // t08
        ["ab",[1,2],0,[2,3],[4,5]],                         // t09
        undef,                                              // t10
        [0,1,2,3,4,0,5,6,7,8,9,10,11,12,13,14,15]           // t11
      ],
      ["delete_T0",
        undef,                                              // t01
        empty_lst,                                          // t02
        undef,                                              // t03
        ["A"," ","s","t","r","i","n","g"],                  // t04
        ["orange","grape","banana"],                        // t05
        ["b","a","n","a","n","a"],                          // t06
        [undef],                                            // t07
        [[1,2]],                                            // t08
        ["ab",[1,2],[4,5]],                                 // t09
        [[1,2,3],[4,5,6],[7,8,9],["a","b","c"]],            // t10
        [0,1,2,3,4,6,7,8,9,10,11,12,13,14,15]               // t11
      ],
      ["strip",
        undef,                                              // t01
        empty_lst,                                          // t02
        undef,                                              // t03
        ["A"," ","s","t","r","i","n","g"],                  // t04
        ["orange","apple","grape","banana"],                // t05
        ["b","a","n","a","n","a","s"],                      // t06
        [undef],                                            // t07
        [[1,2],[2,3]],                                      // t08
        ["ab",[1,2],[2,3],[4,5]],                           // t09
        [[1,2,3],[4,5,6],[7,8,9],["a","b","c"]],            // t10
        [0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15]             // t11
      ],
      ["mask_01R",
        [undef,undef],                                      // t01
        [undef,undef],                                      // t02
        [undef,undef],                                      // t03
        [0,"g"],                                            // t04
        [0,"banana"],                                       // t05
        [0,"s"],                                            // t06
        [undef,undef],                                      // t07
        [0,[2,3]],                                          // t08
        [0,[4,5]],                                          // t09
        [0,["a","b","c"]],                                  // t10
        [0,15]                                              // t11
      ],
      ["unique",
        empty_lst,                                          // t01
        empty_lst,                                          // t02
        [[0:0.5:9]],                                        // t03
        ["A"," ","s","t","r","i","n","g"],                  // t04
        ["orange","apple","grape","banana"],                // t05
        ["b","a","n","s"],                                  // t06
        empty_lst,                                          // t07
        [[1,2],[2,3]],                                      // t08
        ["ab",[1,2],[2,3],[4,5]],                           // t09
        [[1,2,3],[4,5,6],[7,8,9],["a","b","c"]],            // t10
        [0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15]             // t11
      ]
    ];
 
    db = table_validate_init( tbl_test_values, tbl_test_answers );
 
    table_validate_start( db );
    test_ids = table_validate_get_ids( db );
 
    for (id=test_ids) table_validate( db, id, "defined_e_or_DE3", 1, defined_e_or( v1(db,id), 3, "default" ) );
    for (id=test_ids) table_validate( db, id, "defined_e_or_DE3", 1, defined_eon_or( v1(db,id), 3, "default" ) );
    // defined_eonb_or()
    // defined_fle_or()
    // defined_ei_or()
    // find_all()
    for (id=test_ids) table_validate( db, id, "find_12", 1, find( [1,2], v1(db,id) ) );
    for (id=test_ids) table_validate( db, id, "count_S1", 1, count( 1, v1(db,id), true ) );
    for (id=test_ids) table_validate( db, id, "exists_S1", 1, exists( 1, v1(db,id), true ) );
    for (id=test_ids) table_validate( db, id, "exists_e_5", 1, exists_e( 5, v1(db,id )) );
    for (id=test_ids) table_validate( db, id, "first", 1, first( v1(db,id) ) );
    for (id=test_ids) table_validate( db, id, "second", 1, second( v1(db,id) ) );
    for (id=test_ids) table_validate( db, id, "third", 1, third( v1(db,id) ) );
    for (id=test_ids) table_validate( db, id, "last", 1, last( v1(db,id) ) );
    for (id=test_ids) table_validate( db, id, "middle", 1, middle( v1(db,id) ) );
    for (id=test_ids) table_validate( db, id, "first2", 1, first2( v1(db,id) ) );
    for (id=test_ids) table_validate( db, id, "first3", 1, first3( v1(db,id) ) );
    for (id=test_ids) table_validate( db, id, "last2", 1, last2( v1(db,id) ) );
    for (id=test_ids) table_validate( db, id, "last3", 1, last3( v1(db,id) ) );
    for (id=test_ids) table_validate( db, id, "firstn_1", 1, firstn( v1(db,id), n=1 ) );
    for (id=test_ids) table_validate( db, id, "lastn_1", 1, lastn( v1(db,id), n=1 ) );
    for (id=test_ids) table_validate( db, id, "headn_1", 1, headn( v1(db,id), n=1 ) );
    for (id=test_ids) table_validate( db, id, "tailn_1", 1, tailn( v1(db,id), n=1 ) );
    for (id=test_ids) table_validate( db, id, "reverse", 1, reverse( v1(db,id) ) );
    for (id=test_ids) table_validate( db, id, "shift_cd_r1", 1, shift_cd( v1(db,id), n=1, r=true ) );
    for (id=test_ids) table_validate( db, id, "shift_cd_l1", 1, shift_cd( v1(db,id), n=1, r=false ) );
    // shift_ci()
    for (id=test_ids) table_validate( db, id, "select_r_02", 1, select_r( v1(db,id), i=[0:2] ) );
    for (id=test_ids) table_validate( db, id, "sequence_ns_31", 1, sequence_ns( v1(db,id), n=3, s=1 ) );
    // combine_ns()
    // permute_ns()
    // permute_ns_r()
    for (id=test_ids) table_validate( db, id, "append_e_T0", 1, append_e( 0, v1(db,id) ) );
    // append_v()
    for (id=test_ids) table_validate( db, id, "insert_T0", 1, insert( 0, v1(db,id), mv=["x","r","apple","s",[2,3],5] ) );
    // delete_first()
    // delete_each()
    for (id=test_ids) table_validate( db, id, "delete_T0", 1, delete( v1(db,id), mv=["x","r","apple","s",[2,3],5] ) );
    // replace_first()
    for (id=test_ids) table_validate( db, id, "strip", 1, strip( v1(db,id) ) );
    for (id=test_ids) table_validate( db, id, "mask_01R", 1, mask( v1(db,id), [0,1], r=true ) );
    for (id=test_ids) table_validate( db, id, "unique", 1, unique( v1(db,id) ) );
    // common()
    // not_common()
 
    // end_include
  END_OPENSCAD;
 
  BEGIN_MFSCRIPT;
    include --path "${INCLUDE_PATH}" {var_init,var_gen_term}.mfs;
    include --path "${INCLUDE_PATH}" scr_make_mf.mfs;
  END_MFSCRIPT;
END_SCOPE;
*/
 
//----------------------------------------------------------------------------//
// end of file
//----------------------------------------------------------------------------//