Vector operation primitives. More...

Collaboration diagram for Vector Operations:

Files
file	primitives.scad
	Mathematical primitive functions.

Functions
function	consts (l, v)
	Create a vector of constant elements. More...

function	vstr (v)
	Convert all vector elements to strings and concatenate. More...

function	sum (v, i1, i2)
	Compute the sum of a vector of numbers. 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 the existence of a match value in an iterable value. More...

function	defined_or (v, d)
	Return a defined or default value. More...

function	edefined_or (v, i, d)
	Return a defined vector element or default 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	last (v)
	Return the last element of an iterable value. More...

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

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

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

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

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

function	eselect (v, f=true, l=false, i)
	Select an element from each iterable value. More...

function	ciselect (v, i)
	Case-like select a value from a vector of ordered options by index. More...

function	cmvselect (v, mv)
	Case-like select a value from a vector of identified options by match-value. More...

function	smerge (v, r=false)
	Serial-merge vectors of iterable values. More...

function	pmerge (v, j=true)
	Parallel-merge vectors of iterable values. More...

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

function	qsort (v, r=false)
	Sort the numeric or string elements of a vector using quick sort. More...

function	qsort2 (v, d=0, r=false, s=true)
	Hierarchically sort all elements of a vector using quick sort. More...

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

function	eappend (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	unique (v)
	Return the unique elements of an iterable value. More...

Detailed Description

Vector operation primitives.

See validation results.

Function Documentation

function ciselect	(	v	,
		i
	)

Case-like select a value from a vector of ordered options by index.

Parameters

v	<vector> A vector of values.
i	<integer> Element selection index.

Returns: <value> The value of the vector element at the specified index. Returns the default value when i does not map to an element of v or when i is undefined.

Behaves like a case statement for selecting values from a list of ordered options. The default value is: last(v).

Example

ov = [ "value1", "value2", "default" ];



ciselect( ov );     // "default"
ciselect( ov, 4 );  // "default"
ciselect( ov, 0 );  // "value1"

function cmvselect	(	v	,
		mv
	)

Case-like select a value from a vector of identified options by match-value.

Parameters

v	<vector> A two dimensional vector of one or more identified values [[identifier, value], ...].
mv	<value> Element selection match value.

Returns: <value> The value from the vector of identified elements with an identifier matching mv. Returns the default value when mv does not match any of the element identifiers of v or when mv is undefined.

Behaves like a case statement for selecting values from a list of identified options. The default value is: second(last(v)).

Example

ov = [ [0,"value0"], ["a","value1"], ["b","value2"], ["c","default"] ];



cmvselect( ov );      // "default"
cmvselect( ov, "x" ); // "default"
cmvselect( ov, 0 );   // "value0"
cmvselect( ov, "b" ); // "value2"

function consts	(	l	,
		v
	)

Create a vector of constant elements.

Parameters

l	<integer> The vector length.
v	<value> The element value.

Returns: <vector> With l copies of the element value v. Returns empty_v when l is not a number or if (l < 1).

Note: When v is not specified, each element is assigned the value of its index position.

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	<value> An iterable value.
s	<boolean> Use search for element matching (false uses find).
i	<integer> The element column index to match.

Returns: <integer> The number of times mv occurs in v.

See find() for information on value matching.

function defined_or	(	v	,
		d
	)

Return a defined or default value.

Parameters

v	<value> A value.
d	<value> A default value.

Returns: <value> v when it is defined or d otherwise.

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

Delete elements from an iterable value.

Parameters

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

Returns: <vector> v with all specified elements removed. Returns undef when i does not map to an element of v. Returns undef when v is not defined or is not iterable.

The elements to delete can be specified by an index position, a vector of index positions, an index range, an element match value, or a vector of element match values (when using search). When mv is a vector 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: mv, i.

See find() for information on value matching.

function eappend	(	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	<vector> A vector of values.
r	<boolean> Reduce vector element value before appending.
j	<boolean> Join each appendage as a vector.
l	<boolean> Append to last element.

Returns: <vector> With nv appended to each element of v. Returns undef when v is not defined or is not iterable.

Example

v1=[["a"], ["b"], ["c"], ["d"]];
v2=[1, 2, 3];
echo( eappend( v2, v1 ) );
echo( eappend( v2, v1, r=false ) );
echo( eappend( 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"]

Note: Appending with reduction causes nv to be appended to the elements of each value of v that is a vector. Otherwise, nv is appended to the vector itself of each value of v that is a vector.

function edefined_or	(	v	,
		i	,
		d
	)

Return a defined vector element or default value.

Parameters

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

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

function eselect	(	v	,
		f	= `true`,
		l	= `false`,
		i
	)

Select an element from each iterable value.

Parameters

v	<vector> A vector of iterable values.
f	<boolean> Select the first element.
l	<boolean> Select the last element.
i	<integer> Select a numeric element index position.

Returns: <vector> Containing the selected element of each iterable value of v. Returns empty_v when v is empty. Returns undef when v is not defined or is not iterable.

Note: When more than one selection criteria is specified, the order of precedence is: i, l, f.

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

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

Parameters

mv	<value> A match value.
v	<value> An iterable value.
s	<boolean> Use search for element matching (false uses find).
i	<integer> The element column index to match.

Returns: <boolean> true when mv exists in v and false otherwise.

See find() for information on value matching.

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	<value> 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 element column index to match.
i1	<integer> The element index where find begins (default: first).
i2	<integer> The element index where find ends (default: last).

Returns: <vector> Of indexes where elements match mv. Returns empty_v 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	vector of scalars	vector of iterables
scalar		(a)	(b) see note 1
string	(c)		(b) see note 1
vector of scalars			(b) see note 1
vector of iterables			(b) see note 1

Search:

mv / v	string	vector of scalars	vector of iterables
scalar		(a)	(b)
string	(d)	invalid	(e) see note 2
vector of scalars		(f)	(g)
vector 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_v 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_v is returned for each character of mv absent from v.
(f) For each scalar of mv, identify where it exists in v. empty_v 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_v 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 vector of one or more strings is valid. In which case, only the first character of each string element is considered.

function first ( v )

Return the first element of an iterable value.

Parameters

v	<value> An iterable value.

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

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	<value> An iterable value.
i	<integer> An insert position index.
mv	<vector\|string\|value> Match value candidates.
mi	<integer> A match index.
s	<boolean> Use search for element matching (false uses find).
si	<integer> The element column index when matching.

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

The insert position can be specified by an index, an element match value, or vector of potential match values (when using search). When multiple matches exists, mi indicates the insert position. When more than one insert position criteria is specified, the order of precedence is: mv, i.

See find() for information on value matching.

function last ( v )

Return the last element of an iterable value.

Parameters

v	<value> An iterable value.

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

function nfirst	(	v	,
		n	= `1`
	)

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

Parameters

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

Returns: <vector> Containing the first n elements of v. Returns undef when v is not defined, is not iterable, or is empty.

function nhead	(	v	,
		n	= `1`
	)

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

Parameters

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

Returns: <vector> Containing all but the last n elements of v. Returns empty_v when v contains fewer than n elements. Returns undef when v is not defined, is not iterable, or is empty.

function nlast	(	v	,
		n	= `1`
	)

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

Parameters

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

Returns: <vector> Containing the last n elements of v. Returns undef when v is not defined, is not iterable, or is empty.

function ntail	(	v	,
		n	= `1`
	)

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

Parameters

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

Returns: <vector> Containing all but the first n elements of v. Returns empty_v when v contains fewer than n elements. Returns undef when v is not defined, is not iterable, or is empty.

function pmerge	(	v	,
		j	= `true`
	)

Parallel-merge vectors of iterable values.

Parameters

v	<vector> A vector of iterable values.
j	<boolean> Join each merge as a vector.

Returns: <vector> Containing the parallel-wise element concatenation of each iterable value in v. Returns empty_v when any element value in v is empty. Returns undef when v is not defined or when any element value in v is not iterable.

Example

v1=["a", "b", "c", "d"];
v2=[1, 2, 3];
echo( pmerge( [v1, v2], true ) );
echo( pmerge( [v1, v2], false ) );

Result

ECHO: [["a", 1], ["b", 2], ["c", 3]]

ECHO: ["a", 1, "b", 2, "c", 3]

Note: The resulting vector length will be limited by the iterable value with the shortest length.; A string, although iterable, is treated as a merged unit.

function qsort	(	v	,
		r	= `false`
	)

Sort the numeric or string elements of a vector using quick sort.

Parameters

v	<vector> A vector of values.
r	<boolean> Reverse sort order.

Returns: <vector> With elements sorted in ascending order. Returns undef when v is not all strings or all numbers. Returns undef when v is not defined or is not a vector.

Warning: This implementation relies on the comparison operators '<' and '>' which expect the operands to be either two scalar numbers or two strings. Therefore, this function returns undef for vectors containing anything other than all scalar numbers or all strings.

See Wikipedia for more information.

function qsort2	(	v	,
		d	= `0`,
		r	= `false`,
		s	= `true`
	)

Hierarchically sort all elements of a vector using quick sort.

Parameters

v	<vector> A vector of values.
d	<integer> Recursive sort depth.
r	<boolean> Reverse sort order.
s	<boolean> Order ranges by their numerical sum.

Returns: <vector> With all elements sorted in ascending order. Returns undef when v is not defined or is not a vector.

Elements are sorted using the compare function. See its documentation for a description of the parameter s. To recursively sort all elements, set d greater than, or equal to, the maximum level of hierarchy in v.

See Wikipedia for more information.

function reverse ( v )

Reverse the elements of an iterable value.

Parameters

v	<value> An iterable value.

Returns: <vector> Containing the elements of v in reversed order. Returns empty_v when v is empty. Returns undef when v is not defined or is not iterable.

function rselect	(	v	,
		i
	)

Select a range of elements from an iterable value.

Parameters

v	<value> An iterable value.
i	<range\|vector\|integer> Index selection.

Returns: <vector> Containing the vector element indexes selected in i. Returns undef when i does not map to an element of v. Returns empty_v when v is empty. Returns undef when v is not defined or is not iterable.

function second ( v )

Return the second element of an iterable value.

Parameters

v	<value> An iterable value.

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

function smerge	(	v	,
		r	= `false`
	)

Serial-merge vectors of iterable values.

Parameters

v	<vector> A vector of iterable values.
r	<boolean> Recursively merge iterable elements.

Returns: <vector> Containing the serial-wise element concatenation of each element in v. Returns empty_v when v is empty. Returns undef when v is not defined.

Note: A string, although iterable, is treated as a merged unit.

function strip	(	v	,
		mv	= `empty_v`
	)

Strip all matching values from an iterable value.

Parameters

v	<vector> A vector of values.
mv	<value> A match value.

Returns: <vector> v with all elements equal to mv removed. Returns undef when v is not defined or is not iterable.

function sum	(	v	,
		i1	,
		i2
	)

Compute the sum of a vector of numbers.

Parameters

v	<range\|vector> A vector of numerical values.
i1	<integer> The element index at which to begin summation (first when not specified).
i2	<integer> The element index at which to end summation (last when not specified).

Returns: <decimal> The summation of elements over the index range. Returns v when it is a scalar number. Returns 0 when v is empty. Returns undef when v is not defined or is not iterable and not a number.

function unique ( v )

Return the unique elements of an iterable value.

Parameters

v	<value> An iterable value.

Returns: <vector> Of unique elements of v with order preserved. Returns undef when v is not defined or is not iterable.

function vstr ( v )

Convert all vector elements to strings and concatenate.

Parameters

v	<vector> A vector of values.

Returns: <string> Constructed by converting each element of the vector to a string and concatenating together. Returns undef when v is not defined.

Example

v1=["a", "b", "c", "d"];
v2=[1, 2, 3];
echo( vstr(concat(v1, v2)) );

Result

ECHO: "abcd123"

Files

Functions

Detailed Description

Function Documentation