List data type operations. More...

Collaboration diagram for Lists:

Files
file	datatypes-base.scad
	Include file wrapper of data types base primitives.

Functions
function	lstr (v)
	Convert a list of values to a concatenated string. More...

function	lstr_html (v, b, p, a, f, d=false)
	Convert a list of values to a concatenated HTML-formatted string. More...

function	consts (l, v, u=false)
	Create a sequence of constant or incrementing elements. More...

function	get_index (l, s=true, rs)
	Create a sequence for a list index sequence specification. More...

function	pad (l, w, p=0, r=true)
	Pad a list to a constant width of elements. More...

function	dround (v, d=6)
	Round all numerical values of a list to a fixed number of decimal point digits. More...

function	sround (v, d=6)
	Round all numerical values of a list to a fixed number of significant figures. More...

function	limit (v, l, u)
	Limit all numerical values of a list between an upper and lower bounds. More...

function	sum (v, i1, i2)
	Compute the sum of a list of numbers. More...

function	mean (v)
	Compute the mean/average of a list of numbers. More...

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

function	cmvselect (v, mv)
	Case-like select a value from a list of mapped key-value options. More...

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

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

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

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

function	qsort2 (v, i, d=0, r=false, s=true)
	Hierarchically sort an arbitrary data list using quick sort. More...

Detailed Description

List data type operations.

See validation results.

Function Documentation

function ciselect	(	v	,
		i
	)

Case-like select a value from a list of ordered value options.

Parameters

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

Returns: <value> The value of the list element at the specified index. Returns the default value when i does not map to an element.

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"

Here is the caller graph for this function:

function cmvselect	(	v	,
		mv
	)

Case-like select a value from a list of mapped key-value options.

Parameters

v	<matrix-2xN> A matrix of N key-value mapped pairs [[key, value], ...].
mv	<value> Element selection key match value.

Returns: <value> The value from the map that matches the key 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 mapped 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	,
		u	= `false`
	)

Create a sequence of constant or incrementing elements.

Parameters

l	<integer> The list length.
v	<value> The element value.
u	<boolean> Element values are undef.

Returns: <list> A list of l copies of the element. Returns empty_lst when l is not a number or if (l < 1).

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

Here is the caller graph for this function:

function dround	(	v	,
		d	= `6`
	)

Round all numerical values of a list to a fixed number of decimal point digits.

Parameters

v	<list> A list of values.
d	<integer> The (maximum) number of decimals.

Returns: <list> The list with all numeric values truncated to d decimal digits and rounded-up if the following digit is 5 or greater. Non-numeric values are unchanged.

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

Select a specified element from each iterable value of a list.

Parameters

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

Returns: <list> A list containing the selected element of each iterable value of v. Returns empty_lst 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 get_index	(	l	,
		s	= `true`,
		rs
	)

Create a sequence for a list index sequence specification.

Parameters

l	<list> The list.
s	<index> The index sequence specification.
rs	<integer> An optional seed for random sequences.

Returns: <number-list> An index sequence based on the specification. Returns empty_lst for any v that does not fall into one of the specification forms.

See Index sequence for argument specification and conventions.

Here is the caller graph for this function:

function limit	(	v	,
		l	,
		u
	)

Limit all numerical values of a list between an upper and lower bounds.

Parameters

v	<list> A list of values.
l	<number> The minimum value.
u	<number> The maximum value.

Returns: <list> The list with all numeric values limited to the range [l : u]. A value will be assigned l when it is less than l and u when it is greater than u. Non-numeric values are unchanged.

function lstr ( v )

Convert a list of values to a concatenated string.

Parameters

v	<list> A list of values.

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

Example

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

Result

ECHO: "abcd123"

function lstr_html	(	v	,
		b	,
		p	,
		a	,
		f	,
		d	= `false`
	)

Convert a list of values to a concatenated HTML-formatted string.

Parameters

v	<list> A list of values.
b	<tag-list-list> A list of tag lists. Unpaired HTML tag(s) to add before the value.
p	<tag-list-list> A list of tag lists. Paired HTML tag(s) to enclose the value.
a	<tag-list-list> A list of tag lists. Unpaired HTML tag(s) to add after the value.
f	<attr-list-list> A list of tag attribute lists for `fs`, where `fs=["color","size","face"]` is the font tag to enclose the value. Not all attributes are required, but the order is significant.
d	<boolean> Debug. When true angle brackets are replaced with curly brackets to prevent console decoding.

Returns: <string> Constructed by converting each element of the list to a string with specified HTML markup and concatenating. Returns undef when the list is not defined.

When there are fewer tag lists in b, p, a, or f, than there are value elements in v, the last specified tag list is used for all subsequent value elements.

For a list of the paired and unpaired HTML tags supported by the console see: HTML subset.

Example

echo( lstr_html(v="bold text", p="b", d=true) );
echo( lstr_html(v=[1,"x",3], f=[["red",6,"helvetica"],undef,["blue",10,"courier"]], d=true) );
v = ["result", "=", "mc", "2"];
b = ["hr", undef];
p = ["i", undef, ["b", "i"], ["b","sup"]];
a = concat(consts(3, u=true), "hr");
f = [undef, ["red"], undef, ["blue",4]];
echo( lstr_html(v=v, b=b, p=p, a=a, f=f, d=true) );

Result

ECHO: "{b}bold text{/b}"
ECHO: "{font color="red" size="6" face="helvetica"}1{/font}x{font color="blue" size="10" face="courier"}3{/font}"
ECHO: "{hr}{i}result{/i}{font color="red"}={/font}{b}{i}mc{/i}{/b}{b}{sup}{font color="blue" size="4"}2{/font}{/sup}{/b}{hr}"

function mean ( v )

Compute the mean/average of a list of numbers.

Parameters

v	<number-list\|range> A list of numerical values or a range.

Returns: <number|number-list> The sum divided by the number of elements. Returns 0 when the list is empty. Returns undef when list non-numerical.

See Wikipedia for more information.

Here is the caller graph for this function:

function pad	(	l	,
		w	,
		p	= `0`,
		r	= `true`
	)

Pad a list to a constant width of elements.

Parameters

l	<list> The list.
w	<integer> The padded width.
p	<value> The padding value.
r	<boolean> Use right padding (false for left).

Returns: <list> A list padded to w elements.

When the list has greater than w elements, the list is returned unchanged. The empty list, empty_lst, has zero elements. When l is a string, characters are counted as individual elements. Use function lstr() to join padded values back into a single string if desired.

function pmerge	(	v	,
		j	= `true`
	)

Parallel-merge lists of iterable values.

Parameters

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

Returns: <list> A list containing the parallel-wise element concatenation of each iterable value in v. Returns empty_lst 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 list length will be limited by the iterable value with the shortest length.; A single string, although iterable, is treated as a merged unit.

function qsort	(	v	,
		i	,
		r	= `false`
	)

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

Parameters

v	<number-list\|string-list> A list of values.
i	<integer> The sort column index for iterable elements.
r	<boolean> Reverse the sort order.

Returns: <list> A list with elements sorted in ascending order. Returns undef when v is not defined or is not a list.

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 will not correctly sort lists elements that are not numbers or strings. Elements with unknown order are placed at the end of the list.

See Wikipedia for more information.

Here is the caller graph for this function:

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

Hierarchically sort an arbitrary data list using quick sort.

Parameters

v	<data> A list of values.
i	<integer> The sort column index for iterable elements.
d	<integer> The recursive sort depth.
r	<boolean> Reverse the sort order.
s	<boolean> Order ranges by their numerical sum.

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

Elements are ordered using compare(). 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 smerge	(	v	,
		r	= `false`
	)

Serial-merge lists of iterable values.

Parameters

v	<list> A list of iterable values.
r	<boolean> Recursively merge elements that are iterable.

Returns: <list> A list containing the serial-wise element concatenation of each element in v. Returns empty_lst when v is empty. Returns undef when v is not defined.

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

function sround	(	v	,
		d	= `6`
	)

Round all numerical values of a list to a fixed number of significant figures.

Parameters

v	<list> A list of values.
d	<integer> The (maximum) number of significant figures.

Returns: <list> The list with all numeric values rounded-up to d significant figures. Non-numeric values are unchanged.

See Wikipedia for more information.

function sum	(	v	,
		i1	,
		i2
	)

Compute the sum of a list of numbers.

Parameters

v	<number-list\|range> A list of numerical values or a range.
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: <number|number-list> The sum over the index range. Returns 0 when the list is empty. Returns undef when list non-numerical.

Files

Functions

Detailed Description

Function Documentation