Maps

Map data type and operations. More...

Collaboration diagram for Maps:

Files
file	map.scad
	Map data structure and operations.

Variables
	$map_strict = false
	<boolean> Enforce strict checking for map value references.

Functions
function	map_get_index (m, k)
	Return the index of a map key. More...
function	map_exists (m, k)
	Test if a key exists. More...
function	map_get_value (m, k)
	Get the map value associated with a key. More...
function	map_get_keys (m)
	Get a list of all map keys. More...
function	map_get_values (m)
	Get a list of all map values. More...
function	map_get_firstof2_or (m1, m2, k, d)
	Get the the first value associated with an existing key in one of two maps. More...
function	map_get_size (m)
	Get the number of map entries. More...
function	map_merge (m1, m2)
	Merge the unique key-value pairs of a second map with those of a first. More...
function	map_update (m, u, ignore=false)
	Update existing key-value pairs of a map. More...
function	map_equal (m1, m2, keys=true, values=false, sort=true)
	Compare the keys and/or values of two maps to test for equality. More...
function	map_from_table (t, keys=0, values=1)
	Create a map from two selected columns of a data table. More...
function	map_to_table (ml, sort=false)
	Create a table from a list of maps with common keys. More...
function	map_errors (m)
	Perform basic format checks on a map and return errors. More...
module	map_check (m, verbose=false)
	Perform basic format checks on a map and output errors to console. More...
module	map_dump (m, sort=false, number=true, align=true, p=3)
	Dump each map entry to the console. More...
module	map_write (m, ks, sort=false, number=false, fs="^", thn="idx", index_tags=empty_lst, key_tags=["b"], value_tags=empty_lst)
	Write formatted map entries to the console. More...

Usage Details

Map data type and operations.

Validation Summary

file	group	script	results	no test	skipped	passed	failed	warning
datatypes/map.scad	Maps	Script	Results	13	0	0	0	0

No Failures

See complete validation results.

Requires:
include <omdl-base.scad>;

Conventions

• A map is a list of [key, value] pairs. Keys must be strings.
• The map variable is always named m; a second map is m2.
• map_merge(m1, m2): when both maps contain the same key, the value from m1 takes precedence. Order of keys in the result is unspecified.
• map_update(m, u): keys in u that are also in m update the existing value; keys in u absent from m are appended. Values in m absent from u are preserved unchanged.
• The special variable $map_strict controls whether map_get_value() asserts on a missing key (strict=true) or returns undef silently (strict=false, the default).
• map_errors() returns an empty list when the map is valid; a non-empty list indicates the detected error class(es).

Example

Map use script

    include <omdl-base.scad>;
 
    map =
    [
      ["part1",       ["screw10", [10, 11, 13]]],
      ["part2",       ["screw12", [20, 21, 30]]],
      ["part3",       ["screw10", [10, 10, -12]]],
      ["config",      ["top", "front", "rear"]],
      ["version",     [21, 5, 0]],
      ["runid",       10]
    ];
 
    echo( "### map_check ###" );
    map_check(map, true);
 
    echo( "### map_exists ###" );
    echo( str("is part0 = ", map_exists(map, "part0")) );
    echo( str("is part1 = ", map_exists(map, "part1")) );
 
    echo( "### map_get_value ###" );
    p1 = map_get_value(map, "part1");
    echo( c=second(p1) );
 
    keys = map_get_keys(map);
    parts = delete(keys, mv=["config", "version", "runid"]);
 
    echo( "### map_delete ###" );
    for ( p = parts )
      echo
      (
        n=p,
        p=first(map_get_value(map, p)),
        l=second(map_get_value(map, p))
      );
 
    echo( "### map_dump ###" );
    map_dump(map);
 
    // end_include

Map use script output

ECHO: "### map_check ###"
ECHO: "[ INFO ] map_check(); begin map check"
ECHO: "[ INFO ] map_check(); checking map format and keys."
ECHO: "[ INFO ] map_check(); map size: 6 entries."
ECHO: "[ INFO ] map_check(); end map check"
ECHO: "### map_exists ###"
ECHO: "is part0 = false"
ECHO: "is part1 = true"
ECHO: "### map_get_value ###"
ECHO: c = [10, 11, 13]
ECHO: "### map_delete ###"
ECHO: n = "part1", p = "screw10", l = [10, 11, 13]
ECHO: n = "part2", p = "screw12", l = [20, 21, 30]
ECHO: n = "part3", p = "screw10", l = [10, 10, -12]
ECHO: "### map_dump ###"
ECHO: "000:   'part1' = '["screw10", [10, 11, 13]]'"
ECHO: "001:   'part2' = '["screw12", [20, 21, 30]]'"
ECHO: "002:   'part3' = '["screw10", [10, 10, -12]]'"
ECHO: "003:  'config' = '["top", "front", "rear"]'"
ECHO: "004: 'version' = '[21, 5, 0]'"
ECHO: "005:   'runid' = '10'"
ECHO: "map size: 6 entries."

Function and/or Module Documentation

map_get_index()

function map_get_index	(	m	,
		k
	)

Return the index of a map key.

Parameters

m	<map> A list of N key-value map pairs.
k	<value> A map key.

Returns

<integer> The index of the map entry if it exists. Returns undef if key does not exist.

map_exists()

function map_exists	(	m	,
		k
	)

Test if a key exists.

Parameters

m	<map> A list of N key-value map pairs.
k	<value> A map key.

Returns

<boolean> true when the key exists and false otherwise.

Here is the caller graph for this function:

map_get_value()

function map_get_value	(	m	,
		k
	)

Get the map value associated with a key.

Parameters

m	<map> A list of N key-value map pairs.
k	<value> A map key.

Returns

<value> The value associated with key. Returns undef if key does not exist and $map_strict is false. Raises an assertion if key does not exist and $map_strict is true.

Here is the caller graph for this function:

map_get_keys()

function map_get_keys

(

m

)

Get a list of all map keys.

Parameters

m	<map> A list of N key-value map pairs.

Returns

<list-N> A list of keys for all N map entries.

Here is the caller graph for this function:

map_get_values()

function map_get_values

(

m

)

Get a list of all map values.

Parameters

m	<map> A list of N key-value map pairs.

Returns

<list-N> A list of values for all N map entries.

map_get_firstof2_or()

function map_get_firstof2_or	(	m1	,
		m2	,
		k	,
		d
	)

Get the the first value associated with an existing key in one of two maps.

Parameters

m1	<map> A list of N key-value map pairs.
m2	<map> A list of N key-value map pairs.
k	<value> A map key.
d	<value> A default return value.

Returns

<value> The first value associated with key that exists in maps m1 or m2, otherwise return d when it does not exist in either.

map_get_size()

function map_get_size

(

m

)

Get the number of map entries.

Parameters

m	<map> A list of N key-value map pairs.

Returns

<integer> The number of map entries.

map_merge()

function map_merge	(	m1	,
		m2
	)

Merge the unique key-value pairs of a second map with those of a first.

Parameters

m1	<map> A list of N key-value map pairs.
m2	<map> A list of N key-value map pairs.

Returns

<value> The key value-pairs of m1 together with the unique key value-pairs of m2 that are absent in m1.

Here is the caller graph for this function:

map_update()

function map_update	(	m	,
		u	,
		ignore	= false
	)

Update existing key-value pairs of a map.

Parameters

m	<map> A list of N key-value map pairs.
u	<map> The update list of N key-value map pairs.
ignore	<boolean> Ignore the entries of u missing from m.

Returns

<value> The key value-pairs of m together with the updates from u that are present in m.

map_equal()

function map_equal	(	m1	,
		m2	,
		keys	= true,
		values	= false,
		sort	= true
	)

Compare the keys and/or values of two maps to test for equality.

Parameters

m1	<map> A list of N key-value map pairs.
m2	<map> A list of N key-value map pairs.
keys	<boolean> Comparison includes the map keys.
values	<boolean> Comparison includes the map values.
sort	<boolean> Sort prior to the comparison.

Returns

<boolean> true when equal and false otherwise.

map_from_table()

function map_from_table	(	t	,
		keys	= 0,
		values	= 1
	)

Create a map from two selected columns of a data table.

Parameters

t	2d data matrix.
keys	<integer> The table column for the map keys.
values	<integer> The table column for the map values.

Returns

<map> A list of N key-value map pairs.

map_to_table()

function map_to_table	(	ml	,
		sort	= false
	)

Create a table from a list of maps with common keys.

Parameters

ml	<map-list> A list of one or more maps.
sort	<boolean> Sort the output by key.

Returns

<table> The table row data matrix (C-columns x R-Rows), where C is the number of maps and R is the number of map keys.

map_errors()

function map_errors

(

m

)

Perform basic format checks on a map and return errors.

Parameters

m	<map> A list of N key-value map pairs.

Returns

<list-N> A list of map format errors.

Check that: (1) each entry has key-value 2-tuple and (2) key identifiers are unique. When there are no errors, the empty_lst is returned.

map_check()

module map_check	(	m	,
		verbose	= false
	)

Perform basic format checks on a map and output errors to console.

Parameters

m	<map> A list of N key-value map pairs.
verbose	<boolean> Be verbose during check.

Check that: (1) each entry has key-value 2-tuple and (2) key identifiers are unique.

Definition at line 787 of file map.scad.

Here is the caller graph for this function:

map_dump()

module map_dump	(	m	,
		sort	= false,
		number	= true,
		align	= true,
		p	= 3
	)

Dump each map entry to the console.

Parameters

m	<map> A list of N key-value map pairs.
sort	<boolean> Sort the output by key.
number	<boolean> Output index number.
align	<boolean> pad keys for right alignment.
p	<integer> Number of places for zero-padded numbering.

Definition at line 850 of file map.scad.

map_write()

module map_write	(	m	,
		ks	,
		sort	= false,
		number	= false,
		fs	= "^",
		thn	= "idx",
		index_tags	= empty_lst,
		key_tags	= ["b"],
		value_tags	= empty_lst
	)

Write formatted map entries to the console.

Parameters

m	<map> A list of N key-value map pairs.
ks	<string-list> A list of selected keys.
sort	<boolean> Sort the output by key.
number	<boolean> Output index number.
fs	<string> A field separator.
thn	<string> Column heading for numbered row output.
index_tags	<string-list> List of html formatting tags.
key_tags	<string-list> List of html formatting tags.
value_tags	<string-list> List of html formatting tags.

Output map keys and values the console. To output only select keys, assign the desired key identifiers to ks. For example to output only 'key1' and 'key2', assign ks = ["key1", "key2"]. The output can then be processed to produce documentation tables as shown in the example below.

Map write script

    include <omdl-base.scad>;
 
    map =
    [
      ["part1",       ["screw10", [10, 11, 13]]],
      ["part2",       ["screw12", [20, 21, 30]]],
      ["part3",       ["screw10", [10, 10, -12]]],
      ["config",      ["top", "front", "rear"]],
      ["version",     [21, 5, 0]],
      ["runid",       10]
    ];
 
    map_write(map, index_tags=["center","i"]);
 
    // end_include

Map write script output

ECHO: "key^value"
ECHO: "<b>part1</b>^["screw10", [10, 11, 13]]^"
ECHO: "<b>part2</b>^["screw12", [20, 21, 30]]^"
ECHO: "<b>part3</b>^["screw10", [10, 10, -12]]^"
ECHO: "<b>config</b>^["top", "front", "rear"]^"
ECHO: "<b>version</b>^[21, 5, 0]^"
ECHO: "<b>runid</b>^10^"

Map write table

key	value
part1	["screw10", [10, 11, 13]]
part2	["screw12", [20, 21, 30]]
part3	["screw10", [10, 10, -12]]
config	["top", "front", "rear"]
version	[21, 5, 0]
runid	10

Definition at line 1032 of file map.scad.