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 @@
781781 implementation feature, not a language semantic, so it is not guaranteed to be observable to code.
782782 </p>
783783 {#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#}
784808 {#header_close#}
785809 {#header_close#}
786810 {#header_open|Zig Test#}
......@@ -1882,6 +1906,15 @@ or
18821906
18831907 {#see_also|Sentinel-Terminated Pointers|Sentinel-Terminated Slices#}
18841908 {#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#}
18851918 {#header_close#}
18861919
18871920 {#header_open|Vectors#}
......@@ -1929,6 +1962,14 @@ or
19291962 </p>
19301963 {#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
19321973 {#header_close#}
19331974
19341975 {#header_open|Pointers#}
......@@ -2309,6 +2350,23 @@ or
23092350 </p>
23102351 {#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#}
23122370 {#header_close#}
23132371 {#see_also|comptime|@fieldParentPtr#}
23142372 {#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