- The Zig code sample above demonstrates one way to create a program that will output: Hello, world!. -
-
- The code sample shows the contents of a file named hello.zig. Files storing Zig
- source code are {#link|UTF-8 encoded|Source Encoding#} text files. The files storing
- Zig source code must be named with the .zig extension.
-
- Following the hello.zig Zig code sample, the {#link|Zig Build System#} is used
- to build an executable program from the hello.zig source code. Then, the
- hello program is executed showing its output Hello, world!. The
- lines beginning with $ represent command line prompts and a command.
- Everything else is program output.
-
- The code sample begins by adding the {#link|Zig Standard Library#} to the build using the {#link|@import#} builtin function. - The {#syntax#}@import("std"){#endsyntax#} function call creates a structure that represents the Zig Standard Library. - The code then {#link|declares|Container Level Variables#} a - {#link|constant identifier|Assignment#}, named {#syntax#}std{#endsyntax#}, that gives access to the features of the Zig Standard Library. -
-- Next, a {#link|public function|Functions#}, {#syntax#}pub fn{#endsyntax#}, named {#syntax#}main{#endsyntax#} - is declared. The {#syntax#}main{#endsyntax#} function is necessary because it tells the Zig compiler where the program starts. Programs - designed to be executed will need a {#syntax#}pub fn main{#endsyntax#} function. -
- -- 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. If a function - cannot perform its task, it might return an error. Zig makes all of this explicit. -
-
- In the hello.zig code sample, the main function is declared
- with the {#syntax#}!void{#endsyntax#} return type. This return type is known as an {#link|Error Union Type#}.
- This syntax tells the Zig compiler that the function will either return an
- error or a value. An error union type combines an {#link|Error Set Type#} and any other data type
- (e.g. a {#link|Primitive Type|Primitive Types#} or a user-defined type such as a {#link|struct#}, {#link|enum#}, or {#link|union#}).
- The full form of an error union type is
- <error set type>{#syntax#}!{#endsyntax#}<any data type>. In the code
- 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 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. when no errors occur).
-
- In Zig, a function's block of statements and expressions are surrounded by an open curly-brace { and
- close curly-brace }. In hello.zig, the {#syntax#}main{#endsyntax#} function
- contains two statements.
-
- In the first statement, a constant identifier, {#syntax#}stdout{#endsyntax#}, is initialized to represent standard output's - writer. In the second statement, the program tries to print the Hello, world! message to standard output. -
-- Functions sometimes need inputs to perform their task. Inputs are passed, in between parentheses, to functions. These - inputs are also known as arguments. When multiple arguments are passed to a function, they are separated by commas. -
-
- Two arguments are passed to the {#syntax#}stdout.print(){#endsyntax#} function: {#syntax#}"Hello, {s}!\n"{#endsyntax#}
- and {#syntax#}.{"world"}{#endsyntax#}. The first argument is called a format string, which is a string containing one or
- more placeholders. {#syntax#}"Hello, {s}!\n"{#endsyntax#} contains the placeholder {#syntax#}{s}{#endsyntax#}, which is
- replaced with {#syntax#}"world"{#endsyntax#} from the second argument. The file string_literals.zig in
- {#link|String Literals and Unicode Code Point Literals|String Literals and Unicode Code Point Literals#} contains examples of format
- strings that can be used with the {#syntax#}stdout.print(){#endsyntax#} function. The \n inside of
- {#syntax#}"Hello, {s}!\n"{#endsyntax#} is the {#link|escape sequence|Escape Sequences#} for the newline character.
-
- The {#link|try#} expression evaluates the result of {#syntax#}stdout.print{#endsyntax#}. If the result is an error, then the - {#syntax#}try{#endsyntax#} expression will return from {#syntax#}main{#endsyntax#} with the error. Otherwise, the program will continue. - In this case, there are no more statements or expressions left to execute in the {#syntax#}main{#endsyntax#} function, so the program exits. -
-
- In Zig, the standard output writer's {#syntax#}print{#endsyntax#} function is allowed to fail because
- 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, we typically do not expect writing text to the standard output to fail. To avoid having
- to handle the failure case of printing to standard output, you can use alternate functions: the
- functions in {#syntax#}std.log{#endsyntax#} for proper logging or the {#syntax#}std.debug.print{#endsyntax#} function.
- This documentation will use the latter option to print to standard error (stderr) and silently return
- on failure. The next code sample, hello_again.zig demonstrates the use of
- {#syntax#}std.debug.print{#endsyntax#}.
+ Most of the time, it more appropriate to write to stderr rather than stdout, and
+ whether or not the message is successfully written to the stream is irrelevant.
+ For this common case, there is a simpler API:
- Note that you can leave off the {#syntax#}!{#endsyntax#} from the return type because {#syntax#}std.debug.print{#endsyntax#} cannot fail. + In this case, the {#syntax#}!{#endsyntax#} may be omitted from the return + type because no errors are returned from the function.
{#see_also|Values|@import|Errors|Root Source File|Source Encoding#} {#header_close#}