Operations for iterable data types. More...

Collaboration diagram for Iterable Operations:

Files
file	iterable_operate.scad
	Iterable data type operations.

Functions
function	defined_e_or (v, i, d)
	Return an element of an iterable when it exists or a default value otherwise. More...

function	find (mv, v, c=1, i, i1=0, i2)
	Find the occurrences of a match value in an iterable value. More...

function	count (mv, v, s=true, i)
	Count all occurrences of a match value in an iterable value. More...

function	exists (mv, v, s=true, i)
	Check for the existence of a match value in an iterable value. More...

function	exists_e (i, v)
	Test if an element exists at a specified index of an iterable value. More...

function	first (v)
	Return the first element of an iterable value. More...

function	second (v)
	Return the second element of an iterable value. More...

function	third (v)
	Return the third element of an iterable value. More...

function	last (v)
	Return the last element of an iterable value. More...

function	middle (v)
	Return the middle element of an iterable value. More...

function	first2 (v)
	Return a list containing the first two elements of an iterable value. More...

function	first3 (v)
	Return a list containing the first three elements of an iterable value. More...

function	last2 (v)
	Return a list containing the last two elements of an iterable value. More...

function	last3 (v)
	Return a list containing the last three elements of an iterable value. More...

function	firstn (v, n=1)
	Return a list containing the first `n` elements of an iterable value. More...

function	lastn (v, n=1)
	Return a list containing the last `n` elements of an iterable value. More...

function	headn (v, n=1)
	Return a list containing all but the last `n` elements of an iterable value. More...

function	tailn (v, n=1)
	Return a list containing all but the first `n` elements of an iterable value. More...

function	reverse (v)
	Reverse the elements of an iterable value. More...

function	shift (v, n=0, r=true, c=true)
	Shift the elements of an iterable value. More...

function	select_r (v, i)
	Select a range of elements from an iterable value. More...

function	sequence_ns (v, n=1, s=1, w=false)
	Return a list of all n-element sequential-subsets of an iterable value. More...

function	append_e (nv, v, r=true, j=true, l=true)
	Append a value to each element of an iterable value. More...

function	insert (nv, v, i=0, mv, mi=0, s=true, si)
	Insert a new value into an iterable value. More...

function	delete (v, i, mv, mc=1, s=true, si)
	Delete elements from an iterable value. More...

function	strip (v, mv=empty_lst)
	Strip all matching values from an iterable value. More...

function	mask (v, m, r=false, o=0, u=undef, z=0)
	Apply a binary mask to an interable value. More...

function	unique (v)
	Return a list of the unique elements of an iterable value. More...

Detailed Description

Operations for iterable data types.

Requires:
include <omdl-base.scad>;

Validation Summary

file	group	script	results	no test	skipped	passed	failed	warning
datatypes/iterable_operate.scad	Iterable Operations	Script	Results	0	0	319	0	0

No Failures

See complete validation results.

Function Documentation

◆ append_e()

function append_e	(	nv	,
		v	,
		r	= `true`,
		j	= `true`,
		l	= `true`
	)

Append a value to each element of an iterable value.

Parameters

nv	<value> A new value to append.
v	<iterable> An iterable value.
r	<boolean> Reduce list element before appending.
j	<boolean> Join each appendage as a separate list.
l	<boolean> Append new value to last element.

Returns: (1) <list> A list with nv appended to each element of v. (2) Returns undef when v is not defined or is not iterable.

Appending with r == true causes each element of nv to be appended to the elements of each iterable value. When r == false, each element of nv is appended to the iterable value itself. To append a list of elements together as a list to v, enclose the elements of nv with a second set of brackets.

Example

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 ) );

Result

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"]

◆ count()

function count	(	mv	,
		v	,
		s	= `true`,
		i
	)

Count all occurrences of a match value in an iterable value.

Parameters

mv	<value> A match value.
v	<iterable> An iterable value.
s	<boolean> Element matching search method.
i	<integer> The secondary element index to match for when the elements of `v` are themselves iterable elements.

Returns: (1) <integer> The number of times mv occurs in the list.

When s == true, search() is used to match elements. When s == false, find() is used.

Here is the caller graph for this function:

◆ defined_e_or()

function defined_e_or	(	v	,
		i	,
		d
	)

Return an element of an iterable when it exists or a default value otherwise.

Parameters

v	<iterable> An iterable value.
i	<integer> An element index.
d	<value> A default value.

Returns: (1) <value> v[i] when it is defined or d otherwise.

Here is the caller graph for this function:

◆ delete()

function delete	(	v	,
		i	,
		mv	,
		mc	= `1`,
		s	= `true`,
		si
	)

Delete elements from an iterable value.

Parameters

v	<iterable> An iterable value.
i	<range\|list\|integer> Deletion Indexes.
mv	<list\|string\|value> Matched value candidates.
mc	<integer> A match count. For `(mc>=1)`, remove the first `mc` matches. For `(mc<=0)`, remove all matches.
s	<boolean> Element matching search method.
si	<integer> The element column index when matching.

Returns: (1) <list> A list with all specified elements removed. (2) Returns undef when i does not map to an element of v, when v is not defined, or is not iterable.

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 mv is a list of match values, all values of mv that exists in v are candidates for deletion. For each matching candidate, mc indicates the quantity to remove. When more than one deletion criteria is specified, the order of precedence is: (1) mv then (2) i.

◆ exists()

function exists	(	mv	,
		v	,
		s	= `true`,
		i
	)

Check for the existence of a match value in an iterable value.

Parameters

mv	<value> A match value.
v	<iterable> An iterable value.
s	<boolean> Element matching search method.
i	<integer> The secondary element index to match for when the elements of `v` are themselves iterable elements.

Returns: (1) <boolean> true when mv exists in the list and false otherwise.

When s == true, search() is used to match elements. When s == false, find() is used.

◆ exists_e()

function exists_e	(	i	,
		v
	)

Test if an element exists at a specified index of an iterable value.

Parameters

i	<integer> An element index.
v	<iterable> An iterable value.

Returns: (1) <boolean> true when the element v[i], exists and false otherwise. (2) Returns undef when 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 i.

◆ find()

function find	(	mv	,
		v	,
		c	= `1`,
		i	,
		i1	= `0`,
		i2
	)

Find the occurrences of a match value in an iterable value.

Parameters

mv	<value> A match value.
v	<iterable> An iterable value.
c	<integer> A match count. For `(c>=1)`, return the first `c` matches. For `(c<=0)`, return all matches.
i	<integer> The secondary element index to match for when the elements of `v` are themselves iterable elements.
i1	<integer> The element index of `v` where the search begins.
i2	<integer> The element index of `v` where the search ends.

Returns: (1) <list> A list of indexes where elements match mv. (2) Returns empty_lst when no element of v matches mv or when v is not iterable.

The use-cases for find() and search() are summarized in the following tables.

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

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)

Key:

(a) Identify each element of v that equals mv.
(b) Identify each element of v where mv equals the element at the specified column index, i, of each iterable value in v.
(c) If, and only if, mv is a single character, identify each character in v that equals mv.
(d) For each character of mv, identify where it exists in v. empty_lst is returned for each character of mv absent from v.
(e) For each character of mv, identify where it exists in v either as a numeric value or as a character at the specified column index, i. empty_lst is returned for each character of mv absent from v.
(f) For each scalar of mv, identify where it exists in v. empty_lst is returned for each scalar of mv absent from v.
(g) For each element of mv, identify where it equals the element at the specified column index, i, of each iterable value in v. empty_lst is returned for each element of mv absent from v in the specified column index.

Note: 1: When i is specified, that element column is compared. Otherwise, the entire element is compared. Functions find() and search() behave differently in this regard.; 2: Invalid use combination when any element of 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.

◆ first()

function first ( v )

Return the first element of an iterable value.

Parameters

v	<iterable> An iterable value.

Returns: (1) <value> The first element of v. (2) Returns undef when v is not defined, is not iterable, or is empty.

Note: Value may also be a range to obtain its start value.

Here is the caller graph for this function:

◆ first2()

function first2 ( v )

Return a list containing the first two elements of an iterable value.

Parameters

v	<iterable> An iterable value.

Returns: (1) <list> A list containing the first two elements of v. (2) Returns undef when v is not defined, is not iterable, is empty or has less than two elements

Note: Value may also be a range.

◆ first3()

function first3 ( v )

Return a list containing the first three elements of an iterable value.

Parameters

v	<iterable> An iterable value.

Returns: (1) <list> A list containing the first three elements of v. (2) Returns undef when v is not defined, is not iterable, is empty, or has less than three elements.

Note: Value may also be a range.

◆ firstn()

function firstn	(	v	,
		n	= `1`
	)

Return a list containing the first n elements of an iterable value.

Parameters

v	<iterable> An iterable value.
n	<integer> The element count.

Returns: (1) <list> A list containing the first n elements of v. (2) Returns undef when v is not defined, is not iterable, or is empty.

When n is greater than the length of the iterable v, the list will stop at the last element of v.

Here is the caller graph for this function:

◆ headn()

function headn	(	v	,
		n	= `1`
	)

Return a list containing all but the last n elements of an iterable value.

Parameters

v	<iterable> An iterable value.
n	<integer> The element count.

Returns: (1) <list> A list containing all but the last n elements of v. (2) Returns empty_lst when v contains fewer than n elements. (3) Returns undef when v is not defined, is not iterable, or is empty.

Here is the caller graph for this function:

◆ insert()

function insert	(	nv	,
		v	,
		i	= `0`,
		mv	,
		mi	= `0`,
		s	= `true`,
		si
	)

Insert a new value into an iterable value.

Parameters

nv	<value> A new value to insert.
v	<iterable> An iterable value.
i	<integer> The index insert position.
mv	<list\|string\|value> Matched value candidates.
mi	<integer> The matched selection index.
s	<boolean> Element matching search method.
si	<integer> The search element index when matching.

Returns: (1) <list> A list with nv inserted into v at the specified position. (2) Returns undef when no value of mv exists in v, when (mi + 1) exceeds the matched element count, when i does not map to an element of v, or when v is not defined or is not iterable.

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, mi indicates the insert position. When more than one insert position criteria is specified, the order of precedence is: (1) mv then (2) i. To insert a list of elements together as a list to v, enclose the elements of nv with a second set of brackets.

◆ last()

function last ( v )

Return the last element of an iterable value.

Parameters

v	<iterable> An iterable value.

Returns: (1) <value> The last element of v. (2) Returns undef when v is not defined, is not iterable, or is empty.

Here is the caller graph for this function:

◆ last2()

function last2 ( v )

Return a list containing the last two elements of an iterable value.

Parameters

v	<iterable> An iterable value.

Returns: (1) <list> A list containing the last two elements of v. (2) Returns undef when v is not defined, is not iterable, is empty, or has less than two elements.

◆ last3()

function last3 ( v )

Return a list containing the last three elements of an iterable value.

Parameters

v	<iterable> An iterable value.

Returns: (1) <list> A list containing the last three elements of v. (2) Returns undef when v is not defined, is not iterable, is empty, or has less than three elements.

◆ lastn()

function lastn	(	v	,
		n	= `1`
	)

Return a list containing the last n elements of an iterable value.

Parameters

v	<iterable> An iterable value.
n	<integer> The element count.

Returns: (1) <list> A list containing the last n elements of v. (2) Returns undef when v is not defined, is not iterable, or is empty.

When n is greater than the length of the iterable v, the list will start at the first element of v.

Here is the caller graph for this function:

◆ mask()

function mask	(	v	,
		m	,
		r	= `false`,
		o	= `0`,
		u	= `undef`,
		z	= `0`
	)

Apply a binary mask to an interable value.

Parameters

v	<iterable> An iterable value.
m	<iterable> A binary mask.
r	<boolean> Right align the mask to `v` value.
o	<integer> A positive or negative mask offset.
u	<value> The value assigned to elements of the mask that does not exists or are undefined in `v`.
z	<value> The value assigned to masked elements.

Returns: (1) <value> A list containing the masked values of v. (2) Returns v as a list when m is not defined. (3) Returns undef when m is not iterable or contains values other than zero or one.

This mask may be specified as a list or string and is composed of ones and zeros. One indicates that an element value of v is passed and a zero indicates that a value of v is to be replaced with z.

◆ middle()

function middle ( v )

Return the middle element of an iterable value.

Parameters

v	<iterable> An iterable value.

Returns: (1) <value> The middle element of v. (2) Returns undef when v is not defined, is not iterable, or is empty.

◆ reverse()

function reverse ( v )

Reverse the elements of an iterable value.

Parameters

v	<iterable> An iterable value.

Returns: (1) <list> A list containing the elements of v in reversed order. (2) Returns empty_lst when v is empty. (3) Returns undef when v is not defined or is not iterable.

Here is the caller graph for this function:

◆ second()

function second ( v )

Return the second element of an iterable value.

Parameters

v	<iterable> An iterable value.

Returns: (1) <value> The second element of v. (2) Returns undef when v is not defined, is not iterable, or is empty.

Note: Value may also be a range to obtain its step value.

Here is the caller graph for this function:

◆ select_r()

function select_r	(	v	,
		i
	)

Select a range of elements from an iterable value.

Parameters

v	<iterable> An iterable value.
i	<range\|list\|integer> The index selection.

Returns: (1) <list> A list containing the selected elements. (2) Returns undef when v is not defined, is not iterable, or when i does not map to an element of v. (3) Returns empty_lst when v is empty.

◆ sequence_ns()

function sequence_ns	(	v	,
		n	= `1`,
		s	= `1`,
		w	= `false`
	)

Return a list of all n-element sequential-subsets of an iterable value.

Parameters

v	<iterable> An iterable value.
n	<integer> The number of elements for each subset.
s	<integer> The iteration step size.
w	<boolean> Use wrap-at-end circular subset selection.

Returns: (1) <list-list> A list of all n-element sequential subsets of v skipping s elements of v between each subset selection. (2) Returns empty_lst when v is empty, is not defined or is not iterable.

Example

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] ]

Here is the caller graph for this function:

◆ shift()

function shift	(	v	,
		n	= `0`,
		r	= `true`,
		c	= `true`
	)

Shift the elements of an iterable value.

Parameters

v	<iterable> An iterable value.
n	<integer> The element shift count.
r	<boolean> Shift the elements to the right (or left).
c	<boolean> Perform circular shift (or drop).

Returns: (1) <list> A list containing the elements of v shifted by n elements. (2) Returns undef when v is not defined or is not iterable.

The shift count n may be positive or negative.

Here is the caller graph for this function:

◆ strip()

function strip	(	v	,
		mv	= `empty_lst`
	)

Strip all matching values from an iterable value.

Parameters

v	<iterable> An iterable value.
mv	<value> A match value.

Returns: (1) <list> The list 'v' with all elements equal mv removed. (2) Returns undef when v is not defined or is not iterable.

◆ tailn()

function tailn	(	v	,
		n	= `1`
	)

Return a list containing all but the first n elements of an iterable value.

Parameters

v	<iterable> An iterable value.
n	<integer> The element count.

Returns: (1) <list> A list containing all but the first n elements of v. (2) Returns empty_lst when v contains fewer than n elements. (3) Returns undef when v is not defined, is not iterable, or is empty.

Here is the caller graph for this function:

◆ third()

function third ( v )

Return the third element of an iterable value.

Parameters

v	<iterable> An iterable value.

Returns: (1) <value> The second element of v. (2) Returns undef when v is not defined, is not iterable, or is empty.

Note: Value may also be a range to obtain its end value.

Here is the caller graph for this function:

◆ unique()

function unique ( v )

Return a list of the unique elements of an iterable value.

Parameters

v	<iterable> An iterable value.

Returns: (1) <list> A list of unique elements with order preserved. (2) Returns undef when v is not defined or is not iterable.

Warning: Any and all list elements of v that have the value of undef are ignored and is not considered to be a unique.

Files

Functions

Detailed Description

Validation Summary

No Failures

Function Documentation

◆ append_e()

◆ count()

◆ defined_e_or()

◆ delete()

◆ exists()

◆ exists_e()

◆ find()

◆ first()

◆ first2()

◆ first3()

◆ firstn()

◆ headn()

◆ insert()

◆ last()

◆ last2()

◆ last3()

◆ lastn()

◆ mask()

◆ middle()

◆ reverse()

◆ second()

◆ select_r()

◆ sequence_ns()

◆ shift()

◆ strip()

◆ tailn()

◆ third()

◆ unique()