Commit 9b714e019c1c26143112ee1e7930a95cd94797f4 | zig

author	Andrew Kelley <andrew@ziglang.org> 2024-01-18 20:34:00-08:00
committer	GitHub <noreply@github.com> 2024-01-18 20:34:00-08:00
log	9b714e019c1c26143112ee1e7930a95cd94797f4
tree	d8d3b1eb5ece3904ee7d0a9430c6d2deca42f44b
parent	6ecf3b1ef35d1ce8a89a20ecead244a2c37269c6
parent	ef93a36cd5b783d50b595f5f7eea7422649081a7
signature	Signed by PGP key B5690EEEBB952194

Merge pull request #18219 from g-cassie/optional-documentation-tweaks

Minor improvements to the Optionals documentation

1 files changed, 57 insertions(+), 39 deletions(-)

doc
- langref.html.in

doc/langref.html.in+57-39

 @@ -4640,6 +4640,7 @@ test "while null capture" {
     }
     try expect(sum1 == 3);
+    // null capture with an else block
     var sum2: u32 = 0;
     numbers_left = 3;
     while (eventuallyNullSequence()) |value| {
 @@ -4647,6 +4648,15 @@ test "while null capture" {
     } else {
         try expect(sum2 == 3);
     }
+    // null capture with a continue expression
+    var i: u32 = 0;
+    var sum3: u32 = 0;
+    numbers_left = 3;
+    while (eventuallyNullSequence()) |value| : (i += 1) {
+        sum3 += value;
+    }
+    try expect(i == 3);
 }
 var numbers_left: u32 = undefined;
 @@ -4927,87 +4937,92 @@ test "if boolean" {
     }
 }
-test "if optional" {
+test "if error union" {
-    // If expressions test for null.
+    // If expressions test for errors.
+    // Note the |err| capture on the else.
-    const a: ?u32 = 0;
+    const a: anyerror!u32 = 0;
     if (a) |value| {
         try expect(value == 0);
-    } else {
+    } else |err| {
+        _ = err;
         unreachable;
     }
-    const b: ?u32 = null;
+    const b: anyerror!u32 = error.BadValue;
-    if (b) |_| {
+    if (b) |value| {
+        _ = value;
         unreachable;
-    } else {
+    } else |err| {
-        try expect(true);
+        try expect(err == error.BadValue);
     }
-    // The else is not required.
+    // The else and |err| capture is strictly required.
     if (a) |value| {
         try expect(value == 0);
-    }
+    } else |_| {}
-    // To test against null only, use the binary equality operator.
+    // To check only the error value, use an empty block expression.
-    if (b == null) {
+    if (b) |_| {} else |err| {
-        try expect(true);
+        try expect(err == error.BadValue);
     }
     // Access the value by reference using a pointer capture.
-    var c: ?u32 = 3;
+    var c: anyerror!u32 = 3;
     if (c) |*value| {
-        value.* = 2;
+        value.* = 9;
+    } else |_| {
+        unreachable;
     }
     if (c) |value| {
-        try expect(value == 2);
+        try expect(value == 9);
-    } else {
+    } else |_| {
         unreachable;
     }
 }
+      {#code_end#}
+      {#header_open|if with Optionals#}
-test "if error union" {
+      {#code_begin|test|test_if_optionals#}
-    // If expressions test for errors.
+const expect = @import("std").testing.expect;
-    // Note the |err| capture on the else.
-    const a: anyerror!u32 = 0;
+test "if optional" {
+    // If expressions test for null.
+    const a: ?u32 = 0;
     if (a) |value| {
         try expect(value == 0);
-    } else |err| {
+    } else {
-        _ = err;
         unreachable;
     }
-    const b: anyerror!u32 = error.BadValue;
+    const b: ?u32 = null;
-    if (b) |value| {
+    if (b) |_| {
-        _ = value;
         unreachable;
-    } else |err| {
+    } else {
-        try expect(err == error.BadValue);
+        try expect(true);
     }
-    // The else and |err| capture is strictly required.
+    // The else is not required.
     if (a) |value| {
         try expect(value == 0);
-    } else |_| {}
+    }
-    // To check only the error value, use an empty block expression.
+    // To test against null only, use the binary equality operator.
-    if (b) |_| {} else |err| {
+    if (b == null) {
-        try expect(err == error.BadValue);
+        try expect(true);
     }
     // Access the value by reference using a pointer capture.
-    var c: anyerror!u32 = 3;
+    var c: ?u32 = 3;
     if (c) |*value| {
-        value.* = 9;
+        value.* = 2;
-    } else |_| {
-        unreachable;
     }
     if (c) |value| {
-        try expect(value == 9);
+        try expect(value == 2);
-    } else |_| {
+    } else {
         unreachable;
     }
 }
 @@ -5056,6 +5071,7 @@ test "if error union with optional" {
     }
 }
       {#code_end#}
+      {#header_close#}
       {#see_also|Optionals|Errors#}
       {#header_close#}
       {#header_open|defer#}
 @@ -6379,6 +6395,8 @@ test "optional pointers" {
 }
       {#code_end#}
       {#header_close#}
+      {#see_also|while with Optionals|if with Optionals#}
       {#header_close#}
       {#header_open|Casting#}
       <p>