From 43fcc5c1273a319a4aa0d2488f3c2a07a6a68679 Mon Sep 17 00:00:00 2001 From: Justin Lin Date: Mon, 8 Mar 2021 18:17:50 +0800 Subject: [PATCH] add docs --- README.md | 12 +++++------ docs/lib3x-hashset.md | 38 +++++++++++++++++++++++++++++++++ docs/lib3x-hashset_add.md | 22 +++++++++++++++++++ docs/lib3x-hashset_del.md | 22 +++++++++++++++++++ docs/lib3x-hashset_elems.md | 18 ++++++++++++++++ docs/lib3x-hashset_has.md | 20 +++++++++++++++++ docs/lib3x-hashset_len.md | 17 +++++++++++++++ src/util/set/hashset.scad | 10 +++++++++ src/util/set/hashset_add.scad | 10 +++++++++ src/util/set/hashset_del.scad | 10 +++++++++ src/util/set/hashset_elems.scad | 10 +++++++++ src/util/set/hashset_has.scad | 10 +++++++++ src/util/set/hashset_len.scad | 10 +++++++++ 13 files changed, 203 insertions(+), 6 deletions(-) create mode 100644 docs/lib3x-hashset.md create mode 100644 docs/lib3x-hashset_add.md create mode 100644 docs/lib3x-hashset_del.md create mode 100644 docs/lib3x-hashset_elems.md create mode 100644 docs/lib3x-hashset_has.md create mode 100644 docs/lib3x-hashset_len.md diff --git a/README.md b/README.md index f87bebe6..16592de9 100644 --- a/README.md +++ b/README.md @@ -164,12 +164,12 @@ These examples incubate dotSCAD and dotSCAD refactors these examples. See [examp - [util/lerp](https://openhome.cc/eGossip/OpenSCAD/lib3x-lerp.html) - [util/fibseq](https://openhome.cc/eGossip/OpenSCAD/lib3x-fibseq.html) - set - - `util/set/hashset` - - `util/set/hashset_add` - - `util/set/hashset_has` - - `util/set/hashset_del` - - `util/set/hashset_len` - - `util/set/hashset_elems` + - [util/set/hashset](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashset.html) + - [util/set/hashset_add](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashset_add.html) + - [util/set/hashset_has](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashset_has.html) + - [util/set/hashset_del](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashset_del.html) + - [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` diff --git a/docs/lib3x-hashset.md b/docs/lib3x-hashset.md new file mode 100644 index 00000000..c169a02b --- /dev/null +++ b/docs/lib3x-hashset.md @@ -0,0 +1,38 @@ +# hashset + +This function models the mathematical set, backed by a hash table. You can use the following to process the returned set. + +- [util/set/hashset_add](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashset_add.html) : Add an element to the set. It returns a new set. +- [util/set/hashset_has](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashset_has.html) : Returns `true` if the set contains the specified element. +- [util/set/hashset_del](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashset_del.html) : Deletes the specified element. It returns a new set. +- [util/set/hashset_len](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashset_len.html) : Returns the length of the set. +- [util/set/hashset_elems](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashset_elems.html) : Returns a list containing all elements in the set. No guarantees to the order. + +**Since:** 3.0 + +## Parameters + +- `lt` : Constructs a new set containing the elements in the specified list. +- `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 ; + + s1 = hashset([1, 2, 3, 4, 5, 2, 3, 5]); + assert(hashset_len(s1) == 5); + + s2 = hashset_add(s1, 9); + assert(hashset_has(s2, 9)); + + s3 = hashset_del(s2, 2); + assert(!hashset_has(s3, 2)); + + echo(hashset_elems(s3)); // a list contains 1, 3, 4, 5, 9 diff --git a/docs/lib3x-hashset_add.md b/docs/lib3x-hashset_add.md new file mode 100644 index 00000000..07483ca6 --- /dev/null +++ b/docs/lib3x-hashset_add.md @@ -0,0 +1,22 @@ +# hashset_add + +This function adds an element to a [util/set/hashset](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashset.html).It returns a new set containing the added element. + +**Since:** 3.0 + +## Parameters + +- `set` : The original set. +- `elem` : 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 ; + + s1 = hashset([1, 2, 3, 4, 5]); + s2 = hashset_add(s1, 9); + assert(hashset_has(s2, 9)); diff --git a/docs/lib3x-hashset_del.md b/docs/lib3x-hashset_del.md new file mode 100644 index 00000000..67aef480 --- /dev/null +++ b/docs/lib3x-hashset_del.md @@ -0,0 +1,22 @@ +# hashset_del + +This function dels an element from a [util/set/hashset](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashset.html).It returns a new set without the specified element. + +**Since:** 3.0 + +## Parameters + +- `set` : The original set. +- `elem` : The element to be deleted. +- `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 ; + + s1 = hashset([1, 2, 3, 4, 5]); + s2 = hashset_del(s1, 3); + assert(!hashset_has(s2, 3)); diff --git a/docs/lib3x-hashset_elems.md b/docs/lib3x-hashset_elems.md new file mode 100644 index 00000000..a7f85243 --- /dev/null +++ b/docs/lib3x-hashset_elems.md @@ -0,0 +1,18 @@ +# hashset_has + +Returns a list containing all elements in a [util/set/hashset](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashset.html). No guarantees to the order. + +**Since:** 3.0 + +## Parameters + +- `set` : The set. + +## Examples + + use ; + use ; + + s = hashset([1, 2, 3, 4, 5]); + echo(hashset_elems(s)); // a list contains 1, 2, 3, 4, 5 + diff --git a/docs/lib3x-hashset_has.md b/docs/lib3x-hashset_has.md new file mode 100644 index 00000000..520846de --- /dev/null +++ b/docs/lib3x-hashset_has.md @@ -0,0 +1,20 @@ +# hashset_has + +Returns `true` if a [util/set/hashset](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashset.html) contains the specified element. + +**Since:** 3.0 + +## Parameters + +- `set` : The original set. +- `elem` : The element to be checked. +- `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 ; + + s = hashset([1, 2, 3, 4, 5]); + assert(hashset_has(s, 3)); diff --git a/docs/lib3x-hashset_len.md b/docs/lib3x-hashset_len.md new file mode 100644 index 00000000..c1640f3f --- /dev/null +++ b/docs/lib3x-hashset_len.md @@ -0,0 +1,17 @@ +# hashset_has + +Returns the length of the elements in a [util/set/hashset](https://openhome.cc/eGossip/OpenSCAD/lib3x-hashset.html). + +**Since:** 3.0 + +## Parameters + +- `set` : The set. + +## Examples + + use ; + use ; + + s = hashset([1, 2, 3, 4, 5]); + assert(hashset_len(s) == 5); diff --git a/src/util/set/hashset.scad b/src/util/set/hashset.scad index 4dc3ff6a..6ce5f9fc 100644 --- a/src/util/set/hashset.scad +++ b/src/util/set/hashset.scad @@ -1,3 +1,13 @@ +/** +* hashset.scad +* +* @copyright Justin Lin, 2021 +* @license https://opensource.org/licenses/lgpl-3.0.html +* +* @see https://openhome.cc/eGossip/OpenSCAD/lib3x-hashset.html +* +**/ + use <../../__comm__/_str_hash.scad>; use <_impl/_hashset_impl.scad>; use <_impl/_hashset_add_impl.scad>; diff --git a/src/util/set/hashset_add.scad b/src/util/set/hashset_add.scad index b0655b9f..d51ce266 100644 --- a/src/util/set/hashset_add.scad +++ b/src/util/set/hashset_add.scad @@ -1,3 +1,13 @@ +/** +* hashset_add.scad +* +* @copyright Justin Lin, 2021 +* @license https://opensource.org/licenses/lgpl-3.0.html +* +* @see https://openhome.cc/eGossip/OpenSCAD/lib3x-hashset_add.html +* +**/ + use <../../__comm__/_str_hash.scad>; use <_impl/_hashset_add_impl.scad>; diff --git a/src/util/set/hashset_del.scad b/src/util/set/hashset_del.scad index 3694058c..75d69d5a 100644 --- a/src/util/set/hashset_del.scad +++ b/src/util/set/hashset_del.scad @@ -1,3 +1,13 @@ +/** +* hashset_del.scad +* +* @copyright Justin Lin, 2021 +* @license https://opensource.org/licenses/lgpl-3.0.html +* +* @see https://openhome.cc/eGossip/OpenSCAD/lib3x-hashset_del.html +* +**/ + use <../../__comm__/_str_hash.scad>; use <../slice.scad>; use <../find_index.scad>; diff --git a/src/util/set/hashset_elems.scad b/src/util/set/hashset_elems.scad index 191d1386..ae1b1e94 100644 --- a/src/util/set/hashset_elems.scad +++ b/src/util/set/hashset_elems.scad @@ -1,3 +1,13 @@ +/** +* hashset_elems.scad +* +* @copyright Justin Lin, 2021 +* @license https://opensource.org/licenses/lgpl-3.0.html +* +* @see https://openhome.cc/eGossip/OpenSCAD/lib3x-hashset_elems.html +* +**/ + function hashset_elems(set) = [ for(bucket = set) for(elem = bucket) diff --git a/src/util/set/hashset_has.scad b/src/util/set/hashset_has.scad index efce8c97..c2c2b9e0 100644 --- a/src/util/set/hashset_has.scad +++ b/src/util/set/hashset_has.scad @@ -1,3 +1,13 @@ +/** +* hashset_has.scad +* +* @copyright Justin Lin, 2021 +* @license https://opensource.org/licenses/lgpl-3.0.html +* +* @see https://openhome.cc/eGossip/OpenSCAD/lib3x-hashset_has.html +* +**/ + use <../../__comm__/_str_hash.scad>; use <../some.scad>; diff --git a/src/util/set/hashset_len.scad b/src/util/set/hashset_len.scad index c05df352..7f4b31a5 100644 --- a/src/util/set/hashset_len.scad +++ b/src/util/set/hashset_len.scad @@ -1,3 +1,13 @@ +/** +* hashset_len.scad +* +* @copyright Justin Lin, 2021 +* @license https://opensource.org/licenses/lgpl-3.0.html +* +* @see https://openhome.cc/eGossip/OpenSCAD/lib3x-hashset_len.html +* +**/ + use <../sum.scad>; function hashset_len(set) = sum([