diff --git a/content/pages/docs/kcl-lang/arithmetic.md b/content/pages/docs/kcl-lang/arithmetic.md index be5898b1..15c37802 100644 --- a/content/pages/docs/kcl-lang/arithmetic.md +++ b/content/pages/docs/kcl-lang/arithmetic.md @@ -18,7 +18,9 @@ KCL supports the usual arithmetic operators on numbers and logic operators on bo | `\|` | Logical 'or' | | `!` | Unary logical 'not' | -KCL also supports comparsion operators which operate on numbers and produce booleans: +KCL also supports comparison operators which produce booleans. Ordering +comparisons operate on numbers, while `==` and `!=` operate on numbers or +strings: | Operator | Meaning | |----------|---------| @@ -29,6 +31,9 @@ KCL also supports comparsion operators which operate on numbers and produce bool | `<=` | Less than or equal | | `>=` | Greater than or equal | +String equality is exact and case-sensitive. It does not perform Unicode +normalization. + Arithmetics and logic expressions can be arbitrairly combined with the usual rules of associativity and precedence, e.g., ``` diff --git a/content/pages/docs/kcl-lang/settings/project.md b/content/pages/docs/kcl-lang/settings/project.md index 1a316b33..3743c826 100644 --- a/content/pages/docs/kcl-lang/settings/project.md +++ b/content/pages/docs/kcl-lang/settings/project.md @@ -27,31 +27,36 @@ base_unit = "in" ## Available Settings -### cloud +### settings +#### meta -### settings +Information about the project itself. Choices about how settings are merged have prevent me (lee) from easily moving this out of the settings structure. +**Default:** None + +This setting has the following nested options: + +##### id -#### app -The settings for the Design Studio. **Default:** None -This setting has the following nested options: -##### named_views +#### app -Settings that affect the behavior of the command bar. +The settings for the Design Studio. **Default:** None +This setting has the following nested options: + ##### stream_idle_mode When the user is idle, and this is true, the stream will be torn down. @@ -66,19 +71,9 @@ Zookeeper reasoning mode. Uses the app default if not set. **Default:** None +##### named_views -#### meta - -Information about the project itself. Choices about how settings are merged have prevent me (lee) from easily moving this out of the settings structure. - - -**Default:** None - -This setting has the following nested options: - -##### id - - +Settings that affect the behavior of the command bar. **Default:** None @@ -98,6 +93,13 @@ This setting has the following nested options: The default unit to use in modeling dimensions. +**Default:** None + +##### highlight_edges + +Highlight edges of 3D objects? + + **Default:** None ##### enable_ssao @@ -114,12 +116,10 @@ When enabled, the grid will use a fixed size based on your selected units rather **Default:** None -##### highlight_edges -Highlight edges of 3D objects? +### cloud -**Default:** None diff --git a/content/pages/docs/kcl-lang/settings/user.md b/content/pages/docs/kcl-lang/settings/user.md index 9e905920..485eb7ae 100644 --- a/content/pages/docs/kcl-lang/settings/user.md +++ b/content/pages/docs/kcl-lang/settings/user.md @@ -63,16 +63,16 @@ Settings that affect the behavior while modeling. This setting has the following nested options: -##### backface_color +##### base_unit -The default color to use for surface backfaces. +The default unit to use in modeling dimensions. If not given, defaults to millimeters. **Default:** None -##### base_unit +##### camera_projection -The default unit to use in modeling dimensions. If not given, defaults to millimeters. +The projection mode the camera should use while modeling. **Default:** None @@ -84,9 +84,9 @@ The methodology the camera should use to orbit around the model. **Default:** None -##### camera_projection +##### highlight_edges -The projection mode the camera should use while modeling. +Highlight edges of 3D objects? **Default:** None @@ -98,23 +98,23 @@ Whether or not Screen Space Ambient Occlusion (SSAO) is enabled. **Default:** None -##### fixed_size_grid +##### backface_color -When enabled, the grid will use a fixed size based on your selected units rather than automatically scaling with zoom level. If true, the grid cells will be fixed-size, where the width is your default length unit. If false, the grid will get larger as you zoom out, and smaller as you zoom in. +The default color to use for surface backfaces. **Default:** None -##### highlight_edges +##### show_scale_grid -Highlight edges of 3D objects? +Whether or not to show a scale grid in the 3D modeling view **Default:** None -##### show_scale_grid +##### fixed_size_grid -Whether or not to show a scale grid in the 3D modeling view +When enabled, the grid will use a fixed size based on your selected units rather than automatically scaling with zoom level. If true, the grid cells will be fixed-size, where the width is your default length unit. If false, the grid will get larger as you zoom out, and smaller as you zoom in. **Default:** None diff --git a/content/pages/docs/kcl-samples/manifest.json b/content/pages/docs/kcl-samples/manifest.json index 63de0c8e..a918d63d 100644 --- a/content/pages/docs/kcl-samples/manifest.json +++ b/content/pages/docs/kcl-samples/manifest.json @@ -1110,8 +1110,7 @@ { "file": "main.kcl", "categories": [ - "Maker", - "Automotive" + "Maker" ], "pathFromProjectDirectoryToFirstFile": "stylized-car/main.kcl", "multipleFiles": false, @@ -1124,7 +1123,6 @@ { "file": "main.kcl", "categories": [ - "Automotive", "Maker" ], "pathFromProjectDirectoryToFirstFile": "stylized-cybertruck/main.kcl", @@ -1138,7 +1136,6 @@ { "file": "main.kcl", "categories": [ - "Automotive", "Maker" ], "pathFromProjectDirectoryToFirstFile": "stylized-dump-truck/main.kcl", @@ -1152,7 +1149,6 @@ { "file": "main.kcl", "categories": [ - "Automotive", "Maker" ], "pathFromProjectDirectoryToFirstFile": "stylized-firetruck/main.kcl", @@ -1166,7 +1162,6 @@ { "file": "main.kcl", "categories": [ - "Automotive", "Maker" ], "pathFromProjectDirectoryToFirstFile": "stylized-mini-bus/main.kcl", @@ -1180,7 +1175,6 @@ { "file": "main.kcl", "categories": [ - "Automotive", "Maker" ], "pathFromProjectDirectoryToFirstFile": "stylized-pickup-truck/main.kcl", diff --git a/content/pages/docs/kcl-samples/stylized-car/main.kcl b/content/pages/docs/kcl-samples/stylized-car/main.kcl index 1b70abd2..39dd2096 100644 --- a/content/pages/docs/kcl-samples/stylized-car/main.kcl +++ b/content/pages/docs/kcl-samples/stylized-car/main.kcl @@ -1,6 +1,6 @@ // Stylized Toy Car // A simplified, parametric 3-D model of a small toy car intended for use as a low-poly prop in real-time engines, visualization scenes, or rapid prototyping. -// Categories: Maker, Automotive +// Categories: Maker // The model includes: // - A chassis block forming the vehicle’s base diff --git a/content/pages/docs/kcl-samples/stylized-cybertruck/main.kcl b/content/pages/docs/kcl-samples/stylized-cybertruck/main.kcl index 7b02de81..6fc4079e 100644 --- a/content/pages/docs/kcl-samples/stylized-cybertruck/main.kcl +++ b/content/pages/docs/kcl-samples/stylized-cybertruck/main.kcl @@ -1,6 +1,6 @@ // Stylized Toy Cybertruck // A simplified, parametric 3-D model of a low-poly toy cybertruck, intended for use as a game-ready asset, concept visualization, or real-time rendering demo. -// Categories: Automotive, Maker +// Categories: Maker // The model includes: // - A chassis block forming the vehicle’s base diff --git a/content/pages/docs/kcl-samples/stylized-dump-truck/main.kcl b/content/pages/docs/kcl-samples/stylized-dump-truck/main.kcl index 0d97c3b9..12144e33 100644 --- a/content/pages/docs/kcl-samples/stylized-dump-truck/main.kcl +++ b/content/pages/docs/kcl-samples/stylized-dump-truck/main.kcl @@ -1,6 +1,6 @@ // Stylized Toy Dump Truck // A simplified, parametric 3D toy dump truck with front cab, extended cargo bed, and four wheels. -// Categories: Automotive, Maker +// Categories: Maker // The model includes: // - A chassis block forming the base diff --git a/content/pages/docs/kcl-samples/stylized-firetruck/main.kcl b/content/pages/docs/kcl-samples/stylized-firetruck/main.kcl index ed7e36ae..e32c5fb8 100644 --- a/content/pages/docs/kcl-samples/stylized-firetruck/main.kcl +++ b/content/pages/docs/kcl-samples/stylized-firetruck/main.kcl @@ -1,6 +1,6 @@ // Stylized Toy Fire Truck // A toy parametric fire truck with extended rear compartment and roof ladder. Optimized for real-time rendering or schematic use in stylized design scenes. -// Categories: Automotive, Maker +// Categories: Maker // Set units and version @settings(defaultLengthUnit = m) diff --git a/content/pages/docs/kcl-samples/stylized-mini-bus/main.kcl b/content/pages/docs/kcl-samples/stylized-mini-bus/main.kcl index 4bfa9d04..9cfad2f4 100644 --- a/content/pages/docs/kcl-samples/stylized-mini-bus/main.kcl +++ b/content/pages/docs/kcl-samples/stylized-mini-bus/main.kcl @@ -1,6 +1,6 @@ // Stylized Toy Mini-Bus // A simplified, parametric 3-D model of a toy compact van or mini-bus, intended for use as a low-poly prop in real-time engines, visualization scenes, or rapid prototyping. -// Categories: Automotive, Maker +// Categories: Maker // The model includes: // - A solid chassis block forming the vehicle’s base diff --git a/content/pages/docs/kcl-samples/stylized-pickup-truck/main.kcl b/content/pages/docs/kcl-samples/stylized-pickup-truck/main.kcl index 7048801c..6fb90774 100644 --- a/content/pages/docs/kcl-samples/stylized-pickup-truck/main.kcl +++ b/content/pages/docs/kcl-samples/stylized-pickup-truck/main.kcl @@ -1,6 +1,6 @@ // Stylized Toy Pickup Truck // A simplified, parametric 3-D model of a toy pickup truck intended for use as a low-poly prop in real-time engines, visualization scenes, or rapid prototyping. -// Categories: Automotive, Maker +// Categories: Maker // The model includes: // - A chassis block forming the vehicle’s base diff --git a/content/pages/docs/kcl-std/functions/std-fail.md b/content/pages/docs/kcl-std/functions/std-fail.md new file mode 100644 index 00000000..59abcaf0 --- /dev/null +++ b/content/pages/docs/kcl-std/functions/std-fail.md @@ -0,0 +1,45 @@ +--- +title: "fail" +subtitle: "Function in std" +excerpt: "Stop KCL evaluation with a user-defined error." +layout: manual +--- + +**WARNING:** This function is experimental and may change or be removed. + +Stop KCL evaluation with a user-defined error. + +```kcl +fail(@msg: string): never +``` + +Use `fail` when evaluation cannot continue and the caller should receive a +specific error message. `fail` never returns a value. + +### Arguments + +| Name | Type | Description | Required | +|----------|------|-------------|----------| +| `msg` | [`string`](/docs/kcl-std/types/std-types-string) | Message reported to the caller. | Yes | + +### Returns + +[`never`](/docs/kcl-std/types/std-types-never) - The uninhabited type of computations that never complete normally. + + +### Examples + +```kcl +fn positive(@value: number): number { + return if value > 0 { + value + } else { + fail("value must be positive") + } +} + +``` + + + + diff --git a/content/pages/docs/kcl-std/functions/std-runtime-exit.md b/content/pages/docs/kcl-std/functions/std-runtime-exit.md index c3288a5d..ca7b6999 100644 --- a/content/pages/docs/kcl-std/functions/std-runtime-exit.md +++ b/content/pages/docs/kcl-std/functions/std-runtime-exit.md @@ -13,7 +13,16 @@ Exit the program early. exit() ``` +Exiting early can be helpful to see the intermediate output of a program to +help debug. Remember to always remove the call to `exit()` after debugging +is complete. +When `exit()` is used in an imported module, only the imported module exits +early. Because imported modules execute concurrently, `exit()` in one module +does not affect other modules. + +On the other hand, if you import a function from another module, and that +function calls `exit()`, then calling the function exits the caller. diff --git a/content/pages/docs/kcl-std/functions/std-sketch-extrude.md b/content/pages/docs/kcl-std/functions/std-sketch-extrude.md index a98022c8..1c6d0de7 100644 --- a/content/pages/docs/kcl-std/functions/std-sketch-extrude.md +++ b/content/pages/docs/kcl-std/functions/std-sketch-extrude.md @@ -9,11 +9,11 @@ Extend a 2-dimensional sketch or individual segment of a sketch through a third ```kcl extrude( - @sketches: [Sketch | Face | TaggedFace | TaggedEdge | Edge | Segment; 1+], + @sketches: [Sketch | Face | TaggedFace | TaggedEdge | Edge | Segment | any; 1+], length?: number(Length), to?: Point3d | Axis3d | Plane | Edge | Face | Sketch | Solid | TaggedEdge | TaggedFace | any, symmetric?: bool, - direction?: Point3d | Edge | TaggedEdge | Segment, + direction?: Point3d | Edge | TaggedEdge | Segment | any, bidirectionalLength?: number(Length), tagStart?: TagDecl, tagEnd?: TagDecl, @@ -39,11 +39,11 @@ can change this behavior by using the `method` parameter. See | Name | Type | Description | Required | |----------|------|-------------|----------| -| `sketches` | [[`Sketch`](/docs/kcl-std/types/std-types-Sketch) or [`Face`](/docs/kcl-std/types/std-types-Face) or [`TaggedFace`](/docs/kcl-std/types/std-types-TaggedFace) or [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge) or [`Edge`](/docs/kcl-std/types/std-types-Edge) or [`Segment`](/docs/kcl-std/types/std-types-Segment); 1+] | Which sketch or sketches should be extruded. | Yes | +| `sketches` | [[`Sketch`](/docs/kcl-std/types/std-types-Sketch) or [`Face`](/docs/kcl-std/types/std-types-Face) or [`TaggedFace`](/docs/kcl-std/types/std-types-TaggedFace) or [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge) or [`Edge`](/docs/kcl-std/types/std-types-Edge) or [`Segment`](/docs/kcl-std/types/std-types-Segment) or [`any`](/docs/kcl-std/types/std-types-any); 1+] | Which sketch or sketches should be extruded. Experimental face API: edge specifier objects (`{ sideFaces = [faceTag1, faceTag2], endFaces? = [...], index? }`) are not ready for generated or user-facing KCL yet; prefer existing sketch, face, tagged face, tagged edge, edge, or segment forms until point-and-click and migration support ships. | Yes | | `length` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | How far to extrude the given sketches. Incompatible with `to`. | No | | `to` | [`Point3d`](/docs/kcl-std/types/std-types-Point3d) or [`Axis3d`](/docs/kcl-std/types/std-types-Axis3d) or [`Plane`](/docs/kcl-std/types/std-types-Plane) or [`Edge`](/docs/kcl-std/types/std-types-Edge) or [`Face`](/docs/kcl-std/types/std-types-Face) or [`Sketch`](/docs/kcl-std/types/std-types-Sketch) or [`Solid`](/docs/kcl-std/types/std-types-Solid) or [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge) or [`TaggedFace`](/docs/kcl-std/types/std-types-TaggedFace) or [`any`](/docs/kcl-std/types/std-types-any) | Reference to extrude to. Incompatible with `length` and `twistAngle`. Experimental face API: edge specifier objects (`{ sideFaces = [faceTag1, faceTag2], endFaces? = [...], index? }`) are not ready for generated or user-facing KCL yet; prefer existing point, axis, plane, edge, face, sketch, solid, or tag forms until point-and-click and migration support ships. | No | | `symmetric` | [`bool`](/docs/kcl-std/types/std-types-bool) | If true, the extrusion will happen symmetrically around the sketch. Otherwise, the extrusion will happen on only one side of the sketch. | No | -| `direction` | [`Point3d`](/docs/kcl-std/types/std-types-Point3d) or [`Edge`](/docs/kcl-std/types/std-types-Edge) or [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge) or [`Segment`](/docs/kcl-std/types/std-types-Segment) | If specified, will extrude in this direction instead of the sketch plane normal. If an edge is being extruded, this defaults to halfway between the faces on either side of the edge. | No | +| `direction` | [`Point3d`](/docs/kcl-std/types/std-types-Point3d) or [`Edge`](/docs/kcl-std/types/std-types-Edge) or [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge) or [`Segment`](/docs/kcl-std/types/std-types-Segment) or [`any`](/docs/kcl-std/types/std-types-any) | If specified, will extrude in this direction instead of the sketch plane normal. If an edge is being extruded, this defaults to halfway between the faces on either side of the edge. | No | | `bidirectionalLength` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | If specified, will also extrude in the opposite direction to 'distance' to the specified distance. If 'symmetric' is true, this value is ignored. | No | | `tagStart` | [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl) | A named tag for the face at the start of the extrusion, i.e. the original sketch. | No | | `tagEnd` | [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl) | A named tag for the face at the end of the extrusion, i.e. the new face created by extruding the original sketch. | No | @@ -766,3 +766,5 @@ extrude002 = extrude( touch-action="pan-y" > + + diff --git a/content/pages/docs/kcl-std/functions/std-string-isEqual.md b/content/pages/docs/kcl-std/functions/std-string-isEqual.md new file mode 100644 index 00000000..d45c6d40 --- /dev/null +++ b/content/pages/docs/kcl-std/functions/std-string-isEqual.md @@ -0,0 +1,58 @@ +--- +title: "string::isEqual" +subtitle: "Function in std::string" +excerpt: "Compare two strings for equality." +layout: manual +--- + +Compare two strings for equality. + +```kcl +string::isEqual( + @text: string, + to: string, + caseInsensitive?: bool, +): bool +``` + +By default, this performs an exact, case-sensitive comparison equivalent +to the `==` operator. Set `caseInsensitive` to `true` to compare using +locale-independent full Unicode case folding. + +Full case folding may expand characters; for example, `Straße` and +`STRASSE` compare as equal. The exact mappings follow the Unicode data +bundled with KCL. + +Unicode normalization is not performed. Canonically equivalent strings +with different representations therefore compare as unequal. Empty strings +are valid inputs, and comparison is symmetric. + +This function always returns a Boolean predicate, including inside a sketch +block. It does not create an equivalence constraint. + +### Arguments + +| Name | Type | Description | Required | +|----------|------|-------------|----------| +| `text` | [`string`](/docs/kcl-std/types/std-types-string) | The string to compare. | Yes | +| `to` | [`string`](/docs/kcl-std/types/std-types-string) | The string to compare `text` with. | Yes | +| `caseInsensitive` | [`bool`](/docs/kcl-std/types/std-types-bool) | Whether to compare using locale-independent full Unicode case folding. | No | + +### Returns + +[`bool`](/docs/kcl-std/types/std-types-bool) - A boolean value. + + +### Examples + +```kcl +matches = "Straße" + |> string::isEqual(to = "STRASSE", caseInsensitive = true) + +assertIs(matches) + +``` + + + + diff --git a/content/pages/docs/kcl-std/functions/std-string-lowercase.md b/content/pages/docs/kcl-std/functions/std-string-lowercase.md new file mode 100644 index 00000000..f0ef5dba --- /dev/null +++ b/content/pages/docs/kcl-std/functions/std-string-lowercase.md @@ -0,0 +1,48 @@ +--- +title: "string::lowercase" +subtitle: "Function in std::string" +excerpt: "Convert all cased characters in a string to lowercase." +layout: manual +--- + +Convert all cased characters in a string to lowercase. + +```kcl +string::lowercase(@text: string): string +``` + +This conversion is Unicode-aware and locale-independent. Some conversions +depend on the surrounding characters; for example, a Greek capital sigma +becomes `ς` at the end of a word and `σ` elsewhere. Some characters expand +into multiple characters; for example, `İ` becomes `i` followed by a +combining dot above. The exact mappings follow the Unicode data bundled +with KCL. + +Unicode normalization is not performed. Canonically equivalent strings +therefore retain their original representations. Empty strings and strings +without cased characters are returned unchanged. + +### Arguments + +| Name | Type | Description | Required | +|----------|------|-------------|----------| +| `text` | [`string`](/docs/kcl-std/types/std-types-string) | The string to convert. | Yes | + +### Returns + +[`string`](/docs/kcl-std/types/std-types-string) - A sequence of characters + + +### Examples + +```kcl +result = "KCL ΟΣ" + |> string::lowercase() + +assertIs(result == "kcl ος") + +``` + + + + diff --git a/content/pages/docs/kcl-std/functions/std-string-trim.md b/content/pages/docs/kcl-std/functions/std-string-trim.md new file mode 100644 index 00000000..d738b2fb --- /dev/null +++ b/content/pages/docs/kcl-std/functions/std-string-trim.md @@ -0,0 +1,44 @@ +--- +title: "string::trim" +subtitle: "Function in std::string" +excerpt: "Remove whitespace from the start and end of a string." +layout: manual +--- + +Remove whitespace from the start and end of a string. + +```kcl +string::trim(@text: string): string +``` + +Whitespace is defined by Unicode's `White_Space` property and includes +spaces, tabs, newlines, and non-breaking spaces. Whitespace inside the +string is preserved. + +If the input is empty or contains only whitespace, this returns an empty +string. Unicode normalization and case conversion are not performed. + +### Arguments + +| Name | Type | Description | Required | +|----------|------|-------------|----------| +| `text` | [`string`](/docs/kcl-std/types/std-types-string) | The string to trim. | Yes | + +### Returns + +[`string`](/docs/kcl-std/types/std-types-string) - A sequence of characters + + +### Examples + +```kcl +result = " KCL strings " + |> string::trim() + +assertIs(result == "KCL strings") + +``` + + + + diff --git a/content/pages/docs/kcl-std/functions/std-string-trimEnd.md b/content/pages/docs/kcl-std/functions/std-string-trimEnd.md new file mode 100644 index 00000000..768b1c09 --- /dev/null +++ b/content/pages/docs/kcl-std/functions/std-string-trimEnd.md @@ -0,0 +1,47 @@ +--- +title: "string::trimEnd" +subtitle: "Function in std::string" +excerpt: "Remove whitespace from the end of a string." +layout: manual +--- + +Remove whitespace from the end of a string. + +```kcl +string::trimEnd(@text: string): string +``` + +Whitespace is defined by Unicode's `White_Space` property and includes +spaces, tabs, newlines, and non-breaking spaces. Only the contiguous +whitespace at the end is removed; whitespace at the start or inside the +string is preserved. + +The end is the end of the string's character sequence, independent of how +the text is displayed. If the input is empty or contains only whitespace, +this returns an empty string. Unicode normalization and case conversion are +not performed. + +### Arguments + +| Name | Type | Description | Required | +|----------|------|-------------|----------| +| `text` | [`string`](/docs/kcl-std/types/std-types-string) | The string to trim. | Yes | + +### Returns + +[`string`](/docs/kcl-std/types/std-types-string) - A sequence of characters + + +### Examples + +```kcl +result = " KCL strings " + |> string::trimEnd() + +assertIs(result == " KCL strings") + +``` + + + + diff --git a/content/pages/docs/kcl-std/functions/std-string-trimStart.md b/content/pages/docs/kcl-std/functions/std-string-trimStart.md new file mode 100644 index 00000000..c600cea8 --- /dev/null +++ b/content/pages/docs/kcl-std/functions/std-string-trimStart.md @@ -0,0 +1,47 @@ +--- +title: "string::trimStart" +subtitle: "Function in std::string" +excerpt: "Remove whitespace from the start of a string." +layout: manual +--- + +Remove whitespace from the start of a string. + +```kcl +string::trimStart(@text: string): string +``` + +Whitespace is defined by Unicode's `White_Space` property and includes +spaces, tabs, newlines, and non-breaking spaces. Only the contiguous +whitespace at the start is removed; whitespace inside or at the end of the +string is preserved. + +The start is the beginning of the string's character sequence, independent +of how the text is displayed. If the input is empty or contains only +whitespace, this returns an empty string. Unicode normalization and case +conversion are not performed. + +### Arguments + +| Name | Type | Description | Required | +|----------|------|-------------|----------| +| `text` | [`string`](/docs/kcl-std/types/std-types-string) | The string to trim. | Yes | + +### Returns + +[`string`](/docs/kcl-std/types/std-types-string) - A sequence of characters + + +### Examples + +```kcl +result = " KCL strings " + |> string::trimStart() + +assertIs(result == "KCL strings ") + +``` + + + + diff --git a/content/pages/docs/kcl-std/functions/std-string-uppercase.md b/content/pages/docs/kcl-std/functions/std-string-uppercase.md new file mode 100644 index 00000000..376b3da7 --- /dev/null +++ b/content/pages/docs/kcl-std/functions/std-string-uppercase.md @@ -0,0 +1,45 @@ +--- +title: "string::uppercase" +subtitle: "Function in std::string" +excerpt: "Convert all cased characters in a string to uppercase." +layout: manual +--- + +Convert all cased characters in a string to uppercase. + +```kcl +string::uppercase(@text: string): string +``` + +This conversion is Unicode-aware and locale-independent. Some characters +expand into multiple characters; for example, `ß` becomes `SS`. The exact +mappings follow the Unicode data bundled with KCL. + +Unicode normalization is not performed. Canonically equivalent strings +therefore retain their original representations. Empty strings and strings +without cased characters are returned unchanged. + +### Arguments + +| Name | Type | Description | Required | +|----------|------|-------------|----------| +| `text` | [`string`](/docs/kcl-std/types/std-types-string) | The string to convert. | Yes | + +### Returns + +[`string`](/docs/kcl-std/types/std-types-string) - A sequence of characters + + +### Examples + +```kcl +result = "Straße" + |> string::uppercase() + +assertIs(result == "STRASSE") + +``` + + + + diff --git a/content/pages/docs/kcl-std/functions/std-transform-mirror3d.md b/content/pages/docs/kcl-std/functions/std-transform-mirror3d.md index c5615f3b..8ba16c32 100644 --- a/content/pages/docs/kcl-std/functions/std-transform-mirror3d.md +++ b/content/pages/docs/kcl-std/functions/std-transform-mirror3d.md @@ -10,7 +10,7 @@ Create a mirror image of a 3D solid/surface/body, across some specified mirror a ```kcl mirror3d( @bodies: [Solid; 1+], - across: Edge | Plane | Axis3d | Segment, + across: Edge | Plane | Axis3d | Segment | any, ): [Solid; 1+] ``` @@ -21,7 +21,7 @@ mirror3d( | Name | Type | Description | Required | |----------|------|-------------|----------| | `bodies` | [[`Solid`](/docs/kcl-std/types/std-types-Solid); 1+] | The body or bodies to be reflected. | Yes | -| `across` | [`Edge`](/docs/kcl-std/types/std-types-Edge) or [`Plane`](/docs/kcl-std/types/std-types-Plane) or [`Axis3d`](/docs/kcl-std/types/std-types-Axis3d) or [`Segment`](/docs/kcl-std/types/std-types-Segment) | The axis (or other geometry) to reflect across. | Yes | +| `across` | [`Edge`](/docs/kcl-std/types/std-types-Edge) or [`Plane`](/docs/kcl-std/types/std-types-Plane) or [`Axis3d`](/docs/kcl-std/types/std-types-Axis3d) or [`Segment`](/docs/kcl-std/types/std-types-Segment) or [`any`](/docs/kcl-std/types/std-types-any) | The axis (or other geometry) to reflect across. An edge specifier object such as `{ sideFaces = [faceTag1, faceTag2] }` can identify a solid edge without using its UUID. | Yes | ### Returns diff --git a/content/pages/docs/kcl-std/index.md b/content/pages/docs/kcl-std/index.md index b37e8810..f393d706 100644 --- a/content/pages/docs/kcl-std/index.md +++ b/content/pages/docs/kcl-std/index.md @@ -14,6 +14,7 @@ layout: manual * [`clone`](/docs/kcl-std/functions/std-clone) * [`edgeId`](/docs/kcl-std/functions/std-edgeId) * [`faceId`](/docs/kcl-std/functions/std-faceId) + * [`fail`](/docs/kcl-std/functions/std-fail) Experimental * [`helix`](/docs/kcl-std/functions/std-helix) * [`offsetPlane`](/docs/kcl-std/functions/std-offsetPlane) * [**std::appearance**](/docs/kcl-std/modules/std-appearance) @@ -186,6 +187,13 @@ layout: manual * [`solver::tangent`](/docs/kcl-std/functions/std-solver-tangent) * [`solver::vertical`](/docs/kcl-std/functions/std-solver-vertical) * [`solver::verticalDistance`](/docs/kcl-std/functions/std-solver-verticalDistance) +* [**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::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) + * [`string::uppercase`](/docs/kcl-std/functions/std-string-uppercase) * [**std::transform**](/docs/kcl-std/modules/std-transform) * [`delete`](/docs/kcl-std/functions/std-transform-delete) Experimental * [`hide`](/docs/kcl-std/functions/std-transform-hide) @@ -255,6 +263,7 @@ See also the [types overview](/docs/kcl-lang/types) * [`any`](/docs/kcl-std/types/std-types-any) * [`bool`](/docs/kcl-std/types/std-types-bool) * [`fn`](/docs/kcl-std/types/std-types-fn) + * [`never`](/docs/kcl-std/types/std-types-never) Experimental * [`none`](/docs/kcl-std/types/std-types-none) Experimental * [`number`](/docs/kcl-std/types/std-types-number) * [`string`](/docs/kcl-std/types/std-types-string) diff --git a/content/pages/docs/kcl-std/modules/std-string.md b/content/pages/docs/kcl-std/modules/std-string.md new file mode 100644 index 00000000..65f02dd1 --- /dev/null +++ b/content/pages/docs/kcl-std/modules/std-string.md @@ -0,0 +1,23 @@ +--- +title: "string" +subtitle: "Module in std" +excerpt: "Operations on KCL strings. " +layout: manual +--- + +Operations on KCL strings. + +This module provides functions for transforming strings and inspecting +their contents. + + + +## Functions and constants + +* [`string::isEqual`](/docs/kcl-std/functions/std-string-isEqual) +* [`string::lowercase`](/docs/kcl-std/functions/std-string-lowercase) +* [`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) +* [`string::uppercase`](/docs/kcl-std/functions/std-string-uppercase) + diff --git a/content/pages/docs/kcl-std/modules/std-types.md b/content/pages/docs/kcl-std/modules/std-types.md index 281bd5a4..8deca1d3 100644 --- a/content/pages/docs/kcl-std/modules/std-types.md +++ b/content/pages/docs/kcl-std/modules/std-types.md @@ -42,6 +42,7 @@ does. * [`in`](/docs/kcl-std/types/std-types-in) * [`m`](/docs/kcl-std/types/std-types-m) * [`mm`](/docs/kcl-std/types/std-types-mm) +* [`never`](/docs/kcl-std/types/std-types-never) * [`none`](/docs/kcl-std/types/std-types-none) * [`number`](/docs/kcl-std/types/std-types-number) * [`rad`](/docs/kcl-std/types/std-types-rad) diff --git a/content/pages/docs/kcl-std/modules/std.md b/content/pages/docs/kcl-std/modules/std.md index f9b70f3d..6812c3c0 100644 --- a/content/pages/docs/kcl-std/modules/std.md +++ b/content/pages/docs/kcl-std/modules/std.md @@ -28,6 +28,7 @@ You might also want the [KCL language reference](/docs/kcl-lang) or the [KCL gui * [`sketch`](/docs/kcl-std/modules/std-sketch) * [`solid`](/docs/kcl-std/modules/std-solid) * [`solver`](/docs/kcl-std/modules/std-solver) +* [`string::string`](/docs/kcl-std/modules/std-string) * [`sweep::sweep`](/docs/kcl-std/modules/std-sweep) * [`transform`](/docs/kcl-std/modules/std-transform) * [`turns::turns`](/docs/kcl-std/modules/std-turns) @@ -56,6 +57,7 @@ You might also want the [KCL language reference](/docs/kcl-lang) or the [KCL gui * [`clone`](/docs/kcl-std/functions/std-clone) * [`edgeId`](/docs/kcl-std/functions/std-edgeId) * [`faceId`](/docs/kcl-std/functions/std-faceId) +* [`fail`](/docs/kcl-std/functions/std-fail) * [`helix`](/docs/kcl-std/functions/std-helix) * [`offsetPlane`](/docs/kcl-std/functions/std-offsetPlane) diff --git a/content/pages/docs/kcl-std/types/std-types-never.md b/content/pages/docs/kcl-std/types/std-types-never.md new file mode 100644 index 00000000..6ce46339 --- /dev/null +++ b/content/pages/docs/kcl-std/types/std-types-never.md @@ -0,0 +1,18 @@ +--- +title: "never" +subtitle: "Type in std::types" +excerpt: "The uninhabited type of computations that never complete normally." +layout: manual +--- + +**WARNING:** This type is experimental and may change or be removed. + +The uninhabited type of computations that never complete normally. + +[`never`](/docs/kcl-std/types/std-types-never) has no values and is a subtype of every type. Use it as the return +type of a function that always stops evaluation by raising an error. A +function declared to return [`never`](/docs/kcl-std/types/std-types-never) produces a type error if it returns a +value or reaches the end of its body. + + +