add Deprecated/Preview

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.
+
+----

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 <util/sorted.scad>;
+    use <util/binary_search.scad>;
+
+    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);

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 <voxel/vx_circle.scad>;
+    use <util/contains.scad>;
+
+    pts = vx_circle(10);
+    assert(contains(pts, [2, -10])); 
+    assert(!contains(pts, [0, 0]));  

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 <util/sorted.scad>;
+
+    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)
+    );

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
 *
 **/
 

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

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