diff --git a/doc/langref.html.in b/doc/langref.html.in index d5bbb20f7a..9cd1844e51 100644 --- a/doc/langref.html.in +++ b/doc/langref.html.in @@ -8,7 +8,7 @@ @@ -410,109 +370,20 @@ pub fn main() !void { } {#code_end#}

- 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:

{#code_begin|exe|hello_again#} -const print = @import("std").debug.print; +const std = @import("std"); pub fn main() void { - print("Hello, world!\n", .{}); + std.debug.print("Hello, world!\n", .{}); } {#code_end#}

- 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#} @@ -896,42 +767,22 @@ pub fn main() void { The type of string literals encodes both the length, and the fact that they are null-terminated, and thus they can be {#link|coerced|Type Coercion#} to both {#link|Slices#} and {#link|Null-Terminated Pointers|Sentinel-Terminated Pointers#}. + Dereferencing string literals converts them to {#link|Arrays#}.

- Dereferencing string literals converts them to {#link|Arrays#}, allowing you to initialize a buffer with the contents of a string literal. -

- {#code_begin|syntax|mutable_string_buffer#} -test { - var buffer = [_]u8{0}**256; - const home_dir = "C:/Users/root"; - buffer[0..home_dir.len].* = home_dir.*; -} - {#code_end#} -

- The encoding of a string in Zig is de-facto assumed to be UTF-8. - Because Zig source code is {#link|UTF-8 encoded|Source Encoding#}, any non-ASCII bytes appearing within a string literal - in source code carry their UTF-8 meaning into the content of the string in the Zig program; - the bytes are not modified by the compiler. - However, it is possible to embed non-UTF-8 bytes into a string literal using \xNN notation. -

-

- Indexing into a string containing non-ASCII bytes will return individual bytes, whether valid - UTF-8 or not. - The {#link|Zig Standard Library#} provides routines for checking the validity of UTF-8 encoded - strings, accessing their code points and other encoding/decoding related tasks in - {#syntax#}std.unicode{#endsyntax#}. + Because Zig source code is {#link|UTF-8 encoded|Source Encoding#}, any + non-ASCII bytes appearing within a string literal in source code carry + their UTF-8 meaning into the content of the string in the Zig program; + the bytes are not modified by the compiler. It is possible to embed + non-UTF-8 bytes into a string literal using \xNN notation.

+

Indexing into a string containing non-ASCII bytes returns individual + bytes, whether valid UTF-8 or not.

Unicode code point literals have type {#syntax#}comptime_int{#endsyntax#}, the same as {#link|Integer Literals#}. All {#link|Escape Sequences#} are valid in both string literals and Unicode code point literals.

-

- In many other programming languages, a Unicode code point literal is called a "character literal". - However, there is no precise technical definition of a "character" - in recent versions of the Unicode specification (as of Unicode 13.0). - In Zig, a Unicode code point literal corresponds to the Unicode definition of a code point. -

{#code_begin|exe|string_literals#} const print = @import("std").debug.print; const mem = @import("std").mem; // will be used to compare bytes @@ -1632,26 +1483,27 @@ pub fn main() void { {#header_open|Table of Operators#}
- + - - + + - + + - - + + - - + + - - + + - - + + - - + + - - + + - + + - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - + - + + - + + - + + - + + - + + - + + - + - + + - + + - + + - + + - + + - + + - + + - + + - + + - + + - + + - + + - + +
Table of Operators
Name SyntaxRelevant TypesDescriptionTypesRemarks Example 
{#syntax#}a + b
-a += b{#endsyntax#}
Addition
{#syntax#}a + b
+a += b{#endsyntax#}
  • {#link|Integers#}
  • {#link|Floats#}
Addition. +
  • Can cause {#link|overflow|Default Operations#} for integers.
  • Invokes {#link|Peer Type Resolution#} for the operands.
    • @@ -1663,51 +1515,54 @@ a += b{#endsyntax#} 
{#syntax#}a +% b
-a +%= b{#endsyntax#}
Wrapping Addition
{#syntax#}a +% b
+a +%= b{#endsyntax#}
  • {#link|Integers#}
Wrapping Addition. +
    -
  • Guaranteed to have twos-complement wrapping behavior.
    • +
  • Twos-complement wrapping behavior.
  • Invokes {#link|Peer Type Resolution#} for the operands.
  • See also {#link|@addWithOverflow#}.
 - 
{#syntax#}@as(u32, std.math.maxInt(u32)) +% 1 == 0{#endsyntax#}
+ 
{#syntax#}@as(u32, 0xffffffff) +% 1 == 0{#endsyntax#}
 
{#syntax#}a +| b
-a +|= b{#endsyntax#}
Saturating Addition
{#syntax#}a +| b
+a +|= b{#endsyntax#}
  • {#link|Integers#}
Saturating Addition. +
  • Invokes {#link|Peer Type Resolution#} for the operands.
 - 
{#syntax#}@as(u32, std.math.maxInt(u32)) +| 1 == @as(u32, std.math.maxInt(u32)){#endsyntax#}
+ 
{#syntax#}@as(u8, 255) +| 1 == @as(u8, 255){#endsyntax#}
 
{#syntax#}a - b
-a -= b{#endsyntax#}
Subtraction
{#syntax#}a - b
+a -= b{#endsyntax#}
  • {#link|Integers#}
  • {#link|Floats#}
Subtraction. +
  • Can cause {#link|overflow|Default Operations#} for integers.
  • Invokes {#link|Peer Type Resolution#} for the operands.
    • @@ -1719,33 +1574,35 @@ a -= b{#endsyntax#} 
{#syntax#}a -% b
-a -%= b{#endsyntax#}
Wrapping Subtraction
{#syntax#}a -% b
+a -%= b{#endsyntax#}
  • {#link|Integers#}
Wrapping Subtraction. +
    -
  • Guaranteed to have twos-complement wrapping behavior.
    • +
  • Twos-complement wrapping behavior.
  • Invokes {#link|Peer Type Resolution#} for the operands.
  • See also {#link|@subWithOverflow#}.
 - 
{#syntax#}@as(u32, 0) -% 1 == std.math.maxInt(u32){#endsyntax#}
+ 
{#syntax#}@as(u8, 0) -% 1 == 255{#endsyntax#}
 
{#syntax#}a -| b
-a -|= b{#endsyntax#}
Saturating Subtraction
{#syntax#}a -| b
+a -|= b{#endsyntax#}
  • {#link|Integers#}
Saturating Subtraction. +
  • Invokes {#link|Peer Type Resolution#} for the operands.
@@ -1755,7 +1612,8 @@ a -|= b{#endsyntax#} 
{#syntax#}-a{#endsyntax#}
Negation
{#syntax#}-a{#endsyntax#}
  • {#link|Integers#}
    • @@ -1763,7 +1621,6 @@ a -|= b{#endsyntax#}
- Negation.
  • Can cause {#link|overflow|Default Operations#} for integers.
@@ -1773,32 +1630,33 @@ a -|= b{#endsyntax#} 
{#syntax#}-%a{#endsyntax#}
Wrapping Negation
{#syntax#}-%a{#endsyntax#}
  • {#link|Integers#}
 - Wrapping Negation.
    -
  • Guaranteed to have twos-complement wrapping behavior.
    • +
  • Twos-complement wrapping behavior.
 - 
{#syntax#}-%@as(i32, std.math.minInt(i32)) == std.math.minInt(i32){#endsyntax#}
+ 
{#syntax#}-%@as(i8, -127) == -127{#endsyntax#}
 
{#syntax#}a * b
-a *= b{#endsyntax#}
Multiplication
{#syntax#}a * b
+a *= b{#endsyntax#}
  • {#link|Integers#}
  • {#link|Floats#}
Multiplication. +
  • Can cause {#link|overflow|Default Operations#} for integers.
  • Invokes {#link|Peer Type Resolution#} for the operands.
    • @@ -1810,16 +1668,17 @@ a *= b{#endsyntax#} 
{#syntax#}a *% b
-a *%= b{#endsyntax#}
Wrapping Multiplication
{#syntax#}a *% b
+a *%= b{#endsyntax#}
  • {#link|Integers#}
Wrapping Multiplication. +
    -
  • Guaranteed to have twos-complement wrapping behavior.
    • +
  • Twos-complement wrapping behavior.
  • Invokes {#link|Peer Type Resolution#} for the operands.
  • See also {#link|@mulWithOverflow#}.
@@ -1829,14 +1688,15 @@ a *%= b{#endsyntax#} 
{#syntax#}a *| b
-a *|= b{#endsyntax#}
Saturating Multiplication
{#syntax#}a *| b
+a *|= b{#endsyntax#}
  • {#link|Integers#}
Saturating Multiplication. +
  • Invokes {#link|Peer Type Resolution#} for the operands.
@@ -1846,15 +1706,16 @@ a *|= b{#endsyntax#} 
{#syntax#}a / b
-a /= b{#endsyntax#}
Division
{#syntax#}a / b
+a /= b{#endsyntax#}
  • {#link|Integers#}
  • {#link|Floats#}
Division. +
  • Can cause {#link|overflow|Default Operations#} for integers.
  • Can cause {#link|Division by Zero#} for integers.
    • @@ -1872,15 +1733,16 @@ a /= b{#endsyntax#} 
{#syntax#}a % b
-a %= b{#endsyntax#}
Remainder Division
{#syntax#}a % b
+a %= b{#endsyntax#}
  • {#link|Integers#}
  • {#link|Floats#}
Remainder Division. +
  • Can cause {#link|Division by Zero#} for integers.
  • Can cause {#link|Division by Zero#} for floats in {#link|FloatMode.Optimized Mode|Floating Point Operations#}.
    • @@ -1896,33 +1758,39 @@ a %= b{#endsyntax#} 
{#syntax#}a << b
-a <<= b{#endsyntax#}
Bit Shift Left
{#syntax#}a << b
+a <<= b{#endsyntax#}
  • {#link|Integers#}
Bit Shift Left. +
    -
  • {#syntax#}b{#endsyntax#} must be {#link|comptime-known|comptime#} or have a type with log2 number of bits as {#syntax#}a{#endsyntax#}.
    • +
  • Moves all bits to the left, inserting new zeroes at the + least-significant bit.
    • +
  • {#syntax#}b{#endsyntax#} must be + {#link|comptime-known|comptime#} or have a type with log2 number + of bits as {#syntax#}a{#endsyntax#}.
  • See also {#link|@shlExact#}.
  • See also {#link|@shlWithOverflow#}.
 - 
{#syntax#}1 << 8 == 256{#endsyntax#}
+ 
{#syntax#}0b1 << 8 == 0b100000000{#endsyntax#}
 
{#syntax#}a <<| b
-a <<|= b{#endsyntax#}
Saturating Bit Shift Left
{#syntax#}a <<| b
+a <<|= b{#endsyntax#}
  • {#link|Integers#}
Saturating Bit Shift Left. +
  • See also {#link|@shlExact#}.
  • See also {#link|@shlWithOverflow#}.
    • @@ -1933,32 +1801,37 @@ a <<|= b{#endsyntax#} 
{#syntax#}a >> b
-a >>= b{#endsyntax#}
Bit Shift Right
{#syntax#}a >> b
+a >>= b{#endsyntax#}
  • {#link|Integers#}
Bit Shift Right. +
    -
  • {#syntax#}b{#endsyntax#} must be {#link|comptime-known|comptime#} or have a type with log2 number of bits as {#syntax#}a{#endsyntax#}.
    • +
  • Moves all bits to the right, inserting zeroes at the most-significant bit.
    • +
  • {#syntax#}b{#endsyntax#} must be + {#link|comptime-known|comptime#} or have a type with log2 number + of bits as {#syntax#}a{#endsyntax#}.
  • See also {#link|@shrExact#}.
 - 
{#syntax#}10 >> 1 == 5{#endsyntax#}
+ 
{#syntax#}0b1010 >> 1 == 0b101{#endsyntax#}
 
{#syntax#}a & b
-a &= b{#endsyntax#}
Bitwise And
{#syntax#}a & b
+a &= b{#endsyntax#}
  • {#link|Integers#}
Bitwise AND. +
  • Invokes {#link|Peer Type Resolution#} for the operands.
@@ -1968,14 +1841,15 @@ a &= b{#endsyntax#} 
{#syntax#}a | b
-a |= b{#endsyntax#}
Bitwise Or
{#syntax#}a | b
+a |= b{#endsyntax#}
  • {#link|Integers#}
Bitwise OR. +
  • Invokes {#link|Peer Type Resolution#} for the operands.
@@ -1985,14 +1859,15 @@ a |= b{#endsyntax#} 
{#syntax#}a ^ b
-a ^= b{#endsyntax#}
Bitwise Xor
{#syntax#}a ^ b
+a ^= b{#endsyntax#}
  • {#link|Integers#}
Bitwise XOR. +
  • Invokes {#link|Peer Type Resolution#} for the operands.
@@ -2002,30 +1877,30 @@ a ^= b{#endsyntax#} 
{#syntax#}~a{#endsyntax#}
Bitwise Not
{#syntax#}~a{#endsyntax#}
  • {#link|Integers#}
 - Bitwise NOT. - 
{#syntax#}~@as(u8, 0b10101111) == 0b01010000{#endsyntax#}
 
{#syntax#}a orelse b{#endsyntax#}
Defaulting Optional Unwrap
{#syntax#}a orelse b{#endsyntax#}
  • {#link|Optionals#}
 If {#syntax#}a{#endsyntax#} is {#syntax#}null{#endsyntax#}, - returns {#syntax#}b{#endsyntax#} ("default value"), - otherwise returns the unwrapped value of {#syntax#}a{#endsyntax#}. - Note that {#syntax#}b{#endsyntax#} may be a value of type {#link|noreturn#}. + returns {#syntax#}b{#endsyntax#} ("default value"), + otherwise returns the unwrapped value of {#syntax#}a{#endsyntax#}. + Note that {#syntax#}b{#endsyntax#} may be a value of type {#link|noreturn#}. 
{#syntax#}const value: ?u32 = null;
@@ -2034,7 +1909,8 @@ unwrapped == 1234{#endsyntax#}
 
{#syntax#}a.?{#endsyntax#}
Optional Unwrap
{#syntax#}a.?{#endsyntax#}
  • {#link|Optionals#}
    • @@ -2050,18 +1926,19 @@ value.? == 5678{#endsyntax#} 
{#syntax#}a catch b
-a catch |err| b{#endsyntax#}
Defaulting Error Unwrap
{#syntax#}a catch b
+a catch |err| b{#endsyntax#}
  • {#link|Error Unions|Errors#}
 If {#syntax#}a{#endsyntax#} is an {#syntax#}error{#endsyntax#}, - returns {#syntax#}b{#endsyntax#} ("default value"), - otherwise returns the unwrapped value of {#syntax#}a{#endsyntax#}. - Note that {#syntax#}b{#endsyntax#} may be a value of type {#link|noreturn#}. - {#syntax#}err{#endsyntax#} is the {#syntax#}error{#endsyntax#} and is in scope of the expression {#syntax#}b{#endsyntax#}. + returns {#syntax#}b{#endsyntax#} ("default value"), + otherwise returns the unwrapped value of {#syntax#}a{#endsyntax#}. + Note that {#syntax#}b{#endsyntax#} may be a value of type {#link|noreturn#}. +{#syntax#}err{#endsyntax#} is the {#syntax#}error{#endsyntax#} and is in scope of the expression {#syntax#}b{#endsyntax#}. 
{#syntax#}const value: anyerror!u32 = error.Broken;
@@ -2070,51 +1947,55 @@ unwrapped == 1234{#endsyntax#}
 
{#syntax#}a and b{#endsyntax#}
Logical And
{#syntax#}a and b{#endsyntax#}
  • {#link|bool|Primitive Types#}
 - If {#syntax#}a{#endsyntax#} is {#syntax#}false{#endsyntax#}, returns {#syntax#}false{#endsyntax#} - without evaluating {#syntax#}b{#endsyntax#}. Otherwise, returns {#syntax#}b{#endsyntax#}. + If {#syntax#}a{#endsyntax#} is {#syntax#}false{#endsyntax#}, returns {#syntax#}false{#endsyntax#} + without evaluating {#syntax#}b{#endsyntax#}. Otherwise, returns {#syntax#}b{#endsyntax#}. 
{#syntax#}(false and true) == false{#endsyntax#}
 
{#syntax#}a or b{#endsyntax#}
Logical Or
{#syntax#}a or b{#endsyntax#}
  • {#link|bool|Primitive Types#}
 - If {#syntax#}a{#endsyntax#} is {#syntax#}true{#endsyntax#}, returns {#syntax#}true{#endsyntax#} - without evaluating {#syntax#}b{#endsyntax#}. Otherwise, returns {#syntax#}b{#endsyntax#}. + If {#syntax#}a{#endsyntax#} is {#syntax#}true{#endsyntax#}, + returns {#syntax#}true{#endsyntax#} without evaluating + {#syntax#}b{#endsyntax#}. Otherwise, returns + {#syntax#}b{#endsyntax#}. 
{#syntax#}(false or true) == true{#endsyntax#}
 
{#syntax#}!a{#endsyntax#}
Boolean Not
{#syntax#}!a{#endsyntax#}
  • {#link|bool|Primitive Types#}
 - Boolean NOT. - 
{#syntax#}!false == true{#endsyntax#}
 
{#syntax#}a == b{#endsyntax#}
Equality
{#syntax#}a == b{#endsyntax#}
  • {#link|Integers#}
    • @@ -2132,7 +2013,8 @@ unwrapped == 1234{#endsyntax#} 
{#syntax#}a == null{#endsyntax#}
Null Check
{#syntax#}a == null{#endsyntax#}
  • {#link|Optionals#}
    • @@ -2147,7 +2029,8 @@ unwrapped == 1234{#endsyntax#} 
{#syntax#}a != b{#endsyntax#}
Inequality
{#syntax#}a != b{#endsyntax#}
  • {#link|Integers#}
    • @@ -2165,7 +2048,8 @@ unwrapped == 1234{#endsyntax#} 
{#syntax#}a != null{#endsyntax#}
Non-Null Check
{#syntax#}a != null{#endsyntax#}
  • {#link|Optionals#}
    • @@ -2180,7 +2064,8 @@ unwrapped == 1234{#endsyntax#} 
{#syntax#}a > b{#endsyntax#}
Greater Than
{#syntax#}a > b{#endsyntax#}
  • {#link|Integers#}
    • @@ -2196,7 +2081,8 @@ unwrapped == 1234{#endsyntax#} 
{#syntax#}a >= b{#endsyntax#}
Greater or Equal
{#syntax#}a >= b{#endsyntax#}
  • {#link|Integers#}
    • @@ -2212,7 +2098,8 @@ unwrapped == 1234{#endsyntax#} 
{#syntax#}a < b{#endsyntax#}
Less Than
{#syntax#}a < b{#endsyntax#}
  • {#link|Integers#}
    • @@ -2228,7 +2115,8 @@ unwrapped == 1234{#endsyntax#} 
{#syntax#}a <= b{#endsyntax#}
Lesser or Equal
{#syntax#}a <= b{#endsyntax#}
  • {#link|Integers#}
    • @@ -2244,14 +2132,14 @@ unwrapped == 1234{#endsyntax#} 
{#syntax#}a ++ b{#endsyntax#}
Array Concatenation
{#syntax#}a ++ b{#endsyntax#}
  • {#link|Arrays#}
 - Array concatenation.
  • Only available when the lengths of both {#syntax#}a{#endsyntax#} and {#syntax#}b{#endsyntax#} are {#link|compile-time known|comptime#}.
@@ -2265,14 +2153,14 @@ mem.eql(u32, &together, &[_]u32{1,2,3,4}){#endsyntax#} 
{#syntax#}a ** b{#endsyntax#}
Array Multiplication
{#syntax#}a ** b{#endsyntax#}
  • {#link|Arrays#}
 - Array multiplication.
  • Only available when the length of {#syntax#}a{#endsyntax#} and {#syntax#}b{#endsyntax#} are {#link|compile-time known|comptime#}.
@@ -2284,7 +2172,8 @@ mem.eql(u8, pattern, "ababab"){#endsyntax#} 
{#syntax#}a.*{#endsyntax#}
Pointer Dereference
{#syntax#}a.*{#endsyntax#}
  • {#link|Pointers#}
    • @@ -2300,12 +2189,12 @@ ptr.* == 1234{#endsyntax#} 
{#syntax#}&a{#endsyntax#}
Address Of
{#syntax#}&a{#endsyntax#}
 All types - Address of. 
{#syntax#}const x: u32 = 1234;
@@ -2314,7 +2203,8 @@ ptr.* == 1234{#endsyntax#}
 
{#syntax#}a || b{#endsyntax#}
Error Set Merge
{#syntax#}a || b{#endsyntax#}
  • {#link|Error Set Type#}
    • @@ -4311,10 +4201,11 @@ test "enum literals with switch" { {#code_end#} {#header_close#} - {#header_open|Inline switch#} + {#header_open|Inline Switch Prongs#}

    Switch prongs can be marked as {#syntax#}inline{#endsyntax#} to generate - the prong's body for each possible value it could have: + the prong's body for each possible value it could have, making the + captured value {#link|comptime#}.

    {#code_begin|test|test_inline_switch#} const std = @import("std"); @@ -4324,9 +4215,9 @@ const expectError = std.testing.expectError; fn isFieldOptional(comptime T: type, field_index: usize) !bool { const fields = @typeInfo(T).Struct.fields; return switch (field_index) { - // This prong is analyzed `fields.len - 1` times with `idx` being a - // unique comptime-known value each time. - inline 0...fields.len - 1 => |idx| @typeInfo(fields[idx].type) == .Optional, + // This prong is analyzed twice with `idx` being a + // comptime-known value each time. + inline 0, 1 => |idx| @typeInfo(fields[idx].type) == .Optional, else => return error.IndexOutOfBounds, }; } @@ -4350,6 +4241,16 @@ fn isFieldOptionalUnrolled(field_index: usize) !bool { 1 => true, else => return error.IndexOutOfBounds, }; +} + {#code_end#} +

    The {#syntax#}inline{#endsyntax#} keyword may also be combined with ranges:

    + {#code_begin|syntax|inline_prong_range#} +fn isFieldOptional(comptime T: type, field_index: usize) !bool { + const fields = @typeInfo(T).Struct.fields; + return switch (field_index) { + inline 0...fields.len - 1 => |idx| @typeInfo(fields[idx].type) == .Optional, + else => return error.IndexOutOfBounds, + }; } {#code_end#}

    @@ -7853,7 +7754,7 @@ comptime { {#header_close#} {#header_open|@atomicLoad#} - 

    {#syntax#}@atomicLoad(comptime T: type, ptr: *const T, comptime ordering: builtin.AtomicOrder) T{#endsyntax#}
    + 
    {#syntax#}@atomicLoad(comptime T: type, ptr: *const T, comptime ordering: AtomicOrder) T{#endsyntax#}

    This builtin function atomically dereferences a pointer to a {#syntax#}T{#endsyntax#} and returns the value.

    @@ -7861,11 +7762,12 @@ comptime { {#syntax#}T{#endsyntax#} must be a pointer, a {#syntax#}bool{#endsyntax#}, a float, an integer or an enum.

    +

    {#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.

    {#see_also|@atomicStore|@atomicRmw|@fence|@cmpxchgWeak|@cmpxchgStrong#} {#header_close#} {#header_open|@atomicRmw#} - 
    {#syntax#}@atomicRmw(comptime T: type, ptr: *T, comptime op: builtin.AtomicRmwOp, operand: T, comptime ordering: builtin.AtomicOrder) T{#endsyntax#}
    + 
    {#syntax#}@atomicRmw(comptime T: type, ptr: *T, comptime op: AtomicRmwOp, operand: T, comptime ordering: AtomicOrder) T{#endsyntax#}

    This builtin function dereferences a pointer to a {#syntax#}T{#endsyntax#} and atomically modifies the value and returns the previous value. @@ -7874,27 +7776,13 @@ comptime { {#syntax#}T{#endsyntax#} must be a pointer, a {#syntax#}bool{#endsyntax#}, a float, an integer or an enum.

    -

    - Supported values for the {#syntax#}op{#endsyntax#} parameter: -

    -
      -
    • {#syntax#}.Xchg{#endsyntax#} - stores the operand unmodified. Supports enums, integers and floats.
      • -
    • {#syntax#}.Add{#endsyntax#} - for integers, twos complement wraparound addition. - Also supports {#link|Floats#}.
      • -
    • {#syntax#}.Sub{#endsyntax#} - for integers, twos complement wraparound subtraction. - Also supports {#link|Floats#}.
      • -
    • {#syntax#}.And{#endsyntax#} - bitwise and
      • -
    • {#syntax#}.Nand{#endsyntax#} - bitwise nand
      • -
    • {#syntax#}.Or{#endsyntax#} - bitwise or
      • -
    • {#syntax#}.Xor{#endsyntax#} - bitwise xor
      • -
    • {#syntax#}.Max{#endsyntax#} - stores the operand if it is larger. Supports integers and floats.
      • -
    • {#syntax#}.Min{#endsyntax#} - stores the operand if it is smaller. Supports integers and floats.
      • -
    +

    {#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.

    +

    {#syntax#}AtomicRmwOp{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicRmwOp{#endsyntax#}.

    {#see_also|@atomicStore|@atomicLoad|@fence|@cmpxchgWeak|@cmpxchgStrong#} {#header_close#} {#header_open|@atomicStore#} - 
    {#syntax#}@atomicStore(comptime T: type, ptr: *T, value: T, comptime ordering: builtin.AtomicOrder) void{#endsyntax#}
    + 
    {#syntax#}@atomicStore(comptime T: type, ptr: *T, value: T, comptime ordering: AtomicOrder) void{#endsyntax#}

    This builtin function dereferences a pointer to a {#syntax#}T{#endsyntax#} and atomically stores the given value.

    @@ -7902,6 +7790,7 @@ comptime { {#syntax#}T{#endsyntax#} must be a pointer, a {#syntax#}bool{#endsyntax#}, a float, an integer or an enum.

    +

    {#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.

    {#see_also|@atomicLoad|@atomicRmw|@fence|@cmpxchgWeak|@cmpxchgStrong#} {#header_close#} @@ -8178,6 +8067,7 @@ fn cmpxchgStrongButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_v an integer or an enum.

    {#syntax#}@typeInfo(@TypeOf(ptr)).Pointer.alignment{#endsyntax#} must be {#syntax#}>= @sizeOf(T).{#endsyntax#}

    +

    {#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.

    {#see_also|@atomicStore|@atomicLoad|@atomicRmw|@fence|@cmpxchgWeak#} {#header_close#} @@ -8209,6 +8099,7 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val an integer or an enum.

    {#syntax#}@typeInfo(@TypeOf(ptr)).Pointer.alignment{#endsyntax#} must be {#syntax#}>= @sizeOf(T).{#endsyntax#}

    +

    {#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.

    {#see_also|@atomicStore|@atomicLoad|@atomicRmw|@fence|@cmpxchgStrong#} {#header_close#} @@ -8499,9 +8390,7 @@ export fn @"A function name that is a complete sentence."() void {}

    The {#syntax#}fence{#endsyntax#} function is used to introduce happens-before edges between operations.

    -

    - {#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}. -

    +

    {#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.

    {#see_also|@atomicStore|@atomicLoad|@atomicRmw|@cmpxchgWeak|@cmpxchgStrong#} {#header_close#} @@ -8909,7 +8798,7 @@ test "@wasmMemoryGrow" { {#header_close#} {#header_open|@prefetch#} - 
    {#syntax#}@prefetch(ptr: anytype, comptime options: std.builtin.PrefetchOptions) void{#endsyntax#}
    + 
    {#syntax#}@prefetch(ptr: anytype, comptime options: PrefetchOptions) void{#endsyntax#}

    This builtin tells the compiler to emit a prefetch instruction if supported by the target CPU. If the target CPU does not support the requested prefetch instruction, @@ -8921,37 +8810,7 @@ test "@wasmMemoryGrow" { address to prefetch. This function does not dereference the pointer, it is perfectly legal to pass a pointer to invalid memory to this function and no illegal behavior will result.

    -

    - The {#syntax#}options{#endsyntax#} argument is the following struct: -

    - {#code_begin|syntax|builtin#} -/// This data structure is used by the Zig language code generation and -/// therefore must be kept in sync with the compiler implementation. -pub const PrefetchOptions = struct { - /// Whether the prefetch should prepare for a read or a write. - rw: Rw = .read, - /// The data's locality in an inclusive range from 0 to 3. - /// - /// 0 means no temporal locality. That is, the data can be immediately - /// dropped from the cache after it is accessed. - /// - /// 3 means high temporal locality. That is, the data should be kept in - /// the cache as it is likely to be accessed again soon. - locality: u2 = 3, - /// The cache that the prefetch should be preformed on. - cache: Cache = .data, - - pub const Rw = enum(u1) { - read, - write, - }; - - pub const Cache = enum(u1) { - instruction, - data, - }; -}; - {#code_end#} +

    {#syntax#}PrefetchOptions{#endsyntax#} can be found with {#syntax#}@import("std").builtin.PrefetchOptions{#endsyntax#}.

    {#header_close#} {#header_open|@ptrCast#} @@ -9080,16 +8939,8 @@ test "foo" { {#header_close#} {#header_open|@setFloatMode#} - 
    {#syntax#}@setFloatMode(comptime mode: @import("std").builtin.FloatMode) void{#endsyntax#}
    -

    - Sets the floating point mode of the current scope. Possible values are: -

    - {#code_begin|syntax|FloatMode#} -pub const FloatMode = enum { - Strict, - Optimized, -}; - {#code_end#} + 
    {#syntax#}@setFloatMode(comptime mode: FloatMode) void{#endsyntax#}
    +

    Changes the current scope's rules about how floating point operations are defined.

    • {#syntax#}Strict{#endsyntax#} (default) - Floating point operations follow strict IEEE compliance. @@ -9111,6 +8962,7 @@ pub const FloatMode = enum { The floating point mode is inherited by child scopes, and can be overridden in any scope. You can set the floating point mode in a struct or module scope by using a comptime block.

      +

      {#syntax#}FloatMode{#endsyntax#} can be found with {#syntax#}@import("std").builtin.FloatMode{#endsyntax#}.

      {#see_also|Floating Point Operations#} {#header_close#} @@ -11522,7 +11374,6 @@ fn readU32Be() u32 {} {#header_open|Keyword Reference#}
      - diff --git a/lib/std/builtin.zig b/lib/std/builtin.zig index 24c6036d60..56ee990c5f 100644 --- a/lib/std/builtin.zig +++ b/lib/std/builtin.zig @@ -102,14 +102,34 @@ pub const ReduceOp = enum { /// This data structure is used by the Zig language code generation and /// therefore must be kept in sync with the compiler implementation. pub const AtomicRmwOp = enum { + /// Exchange - store the operand unmodified. + /// Supports enums, integers, and floats. Xchg, + /// Add operand to existing value. + /// Supports integers and floats. + /// For integers, two's complement wraparound applies. Add, + /// Subtract operand from existing value. + /// Supports integers and floats. + /// For integers, two's complement wraparound applies. Sub, + /// Perform bitwise AND on existing value with operand. + /// Supports integers. And, + /// Perform bitwise NAND on existing value with operand. + /// Supports integers. Nand, + /// Perform bitwise OR on existing value with operand. + /// Supports integers. Or, + /// Perform bitwise XOR on existing value with operand. + /// Supports integers. Xor, + /// Store operand if it is larger than the existing value. + /// Supports integers and floats. Max, + /// Store operand if it is smaller than the existing value. + /// Supports integers and floats. Min, }; diff --git a/lib/std/fmt.zig b/lib/std/fmt.zig index 6bb7e26da8..a9e1d73c0a 100644 --- a/lib/std/fmt.zig +++ b/lib/std/fmt.zig @@ -40,9 +40,9 @@ pub const FormatOptions = struct { /// - when using a field name, you are required to enclose the field name (an identifier) in square /// brackets, e.g. {[score]...} as opposed to the numeric index form which can be written e.g. {2...} /// - *specifier* is a type-dependent formatting option that determines how a type should formatted (see below) -/// - *fill* is a single character which is used to pad the formatted text -/// - *alignment* is one of the three characters `<`, `^`, or `>` to make the text left-, center-, or right-aligned, respectively -/// - *width* is the total width of the field in characters +/// - *fill* is a single unicode codepoint which is used to pad the formatted text +/// - *alignment* is one of the three bytes '<', '^', or '>' to make the text left-, center-, or right-aligned, respectively +/// - *width* is the total width of the field in unicode codepoints /// - *precision* specifies how many decimals a formatted number should have /// /// Note that most of the parameters are optional and may be omitted. Also you can leave out separators like `:` and `.` when diff --git a/tools/docgen.zig b/tools/docgen.zig index bb4300426a..559b1937e9 100644 --- a/tools/docgen.zig +++ b/tools/docgen.zig @@ -947,19 +947,8 @@ fn isType(name: []const u8) bool { return false; } -const start_line = ""; -const end_line = ""; - fn writeEscapedLines(out: anytype, text: []const u8) !void { - for (text) |char| { - if (char == '\n') { - try out.writeAll(end_line); - try out.writeAll("\n"); - try out.writeAll(start_line); - } else { - try writeEscaped(out, &[_]u8{char}); - } - } + return writeEscaped(out, text); } fn tokenizeAndPrintRaw( @@ -972,7 +961,7 @@ fn tokenizeAndPrintRaw( const src_non_terminated = mem.trim(u8, raw_src, " \r\n"); const src = try allocator.dupeZ(u8, src_non_terminated); - try out.writeAll("" ++ start_line); + try out.writeAll(""); var tokenizer = std.zig.Tokenizer.init(src); var index: usize = 0; var next_tok_is_fn = false; @@ -1062,6 +1051,7 @@ fn tokenizeAndPrintRaw( }, .string_literal, + .multiline_string_literal_line, .char_literal, => { try out.writeAll(""); @@ -1069,18 +1059,6 @@ fn tokenizeAndPrintRaw( try out.writeAll(""); }, - .multiline_string_literal_line => { - if (src[token.loc.end - 1] == '\n') { - try out.writeAll(""); - try writeEscaped(out, src[token.loc.start .. token.loc.end - 1]); - try out.writeAll("" ++ end_line ++ "\n" ++ start_line); - } else { - try out.writeAll(""); - try writeEscaped(out, src[token.loc.start..token.loc.end]); - try out.writeAll(""); - } - }, - .builtin => { try out.writeAll(""); try writeEscaped(out, src[token.loc.start..token.loc.end]); @@ -1211,7 +1189,7 @@ fn tokenizeAndPrintRaw( } index = token.loc.end; } - try out.writeAll(end_line ++ ""); + try out.writeAll(""); } fn tokenizeAndPrint( @@ -1234,9 +1212,9 @@ fn printSourceBlock(allocator: Allocator, docgen_tokenizer: *Tokenizer, out: any const raw_source = docgen_tokenizer.buffer[syntax_block.source_token.start..syntax_block.source_token.end]; const trimmed_raw_source = mem.trim(u8, raw_source, " \r\n"); - try out.writeAll("" ++ start_line); + try out.writeAll(""); try writeEscapedLines(out, trimmed_raw_source); - try out.writeAll(end_line ++ ""); + try out.writeAll(""); }, } try out.writeAll("");
      Keywords
      Keyword