langref: Document destructuring

doc/langref.html.in

@@ -777,6 +777,30 @@
       implementation feature, not a language semantic, so it is not guaranteed to be observable to code.
       </p>
       {#header_close#}
+
+      {#header_open|Destructuring#}
+      <p>
+        Some aggregate values (e.g. {#link|Tuples#}, {#link|Arrays#}, {#link|Vectors#}) can be destructed using
+        destructuring assignment:
+      </p>
+      {#code|destructuring_to_existing.zig#}
+
+      <p>
+        A destructuring expression may only appear within a block (i.e. not at container scope).
+        The left hand side of the assignment must consist of a comma separated list,
+        each element of which may be either an {#link|result location|Result Location Semantics#} or a variable declaration:
+      </p>
+      {#code|destructuring_mixed.zig#}
+
+      <p>
+        A destructure may be prefixed with the {#syntax#}comptime{#endsyntax#} keyword, in which case the entire
+        destructure expression is evaluated at {#link|comptime#}. All {#syntax#}var{#endsyntax#}s declared would
+        be {#syntax#}comptime var{#endsyntax#}s and all expressions (both result locations and the assignee
+        expression) are evaluated at {#link|comptime#}.
+      </p>
+
+      {#see_also|Destructuring Tuples|Destructuring Arrays|Destructuring Vectors#}
+      {#header_close#}
       {#header_close#}
       {#header_close#}
       {#header_open|Zig Test#}
@@ -1878,6 +1902,15 @@ or
 
       {#see_also|Sentinel-Terminated Pointers|Sentinel-Terminated Slices#}
       {#header_close#}
+
+      {#header_open|Destructuring Arrays#}
+      <p>
+        Arrays can be destructured:
+      </p>
+      {#code|destructuring_arrays.zig#}
+
+      {#see_also|Destructuring|Destructuring Tuples|Destructuring Vectors#}
+      {#header_close#}
       {#header_close#}
 
       {#header_open|Vectors#}
@@ -1925,6 +1958,14 @@ or
       </p>
       {#see_also|@splat|@shuffle|@select|@reduce#}
 
+      {#header_open|Destructuring Vectors#}
+      <p>
+        Vectors can be destructured:
+      </p>
+      {#code|destructuring_vectors.zig#}
+      {#see_also|Destructuring|Destructuring Tuples|Destructuring Arrays#}
+      {#header_close#}
+
       {#header_close#}
 
       {#header_open|Pointers#}
@@ -2297,6 +2338,23 @@ or
       </p>
       {#code|test_tuples.zig#}
 
+      {#header_open|Destructuring Tuples#}
+      <p>
+        Tuples can be {#link|destructured|Destructuring#}.
+      </p>
+      <p>
+        Destructuring is helpful for returning multiple values from a block:
+      </p>
+      {#code|destructuring_block.zig#}
+
+      <p>
+        Destructuring is helpful for dealing with functions and built-ins that return multiple values
+        as a tuple:
+      </p>
+      {#code|destructuring_return_value.zig#}
+
+      {#see_also|Destructuring|Destructuring Arrays|Destructuring Vectors#}
+      {#header_close#}
       {#header_close#}
       {#see_also|comptime|@fieldParentPtr#}
       {#header_close#}

doc/langref/destructuring_block.zig

@@ -0,0 +1,22 @@
+const print = @import("std").debug.print;
+
+pub fn main() void {
+    const digits = [_]i8 { 3, 8, 9, 0, 7, 4, 1 };
+
+    const min, const max = blk: {
+        var min: i8 = 127;
+        var max: i8 = -128;
+
+        for (digits) |digit| {
+            if (digit < min) min = digit;
+            if (digit > max) max = digit;
+        }
+
+        break :blk .{ min, max };
+    };
+
+    print("min = {}", .{ min });
+    print("max = {}", .{ max });
+}
+
+// exe=succeed

doc/langref/destructuring_mixed.zig

@@ -0,0 +1,18 @@
+const print = @import("std").debug.print;
+
+pub fn main() void {
+    var x: u32 = undefined;
+
+    const tuple = .{ 1, 2, 3 };
+
+    x, var y : u32, const z = tuple;
+
+    print("x = {}\n", .{x});
+    print("y = {}\n", .{y});
+    print("z = {}\n", .{z});
+
+    // y are mutable
+    y = 100;
+}
+
+// exe=succeed

doc/langref/destructuring_return_value.zig

@@ -0,0 +1,14 @@
+const print = @import("std").debug.print;
+
+fn divmod(numerator: u32, denominator: u32) struct { u32, u32 } {
+    return .{ numerator / denominator, numerator % denominator };
+}
+
+pub fn main() void {
+    const div, const mod = divmod(10, 3);
+
+    print("10 / 3 = {}\n", .{div});
+    print("10 % 3 = {}\n", .{mod});
+}
+
+// exe=succeed

doc/langref/destructuring_to_existing.zig

@@ -0,0 +1,17 @@
+const print = @import("std").debug.print;
+
+pub fn main() void {
+    var x: u32 = undefined;
+    var y: u32 = undefined;
+    var z: u32 = undefined;
+
+    const tuple = .{ 1, 2, 3 };
+
+    x, y, z = tuple;
+
+    print("x = {}\n", .{x});
+    print("y = {}\n", .{y});
+    print("z = {}\n", .{z});
+}
+
+// exe=succeed