diff --git a/content/pages/docs/kcl-std/functions/std-solver-angle.md b/content/pages/docs/kcl-std/functions/std-solver-angle.md index 3b21024a..a1195c33 100644 --- a/content/pages/docs/kcl-std/functions/std-solver-angle.md +++ b/content/pages/docs/kcl-std/functions/std-solver-angle.md @@ -11,13 +11,17 @@ Constrain lines to meet at a given angle. solver::angle(@input: [Segment; 2]) ``` - +The angle is measured counterclockwise from the first line to the second +line, modulo 180 degrees, so the order of the lines matters: +`angle([a, b]) == 30deg` is equivalent to `angle([b, a]) == 150deg`. +Because the angle is measured modulo 180 degrees, it does not matter +which end of each line segment is its start or end. ### Arguments | Name | Type | Description | Required | |----------|------|-------------|----------| -| `input` | [[`Segment`](/docs/kcl-std/types/std-types-Segment); 2] | The two line segments whose relative angle should match the value set with `==`. | Yes | +| `input` | [[`Segment`](/docs/kcl-std/types/std-types-Segment); 2] | The two line segments whose relative angle should match the value set with `==`, measured counterclockwise from the first line to the second, modulo 180 degrees. The order of the lines matters. | Yes | ### Examples diff --git a/content/pages/docs/kcl-std/functions/std-solver-distance.md b/content/pages/docs/kcl-std/functions/std-solver-distance.md index e44cb45a..3e4d44eb 100644 --- a/content/pages/docs/kcl-std/functions/std-solver-distance.md +++ b/content/pages/docs/kcl-std/functions/std-solver-distance.md @@ -1,11 +1,11 @@ --- title: "solver::distance" subtitle: "Function in std::solver" -excerpt: "Constrain the distance between two points." +excerpt: "Constrain the distance between two sketch entities." layout: manual --- -Constrain the distance between two points. +Constrain the distance between two sketch entities. ```kcl solver::distance( @@ -14,13 +14,34 @@ solver::distance( ) ``` +The distance is always non-negative, and the order of the two entities +does not matter: `distance([a, b]) == 5mm` and `distance([b, a]) == 5mm` +are the same constraint. This differs from `horizontalDistance` and +`verticalDistance`, which are signed and order-sensitive. +Supported entity pairs (in either order): + +- Two points: the straight-line distance between them. +- Point and line: the perpendicular distance from the point to the + infinite line through the line segment. +- Two lines: constrains the lines to be parallel and separated by the + given perpendicular distance. +- Point and circle: the gap between the point and the nearest point on + the circle's perimeter, with the point kept outside the circle. +- Line and circle: the gap between the circle's perimeter and the + infinite line through the line segment, with the circle kept to one + side of the line. +- Two circles: the gap between the two perimeters, with each circle kept + outside the other. + +A point may be `ORIGIN`, and arcs are treated as the full circle through +them. ### Arguments | Name | Type | Description | Required | |----------|------|-------------|----------| -| `points` | [[`Segment`](/docs/kcl-std/types/std-types-Segment) or [`Point2d`](/docs/kcl-std/types/std-types-Point2d); 2] | Two sketch points, or one sketch point and `ORIGIN`, whose separation should match the value set with `==`. | Yes | +| `points` | [[`Segment`](/docs/kcl-std/types/std-types-Segment) or [`Point2d`](/docs/kcl-std/types/std-types-Point2d); 2] | Two sketch entities, or one sketch entity and `ORIGIN`, whose separation should match the value set with `==`. The order of the entities does not matter. | Yes | | `labelPosition` | [`Point2d`](/docs/kcl-std/types/std-types-Point2d) | Optional position for the displayed constraint label in the sketch's local 2D coordinate system. | No | diff --git a/content/pages/docs/kcl-std/functions/std-solver-horizontalDistance.md b/content/pages/docs/kcl-std/functions/std-solver-horizontalDistance.md index 5784909b..a8450a4f 100644 --- a/content/pages/docs/kcl-std/functions/std-solver-horizontalDistance.md +++ b/content/pages/docs/kcl-std/functions/std-solver-horizontalDistance.md @@ -14,13 +14,18 @@ solver::horizontalDistance( ) ``` - +The distance is signed, so the order of the points matters: the value set +with `==` equals the second point's X coordinate minus the first point's +X coordinate. A positive value places the second point at a greater X +than the first, and swapping the points negates the sign. For example, +`horizontalDistance([ORIGIN, point]) == 5mm` places `point` at X = 5mm, +while `horizontalDistance([point, ORIGIN]) == 5mm` places it at X = -5mm. ### Arguments | Name | Type | Description | Required | |----------|------|-------------|----------| -| `points` | [[`Segment`](/docs/kcl-std/types/std-types-Segment) or [`Point2d`](/docs/kcl-std/types/std-types-Point2d); 2] | Two sketch points, or one sketch point and `ORIGIN`, whose X-axis separation should match the value set with `==`. | Yes | +| `points` | [[`Segment`](/docs/kcl-std/types/std-types-Segment) or [`Point2d`](/docs/kcl-std/types/std-types-Point2d); 2] | Two sketch points, or one sketch point and `ORIGIN`. The value set with `==` equals the second point's X coordinate minus the first point's X coordinate, so the order of the points determines the sign. | Yes | | `labelPosition` | [`Point2d`](/docs/kcl-std/types/std-types-Point2d) | Optional position for the displayed constraint label in the sketch's local 2D coordinate system. | No | diff --git a/content/pages/docs/kcl-std/functions/std-solver-verticalDistance.md b/content/pages/docs/kcl-std/functions/std-solver-verticalDistance.md index 9df95e5f..2ee4d4ac 100644 --- a/content/pages/docs/kcl-std/functions/std-solver-verticalDistance.md +++ b/content/pages/docs/kcl-std/functions/std-solver-verticalDistance.md @@ -14,13 +14,18 @@ solver::verticalDistance( ) ``` - +The distance is signed, so the order of the points matters: the value set +with `==` equals the second point's Y coordinate minus the first point's +Y coordinate. A positive value places the second point at a greater Y +than the first, and swapping the points negates the sign. For example, +`verticalDistance([ORIGIN, point]) == 5mm` places `point` at Y = 5mm, +while `verticalDistance([point, ORIGIN]) == 5mm` places it at Y = -5mm. ### Arguments | Name | Type | Description | Required | |----------|------|-------------|----------| -| `points` | [[`Segment`](/docs/kcl-std/types/std-types-Segment) or [`Point2d`](/docs/kcl-std/types/std-types-Point2d); 2] | Two sketch points, or one sketch point and `ORIGIN`, whose Y-axis separation should match the value set with `==`. | Yes | +| `points` | [[`Segment`](/docs/kcl-std/types/std-types-Segment) or [`Point2d`](/docs/kcl-std/types/std-types-Point2d); 2] | Two sketch points, or one sketch point and `ORIGIN`. The value set with `==` equals the second point's Y coordinate minus the first point's Y coordinate, so the order of the points determines the sign. | Yes | | `labelPosition` | [`Point2d`](/docs/kcl-std/types/std-types-Point2d) | Optional position for the displayed constraint label in the sketch's local 2D coordinate system. | No | diff --git a/content/pages/docs/kcl-std/functions/std-string-toString.md b/content/pages/docs/kcl-std/functions/std-string-toString.md new file mode 100644 index 00000000..1082922d --- /dev/null +++ b/content/pages/docs/kcl-std/functions/std-string-toString.md @@ -0,0 +1,65 @@ +--- +title: "string::toString" +subtitle: "Function in std::string" +excerpt: "Convert a number to human-readable text." +layout: manual +--- + +Convert a number to human-readable text. + +```kcl +string::toString(@num: number): string +``` + +Defined for every [`number`](/docs/kcl-std/types/std-types-number) value, including the non-finite ones. + +| Value | Result | Why | +|---|---|---| +| `12` | `"12"` | no units, so no suffix | +| `1.5` | `"1.5"` | never rounded | +| `0.1 + 0.2` | `"0.30000000000000004"` | no digits are dropped | +| `-7` | `"-7"` | | +| `-0` | `"0"` | the sign of zero is not kept | +| `3_` | `"3_"` | a count keeps its `_` | +| `12mm` | `"12mm"` | a concrete length keeps its suffix | +| `12cm`, `12m`, `1.5in`, `2ft`, `3yd` | `"12cm"`, `"12m"`, `"1.5in"`, `"2ft"`, `"3yd"` | every length unit does | +| `90deg` | `"90deg"` | a concrete angle keeps its suffix | +| `1.5rad` | `"1.5rad"` | both angle units do | +| `2mm + 10mm` | `"12mm"` | arithmetic that keeps its units | +| `2mm * 10mm` | `"20"` | units no longer tracked, so none is shown | +| `1 / 0` | `"Infinity"` | | +| `-1 / 0` | `"-Infinity"` | | +| `0 / 0` | `"NaN"` | | +| `1mm / 0` | `"Infinity"` | a non-finite value never carries a unit | + +The output is meant to be read, not parsed. Some results are not valid KCL +source and reading one back is not supported. + +### Arguments + +| Name | Type | Description | Required | +|----------|------|-------------|----------| +| `num` | [`number`](/docs/kcl-std/types/std-types-number) | The number to convert. | Yes | + +### Returns + +[`string`](/docs/kcl-std/types/std-types-string) - A sequence of characters + + +### Examples + +```kcl +lengthText = 12mm + |> string::toString() + +assertIs(lengthText == "12mm") + +countText = string::toString(3_) + +assertIs(countText == "3_") + +``` + + + + diff --git a/content/pages/docs/kcl-std/functions/std-vector-add.md b/content/pages/docs/kcl-std/functions/std-vector-add.md index 2eecaa65..d6f4598f 100644 --- a/content/pages/docs/kcl-std/functions/std-vector-add.md +++ b/content/pages/docs/kcl-std/functions/std-vector-add.md @@ -1,11 +1,11 @@ --- title: "vector::add" subtitle: "Function in std::vector" -excerpt: "Adds every element of u to its corresponding element in v. Both vectors must have the same length. Returns a new vector of the same length. In other words, component-wise addition." +excerpt: "Adds every element of u to its corresponding element in v. Both vectors must have the same number of elements. Returns a new vector with the same number of elements. In other words, component-wise addition." layout: manual --- -Adds every element of u to its corresponding element in v. Both vectors must have the same length. Returns a new vector of the same length. In other words, component-wise addition. +Adds every element of u to its corresponding element in v. Both vectors must have the same number of elements. Returns a new vector with the same number of elements. In other words, component-wise addition. ```kcl vector::add( diff --git a/content/pages/docs/kcl-std/functions/std-vector-div.md b/content/pages/docs/kcl-std/functions/std-vector-div.md index 1760e034..b53a336f 100644 --- a/content/pages/docs/kcl-std/functions/std-vector-div.md +++ b/content/pages/docs/kcl-std/functions/std-vector-div.md @@ -1,11 +1,11 @@ --- title: "vector::div" subtitle: "Function in std::vector" -excerpt: "Divides every element of u by its corresponding element in v. Both vectors must have the same length. Returns a new vector of the same length. In other words, component-wise division." +excerpt: "Divides every element of u by its corresponding element in v. Both vectors must have the same number of elements. Returns a new vector with the same number of elements. In other words, component-wise division." layout: manual --- -Divides every element of u by its corresponding element in v. Both vectors must have the same length. Returns a new vector of the same length. In other words, component-wise division. +Divides every element of u by its corresponding element in v. Both vectors must have the same number of elements. Returns a new vector with the same number of elements. In other words, component-wise division. ```kcl vector::div( diff --git a/content/pages/docs/kcl-std/functions/std-vector-mul.md b/content/pages/docs/kcl-std/functions/std-vector-mul.md index 71a902f8..c3f7824f 100644 --- a/content/pages/docs/kcl-std/functions/std-vector-mul.md +++ b/content/pages/docs/kcl-std/functions/std-vector-mul.md @@ -1,11 +1,11 @@ --- title: "vector::mul" subtitle: "Function in std::vector" -excerpt: "Multiplies every element of u by its corresponding element in v. Both vectors must have the same length. Returns a new vector of the same length. In other words, component-wise multiplication." +excerpt: "Multiplies every element of u by its corresponding element in v. Both vectors must have the same number of elements. Returns a new vector with the same number of elements. In other words, component-wise multiplication." layout: manual --- -Multiplies every element of u by its corresponding element in v. Both vectors must have the same length. Returns a new vector of the same length. In other words, component-wise multiplication. +Multiplies every element of u by its corresponding element in v. Both vectors must have the same number of elements. Returns a new vector with the same number of elements. In other words, component-wise multiplication. ```kcl vector::mul( diff --git a/content/pages/docs/kcl-std/functions/std-vector-sub.md b/content/pages/docs/kcl-std/functions/std-vector-sub.md index ddea36e0..d4723283 100644 --- a/content/pages/docs/kcl-std/functions/std-vector-sub.md +++ b/content/pages/docs/kcl-std/functions/std-vector-sub.md @@ -1,11 +1,11 @@ --- title: "vector::sub" subtitle: "Function in std::vector" -excerpt: "Subtracts from every element of u its corresponding element in v. Both vectors must have the same length. Returns a new vector of the same length. In other words, component-wise subtraction." +excerpt: "Subtracts from every element of u its corresponding element in v. Both vectors must have the same number of elements. Returns a new vector with the same number of elements. In other words, component-wise subtraction." layout: manual --- -Subtracts from every element of u its corresponding element in v. Both vectors must have the same length. Returns a new vector of the same length. In other words, component-wise subtraction. +Subtracts from every element of u its corresponding element in v. Both vectors must have the same number of elements. Returns a new vector with the same number of elements. In other words, component-wise subtraction. ```kcl vector::sub( diff --git a/content/pages/docs/kcl-std/index.md b/content/pages/docs/kcl-std/index.md index f393d706..ec5b6c34 100644 --- a/content/pages/docs/kcl-std/index.md +++ b/content/pages/docs/kcl-std/index.md @@ -190,6 +190,7 @@ layout: manual * [**std::string**](/docs/kcl-std/modules/std-string) * [`string::isEqual`](/docs/kcl-std/functions/std-string-isEqual) * [`string::lowercase`](/docs/kcl-std/functions/std-string-lowercase) + * [`string::toString`](/docs/kcl-std/functions/std-string-toString) * [`string::trim`](/docs/kcl-std/functions/std-string-trim) * [`string::trimEnd`](/docs/kcl-std/functions/std-string-trimEnd) * [`string::trimStart`](/docs/kcl-std/functions/std-string-trimStart) diff --git a/content/pages/docs/kcl-std/modules/std-string.md b/content/pages/docs/kcl-std/modules/std-string.md index 65f02dd1..284c2752 100644 --- a/content/pages/docs/kcl-std/modules/std-string.md +++ b/content/pages/docs/kcl-std/modules/std-string.md @@ -16,6 +16,7 @@ their contents. * [`string::isEqual`](/docs/kcl-std/functions/std-string-isEqual) * [`string::lowercase`](/docs/kcl-std/functions/std-string-lowercase) +* [`string::toString`](/docs/kcl-std/functions/std-string-toString) * [`string::trim`](/docs/kcl-std/functions/std-string-trim) * [`string::trimEnd`](/docs/kcl-std/functions/std-string-trimEnd) * [`string::trimStart`](/docs/kcl-std/functions/std-string-trimStart)