| ... | @@ -410,109 +410,20 @@ pub fn main() !void { | ... | @@ -410,109 +410,20 @@ pub fn main() !void { |
| 410 | } | 410 | } |
| 411 | {#code_end#} | 411 | {#code_end#} |
| 412 | <p> | 412 | <p> |
| 413 | The Zig code sample above demonstrates one way to create a program that will output: <samp>Hello, world!</samp>. | 413 | Most of the time, it more appropriate to write to stderr rather than stdout, and |
| 414 | </p> | 414 | whether or not the message is successfully written to the stream is irrelevant. |
| 415 | <p> | 415 | For this common case, there is a simpler API: |
| 416 | The code sample shows the contents of a file named <code class="file">hello.zig</code>. Files storing Zig | | |
| 417 | source code are {#link|UTF-8 encoded|Source Encoding#} text files. The files storing | | |
| 418 | Zig source code must be named with the <code class="file"><em>.zig</em></code> extension. | | |
| 419 | </p> | | |
| 420 | <p> | | |
| 421 | Following the <code class="file">hello.zig</code> Zig code sample, the {#link|Zig Build System#} is used | | |
| 422 | to build an executable program from the <code class="file">hello.zig</code> source code. Then, the | | |
| 423 | <code class="file">hello</code> program is executed showing its output <samp>Hello, world!</samp>. The | | |
| 424 | lines beginning with <samp>$</samp> represent command line prompts and a command. | | |
| 425 | Everything else is program output. | | |
| 426 | </p> | | |
| 427 | <p> | | |
| 428 | The code sample begins by adding the {#link|Zig Standard Library#} to the build using the {#link|@import#} builtin function. | | |
| 429 | The {#syntax#}@import("std"){#endsyntax#} function call creates a structure that represents the Zig Standard Library. | | |
| 430 | The code then {#link|declares|Container Level Variables#} a | | |
| 431 | {#link|constant identifier|Assignment#}, named {#syntax#}std{#endsyntax#}, that gives access to the features of the Zig Standard Library. | | |
| 432 | </p> | | |
| 433 | <p> | | |
| 434 | Next, a {#link|public function|Functions#}, {#syntax#}pub fn{#endsyntax#}, named {#syntax#}main{#endsyntax#} | | |
| 435 | is declared. The {#syntax#}main{#endsyntax#} function is necessary because it tells the Zig compiler where the program starts. Programs | | |
| 436 | designed to be executed will need a {#syntax#}pub fn main{#endsyntax#} function. | | |
| 437 | </p> | | |
| 438 | <aside role="note" aria-label="Note about main function"> | | |
| 439 | <p> | | |
| 440 | For more advanced use cases, Zig offers other features to inform the compiler where the program starts. Also, libraries do not need a | | |
| 441 | {#syntax#}pub fn main{#endsyntax#} function because library code is called by other programs or libraries. | | |
| 442 | </p> | | |
| 443 | </aside> | | |
| 444 | <p> | | |
| 445 | A function is a block of any number of statements and expressions, that as a whole, perform a task. | | |
| 446 | Functions may or may not return data after they are done performing their task. If a function | | |
| 447 | cannot perform its task, it might return an error. Zig makes all of this explicit. | | |
| 448 | </p> | | |
| 449 | <p> | | |
| 450 | In the <code class="file">hello.zig</code> code sample, the <code>main</code> function is declared | | |
| 451 | with the {#syntax#}!void{#endsyntax#} return type. This return type is known as an {#link|Error Union Type#}. | | |
| 452 | This syntax tells the Zig compiler that the function will either return an | | |
| 453 | error or a value. An error union type combines an {#link|Error Set Type#} and any other data type | | |
| 454 | (e.g. a {#link|Primitive Type|Primitive Types#} or a user-defined type such as a {#link|struct#}, {#link|enum#}, or {#link|union#}). | | |
| 455 | The full form of an error union type is | | |
| 456 | <code><error set type></code>{#syntax#}!{#endsyntax#}<code><any data type></code>. In the code | | |
| 457 | sample, the error set type is not explicitly written on the left side of the {#syntax#}!{#endsyntax#} operator. | | |
| 458 | When written this way, the error set type is an {#link|inferred error set type|Inferred Error Sets#}. The | | |
| 459 | {#syntax#}void{#endsyntax#} after the {#syntax#}!{#endsyntax#} operator | | |
| 460 | tells the compiler that the function will not return a value under normal circumstances (i.e. when no errors occur). | | |
| 461 | </p> | | |
| 462 | <aside role="note" aria-label="Note to disambiguate exclamation mark operator"> | | |
| 463 | <p> | | |
| 464 | Note to experienced programmers: Zig also has the boolean {#link|operator|Operators#} {#syntax#}!a{#endsyntax#} | | |
| 465 | where {#syntax#}a{#endsyntax#} is a value of type {#syntax#}bool{#endsyntax#}. Error union types contain the | | |
| 466 | name of the type in the syntax: {#syntax#}!{#endsyntax#}<code><any data type></code>. | | |
| 467 | </p> | | |
| 468 | </aside> | | |
| 469 | <p> | | |
| 470 | In Zig, a function's block of statements and expressions are surrounded by an open curly-brace <code>{</code> and | | |
| 471 | close curly-brace <code>}</code>. In <code class="file">hello.zig</code>, the {#syntax#}main{#endsyntax#} function | | |
| 472 | contains two statements. | | |
| 473 | </p> | | |
| 474 | <p> | | |
| 475 | In the first statement, a constant identifier, {#syntax#}stdout{#endsyntax#}, is initialized to represent standard output's | | |
| 476 | writer. In the second statement, the program tries to print the <samp>Hello, world!</samp> message to standard output. | | |
| 477 | </p> | | |
| 478 | <p> | | |
| 479 | Functions sometimes need inputs to perform their task. Inputs are passed, in between parentheses, to functions. These | | |
| 480 | inputs are also known as arguments. When multiple arguments are passed to a function, they are separated by commas. | | |
| 481 | </p> | | |
| 482 | <p> | | |
| 483 | Two arguments are passed to the {#syntax#}stdout.print(){#endsyntax#} function: {#syntax#}"Hello, {s}!\n"{#endsyntax#} | | |
| 484 | and {#syntax#}.{"world"}{#endsyntax#}. The first argument is called a format string, which is a string containing one or | | |
| 485 | more placeholders. {#syntax#}"Hello, {s}!\n"{#endsyntax#} contains the placeholder {#syntax#}{s}{#endsyntax#}, which is | | |
| 486 | replaced with {#syntax#}"world"{#endsyntax#} from the second argument. The file <code class="file">string_literals.zig</code> in | | |
| 487 | {#link|String Literals and Unicode Code Point Literals|String Literals and Unicode Code Point Literals#} contains examples of format | | |
| 488 | strings that can be used with the {#syntax#}stdout.print(){#endsyntax#} function. The <code>\n</code> inside of | | |
| 489 | {#syntax#}"Hello, {s}!\n"{#endsyntax#} is the {#link|escape sequence|Escape Sequences#} for the newline character. | | |
| 490 | </p> | | |
| 491 | <p> | | |
| 492 | The {#link|try#} expression evaluates the result of {#syntax#}stdout.print{#endsyntax#}. If the result is an error, then the | | |
| 493 | {#syntax#}try{#endsyntax#} expression will return from {#syntax#}main{#endsyntax#} with the error. Otherwise, the program will continue. | | |
| 494 | In this case, there are no more statements or expressions left to execute in the {#syntax#}main{#endsyntax#} function, so the program exits. | | |
| 495 | </p> | | |
| 496 | <p> | | |
| 497 | In Zig, the standard output writer's {#syntax#}print{#endsyntax#} function is allowed to fail because | | |
| 498 | it is actually a function defined as part of a generic Writer. Consider a generic Writer that | | |
| 499 | represents writing data to a file. When the disk is full, a write to the file will fail. | | |
| 500 | However, we typically do not expect writing text to the standard output to fail. To avoid having | | |
| 501 | to handle the failure case of printing to standard output, you can use alternate functions: the | | |
| 502 | functions in {#syntax#}std.log{#endsyntax#} for proper logging or the {#syntax#}std.debug.print{#endsyntax#} function. | | |
| 503 | This documentation will use the latter option to print to standard error (stderr) and silently return | | |
| 504 | on failure. The next code sample, <code class="file">hello_again.zig</code> demonstrates the use of | | |
| 505 | {#syntax#}std.debug.print{#endsyntax#}. | | |
| 506 | </p> | 416 | </p> |
| 507 | {#code_begin|exe|hello_again#} | 417 | {#code_begin|exe|hello_again#} |
| 508 | const print = @import("std").debug.print; | 418 | const std = @import("std"); |
| 509 | | 419 | |
| 510 | pub fn main() void { | 420 | pub fn main() void { |
| 511 | print("Hello, world!\n", .{}); | 421 | std.debug.print("Hello, world!\n", .{}); |
| 512 | } | 422 | } |
| 513 | {#code_end#} | 423 | {#code_end#} |
| 514 | <p> | 424 | <p> |
| 515 | Note that you can leave off the {#syntax#}!{#endsyntax#} from the return type because {#syntax#}std.debug.print{#endsyntax#} cannot fail. | 425 | In this case, the {#syntax#}!{#endsyntax#} may be omitted from the return |
| | 426 | type because no errors are returned from the function. |
| 516 | </p> | 427 | </p> |
| 517 | {#see_also|Values|@import|Errors|Root Source File|Source Encoding#} | 428 | {#see_also|Values|@import|Errors|Root Source File|Source Encoding#} |
| 518 | {#header_close#} | 429 | {#header_close#} |
Andrew Kelley <andrew@ziglang.org> 2024-01-21 16:47:18-07:00