add unit functions (#3604)

* add unit functions

Signed-off-by: Jess Frazelle <github@jessfraz.com>

* add tests

Signed-off-by: Jess Frazelle <github@jessfraz.com>

* update docs

Signed-off-by: Jess Frazelle <github@jessfraz.com>

* updates

Signed-off-by: Jess Frazelle <github@jessfraz.com>

* A snapshot a day keeps the bugs away! 📷🐛 (OS: windows-latest)

* empty

* A snapshot a day keeps the bugs away! 📷🐛 (OS: windows-latest)

---------

Signed-off-by: Jess Frazelle <github@jessfraz.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

docs/kcl/index.md

@@ -32,17 +32,20 @@ layout: manual
 * [`chamfer`](kcl/chamfer)
 * [`circle`](kcl/circle)
 * [`close`](kcl/close)
+* [`cm`](kcl/cm)
 * [`cos`](kcl/cos)
 * [`e`](kcl/e)
 * [`extrude`](kcl/extrude)
 * [`fillet`](kcl/fillet)
 * [`floor`](kcl/floor)
+* [`ft`](kcl/ft)
 * [`getNextAdjacentEdge`](kcl/getNextAdjacentEdge)
 * [`getOppositeEdge`](kcl/getOppositeEdge)
 * [`getPreviousAdjacentEdge`](kcl/getPreviousAdjacentEdge)
 * [`helix`](kcl/helix)
 * [`hole`](kcl/hole)
 * [`import`](kcl/import)
+* [`inch`](kcl/inch)
 * [`int`](kcl/int)
 * [`lastSegX`](kcl/lastSegX)
 * [`lastSegY`](kcl/lastSegY)
@@ -55,8 +58,10 @@ layout: manual
 * [`log`](kcl/log)
 * [`log10`](kcl/log10)
 * [`log2`](kcl/log2)
+* [`m`](kcl/m)
 * [`max`](kcl/max)
 * [`min`](kcl/min)
+* [`mm`](kcl/mm)
 * [`patternCircular2d`](kcl/patternCircular2d)
 * [`patternCircular3d`](kcl/patternCircular3d)
 * [`patternLinear2d`](kcl/patternLinear2d)
@@ -89,3 +94,4 @@ layout: manual
 * [`xLineTo`](kcl/xLineTo)
 * [`yLine`](kcl/yLine)
 * [`yLineTo`](kcl/yLineTo)
+* [`yd`](kcl/yd)

docs/kcl/std.json

@@ -55356,7 +55356,7 @@
     "unpublished": false,
     "deprecated": false,
     "examples": [
-      "let n = 1.0285\nlet m = 1.0286\nassertEqual(n, m, 0.01, \"n is within the given tolerance for m\")"
+      "let n = 1.0285\nlet o = 1.0286\nassertEqual(n, o, 0.01, \"n is within the given tolerance for o\")"
     ]
   },
   {
@@ -82255,6 +82255,29 @@
       "const exampleSketch = startSketchOn('-XZ')\n  |> startProfileAt([0, 0], %)\n  |> line([10, 0], %)\n  |> line([0, 10], %)\n  |> close(%)\n\nconst example = extrude(10, exampleSketch)"
     ]
   },
+  {
+    "name": "cm",
+    "summary": "Centimeters conversion factor for current projects units.",
+    "description": "No matter what units the current project uses, this function will always return the conversion factor to centimeters.\nFor example, if the current project uses inches, this function will return `0.393701`. If the current project uses millimeters, this function will return `10`. If the current project uses centimeters, this function will return `1`.\n**Caution**: This function is only intended to be used when you absolutely MUST have different units in your code than the project settings. Otherwise, it is a bad pattern to use this function.\nWe merely provide these functions for convenience and readability, as `10 * cm()` is more readable that your intent is \"I want 10 centimeters\" than `10 * 10`, if the project settings are in millimeters.",
+    "tags": [
+      "units"
+    ],
+    "args": [],
+    "returnValue": {
+      "name": "",
+      "type": "number",
+      "schema": {
+        "type": "number",
+        "format": "double"
+      },
+      "required": true
+    },
+    "unpublished": false,
+    "deprecated": false,
+    "examples": [
+      "const totalWidth = 10 * cm()"
+    ]
+  },
   {
     "name": "cos",
     "summary": "Compute the cosine of a number (in radians).",
@@ -98138,6 +98161,29 @@
       "const sketch001 = startSketchOn('XZ')\n  |> startProfileAt([0, 0], %)\n  |> lineTo([12, 10], %)\n  |> line([floor(7.02986), 0], %)\n  |> yLineTo(0, %)\n  |> close(%)\n\nconst extrude001 = extrude(5, sketch001)"
     ]
   },
+  {
+    "name": "ft",
+    "summary": "Feet conversion factor for current projects units.",
+    "description": "No matter what units the current project uses, this function will always return the conversion factor to feet.\nFor example, if the current project uses inches, this function will return `12`. If the current project uses millimeters, this function will return `304.8`. If the current project uses feet, this function will return `1`.\n**Caution**: This function is only intended to be used when you absolutely MUST have different units in your code than the project settings. Otherwise, it is a bad pattern to use this function.\nWe merely provide these functions for convenience and readability, as `10 * ft()` is more readable that your intent is \"I want 10 feet\" than `10 * 304.8`, if the project settings are in millimeters.",
+    "tags": [
+      "units"
+    ],
+    "args": [],
+    "returnValue": {
+      "name": "",
+      "type": "number",
+      "schema": {
+        "type": "number",
+        "format": "double"
+      },
+      "required": true
+    },
+    "unpublished": false,
+    "deprecated": false,
+    "examples": [
+      "const totalWidth = 10 * ft()"
+    ]
+  },
   {
     "name": "getNextAdjacentEdge",
     "summary": "Get the next adjacent edge to the edge given.",
@@ -117499,6 +117545,29 @@
       "const model = import(\"tests/inputs/cube.step\")"
     ]
   },
+  {
+    "name": "inch",
+    "summary": "Inches conversion factor for current projects units.",
+    "description": "No matter what units the current project uses, this function will always return the conversion factor to inches.\nFor example, if the current project uses inches, this function will return `1`. If the current project uses millimeters, this function will return `25.4`.\n**Caution**: This function is only intended to be used when you absolutely MUST have different units in your code than the project settings. Otherwise, it is a bad pattern to use this function.\nWe merely provide these functions for convenience and readability, as `10 * inch()` is more readable that your intent is \"I want 10 inches\" than `10 * 25.4`, if the project settings are in millimeters.",
+    "tags": [
+      "units"
+    ],
+    "args": [],
+    "returnValue": {
+      "name": "",
+      "type": "number",
+      "schema": {
+        "type": "number",
+        "format": "double"
+      },
+      "required": true
+    },
+    "unpublished": false,
+    "deprecated": false,
+    "examples": [
+      "const totalWidth = 10 * inch()"
+    ]
+  },
   {
     "name": "int",
     "summary": "Convert a number to an integer.",
@@ -137886,6 +137955,29 @@
       "const exampleSketch = startSketchOn(\"XZ\")\n  |> startProfileAt([0, 0], %)\n  |> line([log2(100), 0], %)\n  |> line([5, 8], %)\n  |> line([-10, 0], %)\n  |> close(%)\n\nconst example = extrude(5, exampleSketch)"
     ]
   },
+  {
+    "name": "m",
+    "summary": "Meters conversion factor for current projects units.",
+    "description": "No matter what units the current project uses, this function will always return the conversion factor to meters.\nFor example, if the current project uses inches, this function will return `39.3701`. If the current project uses millimeters, this function will return `1000`. If the current project uses meters, this function will return `1`.\n**Caution**: This function is only intended to be used when you absolutely MUST have different units in your code than the project settings. Otherwise, it is a bad pattern to use this function.\nWe merely provide these functions for convenience and readability, as `10 * m()` is more readable that your intent is \"I want 10 meters\" than `10 * 1000`, if the project settings are in millimeters.",
+    "tags": [
+      "units"
+    ],
+    "args": [],
+    "returnValue": {
+      "name": "",
+      "type": "number",
+      "schema": {
+        "type": "number",
+        "format": "double"
+      },
+      "required": true
+    },
+    "unpublished": false,
+    "deprecated": false,
+    "examples": [
+      "const totalWidth = 10 * m()"
+    ]
+  },
   {
     "name": "max",
     "summary": "Compute the maximum of the given arguments.",
@@ -137958,6 +138050,29 @@
       "const exampleSketch = startSketchOn(\"XZ\")\n  |> startProfileAt([0, 0], %)\n  |> angledLine({\n       angle: 70,\n       length: min(15, 31, 4, 13, 22)\n     }, %)\n  |> line([20, 0], %)\n  |> close(%)\n\nconst example = extrude(5, exampleSketch)"
     ]
   },
+  {
+    "name": "mm",
+    "summary": "Millimeters conversion factor for current projects units.",
+    "description": "No matter what units the current project uses, this function will always return the conversion factor to millimeters.\nFor example, if the current project uses inches, this function will return `(1/25.4)`. If the current project uses millimeters, this function will return `1`.\n**Caution**: This function is only intended to be used when you absolutely MUST have different units in your code than the project settings. Otherwise, it is a bad pattern to use this function.\nWe merely provide these functions for convenience and readability, as `10 * mm()` is more readable that your intent is \"I want 10 millimeters\" than `10 * (1/25.4)`, if the project settings are in inches.",
+    "tags": [
+      "units"
+    ],
+    "args": [],
+    "returnValue": {
+      "name": "",
+      "type": "number",
+      "schema": {
+        "type": "number",
+        "format": "double"
+      },
+      "required": true
+    },
+    "unpublished": false,
+    "deprecated": false,
+    "examples": [
+      "const totalWidth = 10 * mm()"
+    ]
+  },
   {
     "name": "patternCircular2d",
     "summary": "Repeat a 2-dimensional sketch some number of times along a partial or",
@@ -252170,5 +252285,28 @@
     "examples": [
       "const exampleSketch = startSketchOn(\"XZ\")\n  |> startProfileAt([0, 0], %)\n  |> angledLine({ angle: 50, length: 45 }, %)\n  |> yLineTo(0, %)\n  |> close(%)\n\nconst example = extrude(5, exampleSketch)"
     ]
+  },
+  {
+    "name": "yd",
+    "summary": "Yards conversion factor for current projects units.",
+    "description": "No matter what units the current project uses, this function will always return the conversion factor to yards.\nFor example, if the current project uses inches, this function will return `36`. If the current project uses millimeters, this function will return `914.4`. If the current project uses yards, this function will return `1`.\n**Caution**: This function is only intended to be used when you absolutely MUST have different units in your code than the project settings. Otherwise, it is a bad pattern to use this function.\nWe merely provide these functions for convenience and readability, as `10 * yd()` is more readable that your intent is \"I want 10 yards\" than `10 * 914.4`, if the project settings are in millimeters.",
+    "tags": [
+      "units"
+    ],
+    "args": [],
+    "returnValue": {
+      "name": "",
+      "type": "number",
+      "schema": {
+        "type": "number",
+        "format": "double"
+      },
+      "required": true
+    },
+    "unpublished": false,
+    "deprecated": false,
+    "examples": [
+      "const totalWidth = 10 * yd()"
+    ]
   }
 ]