authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2024-01-18 20:34:00-08:00
committergravatar for noreply@github.comGitHub <noreply@github.com> 2024-01-18 20:34:00-08:00
log9b714e019c1c26143112ee1e7930a95cd94797f4
treed8d3b1eb5ece3904ee7d0a9430c6d2deca42f44b
parent6ecf3b1ef35d1ce8a89a20ecead244a2c37269c6
parentef93a36cd5b783d50b595f5f7eea7422649081a7
signaturebadge-check 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+57-39
......@@ -4640,6 +4640,7 @@ test "while null capture" {
46404640 }
46414641 try expect(sum1 == 3);
46424642
4643 // null capture with an else block
46434644 var sum2: u32 = 0;
46444645 numbers_left = 3;
46454646 while (eventuallyNullSequence()) |value| {
......@@ -4647,6 +4648,15 @@ test "while null capture" {
46474648 } else {
46484649 try expect(sum2 == 3);
46494650 }
4651
4652 // null capture with a continue expression
4653 var i: u32 = 0;
4654 var sum3: u32 = 0;
4655 numbers_left = 3;
4656 while (eventuallyNullSequence()) |value| : (i += 1) {
4657 sum3 += value;
4658 }
4659 try expect(i == 3);
46504660}
46514661
46524662var numbers_left: u32 = undefined;
......@@ -4927,87 +4937,92 @@ test "if boolean" {
49274937 }
49284938}
49294939
4930test "if optional" {
4931 // If expressions test for null.
4940test "if error union" {
4941 // If expressions test for errors.
4942 // Note the |err| capture on the else.
49324943
4933 const a: ?u32 = 0;
4944 const a: anyerror!u32 = 0;
49344945 if (a) |value| {
49354946 try expect(value == 0);
4936 } else {
4947 } else |err| {
4948 _ = err;
49374949 unreachable;
49384950 }
49394951
4940 const b: ?u32 = null;
4941 if (b) |_| {
4952 const b: anyerror!u32 = error.BadValue;
4953 if (b) |value| {
4954 _ = value;
49424955 unreachable;
4943 } else {
4944 try expect(true);
4956 } else |err| {
4957 try expect(err == error.BadValue);
49454958 }
49464959
4947 // The else is not required.
4960 // The else and |err| capture is strictly required.
49484961 if (a) |value| {
49494962 try expect(value == 0);
4950 }
4963 } else |_| {}
49514964
4952 // To test against null only, use the binary equality operator.
4953 if (b == null) {
4954 try expect(true);
4965 // To check only the error value, use an empty block expression.
4966 if (b) |_| {} else |err| {
4967 try expect(err == error.BadValue);
49554968 }
49564969
49574970 // Access the value by reference using a pointer capture.
4958 var c: ?u32 = 3;
4971 var c: anyerror!u32 = 3;
49594972 if (c) |*value| {
4960 value.* = 2;
4973 value.* = 9;
4974 } else |_| {
4975 unreachable;
49614976 }
49624977
49634978 if (c) |value| {
4964 try expect(value == 2);
4965 } else {
4979 try expect(value == 9);
4980 } else |_| {
49664981 unreachable;
49674982 }
49684983}
4984 {#code_end#}
4985 {#header_open|if with Optionals#}
49694986
4970test "if error union" {
4971 // If expressions test for errors.
4972 // Note the |err| capture on the else.
4987 {#code_begin|test|test_if_optionals#}
4988const expect = @import("std").testing.expect;
49734989
4974 const a: anyerror!u32 = 0;
4990test "if optional" {
4991 // If expressions test for null.
4992
4993 const a: ?u32 = 0;
49754994 if (a) |value| {
49764995 try expect(value == 0);
4977 } else |err| {
4978 _ = err;
4996 } else {
49794997 unreachable;
49804998 }
49814999
4982 const b: anyerror!u32 = error.BadValue;
4983 if (b) |value| {
4984 _ = value;
5000 const b: ?u32 = null;
5001 if (b) |_| {
49855002 unreachable;
4986 } else |err| {
4987 try expect(err == error.BadValue);
5003 } else {
5004 try expect(true);
49885005 }
49895006
4990 // The else and |err| capture is strictly required.
5007 // The else is not required.
49915008 if (a) |value| {
49925009 try expect(value == 0);
4993 } else |_| {}
5010 }
49945011
4995 // To check only the error value, use an empty block expression.
4996 if (b) |_| {} else |err| {
4997 try expect(err == error.BadValue);
5012 // To test against null only, use the binary equality operator.
5013 if (b == null) {
5014 try expect(true);
49985015 }
49995016
50005017 // Access the value by reference using a pointer capture.
5001 var c: anyerror!u32 = 3;
5018 var c: ?u32 = 3;
50025019 if (c) |*value| {
5003 value.* = 9;
5004 } else |_| {
5005 unreachable;
5020 value.* = 2;
50065021 }
50075022
50085023 if (c) |value| {
5009 try expect(value == 9);
5010 } else |_| {
5024 try expect(value == 2);
5025 } else {
50115026 unreachable;
50125027 }
50135028}
......@@ -5056,6 +5071,7 @@ test "if error union with optional" {
50565071 }
50575072}
50585073 {#code_end#}
5074 {#header_close#}
50595075 {#see_also|Optionals|Errors#}
50605076 {#header_close#}
50615077 {#header_open|defer#}
......@@ -6379,6 +6395,8 @@ test "optional pointers" {
63796395}
63806396 {#code_end#}
63816397 {#header_close#}
6398
6399 {#see_also|while with Optionals|if with Optionals#}
63826400 {#header_close#}
63836401 {#header_open|Casting#}
63846402 <p>