diff --git a/README.md b/README.md index 1e5f850f..3548a171 100644 --- a/README.md +++ b/README.md @@ -373,3 +373,22 @@ These examples incubate dotSCAD and dotSCAD refactors these examples. See [examp ---- +# Preview + +## Deprecated + + Signature | Description +--|-- +**util/sort**(lt[, by, idx]) | use [`util/sorted`](https://openhome.cc/eGossip/OpenSCAD/lib3x-sorted.html) instead. +**util/has**(lt, elem[, sorted]) | use [`util/contains`](https://openhome.cc/eGossip/OpenSCAD/lib3x-contains.html) instead. +**util/bsearch**(sorted, target) | use [`util/binary_search`](https://openhome.cc/eGossip/OpenSCAD/lib3x-binary_search.html) instead. + +## Util + + Signature | Description +--|-- +[**util/sorted**(lt[, cmp, key, reverse])](https://openhome.cc/eGossip/OpenSCAD/lib3x-sorted.html) | sort a list. +[**util/contains**(lt, elem)](https://openhome.cc/eGossip/OpenSCAD/lib3x-contains.html) | return `true` if `lt` contains `elem`. +[**util/binary_search**(sorted, target[, lo, hi])](https://openhome.cc/eGossip/OpenSCAD/lib3x-binary_search.html) | search a value in a sorted list. + +---- \ No newline at end of file diff --git a/docs/lib3x-binary_search.md b/docs/lib3x-binary_search.md new file mode 100644 index 00000000..4ba93128 --- /dev/null +++ b/docs/lib3x-binary_search.md @@ -0,0 +1,28 @@ +# binary_search + +A general-purpose function to search a value in a sorted list. + +**Since:** 3.3 + +## Parameters + +- `sorted` : The sorted list. +- `target` : The target element or a function literal that returns a negative integer, zero, or a positive integer as the element is less than, equal to, or greater than the value you want to search. +- `lo` : Default to 0. The lower bound to be searched. +- `hi` : Default to the end of the list. The higher bound to be searched. + +## Examples + + use ; + use ; + + points = [[1, 1], [3, 4], [7, 2], [5, 2]]; + lt = sorted(points); // [[1, 1], [3, 4], [5, 2], [7, 2]] + + assert(binary_search(lt, [7, 2]) == 3); + + xIs5 = function(elem) elem[0] - 5; + assert(binary_search(lt, xIs5) == 2); + + yIs4 = function(elem) elem[1] - 4; + assert(binary_search(lt, yIs4) == 1); \ No newline at end of file diff --git a/docs/lib3x-contains.md b/docs/lib3x-contains.md new file mode 100644 index 00000000..46b3d3c9 --- /dev/null +++ b/docs/lib3x-contains.md @@ -0,0 +1,19 @@ +# contains + +If `lt` contains `elem`, this function returns `true`. + +**Since:** 3.3 + +## Parameters + +- `lt` : A list of vectors. +- `elem` : A element. + +## Examples + + use ; + use ; + + pts = vx_circle(10); + assert(contains(pts, [2, -10])); + assert(!contains(pts, [0, 0])); diff --git a/docs/lib3x-sorted.md b/docs/lib3x-sorted.md new file mode 100644 index 00000000..ee846b99 --- /dev/null +++ b/docs/lib3x-sorted.md @@ -0,0 +1,48 @@ +# sorted + +Sorts a list. It uses comparison operators between elements by default. + +**Since:** 3.3 + +## Parameters + +- `lt` : The original list. +- `cmp` : A function literal that compares its two arguments for order. Returns a negative integer, zero, or a positive integer as the first argument is less than, equal to, or greater than the second. +- `key` : Specifies a function of one argument that is used to extract a comparison key from each element. +- `reverse` : Default to `false`. If set to `true`, then the list elements are sorted as if each comparison were reversed. + +## Examples + + use ; + + assert([1, 2, 3, 4, 5, 6] == sorted([1, 6, 2, 5, 4, 3])); + assert([6, 5, 4, 3, 2, 1] == sorted([1, 6, 2, 5, 4, 3], reverse = true)); + + assert(["b", "c", "d", "m", "x"] == sorted(["x", "c", "b", "d", "m"])); + assert(["x", "m", "d", "c", "b"] == sorted(["x", "c", "b", "d", "m"], reverse = true)); + + assert( + [[2, 0, 0], [5, 0, 0], [7, 0, 0], [9, 0, 0], [10, 0, 0]] == + sorted([[2, 0, 0], [5, 0, 0], [7, 0, 0], [9, 0, 0], [10, 0, 0]]) + ); + + assert( + [[2, 0, 0], [5, 0, 0], [7, 0, 0], [9, 0, 0], [10, 0, 0]] == + sorted([[10, 0, 0], [5, 0, 0], [7, 0, 0], [2, 0, 0], [9, 0, 0]], cmp = function(a, b) a[0] - b[0]) + ); + + ascending = function(e1, e2) e1 - e2; + descending = function(e1, e2) e2 - e1; + assert(sorted([2, 1, 3, 5, 4], ascending) == [1, 2, 3, 4, 5]); + assert(sorted([2, 1, 3, 5, 4], ascending, reverse = true) == [5, 4, 3, 2, 1]); + assert(sorted([2, 1, 3, 5, 4], descending) == [5, 4, 3, 2, 1]); + + assert( + [[2, 0, 0], [5, 0, 0], [7, 0, 0], [9, 0, 0], [10, 0, 0]] == + sorted([[10, 0, 0], [5, 0, 0], [7, 0, 0], [2, 0, 0], [9, 0, 0]], key = function(elem) elem.x) + ); + + assert( + [[10, 0, 0], [9, 0, 0], [7, 0, 0], [5, 0, 0], [2, 0, 0]] == + sorted([[10, 0, 0], [5, 0, 0], [7, 0, 0], [2, 0, 0], [9, 0, 0]], key = function(elem) elem.x, reverse = true) + ); \ No newline at end of file diff --git a/src/util/binary_search.scad b/src/util/binary_search.scad index 45aebab7..2b9a36ed 100644 --- a/src/util/binary_search.scad +++ b/src/util/binary_search.scad @@ -1,10 +1,10 @@ /** -* bsearch.scad +* binary_search.scad * -* @copyright Justin Lin, 2020 +* @copyright Justin Lin, 2022 * @license https://opensource.org/licenses/lgpl-3.0.html * -* @see https://openhome.cc/eGossip/OpenSCAD/lib3x-bsearch.html +* @see https://openhome.cc/eGossip/OpenSCAD/lib3x-binary_search.html * **/ diff --git a/src/util/contains.scad b/src/util/contains.scad index 5ba05148..0206ad5d 100644 --- a/src/util/contains.scad +++ b/src/util/contains.scad @@ -1,7 +1,7 @@ /** -* has.scad +* contains.scad * -* @copyright Justin Lin, 2020 +* @copyright Justin Lin, 2022 * @license https://opensource.org/licenses/lgpl-3.0.html * * @see https://openhome.cc/eGossip/OpenSCAD/lib3x-contains.html diff --git a/src/util/sorted.scad b/src/util/sorted.scad index cdcae308..ee7e1ba3 100644 --- a/src/util/sorted.scad +++ b/src/util/sorted.scad @@ -1,5 +1,5 @@ /** -* sort.scad +* sorted.scad * * @copyright Justin Lin, 2022 * @license https://opensource.org/licenses/lgpl-3.0.html