| author |  Justus Klausecker <justus@klausecker.de> 2026-01-10 14:57:23+01:00 |
| committer |  Matthew Lugg <mlugg@mlugg.co.uk> 2026-01-11 11:37:17+00:00 |
| log | 5a376d97d4595f12dffaf54c4cfc303b0e902cc6 |
| tree | 3e6b5d1b55e379d87ae321ed74a68e643d9631d5 |
| parent | 0b3b536f18957979374a00b2411943b4a37beb0f |
| signature |  Commit is signed but in an unrecognized format. |
langref: document new switch features
- switch on tagged union with runtime-captured tag
- switch on errors special cases3 files changed, 70 insertions(+), 4 deletions(-)
doc/langref.html.in+13-4
| ... | ... | @@ -2461,7 +2461,8 @@ or |
| 2461 | 2461 | {#header_open|Tagged union#} |
| 2462 | 2462 | <p>Unions can be declared with an enum tag type. |
| 2463 | 2463 | This turns the union into a <em>tagged</em> union, which makes it eligible |
| 2464 | to use with {#link|switch#} expressions. | |
| 2464 | to use with {#link|switch#} expressions. When switching on tagged unions, | |
| 2465 | the tag value can be obtained using an additional capture. | |
| 2465 | 2466 | Tagged unions coerce to their tag type: {#link|Type Coercion: Unions and Enums#}. |
| 2466 | 2467 | </p> |
| 2467 | 2468 | {#code|test_tagged_union.zig#} |
| ... | ... | @@ -2594,6 +2595,13 @@ or |
| 2594 | 2595 | |
| 2595 | 2596 | {#header_close#} |
| 2596 | 2597 | |
| 2598 | {#header_open|Switching on errors#} | |
| 2599 | <p> | |
| 2600 | When switching on errors, some special cases are allowed to simplify generic programming patterns: | |
| 2601 | </p> | |
| 2602 | {#code|test_switch_on_errors.zig#} | |
| 2603 | {#header_close#} | |
| 2604 | ||
| 2597 | 2605 | {#header_open|Labeled switch#} |
| 2598 | 2606 | <p> |
| 2599 | 2607 | When a switch statement is labeled, it can be referenced from a |
| ... | ... | @@ -2659,12 +2667,13 @@ or |
| 2659 | 2667 | {#code|test_inline_else.zig#} |
| 2660 | 2668 | |
| 2661 | 2669 | <p> |
| 2662 | When using an inline prong switching on an union an additional | |
| 2663 | capture can be used to obtain the union's enum tag value. | |
| 2670 | When using an inline prong switching on an union an additional capture | |
| 2671 | can be used to obtain the union's enum tag value at comptime, even though | |
| 2672 | its payload might only be known at runtime. | |
| 2664 | 2673 | </p> |
| 2665 | 2674 | {#code|test_inline_switch_union_tag.zig#} |
| 2666 | 2675 | |
| 2667 | {#see_also|inline while|inline for#} | |
| 2676 | {#see_also|inline while|inline for|Tagged union#} | |
| 2668 | 2677 | {#header_close#} |
| 2669 | 2678 | {#header_close#} |
| 2670 | 2679 |
doc/langref/test_switch_on_errors.zig created+52
| ... | ... | @@ -0,0 +1,52 @@ |
| 1 | const FileOpenError0 = error{ | |
| 2 | AccessDenied, | |
| 3 | OutOfMemory, | |
| 4 | FileNotFound, | |
| 5 | }; | |
| 6 | ||
| 7 | fn openFile0() FileOpenError0 { | |
| 8 | return error.OutOfMemory; | |
| 9 | } | |
| 10 | ||
| 11 | test "unreachable else prong" { | |
| 12 | switch (openFile0()) { | |
| 13 | error.AccessDenied, error.FileNotFound => |e| return e, | |
| 14 | error.OutOfMemory => {}, | |
| 15 | else => unreachable, // technically unreachable, but will still compile! | |
| 16 | } | |
| 17 | ||
| 18 | // Allowed unreachable else prongs are: | |
| 19 | // `else => unreachable,` | |
| 20 | // `else => return,` | |
| 21 | // `else => |e| return e,` (where `e` is any identifier) | |
| 22 | } | |
| 23 | ||
| 24 | const FileOpenError1 = error{ | |
| 25 | AccessDenied, | |
| 26 | SystemResources, | |
| 27 | FileNotFound, | |
| 28 | }; | |
| 29 | ||
| 30 | fn openFile1() FileOpenError1 { | |
| 31 | return error.SystemResources; | |
| 32 | } | |
| 33 | ||
| 34 | fn openFileGeneric(comptime kind: u1) switch (kind) { | |
| 35 | 0 => FileOpenError0, | |
| 36 | 1 => FileOpenError1, | |
| 37 | } { | |
| 38 | return switch (kind) { | |
| 39 | 0 => openFile0(), | |
| 40 | 1 => openFile1(), | |
| 41 | }; | |
| 42 | } | |
| 43 | ||
| 44 | test "comptime unreachable errors not in error set" { | |
| 45 | switch (openFileGeneric(1)) { | |
| 46 | error.AccessDenied, error.FileNotFound => |e| return e, | |
| 47 | error.OutOfMemory => comptime unreachable, // not in `FileOpenError1`! | |
| 48 | error.SystemResources => {}, | |
| 49 | } | |
| 50 | } | |
| 51 | ||
| 52 | // test |
doc/langref/test_tagged_union.zig+5
| ... | ... | @@ -18,6 +18,11 @@ test "switch on tagged union" { |
| 18 | 18 | .ok => |value| try expect(value == 42), |
| 19 | 19 | .not_ok => unreachable, |
| 20 | 20 | } |
| 21 | ||
| 22 | switch (c) { | |
| 23 | .ok => |_, tag| try expect(tag == .ok), | |
| 24 | .not_ok => unreachable, | |
| 25 | } | |
| 21 | 26 | } |
| 22 | 27 | |
| 23 | 28 | test "get tag type" { |