authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2024-01-22 02:26:46-08:00
committergravatar for noreply@github.comGitHub <noreply@github.com> 2024-01-22 02:26:46-08:00
logb0c8a3f31631a63bca3a2feece38e57b9a1c5060
tree8428815a61dac26778872cc588713593335b4bea
parentfdb4eb3056ee85709f8d1af6c11641481de5e653
parentce7c66e2d0ccaf0265f2c2afce9824c9b9ae6123
signaturebadge-check Signed by PGP key B5690EEEBB952194

Merge pull request #18644 from ziglang/langref

4 files changed, 245 insertions(+), 396 deletions(-)

doc/langref.html.in+216-365
......@@ -8,7 +8,7 @@
88 <link rel="icon" href="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxNTMgMTQwIj48ZyBmaWxsPSIjRjdBNDFEIj48Zz48cG9seWdvbiBwb2ludHM9IjQ2LDIyIDI4LDQ0IDE5LDMwIi8+PHBvbHlnb24gcG9pbnRzPSI0NiwyMiAzMywzMyAyOCw0NCAyMiw0NCAyMiw5NSAzMSw5NSAyMCwxMDAgMTIsMTE3IDAsMTE3IDAsMjIiIHNoYXBlLXJlbmRlcmluZz0iY3Jpc3BFZGdlcyIvPjxwb2x5Z29uIHBvaW50cz0iMzEsOTUgMTIsMTE3IDQsMTA2Ii8+PC9nPjxnPjxwb2x5Z29uIHBvaW50cz0iNTYsMjIgNjIsMzYgMzcsNDQiLz48cG9seWdvbiBwb2ludHM9IjU2LDIyIDExMSwyMiAxMTEsNDQgMzcsNDQgNTYsMzIiIHNoYXBlLXJlbmRlcmluZz0iY3Jpc3BFZGdlcyIvPjxwb2x5Z29uIHBvaW50cz0iMTE2LDk1IDk3LDExNyA5MCwxMDQiLz48cG9seWdvbiBwb2ludHM9IjExNiw5NSAxMDAsMTA0IDk3LDExNyA0MiwxMTcgNDIsOTUiIHNoYXBlLXJlbmRlcmluZz0iY3Jpc3BFZGdlcyIvPjxwb2x5Z29uIHBvaW50cz0iMTUwLDAgNTIsMTE3IDMsMTQwIDEwMSwyMiIvPjwvZz48Zz48cG9seWdvbiBwb2ludHM9IjE0MSwyMiAxNDAsNDAgMTIyLDQ1Ii8+PHBvbHlnb24gcG9pbnRzPSIxNTMsMjIgMTUzLDExNyAxMDYsMTE3IDEyMCwxMDUgMTI1LDk1IDEzMSw5NSAxMzEsNDUgMTIyLDQ1IDEzMiwzNiAxNDEsMjIiIHNoYXBlLXJlbmRlcmluZz0iY3Jpc3BFZGdlcyIvPjxwb2x5Z29uIHBvaW50cz0iMTI1LDk1IDEzMCwxMTAgMTA2LDExNyIvPjwvZz48L2c+PC9zdmc+">
99 <style>
1010 :root{
11 --nav-width: 24em;
11 --nav-width: 26em;
1212 --nav-margin-l: 1em;
1313 }
1414 body{
......@@ -27,6 +27,25 @@
2727 #navigation {
2828 padding: 0 1em;
2929 }
30 table ul {
31 list-style-type: none;
32 padding: 0em;
33 }
34 table li {
35 padding-bottom: 1em;
36 line-height:1.2em;
37 }
38 table, th, td {
39 border-collapse: collapse;
40 border: 1px solid grey;
41 }
42 th, td {
43 padding: 0.5em;
44 }
45 th[scope=row] {
46 text-align: left;
47 font-weight: normal;
48 }
3049
3150 @media screen and (min-width: 1025px) {
3251 header {
......@@ -61,17 +80,6 @@
6180 dt {
6281 font-weight: bold;
6382 }
64 table, th, td {
65 border-collapse: collapse;
66 border: 1px solid grey;
67 }
68 th, td {
69 padding: 0.1em;
70 }
71 th[scope=row] {
72 text-align: left;
73 font-weight: normal;
74 }
7583 .sgr-1m {
7684 font-weight: bold;
7785 }
......@@ -200,24 +208,9 @@
200208 visibility: visible;
201209 }
202210
203 pre {
204 counter-reset: line;
205 }
206 pre .line:before {
207 counter-increment: line;
208 content: counter(line);
209 display: inline-block;
210 padding-right: 1em;
211 width: 2em;
212 text-align: right;
213 color: #999;
214 }
215211 th pre code {
216212 background: none;
217213 }
218 th .line:before {
219 display: none;
220 }
221214
222215 @media (prefers-color-scheme: dark) {
223216 body{
......@@ -301,39 +294,6 @@
301294 color: #fff;
302295 }
303296 }
304
305 @media all {
306 main {
307 counter-reset: section-2;
308 }
309 h2 {
310 counter-reset: section-3;
311 }
312 h2::before {
313 counter-increment: section-2;
314 content: counter(section-2) ". ";
315 font-weight: normal;
316 }
317 h3 {
318 counter-reset: section-4;
319 }
320 h3::before {
321 counter-increment: section-3;
322 content: counter(section-2) "." counter(section-3) ". ";
323 font-weight: normal;
324 }
325 h4::before {
326 counter-increment: section-4;
327 content: counter(section-2) "." counter(section-3) "." counter(section-4) ". ";
328 font-weight: normal;
329 }
330 #zig-version::before {
331 content: "";
332 }
333 #table-of-contents::before {
334 content: "";
335 }
336 }
337297 </style>
338298</head>
339299<body>
......@@ -410,109 +370,20 @@ pub fn main() !void {
410370}
411371 {#code_end#}
412372 <p>
413 The Zig code sample above demonstrates one way to create a program that will output: <samp>Hello, world!</samp>.
414 </p>
415 <p>
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>&lt;error set type&gt;</code>{#syntax#}!{#endsyntax#}<code>&lt;any data type&gt;</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>&lt;any data type&gt;</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#}.
373 Most of the time, it more appropriate to write to stderr rather than stdout, and
374 whether or not the message is successfully written to the stream is irrelevant.
375 For this common case, there is a simpler API:
506376 </p>
507377 {#code_begin|exe|hello_again#}
508const print = @import("std").debug.print;
378const std = @import("std");
509379
510380pub fn main() void {
511 print("Hello, world!\n", .{});
381 std.debug.print("Hello, world!\n", .{});
512382}
513383 {#code_end#}
514384 <p>
515 Note that you can leave off the {#syntax#}!{#endsyntax#} from the return type because {#syntax#}std.debug.print{#endsyntax#} cannot fail.
385 In this case, the {#syntax#}!{#endsyntax#} may be omitted from the return
386 type because no errors are returned from the function.
516387 </p>
517388 {#see_also|Values|@import|Errors|Root Source File|Source Encoding#}
518389 {#header_close#}
......@@ -896,42 +767,22 @@ pub fn main() void {
896767 The type of string literals encodes both the length, and the fact that they are null-terminated,
897768 and thus they can be {#link|coerced|Type Coercion#} to both {#link|Slices#} and
898769 {#link|Null-Terminated Pointers|Sentinel-Terminated Pointers#}.
770 Dereferencing string literals converts them to {#link|Arrays#}.
899771 </p>
900772 <p>
901 Dereferencing string literals converts them to {#link|Arrays#}, allowing you to initialize a buffer with the contents of a string literal.
902 </p>
903 {#code_begin|syntax|mutable_string_buffer#}
904test {
905 var buffer = [_]u8{0}**256;
906 const home_dir = "C:/Users/root";
907 buffer[0..home_dir.len].* = home_dir.*;
908}
909 {#code_end#}
910 <p>
911 The encoding of a string in Zig is de-facto assumed to be UTF-8.
912 Because Zig source code is {#link|UTF-8 encoded|Source Encoding#}, any non-ASCII bytes appearing within a string literal
913 in source code carry their UTF-8 meaning into the content of the string in the Zig program;
914 the bytes are not modified by the compiler.
915 However, it is possible to embed non-UTF-8 bytes into a string literal using <code>\xNN</code> notation.
916 </p>
917 <p>
918 Indexing into a string containing non-ASCII bytes will return individual bytes, whether valid
919 UTF-8 or not.
920 The {#link|Zig Standard Library#} provides routines for checking the validity of UTF-8 encoded
921 strings, accessing their code points and other encoding/decoding related tasks in
922 {#syntax#}std.unicode{#endsyntax#}.
773 Because Zig source code is {#link|UTF-8 encoded|Source Encoding#}, any
774 non-ASCII bytes appearing within a string literal in source code carry
775 their UTF-8 meaning into the content of the string in the Zig program;
776 the bytes are not modified by the compiler. It is possible to embed
777 non-UTF-8 bytes into a string literal using <code>\xNN</code> notation.
923778 </p>
779 <p>Indexing into a string containing non-ASCII bytes returns individual
780 bytes, whether valid UTF-8 or not.</p>
924781 <p>
925782 Unicode code point literals have type {#syntax#}comptime_int{#endsyntax#}, the same as
926783 {#link|Integer Literals#}. All {#link|Escape Sequences#} are valid in both string literals
927784 and Unicode code point literals.
928785 </p>
929 <p>
930 In many other programming languages, a Unicode code point literal is called a "character literal".
931 However, there is <a href="https://unicode.org/glossary">no precise technical definition of a "character"</a>
932 in recent versions of the Unicode specification (as of Unicode 13.0).
933 In Zig, a Unicode code point literal corresponds to the Unicode definition of a code point.
934 </p>
935786 {#code_begin|exe|string_literals#}
936787const print = @import("std").debug.print;
937788const mem = @import("std").mem; // will be used to compare bytes
......@@ -1632,26 +1483,27 @@ pub fn main() void {
16321483 {#header_open|Table of Operators#}
16331484 <div class="table-wrapper">
16341485 <table>
1635 <caption>Table of Operators</caption>
16361486 <thead>
16371487 <tr>
1488 <th scope="col">Name</th>
16381489 <th scope="col">Syntax</th>
1639 <th scope="col">Relevant Types</th>
1640 <th scope="col">Description</th>
1490 <th scope="col">Types</th>
1491 <th scope="col">Remarks</th>
16411492 <th scope="col">Example</th>
16421493 </tr>
16431494 </thead>
16441495 <tbody>
16451496 <tr>
1646 <th scope="row"><pre>{#syntax#}a + b
1647a += b{#endsyntax#}</pre></th>
1497 <td>Addition</td>
1498 <td><pre>{#syntax#}a + b
1499a += b{#endsyntax#}</pre></td>
16481500 <td>
16491501 <ul>
16501502 <li>{#link|Integers#}</li>
16511503 <li>{#link|Floats#}</li>
16521504 </ul>
16531505 </td>
1654 <td>Addition.
1506 <td>
16551507 <ul>
16561508 <li>Can cause {#link|overflow|Default Operations#} for integers.</li>
16571509 <li>Invokes {#link|Peer Type Resolution#} for the operands.</li>
......@@ -1663,51 +1515,54 @@ a += b{#endsyntax#}</pre></th>
16631515 </td>
16641516 </tr>
16651517 <tr>
1666 <th scope="row"><pre>{#syntax#}a +% b
1667a +%= b{#endsyntax#}</pre></th>
1518 <td>Wrapping Addition</td>
1519 <td><pre>{#syntax#}a +% b
1520a +%= b{#endsyntax#}</pre></td>
16681521 <td>
16691522 <ul>
16701523 <li>{#link|Integers#}</li>
16711524 </ul>
16721525 </td>
1673 <td>Wrapping Addition.
1526 <td>
16741527 <ul>
1675 <li>Guaranteed to have twos-complement wrapping behavior.</li>
1528 <li>Twos-complement wrapping behavior.</li>
16761529 <li>Invokes {#link|Peer Type Resolution#} for the operands.</li>
16771530 <li>See also {#link|@addWithOverflow#}.</li>
16781531 </ul>
16791532 </td>
16801533 <td>
1681 <pre>{#syntax#}@as(u32, std.math.maxInt(u32)) +% 1 == 0{#endsyntax#}</pre>
1534 <pre>{#syntax#}@as(u32, 0xffffffff) +% 1 == 0{#endsyntax#}</pre>
16821535 </td>
16831536 </tr>
16841537 <tr>
1685 <th scope="row"><pre>{#syntax#}a +| b
1686a +|= b{#endsyntax#}</pre></th>
1538 <td>Saturating Addition</td>
1539 <td><pre>{#syntax#}a +| b
1540a +|= b{#endsyntax#}</pre></td>
16871541 <td>
16881542 <ul>
16891543 <li>{#link|Integers#}</li>
16901544 </ul>
16911545 </td>
1692 <td>Saturating Addition.
1546 <td>
16931547 <ul>
16941548 <li>Invokes {#link|Peer Type Resolution#} for the operands.</li>
16951549 </ul>
16961550 </td>
16971551 <td>
1698 <pre>{#syntax#}@as(u32, std.math.maxInt(u32)) +| 1 == @as(u32, std.math.maxInt(u32)){#endsyntax#}</pre>
1552 <pre>{#syntax#}@as(u8, 255) +| 1 == @as(u8, 255){#endsyntax#}</pre>
16991553 </td>
17001554 </tr>
17011555 <tr>
1702 <th scope="row"><pre>{#syntax#}a - b
1703a -= b{#endsyntax#}</pre></th>
1556 <td>Subtraction</td>
1557 <td><pre>{#syntax#}a - b
1558a -= b{#endsyntax#}</pre></td>
17041559 <td>
17051560 <ul>
17061561 <li>{#link|Integers#}</li>
17071562 <li>{#link|Floats#}</li>
17081563 </ul>
17091564 </td>
1710 <td>Subtraction.
1565 <td>
17111566 <ul>
17121567 <li>Can cause {#link|overflow|Default Operations#} for integers.</li>
17131568 <li>Invokes {#link|Peer Type Resolution#} for the operands.</li>
......@@ -1719,33 +1574,35 @@ a -= b{#endsyntax#}</pre></th>
17191574 </td>
17201575 </tr>
17211576 <tr>
1722 <th scope="row"><pre>{#syntax#}a -% b
1723a -%= b{#endsyntax#}</pre></th>
1577 <td>Wrapping Subtraction</td>
1578 <td><pre>{#syntax#}a -% b
1579a -%= b{#endsyntax#}</pre></td>
17241580 <td>
17251581 <ul>
17261582 <li>{#link|Integers#}</li>
17271583 </ul>
17281584 </td>
1729 <td>Wrapping Subtraction.
1585 <td>
17301586 <ul>
1731 <li>Guaranteed to have twos-complement wrapping behavior.</li>
1587 <li>Twos-complement wrapping behavior.</li>
17321588 <li>Invokes {#link|Peer Type Resolution#} for the operands.</li>
17331589 <li>See also {#link|@subWithOverflow#}.</li>
17341590 </ul>
17351591 </td>
17361592 <td>
1737 <pre>{#syntax#}@as(u32, 0) -% 1 == std.math.maxInt(u32){#endsyntax#}</pre>
1593 <pre>{#syntax#}@as(u8, 0) -% 1 == 255{#endsyntax#}</pre>
17381594 </td>
17391595 </tr>
17401596 <tr>
1741 <th scope="row"><pre>{#syntax#}a -| b
1742a -|= b{#endsyntax#}</pre></th>
1597 <td>Saturating Subtraction</td>
1598 <td><pre>{#syntax#}a -| b
1599a -|= b{#endsyntax#}</pre></td>
17431600 <td>
17441601 <ul>
17451602 <li>{#link|Integers#}</li>
17461603 </ul>
17471604 </td>
1748 <td>Saturating Subtraction.
1605 <td>
17491606 <ul>
17501607 <li>Invokes {#link|Peer Type Resolution#} for the operands.</li>
17511608 </ul>
......@@ -1755,7 +1612,8 @@ a -|= b{#endsyntax#}</pre></th>
17551612 </td>
17561613 </tr>
17571614 <tr>
1758 <th scope="row"><pre>{#syntax#}-a{#endsyntax#}</pre></th>
1615 <td>Negation</td>
1616 <td><pre>{#syntax#}-a{#endsyntax#}</pre></td>
17591617 <td>
17601618 <ul>
17611619 <li>{#link|Integers#}</li>
......@@ -1763,7 +1621,6 @@ a -|= b{#endsyntax#}</pre></th>
17631621 </ul>
17641622 </td>
17651623 <td>
1766 Negation.
17671624 <ul>
17681625 <li>Can cause {#link|overflow|Default Operations#} for integers.</li>
17691626 </ul>
......@@ -1773,32 +1630,33 @@ a -|= b{#endsyntax#}</pre></th>
17731630 </td>
17741631 </tr>
17751632 <tr>
1776 <th scope="row"><pre>{#syntax#}-%a{#endsyntax#}</pre></th>
1633 <td>Wrapping Negation</td>
1634 <td><pre>{#syntax#}-%a{#endsyntax#}</pre></td>
17771635 <td>
17781636 <ul>
17791637 <li>{#link|Integers#}</li>
17801638 </ul>
17811639 </td>
17821640 <td>
1783 Wrapping Negation.
17841641 <ul>
1785 <li>Guaranteed to have twos-complement wrapping behavior.</li>
1642 <li>Twos-complement wrapping behavior.</li>
17861643 </ul>
17871644 </td>
17881645 <td>
1789 <pre>{#syntax#}-%@as(i32, std.math.minInt(i32)) == std.math.minInt(i32){#endsyntax#}</pre>
1646 <pre>{#syntax#}-%@as(i8, -127) == -127{#endsyntax#}</pre>
17901647 </td>
17911648 </tr>
17921649 <tr>
1793 <th scope="row"><pre>{#syntax#}a * b
1794a *= b{#endsyntax#}</pre></th>
1650 <td>Multiplication</td>
1651 <td><pre>{#syntax#}a * b
1652a *= b{#endsyntax#}</pre></td>
17951653 <td>
17961654 <ul>
17971655 <li>{#link|Integers#}</li>
17981656 <li>{#link|Floats#}</li>
17991657 </ul>
18001658 </td>
1801 <td>Multiplication.
1659 <td>
18021660 <ul>
18031661 <li>Can cause {#link|overflow|Default Operations#} for integers.</li>
18041662 <li>Invokes {#link|Peer Type Resolution#} for the operands.</li>
......@@ -1810,16 +1668,17 @@ a *= b{#endsyntax#}</pre></th>
18101668 </td>
18111669 </tr>
18121670 <tr>
1813 <th scope="row"><pre>{#syntax#}a *% b
1814a *%= b{#endsyntax#}</pre></th>
1671 <td>Wrapping Multiplication</td>
1672 <td><pre>{#syntax#}a *% b
1673a *%= b{#endsyntax#}</pre></td>
18151674 <td>
18161675 <ul>
18171676 <li>{#link|Integers#}</li>
18181677 </ul>
18191678 </td>
1820 <td>Wrapping Multiplication.
1679 <td>
18211680 <ul>
1822 <li>Guaranteed to have twos-complement wrapping behavior.</li>
1681 <li>Twos-complement wrapping behavior.</li>
18231682 <li>Invokes {#link|Peer Type Resolution#} for the operands.</li>
18241683 <li>See also {#link|@mulWithOverflow#}.</li>
18251684 </ul>
......@@ -1829,14 +1688,15 @@ a *%= b{#endsyntax#}</pre></th>
18291688 </td>
18301689 </tr>
18311690 <tr>
1832 <th scope="row"><pre>{#syntax#}a *| b
1833a *|= b{#endsyntax#}</pre></th>
1691 <td>Saturating Multiplication</td>
1692 <td><pre>{#syntax#}a *| b
1693a *|= b{#endsyntax#}</pre></td>
18341694 <td>
18351695 <ul>
18361696 <li>{#link|Integers#}</li>
18371697 </ul>
18381698 </td>
1839 <td>Saturating Multiplication.
1699 <td>
18401700 <ul>
18411701 <li>Invokes {#link|Peer Type Resolution#} for the operands.</li>
18421702 </ul>
......@@ -1846,15 +1706,16 @@ a *|= b{#endsyntax#}</pre></th>
18461706 </td>
18471707 </tr>
18481708 <tr>
1849 <th scope="row"><pre>{#syntax#}a / b
1850a /= b{#endsyntax#}</pre></th>
1709 <td>Division</td>
1710 <td><pre>{#syntax#}a / b
1711a /= b{#endsyntax#}</pre></td>
18511712 <td>
18521713 <ul>
18531714 <li>{#link|Integers#}</li>
18541715 <li>{#link|Floats#}</li>
18551716 </ul>
18561717 </td>
1857 <td>Division.
1718 <td>
18581719 <ul>
18591720 <li>Can cause {#link|overflow|Default Operations#} for integers.</li>
18601721 <li>Can cause {#link|Division by Zero#} for integers.</li>
......@@ -1872,15 +1733,16 @@ a /= b{#endsyntax#}</pre></th>
18721733 </td>
18731734 </tr>
18741735 <tr>
1875 <th scope="row"><pre>{#syntax#}a % b
1876a %= b{#endsyntax#}</pre></th>
1736 <td>Remainder Division</td>
1737 <td><pre>{#syntax#}a % b
1738a %= b{#endsyntax#}</pre></td>
18771739 <td>
18781740 <ul>
18791741 <li>{#link|Integers#}</li>
18801742 <li>{#link|Floats#}</li>
18811743 </ul>
18821744 </td>
1883 <td>Remainder Division.
1745 <td>
18841746 <ul>
18851747 <li>Can cause {#link|Division by Zero#} for integers.</li>
18861748 <li>Can cause {#link|Division by Zero#} for floats in {#link|FloatMode.Optimized Mode|Floating Point Operations#}.</li>
......@@ -1896,33 +1758,39 @@ a %= b{#endsyntax#}</pre></th>
18961758 </td>
18971759 </tr>
18981760 <tr>
1899 <th scope="row"><pre>{#syntax#}a << b
1900a <<= b{#endsyntax#}</pre></th>
1761 <td>Bit Shift Left</td>
1762 <td><pre>{#syntax#}a << b
1763a <<= b{#endsyntax#}</pre></td>
19011764 <td>
19021765 <ul>
19031766 <li>{#link|Integers#}</li>
19041767 </ul>
19051768 </td>
1906 <td>Bit Shift Left.
1769 <td>
19071770 <ul>
1908 <li>{#syntax#}b{#endsyntax#} must be {#link|comptime-known|comptime#} or have a type with log2 number of bits as {#syntax#}a{#endsyntax#}.</li>
1771 <li>Moves all bits to the left, inserting new zeroes at the
1772 least-significant bit.</li>
1773 <li>{#syntax#}b{#endsyntax#} must be
1774 {#link|comptime-known|comptime#} or have a type with log2 number
1775 of bits as {#syntax#}a{#endsyntax#}.</li>
19091776 <li>See also {#link|@shlExact#}.</li>
19101777 <li>See also {#link|@shlWithOverflow#}.</li>
19111778 </ul>
19121779 </td>
19131780 <td>
1914 <pre>{#syntax#}1 << 8 == 256{#endsyntax#}</pre>
1781 <pre>{#syntax#}0b1 << 8 == 0b100000000{#endsyntax#}</pre>
19151782 </td>
19161783 </tr>
19171784 <tr>
1918 <th scope="row"><pre>{#syntax#}a <<| b
1919a <<|= b{#endsyntax#}</pre></th>
1785 <td>Saturating Bit Shift Left</td>
1786 <td><pre>{#syntax#}a <<| b
1787a <<|= b{#endsyntax#}</pre></td>
19201788 <td>
19211789 <ul>
19221790 <li>{#link|Integers#}</li>
19231791 </ul>
19241792 </td>
1925 <td>Saturating Bit Shift Left.
1793 <td>
19261794 <ul>
19271795 <li>See also {#link|@shlExact#}.</li>
19281796 <li>See also {#link|@shlWithOverflow#}.</li>
......@@ -1933,32 +1801,37 @@ a <<|= b{#endsyntax#}</pre></th>
19331801 </td>
19341802 </tr>
19351803 <tr>
1936 <th scope="row"><pre>{#syntax#}a >> b
1937a >>= b{#endsyntax#}</pre></th>
1804 <td>Bit Shift Right</td>
1805 <td><pre>{#syntax#}a >> b
1806a >>= b{#endsyntax#}</pre></td>
19381807 <td>
19391808 <ul>
19401809 <li>{#link|Integers#}</li>
19411810 </ul>
19421811 </td>
1943 <td>Bit Shift Right.
1812 <td>
19441813 <ul>
1945 <li>{#syntax#}b{#endsyntax#} must be {#link|comptime-known|comptime#} or have a type with log2 number of bits as {#syntax#}a{#endsyntax#}.</li>
1814 <li>Moves all bits to the right, inserting zeroes at the most-significant bit.</li>
1815 <li>{#syntax#}b{#endsyntax#} must be
1816 {#link|comptime-known|comptime#} or have a type with log2 number
1817 of bits as {#syntax#}a{#endsyntax#}.</li>
19461818 <li>See also {#link|@shrExact#}.</li>
19471819 </ul>
19481820 </td>
19491821 <td>
1950 <pre>{#syntax#}10 >> 1 == 5{#endsyntax#}</pre>
1822 <pre>{#syntax#}0b1010 >> 1 == 0b101{#endsyntax#}</pre>
19511823 </td>
19521824 </tr>
19531825 <tr>
1954 <th scope="row"><pre>{#syntax#}a & b
1955a &= b{#endsyntax#}</pre></th>
1826 <td>Bitwise And</td>
1827 <td><pre>{#syntax#}a & b
1828a &= b{#endsyntax#}</pre></td>
19561829 <td>
19571830 <ul>
19581831 <li>{#link|Integers#}</li>
19591832 </ul>
19601833 </td>
1961 <td>Bitwise AND.
1834 <td>
19621835 <ul>
19631836 <li>Invokes {#link|Peer Type Resolution#} for the operands.</li>
19641837 </ul>
......@@ -1968,14 +1841,15 @@ a &= b{#endsyntax#}</pre></th>
19681841 </td>
19691842 </tr>
19701843 <tr>
1971 <th scope="row"><pre>{#syntax#}a | b
1972a |= b{#endsyntax#}</pre></th>
1844 <td>Bitwise Or</td>
1845 <td><pre>{#syntax#}a | b
1846a |= b{#endsyntax#}</pre></td>
19731847 <td>
19741848 <ul>
19751849 <li>{#link|Integers#}</li>
19761850 </ul>
19771851 </td>
1978 <td>Bitwise OR.
1852 <td>
19791853 <ul>
19801854 <li>Invokes {#link|Peer Type Resolution#} for the operands.</li>
19811855 </ul>
......@@ -1985,14 +1859,15 @@ a |= b{#endsyntax#}</pre></th>
19851859 </td>
19861860 </tr>
19871861 <tr>
1988 <th scope="row"><pre>{#syntax#}a ^ b
1989a ^= b{#endsyntax#}</pre></th>
1862 <td>Bitwise Xor</td>
1863 <td><pre>{#syntax#}a ^ b
1864a ^= b{#endsyntax#}</pre></td>
19901865 <td>
19911866 <ul>
19921867 <li>{#link|Integers#}</li>
19931868 </ul>
19941869 </td>
1995 <td>Bitwise XOR.
1870 <td>
19961871 <ul>
19971872 <li>Invokes {#link|Peer Type Resolution#} for the operands.</li>
19981873 </ul>
......@@ -2002,30 +1877,30 @@ a ^= b{#endsyntax#}</pre></th>
20021877 </td>
20031878 </tr>
20041879 <tr>
2005 <th scope="row"><pre>{#syntax#}~a{#endsyntax#}</pre></th>
1880 <td>Bitwise Not</td>
1881 <td><pre>{#syntax#}~a{#endsyntax#}</pre></td>
20061882 <td>
20071883 <ul>
20081884 <li>{#link|Integers#}</li>
20091885 </ul>
20101886 </td>
2011 <td>
2012 Bitwise NOT.
2013 </td>
1887 <td></td>
20141888 <td>
20151889 <pre>{#syntax#}~@as(u8, 0b10101111) == 0b01010000{#endsyntax#}</pre>
20161890 </td>
20171891 </tr>
20181892 <tr>
2019 <th scope="row"><pre>{#syntax#}a orelse b{#endsyntax#}</pre></th>
1893 <td>Defaulting Optional Unwrap</td>
1894 <td><pre>{#syntax#}a orelse b{#endsyntax#}</pre></td>
20201895 <td>
20211896 <ul>
20221897 <li>{#link|Optionals#}</li>
20231898 </ul>
20241899 </td>
20251900 <td>If {#syntax#}a{#endsyntax#} is {#syntax#}null{#endsyntax#},
2026 returns {#syntax#}b{#endsyntax#} ("default value"),
2027 otherwise returns the unwrapped value of {#syntax#}a{#endsyntax#}.
2028 Note that {#syntax#}b{#endsyntax#} may be a value of type {#link|noreturn#}.
1901 returns {#syntax#}b{#endsyntax#} ("default value"),
1902 otherwise returns the unwrapped value of {#syntax#}a{#endsyntax#}.
1903 Note that {#syntax#}b{#endsyntax#} may be a value of type {#link|noreturn#}.
20291904 </td>
20301905 <td>
20311906 <pre>{#syntax#}const value: ?u32 = null;
......@@ -2034,7 +1909,8 @@ unwrapped == 1234{#endsyntax#}</pre>
20341909 </td>
20351910 </tr>
20361911 <tr>
2037 <th scope="row"><pre>{#syntax#}a.?{#endsyntax#}</pre></th>
1912 <td>Optional Unwrap</td>
1913 <td><pre>{#syntax#}a.?{#endsyntax#}</pre></td>
20381914 <td>
20391915 <ul>
20401916 <li>{#link|Optionals#}</li>
......@@ -2050,18 +1926,19 @@ value.? == 5678{#endsyntax#}</pre>
20501926 </td>
20511927 </tr>
20521928 <tr>
2053 <th scope="row"><pre>{#syntax#}a catch b
2054a catch |err| b{#endsyntax#}</pre></th>
1929 <td>Defaulting Error Unwrap</td>
1930 <td><pre>{#syntax#}a catch b
1931a catch |err| b{#endsyntax#}</pre></td>
20551932 <td>
20561933 <ul>
20571934 <li>{#link|Error Unions|Errors#}</li>
20581935 </ul>
20591936 </td>
20601937 <td>If {#syntax#}a{#endsyntax#} is an {#syntax#}error{#endsyntax#},
2061 returns {#syntax#}b{#endsyntax#} ("default value"),
2062 otherwise returns the unwrapped value of {#syntax#}a{#endsyntax#}.
2063 Note that {#syntax#}b{#endsyntax#} may be a value of type {#link|noreturn#}.
2064 {#syntax#}err{#endsyntax#} is the {#syntax#}error{#endsyntax#} and is in scope of the expression {#syntax#}b{#endsyntax#}.
1938 returns {#syntax#}b{#endsyntax#} ("default value"),
1939 otherwise returns the unwrapped value of {#syntax#}a{#endsyntax#}.
1940 Note that {#syntax#}b{#endsyntax#} may be a value of type {#link|noreturn#}.
1941{#syntax#}err{#endsyntax#} is the {#syntax#}error{#endsyntax#} and is in scope of the expression {#syntax#}b{#endsyntax#}.
20651942 </td>
20661943 <td>
20671944 <pre>{#syntax#}const value: anyerror!u32 = error.Broken;
......@@ -2070,51 +1947,55 @@ unwrapped == 1234{#endsyntax#}</pre>
20701947 </td>
20711948 </tr>
20721949 <tr>
2073 <th scope="row"><pre>{#syntax#}a and b{#endsyntax#}</pre></th>
1950 <td>Logical And</td>
1951 <td><pre>{#syntax#}a and b{#endsyntax#}</pre></td>
20741952 <td>
20751953 <ul>
20761954 <li>{#link|bool|Primitive Types#}</li>
20771955 </ul>
20781956 </td>
20791957 <td>
2080 If {#syntax#}a{#endsyntax#} is {#syntax#}false{#endsyntax#}, returns {#syntax#}false{#endsyntax#}
2081 without evaluating {#syntax#}b{#endsyntax#}. Otherwise, returns {#syntax#}b{#endsyntax#}.
1958 If {#syntax#}a{#endsyntax#} is {#syntax#}false{#endsyntax#}, returns {#syntax#}false{#endsyntax#}
1959 without evaluating {#syntax#}b{#endsyntax#}. Otherwise, returns {#syntax#}b{#endsyntax#}.
20821960 </td>
20831961 <td>
20841962 <pre>{#syntax#}(false and true) == false{#endsyntax#}</pre>
20851963 </td>
20861964 </tr>
20871965 <tr>
2088 <th scope="row"><pre>{#syntax#}a or b{#endsyntax#}</pre></th>
1966 <td>Logical Or</td>
1967 <td><pre>{#syntax#}a or b{#endsyntax#}</pre></td>
20891968 <td>
20901969 <ul>
20911970 <li>{#link|bool|Primitive Types#}</li>
20921971 </ul>
20931972 </td>
20941973 <td>
2095 If {#syntax#}a{#endsyntax#} is {#syntax#}true{#endsyntax#}, returns {#syntax#}true{#endsyntax#}
2096 without evaluating {#syntax#}b{#endsyntax#}. Otherwise, returns {#syntax#}b{#endsyntax#}.
1974 If {#syntax#}a{#endsyntax#} is {#syntax#}true{#endsyntax#},
1975 returns {#syntax#}true{#endsyntax#} without evaluating
1976 {#syntax#}b{#endsyntax#}. Otherwise, returns
1977 {#syntax#}b{#endsyntax#}.
20971978 </td>
20981979 <td>
20991980 <pre>{#syntax#}(false or true) == true{#endsyntax#}</pre>
21001981 </td>
21011982 </tr>
21021983 <tr>
2103 <th scope="row"><pre>{#syntax#}!a{#endsyntax#}</pre></th>
1984 <td>Boolean Not</td>
1985 <td><pre>{#syntax#}!a{#endsyntax#}</pre></td>
21041986 <td>
21051987 <ul>
21061988 <li>{#link|bool|Primitive Types#}</li>
21071989 </ul>
21081990 </td>
2109 <td>
2110 Boolean NOT.
2111 </td>
1991 <td></td>
21121992 <td>
21131993 <pre>{#syntax#}!false == true{#endsyntax#}</pre>
21141994 </td>
21151995 </tr>
21161996 <tr>
2117 <th scope="row"><pre>{#syntax#}a == b{#endsyntax#}</pre></th>
1997 <td>Equality</td>
1998 <td><pre>{#syntax#}a == b{#endsyntax#}</pre></td>
21181999 <td>
21192000 <ul>
21202001 <li>{#link|Integers#}</li>
......@@ -2132,7 +2013,8 @@ unwrapped == 1234{#endsyntax#}</pre>
21322013 </td>
21332014 </tr>
21342015 <tr>
2135 <th scope="row"><pre>{#syntax#}a == null{#endsyntax#}</pre></th>
2016 <td>Null Check</td>
2017 <td><pre>{#syntax#}a == null{#endsyntax#}</pre></td>
21362018 <td>
21372019 <ul>
21382020 <li>{#link|Optionals#}</li>
......@@ -2147,7 +2029,8 @@ unwrapped == 1234{#endsyntax#}</pre>
21472029 </td>
21482030 </tr>
21492031 <tr>
2150 <th scope="row"><pre>{#syntax#}a != b{#endsyntax#}</pre></th>
2032 <td>Inequality</td>
2033 <td><pre>{#syntax#}a != b{#endsyntax#}</pre></td>
21512034 <td>
21522035 <ul>
21532036 <li>{#link|Integers#}</li>
......@@ -2165,7 +2048,8 @@ unwrapped == 1234{#endsyntax#}</pre>
21652048 </td>
21662049 </tr>
21672050 <tr>
2168 <th scope="row"><pre>{#syntax#}a != null{#endsyntax#}</pre></th>
2051 <td>Non-Null Check</td>
2052 <td><pre>{#syntax#}a != null{#endsyntax#}</pre></td>
21692053 <td>
21702054 <ul>
21712055 <li>{#link|Optionals#}</li>
......@@ -2180,7 +2064,8 @@ unwrapped == 1234{#endsyntax#}</pre>
21802064 </td>
21812065 </tr>
21822066 <tr>
2183 <th scope="row"><pre>{#syntax#}a > b{#endsyntax#}</pre></th>
2067 <td>Greater Than</td>
2068 <td><pre>{#syntax#}a > b{#endsyntax#}</pre></td>
21842069 <td>
21852070 <ul>
21862071 <li>{#link|Integers#}</li>
......@@ -2196,7 +2081,8 @@ unwrapped == 1234{#endsyntax#}</pre>
21962081 </td>
21972082 </tr>
21982083 <tr>
2199 <th scope="row"><pre>{#syntax#}a >= b{#endsyntax#}</pre></th>
2084 <td>Greater or Equal</td>
2085 <td><pre>{#syntax#}a >= b{#endsyntax#}</pre></td>
22002086 <td>
22012087 <ul>
22022088 <li>{#link|Integers#}</li>
......@@ -2212,7 +2098,8 @@ unwrapped == 1234{#endsyntax#}</pre>
22122098 </td>
22132099 </tr>
22142100 <tr>
2215 <th scope="row"><pre>{#syntax#}a < b{#endsyntax#}</pre></th>
2101 <td>Less Than</td>
2102 <td><pre>{#syntax#}a < b{#endsyntax#}</pre></td>
22162103 <td>
22172104 <ul>
22182105 <li>{#link|Integers#}</li>
......@@ -2228,7 +2115,8 @@ unwrapped == 1234{#endsyntax#}</pre>
22282115 </td>
22292116 </tr>
22302117 <tr>
2231 <th scope="row"><pre>{#syntax#}a <= b{#endsyntax#}</pre></th>
2118 <td>Lesser or Equal</td>
2119 <td><pre>{#syntax#}a <= b{#endsyntax#}</pre></td>
22322120 <td>
22332121 <ul>
22342122 <li>{#link|Integers#}</li>
......@@ -2244,14 +2132,14 @@ unwrapped == 1234{#endsyntax#}</pre>
22442132 </td>
22452133 </tr>
22462134 <tr>
2247 <th scope="row"><pre>{#syntax#}a ++ b{#endsyntax#}</pre></th>
2135 <td>Array Concatenation</td>
2136 <td><pre>{#syntax#}a ++ b{#endsyntax#}</pre></td>
22482137 <td>
22492138 <ul>
22502139 <li>{#link|Arrays#}</li>
22512140 </ul>
22522141 </td>
22532142 <td>
2254 Array concatenation.
22552143 <ul>
22562144 <li>Only available when the lengths of both {#syntax#}a{#endsyntax#} and {#syntax#}b{#endsyntax#} are {#link|compile-time known|comptime#}.</li>
22572145 </ul>
......@@ -2265,14 +2153,14 @@ mem.eql(u32, &together, &[_]u32{1,2,3,4}){#endsyntax#}</pre>
22652153 </td>
22662154 </tr>
22672155 <tr>
2268 <th scope="row"><pre>{#syntax#}a ** b{#endsyntax#}</pre></th>
2156 <td>Array Multiplication</td>
2157 <td><pre>{#syntax#}a ** b{#endsyntax#}</pre></td>
22692158 <td>
22702159 <ul>
22712160 <li>{#link|Arrays#}</li>
22722161 </ul>
22732162 </td>
22742163 <td>
2275 Array multiplication.
22762164 <ul>
22772165 <li>Only available when the length of {#syntax#}a{#endsyntax#} and {#syntax#}b{#endsyntax#} are {#link|compile-time known|comptime#}.</li>
22782166 </ul>
......@@ -2284,7 +2172,8 @@ mem.eql(u8, pattern, "ababab"){#endsyntax#}</pre>
22842172 </td>
22852173 </tr>
22862174 <tr>
2287 <th scope="row"><pre>{#syntax#}a.*{#endsyntax#}</pre></th>
2175 <td>Pointer Dereference</td>
2176 <td><pre>{#syntax#}a.*{#endsyntax#}</pre></td>
22882177 <td>
22892178 <ul>
22902179 <li>{#link|Pointers#}</li>
......@@ -2300,12 +2189,12 @@ ptr.* == 1234{#endsyntax#}</pre>
23002189 </td>
23012190 </tr>
23022191 <tr>
2303 <th scope="row"><pre>{#syntax#}&a{#endsyntax#}</pre></th>
2192 <td>Address Of</td>
2193 <td><pre>{#syntax#}&a{#endsyntax#}</pre></td>
23042194 <td>
23052195 All types
23062196 </td>
23072197 <td>
2308 Address of.
23092198 </td>
23102199 <td>
23112200 <pre>{#syntax#}const x: u32 = 1234;
......@@ -2314,7 +2203,8 @@ ptr.* == 1234{#endsyntax#}</pre>
23142203 </td>
23152204 </tr>
23162205 <tr>
2317 <th scope="row"><pre>{#syntax#}a || b{#endsyntax#}</pre></th>
2206 <td>Error Set Merge</td>
2207 <td><pre>{#syntax#}a || b{#endsyntax#}</pre></td>
23182208 <td>
23192209 <ul>
23202210 <li>{#link|Error Set Type#}</li>
......@@ -4311,10 +4201,11 @@ test "enum literals with switch" {
43114201 {#code_end#}
43124202 {#header_close#}
43134203
4314 {#header_open|Inline switch#}
4204 {#header_open|Inline Switch Prongs#}
43154205 <p>
43164206 Switch prongs can be marked as {#syntax#}inline{#endsyntax#} to generate
4317 the prong's body for each possible value it could have:
4207 the prong's body for each possible value it could have, making the
4208 captured value {#link|comptime#}.
43184209 </p>
43194210 {#code_begin|test|test_inline_switch#}
43204211const std = @import("std");
......@@ -4324,9 +4215,9 @@ const expectError = std.testing.expectError;
43244215fn isFieldOptional(comptime T: type, field_index: usize) !bool {
43254216 const fields = @typeInfo(T).Struct.fields;
43264217 return switch (field_index) {
4327 // This prong is analyzed `fields.len - 1` times with `idx` being a
4328 // unique comptime-known value each time.
4329 inline 0...fields.len - 1 => |idx| @typeInfo(fields[idx].type) == .Optional,
4218 // This prong is analyzed twice with `idx` being a
4219 // comptime-known value each time.
4220 inline 0, 1 => |idx| @typeInfo(fields[idx].type) == .Optional,
43304221 else => return error.IndexOutOfBounds,
43314222 };
43324223}
......@@ -4350,6 +4241,16 @@ fn isFieldOptionalUnrolled(field_index: usize) !bool {
43504241 1 => true,
43514242 else => return error.IndexOutOfBounds,
43524243 };
4244}
4245 {#code_end#}
4246 <p>The {#syntax#}inline{#endsyntax#} keyword may also be combined with ranges:</p>
4247 {#code_begin|syntax|inline_prong_range#}
4248fn isFieldOptional(comptime T: type, field_index: usize) !bool {
4249 const fields = @typeInfo(T).Struct.fields;
4250 return switch (field_index) {
4251 inline 0...fields.len - 1 => |idx| @typeInfo(fields[idx].type) == .Optional,
4252 else => return error.IndexOutOfBounds,
4253 };
43534254}
43544255 {#code_end#}
43554256 <p>
......@@ -7853,7 +7754,7 @@ comptime {
78537754 {#header_close#}
78547755
78557756 {#header_open|@atomicLoad#}
7856 <pre>{#syntax#}@atomicLoad(comptime T: type, ptr: *const T, comptime ordering: builtin.AtomicOrder) T{#endsyntax#}</pre>
7757 <pre>{#syntax#}@atomicLoad(comptime T: type, ptr: *const T, comptime ordering: AtomicOrder) T{#endsyntax#}</pre>
78577758 <p>
78587759 This builtin function atomically dereferences a pointer to a {#syntax#}T{#endsyntax#} and returns the value.
78597760 </p>
......@@ -7861,11 +7762,12 @@ comptime {
78617762 {#syntax#}T{#endsyntax#} must be a pointer, a {#syntax#}bool{#endsyntax#}, a float,
78627763 an integer or an enum.
78637764 </p>
7765 <p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
78647766 {#see_also|@atomicStore|@atomicRmw|@fence|@cmpxchgWeak|@cmpxchgStrong#}
78657767 {#header_close#}
78667768
78677769 {#header_open|@atomicRmw#}
7868 <pre>{#syntax#}@atomicRmw(comptime T: type, ptr: *T, comptime op: builtin.AtomicRmwOp, operand: T, comptime ordering: builtin.AtomicOrder) T{#endsyntax#}</pre>
7770 <pre>{#syntax#}@atomicRmw(comptime T: type, ptr: *T, comptime op: AtomicRmwOp, operand: T, comptime ordering: AtomicOrder) T{#endsyntax#}</pre>
78697771 <p>
78707772 This builtin function dereferences a pointer to a {#syntax#}T{#endsyntax#} and atomically
78717773 modifies the value and returns the previous value.
......@@ -7874,27 +7776,13 @@ comptime {
78747776 {#syntax#}T{#endsyntax#} must be a pointer, a {#syntax#}bool{#endsyntax#}, a float,
78757777 an integer or an enum.
78767778 </p>
7877 <p>
7878 Supported values for the {#syntax#}op{#endsyntax#} parameter:
7879 </p>
7880 <ul>
7881 <li>{#syntax#}.Xchg{#endsyntax#} - stores the operand unmodified. Supports enums, integers and floats.</li>
7882 <li>{#syntax#}.Add{#endsyntax#} - for integers, twos complement wraparound addition.
7883 Also supports {#link|Floats#}.</li>
7884 <li>{#syntax#}.Sub{#endsyntax#} - for integers, twos complement wraparound subtraction.
7885 Also supports {#link|Floats#}.</li>
7886 <li>{#syntax#}.And{#endsyntax#} - bitwise and</li>
7887 <li>{#syntax#}.Nand{#endsyntax#} - bitwise nand</li>
7888 <li>{#syntax#}.Or{#endsyntax#} - bitwise or</li>
7889 <li>{#syntax#}.Xor{#endsyntax#} - bitwise xor</li>
7890 <li>{#syntax#}.Max{#endsyntax#} - stores the operand if it is larger. Supports integers and floats.</li>
7891 <li>{#syntax#}.Min{#endsyntax#} - stores the operand if it is smaller. Supports integers and floats.</li>
7892 </ul>
7779 <p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
7780 <p>{#syntax#}AtomicRmwOp{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicRmwOp{#endsyntax#}.</p>
78937781 {#see_also|@atomicStore|@atomicLoad|@fence|@cmpxchgWeak|@cmpxchgStrong#}
78947782 {#header_close#}
78957783
78967784 {#header_open|@atomicStore#}
7897 <pre>{#syntax#}@atomicStore(comptime T: type, ptr: *T, value: T, comptime ordering: builtin.AtomicOrder) void{#endsyntax#}</pre>
7785 <pre>{#syntax#}@atomicStore(comptime T: type, ptr: *T, value: T, comptime ordering: AtomicOrder) void{#endsyntax#}</pre>
78987786 <p>
78997787 This builtin function dereferences a pointer to a {#syntax#}T{#endsyntax#} and atomically stores the given value.
79007788 </p>
......@@ -7902,6 +7790,7 @@ comptime {
79027790 {#syntax#}T{#endsyntax#} must be a pointer, a {#syntax#}bool{#endsyntax#}, a float,
79037791 an integer or an enum.
79047792 </p>
7793 <p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
79057794 {#see_also|@atomicLoad|@atomicRmw|@fence|@cmpxchgWeak|@cmpxchgStrong#}
79067795 {#header_close#}
79077796
......@@ -8178,6 +8067,7 @@ fn cmpxchgStrongButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_v
81788067 an integer or an enum.
81798068 </p>
81808069 <p>{#syntax#}@typeInfo(@TypeOf(ptr)).Pointer.alignment{#endsyntax#} must be {#syntax#}>= @sizeOf(T).{#endsyntax#}</p>
8070 <p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
81818071 {#see_also|@atomicStore|@atomicLoad|@atomicRmw|@fence|@cmpxchgWeak#}
81828072 {#header_close#}
81838073
......@@ -8209,6 +8099,7 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val
82098099 an integer or an enum.
82108100 </p>
82118101 <p>{#syntax#}@typeInfo(@TypeOf(ptr)).Pointer.alignment{#endsyntax#} must be {#syntax#}>= @sizeOf(T).{#endsyntax#}</p>
8102 <p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
82128103 {#see_also|@atomicStore|@atomicLoad|@atomicRmw|@fence|@cmpxchgStrong#}
82138104 {#header_close#}
82148105
......@@ -8499,9 +8390,7 @@ export fn @"A function name that is a complete sentence."() void {}
84998390 <p>
85008391 The {#syntax#}fence{#endsyntax#} function is used to introduce happens-before edges between operations.
85018392 </p>
8502 <p>
8503 {#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.
8504 </p>
8393 <p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
85058394 {#see_also|@atomicStore|@atomicLoad|@atomicRmw|@cmpxchgWeak|@cmpxchgStrong#}
85068395 {#header_close#}
85078396
......@@ -8909,7 +8798,7 @@ test "@wasmMemoryGrow" {
89098798 {#header_close#}
89108799
89118800 {#header_open|@prefetch#}
8912 <pre>{#syntax#}@prefetch(ptr: anytype, comptime options: std.builtin.PrefetchOptions) void{#endsyntax#}</pre>
8801 <pre>{#syntax#}@prefetch(ptr: anytype, comptime options: PrefetchOptions) void{#endsyntax#}</pre>
89138802 <p>
89148803 This builtin tells the compiler to emit a prefetch instruction if supported by the
89158804 target CPU. If the target CPU does not support the requested prefetch instruction,
......@@ -8921,37 +8810,7 @@ test "@wasmMemoryGrow" {
89218810 address to prefetch. This function does not dereference the pointer, it is perfectly legal
89228811 to pass a pointer to invalid memory to this function and no illegal behavior will result.
89238812 </p>
8924 <p>
8925 The {#syntax#}options{#endsyntax#} argument is the following struct:
8926 </p>
8927 {#code_begin|syntax|builtin#}
8928/// This data structure is used by the Zig language code generation and
8929/// therefore must be kept in sync with the compiler implementation.
8930pub const PrefetchOptions = struct {
8931 /// Whether the prefetch should prepare for a read or a write.
8932 rw: Rw = .read,
8933 /// The data's locality in an inclusive range from 0 to 3.
8934 ///
8935 /// 0 means no temporal locality. That is, the data can be immediately
8936 /// dropped from the cache after it is accessed.
8937 ///
8938 /// 3 means high temporal locality. That is, the data should be kept in
8939 /// the cache as it is likely to be accessed again soon.
8940 locality: u2 = 3,
8941 /// The cache that the prefetch should be preformed on.
8942 cache: Cache = .data,
8943
8944 pub const Rw = enum(u1) {
8945 read,
8946 write,
8947 };
8948
8949 pub const Cache = enum(u1) {
8950 instruction,
8951 data,
8952 };
8953};
8954 {#code_end#}
8813 <p>{#syntax#}PrefetchOptions{#endsyntax#} can be found with {#syntax#}@import("std").builtin.PrefetchOptions{#endsyntax#}.</p>
89558814 {#header_close#}
89568815
89578816 {#header_open|@ptrCast#}
......@@ -9080,16 +8939,8 @@ test "foo" {
90808939 {#header_close#}
90818940
90828941 {#header_open|@setFloatMode#}
9083 <pre>{#syntax#}@setFloatMode(comptime mode: @import("std").builtin.FloatMode) void{#endsyntax#}</pre>
9084 <p>
9085 Sets the floating point mode of the current scope. Possible values are:
9086 </p>
9087 {#code_begin|syntax|FloatMode#}
9088pub const FloatMode = enum {
9089 Strict,
9090 Optimized,
9091};
9092 {#code_end#}
8942 <pre>{#syntax#}@setFloatMode(comptime mode: FloatMode) void{#endsyntax#}</pre>
8943 <p>Changes the current scope's rules about how floating point operations are defined.</p>
90938944 <ul>
90948945 <li>
90958946 {#syntax#}Strict{#endsyntax#} (default) - Floating point operations follow strict IEEE compliance.
......@@ -9111,6 +8962,7 @@ pub const FloatMode = enum {
91118962 The floating point mode is inherited by child scopes, and can be overridden in any scope.
91128963 You can set the floating point mode in a struct or module scope by using a comptime block.
91138964 </p>
8965 <p>{#syntax#}FloatMode{#endsyntax#} can be found with {#syntax#}@import("std").builtin.FloatMode{#endsyntax#}.</p>
91148966 {#see_also|Floating Point Operations#}
91158967 {#header_close#}
91168968
......@@ -11522,7 +11374,6 @@ fn readU32Be() u32 {}
1152211374 {#header_open|Keyword Reference#}
1152311375 <div class="table-wrapper">
1152411376 <table>
11525 <caption>Keywords</caption>
1152611377 <thead>
1152711378 <tr>
1152811379 <th scope="col">Keyword</th>
lib/std/builtin.zig+20
......@@ -102,14 +102,34 @@ pub const ReduceOp = enum {
102102/// This data structure is used by the Zig language code generation and
103103/// therefore must be kept in sync with the compiler implementation.
104104pub const AtomicRmwOp = enum {
105 /// Exchange - store the operand unmodified.
106 /// Supports enums, integers, and floats.
105107 Xchg,
108 /// Add operand to existing value.
109 /// Supports integers and floats.
110 /// For integers, two's complement wraparound applies.
106111 Add,
112 /// Subtract operand from existing value.
113 /// Supports integers and floats.
114 /// For integers, two's complement wraparound applies.
107115 Sub,
116 /// Perform bitwise AND on existing value with operand.
117 /// Supports integers.
108118 And,
119 /// Perform bitwise NAND on existing value with operand.
120 /// Supports integers.
109121 Nand,
122 /// Perform bitwise OR on existing value with operand.
123 /// Supports integers.
110124 Or,
125 /// Perform bitwise XOR on existing value with operand.
126 /// Supports integers.
111127 Xor,
128 /// Store operand if it is larger than the existing value.
129 /// Supports integers and floats.
112130 Max,
131 /// Store operand if it is smaller than the existing value.
132 /// Supports integers and floats.
113133 Min,
114134};
115135
lib/std/fmt.zig+3-3
......@@ -40,9 +40,9 @@ pub const FormatOptions = struct {
4040/// - when using a field name, you are required to enclose the field name (an identifier) in square
4141/// brackets, e.g. {[score]...} as opposed to the numeric index form which can be written e.g. {2...}
4242/// - *specifier* is a type-dependent formatting option that determines how a type should formatted (see below)
43/// - *fill* is a single character which is used to pad the formatted text
44/// - *alignment* is one of the three characters `<`, `^`, or `>` to make the text left-, center-, or right-aligned, respectively
45/// - *width* is the total width of the field in characters
43/// - *fill* is a single unicode codepoint which is used to pad the formatted text
44/// - *alignment* is one of the three bytes '<', '^', or '>' to make the text left-, center-, or right-aligned, respectively
45/// - *width* is the total width of the field in unicode codepoints
4646/// - *precision* specifies how many decimals a formatted number should have
4747///
4848/// Note that most of the parameters are optional and may be omitted. Also you can leave out separators like `:` and `.` when
tools/docgen.zig+6-28
......@@ -947,19 +947,8 @@ fn isType(name: []const u8) bool {
947947 return false;
948948}
949949
950const start_line = "<span class=\"line\">";
951const end_line = "</span>";
952
953950fn writeEscapedLines(out: anytype, text: []const u8) !void {
954 for (text) |char| {
955 if (char == '\n') {
956 try out.writeAll(end_line);
957 try out.writeAll("\n");
958 try out.writeAll(start_line);
959 } else {
960 try writeEscaped(out, &[_]u8{char});
961 }
962 }
951 return writeEscaped(out, text);
963952}
964953
965954fn tokenizeAndPrintRaw(
......@@ -972,7 +961,7 @@ fn tokenizeAndPrintRaw(
972961 const src_non_terminated = mem.trim(u8, raw_src, " \r\n");
973962 const src = try allocator.dupeZ(u8, src_non_terminated);
974963
975 try out.writeAll("<code>" ++ start_line);
964 try out.writeAll("<code>");
976965 var tokenizer = std.zig.Tokenizer.init(src);
977966 var index: usize = 0;
978967 var next_tok_is_fn = false;
......@@ -1062,6 +1051,7 @@ fn tokenizeAndPrintRaw(
10621051 },
10631052
10641053 .string_literal,
1054 .multiline_string_literal_line,
10651055 .char_literal,
10661056 => {
10671057 try out.writeAll("<span class=\"tok-str\">");
......@@ -1069,18 +1059,6 @@ fn tokenizeAndPrintRaw(
10691059 try out.writeAll("</span>");
10701060 },
10711061
1072 .multiline_string_literal_line => {
1073 if (src[token.loc.end - 1] == '\n') {
1074 try out.writeAll("<span class=\"tok-str\">");
1075 try writeEscaped(out, src[token.loc.start .. token.loc.end - 1]);
1076 try out.writeAll("</span>" ++ end_line ++ "\n" ++ start_line);
1077 } else {
1078 try out.writeAll("<span class=\"tok-str\">");
1079 try writeEscaped(out, src[token.loc.start..token.loc.end]);
1080 try out.writeAll("</span>");
1081 }
1082 },
1083
10841062 .builtin => {
10851063 try out.writeAll("<span class=\"tok-builtin\">");
10861064 try writeEscaped(out, src[token.loc.start..token.loc.end]);
......@@ -1211,7 +1189,7 @@ fn tokenizeAndPrintRaw(
12111189 }
12121190 index = token.loc.end;
12131191 }
1214 try out.writeAll(end_line ++ "</code>");
1192 try out.writeAll("</code>");
12151193}
12161194
12171195fn tokenizeAndPrint(
......@@ -1234,9 +1212,9 @@ fn printSourceBlock(allocator: Allocator, docgen_tokenizer: *Tokenizer, out: any
12341212 const raw_source = docgen_tokenizer.buffer[syntax_block.source_token.start..syntax_block.source_token.end];
12351213 const trimmed_raw_source = mem.trim(u8, raw_source, " \r\n");
12361214
1237 try out.writeAll("<code>" ++ start_line);
1215 try out.writeAll("<code>");
12381216 try writeEscapedLines(out, trimmed_raw_source);
1239 try out.writeAll(end_line ++ "</code>");
1217 try out.writeAll("</code>");
12401218 },
12411219 }
12421220 try out.writeAll("</pre></figure>");