mirror/zig
1
0
Fork 0
mirror of https://github.com/ziglang/zig.git synced 2025-12-20 13:13:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

Introduce Error Union and Use Writer

Browse Source 
This commit edits the "Hello, World!" introduction. It introduces Error Union
Types. Also, it changes `outStream` to `writer` in the code example and description.
This commit is contained in:
Paul Espinosa 2020-07-11 18:08:00 +07:00
parent e57458a94f
commit b45a2d72c8
1 changed files with 27 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
doc/langref.html.in
View File

@ -233,7 +233,7 @@
const std = @import("std"); const std = @import("std");
pub fn main() !void { pub fn main() !void {
const stdout = std.io.getStdOut().outStream(); const stdout = std.io.getStdOut().writer();
try stdout.print("Hello, {}!\n", .{"world"}); try stdout.print("Hello, {}!\n", .{"world"});
} }
{#code_end#} {#code_end#}
@ -269,16 +269,25 @@ pub fn main() !void {
</p> </p>
<p> <p>
A function is a block of any number of statements and expressions that, as a whole, perform a task. A function is a block of any number of statements and expressions that, as a whole, perform a task.
Functions may or may not return data after they are done performing their task. Functions may or may not return data after they are done performing their task. If a function
cannot perform its task, it might return an error. Zig makes all of this explicit.
</p> </p>
<p> <p>
In the <code>hello.zig</code> code sample, the <code>main</code> function is declared In the <code>hello.zig</code> code sample, the <code>main</code> function is declared
with the {#syntax#}!void{#endsyntax#} return type. This return type tells the Zig compiler with the {#syntax#}!void{#endsyntax#} return type. This return type is known as an {#link|Error Union Type#}.
and other people reading the code that the function will not return a value and it <i>might</i> fail. This syntax tells the Zig compiler that the function will either return an
The {#syntax#}!{#endsyntax#} (bang, exclamation mark) before the {#syntax#}void{#endsyntax#} error or a value. An error union type combines an {#link|Error Set Type#} and a {#link|Primitive Type|Primitive Types#}.
{#link|type|Primitive Types#} is what tells the Zig compiler an {#link|error|Errors#} <i>might</i> The full form of an error union type is
occur. The {#syntax#}void{#endsyntax#} return type tells the Zig compiler the <code>main</code> <code>&lt;error set type&gt;</code>{#syntax#}!{#endsyntax#}<code>&lt;primitive type&gt;</code>. In the code
function will not return a value. sample, the error set type is not explicitly written on the left side of the {#syntax#}!{#endsyntax#} operator.
When written this way, the error set type is a special kind of error union type that has an
{#link|inferred error set type|Inferred Error Sets#}. The {#syntax#}void{#endsyntax#} after the {#syntax#}!{#endsyntax#} operator
tells the compiler that the function will not return a value under normal circumstances (i.e. no errors occur).
</p>
<p>
Note to experienced programmers: Zig also has the boolean {#link|operator|Operators#} {#syntax#}!a{#endsyntax#}
where {#syntax#}a{#endsyntax#} is a value of type {#syntax#}bool{#endsyntax#}. Error union types contain the
name of the type in the syntax: {#syntax#}!{#endsyntax#}<code>&lt;primitive type&gt;</code>.
</p> </p>
<p> <p>
In Zig, a function's block of statements and expressions are surrounded by <code>{</code> and In Zig, a function's block of statements and expressions are surrounded by <code>{</code> and
@ -286,9 +295,9 @@ pub fn main() !void {
the task of outputting <code>Hello, world!</code> to standard output. the task of outputting <code>Hello, world!</code> to standard output.
</p> </p>
<p> <p>
First, a constant identifier, <code>stdout</code>, is initialized to represent the standard output First, a constant identifier, <code>stdout</code>, is initialized to represent standard output's
stream. Then, the program tries to print the <code>Hello, world!</code> message to the standard output writer. Then, the program tries to print the <code>Hello, world!</code>
stream. message to standard output.
</p> </p>
<p> <p>
Functions sometimes need information to perform their task. In Zig, information is passed Functions sometimes need information to perform their task. In Zig, information is passed
@ -310,14 +319,14 @@ pub fn main() !void {
more statements or expressions left to execute in the <code>main</code> function, so the program exits. more statements or expressions left to execute in the <code>main</code> function, so the program exits.
</p> </p>
<p> <p>
In Zig, the standard output stream's <code>print</code> function is allowed to fail because In Zig, the standard output writer's <code>print</code> function is allowed to fail because
it is actually a function defined for a generic output stream. Consider a generic output stream that it is actually a function defined as part of a generic Writer. Consider a generic Writer that
represents writing data to a file. When the disk is full, a write to the file will fail. However, represents writing data to a file. When the disk is full, a write to the file will fail.
we typically do not expect writing text to the standard output stream to fail. To avoid having However, we typically do not expect writing text to the standard output to fail. To avoid having
to handle the failure case of printing to a standard output, you can use alternate functions: the to handle the failure case of printing to standard output, you can use alternate functions: the
<code>std.log</code> function for proper logging or the <code>std.debug.print</code> function. <code>std.log</code> function for proper logging or the <code>std.debug.print</code> function.
This documentation will use the latter option to print to standard error (stderr) and silently This documentation will use the latter option to print to standard error (stderr) and silently return
return on failure. The next code sample, <code>hello_again.zig</code> demonstrates the use of on failure. The next code sample, <code>hello_again.zig</code> demonstrates the use of
<code>std.debug.print</code>. <code>std.debug.print</code>.
</p> </p>
{#code_begin|exe|hello_again#} {#code_begin|exe|hello_again#}