From 3bc1e32859682e8090d48dbde2991de5f24431c5 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 29 Jul 2026 15:54:42 +0000 Subject: [PATCH 1/2] Update KCL docs --- .../kcl-std/functions/std-sketch-region.md | 55 ++++++++-------- .../kcl-std/functions/std-string-toString.md | 65 +++++++++++++++++++ .../docs/kcl-std/functions/std-vector-add.md | 4 +- .../docs/kcl-std/functions/std-vector-div.md | 4 +- .../docs/kcl-std/functions/std-vector-mul.md | 4 +- .../docs/kcl-std/functions/std-vector-sub.md | 4 +- content/pages/docs/kcl-std/index.md | 1 + .../pages/docs/kcl-std/modules/std-string.md | 1 + 8 files changed, 103 insertions(+), 35 deletions(-) create mode 100644 content/pages/docs/kcl-std/functions/std-string-toString.md diff --git a/content/pages/docs/kcl-std/functions/std-sketch-region.md b/content/pages/docs/kcl-std/functions/std-sketch-region.md index d34d20e3..60a68c15 100644 --- a/content/pages/docs/kcl-std/functions/std-sketch-region.md +++ b/content/pages/docs/kcl-std/functions/std-sketch-region.md @@ -17,31 +17,26 @@ region( ): Sketch ``` -Form the region from sketch block segments that have a given point within a -closed boundary. When using a 2D point, not a point from the sketch, the -`sketch` parameter is required to specify which sketch the region is from. +Prefer the `segments` parameter. It forms a region by tracing the first +segment from its start point to the intersection with the second segment, +then turning at each intersection using `direction` until returning to the +first segment. -Alternatively, form the region by tracing the first segment from its start -point to the intersection with the second segment, and turn at each -intersection using the `direction` until returning back to the first -segment. +As a fallback, use the `point` parameter to select the closed boundary that +contains a given point. When using a 2D point rather than a point from the +sketch, provide the `sketch` parameter to specify which sketch the region is +from. -Important: Creating a region using the `segments` parameter is currently -only supported when there is a single closed region in the sketch. If the -sketch may have multiple regions, use the `point` parameter instead. Until -this limitation is lifted, using a point to select a region is preferred. - -To help allow the region's point to move with the sketch, which may be -created parametrically, consider creating a construction point in the sketch -and constraining it into place. Then you can refer to the point to create -the region. +To make a fallback point move with a parametric sketch, consider creating a +construction point in the sketch and constraining it into place. You can then +refer to that point to create the region. ### Arguments | Name | Type | Description | Required | |----------|------|-------------|----------| -| `point` | [`Point2d`](/docs/kcl-std/types/std-types-Point2d) or [`Segment`](/docs/kcl-std/types/std-types-Segment) | A point that is within the region's boundary. | No | -| `segments` | [[`Segment`](/docs/kcl-std/types/std-types-Segment); 1+] | The first two segments that form the region's boundary. In case of a circle, the one circle segment that forms the region. This parameter is currently only supported when there is only one region in the sketch. If the sketch may have multiple regions, use the `point` parameter instead. | No | +| `point` | [`Point2d`](/docs/kcl-std/types/std-types-Point2d) or [`Segment`](/docs/kcl-std/types/std-types-Segment) | A fallback point that is within the region's boundary. | No | +| `segments` | [[`Segment`](/docs/kcl-std/types/std-types-Segment); 1+] | The first two segments that form the region's boundary. In case of a circle, the one circle segment that forms the region. This is the preferred way to create a region. | No | | `intersectionIndex` | [`number(_)`](/docs/kcl-std/types/std-types-number) | Index of the intersection of the first segment with the second segment to use as the region's boundary. The default is `-1`, which uses the last intersection. This is only used when the `segments` argument is provided. | No | | `direction` | [`string`](/docs/kcl-std/types/std-types-string) | `CCW` for counterclockwise, `CW` for clockwise. Default is `CCW`. This is only used when the `segments` argument is provided. | No | | `sketch` | [`any`](/docs/kcl-std/types/std-types-any) | The sketch that the region is from. This is required when point is a [`Point2d`](/docs/kcl-std/types/std-types-Point2d). | No | @@ -54,6 +49,9 @@ the region. ### Examples ```kcl +@settings(kclVersion = 2.0) + +// `region` traces counterclockwise by default. triangle = sketch(on = XY) { line1 = line(start = [var -0.05mm, var -0.01mm], end = [var 3.88mm, var 0.81mm]) line2 = line(start = [var 3.88mm, var 0.81mm], end = [var 0.92mm, var 4.67mm]) @@ -65,7 +63,7 @@ triangle = sketch(on = XY) { equalLength([line2, line3]) } -r = region(point = [0.5mm, 0.5mm], sketch = triangle) +r = region(segments = [triangle.line1, triangle.line2]) extrude(r, length = 5) ``` @@ -85,21 +83,24 @@ extrude(r, length = 5) ```kcl +@settings(kclVersion = 2.0) + +// Set `direction = CW` when the segments trace the boundary clockwise. trapezoid = sketch(on = XY) { - line1 = line(start = [var 0mm, var 0mm], end = [var 4mm, var 0mm]) - line2 = line(start = [var 4mm, var 0mm], end = [var 4mm, var 3mm]) - line3 = line(start = [var 4mm, var 3mm], end = [var 0mm, var 3mm]) - line4 = line(start = [var 0mm, var 3mm], end = [var 0mm, var 0mm]) + line1 = line(start = [var 0mm, var 0mm], end = [var 0mm, var 3mm]) + line2 = line(start = [var 0mm, var 3mm], end = [var 4mm, var 3mm]) + line3 = line(start = [var 4mm, var 3mm], end = [var 4mm, var 0mm]) + line4 = line(start = [var 4mm, var 0mm], end = [var 0mm, var 0mm]) coincident([line1.end, line2.start]) coincident([line2.end, line3.start]) coincident([line3.end, line4.start]) coincident([line4.end, line1.start]) - vertical(line2) - horizontal(line3) - parallel([line1, line3]) + vertical(line1) + horizontal(line2) + parallel([line2, line4]) } -r = region(point = [1mm, 1mm], sketch = trapezoid) +r = region(segments = [trapezoid.line1, trapezoid.line2], direction = CW) extrude(r, length = 3) ``` 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) From 67fc37a60bd4aa7c559b645ba6fbfd2fb7d4bc96 Mon Sep 17 00:00:00 2001 From: Pierre Jacquier Date: Thu, 30 Jul 2026 09:51:24 -0400 Subject: [PATCH 2/2] Clean up, keep only region notes which are already released --- .../kcl-std/functions/std-string-toString.md | 65 ------------------- .../docs/kcl-std/functions/std-vector-add.md | 4 +- .../docs/kcl-std/functions/std-vector-div.md | 4 +- .../docs/kcl-std/functions/std-vector-mul.md | 4 +- .../docs/kcl-std/functions/std-vector-sub.md | 4 +- content/pages/docs/kcl-std/index.md | 1 - .../pages/docs/kcl-std/modules/std-string.md | 1 - 7 files changed, 8 insertions(+), 75 deletions(-) delete mode 100644 content/pages/docs/kcl-std/functions/std-string-toString.md diff --git a/content/pages/docs/kcl-std/functions/std-string-toString.md b/content/pages/docs/kcl-std/functions/std-string-toString.md deleted file mode 100644 index 1082922d..00000000 --- a/content/pages/docs/kcl-std/functions/std-string-toString.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -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 d6f4598f..2eecaa65 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 number of elements. Returns a new vector with the same number of elements. In other words, component-wise addition." +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." layout: manual --- -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. +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. ```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 b53a336f..1760e034 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 number of elements. Returns a new vector with the same number of elements. In other words, component-wise division." +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." layout: manual --- -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. +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. ```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 c3f7824f..71a902f8 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 number of elements. Returns a new vector with the same number of elements. In other words, component-wise multiplication." +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." layout: manual --- -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. +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. ```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 d4723283..ddea36e0 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 number of elements. Returns a new vector with the same number of elements. In other words, component-wise subtraction." +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." layout: manual --- -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. +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. ```kcl vector::sub( diff --git a/content/pages/docs/kcl-std/index.md b/content/pages/docs/kcl-std/index.md index ec5b6c34..f393d706 100644 --- a/content/pages/docs/kcl-std/index.md +++ b/content/pages/docs/kcl-std/index.md @@ -190,7 +190,6 @@ 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 284c2752..65f02dd1 100644 --- a/content/pages/docs/kcl-std/modules/std-string.md +++ b/content/pages/docs/kcl-std/modules/std-string.md @@ -16,7 +16,6 @@ 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)