authorgravatar for dev@87flowers.com87 <dev@87flowers.com> 2025-01-28 04:23:13+00:00
committergravatar for noreply@github.comGitHub <noreply@github.com> 2025-01-28 04:23:13+00:00
log183bb8b08403ab594cdc543c2db2503e7eac0052
tree9718b7651aae5caf7f39d68591359d84fc6e9c35
parent41e7604359a83d45fb4a755648f58919512b4513
signaturebadge-check Signed by PGP key B5690EEEBB952194

langref: Document destructuring (#21627)

7 files changed, 176 insertions(+), 0 deletions(-)

doc/langref.html.in+58
...@@ -781,6 +781,30 @@...@@ -781,6 +781,30 @@
781 implementation feature, not a language semantic, so it is not guaranteed to be observable to code.781 implementation feature, not a language semantic, so it is not guaranteed to be observable to code.
782 </p>782 </p>
783 {#header_close#}783 {#header_close#}
784
785 {#header_open|Destructuring#}
786 <p>
787 A destructuring assignment can separate elements of indexable aggregate types
788 ({#link|Tuples#}, {#link|Arrays#}, {#link|Vectors#}):
789 </p>
790 {#code|destructuring_to_existing.zig#}
791
792 <p>
793 A destructuring expression may only appear within a block (i.e. not at container scope).
794 The left hand side of the assignment must consist of a comma separated list,
795 each element of which may be either an lvalue (for instance, an existing `var`) or a variable declaration:
796 </p>
797 {#code|destructuring_mixed.zig#}
798
799 <p>
800 A destructure may be prefixed with the {#syntax#}comptime{#endsyntax#} keyword, in which case the entire
801 destructure expression is evaluated at {#link|comptime#}. All {#syntax#}var{#endsyntax#}s declared would
802 be {#syntax#}comptime var{#endsyntax#}s and all expressions (both result locations and the assignee
803 expression) are evaluated at {#link|comptime#}.
804 </p>
805
806 {#see_also|Destructuring Tuples|Destructuring Arrays|Destructuring Vectors#}
807 {#header_close#}
784 {#header_close#}808 {#header_close#}
785 {#header_close#}809 {#header_close#}
786 {#header_open|Zig Test#}810 {#header_open|Zig Test#}
...@@ -1882,6 +1906,15 @@ or...@@ -1882,6 +1906,15 @@ or
18821906
1883 {#see_also|Sentinel-Terminated Pointers|Sentinel-Terminated Slices#}1907 {#see_also|Sentinel-Terminated Pointers|Sentinel-Terminated Slices#}
1884 {#header_close#}1908 {#header_close#}
1909
1910 {#header_open|Destructuring Arrays#}
1911 <p>
1912 Arrays can be destructured:
1913 </p>
1914 {#code|destructuring_arrays.zig#}
1915
1916 {#see_also|Destructuring|Destructuring Tuples|Destructuring Vectors#}
1917 {#header_close#}
1885 {#header_close#}1918 {#header_close#}
18861919
1887 {#header_open|Vectors#}1920 {#header_open|Vectors#}
...@@ -1929,6 +1962,14 @@ or...@@ -1929,6 +1962,14 @@ or
1929 </p>1962 </p>
1930 {#see_also|@splat|@shuffle|@select|@reduce#}1963 {#see_also|@splat|@shuffle|@select|@reduce#}
19311964
1965 {#header_open|Destructuring Vectors#}
1966 <p>
1967 Vectors can be destructured:
1968 </p>
1969 {#code|destructuring_vectors.zig#}
1970 {#see_also|Destructuring|Destructuring Tuples|Destructuring Arrays#}
1971 {#header_close#}
1972
1932 {#header_close#}1973 {#header_close#}
19331974
1934 {#header_open|Pointers#}1975 {#header_open|Pointers#}
...@@ -2309,6 +2350,23 @@ or...@@ -2309,6 +2350,23 @@ or
2309 </p>2350 </p>
2310 {#code|test_tuples.zig#}2351 {#code|test_tuples.zig#}
23112352
2353 {#header_open|Destructuring Tuples#}
2354 <p>
2355 Tuples can be {#link|destructured|Destructuring#}.
2356 </p>
2357 <p>
2358 Tuple destructuring is helpful for returning multiple values from a block:
2359 </p>
2360 {#code|destructuring_block.zig#}
2361
2362 <p>
2363 Tuple destructuring is helpful for dealing with functions and built-ins that return multiple values
2364 as a tuple:
2365 </p>
2366 {#code|destructuring_return_value.zig#}
2367
2368 {#see_also|Destructuring|Destructuring Arrays|Destructuring Vectors#}
2369 {#header_close#}
2312 {#header_close#}2370 {#header_close#}
2313 {#see_also|comptime|@fieldParentPtr#}2371 {#see_also|comptime|@fieldParentPtr#}
2314 {#header_close#}2372 {#header_close#}
doc/langref/destructuring_arrays.zig created+18
...@@ -0,0 +1,18 @@
1const print = @import("std").debug.print;
2
3fn swizzleRgbaToBgra(rgba: [4]u8) [4]u8 {
4 // readable swizzling by destructuring
5 const r, const g, const b, const a = rgba;
6 return .{ b, g, r, a };
7}
8
9pub fn main() void {
10 const pos = [_]i32{ 1, 2 };
11 const x, const y = pos;
12 print("x = {}, y = {}\n", .{x, y});
13
14 const orange: [4]u8 = .{ 255, 165, 0, 255 };
15 print("{any}\n", .{swizzleRgbaToBgra(orange)});
16}
17
18// exe=succeed
doc/langref/destructuring_block.zig created+22
...@@ -0,0 +1,22 @@
1const print = @import("std").debug.print;
2
3pub fn main() void {
4 const digits = [_]i8 { 3, 8, 9, 0, 7, 4, 1 };
5
6 const min, const max = blk: {
7 var min: i8 = 127;
8 var max: i8 = -128;
9
10 for (digits) |digit| {
11 if (digit < min) min = digit;
12 if (digit > max) max = digit;
13 }
14
15 break :blk .{ min, max };
16 };
17
18 print("min = {}", .{ min });
19 print("max = {}", .{ max });
20}
21
22// exe=succeed
doc/langref/destructuring_mixed.zig created+21
...@@ -0,0 +1,21 @@
1const print = @import("std").debug.print;
2
3pub fn main() void {
4 var x: u32 = undefined;
5
6 const tuple = .{ 1, 2, 3 };
7
8 x, var y : u32, const z = tuple;
9
10 print("x = {}, y = {}, z = {}\n", .{x, y, z});
11
12 // y is mutable
13 y = 100;
14
15 // You can use _ to throw away unwanted values.
16 _, x, _ = tuple;
17
18 print("x = {}", .{x});
19}
20
21// exe=succeed
doc/langref/destructuring_return_value.zig created+14
...@@ -0,0 +1,14 @@
1const print = @import("std").debug.print;
2
3fn divmod(numerator: u32, denominator: u32) struct { u32, u32 } {
4 return .{ numerator / denominator, numerator % denominator };
5}
6
7pub fn main() void {
8 const div, const mod = divmod(10, 3);
9
10 print("10 / 3 = {}\n", .{div});
11 print("10 % 3 = {}\n", .{mod});
12}
13
14// exe=succeed
doc/langref/destructuring_to_existing.zig created+27
...@@ -0,0 +1,27 @@
1const print = @import("std").debug.print;
2
3pub fn main() void {
4 var x: u32 = undefined;
5 var y: u32 = undefined;
6 var z: u32 = undefined;
7
8 const tuple = .{ 1, 2, 3 };
9
10 x, y, z = tuple;
11
12 print("tuple: x = {}, y = {}, z = {}\n", .{x, y, z});
13
14 const array = [_]u32{ 4, 5, 6 };
15
16 x, y, z = array;
17
18 print("array: x = {}, y = {}, z = {}\n", .{x, y, z});
19
20 const vector: @Vector(3, u32) = .{ 7, 8, 9 };
21
22 x, y, z = vector;
23
24 print("vector: x = {}, y = {}, z = {}\n", .{x, y, z});
25}
26
27// exe=succeed
doc/langref/destructuring_vectors.zig created+16
...@@ -0,0 +1,16 @@
1const print = @import("std").debug.print;
2
3// emulate punpckldq
4pub fn unpack(x: @Vector(4, f32), y: @Vector(4, f32)) @Vector(4, f32) {
5 const a, const c, _, _ = x;
6 const b, const d, _, _ = y;
7 return .{ a, b, c, d };
8}
9
10pub fn main() void {
11 const x: @Vector(4, f32) = .{ 1.0, 2.0, 3.0, 4.0 };
12 const y: @Vector(4, f32) = .{ 5.0, 6.0, 7.0, 8.0 };
13 print("{}", .{unpack(x, y)});
14}
15
16// exe=succeed