| 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,7 +2461,8 @@ or |
| 2461 | {#header_open|Tagged union#} | 2461 | {#header_open|Tagged union#} |
| 2462 | <p>Unions can be declared with an enum tag type. | 2462 | <p>Unions can be declared with an enum tag type. |
| 2463 | This turns the union into a <em>tagged</em> union, which makes it eligible | 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 | Tagged unions coerce to their tag type: {#link|Type Coercion: Unions and Enums#}. | 2466 | Tagged unions coerce to their tag type: {#link|Type Coercion: Unions and Enums#}. |
| 2466 | </p> | 2467 | </p> |
| 2467 | {#code|test_tagged_union.zig#} | 2468 | {#code|test_tagged_union.zig#} |
| ... | @@ -2594,6 +2595,13 @@ or | ... | @@ -2594,6 +2595,13 @@ or |
| 2594 | 2595 | ||
| 2595 | {#header_close#} | 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 | {#header_open|Labeled switch#} | 2605 | {#header_open|Labeled switch#} |
| 2598 | <p> | 2606 | <p> |
| 2599 | When a switch statement is labeled, it can be referenced from a | 2607 | When a switch statement is labeled, it can be referenced from a |
| ... | @@ -2659,12 +2667,13 @@ or | ... | @@ -2659,12 +2667,13 @@ or |
| 2659 | {#code|test_inline_else.zig#} | 2667 | {#code|test_inline_else.zig#} |
| 2660 | 2668 | ||
| 2661 | <p> | 2669 | <p> |
| 2662 | When using an inline prong switching on an union an additional | 2670 | When using an inline prong switching on an union an additional capture |
| 2663 | capture can be used to obtain the union's enum tag value. | 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 | </p> | 2673 | </p> |
| 2665 | {#code|test_inline_switch_union_tag.zig#} | 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 | {#header_close#} | 2677 | {#header_close#} |
| 2669 | {#header_close#} | 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,6 +18,11 @@ test "switch on tagged union" { |
| 18 | .ok => |value| try expect(value == 42), | 18 | .ok => |value| try expect(value == 42), |
| 19 | .not_ok => unreachable, | 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 | test "get tag type" { | 28 | test "get tag type" { |