diff --git a/README.md b/README.md index 16592de9..450be819 100644 --- a/README.md +++ b/README.md @@ -171,14 +171,14 @@ These examples incubate dotSCAD and dotSCAD refactors these examples. See [examp - [util/set/hashset_len](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashset_len.html) - [util/set/hashset_elems](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashset_elems.html) - map - - `util/map/hashmap` - - `util/map/hashmap_put` - - `util/map/hashmap_get` - - `util/map/hashmap_del` - - `util/map/hashmap_len` - - `util/map/hashmap_keys` - - `util/map/hashmap_values` - - `util/map/hashmap_entries` + - [util/map/hashmap](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap.html) + - [util/map/hashmap_put](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap_put.html) + - [util/map/hashmap_get](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap_get.html) + - [util/map/hashmap_del](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap_del.html) + - [util/map/hashmap_len](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap_len.html) + - [util/map/hashmap_keys](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap_keys.html) + - [util/map/hashmap_values](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap_values.html) + - [util/map/hashmap_entries](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap_entries.html) ### Matrix - [matrix/m_determinant](https://openhome.cc/eGossip/OpenSCAD/lib3x-m_determinant.html) diff --git a/docs/lib3x-hashmap.md b/docs/lib3x-hashmap.md new file mode 100644 index 00000000..f0e8add9 --- /dev/null +++ b/docs/lib3x-hashmap.md @@ -0,0 +1,44 @@ +# hashmap + +This function maps keys to values. You can use the following to process the returned map. + +- [util/map/hashmap_put](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap_put.html) : Puts an element to the map. It returns a new map. +- [util/map/hashmap_get](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap_get.html) : Returns the value to which the specified key is mapped, or `undef` if the map contains no mapping for the key. +- [util/map/hashmap_del](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap_del.html) : Deletes the mapping for the specified key from a map if present. +- [util/map/hashmap_len](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap_len.html) : Returns the length of the map. +- [util/map/hashmap_keys](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap_keys.html) : Returns a list containing all keys in the map. +- [util/map/hashmap_values](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap_values.html) : Returns a list containing all values in the map. +- [util/map/hashmap_entries](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap_entries.html) : Returns a list containing all `[key, value]`s in the map. + +**Since:** 3.0 + +## Parameters + +- `kv_lt` : Constructs a new map containing the `[key, value]`s in the specified list. It can be ignored if you want an empty map. +- `eq` : A equality function. If it's ignored, use `==` to compare elements. +- `hash` : A hash function. If it's ignored, convert each element to a string and hash it. +- `number_of_buckets` : The function uses a hash table internally. Change the number of buckets if you're trying to do optimization. + +## Examples + + use ; + use ; + use ; + use ; + use ; + use ; + use ; + use ; + + m1 = hashmap([["k1", 10], ["k2", 20], ["k3", 30]]); + assert(hashmap_len(m1) == 3); + + m2 = hashmap_put(m1, "k4", 40); + assert(hashmap_get(m2, "k4") == 40); + + m3 = hashmap_del(m2, "k1"); + assert(hashmap_get(m3, "k1") == undef); + + echo(hashmap_keys(m3)); // a list contains "k2", "k2", "k3" + echo(hashmap_values(m3)); // a list contains 20, 30, 40 + echo(hashmap_entries(m3)); // a list contains ["k2", 20], ["k3", 30], ["k4", 40] diff --git a/docs/lib3x-hashmap_del.md b/docs/lib3x-hashmap_del.md new file mode 100644 index 00000000..41dd87f8 --- /dev/null +++ b/docs/lib3x-hashmap_del.md @@ -0,0 +1,22 @@ +# hashmap_put + +This function deletes the mapping for the specified key from a [util/map/hashmap](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap.html) if present. It returns a new map without the key/value. + +**Since:** 3.0 + +## Parameters + +- `map` : The original map. +- `key` : Adds the specified element to the specified set +- `eq` : A equality function. If it's ignored, use `==` to compare elements. +- `hash` : A hash function. If it's ignored, convert each element to a string and hash it. + +## Examples + + use ; + use ; + use ; + + m1 = hashmap([["k1", 10], ["k2", 20], ["k3", 30]]); + m2 = hashmap_del(m1, "k1"); + assert(hashmap_get(m2, "k1") == undef); \ No newline at end of file diff --git a/docs/lib3x-hashmap_entries.md b/docs/lib3x-hashmap_entries.md new file mode 100644 index 00000000..e5a481f3 --- /dev/null +++ b/docs/lib3x-hashmap_entries.md @@ -0,0 +1,17 @@ +# hashmap_entries + +Returns a list containing all `[key, value]`s in a [util/map/hashmap](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap.html). + +**Since:** 3.0 + +## Parameters + +- `map` : The map. + +## Examples + + use ; + use ; + + m = hashmap([["k1", 10], ["k2", 20], ["k3", 30]]); + echo(hashmap_entries(m)); // a list contains ["k1", 10], ["k2", 20], ["k3", 30] diff --git a/docs/lib3x-hashmap_get.md b/docs/lib3x-hashmap_get.md new file mode 100644 index 00000000..98f17051 --- /dev/null +++ b/docs/lib3x-hashmap_get.md @@ -0,0 +1,20 @@ +# hashmap_put + +This function gets the value of the specified key from a [util/map/hashmap](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap.html). + +**Since:** 3.0 + +## Parameters + +- `map` : The original map. +- `key` : Adds the specified element to the specified set +- `eq` : A equality function. If it's ignored, use `==` to compare elements. +- `hash` : A hash function. If it's ignored, convert each element to a string and hash it. + +## Examples + + use ; + use ; + + m = hashmap([["k1", 10], ["k2", 20], ["k3", 30]]); + assert(hashmap_get(m, "k2") == 20); \ No newline at end of file diff --git a/docs/lib3x-hashmap_keys.md b/docs/lib3x-hashmap_keys.md new file mode 100644 index 00000000..6f7c6528 --- /dev/null +++ b/docs/lib3x-hashmap_keys.md @@ -0,0 +1,18 @@ +# hashmap_keys + +Returns a list containing all keys in a [util/map/hashmap](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap.html). + +**Since:** 3.0 + +## Parameters + +- `map` : The map. + +## Examples + + use ; + use ; + + m = hashmap([["k1", 10], ["k2", 20], ["k3", 30]]); + + echo(hashmap_keys(m)); // a list contains "k1", "k2", "k3" diff --git a/docs/lib3x-hashmap_len.md b/docs/lib3x-hashmap_len.md new file mode 100644 index 00000000..ba660f30 --- /dev/null +++ b/docs/lib3x-hashmap_len.md @@ -0,0 +1,17 @@ +# hashmap_put + +This function puts a key/value to a [util/map/hashmap](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap.html). It returns a new map containing the key/value. + +**Since:** 3.0 + +## Parameters + +- `map` : The map. + +## Examples + + use ; + use ; + + m = hashmap([["k1", 10], ["k2", 20], ["k3", 30]]); + assert(hashmap_len(m) == 3); \ No newline at end of file diff --git a/docs/lib3x-hashmap_put.md b/docs/lib3x-hashmap_put.md new file mode 100644 index 00000000..25c851eb --- /dev/null +++ b/docs/lib3x-hashmap_put.md @@ -0,0 +1,20 @@ +# hashmap_put + +This function returns the length of a [util/map/hashmap](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap.html). + +**Since:** 3.0 + +## Parameters + +- `map` : The original map. + +## Examples + + use ; + use ; + use ; + + m1 = hashmap([["k1", 10], ["k2", 20], ["k3", 30]]); + + m2 = hashmap_put(m1, "k4", 40); + assert(hashmap_get(m2, "k4") == 40); \ No newline at end of file diff --git a/docs/lib3x-hashmap_values.md b/docs/lib3x-hashmap_values.md new file mode 100644 index 00000000..b452a627 --- /dev/null +++ b/docs/lib3x-hashmap_values.md @@ -0,0 +1,18 @@ +# hashmap_values + +Returns a list containing all values in a [util/map/hashmap](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap.html). + +**Since:** 3.0 + +## Parameters + +- `map` : The map. + +## Examples + + use ; + use ; + + m = hashmap([["k1", 10], ["k2", 20], ["k3", 30]]); + + echo(hashmap_values(m)); // a list contains 10, 20, 30 diff --git a/src/util/map/hashmap.scad b/src/util/map/hashmap.scad index 3e1ef9e7..d206725f 100644 --- a/src/util/map/hashmap.scad +++ b/src/util/map/hashmap.scad @@ -1,3 +1,13 @@ +/** +* hashmap.scad +* +* @copyright Justin Lin, 2021 +* @license https://opensource.org/licenses/lgpl-3.0.html +* +* @see https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap.html +* +**/ + use <../../__comm__/_str_hash.scad>; use <_impl/_hashmap_impl.scad>; use <_impl/_hashmap_put_impl.scad>; diff --git a/src/util/map/hashmap_del.scad b/src/util/map/hashmap_del.scad index 9faa032b..1c3be6e5 100644 --- a/src/util/map/hashmap_del.scad +++ b/src/util/map/hashmap_del.scad @@ -1,3 +1,13 @@ +/** +* hashmap_del.scad +* +* @copyright Justin Lin, 2021 +* @license https://opensource.org/licenses/lgpl-3.0.html +* +* @see https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap_del.html +* +**/ + use <../../__comm__/_str_hash.scad>; use <../slice.scad>; use <../find_index.scad>; diff --git a/src/util/map/hashmap_entries.scad b/src/util/map/hashmap_entries.scad index 24f7210b..bbbe241f 100644 --- a/src/util/map/hashmap_entries.scad +++ b/src/util/map/hashmap_entries.scad @@ -1,3 +1,13 @@ +/** +* hashmap_entries.scad +* +* @copyright Justin Lin, 2021 +* @license https://opensource.org/licenses/lgpl-3.0.html +* +* @see https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap_entries.html +* +**/ + function hashmap_entries(map) = [ for(bucket = map) for(kv = bucket) diff --git a/src/util/map/hashmap_get.scad b/src/util/map/hashmap_get.scad index 1078d082..dbe90181 100644 --- a/src/util/map/hashmap_get.scad +++ b/src/util/map/hashmap_get.scad @@ -1,3 +1,13 @@ +/** +* hashmap_get.scad +* +* @copyright Justin Lin, 2021 +* @license https://opensource.org/licenses/lgpl-3.0.html +* +* @see https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap_get.html +* +**/ + use <../../__comm__/_str_hash.scad>; use <../slice.scad>; use <../find_index.scad>; diff --git a/src/util/map/hashmap_keys.scad b/src/util/map/hashmap_keys.scad index d70ba639..098081d8 100644 --- a/src/util/map/hashmap_keys.scad +++ b/src/util/map/hashmap_keys.scad @@ -1,3 +1,13 @@ +/** +* hashmap_keys.scad +* +* @copyright Justin Lin, 2021 +* @license https://opensource.org/licenses/lgpl-3.0.html +* +* @see https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap_keys.html +* +**/ + function hashmap_keys(map) = [ for(bucket = map) for(kv = bucket) diff --git a/src/util/map/hashmap_len.scad b/src/util/map/hashmap_len.scad index 8b07a3f6..eb9cd025 100644 --- a/src/util/map/hashmap_len.scad +++ b/src/util/map/hashmap_len.scad @@ -1,3 +1,13 @@ +/** +* hashmap_len.scad +* +* @copyright Justin Lin, 2021 +* @license https://opensource.org/licenses/lgpl-3.0.html +* +* @see https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap_len.html +* +**/ + use <../sum.scad>; function hashmap_len(map) = sum([ diff --git a/src/util/map/hashmap_put.scad b/src/util/map/hashmap_put.scad index d7471405..77c4eb25 100644 --- a/src/util/map/hashmap_put.scad +++ b/src/util/map/hashmap_put.scad @@ -1,3 +1,13 @@ +/** +* hashmap_put.scad +* +* @copyright Justin Lin, 2021 +* @license https://opensource.org/licenses/lgpl-3.0.html +* +* @see https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap_put.html +* +**/ + use <../../__comm__/_str_hash.scad>; use <_impl/_hashmap_put_impl.scad>; diff --git a/src/util/map/hashmap_values.scad b/src/util/map/hashmap_values.scad index 6b704c75..a17ca9d9 100644 --- a/src/util/map/hashmap_values.scad +++ b/src/util/map/hashmap_values.scad @@ -1,3 +1,13 @@ +/** +* hashmap_values.scad +* +* @copyright Justin Lin, 2021 +* @license https://opensource.org/licenses/lgpl-3.0.html +* +* @see https://openhome.cc/eGossip/OpenSCAD/lib3x-hashmap_values.html +* +**/ + function hashmap_values(map) = [ for(bucket = map) for(kv = bucket)