Commit 0c091feb5ae52caf1ebf885c0de55b3159207001 | zig

author	Mr. Paul <mrpaul@aestheticwisdom.com> 2021-08-11 16:01:03+07:00
committer	Andrew Kelley <andrew@ziglang.org> 2021-09-10 14:23:32-04:00
log	0c091feb5ae52caf1ebf885c0de55b3159207001
tree	6619f5d03bbccd5a500035947cf50f2118b4dc46
parent	9e24727062624ec51eadb833d3c434b15889a9c3

Improve HTML semantics and a11y of language reference

The language reference's HTML has been updated to be more semantically correct.
This also helps to improve the document's accessibility concerns.

* Document structure has single h1, other header sections start at h2, nav sections w/ aria labels, main section
* Zig's homepage is linked, Zig Standard Library section link to it
* Tables have caption and scoping rows and columns
* Code blocks are figures with figure captions citing source files
* Change line height 1.5 to include table of contents as well
* Luminosity contrast ratios have been adjusted to 7:1
* Dark mode colors adjusted to reduce eye strain
* Links have default browser underline with hover and focus effects
* Asides, definition lists, keyboard inputs, program outputs are represented semantically

Tools used to check:
WAVE plugin https://wave.webaim.org/
Firefox Accessibility Developer Tool
Lighthouse Accessibility Tool

2 files changed, 1142 insertions(+), 726 deletions(-)

doc
- docgen.zig
- langref.html.in

doc/docgen.zig+391-65

...	...	@@ -280,7 +280,7 @@ const Code = struct {
280	280	id: Id,
281	281	name: []const u8,
282	282	source_token: Token,
283		is_inline: bool,
	283	just_check_syntax: bool,
284	284	mode: std.builtin.Mode,
285	285	link_objects: []const []const u8,
286	286	target_str: ?[]const u8,
...	...	@@ -305,6 +305,18 @@ const Link = struct {
305	305	token: Token,
306	306	};
307	307
	308	const SyntaxBlock = struct {
	309	source_type: SourceType,
	310	name: []const u8,
	311	source_token: Token,
	312
	313	const SourceType = enum {
	314	zig,
	315	c,
	316	javascript,
	317	};
	318	};
	319
308	320	const Node = union(enum) {
309	321	Content: []const u8,
310	322	Nav,
...	...	@@ -313,7 +325,9 @@ const Node = union(enum) {
313	325	SeeAlso: []const SeeAlsoItem,
314	326	Code: Code,
315	327	Link: Link,
316		Syntax: Token,
	328	InlineSyntax: Token,
	329	Shell: Token,
	330	SyntaxBlock: SyntaxBlock,
317	331	};
318	332
319	333	const Toc = struct {
...	...	@@ -403,7 +417,7 @@ fn genToc(allocator: Allocator, tokenizer: Tokenizer) !Toc {
403	417	.HeaderOpen = HeaderOpen{
404	418	.name = content,
405	419	.url = urlized,
406		.n = header_stack_size,
	420	.n = header_stack_size + 1, // highest-level section headers start at h2
407	421	},
408	422	});
409	423	if (try urls.fetchPut(urlized, tag_token)) \|kv\| {
...	...	@@ -502,7 +516,7 @@ fn genToc(allocator: Allocator, tokenizer: Tokenizer) !Toc {
502	516	}
503	517	const code_kind_str = tokenizer.buffer[code_kind_tok.start..code_kind_tok.end];
504	518	var code_kind_id: Code.Id = undefined;
505		var is_inline = false;
	519	var just_check_syntax = false;
506	520	if (mem.eql(u8, code_kind_str, "exe")) {
507	521	code_kind_id = Code.Id{ .Exe = ExpectedOutcome.Succeed };
508	522	} else if (mem.eql(u8, code_kind_str, "exe_err")) {
...	...	@@ -526,7 +540,7 @@ fn genToc(allocator: Allocator, tokenizer: Tokenizer) !Toc {
526	540	code_kind_id = Code.Id.Lib;
527	541	} else if (mem.eql(u8, code_kind_str, "syntax")) {
528	542	code_kind_id = Code.Id{ .Obj = null };
529		is_inline = true;
	543	just_check_syntax = true;
530	544	} else {
531	545	return parseError(tokenizer, code_kind_tok, "unrecognized code kind: {s}", .{code_kind_str});
532	546	}
...	...	@@ -589,7 +603,7 @@ fn genToc(allocator: Allocator, tokenizer: Tokenizer) !Toc {
589	603	.id = code_kind_id,
590	604	.name = name,
591	605	.source_token = source_token,
592		.is_inline = is_inline,
	606	.just_check_syntax = just_check_syntax,
593	607	.mode = mode,
594	608	.link_objects = link_objects.toOwnedSlice(),
595	609	.target_str = target_str,
...	...	@@ -615,7 +629,67 @@ fn genToc(allocator: Allocator, tokenizer: Tokenizer) !Toc {
615	629	);
616	630	}
617	631	_ = try eatToken(tokenizer, Token.Id.BracketClose);
618		try nodes.append(Node{ .Syntax = content_tok });
	632	try nodes.append(Node{ .InlineSyntax = content_tok });
	633	} else if (mem.eql(u8, tag_name, "shell_samp")) {
	634	_ = try eatToken(tokenizer, Token.Id.BracketClose);
	635	const content_tok = try eatToken(tokenizer, Token.Id.Content);
	636	_ = try eatToken(tokenizer, Token.Id.BracketOpen);
	637	const end_syntax_tag = try eatToken(tokenizer, Token.Id.TagContent);
	638	const end_tag_name = tokenizer.buffer[end_syntax_tag.start..end_syntax_tag.end];
	639	if (!mem.eql(u8, end_tag_name, "end_shell_samp")) {
	640	return parseError(
	641	tokenizer,
	642	end_syntax_tag,
	643	"invalid token inside syntax: {s}",
	644	.{end_tag_name},
	645	);
	646	}
	647	_ = try eatToken(tokenizer, Token.Id.BracketClose);
	648	try nodes.append(Node{ .Shell = content_tok });
	649	} else if (mem.eql(u8, tag_name, "syntax_block")) {
	650	_ = try eatToken(tokenizer, Token.Id.Separator);
	651	const source_type_tok = try eatToken(tokenizer, Token.Id.TagContent);
	652	var name: []const u8 = "sample_code";
	653	const maybe_sep = tokenizer.next();
	654	switch (maybe_sep.id) {
	655	Token.Id.Separator => {
	656	const name_tok = try eatToken(tokenizer, Token.Id.TagContent);
	657	name = tokenizer.buffer[name_tok.start..name_tok.end];
	658	_ = try eatToken(tokenizer, Token.Id.BracketClose);
	659	},
	660	Token.Id.BracketClose => {},
	661	else => return parseError(tokenizer, token, "invalid token", .{}),
	662	}
	663	const source_type_str = tokenizer.buffer[source_type_tok.start..source_type_tok.end];
	664	var source_type: SyntaxBlock.SourceType = undefined;
	665	if (mem.eql(u8, source_type_str, "zig")) {
	666	source_type = SyntaxBlock.SourceType.zig;
	667	} else if (mem.eql(u8, source_type_str, "c")) {
	668	source_type = SyntaxBlock.SourceType.c;
	669	} else if (mem.eql(u8, source_type_str, "javascript")) {
	670	source_type = SyntaxBlock.SourceType.javascript;
	671	} else {
	672	return parseError(tokenizer, source_type_tok, "unrecognized code kind: {s}", .{source_type_str});
	673	}
	674	const source_token = while (true) {
	675	const content_tok = try eatToken(tokenizer, Token.Id.Content);
	676	_ = try eatToken(tokenizer, Token.Id.BracketOpen);
	677	const end_code_tag = try eatToken(tokenizer, Token.Id.TagContent);
	678	const end_tag_name = tokenizer.buffer[end_code_tag.start..end_code_tag.end];
	679	if (mem.eql(u8, end_tag_name, "end_syntax_block")) {
	680	_ = try eatToken(tokenizer, Token.Id.BracketClose);
	681	break content_tok;
	682	} else {
	683	return parseError(
	684	tokenizer,
	685	end_code_tag,
	686	"invalid token inside code_begin: {s}",
	687	.{end_tag_name},
	688	);
	689	}
	690	_ = try eatToken(tokenizer, Token.Id.BracketClose);
	691	} else unreachable; // TODO issue #707
	692	try nodes.append(Node{ .SyntaxBlock = SyntaxBlock{ .source_type = source_type, .name = name, .source_token = source_token } });
619	693	} else {
620	694	return parseError(tokenizer, tag_token, "unrecognized tag name: {s}", .{tag_name});
621	695	}
...	...	@@ -693,7 +767,7 @@ test "term color" {
693	767	const input_bytes = "A\x1b[32;1mgreen\x1b[0mB";
694	768	const result = try termColor(std.testing.allocator, input_bytes);
695	769	defer std.testing.allocator.free(result);
696		testing.expectEqualSlices(u8, "A<span class=\"t32\">green</span>B", result);
	770	try testing.expectEqualSlices(u8, "A<span class=\"t32_1\">green</span>B", result);
697	771	}
698	772
699	773	fn termColor(allocator: *Allocator, input: []const u8) ![]u8 {
...	...	@@ -799,7 +873,7 @@ fn tokenizeAndPrintRaw(
799	873	) !void {
800	874	const src_non_terminated = mem.trim(u8, raw_src, " \n");
801	875	const src = try allocator.dupeZ(u8, src_non_terminated);
802		try out.writeAll("<code class=\"zig\">");
	876	try out.writeAll("<code>");
803	877	var tokenizer = std.zig.Tokenizer.init(src);
804	878	var index: usize = 0;
805	879	var next_tok_is_fn = false;
...	...	@@ -1033,6 +1107,47 @@ fn tokenizeAndPrint(
1033	1107	return tokenizeAndPrintRaw(allocator, docgen_tokenizer, out, source_token, raw_src);
1034	1108	}
1035	1109
	1110	fn printSourceBlock(allocator: Allocator, docgen_tokenizer: Tokenizer, out: anytype, syntax_block: SyntaxBlock) !void {
	1111	const source_type = @tagName(syntax_block.source_type);
	1112
	1113	try out.print("<figure><figcaption class=\"{s}-cap\"><cite class=\"file\">{s}</cite></figcaption><pre>", .{ source_type, syntax_block.name });
	1114	switch (syntax_block.source_type) {
	1115	.zig => try tokenizeAndPrint(allocator, docgen_tokenizer, out, syntax_block.source_token),
	1116	else => {
	1117	const raw_source = docgen_tokenizer.buffer[syntax_block.source_token.start..syntax_block.source_token.end];
	1118	const trimmed_raw_source = mem.trim(u8, raw_source, " \n");
	1119
	1120	try out.writeAll("<code>");
	1121	try writeEscaped(out, trimmed_raw_source);
	1122	try out.writeAll("</code>");
	1123	},
	1124	}
	1125	try out.writeAll("</pre></figure>");
	1126	}
	1127
	1128	fn printShell(out: anytype, shell_content: []const u8) !void {
	1129	const trimmed_shell_content = mem.trim(u8, shell_content, " \n");
	1130	try out.writeAll("<figure><figcaption class=\"shell-cap\">Shell</figcaption><pre><samp>");
	1131	var cmd_cont: bool = false;
	1132	var iter = std.mem.split(u8, trimmed_shell_content, "\n");
	1133	while (iter.next()) \|orig_line\| {
	1134	const line = mem.trimRight(u8, orig_line, " ");
	1135	if (!cmd_cont and line.len > 1 and mem.eql(u8, line[0..2], "$ ") and line[line.len - 1] != '\\') {
	1136	try out.print("$ <kbd>{s}</kbd>\n", .{std.mem.trimLeft(u8, line[1..], " ")});
	1137	} else if (!cmd_cont and line.len > 1 and mem.eql(u8, line[0..2], "$ ") and line[line.len - 1] == '\\') {
	1138	try out.print("$ <kbd>{s}\n", .{std.mem.trimLeft(u8, line[1..], " ")});
	1139	cmd_cont = true;
	1140	} else if (line.len > 0 and line[line.len - 1] != '\\' and cmd_cont) {
	1141	try out.print("{s}</kbd>\n", .{line});
	1142	cmd_cont = false;
	1143	} else {
	1144	try out.print("{s}\n", .{line});
	1145	}
	1146	}
	1147
	1148	try out.writeAll("</samp></pre></figure>");
	1149	}
	1150
1036	1151	fn genHtml(
1037	1152	allocator: *Allocator,
1038	1153	tokenizer: *Tokenizer,
...	...	@@ -1066,9 +1181,9 @@ fn genHtml(
1066	1181	try out.writeAll(toc.toc);
1067	1182	},
1068	1183	.Builtin => \|tok\| {
1069		try out.writeAll("<pre>");
	1184	try out.writeAll("<figure><figcaption class=\"zig-cap\"><cite>@import(\"builtin\")</cite></figcaption><pre>");
1070	1185	try tokenizeAndPrintRaw(allocator, tokenizer, out, tok, builtin_code);
1071		try out.writeAll("</pre>");
	1186	try out.writeAll("</pre></figure>");
1072	1187	},
1073	1188	.HeaderOpen => \|info\| {
1074	1189	try out.print(
...	...	@@ -1087,30 +1202,44 @@ fn genHtml(
1087	1202	}
1088	1203	try out.writeAll("</ul>\n");
1089	1204	},
1090		.Syntax => \|content_tok\| {
	1205	.InlineSyntax => \|content_tok\| {
1091	1206	try tokenizeAndPrint(allocator, tokenizer, out, content_tok);
1092	1207	},
	1208	.Shell => \|content_tok\| {
	1209	const raw_shell_content = tokenizer.buffer[content_tok.start..content_tok.end];
	1210	try printShell(out, raw_shell_content);
	1211	},
	1212	.SyntaxBlock => \|syntax_block\| {
	1213	try printSourceBlock(allocator, tokenizer, out, syntax_block);
	1214	},
1093	1215	.Code => \|code\| {
1094		const raw_source = tokenizer.buffer[code.source_token.start..code.source_token.end];
1095		const trimmed_raw_source = mem.trim(u8, raw_source, " \n");
1096		if (!code.is_inline) {
1097		try out.print("<p class=\"file\">{s}.zig</p>", .{code.name});
1098		}
1099		try out.writeAll("<pre>");
1100		try tokenizeAndPrint(allocator, tokenizer, out, code.source_token);
1101		try out.writeAll("</pre>");
	1216	const name_plus_ext = try std.fmt.allocPrint(allocator, "{s}.zig", .{code.name});
	1217	const syntax_block = SyntaxBlock{
	1218	.source_type = .zig,
	1219	.name = name_plus_ext,
	1220	.source_token = code.source_token,
	1221	};
	1222
	1223	try printSourceBlock(allocator, tokenizer, out, syntax_block);
1102	1224
1103		if (!do_code_tests or code.is_inline) {
	1225	// TODO: remove code.just_check_syntax after updating code samples
	1226	// that have stopped working due to a change in the compiler.
	1227	if (!do_code_tests or code.just_check_syntax) {
1104	1228	continue;
1105	1229	}
1106	1230
1107		const name_plus_ext = try std.fmt.allocPrint(allocator, "{s}.zig", .{code.name});
	1231	const raw_source = tokenizer.buffer[code.source_token.start..code.source_token.end];
	1232	const trimmed_raw_source = mem.trim(u8, raw_source, " \n");
1108	1233	const tmp_source_file_name = try fs.path.join(
1109	1234	allocator,
1110	1235	&[_][]const u8{ tmp_dir_name, name_plus_ext },
1111	1236	);
1112	1237	try fs.cwd().writeFile(tmp_source_file_name, trimmed_raw_source);
1113	1238
	1239	var shell_buffer = std.ArrayList(u8).init(allocator);
	1240	defer shell_buffer.deinit();
	1241	var shell_out = shell_buffer.writer();
	1242
1114	1243	switch (code.id) {
1115	1244	Code.Id.Exe => \|expected_outcome\| code_block: {
1116	1245	var build_args = std.ArrayList([]const u8).init(allocator);
...	...	@@ -1121,12 +1250,14 @@ fn genHtml(
1121	1250	"--color", "on",
1122	1251	"--enable-cache", tmp_source_file_name,
1123	1252	});
1124		try out.print("<pre><code class=\"shell\">$ zig build-exe {s}.zig", .{code.name});
	1253
	1254	try shell_out.print("$ zig build-exe {s} ", .{name_plus_ext});
	1255
1125	1256	switch (code.mode) {
1126	1257	.Debug => {},
1127	1258	else => {
1128	1259	try build_args.appendSlice(&[_][]const u8{ "-O", @tagName(code.mode) });
1129		try out.print(" -O {s}", .{@tagName(code.mode)});
	1260	try shell_out.print("-O {s} ", .{@tagName(code.mode)});
1130	1261	},
1131	1262	}
1132	1263	for (code.link_objects) \|link_object\| {
...	...	@@ -1136,25 +1267,26 @@ fn genHtml(
1136	1267	&[_][]const u8{ tmp_dir_name, name_with_ext },
1137	1268	);
1138	1269	try build_args.append(full_path_object);
1139		try out.print(" {s}", .{name_with_ext});
	1270	try shell_out.print("{s} ", .{name_with_ext});
1140	1271	}
1141	1272	if (code.link_libc) {
1142	1273	try build_args.append("-lc");
1143		try out.print(" -lc", .{});
	1274	try shell_out.print("-lc ", .{});
1144	1275	}
1145	1276	const target = try std.zig.CrossTarget.parse(.{
1146	1277	.arch_os_abi = code.target_str orelse "native",
1147	1278	});
1148	1279	if (code.target_str) \|triple\| {
1149	1280	try build_args.appendSlice(&[_][]const u8{ "-target", triple });
1150		if (!code.is_inline) {
1151		try out.print(" -target {s}", .{triple});
1152		}
	1281	try shell_out.print("-target {s} ", .{triple});
1153	1282	}
1154	1283	if (code.verbose_cimport) {
1155	1284	try build_args.append("--verbose-cimport");
1156		try out.print(" --verbose-cimport", .{});
	1285	try shell_out.print("--verbose-cimport ", .{});
1157	1286	}
	1287
	1288	try shell_out.print("\n", .{});
	1289
1158	1290	if (expected_outcome == .BuildFail) {
1159	1291	const result = try ChildProcess.exec(.{
1160	1292	.allocator = allocator,
...	...	@@ -1180,12 +1312,17 @@ fn genHtml(
1180	1312	}
1181	1313	const escaped_stderr = try escapeHtml(allocator, result.stderr);
1182	1314	const colored_stderr = try termColor(allocator, escaped_stderr);
1183		try out.print("\n{s}</code></pre>\n", .{colored_stderr});
	1315	try shell_out.writeAll(colored_stderr);
1184	1316	break :code_block;
1185	1317	}
1186	1318	const exec_result = exec(allocator, &env_map, build_args.items) catch
1187	1319	return parseError(tokenizer, code.source_token, "example failed to compile", .{});
1188	1320
	1321	if (code.verbose_cimport) {
	1322	const escaped_build_stderr = try escapeHtml(allocator, exec_result.stderr);
	1323	try shell_out.writeAll(escaped_build_stderr);
	1324	}
	1325
1189	1326	if (code.target_str) \|triple\| {
1190	1327	if (mem.startsWith(u8, triple, "wasm32") or
1191	1328	mem.startsWith(u8, triple, "riscv64-linux") or
...	...	@@ -1193,7 +1330,6 @@ fn genHtml(
1193	1330	std.Target.current.os.tag != .linux or std.Target.current.cpu.arch != .x86_64))
1194	1331	{
1195	1332	// skip execution
1196		try out.print("</code></pre>\n", .{});
1197	1333	break :code_block;
1198	1334	}
1199	1335	}
...	...	@@ -1241,41 +1377,38 @@ fn genHtml(
1241	1377	const colored_stderr = try termColor(allocator, escaped_stderr);
1242	1378	const colored_stdout = try termColor(allocator, escaped_stdout);
1243	1379
1244		if (code.verbose_cimport) {
1245		const escaped_build_stderr = try escapeHtml(allocator, exec_result.stderr);
1246		try out.print("\n{s}", .{escaped_build_stderr});
1247		}
1248		try out.print("\n$ ./{s}\n{s}{s}", .{ code.name, colored_stdout, colored_stderr });
	1380	try shell_out.print("\n$ ./{s}\n{s}{s}", .{ code.name, colored_stdout, colored_stderr });
1249	1381	if (exited_with_signal) {
1250		try out.print("(process terminated by signal)", .{});
	1382	try shell_out.print("(process terminated by signal)", .{});
1251	1383	}
1252		try out.print("</code></pre>\n", .{});
	1384	try shell_out.writeAll("\n");
1253	1385	},
1254	1386	Code.Id.Test => {
1255	1387	var test_args = std.ArrayList([]const u8).init(allocator);
1256	1388	defer test_args.deinit();
1257	1389
1258	1390	try test_args.appendSlice(&[_][]const u8{ zig_exe, "test", tmp_source_file_name });
1259		try out.print("<pre><code class=\"shell\">$ zig test {s}.zig", .{code.name});
	1391	try shell_out.print("$ zig test {s}.zig ", .{code.name});
	1392
1260	1393	switch (code.mode) {
1261	1394	.Debug => {},
1262	1395	else => {
1263	1396	try test_args.appendSlice(&[_][]const u8{ "-O", @tagName(code.mode) });
1264		try out.print(" -O {s}", .{@tagName(code.mode)});
	1397	try shell_out.print("-O {s} ", .{@tagName(code.mode)});
1265	1398	},
1266	1399	}
1267	1400	if (code.link_libc) {
1268	1401	try test_args.append("-lc");
1269		try out.print(" -lc", .{});
	1402	try shell_out.print("-lc ", .{});
1270	1403	}
1271	1404	if (code.target_str) \|triple\| {
1272	1405	try test_args.appendSlice(&[_][]const u8{ "-target", triple });
1273		try out.print(" -target {s}", .{triple});
	1406	try shell_out.print("-target {s} ", .{triple});
1274	1407	}
1275	1408	const result = exec(allocator, &env_map, test_args.items) catch return parseError(tokenizer, code.source_token, "test failed", .{});
1276	1409	const escaped_stderr = try escapeHtml(allocator, result.stderr);
1277	1410	const escaped_stdout = try escapeHtml(allocator, result.stdout);
1278		try out.print("\n{s}{s}</code></pre>\n", .{ escaped_stderr, escaped_stdout });
	1411	try shell_out.print("\n{s}{s}\n", .{ escaped_stderr, escaped_stdout });
1279	1412	},
1280	1413	Code.Id.TestError => \|error_match\| {
1281	1414	var test_args = std.ArrayList([]const u8).init(allocator);
...	...	@@ -1288,12 +1421,13 @@ fn genHtml(
1288	1421	"on",
1289	1422	tmp_source_file_name,
1290	1423	});
1291		try out.print("<pre><code class=\"shell\">$ zig test {s}.zig", .{code.name});
	1424	try shell_out.print("$ zig test {s}.zig ", .{code.name});
	1425
1292	1426	switch (code.mode) {
1293	1427	.Debug => {},
1294	1428	else => {
1295	1429	try test_args.appendSlice(&[_][]const u8{ "-O", @tagName(code.mode) });
1296		try out.print(" -O {s}", .{@tagName(code.mode)});
	1430	try shell_out.print("-O {s} ", .{@tagName(code.mode)});
1297	1431	},
1298	1432	}
1299	1433	const result = try ChildProcess.exec(.{
...	...	@@ -1325,7 +1459,7 @@ fn genHtml(
1325	1459	}
1326	1460	const escaped_stderr = try escapeHtml(allocator, result.stderr);
1327	1461	const colored_stderr = try termColor(allocator, escaped_stderr);
1328		try out.print("\n{s}</code></pre>\n", .{colored_stderr});
	1462	try shell_out.print("\n{s}\n", .{colored_stderr});
1329	1463	},
1330	1464
1331	1465	Code.Id.TestSafety => \|error_match\| {
...	...	@@ -1383,7 +1517,7 @@ fn genHtml(
1383	1517	}
1384	1518	const escaped_stderr = try escapeHtml(allocator, result.stderr);
1385	1519	const colored_stderr = try termColor(allocator, escaped_stderr);
1386		try out.print("<pre><code class=\"shell\">$ zig test {s}.zig {s}\n{s}</code></pre>\n", .{
	1520	try shell_out.print("$ zig test {s}.zig {s}\n{s}\n", .{
1387	1521	code.name,
1388	1522	mode_arg,
1389	1523	colored_stderr,
...	...	@@ -1406,23 +1540,20 @@ fn genHtml(
1406	1540	tmp_dir_name, fs.path.sep, name_plus_obj_ext,
1407	1541	}),
1408	1542	});
1409		if (!code.is_inline) {
1410		try out.print("<pre><code class=\"shell\">$ zig build-obj {s}.zig", .{code.name});
1411		}
	1543
	1544	try shell_out.print("$ zig build-obj {s}.zig ", .{code.name});
1412	1545
1413	1546	switch (code.mode) {
1414	1547	.Debug => {},
1415	1548	else => {
1416	1549	try build_args.appendSlice(&[_][]const u8{ "-O", @tagName(code.mode) });
1417		if (!code.is_inline) {
1418		try out.print(" -O {s}", .{@tagName(code.mode)});
1419		}
	1550	try shell_out.print("-O {s} ", .{@tagName(code.mode)});
1420	1551	},
1421	1552	}
1422	1553
1423	1554	if (code.target_str) \|triple\| {
1424	1555	try build_args.appendSlice(&[_][]const u8{ "-target", triple });
1425		try out.print(" -target {s}", .{triple});
	1556	try shell_out.print("-target {s} ", .{triple});
1426	1557	}
1427	1558
1428	1559	if (maybe_error_match) \|error_match\| {
...	...	@@ -1455,13 +1586,11 @@ fn genHtml(
1455	1586	}
1456	1587	const escaped_stderr = try escapeHtml(allocator, result.stderr);
1457	1588	const colored_stderr = try termColor(allocator, escaped_stderr);
1458		try out.print("\n{s}", .{colored_stderr});
	1589	try shell_out.print("\n{s} ", .{colored_stderr});
1459	1590	} else {
1460	1591	_ = exec(allocator, &env_map, build_args.items) catch return parseError(tokenizer, code.source_token, "example failed to compile", .{});
1461	1592	}
1462		if (!code.is_inline) {
1463		try out.print("</code></pre>\n", .{});
1464		}
	1593	try shell_out.writeAll("\n");
1465	1594	},
1466	1595	Code.Id.Lib => {
1467	1596	const bin_basename = try std.zig.binNameAlloc(allocator, .{
...	...	@@ -1481,36 +1610,41 @@ fn genHtml(
1481	1610	tmp_dir_name, fs.path.sep_str, bin_basename,
1482	1611	}),
1483	1612	});
1484		try out.print("<pre><code class=\"shell\">$ zig build-lib {s}.zig", .{code.name});
	1613	try shell_out.print("$ zig build-lib {s}.zig ", .{code.name});
	1614
1485	1615	switch (code.mode) {
1486	1616	.Debug => {},
1487	1617	else => {
1488	1618	try test_args.appendSlice(&[_][]const u8{ "-O", @tagName(code.mode) });
1489		try out.print(" -O {s}", .{@tagName(code.mode)});
	1619	try shell_out.print("-O {s} ", .{@tagName(code.mode)});
1490	1620	},
1491	1621	}
1492	1622	if (code.target_str) \|triple\| {
1493	1623	try test_args.appendSlice(&[_][]const u8{ "-target", triple });
1494		try out.print(" -target {s}", .{triple});
	1624	try shell_out.print("-target {s} ", .{triple});
1495	1625	}
1496	1626	if (code.link_mode) \|link_mode\| {
1497	1627	switch (link_mode) {
1498	1628	.Static => {
1499	1629	try test_args.append("-static");
1500		try out.print(" -static", .{});
	1630	try shell_out.print("-static ", .{});
1501	1631	},
1502	1632	.Dynamic => {
1503	1633	try test_args.append("-dynamic");
1504		try out.print(" -dynamic", .{});
	1634	try shell_out.print("-dynamic ", .{});
1505	1635	},
1506	1636	}
1507	1637	}
1508	1638	const result = exec(allocator, &env_map, test_args.items) catch return parseError(tokenizer, code.source_token, "test failed", .{});
1509	1639	const escaped_stderr = try escapeHtml(allocator, result.stderr);
1510	1640	const escaped_stdout = try escapeHtml(allocator, result.stdout);
1511		try out.print("\n{s}{s}</code></pre>\n", .{ escaped_stderr, escaped_stdout });
	1641	try shell_out.print("\n{s}{s}\n", .{ escaped_stderr, escaped_stdout });
1512	1642	},
1513	1643	}
	1644
	1645	if (!code.just_check_syntax) {
	1646	try printShell(out, shell_buffer.items);
	1647	}
1514	1648	},
1515	1649	}
1516	1650	}
...	...	@@ -1551,3 +1685,195 @@ fn dumpArgs(args: []const []const u8) void {
1551	1685	else
1552	1686	print("\n", .{});
1553	1687	}
	1688
	1689	test "shell parsed" {
	1690	const test_allocator = std.testing.allocator;
	1691
	1692	{
	1693	const shell_out =
	1694	\\$ zig build test.zig
	1695	;
	1696	const expected =
	1697	\\<figure><figcaption class="shell-cap">Shell</figcaption><pre><samp>$ <kbd>zig build test.zig</kbd>
	1698	\\</samp></pre></figure>
	1699	;
	1700
	1701	var buffer = std.ArrayList(u8).init(test_allocator);
	1702	defer buffer.deinit();
	1703
	1704	try printShell(buffer.writer(), shell_out);
	1705	try testing.expectEqualSlices(u8, expected, buffer.items);
	1706	}
	1707	{
	1708	const shell_out =
	1709	\\$ zig build test.zig
	1710	\\build output
	1711	;
	1712	const expected =
	1713	\\<figure><figcaption class="shell-cap">Shell</figcaption><pre><samp>$ <kbd>zig build test.zig</kbd>
	1714	\\build output
	1715	\\</samp></pre></figure>
	1716	;
	1717
	1718	var buffer = std.ArrayList(u8).init(test_allocator);
	1719	defer buffer.deinit();
	1720
	1721	try printShell(buffer.writer(), shell_out);
	1722	try testing.expectEqualSlices(u8, expected, buffer.items);
	1723	}
	1724	{
	1725	const shell_out =
	1726	\\$ zig build test.zig
	1727	\\build output
	1728	\\$ ./test
	1729	;
	1730	const expected =
	1731	\\<figure><figcaption class="shell-cap">Shell</figcaption><pre><samp>$ <kbd>zig build test.zig</kbd>
	1732	\\build output
	1733	\\$ <kbd>./test</kbd>
	1734	\\</samp></pre></figure>
	1735	;
	1736
	1737	var buffer = std.ArrayList(u8).init(test_allocator);
	1738	defer buffer.deinit();
	1739
	1740	try printShell(buffer.writer(), shell_out);
	1741	try testing.expectEqualSlices(u8, expected, buffer.items);
	1742	}
	1743	{
	1744	const shell_out =
	1745	\\$ zig build test.zig
	1746	\\
	1747	\\$ ./test
	1748	\\output
	1749	;
	1750	const expected =
	1751	\\<figure><figcaption class="shell-cap">Shell</figcaption><pre><samp>$ <kbd>zig build test.zig</kbd>
	1752	\\
	1753	\\$ <kbd>./test</kbd>
	1754	\\output
	1755	\\</samp></pre></figure>
	1756	;
	1757
	1758	var buffer = std.ArrayList(u8).init(test_allocator);
	1759	defer buffer.deinit();
	1760
	1761	try printShell(buffer.writer(), shell_out);
	1762	try testing.expectEqualSlices(u8, expected, buffer.items);
	1763	}
	1764	{
	1765	const shell_out =
	1766	\\$ zig build test.zig
	1767	\\$ ./test
	1768	\\output
	1769	;
	1770	const expected =
	1771	\\<figure><figcaption class="shell-cap">Shell</figcaption><pre><samp>$ <kbd>zig build test.zig</kbd>
	1772	\\$ <kbd>./test</kbd>
	1773	\\output
	1774	\\</samp></pre></figure>
	1775	;
	1776
	1777	var buffer = std.ArrayList(u8).init(test_allocator);
	1778	defer buffer.deinit();
	1779
	1780	try printShell(buffer.writer(), shell_out);
	1781	try testing.expectEqualSlices(u8, expected, buffer.items);
	1782	}
	1783	{
	1784	const shell_out =
	1785	\\$ zig build test.zig \
	1786	\\ --build-option
	1787	\\build output
	1788	\\$ ./test
	1789	\\output
	1790	;
	1791	const expected =
	1792	\\<figure><figcaption class="shell-cap">Shell</figcaption><pre><samp>$ <kbd>zig build test.zig \
	1793	\\ --build-option</kbd>
	1794	\\build output
	1795	\\$ <kbd>./test</kbd>
	1796	\\output
	1797	\\</samp></pre></figure>
	1798	;
	1799
	1800	var buffer = std.ArrayList(u8).init(test_allocator);
	1801	defer buffer.deinit();
	1802
	1803	try printShell(buffer.writer(), shell_out);
	1804	try testing.expectEqualSlices(u8, expected, buffer.items);
	1805	}
	1806	{
	1807	// intentional space after "--build-option1 \"
	1808	const shell_out =
	1809	\\$ zig build test.zig \
	1810	\\ --build-option1 \
	1811	\\ --build-option2
	1812	\\$ ./test
	1813	;
	1814	const expected =
	1815	\\<figure><figcaption class="shell-cap">Shell</figcaption><pre><samp>$ <kbd>zig build test.zig \
	1816	\\ --build-option1 \
	1817	\\ --build-option2</kbd>
	1818	\\$ <kbd>./test</kbd>
	1819	\\</samp></pre></figure>
	1820	;
	1821
	1822	var buffer = std.ArrayList(u8).init(test_allocator);
	1823	defer buffer.deinit();
	1824
	1825	try printShell(buffer.writer(), shell_out);
	1826	try testing.expectEqualSlices(u8, expected, buffer.items);
	1827	}
	1828	{
	1829	const shell_out =
	1830	\\$ zig build test.zig \
	1831	\\$ ./test
	1832	;
	1833	const expected =
	1834	\\<figure><figcaption class="shell-cap">Shell</figcaption><pre><samp>$ <kbd>zig build test.zig \
	1835	\\$ ./test</kbd>
	1836	\\</samp></pre></figure>
	1837	;
	1838
	1839	var buffer = std.ArrayList(u8).init(test_allocator);
	1840	defer buffer.deinit();
	1841
	1842	try printShell(buffer.writer(), shell_out);
	1843	try testing.expectEqualSlices(u8, expected, buffer.items);
	1844	}
	1845	{
	1846	const shell_out =
	1847	\\$ zig build test.zig
	1848	\\$ ./test
	1849	\\$1
	1850	;
	1851	const expected =
	1852	\\<figure><figcaption class="shell-cap">Shell</figcaption><pre><samp>$ <kbd>zig build test.zig</kbd>
	1853	\\$ <kbd>./test</kbd>
	1854	\\$1
	1855	\\</samp></pre></figure>
	1856	;
	1857
	1858	var buffer = std.ArrayList(u8).init(test_allocator);
	1859	defer buffer.deinit();
	1860
	1861	try printShell(buffer.writer(), shell_out);
	1862	try testing.expectEqualSlices(u8, expected, buffer.items);
	1863	}
	1864	{
	1865	const shell_out =
	1866	\\$zig build test.zig
	1867	;
	1868	const expected =
	1869	\\<figure><figcaption class="shell-cap">Shell</figcaption><pre><samp>$zig build test.zig
	1870	\\</samp></pre></figure>
	1871	;
	1872
	1873	var buffer = std.ArrayList(u8).init(test_allocator);
	1874	defer buffer.deinit();
	1875
	1876	try printShell(buffer.writer(), shell_out);
	1877	try testing.expectEqualSlices(u8, expected, buffer.items);
	1878	}
	1879	}

doc/langref.html.in+751-661

...	...	@@ -6,225 +6,312 @@
6	6	<title>Documentation - The Zig Programming Language</title>
7	7	<link rel="icon" href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAgklEQVR4AWMYWuD7EllJIM4G4g4g5oIJ/odhOJ8wToOxSTXgNxDHoeiBMfA4+wGShjyYOCkG/IGqWQziEzYAoUAeiF9D5U+DxEg14DRU7jWIT5IBIOdCxf+A+CQZAAoopEB7QJwBCBwHiip8UYmRdrAlDpIMgApwQZNnNii5Dq0MBgCxxycBnwEd+wAAAABJRU5ErkJggg=="/>
8	8	<style>
	9	:root{
	10	--nav-width: 24em;
	11	--nav-margin-l: 1em;
	12	}
9	13	body{
10	14	font-family: system-ui, -apple-system, Roboto, "Segoe UI", sans-serif;
11	15	margin: 0;
	16	line-height: 1.5;
12	17	}
13		a:not(:hover) {
14		text-decoration: none;
	18	header {
	19	padding: 0 1em;
15	20	}
16		table, th, td {
17		border-collapse: collapse;
18		border: 1px solid grey;
	21	#contents {
	22	max-width: 60em;
	23	margin: auto;
	24	padding: 0 1em;
19	25	}
20		th, td {
21		padding: 0.1em;
	26	#navigation {
	27	padding: 0 1em;
22	28	}
23		.t0_1, .t37, .t37_1 {
	29
	30	@media screen and (min-width: 1025px) {
	31	header {
	32	margin-left: calc(var(--nav-width) + var(--nav-margin-l));
	33	}
	34	header h1 {
	35	margin: auto;
	36	max-width: 30em;
	37	}
	38	#navigation {
	39	overflow: auto;
	40	width: var(--nav-width);
	41	height: 100vh;
	42	position: fixed;
	43	top:0;
	44	left:0;
	45	bottom:0;
	46	padding: unset;
	47	margin-left: var(--nav-margin-l);
	48	}
	49	#navigation nav ul {
	50	padding-left: 1em;
	51	}
	52	#contents-wrapper {
	53	margin-left: calc(var(--nav-width) + var(--nav-margin-l));
	54	}
	55	}
	56
	57	a:hover,a:focus {
	58	background: #fff2a8;
	59	}
	60	dt {
	61	font-weight: bold;
	62	}
	63	table, th, td {
	64	border-collapse: collapse;
	65	border: 1px solid grey;
	66	}
	67	th, td {
	68	padding: 0.1em;
	69	}
	70	th[scope=row] {
	71	text-align: left;
	72	font-weight: normal;
	73	}
	74	.t0_1, .t37, .t37_1 {
	75	font-weight: bold;
	76	}
	77	.t2_0 {
	78	color: #575757;
	79	}
	80	.t31_1 {
	81	color: #b40000;
	82	}
	83	.t32_1 {
	84	color: green;
	85	}
	86	.t36_1 {
	87	color: #005C7A;
	88	}
	89	.file {
	90	font-weight: bold;
	91	border: unset;
	92	}
	93	code {
	94	background: #f8f8f8;
	95	border: 1px dotted silver;
	96	padding-left: 0.3em;
	97	padding-right: 0.3em;
	98	}
	99	pre > code {
	100	display: block;
	101	overflow: auto;
	102	padding: 0.5em;
	103	border: 1px solid #eee;
	104	line-height: normal;
	105	}
	106	samp {
	107	background: #fafafa;
	108	}
	109	pre > samp {
	110	display: block;
	111	overflow: auto;
	112	padding: 0.5em;
	113	border: 1px solid #eee;
	114	line-height: normal;
	115	}
	116	kbd {
	117	font-weight: bold;
	118	}
	119	.table-wrapper {
	120	width: 100%;
	121	overflow-x: auto;
	122	}
	123
	124	.tok-kw {
	125	color: #333;
24	126	font-weight: bold;
	127	}
	128	.tok-str {
	129	color: #d14;
	130	}
	131	.tok-builtin {
	132	color: #005C7A;
	133	}
	134	.tok-comment {
	135	color: #545454;
	136	font-style: italic;
	137	}
	138	.tok-fn {
	139	color: #900;
	140	font-weight: bold;
	141	}
	142	.tok-null {
	143	color: #005C5C;
	144	}
	145	.tok-number {
	146	color: #005C5C;
	147	}
	148	.tok-type {
	149	color: #458;
	150	font-weight: bold;
	151	}
	152
	153	figure {
	154	margin: auto 0;
	155	}
	156	figure pre {
	157	margin-top: 0;
	158	}
	159
	160	figcaption {
	161	padding-left: 0.5em;
	162	font-size: small;
	163	border-top-left-radius: 5px;
	164	border-top-right-radius: 5px;
	165	}
	166	figcaption.zig-cap {
	167	background: #fcdba5;
	168	}
	169	figcaption.c-cap {
	170	background: #a8b9cc;
	171	color: #000;
	172	}
	173	figcaption.javascript-cap {
	174	background: #365d95;
	175	color: #fff;
	176	}
	177	figcaption.shell-cap {
	178	background: #ccc;
	179	color: #000;
	180	}
	181
	182	aside {
	183	border-left: 0.25em solid #f7a41d;
	184	padding: 0 1em 0 1em;
	185	}
	186
	187	h1 a, h2 a, h3 a, h4 a, h5 a {
	188	text-decoration: none;
	189	color: #333;
	190	}
	191
	192	a.hdr {
	193	visibility: hidden;
	194	}
	195	h1:hover > a.hdr, h2:hover > a.hdr, h3:hover > a.hdr, h4:hover > a.hdr, h5:hover > a.hdr {
	196	visibility: visible;
	197	}
	198
	199	@media (prefers-color-scheme: dark) {
	200	body{
	201	background:#121212;
	202	color: #ccc;
	203	}
	204	a {
	205	color: #88f;
	206	}
	207	a:hover,a:focus {
	208	color: #000;
	209	}
	210	table, th, td {
	211	border-color: grey;
25	212	}
26	213	.t2_0 {
27		color: grey;
	214	color: grey;
28	215	}
29	216	.t31_1 {
30		color: red;
	217	color: red;
31	218	}
32	219	.t32_1 {
33		color: green;
	220	color: #00B800;
34	221	}
35	222	.t36_1 {
36		color: #0086b3;
	223	color: #0086b3;
37	224	}
38		.file {
39		text-decoration: underline;
	225	code {
	226	background: #222;
	227	border-color: #444;
40	228	}
41	229	pre > code {
42		display: block;
43		overflow: auto;
44		padding: 0.5em;
45		color: #333;
46		background: #f8f8f8;
47		border: 1px dotted silver;
48		line-height: normal;
	230	color: #ccc;
	231	background: #222;
	232	border: unset;
49	233	}
50		code {
51		background-color: #f8f8f8;
52		border: 1px dotted silver;
53		padding-left: 0.3em;
54		padding-right: 0.3em;
	234	samp {
	235	background: #000;
	236	color: #ccc;
55	237	}
56		.table-wrapper {
57		width: 100%;
58		overflow-y: auto;
	238	pre > samp {
	239	border: unset;
59	240	}
60
61	241	.tok-kw {
62		color: #333;
63		font-weight: bold;
	242	color: #eee;
64	243	}
65	244	.tok-str {
66		color: #d14;
	245	color: #2e5;
67	246	}
68	247	.tok-builtin {
69		color: #0086b3;
	248	color: #ff894c;
70	249	}
71	250	.tok-comment {
72		color: #777;
73		font-style: italic;
	251	color: #aa7;
74	252	}
75	253	.tok-fn {
76		color: #900;
77		font-weight: bold;
	254	color: #B1A0F8;
78	255	}
79	256	.tok-null {
80		color: #008080;
	257	color: #ff8080;
81	258	}
82	259	.tok-number {
83		color: #008080;
	260	color: #ff8080;
84	261	}
85	262	.tok-type {
86		color: #458;
87		font-weight: bold;
88		}
89
90		#main-wrapper {
91		display: flex;
92		flex-direction: column;
93		}
94
95		#contents-wrapper {
96		flex-grow: 1;
97		padding: 0 2em;
	263	color: #68f;
98	264	}
99
100		#contents {
101		max-width: 60em;
102		margin: auto;
103		line-height: 1.5;
104		}
105
106		#toc {
107		padding: 0 1em;
108		}
109
110		@media screen and (min-width: 1025px) {
111		#main-wrapper {
112		flex-direction: row;
113		}
114		#toc {
115		height: 100vh;
116		position: sticky;
117		top: 0;
118		}
119		#contents-wrapper, #toc {
120		overflow: auto;
121		}
122		}
123
124	265	h1 a, h2 a, h3 a, h4 a, h5 a {
125		text-decoration: none;
126		color: #333;
	266	color: #aaa;
127	267	}
128
129		a.hdr {
130		visibility: hidden;
131		}
132		h1:hover > a.hdr, h2:hover > a.hdr, h3:hover > a.hdr, h4:hover > a.hdr, h5:hover > a.hdr {
133		visibility: visible;
	268	figcaption.zig-cap {
	269	background-color: #b27306;
	270	color: #000;
134	271	}
135
136		@media (prefers-color-scheme: dark) {
137		body{
138		background-color:#111;
139		color: #bbb;
140		}
141		a {
142		color: #f7a31d;
143		}
144		table, th, td {
145		border-color: grey;
146		}
147		.t2_0 {
148		color: grey;
149		}
150		.t31_1 {
151		color: red;
152		}
153		.t32_1 {
154		color: green;
155		}
156		.t36_1 {
157		color: #0086b3;
158		}
159		pre > code {
160		color: #ccc;
161		background: #222;
162		border-color: #444;
163		}
164		code {
165		background-color: #222;
166		border-color: #444;
167		}
168		.tok-kw {
169		color: #eee;
170		}
171		.tok-str {
172		color: #2e5;
173		}
174		.tok-builtin {
175		color: #ff894c;
176		}
177		.tok-comment {
178		color: #aa7;
179		}
180		.tok-fn {
181		color: #e33;
182		}
183		.tok-null {
184		color: #ff8080;
185		}
186		.tok-number {
187		color: #ff8080;
188		}
189		.tok-type {
190		color: #68f;
191		}
192		h1 a, h2 a, h3 a, h4 a, h5 a {
193		color: #aaa;
194		}
	272	figcaption.shell-cap {
	273	background: #2a2a2a;
	274	color: #fff;
195	275	}
196		</style>
197		</head>
198		<body>
199		<div id="main-wrapper">
200		<div id="toc">
201		<a href="https://ziglang.org/documentation/0.1.1/">0.1.1</a> \|
202		<a href="https://ziglang.org/documentation/0.2.0/">0.2.0</a> \|
203		<a href="https://ziglang.org/documentation/0.3.0/">0.3.0</a> \|
204		<a href="https://ziglang.org/documentation/0.4.0/">0.4.0</a> \|
205		<a href="https://ziglang.org/documentation/0.5.0/">0.5.0</a> \|
206		<a href="https://ziglang.org/documentation/0.6.0/">0.6.0</a> \|
207		<a href="https://ziglang.org/documentation/0.7.1/">0.7.1</a> \|
208		<a href="https://ziglang.org/documentation/0.8.1/">0.8.1</a> \|
209		master
210		<h1>Contents</h1>
211		{#nav#}
	276	}
	277	</style>
	278	</head>
	279	<body>
	280	<header><h1>Zig Language Reference</h1></header>
	281	<div id="main-wrapper">
	282	<div id="navigation">
	283	<nav aria-labelledby="zig-version">
	284	<h2 id="zig-version">Zig Version</h2>
	285	<a href="https://ziglang.org/documentation/0.1.1/">0.1.1</a> \|
	286	<a href="https://ziglang.org/documentation/0.2.0/">0.2.0</a> \|
	287	<a href="https://ziglang.org/documentation/0.3.0/">0.3.0</a> \|
	288	<a href="https://ziglang.org/documentation/0.4.0/">0.4.0</a> \|
	289	<a href="https://ziglang.org/documentation/0.5.0/">0.5.0</a> \|
	290	<a href="https://ziglang.org/documentation/0.6.0/">0.6.0</a> \|
	291	<a href="https://ziglang.org/documentation/0.7.1/">0.7.1</a> \|
	292	<a href="https://ziglang.org/documentation/0.8.1/">0.8.1</a> \|
	293	master
	294	</nav>
	295	<nav aria-labelledby="table-of-contents">
	296	<h2 id="table-of-contents">Table of Contents</h2>
	297	{#nav#}
	298	</nav>
212	299	</div>
213		<div id="contents-wrapper"><div id="contents">
	300	<div id="contents-wrapper"><main id="contents">
214	301	{#header_open\|Introduction#}
215	302	<p>
216		Zig is a general-purpose programming language and toolchain for maintaining
	303	<a href="https://ziglang.org">Zig</a> is a general-purpose programming language and toolchain for maintaining
217	304	<strong>robust</strong>, <strong>optimal</strong>, and <strong>reusable</strong> software.
218	305	</p>
219		<ul>
220		<li><strong>Robust</strong> - behavior is correct even for edge cases such as out of memory.</li>
221		<li><strong>Optimal</strong> - write programs the best way they can behave and perform.</li>
222		<li><strong>Reusable</strong> - the same code works in many environments which have different
223		constraints.</li>
224		<li><strong>Maintainable</strong> - precisely communicate intent to the compiler and
	306	<dl>
	307	<dt>Robust</dt><dd>Behavior is correct even for edge cases such as out of memory.</dd>
	308	<dt>Optimal</dt><dd>Write programs the best way they can behave and perform.</dd>
	309	<dt>Reusable</dt><dd>The same code works in many environments which have different
	310	constraints.</dd>
	311	<dt>Maintainable</dt><dd>Precisely communicate intent to the compiler and
225	312	other programmers. The language imposes a low overhead to reading code and is
226		resilient to changing requirements and environments.</li>
227		</ul>
	313	resilient to changing requirements and environments.</dd>
	314	</dl>
228	315	<p>
229	316	Often the most efficient way to learn something new is to see examples, so
230	317	this documentation shows how to use each of Zig's features. It is
...	...	@@ -236,8 +323,16 @@
236	323	<p>
237	324	This HTML document depends on no external files, so you can use it offline.
238	325	</p>
	326	{#header_close#}
	327
	328	{#header_open\|Zig Standard Library#}
	329	<p>
	330	The <a href="https://ziglang.org/documentation/master/std/">Zig Standard Library</a> has its own documentation.
	331	</p>
239	332	<p>
240		<a href="https://github.com/ziglang/zig/wiki/FAQ#where-is-the-documentation-for-the-zig-standard-library">Where is the documentation for the Zig standard library?</a>
	333	Zig's Standard Library contains commonly used algorithms, data structures, and definitions to help you build programs or libraries.
	334	You will see many examples of Zig's Standard Library used in this documentation. To learn more about the Zig Standard Library,
	335	visit the link above.
241	336	</p>
242	337	{#header_close#}
243	338
...	...	@@ -252,96 +347,102 @@ pub fn main() !void {
252	347	}
253	348	{#code_end#}
254	349	<p>
255		The Zig code sample above demonstrates one way to create a program that will output <code>Hello, world!</code>.
	350	The Zig code sample above demonstrates one way to create a program that will output: <samp>Hello, world!</samp>.
256	351	</p>
257	352	<p>
258		The code sample shows the contents of a file named <code>hello.zig</code>. Files storing Zig
	353	The code sample shows the contents of a file named <code class="file">hello.zig</code>. Files storing Zig
259	354	source code are {#link\|UTF-8 encoded\|Source Encoding#} text files. The files storing
260		Zig source code are usually named with the <code>.zig</code> extension.
	355	Zig source code are usually named with the <code class="file"><em>.zig</em></code> extension.
261	356	</p>
262	357	<p>
263		Following the <code>hello.zig</code> Zig code sample, the {#link\|Zig Build System#} is used
264		to build an executable program from the <code>hello.zig</code> source code. Then, the
265		<code>hello</code> program is executed showing its output <code>Hello, world!</code>. The
266		lines beginning with <code>$</code> represent command line prompts and a command.
	358	Following the <code class="file">hello.zig</code> Zig code sample, the {#link\|Zig Build System#} is used
	359	to build an executable program from the <code class="file">hello.zig</code> source code. Then, the
	360	<code class="file">hello</code> program is executed showing its output <samp>Hello, world!</samp>. The
	361	lines beginning with <samp>$</samp> represent command line prompts and a command.
267	362	Everything else is program output.
268	363	</p>
269	364	<p>
270		The code sample begins by adding Zig's Standard Library to the build using the {#link\|@import#} builtin function.
271		The {#syntax#}@import("std"){#endsyntax#} function call creates a structure to represent the Standard Library.
	365	The code sample begins by adding the {#link\|Zig Standard Library#} to the build using the {#link\|@import#} builtin function.
	366	The {#syntax#}@import("std"){#endsyntax#} function call creates a structure that represents the Zig Standard Library.
272	367	The code then {#link\|declares\|Container Level Variables#} a
273		{#link\|constant identifier\|Assignment#}, named <code>std</code>, for easy access to
274		<a href="https://github.com/ziglang/zig/wiki/FAQ#where-is-the-documentation-for-the-zig-standard-library">Zig's standard library</a>.
	368	{#link\|constant identifier\|Assignment#}, named {#syntax#}std{#endsyntax#}, that gives access the features of the Zig Standard Library.
275	369	</p>
276	370	<p>
277		Next, a {#link\|public function\|Functions#}, {#syntax#}pub fn{#endsyntax#}, named <code>main</code>
278		is declared. The <code>main</code> function is necessary because it tells the Zig compiler where the start of
	371	Next, a {#link\|public function\|Functions#}, {#syntax#}pub fn{#endsyntax#}, named {#syntax#}main{#endsyntax#}
	372	is declared. The {#syntax#}main{#endsyntax#} function is necessary because it tells the Zig compiler where the start of
279	373	the program exists. Programs designed to be executed will need a {#syntax#}pub fn main{#endsyntax#} function.
280		For more advanced use cases, Zig offers other features to inform the compiler where the start of
281		the program exists. Libraries, on the other hand, do not need a <code>main</code> function because
282		library code is usually called by other programs.
283	374	</p>
	375	<aside role="note" aria-label="Note about main function">
	376	<p>
	377	For more advanced use cases, Zig offers other features to inform the compiler where the start of
	378	the program exists. Also, libraries do not need a {#syntax#}pub fn main{#endsyntax#} function because
	379	library code is called by other programs or libraries.
	380	</p>
	381	</aside>
284	382	<p>
285	383	A function is a block of any number of statements and expressions that, as a whole, perform a task.
286	384	Functions may or may not return data after they are done performing their task. If a function
287	385	cannot perform its task, it might return an error. Zig makes all of this explicit.
288	386	</p>
289	387	<p>
290		In the <code>hello.zig</code> code sample, the <code>main</code> function is declared
	388	In the <code class="file">hello.zig</code> code sample, the <code>main</code> function is declared
291	389	with the {#syntax#}!void{#endsyntax#} return type. This return type is known as an {#link\|Error Union Type#}.
292	390	This syntax tells the Zig compiler that the function will either return an
293		error or a value. An error union type combines an {#link\|Error Set Type#} and a {#link\|Primitive Type\|Primitive Types#}.
	391	error or a value. An error union type combines an {#link\|Error Set Type#} and any other data type
	392	(e.g. a {#link\|Primitive Type\|Primitive Types#} or a user-defined type such as a {#link\|struct#}, {#link\|enum#}, or {#link\|union#}).
294	393	The full form of an error union type is
295		<code><error set type></code>{#syntax#}!{#endsyntax#}<code><primitive type></code>. In the code
	394	<code><error set type></code>{#syntax#}!{#endsyntax#}<code><any data type></code>. In the code
296	395	sample, the error set type is not explicitly written on the left side of the {#syntax#}!{#endsyntax#} operator.
297		When written this way, the error set type is a special kind of error union type that has an
298		{#link\|inferred error set type\|Inferred Error Sets#}. The {#syntax#}void{#endsyntax#} after the {#syntax#}!{#endsyntax#} operator
299		tells the compiler that the function will not return a value under normal circumstances (i.e. no errors occur).
300		</p>
301		<p>
302		Note to experienced programmers: Zig also has the boolean {#link\|operator\|Operators#} {#syntax#}!a{#endsyntax#}
303		where {#syntax#}a{#endsyntax#} is a value of type {#syntax#}bool{#endsyntax#}. Error union types contain the
304		name of the type in the syntax: {#syntax#}!{#endsyntax#}<code><primitive type></code>.
	396	When written this way, the error set type is an {#link\|inferred error set type\|Inferred Error Sets#}. The
	397	{#syntax#}void{#endsyntax#} after the {#syntax#}!{#endsyntax#} operator
	398	tells the compiler that the function will not return a value under normal circumstances (i.e. when no errors occur).
305	399	</p>
	400	<aside role="note" aria-label="Note to disambiguate exclamation mark operator">
	401	<p>
	402	Note to experienced programmers: Zig also has the boolean {#link\|operator\|Operators#} {#syntax#}!a{#endsyntax#}
	403	where {#syntax#}a{#endsyntax#} is a value of type {#syntax#}bool{#endsyntax#}. Error union types contain the
	404	name of the type in the syntax: {#syntax#}!{#endsyntax#}<code><any data type></code>.
	405	</p>
	406	</aside>
306	407	<p>
307		In Zig, a function's block of statements and expressions are surrounded by <code>{</code> and
308		<code>}</code> curly-braces. Inside of the <code>main</code> function are expressions that perform
309		the task of outputting <code>Hello, world!</code> to standard output.
	408	In Zig, a function's block of statements and expressions are surrounded by an open curly-brace <code>{</code> and
	409	close curly-brace <code>}</code>. Inside of the {#syntax#}main{#endsyntax#} function are expressions that perform
	410	the task of outputting <samp>Hello, world!</samp> to standard output.
310	411	</p>
311	412	<p>
312		First, a constant identifier, <code>stdout</code>, is initialized to represent standard output's
313		writer. Then, the program tries to print the <code>Hello, world!</code>
	413	First, a constant identifier, {#syntax#}stdout{#endsyntax#}, is initialized to represent standard output's
	414	writer. Then, the program tries to print the <samp>Hello, world!</samp>
314	415	message to standard output.
315	416	</p>
316	417	<p>
317	418	Functions sometimes need information to perform their task. In Zig, information is passed
318		to functions between open <code>(</code> and close <code>)</code> parenthesis placed after
	419	to functions between an open parenthesis {#syntax#}({#endsyntax#} and a close parenthesis {#syntax#}){#endsyntax#} placed after
319	420	the function's name. This information is also known as arguments. When there are
320		multiple arguments passed to a function, they are separated by commas <code>,</code>.
	421	multiple arguments passed to a function, they are separated by commas {#syntax#},{#endsyntax#}.
321	422	</p>
322	423	<p>
323		The two arguments passed to the <code>stdout.print()</code> function, <code>"Hello, {s}!\n"</code>
324		and <code>.{"world"}</code>, are evaluated at {#link\|compile-time\|comptime#}. The code sample is
	424	The two arguments passed to the {#syntax#}stdout.print(){#endsyntax#} function, {#syntax#}"Hello, {s}!\n"{#endsyntax#}
	425	and {#syntax#}.{"world"}{#endsyntax#}, are evaluated at {#link\|compile-time\|comptime#}. The code sample is
325	426	purposely written to show how to perform {#link\|string\|String Literals and Unicode Code Point Literals#}
326		substitution in the <code>print</code> function. The curly-braces inside of the first argument
	427	substitution in the {#syntax#}print{#endsyntax#} function. The curly-braces inside of the first argument
327	428	are substituted with the compile-time known value inside of the second argument
328	429	(known as an {#link\|anonymous struct literal\|Anonymous Struct Literals#}). The <code>\n</code>
329	430	inside of the double-quotes of the first argument is the {#link\|escape sequence\|Escape Sequences#} for the
330		newline character. The {#link\|try#} expression evaluates the result of <code>stdout.print</code>.
	431	newline character. The {#link\|try#} expression evaluates the result of {#syntax#}stdout.print{#endsyntax#}.
331	432	If the result is an error, then the {#syntax#}try{#endsyntax#} expression will return from
332		<code>main</code> with the error. Otherwise, the program will continue. In this case, there are no
333		more statements or expressions left to execute in the <code>main</code> function, so the program exits.
	433	{#syntax#}main{#endsyntax#} with the error. Otherwise, the program will continue. In this case, there are no
	434	more statements or expressions left to execute in the {#syntax#}main{#endsyntax#} function, so the program exits.
334	435	</p>
335	436	<p>
336		In Zig, the standard output writer's <code>print</code> function is allowed to fail because
	437	In Zig, the standard output writer's {#syntax#}print{#endsyntax#} function is allowed to fail because
337	438	it is actually a function defined as part of a generic Writer. Consider a generic Writer that
338	439	represents writing data to a file. When the disk is full, a write to the file will fail.
339	440	However, we typically do not expect writing text to the standard output to fail. To avoid having
340	441	to handle the failure case of printing to standard output, you can use alternate functions: the
341		functions in <code>std.log</code> for proper logging or the <code>std.debug.print</code> function.
	442	functions in {#syntax#}std.log{#endsyntax#} for proper logging or the {#syntax#}std.debug.print{#endsyntax#} function.
342	443	This documentation will use the latter option to print to standard error (stderr) and silently return
343		on failure. The next code sample, <code>hello_again.zig</code> demonstrates the use of
344		<code>std.debug.print</code>.
	444	on failure. The next code sample, <code class="file">hello_again.zig</code> demonstrates the use of
	445	{#syntax#}std.debug.print{#endsyntax#}.
345	446	</p>
346	447	{#code_begin\|exe\|hello_again#}
347	448	const print = @import("std").debug.print;
...	...	@@ -351,13 +452,13 @@ pub fn main() void {
351	452	}
352	453	{#code_end#}
353	454	<p>
354		Note that you can leave off the {#syntax#}!{#endsyntax#} from the return type because <code>std.debug.print</code> cannot fail.
	455	Note that you can leave off the {#syntax#}!{#endsyntax#} from the return type because {#syntax#}std.debug.print{#endsyntax#} cannot fail.
355	456	</p>
356	457	{#see_also\|Values\|@import\|Errors\|Root Source File\|Source Encoding#}
357	458	{#header_close#}
358	459	{#header_open\|Zig Test#}
359	460	<p>
360		<code>zig test</code> is a tool that can be used to quickly build and run Zig code
	461	<kbd>zig test</kbd> is a tool that can be used to quickly build and run Zig code
361	462	to make sure behavior meets expectations. {#syntax#}@import("builtin").is_test{#endsyntax#}
362	463	is available for code to detect whether the current build is a test build.
363	464	</p>
...	...	@@ -387,7 +488,7 @@ test "unused function" { }
387	488	undefined behavior. The implementation of {#syntax#}std.debug.assert{#endsyntax#} is as
388	489	simple as:
389	490	</p>
390		{#code_begin\|syntax#}
	491	{#code_begin\|syntax\|assert#}
391	492	pub fn assert(ok: bool) void {
392	493	if (!ok) unreachable;
393	494	}
...	...	@@ -396,7 +497,7 @@ pub fn assert(ok: bool) void {
396	497	This means that when testing in ReleaseFast or ReleaseSmall mode, {#syntax#}assert{#endsyntax#}
397	498	is not sufficient to check the result of a computation:
398	499	</p>
399		{#code_begin\|syntax#}
	500	{#code_begin\|syntax\|assert_release_fast_mode#}
400	501	const std = @import("std");
401	502	const assert = std.debug.assert;
402	503
...	...	@@ -423,14 +524,13 @@ test "expect in release fast mode" {
423	524	{#code_end#}
424	525	<p>See the rest of the {#syntax#}std.testing{#endsyntax#} namespace for more available functions.</p>
425	526	<p>
426		<code>zig test</code> has a few command line parameters which affect the compilation. See
427		<code>zig --help</code> for a full list. The most interesting one is <code>--test-filter [text]</code>.
	527	<kbd>zig test</kbd> has a few command line parameters which affect the compilation. See
	528	<kbd>zig --help</kbd> for a full list. The most interesting one is <kbd>--test-filter [text]</kbd>.
428	529	This makes the test build only include tests whose name contains the supplied filter text.
429	530	Again, thanks to lazy analysis, this can allow you to narrow a build to only a few functions in
430	531	isolation.
431	532	</p>
432	533	{#header_close#}
433
434	534	{#header_open\|Comments#}
435	535	{#code_begin\|test\|comments#}
436	536	const expect = @import("std").testing.expect;
...	...	@@ -555,184 +655,183 @@ pub fn main() void {
555	655	{#header_open\|Primitive Types#}
556	656	<div class="table-wrapper">
557	657	<table>
558		<tr>
559		<th>
560		Name
561		</th>
562		<th>
563		C Equivalent
564		</th>
565		<th>
566		Description
567		</th>
	658	<caption>Primitive Types</caption>
	659	<thead>
	660	<tr>
	661	<th scope="col">Type</th>
	662	<th scope="col">C Equivalent</th>
	663	<th scope="col">Description</th>
568	664	</tr>
	665	</thead>
	666	<tbody>
569	667	<tr>
570		<td>{#syntax#}i8{#endsyntax#}</td>
	668	<th scope="row">{#syntax#}i8{#endsyntax#}</th>
571	669	<td><code class="c">int8_t</code></td>
572	670	<td>signed 8-bit integer</td>
573	671	</tr>
574	672	<tr>
575		<td>{#syntax#}u8{#endsyntax#}</td>
	673	<th scope="row">{#syntax#}u8{#endsyntax#}</th>
576	674	<td><code class="c">uint8_t</code></td>
577	675	<td>unsigned 8-bit integer</td>
578	676	</tr>
579	677	<tr>
580		<td>{#syntax#}i16{#endsyntax#}</td>
	678	<th scope="row">{#syntax#}i16{#endsyntax#}</th>
581	679	<td><code class="c">int16_t</code></td>
582	680	<td>signed 16-bit integer</td>
583	681	</tr>
584	682	<tr>
585		<td>{#syntax#}u16{#endsyntax#}</td>
	683	<th scope="row">{#syntax#}u16{#endsyntax#}</th>
586	684	<td><code class="c">uint16_t</code></td>
587	685	<td>unsigned 16-bit integer</td>
588	686	</tr>
589	687	<tr>
590		<td>{#syntax#}i32{#endsyntax#}</td>
	688	<th scope="row">{#syntax#}i32{#endsyntax#}</th>
591	689	<td><code class="c">int32_t</code></td>
592	690	<td>signed 32-bit integer</td>
593	691	</tr>
594	692	<tr>
595		<td>{#syntax#}u32{#endsyntax#}</td>
	693	<th scope="row">{#syntax#}u32{#endsyntax#}</th>
596	694	<td><code class="c">uint32_t</code></td>
597	695	<td>unsigned 32-bit integer</td>
598	696	</tr>
599	697	<tr>
600		<td>{#syntax#}i64{#endsyntax#}</td>
	698	<th scope="row">{#syntax#}i64{#endsyntax#}</th>
601	699	<td><code class="c">int64_t</code></td>
602	700	<td>signed 64-bit integer</td>
603	701	</tr>
604	702	<tr>
605		<td>{#syntax#}u64{#endsyntax#}</td>
	703	<th scope="row">{#syntax#}u64{#endsyntax#}</th>
606	704	<td><code class="c">uint64_t</code></td>
607	705	<td>unsigned 64-bit integer</td>
608	706	</tr>
609	707	<tr>
610		<td>{#syntax#}i128{#endsyntax#}</td>
	708	<th scope="row">{#syntax#}i128{#endsyntax#}</th>
611	709	<td><code class="c">__int128</code></td>
612	710	<td>signed 128-bit integer</td>
613	711	</tr>
614	712	<tr>
615		<td>{#syntax#}u128{#endsyntax#}</td>
	713	<th scope="row">{#syntax#}u128{#endsyntax#}</th>
616	714	<td><code class="c">unsigned __int128</code></td>
617	715	<td>unsigned 128-bit integer</td>
618	716	</tr>
619	717	<tr>
620		<td>{#syntax#}isize{#endsyntax#}</td>
	718	<th scope="row">{#syntax#}isize{#endsyntax#}</th>
621	719	<td><code class="c">intptr_t</code></td>
622	720	<td>signed pointer sized integer</td>
623	721	</tr>
624	722	<tr>
625		<td>{#syntax#}usize{#endsyntax#}</td>
	723	<th scope="row">{#syntax#}usize{#endsyntax#}</th>
626	724	<td><code class="c">uintptr_t</code></td>
627	725	<td>unsigned pointer sized integer</td>
628	726	</tr>
629	727
630	728	<tr>
631		<td>{#syntax#}c_short{#endsyntax#}</td>
	729	<th scope="row">{#syntax#}c_short{#endsyntax#}</th>
632	730	<td><code class="c">short</code></td>
633	731	<td>for ABI compatibility with C</td>
634	732	</tr>
635	733	<tr>
636		<td>{#syntax#}c_ushort{#endsyntax#}</td>
	734	<th scope="row">{#syntax#}c_ushort{#endsyntax#}</th>
637	735	<td><code class="c">unsigned short</code></td>
638	736	<td>for ABI compatibility with C</td>
639	737	</tr>
640	738	<tr>
641		<td>{#syntax#}c_int{#endsyntax#}</td>
	739	<th scope="row">{#syntax#}c_int{#endsyntax#}</th>
642	740	<td><code class="c">int</code></td>
643	741	<td>for ABI compatibility with C</td>
644	742	</tr>
645	743	<tr>
646		<td>{#syntax#}c_uint{#endsyntax#}</td>
	744	<th scope="row">{#syntax#}c_uint{#endsyntax#}</th>
647	745	<td><code class="c">unsigned int</code></td>
648	746	<td>for ABI compatibility with C</td>
649	747	</tr>
650	748	<tr>
651		<td>{#syntax#}c_long{#endsyntax#}</td>
	749	<th scope="row">{#syntax#}c_long{#endsyntax#}</th>
652	750	<td><code class="c">long</code></td>
653	751	<td>for ABI compatibility with C</td>
654	752	</tr>
655	753	<tr>
656		<td>{#syntax#}c_ulong{#endsyntax#}</td>
	754	<th scope="row">{#syntax#}c_ulong{#endsyntax#}</th>
657	755	<td><code class="c">unsigned long</code></td>
658	756	<td>for ABI compatibility with C</td>
659	757	</tr>
660	758	<tr>
661		<td>{#syntax#}c_longlong{#endsyntax#}</td>
	759	<th scope="row">{#syntax#}c_longlong{#endsyntax#}</th>
662	760	<td><code class="c">long long</code></td>
663	761	<td>for ABI compatibility with C</td>
664	762	</tr>
665	763	<tr>
666		<td>{#syntax#}c_ulonglong{#endsyntax#}</td>
	764	<th scope="row">{#syntax#}c_ulonglong{#endsyntax#}</th>
667	765	<td><code class="c">unsigned long long</code></td>
668	766	<td>for ABI compatibility with C</td>
669	767	</tr>
670	768	<tr>
671		<td>{#syntax#}c_longdouble{#endsyntax#}</td>
	769	<th scope="row">{#syntax#}c_longdouble{#endsyntax#}</th>
672	770	<td><code class="c">long double</code></td>
673	771	<td>for ABI compatibility with C</td>
674	772	</tr>
675	773	<tr>
676		<td>{#syntax#}c_void{#endsyntax#}</td>
	774	<th scope="row">{#syntax#}c_void{#endsyntax#}</th>
677	775	<td><code class="c">void</code></td>
678	776	<td>for ABI compatibility with C</td>
679	777	</tr>
680	778
681	779	<tr>
682		<td>{#syntax#}f16{#endsyntax#}</td>
	780	<th scope="row">{#syntax#}f16{#endsyntax#}</th>
683	781	<td><code class="c">_Float16</code></td>
684	782	<td>16-bit floating point (10-bit mantissa) IEEE-754-2008 binary16</td>
685	783	</tr>
686	784	<tr>
687		<td>{#syntax#}f32{#endsyntax#}</td>
	785	<th scope="row">{#syntax#}f32{#endsyntax#}</th>
688	786	<td><code class="c">float</code></td>
689	787	<td>32-bit floating point (23-bit mantissa) IEEE-754-2008 binary32</td>
690	788	</tr>
691	789	<tr>
692		<td>{#syntax#}f64{#endsyntax#}</td>
	790	<th scope="row">{#syntax#}f64{#endsyntax#}</th>
693	791	<td><code class="c">double</code></td>
694	792	<td>64-bit floating point (52-bit mantissa) IEEE-754-2008 binary64</td>
695	793	</tr>
696	794	<tr>
697		<td>{#syntax#}f128{#endsyntax#}</td>
	795	<th scope="row">{#syntax#}f128{#endsyntax#}</th>
698	796	<td><code class="c">_Float128</code></td>
699	797	<td>128-bit floating point (112-bit mantissa) IEEE-754-2008 binary128</td>
700	798	</tr>
701	799	<tr>
702		<td>{#syntax#}bool{#endsyntax#}</td>
	800	<th scope="row">{#syntax#}bool{#endsyntax#}</th>
703	801	<td><code class="c">bool</code></td>
704	802	<td>{#syntax#}true{#endsyntax#} or {#syntax#}false{#endsyntax#}</td>
705	803	</tr>
706	804	<tr>
707		<td>{#syntax#}void{#endsyntax#}</td>
	805	<th scope="row">{#syntax#}void{#endsyntax#}</th>
708	806	<td>(none)</td>
709	807	<td>0 bit type</td>
710	808	</tr>
711	809	<tr>
712		<td>{#syntax#}noreturn{#endsyntax#}</td>
	810	<th scope="row">{#syntax#}noreturn{#endsyntax#}</th>
713	811	<td>(none)</td>
714	812	<td>the type of {#syntax#}break{#endsyntax#}, {#syntax#}continue{#endsyntax#}, {#syntax#}return{#endsyntax#}, {#syntax#}unreachable{#endsyntax#}, and {#syntax#}while (true) {}{#endsyntax#}</td>
715	813	</tr>
716	814	<tr>
717		<td>{#syntax#}type{#endsyntax#}</td>
	815	<th scope="row">{#syntax#}type{#endsyntax#}</th>
718	816	<td>(none)</td>
719	817	<td>the type of types</td>
720	818	</tr>
721	819	<tr>
722		<td>{#syntax#}anyerror{#endsyntax#}</td>
	820	<th scope="row">{#syntax#}anyerror{#endsyntax#}</th>
723	821	<td>(none)</td>
724	822	<td>an error code</td>
725	823	</tr>
726	824	<tr>
727		<td>{#syntax#}comptime_int{#endsyntax#}</td>
	825	<th scope="row">{#syntax#}comptime_int{#endsyntax#}</th>
728	826	<td>(none)</td>
729	827	<td>Only allowed for {#link\|comptime#}-known values. The type of integer literals.</td>
730	828	</tr>
731	829	<tr>
732		<td>{#syntax#}comptime_float{#endsyntax#}</td>
	830	<th scope="row">{#syntax#}comptime_float{#endsyntax#}</th>
733	831	<td>(none)</td>
734	832	<td>Only allowed for {#link\|comptime#}-known values. The type of float literals.</td>
735	833	</tr>
	834	</tbody>
736	835	</table>
737	836	</div>
738	837	<p>
...	...	@@ -746,26 +845,27 @@ pub fn main() void {
746	845	{#header_open\|Primitive Values#}
747	846	<div class="table-wrapper">
748	847	<table>
	848	<caption>Primitive Values</caption>
	849	<thead>
749	850	<tr>
750		<th>
751		Name
752		</th>
753		<th>
754		Description
755		</th>
	851	<th scope="col">Name</th>
	852	<th scope="col">Description</th>
756	853	</tr>
	854	</thead>
	855	<tbody>
757	856	<tr>
758		<td>{#syntax#}true{#endsyntax#} and {#syntax#}false{#endsyntax#}</td>
	857	<th scope="row">{#syntax#}true{#endsyntax#} and {#syntax#}false{#endsyntax#}</th>
759	858	<td>{#syntax#}bool{#endsyntax#} values</td>
760	859	</tr>
761	860	<tr>
762		<td>{#syntax#}null{#endsyntax#}</td>
	861	<th scope="row">{#syntax#}null{#endsyntax#}</th>
763	862	<td>used to set an optional type to {#syntax#}null{#endsyntax#}</td>
764	863	</tr>
765	864	<tr>
766		<td>{#syntax#}undefined{#endsyntax#}</td>
	865	<th scope="row">{#syntax#}undefined{#endsyntax#}</th>
767	866	<td>used to leave a value unspecified</td>
768	867	</tr>
	868	</tbody>
769	869	</table>
770	870	</div>
771	871	{#see_also\|Optionals\|undefined#}
...	...	@@ -796,7 +896,7 @@ pub fn main() void {
796	896	in recent versions of the Unicode specification (as of Unicode 13.0).
797	897	In Zig, a Unicode code point literal corresponds to the Unicode definition of a code point.
798	898	</p>
799		{#code_begin\|test#}
	899	{#code_begin\|test\|string_literals_test#}
800	900	const expect = @import("std").testing.expect;
801	901	const mem = @import("std").mem;
802	902
...	...	@@ -817,46 +917,47 @@ test "string literals" {
817	917	{#header_open\|Escape Sequences#}
818	918	<div class="table-wrapper">
819	919	<table>
	920	<caption>Escape Sequences</caption>
	921	<thead>
820	922	<tr>
821		<th>
822		Escape Sequence
823		</th>
824		<th>
825		Name
826		</th>
	923	<th scope="col">Escape Sequence</th>
	924	<th scope="col">Name</th>
827	925	</tr>
	926	</thead>
	927	<tbody>
828	928	<tr>
829		<td><code>\n</code></td>
	929	<th scope="row"><code>\n</code></th>
830	930	<td>Newline</td>
831	931	</tr>
832	932	<tr>
833		<td><code>\r</code></td>
	933	<th scope="row"><code>\r</code></th>
834	934	<td>Carriage Return</td>
835	935	</tr>
836	936	<tr>
837		<td><code>\t</code></td>
	937	<th scope="row"><code>\t</code></th>
838	938	<td>Tab</td>
839	939	</tr>
840	940	<tr>
841		<td><code>\\</code></td>
	941	<th scope="row"><code>\\</code></th>
842	942	<td>Backslash</td>
843	943	</tr>
844	944	<tr>
845		<td><code>\'</code></td>
	945	<th scope="row"><code>\'</code></th>
846	946	<td>Single Quote</td>
847	947	</tr>
848	948	<tr>
849		<td><code>\"</code></td>
	949	<th scope="row"><code>\"</code></th>
850	950	<td>Double Quote</td>
851	951	</tr>
852	952	<tr>
853		<td><code>\xNN</code></td>
	953	<th scope="row"><code>\xNN</code></th>
854	954	<td>hexadecimal 8-bit byte value (2 digits)</td>
855	955	</tr>
856	956	<tr>
857		<td><code>\u{NNNNNN}</code></td>
	957	<th scope="row"><code>\u{NNNNNN}</code></th>
858	958	<td>hexadecimal Unicode code point UTF-8 encoded (1 or more digits)</td>
859	959	</tr>
	960	</tbody>
860	961	</table>
861	962	</div>
862	963	<p>Note that the maximum valid Unicode point is {#syntax#}0x10ffff{#endsyntax#}.</p>
...	...	@@ -870,7 +971,7 @@ test "string literals" {
870	971	However, if the next line begins with {#syntax#}\\{#endsyntax#} then a newline is appended and
871	972	the string literal continues.
872	973	</p>
873		{#code_begin\|syntax#}
	974	{#code_begin\|syntax\|multiline_string_literals#}
874	975	const hello_world_in_c =
875	976	\\#include <stdio.h>
876	977	\\
...	...	@@ -902,7 +1003,7 @@ test "assignment" {
902	1003	{#code_end#}
903	1004	<p>{#syntax#}const{#endsyntax#} applies to all of the bytes that the identifier immediately addresses. {#link\|Pointers#} have their own const-ness.</p>
904	1005	<p>If you need a variable that you can modify, use the {#syntax#}var{#endsyntax#} keyword:</p>
905		{#code_begin\|test#}
	1006	{#code_begin\|test\|var_test#}
906	1007	const expect = @import("std").testing.expect;
907	1008
908	1009	test "var" {
...	...	@@ -923,7 +1024,7 @@ test "initialization" {
923	1024	{#code_end#}
924	1025	{#header_open\|undefined#}
925	1026	<p>Use {#syntax#}undefined{#endsyntax#} to leave variables uninitialized:</p>
926		{#code_begin\|test#}
	1027	{#code_begin\|test\|undefined_test#}
927	1028	const expect = @import("std").testing.expect;
928	1029
929	1030	test "init with undefined" {
...	...	@@ -1108,7 +1209,7 @@ test "comptime vars" {
1108	1209
1109	1210	{#header_open\|Integers#}
1110	1211	{#header_open\|Integer Literals#}
1111		{#code_begin\|syntax#}
	1212	{#code_begin\|syntax\|integer_literals#}
1112	1213	const decimal_int = 98222;
1113	1214	const hex_int = 0xff;
1114	1215	const another_hex_int = 0xFF;
...	...	@@ -1131,7 +1232,7 @@ const big_address = 0xFF80_0000_0000_0000;
1131	1232	However, once an integer value is no longer known at compile-time, it must have a
1132	1233	known size, and is vulnerable to undefined behavior.
1133	1234	</p>
1134		{#code_begin\|syntax#}
	1235	{#code_begin\|syntax\|runtime_vs_comptime#}
1135	1236	fn divide(a: i32, b: i32) i32 {
1136	1237	return a / b;
1137	1238	}
...	...	@@ -1174,7 +1275,7 @@ fn divide(a: i32, b: i32) i32 {
1174	1275	Float literals {#link\|coerce\|Type Coercion#} to any floating point type,
1175	1276	and to any {#link\|integer\|Integers#} type when there is no fractional component.
1176	1277	</p>
1177		{#code_begin\|syntax#}
	1278	{#code_begin\|syntax\|float_literals#}
1178	1279	const floating_point = 123.0E+77;
1179	1280	const another_float = 123.0;
1180	1281	const yet_another = 123.0e+77;
...	...	@@ -1192,7 +1293,7 @@ const more_hex = 0x1234_5678.9ABC_CDEFp-10;
1192	1293	There is no syntax for NaN, infinity, or negative infinity. For these special values,
1193	1294	one must use the standard library:
1194	1295	</p>
1195		{#code_begin\|syntax#}
	1296	{#code_begin\|syntax\|float_special_values#}
1196	1297	const std = @import("std");
1197	1298
1198	1299	const inf = std.math.inf(f32);
...	...	@@ -1245,23 +1346,19 @@ pub fn main() void {
1245	1346	{#header_open\|Table of Operators#}
1246	1347	<div class="table-wrapper">
1247	1348	<table>
	1349	<caption>Table of Operators</caption>
	1350	<thead>
1248	1351	<tr>
1249		<th>
1250		Syntax
1251		</th>
1252		<th>
1253		Relevant Types
1254		</th>
1255		<th>
1256		Description
1257		</th>
1258		<th>
1259		Example
1260		</th>
	1352	<th scope="col">Syntax</th>
	1353	<th scope="col">Relevant Types</th>
	1354	<th scope="col">Description</th>
	1355	<th scope="col">Example</th>
1261	1356	</tr>
	1357	</thead>
	1358	<tbody>
1262	1359	<tr>
1263		<td><pre>{#syntax#}a + b
1264		a += b{#endsyntax#}</pre></td>
	1360	<th scope="row"><pre>{#syntax#}a + b
	1361	a += b{#endsyntax#}</pre></th>
1265	1362	<td>
1266	1363	<ul>
1267	1364	<li>{#link\|Integers#}</li>
...	...	@@ -1280,8 +1377,8 @@ a += b{#endsyntax#}</pre></td>
1280	1377	</td>
1281	1378	</tr>
1282	1379	<tr>
1283		<td><pre>{#syntax#}a +% b
1284		a +%= b{#endsyntax#}</pre></td>
	1380	<th scope="row"><pre>{#syntax#}a +% b
	1381	a +%= b{#endsyntax#}</pre></th>
1285	1382	<td>
1286	1383	<ul>
1287	1384	<li>{#link\|Integers#}</li>
...	...	@@ -1299,8 +1396,8 @@ a +%= b{#endsyntax#}</pre></td>
1299	1396	</td>
1300	1397	</tr>
1301	1398	<tr>
1302		<td><pre>{#syntax#}a - b
1303		a -= b{#endsyntax#}</pre></td>
	1399	<th scope="row"><pre>{#syntax#}a - b
	1400	a -= b{#endsyntax#}</pre></th>
1304	1401	<td>
1305	1402	<ul>
1306	1403	<li>{#link\|Integers#}</li>
...	...	@@ -1319,8 +1416,8 @@ a -= b{#endsyntax#}</pre></td>
1319	1416	</td>
1320	1417	</tr>
1321	1418	<tr>
1322		<td><pre>{#syntax#}a -% b
1323		a -%= b{#endsyntax#}</pre></td>
	1419	<th scope="row"><pre>{#syntax#}a -% b
	1420	a -%= b{#endsyntax#}</pre></th>
1324	1421	<td>
1325	1422	<ul>
1326	1423	<li>{#link\|Integers#}</li>
...	...	@@ -1338,7 +1435,7 @@ a -%= b{#endsyntax#}</pre></td>
1338	1435	</td>
1339	1436	</tr>
1340	1437	<tr>
1341		<td><pre>{#syntax#}-a{#endsyntax#}</pre></td>
	1438	<th scope="row"><pre>{#syntax#}-a{#endsyntax#}</pre></th>
1342	1439	<td>
1343	1440	<ul>
1344	1441	<li>{#link\|Integers#}</li>
...	...	@@ -1356,7 +1453,7 @@ a -%= b{#endsyntax#}</pre></td>
1356	1453	</td>
1357	1454	</tr>
1358	1455	<tr>
1359		<td><pre>{#syntax#}-%a{#endsyntax#}</pre></td>
	1456	<th scope="row"><pre>{#syntax#}-%a{#endsyntax#}</pre></th>
1360	1457	<td>
1361	1458	<ul>
1362	1459	<li>{#link\|Integers#}</li>
...	...	@@ -1373,8 +1470,8 @@ a -%= b{#endsyntax#}</pre></td>
1373	1470	</td>
1374	1471	</tr>
1375	1472	<tr>
1376		<td><pre>{#syntax#}a * b
1377		a *= b{#endsyntax#}</pre></td>
	1473	<th scope="row"><pre>{#syntax#}a * b
	1474	a *= b{#endsyntax#}</pre></th>
1378	1475	<td>
1379	1476	<ul>
1380	1477	<li>{#link\|Integers#}</li>
...	...	@@ -1393,8 +1490,8 @@ a *= b{#endsyntax#}</pre></td>
1393	1490	</td>
1394	1491	</tr>
1395	1492	<tr>
1396		<td><pre>{#syntax#}a *% b
1397		a *%= b{#endsyntax#}</pre></td>
	1493	<th scope="row"><pre>{#syntax#}a *% b
	1494	a *%= b{#endsyntax#}</pre></th>
1398	1495	<td>
1399	1496	<ul>
1400	1497	<li>{#link\|Integers#}</li>
...	...	@@ -1412,8 +1509,8 @@ a *%= b{#endsyntax#}</pre></td>
1412	1509	</td>
1413	1510	</tr>
1414	1511	<tr>
1415		<td><pre>{#syntax#}a / b
1416		a /= b{#endsyntax#}</pre></td>
	1512	<th scope="row"><pre>{#syntax#}a / b
	1513	a /= b{#endsyntax#}</pre></th>
1417	1514	<td>
1418	1515	<ul>
1419	1516	<li>{#link\|Integers#}</li>
...	...	@@ -1438,8 +1535,8 @@ a /= b{#endsyntax#}</pre></td>
1438	1535	</td>
1439	1536	</tr>
1440	1537	<tr>
1441		<td><pre>{#syntax#}a % b
1442		a %= b{#endsyntax#}</pre></td>
	1538	<th scope="row"><pre>{#syntax#}a % b
	1539	a %= b{#endsyntax#}</pre></th>
1443	1540	<td>
1444	1541	<ul>
1445	1542	<li>{#link\|Integers#}</li>
...	...	@@ -1462,8 +1559,8 @@ a %= b{#endsyntax#}</pre></td>
1462	1559	</td>
1463	1560	</tr>
1464	1561	<tr>
1465		<td><pre>{#syntax#}a << b
1466		a <<= b{#endsyntax#}</pre></td>
	1562	<th scope="row"><pre>{#syntax#}a << b
	1563	a <<= b{#endsyntax#}</pre></th>
1467	1564	<td>
1468	1565	<ul>
1469	1566	<li>{#link\|Integers#}</li>
...	...	@@ -1481,8 +1578,8 @@ a <<= b{#endsyntax#}</pre></td>
1481	1578	</td>
1482	1579	</tr>
1483	1580	<tr>
1484		<td><pre>{#syntax#}a >> b
1485		a >>= b{#endsyntax#}</pre></td>
	1581	<th scope="row"><pre>{#syntax#}a >> b
	1582	a >>= b{#endsyntax#}</pre></th>
1486	1583	<td>
1487	1584	<ul>
1488	1585	<li>{#link\|Integers#}</li>
...	...	@@ -1499,8 +1596,8 @@ a >>= b{#endsyntax#}</pre></td>
1499	1596	</td>
1500	1597	</tr>
1501	1598	<tr>
1502		<td><pre>{#syntax#}a & b
1503		a &= b{#endsyntax#}</pre></td>
	1599	<th scope="row"><pre>{#syntax#}a & b
	1600	a &= b{#endsyntax#}</pre></th>
1504	1601	<td>
1505	1602	<ul>
1506	1603	<li>{#link\|Integers#}</li>
...	...	@@ -1516,8 +1613,8 @@ a &= b{#endsyntax#}</pre></td>
1516	1613	</td>
1517	1614	</tr>
1518	1615	<tr>
1519		<td><pre>{#syntax#}a \| b
1520		a \|= b{#endsyntax#}</pre></td>
	1616	<th scope="row"><pre>{#syntax#}a \| b
	1617	a \|= b{#endsyntax#}</pre></th>
1521	1618	<td>
1522	1619	<ul>
1523	1620	<li>{#link\|Integers#}</li>
...	...	@@ -1533,8 +1630,8 @@ a \|= b{#endsyntax#}</pre></td>
1533	1630	</td>
1534	1631	</tr>
1535	1632	<tr>
1536		<td><pre>{#syntax#}a ^ b
1537		a ^= b{#endsyntax#}</pre></td>
	1633	<th scope="row"><pre>{#syntax#}a ^ b
	1634	a ^= b{#endsyntax#}</pre></th>
1538	1635	<td>
1539	1636	<ul>
1540	1637	<li>{#link\|Integers#}</li>
...	...	@@ -1550,7 +1647,7 @@ a ^= b{#endsyntax#}</pre></td>
1550	1647	</td>
1551	1648	</tr>
1552	1649	<tr>
1553		<td><pre>{#syntax#}~a{#endsyntax#}</pre></td>
	1650	<th scope="row"><pre>{#syntax#}~a{#endsyntax#}</pre></th>
1554	1651	<td>
1555	1652	<ul>
1556	1653	<li>{#link\|Integers#}</li>
...	...	@@ -1564,7 +1661,7 @@ a ^= b{#endsyntax#}</pre></td>
1564	1661	</td>
1565	1662	</tr>
1566	1663	<tr>
1567		<td><pre>{#syntax#}a orelse b{#endsyntax#}</pre></td>
	1664	<th scope="row"><pre>{#syntax#}a orelse b{#endsyntax#}</pre></th>
1568	1665	<td>
1569	1666	<ul>
1570	1667	<li>{#link\|Optionals#}</li>
...	...	@@ -1582,7 +1679,7 @@ unwrapped == 1234{#endsyntax#}</pre>
1582	1679	</td>
1583	1680	</tr>
1584	1681	<tr>
1585		<td><pre>{#syntax#}a.?{#endsyntax#}</pre></td>
	1682	<th scope="row"><pre>{#syntax#}a.?{#endsyntax#}</pre></th>
1586	1683	<td>
1587	1684	<ul>
1588	1685	<li>{#link\|Optionals#}</li>
...	...	@@ -1598,8 +1695,8 @@ value.? == 5678{#endsyntax#}</pre>
1598	1695	</td>
1599	1696	</tr>
1600	1697	<tr>
1601		<td><pre>{#syntax#}a catch b
1602		a catch \|err\| b{#endsyntax#}</pre></td>
	1698	<th scope="row"><pre>{#syntax#}a catch b
	1699	a catch \|err\| b{#endsyntax#}</pre></th>
1603	1700	<td>
1604	1701	<ul>
1605	1702	<li>{#link\|Error Unions\|Errors#}</li>
...	...	@@ -1618,7 +1715,7 @@ unwrapped == 1234{#endsyntax#}</pre>
1618	1715	</td>
1619	1716	</tr>
1620	1717	<tr>
1621		<td><pre>{#syntax#}a and b{#endsyntax#}</pre></td>
	1718	<th scope="row"><pre>{#syntax#}a and b{#endsyntax#}</pre></th>
1622	1719	<td>
1623	1720	<ul>
1624	1721	<li>{#link\|bool\|Primitive Types#}</li>
...	...	@@ -1633,7 +1730,7 @@ unwrapped == 1234{#endsyntax#}</pre>
1633	1730	</td>
1634	1731	</tr>
1635	1732	<tr>
1636		<td><pre>{#syntax#}a or b{#endsyntax#}</pre></td>
	1733	<th scope="row"><pre>{#syntax#}a or b{#endsyntax#}</pre></th>
1637	1734	<td>
1638	1735	<ul>
1639	1736	<li>{#link\|bool\|Primitive Types#}</li>
...	...	@@ -1648,7 +1745,7 @@ unwrapped == 1234{#endsyntax#}</pre>
1648	1745	</td>
1649	1746	</tr>
1650	1747	<tr>
1651		<td><pre>{#syntax#}!a{#endsyntax#}</pre></td>
	1748	<th scope="row"><pre>{#syntax#}!a{#endsyntax#}</pre></th>
1652	1749	<td>
1653	1750	<ul>
1654	1751	<li>{#link\|bool\|Primitive Types#}</li>
...	...	@@ -1662,7 +1759,7 @@ unwrapped == 1234{#endsyntax#}</pre>
1662	1759	</td>
1663	1760	</tr>
1664	1761	<tr>
1665		<td><pre>{#syntax#}a == b{#endsyntax#}</pre></td>
	1762	<th scope="row"><pre>{#syntax#}a == b{#endsyntax#}</pre></th>
1666	1763	<td>
1667	1764	<ul>
1668	1765	<li>{#link\|Integers#}</li>
...	...	@@ -1680,7 +1777,7 @@ unwrapped == 1234{#endsyntax#}</pre>
1680	1777	</td>
1681	1778	</tr>
1682	1779	<tr>
1683		<td><pre>{#syntax#}a == null{#endsyntax#}</pre></td>
	1780	<th scope="row"><pre>{#syntax#}a == null{#endsyntax#}</pre></th>
1684	1781	<td>
1685	1782	<ul>
1686	1783	<li>{#link\|Optionals#}</li>
...	...	@@ -1695,7 +1792,7 @@ value == null{#endsyntax#}</pre>
1695	1792	</td>
1696	1793	</tr>
1697	1794	<tr>
1698		<td><pre>{#syntax#}a != b{#endsyntax#}</pre></td>
	1795	<th scope="row"><pre>{#syntax#}a != b{#endsyntax#}</pre></th>
1699	1796	<td>
1700	1797	<ul>
1701	1798	<li>{#link\|Integers#}</li>
...	...	@@ -1713,7 +1810,7 @@ value == null{#endsyntax#}</pre>
1713	1810	</td>
1714	1811	</tr>
1715	1812	<tr>
1716		<td><pre>{#syntax#}a > b{#endsyntax#}</pre></td>
	1813	<th scope="row"><pre>{#syntax#}a > b{#endsyntax#}</pre></th>
1717	1814	<td>
1718	1815	<ul>
1719	1816	<li>{#link\|Integers#}</li>
...	...	@@ -1729,7 +1826,7 @@ value == null{#endsyntax#}</pre>
1729	1826	</td>
1730	1827	</tr>
1731	1828	<tr>
1732		<td><pre>{#syntax#}a >= b{#endsyntax#}</pre></td>
	1829	<th scope="row"><pre>{#syntax#}a >= b{#endsyntax#}</pre></th>
1733	1830	<td>
1734	1831	<ul>
1735	1832	<li>{#link\|Integers#}</li>
...	...	@@ -1745,7 +1842,7 @@ value == null{#endsyntax#}</pre>
1745	1842	</td>
1746	1843	</tr>
1747	1844	<tr>
1748		<td><pre>{#syntax#}a < b{#endsyntax#}</pre></td>
	1845	<th scope="row"><pre>{#syntax#}a < b{#endsyntax#}</pre></th>
1749	1846	<td>
1750	1847	<ul>
1751	1848	<li>{#link\|Integers#}</li>
...	...	@@ -1761,7 +1858,7 @@ value == null{#endsyntax#}</pre>
1761	1858	</td>
1762	1859	</tr>
1763	1860	<tr>
1764		<td><pre>{#syntax#}a <= b{#endsyntax#}</pre></td>
	1861	<th scope="row"><pre>{#syntax#}a <= b{#endsyntax#}</pre></th>
1765	1862	<td>
1766	1863	<ul>
1767	1864	<li>{#link\|Integers#}</li>
...	...	@@ -1777,7 +1874,7 @@ value == null{#endsyntax#}</pre>
1777	1874	</td>
1778	1875	</tr>
1779	1876	<tr>
1780		<td><pre>{#syntax#}a ++ b{#endsyntax#}</pre></td>
	1877	<th scope="row"><pre>{#syntax#}a ++ b{#endsyntax#}</pre></th>
1781	1878	<td>
1782	1879	<ul>
1783	1880	<li>{#link\|Arrays#}</li>
...	...	@@ -1786,7 +1883,7 @@ value == null{#endsyntax#}</pre>
1786	1883	<td>
1787	1884	Array concatenation.
1788	1885	<ul>
1789		<li>Only available when {#syntax#}a{#endsyntax#} and {#syntax#}b{#endsyntax#} are {#link\|compile-time known\|comptime#}.
	1886	<li>Only available when {#syntax#}a{#endsyntax#} and {#syntax#}b{#endsyntax#} are {#link\|compile-time known\|comptime#}.</li>
1790	1887	</ul>
1791	1888	</td>
1792	1889	<td>
...	...	@@ -1798,7 +1895,7 @@ mem.eql(u32, &together, &[_]u32{1,2,3,4}){#endsyntax#}</pre>
1798	1895	</td>
1799	1896	</tr>
1800	1897	<tr>
1801		<td><pre>{#syntax#}a ** b{#endsyntax#}</pre></td>
	1898	<th scope="row"><pre>{#syntax#}a ** b{#endsyntax#}</pre></th>
1802	1899	<td>
1803	1900	<ul>
1804	1901	<li>{#link\|Arrays#}</li>
...	...	@@ -1807,7 +1904,7 @@ mem.eql(u32, &together, &[_]u32{1,2,3,4}){#endsyntax#}</pre>
1807	1904	<td>
1808	1905	Array multiplication.
1809	1906	<ul>
1810		<li>Only available when {#syntax#}a{#endsyntax#} and {#syntax#}b{#endsyntax#} are {#link\|compile-time known\|comptime#}.
	1907	<li>Only available when {#syntax#}a{#endsyntax#} and {#syntax#}b{#endsyntax#} are {#link\|compile-time known\|comptime#}.</li>
1811	1908	</ul>
1812	1909	</td>
1813	1910	<td>
...	...	@@ -1817,7 +1914,7 @@ mem.eql(u8, pattern, "ababab"){#endsyntax#}</pre>
1817	1914	</td>
1818	1915	</tr>
1819	1916	<tr>
1820		<td><pre>{#syntax#}a.*{#endsyntax#}</pre></td>
	1917	<th scope="row"><pre>{#syntax#}a.*{#endsyntax#}</pre></th>
1821	1918	<td>
1822	1919	<ul>
1823	1920	<li>{#link\|Pointers#}</li>
...	...	@@ -1833,7 +1930,7 @@ ptr.* == 1234{#endsyntax#}</pre>
1833	1930	</td>
1834	1931	</tr>
1835	1932	<tr>
1836		<td><pre>{#syntax#}&a{#endsyntax#}</pre></td>
	1933	<th scope="row"><pre>{#syntax#}&a{#endsyntax#}</pre></th>
1837	1934	<td>
1838	1935	All types
1839	1936	</td>
...	...	@@ -1847,7 +1944,7 @@ ptr.* == 1234{#endsyntax#}</pre>
1847	1944	</td>
1848	1945	</tr>
1849	1946	<tr>
1850		<td><pre>{#syntax#}a \|\| b{#endsyntax#}</pre></td>
	1947	<th scope="row"><pre>{#syntax#}a \|\| b{#endsyntax#}</pre></th>
1851	1948	<td>
1852	1949	<ul>
1853	1950	<li>{#link\|Error Set Type#}</li>
...	...	@@ -1862,6 +1959,7 @@ const B = error{Two};
1862	1959	(A \|\| B) == error{One, Two}{#endsyntax#}</pre>
1863	1960	</td>
1864	1961	</tr>
	1962	</tbody>
1865	1963	</table>
1866	1964	</div>
1867	1965	{#header_close#}
...	...	@@ -2138,7 +2236,7 @@ test "null terminated array" {
2138	2236	</li>
2139	2237	</ul>
2140	2238	<p>Use {#syntax#}&x{#endsyntax#} to obtain a single-item pointer:</p>
2141		{#code_begin\|test#}
	2239	{#code_begin\|test\|single_item_pointer_test#}
2142	2240	const expect = @import("std").testing.expect;
2143	2241
2144	2242	test "address of syntax" {
...	...	@@ -2182,7 +2280,7 @@ test "pointer array access" {
2182	2280	against this kind of undefined behavior. This is one reason
2183	2281	we prefer slices to pointers.
2184	2282	</p>
2185		{#code_begin\|test#}
	2283	{#code_begin\|test\|slice_bounds#}
2186	2284	const expect = @import("std").testing.expect;
2187	2285
2188	2286	test "pointer slicing" {
...	...	@@ -2197,7 +2295,7 @@ test "pointer slicing" {
2197	2295	{#code_end#}
2198	2296	<p>Pointers work at compile-time too, as long as the code does not depend on
2199	2297	an undefined memory layout:</p>
2200		{#code_begin\|test#}
	2298	{#code_begin\|test\|comptime_pointers#}
2201	2299	const expect = @import("std").testing.expect;
2202	2300
2203	2301	test "comptime pointers" {
...	...	@@ -2212,7 +2310,7 @@ test "comptime pointers" {
2212	2310	{#code_end#}
2213	2311	<p>To convert an integer address into a pointer, use {#syntax#}@intToPtr{#endsyntax#}.
2214	2312	To convert a pointer to an integer, use {#syntax#}@ptrToInt{#endsyntax#}:</p>
2215		{#code_begin\|test#}
	2313	{#code_begin\|test\|integer_pointer_conversion#}
2216	2314	const expect = @import("std").testing.expect;
2217	2315
2218	2316	test "@ptrToInt and @intToPtr" {
...	...	@@ -2224,7 +2322,7 @@ test "@ptrToInt and @intToPtr" {
2224	2322	{#code_end#}
2225	2323	<p>Zig is able to preserve memory addresses in comptime code, as long as
2226	2324	the pointer is never dereferenced:</p>
2227		{#code_begin\|test#}
	2325	{#code_begin\|test\|comptime_pointer_conversion#}
2228	2326	const expect = @import("std").testing.expect;
2229	2327
2230	2328	test "comptime @intToPtr" {
...	...	@@ -2244,7 +2342,7 @@ test "comptime @intToPtr" {
2244	2342	should have side effects, such as Memory Mapped Input/Output (MMIO), use {#syntax#}volatile{#endsyntax#}.
2245	2343	In the following code, loads and stores with {#syntax#}mmio_ptr{#endsyntax#} are guaranteed to all happen
2246	2344	and in the same order as in source code:</p>
2247		{#code_begin\|test#}
	2345	{#code_begin\|test\|volatile#}
2248	2346	const expect = @import("std").testing.expect;
2249	2347
2250	2348	test "volatile" {
...	...	@@ -2263,7 +2361,7 @@ test "volatile" {
2263	2361	operation that Zig cannot protect you against. Use {#syntax#}@ptrCast{#endsyntax#} only when other
2264	2362	conversions are not possible.
2265	2363	</p>
2266		{#code_begin\|test#}
	2364	{#code_begin\|test\|pointer_casting#}
2267	2365	const std = @import("std");
2268	2366	const expect = std.testing.expect;
2269	2367
...	...	@@ -2301,7 +2399,7 @@ test "pointer child type" {
2301	2399	In Zig, a pointer type has an alignment value. If the value is equal to the
2302	2400	alignment of the underlying type, it can be omitted from the type:
2303	2401	</p>
2304		{#code_begin\|test#}
	2402	{#code_begin\|test\|variable_alignment#}
2305	2403	const std = @import("std");
2306	2404	const expect = std.testing.expect;
2307	2405
...	...	@@ -2323,7 +2421,7 @@ test "variable alignment" {
2323	2421	You can specify alignment on variables and functions. If you do this, then
2324	2422	pointers to them get the specified alignment:
2325	2423	</p>
2326		{#code_begin\|test#}
	2424	{#code_begin\|test\|variable_func_alignment#}
2327	2425	const expect = @import("std").testing.expect;
2328	2426
2329	2427	var foo: u8 align(4) = 100;
...	...	@@ -2660,7 +2758,7 @@ test "linked list" {
2660	2758	Each struct field may have an expression indicating the default field value. Such expressions
2661	2759	are executed at {#link\|comptime#}, and allow the field to be omitted in a struct literal expression:
2662	2760	</p>
2663		{#code_begin\|test#}
	2761	{#code_begin\|test\|default_field_values#}
2664	2762	const Foo = struct {
2665	2763	a: i32 = 1234,
2666	2764	b: i32,
...	...	@@ -2709,7 +2807,7 @@ test "default struct initialization fields" {
2709	2807	in a {#link\|@bitCast#} or a {#link\|@ptrCast#} to reinterpret memory.
2710	2808	This even works at {#link\|comptime#}:
2711	2809	</p>
2712		{#code_begin\|test#}
	2810	{#code_begin\|test\|packed_structs#}
2713	2811	const std = @import("std");
2714	2812	const native_endian = @import("builtin").target.cpu.arch.endian();
2715	2813	const expect = std.testing.expect;
...	...	@@ -2750,7 +2848,7 @@ fn doTheTest() !void {
2750	2848	<p>
2751	2849	Zig allows the address to be taken of a non-byte-aligned field:
2752	2850	</p>
2753		{#code_begin\|test#}
	2851	{#code_begin\|test\|pointer_to_non-byte_aligned_field#}
2754	2852	const std = @import("std");
2755	2853	const expect = std.testing.expect;
2756	2854
...	...	@@ -2806,7 +2904,7 @@ fn bar(x: *const u3) u3 {
2806	2904	<p>
2807	2905	Pointers to non-ABI-aligned fields share the same address as the other fields within their host integer:
2808	2906	</p>
2809		{#code_begin\|test#}
	2907	{#code_begin\|test\|pointer_to_non-bit_aligned_field#}
2810	2908	const std = @import("std");
2811	2909	const expect = std.testing.expect;
2812	2910
...	...	@@ -2830,7 +2928,7 @@ test "pointer to non-bit-aligned field" {
2830	2928	<p>
2831	2929	This can be observed with {#link\|@bitOffsetOf#} and {#link\|offsetOf#}:
2832	2930	</p>
2833		{#code_begin\|test#}
	2931	{#code_begin\|test\|test_bitOffsetOf_offsetOf#}
2834	2932	const std = @import("std");
2835	2933	const expect = std.testing.expect;
2836	2934
...	...	@@ -2875,7 +2973,7 @@ test "overaligned pointer to packed struct" {
2875	2973	<p>
2876	2974	It's also possible to set alignment of struct fields:
2877	2975	</p>
2878		{#code_begin\|test#}
	2976	{#code_begin\|test\|test_aligned_struct_fields#}
2879	2977	const std = @import("std");
2880	2978	const expectEqual = std.testing.expectEqual;
2881	2979
...	...	@@ -3129,7 +3227,7 @@ export fn entry(foo: Foo) void { _ = foo; }
3129	3227	<p>
3130	3228	Enum literals allow specifying the name of an enum field without specifying the enum type:
3131	3229	</p>
3132		{#code_begin\|test#}
	3230	{#code_begin\|test\|test_enum_literals#}
3133	3231	const std = @import("std");
3134	3232	const expect = std.testing.expect;
3135	3233
...	...	@@ -3171,7 +3269,7 @@ test "switch using enum literals" {
3171	3269	A switch on a non-exhaustive enum can include a '_' prong as an alternative to an {#syntax#}else{#endsyntax#} prong
3172	3270	with the difference being that it makes it a compile error if all the known tag names are not handled by the switch.
3173	3271	</p>
3174		{#code_begin\|test#}
	3272	{#code_begin\|test\|test_switch_non-exhaustive#}
3175	3273	const std = @import("std");
3176	3274	const expect = std.testing.expect;
3177	3275
...	...	@@ -3224,7 +3322,7 @@ test "simple union" {
3224	3322	}
3225	3323	{#code_end#}
3226	3324	<p>You can activate another field by assigning the entire union:</p>
3227		{#code_begin\|test#}
	3325	{#code_begin\|test\|test_simple_union#}
3228	3326	const std = @import("std");
3229	3327	const expect = std.testing.expect;
3230	3328
...	...	@@ -3253,7 +3351,7 @@ test "simple union" {
3253	3351	to use with {#link\|switch#} expressions.
3254	3352	Tagged unions coerce to their tag type: {#link\|Type Coercion: unions and enums#}.
3255	3353	</p>
3256		{#code_begin\|test#}
	3354	{#code_begin\|test\|test_switch_tagged_union#}
3257	3355	const std = @import("std");
3258	3356	const expect = std.testing.expect;
3259	3357
...	...	@@ -3291,7 +3389,7 @@ test "coerce to enum" {
3291	3389	<p>In order to modify the payload of a tagged union in a switch expression,
3292	3390	place a {#syntax#}*{#endsyntax#} before the variable name to make it a pointer:
3293	3391	</p>
3294		{#code_begin\|test#}
	3392	{#code_begin\|test\|test_switch_modify_tagged_union#}
3295	3393	const std = @import("std");
3296	3394	const expect = std.testing.expect;
3297	3395
...	...	@@ -3320,7 +3418,7 @@ test "modify tagged union in switch" {
3320	3418	Unions can be made to infer the enum tag type.
3321	3419	Further, unions can have methods just like structs and enums.
3322	3420	</p>
3323		{#code_begin\|test#}
	3421	{#code_begin\|test\|test_union_method#}
3324	3422	const std = @import("std");
3325	3423	const expect = std.testing.expect;
3326	3424
...	...	@@ -3352,7 +3450,7 @@ test "union method" {
3352	3450	{#link\|@tagName#} can be used to return a {#link\|comptime#}
3353	3451	{#syntax#}[:0]const u8{#endsyntax#} value representing the field name:
3354	3452	</p>
3355		{#code_begin\|test#}
	3453	{#code_begin\|test\|test_tagName#}
3356	3454	const std = @import("std");
3357	3455	const expect = std.testing.expect;
3358	3456
...	...	@@ -3377,7 +3475,7 @@ test "@tagName" {
3377	3475
3378	3476	{#header_open\|packed union#}
3379	3477	<p>A {#syntax#}packed union{#endsyntax#} has well-defined in-memory layout and is eligible
3380		to be in a {#link\|packed struct#}.
	3478	to be in a {#link\|packed struct#}.</p>
3381	3479	{#header_close#}
3382	3480
3383	3481	{#header_open\|Anonymous Union Literals#}
...	...	@@ -3448,7 +3546,7 @@ test "access variable after block scope" {
3448	3546	<p>Blocks are expressions. When labeled, {#syntax#}break{#endsyntax#} can be used
3449	3547	to return a value from the block:
3450	3548	</p>
3451		{#code_begin\|test#}
	3549	{#code_begin\|test\|test_labeled_break#}
3452	3550	const std = @import("std");
3453	3551	const expect = std.testing.expect;
3454	3552
...	...	@@ -3482,7 +3580,7 @@ test "inside test block" {
3482	3580	Because of this, when you read Zig code you can rely on an identifier always meaning the same thing,
3483	3581	within the scope it is defined. Note that you can, however use the same name if the scopes are separate:
3484	3582	</p>
3485		{#code_begin\|test#}
	3583	{#code_begin\|test\|test_scopes#}
3486	3584	test "separate scopes" {
3487	3585	{
3488	3586	const pi = 3.14;
...	...	@@ -3569,7 +3667,7 @@ test "switch inside function" {
3569	3667	done by placing a {#syntax#}*{#endsyntax#} before the capture variable name,
3570	3668	turning it into a pointer.
3571	3669	</p>
3572		{#code_begin\|test#}
	3670	{#code_begin\|test\|test_switch_tagged_union#}
3573	3671	const expect = @import("std").testing.expect;
3574	3672
3575	3673	test "switch on tagged union" {
...	...	@@ -3636,7 +3734,7 @@ test "exhaustive switching" {
3636	3734	{#link\|Enum Literals#} can be useful to use with {#syntax#}switch{#endsyntax#} to avoid
3637	3735	repetitively specifying {#link\|enum#} or {#link\|union#} types:
3638	3736	</p>
3639		{#code_begin\|test#}
	3737	{#code_begin\|test\|test_exhaustive_switch#}
3640	3738	const std = @import("std");
3641	3739	const expect = std.testing.expect;
3642	3740
...	...	@@ -3761,7 +3859,7 @@ fn rangeHasNumber(begin: usize, end: usize, number: usize) bool {
3761	3859	{#header_open\|Labeled while#}
3762	3860	<p>When a {#syntax#}while{#endsyntax#} loop is labeled, it can be referenced from a {#syntax#}break{#endsyntax#}
3763	3861	or {#syntax#}continue{#endsyntax#} from within a nested loop:</p>
3764		{#code_begin\|test#}
	3862	{#code_begin\|test\|test_nested_break#}
3765	3863	test "nested break" {
3766	3864	outer: while (true) {
3767	3865	while (true) {
...	...	@@ -3866,7 +3964,7 @@ fn eventuallyErrorSequence() anyerror!u32 {
3866	3964	allows the code to do some things which only work at compile time,
3867	3965	such as use types as first class values.
3868	3966	</p>
3869		{#code_begin\|test#}
	3967	{#code_begin\|test\|test_inline_while#}
3870	3968	const expect = @import("std").testing.expect;
3871	3969
3872	3970	test "inline while loop" {
...	...	@@ -3969,7 +4067,7 @@ test "for else" {
3969	4067	{#header_open\|Labeled for#}
3970	4068	<p>When a {#syntax#}for{#endsyntax#} loop is labeled, it can be referenced from a {#syntax#}break{#endsyntax#}
3971	4069	or {#syntax#}continue{#endsyntax#} from within a nested loop:</p>
3972		{#code_begin\|test#}
	4070	{#code_begin\|test\|test_nested_break#}
3973	4071	const std = @import("std");
3974	4072	const expect = std.testing.expect;
3975	4073
...	...	@@ -4005,7 +4103,7 @@ test "nested continue" {
4005	4103	The capture value and iterator value of inlined for loops are
4006	4104	compile-time known.
4007	4105	</p>
4008		{#code_begin\|test#}
	4106	{#code_begin\|test\|test_inline_loop#}
4009	4107	const expect = @import("std").testing.expect;
4010	4108
4011	4109	test "inline for loop" {
...	...	@@ -4278,16 +4376,16 @@ test "errdefer unwinding" {
4278	4376	{#header_close#}
4279	4377	{#header_open\|unreachable#}
4280	4378	<p>
4281		In {#syntax#}Debug{#endsyntax#} and {#syntax#}ReleaseSafe{#endsyntax#} mode, and when using <code>zig test</code>,
	4379	In {#syntax#}Debug{#endsyntax#} and {#syntax#}ReleaseSafe{#endsyntax#} mode, and when using <kbd>zig test</kbd>,
4282	4380	{#syntax#}unreachable{#endsyntax#} emits a call to {#syntax#}panic{#endsyntax#} with the message <code>reached unreachable code</code>.
4283	4381	</p>
4284	4382	<p>
4285	4383	In {#syntax#}ReleaseFast{#endsyntax#} mode, the optimizer uses the assumption that {#syntax#}unreachable{#endsyntax#} code
4286		will never be hit to perform optimizations. However, <code>zig test</code> even in {#syntax#}ReleaseFast{#endsyntax#} mode
	4384	will never be hit to perform optimizations. However, <kbd>zig test</kbd> even in {#syntax#}ReleaseFast{#endsyntax#} mode
4287	4385	still emits {#syntax#}unreachable{#endsyntax#} as calls to {#syntax#}panic{#endsyntax#}.
4288	4386	</p>
4289	4387	{#header_open\|Basics#}
4290		{#code_begin\|test#}
	4388	{#code_begin\|test\|test_unreachable#}
4291	4389	// unreachable is used to assert that control flow will never happen upon a
4292	4390	// particular location:
4293	4391	test "basic math" {
...	...	@@ -4343,7 +4441,7 @@ test "type of unreachable" {
4343	4441	<p>When resolving types together, such as {#syntax#}if{#endsyntax#} clauses or {#syntax#}switch{#endsyntax#} prongs,
4344	4442	the {#syntax#}noreturn{#endsyntax#} type is compatible with every other type. Consider:
4345	4443	</p>
4346		{#code_begin\|test#}
	4444	{#code_begin\|test\|test_noreturn#}
4347	4445	fn foo(condition: bool, b: u32) void {
4348	4446	const a = if (condition) b else return;
4349	4447	_ = a;
...	...	@@ -4354,7 +4452,7 @@ test "noreturn" {
4354	4452	}
4355	4453	{#code_end#}
4356	4454	<p>Another use case for {#syntax#}noreturn{#endsyntax#} is the {#syntax#}exit{#endsyntax#} function:</p>
4357		{#code_begin\|test#}
	4455	{#code_begin\|test\|noreturn_from_exit#}
4358	4456	{#target_windows#}
4359	4457	pub extern "kernel32" fn ExitProcess(exit_code: c_uint) callconv(if (@import("builtin").target.cpu.arch == .i386) .Stdcall else .C) noreturn;
4360	4458
...	...	@@ -4451,7 +4549,7 @@ fn foo() void { }
4451	4549	as parameters, Zig may choose to copy and pass by value, or pass by reference, whichever way
4452	4550	Zig decides will be faster. This is made possible, in part, by the fact that parameters are immutable.
4453	4551	</p>
4454		{#code_begin\|test#}
	4552	{#code_begin\|test\|pass_by_reference_or_value#}
4455	4553	const Point = struct {
4456	4554	x: i32,
4457	4555	y: i32,
...	...	@@ -4481,7 +4579,7 @@ test "pass struct to function" {
4481	4579	In this case the parameter types will be inferred when the function is called.
4482	4580	Use {#link\|@TypeOf#} and {#link\|@typeInfo#} to get information about the inferred type.
4483	4581	</p>
4484		{#code_begin\|test#}
	4582	{#code_begin\|test\|test_fn_type_inference#}
4485	4583	const expect = @import("std").testing.expect;
4486	4584
4487	4585	fn addFortyTwo(x: anytype) @TypeOf(x) {
...	...	@@ -4499,7 +4597,7 @@ test "fn type inference" {
4499	4597
4500	4598	{#header_close#}
4501	4599	{#header_open\|Function Reflection#}
4502		{#code_begin\|test#}
	4600	{#code_begin\|test\|test_fn_reflection#}
4503	4601	const expect = @import("std").testing.expect;
4504	4602
4505	4603	test "fn reflection" {
...	...	@@ -4524,7 +4622,7 @@ test "fn reflection" {
4524	4622	<p>
4525	4623	You can {#link\|coerce\|Type Coercion#} an error from a subset to a superset:
4526	4624	</p>
4527		{#code_begin\|test#}
	4625	{#code_begin\|test\|coercing_subset_to_superset#}
4528	4626	const std = @import("std");
4529	4627
4530	4628	const FileOpenError = error {
...	...	@@ -4608,7 +4706,7 @@ const err = (error {FileNotFound}).FileNotFound;
4608	4706	<p>
4609	4707	Here is a function to parse a string into a 64-bit integer:
4610	4708	</p>
4611		{#code_begin\|test#}
	4709	{#code_begin\|test\|error_union_parsing_u64#}
4612	4710	const std = @import("std");
4613	4711	const maxInt = std.math.maxInt;
4614	4712
...	...	@@ -4791,7 +4889,7 @@ fn createFoo(param: i32) !Foo {
4791	4889
4792	4890	<p>An error union is created with the {#syntax#}!{#endsyntax#} binary operator.
4793	4891	You can use compile-time reflection to access the child type of an error union:</p>
4794		{#code_begin\|test#}
	4892	{#code_begin\|test\|test_error_union#}
4795	4893	const expect = @import("std").testing.expect;
4796	4894
4797	4895	test "error union" {
...	...	@@ -4823,7 +4921,7 @@ test "error union" {
4823	4921	{#syntax#}LinuxFileOpenError \|\| WindowsFileOpenError{#endsyntax#} for the error set of opening
4824	4922	files.
4825	4923	</p>
4826		{#code_begin\|test#}
	4924	{#code_begin\|test\|test_merging_error_sets#}
4827	4925	const A = error{
4828	4926	NotDir,
4829	4927
...	...	@@ -4859,7 +4957,7 @@ test "merge error sets" {
4859	4957	Because many functions in Zig return a possible error, Zig supports inferring the error set.
4860	4958	To infer the error set for a function, use this syntax:
4861	4959	</p>
4862		{#code_begin\|test#}
	4960	{#code_begin\|test\|inferred_error_sets#}
4863	4961	// With an inferred error set
4864	4962	pub fn add_inferred(comptime T: type, a: T, b: T) !T {
4865	4963	var answer: T = undefined;
...	...	@@ -5173,7 +5271,7 @@ fn doAThing(optional_foo: ?*Foo) void {
5173	5271	{#header_open\|Optional Type#}
5174	5272	<p>An optional is created by putting {#syntax#}?{#endsyntax#} in front of a type. You can use compile-time
5175	5273	reflection to access the child type of an optional:</p>
5176		{#code_begin\|test#}
	5274	{#code_begin\|test\|test_optional_type#}
5177	5275	const expect = @import("std").testing.expect;
5178	5276
5179	5277	test "optional type" {
...	...	@@ -5200,7 +5298,7 @@ const optional_value: ?i32 = null;
5200	5298	{#header_open\|Optional Pointers#}
5201	5299	<p>An optional pointer is guaranteed to be the same size as a pointer. The {#syntax#}null{#endsyntax#} of
5202	5300	the optional is guaranteed to be address 0.</p>
5203		{#code_begin\|test#}
	5301	{#code_begin\|test\|test_optional_pointer#}
5204	5302	const expect = @import("std").testing.expect;
5205	5303
5206	5304	test "optional pointers" {
...	...	@@ -5232,7 +5330,7 @@ test "optional pointers" {
5232	5330	<p>
5233	5331	Type coercion occurs when one type is expected, but different type is provided:
5234	5332	</p>
5235		{#code_begin\|test#}
	5333	{#code_begin\|test\|type_coercion#}
5236	5334	test "type coercion - variable declaration" {
5237	5335	var a: u8 = 1;
5238	5336	var b: u16 = a;
...	...	@@ -5272,7 +5370,7 @@ test "type coercion - @as builtin" {
5272	5370	<p>
5273	5371	These casts are no-ops at runtime since the value representation does not change.
5274	5372	</p>
5275		{#code_begin\|test#}
	5373	{#code_begin\|test\|no_op_casts#}
5276	5374	test "type coercion - const qualification" {
5277	5375	var a: i32 = 1;
5278	5376	var b: *i32 = &a;
...	...	@@ -5284,7 +5382,7 @@ fn foo(_: *const i32) void {}
5284	5382	<p>
5285	5383	In addition, pointers coerce to const optional pointers:
5286	5384	</p>
5287		{#code_begin\|test#}
	5385	{#code_begin\|test\|pointer_coerce_const_optional#}
5288	5386	const std = @import("std");
5289	5387	const expect = std.testing.expect;
5290	5388	const mem = std.mem;
...	...	@@ -5301,7 +5399,7 @@ test "cast [1][]const u8 to []const ?[]const u8" {
5301	5399	{#link\|Integers#} coerce to integer types which can represent every value of the old type, and likewise
5302	5400	{#link\|Floats#} coerce to float types which can represent every value of the old type.
5303	5401	</p>
5304		{#code_begin\|test#}
	5402	{#code_begin\|test\|test_integer_widening#}
5305	5403	const std = @import("std");
5306	5404	const expect = std.testing.expect;
5307	5405	const mem = std.mem;
...	...	@@ -5429,7 +5527,7 @@ test "T to [1]T" {
5429	5527	<p>
5430	5528	The payload type of {#link\|Optionals#}, as well as {#link\|null#}, coerce to the optional type.
5431	5529	</p>
5432		{#code_begin\|test#}
	5530	{#code_begin\|test\|test_coerce_optionals#}
5433	5531	const std = @import("std");
5434	5532	const expect = std.testing.expect;
5435	5533
...	...	@@ -5442,7 +5540,7 @@ test "coerce to optionals" {
5442	5540	}
5443	5541	{#code_end#}
5444	5542	<p>It works nested inside the {#link\|Error Union Type#}, too:</p>
5445		{#code_begin\|test#}
	5543	{#code_begin\|test\|test_corerce_optional_wrapped_error_union#}
5446	5544	const std = @import("std");
5447	5545	const expect = std.testing.expect;
5448	5546
...	...	@@ -5459,7 +5557,7 @@ test "coerce to optionals wrapped in error union" {
5459	5557	<p>The payload type of an {#link\|Error Union Type#} as well as the {#link\|Error Set Type#}
5460	5558	coerce to the error union type:
5461	5559	</p>
5462		{#code_begin\|test#}
	5560	{#code_begin\|test\|test_coerce_to_error_union#}
5463	5561	const std = @import("std");
5464	5562	const expect = std.testing.expect;
5465	5563
...	...	@@ -5476,7 +5574,7 @@ test "coercion to error unions" {
5476	5574	<p>When a number is {#link\|comptime#}-known to be representable in the destination type,
5477	5575	it may be coerced:
5478	5576	</p>
5479		{#code_begin\|test#}
	5577	{#code_begin\|test\|test_coerce_large_to_small#}
5480	5578	const std = @import("std");
5481	5579	const expect = std.testing.expect;
5482	5580
...	...	@@ -5492,7 +5590,7 @@ test "coercing large integer type to smaller one when value is comptime known to
5492	5590	when they are {#link\|comptime#}-known to be a field of the union that has only one possible value, such as
5493	5591	{#link\|void#}:
5494	5592	</p>
5495		{#code_begin\|test#}
	5593	{#code_begin\|test\|test_coerce_unions_enums#}
5496	5594	const std = @import("std");
5497	5595	const expect = std.testing.expect;
5498	5596
...	...	@@ -5525,7 +5623,7 @@ test "coercion between unions and enums" {
5525	5623	regardless of const.</p>
5526	5624	<p>TODO document the reasoning for this</p>
5527	5625	<p>TODO document whether vice versa should work and why</p>
5528		{#code_begin\|test#}
	5626	{#code_begin\|test\|coerce_zero_bit_types#}
5529	5627	test "coercion of zero bit types" {
5530	5628	var x: void = {};
5531	5629	var y: *void = x;
...	...	@@ -5715,7 +5813,7 @@ export fn entry() void {
5715	5813	{#syntax#}Map(Key, Value){#endsyntax#}, one can pass {#syntax#}void{#endsyntax#} for the {#syntax#}Value{#endsyntax#}
5716	5814	type to make it into a {#syntax#}Set{#endsyntax#}:
5717	5815	</p>
5718		{#code_begin\|test#}
	5816	{#code_begin\|test\|void_in_hashmap#}
5719	5817	const std = @import("std");
5720	5818	const expect = std.testing.expect;
5721	5819
...	...	@@ -5755,7 +5853,7 @@ fn foo() i32 {
5755	5853	}
5756	5854	{#code_end#}
5757	5855	<p>However, if the expression has type {#syntax#}void{#endsyntax#}, there will be no error. Function return values can also be explicitly ignored by assigning them to {#syntax#}_{#endsyntax#}. </p>
5758		{#code_begin\|test#}
	5856	{#code_begin\|test\|void_ignored#}
5759	5857	test "void is ignored" {
5760	5858	returnsVoid();
5761	5859	}
...	...	@@ -5774,7 +5872,7 @@ fn foo() i32 {
5774	5872
5775	5873	{#header_open\|Pointers to Zero Bit Types#}
5776	5874	<p>Pointers to zero bit types also have zero bits. They always compare equal to each other:</p>
5777		{#code_begin\|test#}
	5875	{#code_begin\|test\|pointers_to_zero_bits#}
5778	5876	const std = @import("std");
5779	5877	const expect = std.testing.expect;
5780	5878
...	...	@@ -5826,10 +5924,10 @@ test "using std namespace" {
5826	5924	{#code_end#}
5827	5925	<p>
5828	5926	{#syntax#}usingnamespace{#endsyntax#} has an important use case when organizing the public
5829		API of a file or package. For example, one might have <code>c.zig</code> with all of the
	5927	API of a file or package. For example, one might have <code class="file">c.zig</code> with all of the
5830	5928	{#link\|C imports\|Import from C Header File#}:
5831	5929	</p>
5832		<pre>{#syntax#}
	5930	{#syntax_block\|zig\|c.zig#}
5833	5931	pub usingnamespace @cImport({
5834	5932	@cInclude("epoxy/gl.h");
5835	5933	@cInclude("GLFW/glfw3.h");
...	...	@@ -5837,7 +5935,7 @@ pub usingnamespace @cImport({
5837	5935	@cDefine("STBI_NO_STDIO", "");
5838	5936	@cInclude("stb_image.h");
5839	5937	});
5840		{#endsyntax#}</pre>
	5938	{#end_syntax_block#}
5841	5939	<p>
5842	5940	The above example demonstrates using {#syntax#}pub{#endsyntax#} to qualify the
5843	5941	{#syntax#}usingnamespace{#endsyntax#} additionally makes the imported declarations
...	...	@@ -5923,7 +6021,7 @@ test "try to compare bools" {
5923	6021	value is known at compile-time. This means that we actually could make this work for the bool type
5924	6022	if we wanted to:
5925	6023	</p>
5926		{#code_begin\|test#}
	6024	{#code_begin\|test\|comptime_max_with_bool#}
5927	6025	fn max(comptime T: type, a: T, b: T) T {
5928	6026	if (T == bool) {
5929	6027	return a or b;
...	...	@@ -6086,7 +6184,7 @@ test "foo" {
6086	6184	<p>
6087	6185	Let's look at an example:
6088	6186	</p>
6089		{#code_begin\|test#}
	6187	{#code_begin\|test\|fibonacci_recursion#}
6090	6188	const expect = @import("std").testing.expect;
6091	6189
6092	6190	fn fibonacci(index: u32) u32 {
...	...	@@ -6179,7 +6277,7 @@ test "fibonacci" {
6179	6277	{#syntax#}comptime{#endsyntax#} expressions. This means that we can use functions to
6180	6278	initialize complex static data. For example:
6181	6279	</p>
6182		{#code_begin\|test#}
	6280	{#code_begin\|test\|N_primes#}
6183	6281	const first_25_primes = firstNPrimes(25);
6184	6282	const sum_of_first_25_primes = sum(&first_25_primes);
6185	6283
...	...	@@ -6480,7 +6578,7 @@ pub fn syscall3(number: usize, arg1: usize, arg2: usize, arg3: usize) usize {
6480	6578	<p>
6481	6579	Dissecting the syntax:
6482	6580	</p>
6483		<pre>{#syntax#}// Inline assembly is an expression which returns a value.
	6581	{#syntax_block\|zig\|Assembly Syntax Explained#}// Inline assembly is an expression which returns a value.
6484	6582	// the `asm` keyword begins the expression.
6485	6583	_ = asm
6486	6584	// `volatile` is an optional modifier that tells Zig this
...	...	@@ -6535,7 +6633,7 @@ volatile (
6535	6633	// output. In this example we list $rcx and $r11 because it is known the
6536	6634	// kernel syscall does not preserve these registers.
6537	6635	: "rcx", "r11"
6538		);{#endsyntax#}</pre>
	6636	);{#end_syntax_block#}
6539	6637	<p>
6540	6638	For i386 and x86_64 targets, the syntax is AT&T syntax, rather than the more
6541	6639	popular Intel syntax. This is due to technical constraints; assembly parsing is
...	...	@@ -6661,7 +6759,7 @@ test "global assembly" {
6661	6759	return to the callsite (in the case of the first suspension),
6662	6760	or resumer (in the case of subsequent suspensions).
6663	6761	</p>
6664		{#code_begin\|test#}
	6762	{#code_begin\|test\|suspend_no_resume#}
6665	6763	const std = @import("std");
6666	6764	const expect = std.testing.expect;
6667	6765
...	...	@@ -6688,7 +6786,7 @@ fn func() void {
6688	6786	{#syntax#}resume{#endsyntax#} operation on a different thread.
6689	6787	{#link\|@frame#} provides access to the async function frame pointer.
6690	6788	</p>
6691		{#code_begin\|test#}
	6789	{#code_begin\|test\|async_suspend_block#}
6692	6790	const std = @import("std");
6693	6791	const expect = std.testing.expect;
6694	6792
...	...	@@ -6726,7 +6824,7 @@ fn testSuspendBlock() void {
6726	6824	However, the async function can be directly resumed from the suspend block, in which case it
6727	6825	never returns to its resumer and continues executing.
6728	6826	</p>
6729		{#code_begin\|test#}
	6827	{#code_begin\|test\|resume_from_suspend#}
6730	6828	const std = @import("std");
6731	6829	const expect = std.testing.expect;
6732	6830
...	...	@@ -6762,7 +6860,7 @@ fn testResumeFromSuspend(my_result: *i32) void {
6762	6860	execution would continue at the most recent {#syntax#}async{#endsyntax#} callsite or {#syntax#}resume{#endsyntax#} callsite,
6763	6861	and the return value of the async function would be lost.
6764	6862	</p>
6765		{#code_begin\|test#}
	6863	{#code_begin\|test\|async_await#}
6766	6864	const std = @import("std");
6767	6865	const expect = std.testing.expect;
6768	6866
...	...	@@ -6806,7 +6904,7 @@ fn func() void {
6806	6904	does not suspend; instead it copies the
6807	6905	return value directly from the target function's frame.
6808	6906	</p>
6809		{#code_begin\|test#}
	6907	{#code_begin\|test\|async_await_sequence#}
6810	6908	const std = @import("std");
6811	6909	const expect = std.testing.expect;
6812	6910
...	...	@@ -7084,7 +7182,7 @@ comptime {
7084	7182	read after {#link\|await\|Async and Await#} completes. Any result location provided to
7085	7183	{#syntax#}await{#endsyntax#} will copy the result from {#syntax#}result_ptr{#endsyntax#}.
7086	7184	</p>
7087		{#code_begin\|test#}
	7185	{#code_begin\|test\|async_struct_field_fn_pointer#}
7088	7186	const std = @import("std");
7089	7187	const expect = std.testing.expect;
7090	7188
...	...	@@ -7526,7 +7624,7 @@ test "main" {
7526	7624	not encountered by analysis, the
7527	7625	program compiles successfully and the generated executable prints:
7528	7626	</p>
7529		{#code_begin\|test#}
	7627	{#code_begin\|test\|without_compileLog#}
7530	7628	const print = @import("std").debug.print;
7531	7629
7532	7630	const num1 = blk: {
...	...	@@ -7758,7 +7856,7 @@ export fn @"A function name that is a complete sentence."() void {}
7758	7856	<pre>{#syntax#}@field(lhs: anytype, comptime field_name: []const u8) (field){#endsyntax#}</pre>
7759	7857	<p>Performs field access by a compile-time string. Works on both fields and declarations.
7760	7858	</p>
7761		{#code_begin\|test#}
	7859	{#code_begin\|test\|field_decl_access_by_string#}
7762	7860	const std = @import("std");
7763	7861
7764	7862	const Point = struct {
...	...	@@ -7843,7 +7941,7 @@ test "decl access by string" {
7843	7941	This type is suitable to be used as the return type of {#link\|async\|Async and Await#} which
7844	7942	allows one to, for example, heap-allocate an async function frame:
7845	7943	</p>
7846		{#code_begin\|test#}
	7944	{#code_begin\|test\|heap_allocated_frame#}
7847	7945	const std = @import("std");
7848	7946
7849	7947	test "heap allocated frame" {
...	...	@@ -7889,7 +7987,7 @@ fn func() void {
7889	7987	Returns whether or not a {#link\|struct#}, {#link\|enum#}, or {#link\|union#} has a declaration
7890	7988	matching {#syntax#}name{#endsyntax#}.
7891	7989	</p>
7892		{#code_begin\|test#}
	7990	{#code_begin\|test\|hasDecl#}
7893	7991	const std = @import("std");
7894	7992	const expect = std.testing.expect;
7895	7993
...	...	@@ -8104,7 +8202,7 @@ mem.set(u8, dest, c);{#endsyntax#}</pre>
8104	8202	designers targeting Wasm. So unless you are writing a new allocator from scratch, you should use
8105	8203	something like {#syntax#}@import("std").heap.WasmPageAllocator{#endsyntax#}.
8106	8204	</p>
8107		{#code_begin\|test#}
	8205	{#code_begin\|test\|wasmMemoryGrow#}
8108	8206	const std = @import("std");
8109	8207	const native_arch = @import("builtin").target.cpu.arch;
8110	8208	const expect = std.testing.expect;
...	...	@@ -8291,7 +8389,7 @@ test "foo" {
8291	8389	}
8292	8390	{#code_end#}
8293	8391	<p>Now we use {#syntax#}@setEvalBranchQuota{#endsyntax#}:</p>
8294		{#code_begin\|test#}
	8392	{#code_begin\|test\|setEvalBranchQuota#}
8295	8393	test "foo" {
8296	8394	comptime {
8297	8395	@setEvalBranchQuota(1001);
...	...	@@ -8490,7 +8588,7 @@ test "@setRuntimeSafety" {
8490	8588	Produces a vector of length {#syntax#}len{#endsyntax#} where each element is the value
8491	8589	{#syntax#}scalar{#endsyntax#}:
8492	8590	</p>
8493		{#code_begin\|test#}
	8591	{#code_begin\|test\|vector_splat#}
8494	8592	const std = @import("std");
8495	8593	const expect = std.testing.expect;
8496	8594
...	...	@@ -8524,7 +8622,7 @@ test "vector @splat" {
8524	8622	<li>{#syntax#}.Min{#endsyntax#}, {#syntax#}.Max{#endsyntax#},
8525	8623	{#syntax#}.Add{#endsyntax#}, {#syntax#}.Mul{#endsyntax#} are
8526	8624	available for {#link\|floating point\|Floats#} vectors,</li>
8527		<li>Every operator is available for {#link\|integer\|Integers#} vectors.
	8625	<li>Every operator is available for {#link\|integer\|Integers#} vectors.</li>
8528	8626	</ul>
8529	8627	<p>
8530	8628	Note that {#syntax#}.Add{#endsyntax#} and {#syntax#}.Mul{#endsyntax#}
...	...	@@ -8532,7 +8630,7 @@ test "vector @splat" {
8532	8630	types the operation associativity is preserved, unless the float mode is
8533	8631	set to {#syntax#}Optimized{#endsyntax#}.
8534	8632	</p>
8535		{#code_begin\|test#}
	8633	{#code_begin\|test\|vector_reduce#}
8536	8634	const std = @import("std");
8537	8635	const expect = std.testing.expect;
8538	8636
...	...	@@ -8554,7 +8652,7 @@ test "vector @reduce" {
8554	8652	<p>
8555	8653	Returns a {#syntax#}SourceLocation{#endsyntax#} struct representing the function's name and location in the source code. This must be called in a function.
8556	8654	</p>
8557		{#code_begin\|test#}
	8655	{#code_begin\|test\|source_location#}
8558	8656	const std = @import("std");
8559	8657	const expect = std.testing.expect;
8560	8658
...	...	@@ -8568,7 +8666,7 @@ fn doTheTest() !void {
8568	8666	try expect(src.line == 9);
8569	8667	try expect(src.column == 17);
8570	8668	try expect(std.mem.endsWith(u8, src.fn_name, "doTheTest"));
8571		try expect(std.mem.endsWith(u8, src.file, "test.zig"));
	8669	try expect(std.mem.endsWith(u8, src.file, "source_location.zig"));
8572	8670	}
8573	8671	{#code_end#}
8574	8672	{#header_close#}
...	...	@@ -8749,7 +8847,7 @@ fn doTheTest() !void {
8749	8847	Returns the innermost struct, enum, or union that this function call is inside.
8750	8848	This can be useful for an anonymous struct that needs to refer to itself:
8751	8849	</p>
8752		{#code_begin\|test#}
	8850	{#code_begin\|test\|this_innermost#}
8753	8851	const std = @import("std");
8754	8852	const expect = std.testing.expect;
8755	8853
...	...	@@ -8884,7 +8982,7 @@ test "integer truncation" {
8884	8982	<p>
8885	8983	The expressions are evaluated, however they are guaranteed to have no <em>runtime</em> side-effects:
8886	8984	</p>
8887		{#code_begin\|test#}
	8985	{#code_begin\|test\|no_runtime_side_effects#}
8888	8986	const std = @import("std");
8889	8987	const expect = std.testing.expect;
8890	8988
...	...	@@ -8925,9 +9023,9 @@ fn foo(comptime T: type, ptr: *T) T {
8925	9023	<li>{#link\|ReleaseSmall#}</li>
8926	9024	</ul>
8927	9025	<p>
8928		To add standard build options to a <code>build.zig</code> file:
	9026	To add standard build options to a <code class="file">build.zig</code> file:
8929	9027	</p>
8930		{#code_begin\|syntax#}
	9028	{#code_begin\|syntax\|build#}
8931	9029	const Builder = @import("std").build.Builder;
8932	9030
8933	9031	pub fn build(b: *Builder) void {
...	...	@@ -8939,11 +9037,13 @@ pub fn build(b: *Builder) void {
8939	9037	<p>
8940	9038	This causes these options to be available:
8941	9039	</p>
8942		<pre><code class="shell"> -Drelease-safe=[bool] optimizations on and safety on
8943		-Drelease-fast=[bool] optimizations on and safety off
8944		-Drelease-small=[bool] size optimizations on and safety off</code></pre>
	9040	<dl>
	9041	<dt><kbd>-Drelease-safe=[bool]</kbd></dt><dd>Optimizations on and safety on</dd>
	9042	<dt><kbd>-Drelease-fast=[bool]</kbd></dt><dd>Optimizations on and safety off</dd>
	9043	<dt><kbd>-Drelease-small=[bool]</kbd></dt><dd>Size optimizations on and safety off</dd>
	9044	</dl>
8945	9045	{#header_open\|Debug#}
8946		<pre><code class="shell">$ zig build-exe example.zig</code></pre>
	9046	{#shell_samp#}$ zig build-exe example.zig{#end_shell_samp#}
8947	9047	<ul>
8948	9048	<li>Fast compilation speed</li>
8949	9049	<li>Safety checks enabled</li>
...	...	@@ -8953,7 +9053,7 @@ pub fn build(b: *Builder) void {
8953	9053	</ul>
8954	9054	{#header_close#}
8955	9055	{#header_open\|ReleaseFast#}
8956		<pre><code class="shell">$ zig build-exe example.zig -O ReleaseFast</code></pre>
	9056	{#shell_samp#}$ zig build-exe example.zig -O ReleaseFast{#end_shell_samp#}
8957	9057	<ul>
8958	9058	<li>Fast runtime performance</li>
8959	9059	<li>Safety checks disabled</li>
...	...	@@ -8963,7 +9063,7 @@ pub fn build(b: *Builder) void {
8963	9063	</ul>
8964	9064	{#header_close#}
8965	9065	{#header_open\|ReleaseSafe#}
8966		<pre><code class="shell">$ zig build-exe example.zig -O ReleaseSafe</code></pre>
	9066	{#shell_samp#}$ zig build-exe example.zig -O ReleaseSafe{#end_shell_samp#}
8967	9067	<ul>
8968	9068	<li>Medium runtime performance</li>
8969	9069	<li>Safety checks enabled</li>
...	...	@@ -8973,7 +9073,7 @@ pub fn build(b: *Builder) void {
8973	9073	</ul>
8974	9074	{#header_close#}
8975	9075	{#header_open\|ReleaseSmall#}
8976		<pre><code class="shell">$ zig build-exe example.zig -O ReleaseSmall</code></pre>
	9076	{#shell_samp#}$ zig build-exe example.zig -O ReleaseSmall{#end_shell_samp#}
8977	9077	<ul>
8978	9078	<li>Medium runtime performance</li>
8979	9079	<li>Safety checks disabled</li>
...	...	@@ -8986,7 +9086,7 @@ pub fn build(b: *Builder) void {
8986	9086	{#header_close#}
8987	9087
8988	9088	{#header_open\|Single Threaded Builds#}
8989		<p>Zig has a compile option <code>--single-threaded</code> which has the following effects:</p>
	9089	<p>Zig has a compile option <kbd>--single-threaded</kbd> which has the following effects:</p>
8990	9090	<ul>
8991	9091	<li>All {#link\|Thread Local Variables#} are treated as regular {#link\|Container Level Variables#}.</li>
8992	9092	<li>The overhead of {#link\|Async Functions#} becomes equivalent to function call overhead.</li>
...	...	@@ -9197,7 +9297,7 @@ pub fn main() void {
9197	9297	<li>{#syntax#}-%{#endsyntax#} (wraparound negation)</li>
9198	9298	<li>{#syntax#}*%{#endsyntax#} (wraparound multiplication)</li>
9199	9299	</ul>
9200		{#code_begin\|test#}
	9300	{#code_begin\|test\|wraparound_semantics#}
9201	9301	const std = @import("std");
9202	9302	const expect = std.testing.expect;
9203	9303	const minInt = std.math.minInt;
...	...	@@ -9935,14 +10035,14 @@ const separator = if (builtin.os.tag == builtin.Os.windows) '\\' else '/';
9935	10035	<li>Custom tasks.</li>
9936	10036	</ul>
9937	10037	<p>
9938		To use the build system, run <code class="shell">zig build --help</code>
	10038	To use the build system, run <kbd>zig build --help</kbd>
9939	10039	to see a command-line usage help menu. This will include project-specific
9940	10040	options that were declared in the build.zig script.
9941	10041	</p>
9942	10042
9943	10043	{#header_open\|Building an Executable#}
9944		<p>This <code>build.zig</code> file is automatically generated
9945		by <code>zig init-exe</code>.</p>
	10044	<p>This <code class="file">build.zig</code> file is automatically generated
	10045	by <kbd>zig init-exe</kbd>.</p>
9946	10046	{#code_begin\|syntax\|build#}
9947	10047	const Builder = @import("std").build.Builder;
9948	10048
...	...	@@ -9975,8 +10075,8 @@ pub fn build(b: *Builder) void {
9975	10075	{#header_close#}
9976	10076
9977	10077	{#header_open\|Building a Library#}
9978		<p>This <code>build.zig</code> file is automatically generated
9979		by <code>zig init-lib</code>.</p>
	10078	<p>This <code class="file">build.zig</code> file is automatically generated
	10079	by <kbd>zig init-lib</kbd>.</p>
9980	10080	{#code_begin\|syntax\|build#}
9981	10081	const Builder = @import("std").build.Builder;
9982	10082
...	...	@@ -10035,7 +10135,7 @@ lib.addCSourceFile("src/lib.c", &[_][]const u8{
10035	10135	{#header_open\|Import from C Header File#}
10036	10136	<p>
10037	10137	The {#syntax#}@cImport{#endsyntax#} builtin function can be used
10038		to directly import symbols from .h files:
	10138	to directly import symbols from <code class="file">.h</code> files:
10039	10139	</p>
10040	10140	{#code_begin\|exe#}
10041	10141	{#link_libc#}
...	...	@@ -10051,7 +10151,7 @@ pub fn main() void {
10051	10151	<p>
10052	10152	The {#syntax#}@cImport{#endsyntax#} function takes an expression as a parameter.
10053	10153	This expression is evaluated at compile-time and is used to control
10054		preprocessor directives and include multiple .h files:
	10154	preprocessor directives and include multiple <code class="file">.h</code> files:
10055	10155	</p>
10056	10156	{#code_begin\|syntax#}
10057	10157	const builtin = @import("builtin");
...	...	@@ -10072,66 +10172,65 @@ const c = @cImport({
10072	10172	{#header_close#}
10073	10173
10074	10174	{#header_open\|C Translation CLI#}
10075		Zig's C translation capability is available as a CLI tool via <code class="shell">zig translate-c</code>.
	10175	Zig's C translation capability is available as a CLI tool via <kbd>zig translate-c</kbd>.
10076	10176	It requires a single filename as an argument. It may also take a set of optional flags that are
10077	10177	forwarded to clang. It writes the translated file to stdout.
10078	10178	{#header_open\|Command line flags#}
10079	10179	<ul>
10080	10180	<li>
10081		<code class="shell">-I</code>:
	10181	<kbd>-I</kbd>:
10082	10182	Specify a search directory for include files. May be used multiple times. Equivalent to
10083	10183	<a href="https://releases.llvm.org/12.0.0/tools/clang/docs/ClangCommandLineReference.html#cmdoption-clang-i-dir">
10084		clang's <code>-I</code> flag</a>. The current directory is <em>not</em> included by default;
10085		use <code>-I.</code> to include it.
	10184	clang's <kbd>-I</kbd> flag</a>. The current directory is <em>not</em> included by default;
	10185	use <kbd>-I.</kbd> to include it.
10086	10186	</li>
10087	10187	<li>
10088		<code class="shell">-D</code>: Define a preprocessor macro. Equivalent to
	10188	<kbd>-D</kbd>: Define a preprocessor macro. Equivalent to
10089	10189	<a href="https://releases.llvm.org/12.0.0/tools/clang/docs/ClangCommandLineReference.html#cmdoption-clang-d-macro">
10090		clang's <code>-D</code> flag</a>.
	10190	clang's <kbd>-D</kbd> flag</a>.
10091	10191	</li>
10092	10192	<li>
10093		<code class="shell">-cflags [flags] --</code>: Pass arbitrary additional
	10193	<kbd>-cflags [flags] --</kbd>: Pass arbitrary additional
10094	10194	<a href="https://releases.llvm.org/12.0.0/tools/clang/docs/ClangCommandLineReference.html">command line
10095		flags</a> to clang. Note: the list of flags must end with <code>--</code>
	10195	flags</a> to clang. Note: the list of flags must end with <kbd>--</kbd>
10096	10196	</li>
10097	10197	<li>
10098		<code class="shell">-target</code>: The {#link\|target triple\|Targets#} for the translated Zig code.
	10198	<kbd>-target</kbd>: The {#link\|target triple\|Targets#} for the translated Zig code.
10099	10199	If no target is specified, the current host target will be used.
10100	10200	</li>
10101	10201	</ul>
10102	10202	{#header_close#}
10103	10203	{#header_open\|Using -target and -cflags#}
10104	10204	<p>
10105		<strong>Important!</strong> When translating C code with <code class="shell">zig translate-c</code>,
10106		you <strong>must</strong> use the same <code>-target</code> triple that you will use when compiling
10107		the translated code. In addition, you <strong>must</strong> ensure that the <code>-cflags</code> used,
10108		if any, match the cflags used by code on the target system. Using the incorrect <code>-target</code>
10109		or <code>-cflags</code> could result in clang or Zig parse failures, or subtle ABI incompatibilities
	10205	<strong>Important!</strong> When translating C code with <kbd>zig translate-c</kbd>,
	10206	you <strong>must</strong> use the same <kbd>-target</kbd> triple that you will use when compiling
	10207	the translated code. In addition, you <strong>must</strong> ensure that the <kbd>-cflags</kbd> used,
	10208	if any, match the cflags used by code on the target system. Using the incorrect <kbd>-target</kbd>
	10209	or <kbd>-cflags</kbd> could result in clang or Zig parse failures, or subtle ABI incompatibilities
10110	10210	when linking with C code.
10111	10211	</p>
10112		<p class="file">varytarget.h</p>
10113		<pre><code class="c">long FOO = __LONG_MAX__;</code></pre>
10114		<pre><code class="shell">$ zig translate-c -target <strong>thumb-freestanding-gnueabihf</strong> varytarget.h\|grep FOO
10115		pub export var FOO: c_long = <strong>2147483647</strong>;</code></pre>
10116		<pre><code class="shell">$ zig translate-c -target <strong>x86_64-macos-gnu</strong> varytarget.h\|grep FOO
10117		pub export var FOO: c_long = <strong>9223372036854775807</strong>;</code></pre>
10118		<p class="file">varycflags.h</p>
10119		<pre><code class="c">enum FOO { BAR };
10120		int do_something(enum FOO foo);</code></pre>
10121		<pre><code class="shell">$ zig translate-c varycflags.h\|grep -B1 do_something
10122		pub const enum_FOO = <strong>c_uint</strong>;
10123		pub extern fn do_something(foo: enum_FOO) c_int;</code></pre>
10124		<pre><code class="shell">$ zig translate-c <strong>-cflags -fshort-enums --</strong> varycflags.h\|grep -B1 do_something
10125		pub const enum_FOO = <strong>u8</strong>;
10126		pub extern fn do_something(foo: enum_FOO) c_int;</code></pre>
	10212	{#syntax_block\|c\|varytarget.h#}long FOO = __LONG_MAX__;{#end_syntax_block#}
	10213	{#shell_samp#}$ zig translate-c -target <em>thumb-freestanding-gnueabihf</em> varytarget.h\|grep FOO
	10214	pub export var FOO: c_long = <em>2147483647</em>;
	10215	$ zig translate-c -target <em>x86_64-macos-gnu</em> varytarget.h\|grep FOO
	10216	pub export var FOO: c_long = <em>9223372036854775807</em>;{#end_shell_samp#}
	10217	{#syntax_block\|c\|varycflags.h#}enum FOO { BAR };
	10218	int do_something(enum FOO foo);
	10219	{#end_syntax_block#}
	10220	{#shell_samp#}$ zig translate-c varycflags.h\|grep -B1 do_something
	10221	pub const enum_FOO = <em>c_uint</em>;
	10222	pub extern fn do_something(foo: enum_FOO) c_int;
	10223	$ zig translate-c <em>-cflags -fshort-enums --</em> varycflags.h\|grep -B1 do_something
	10224	pub const enum_FOO = <em>u8</em>;
	10225	pub extern fn do_something(foo: enum_FOO) c_int;{#end_shell_samp#}
10127	10226	{#header_close#}
10128	10227	{#header_open\|@cImport vs translate-c#}
10129		<p>{#syntax#}@cImport{#endsyntax#} and <code class="shell">zig translate-c</code> use the same underlying
	10228	<p>{#syntax#}@cImport{#endsyntax#} and <kbd>zig translate-c</kbd> use the same underlying
10130	10229	C translation functionality, so on a technical level they are equivalent. In practice,
10131	10230	{#syntax#}@cImport{#endsyntax#} is useful as a way to quickly and easily access numeric constants, typedefs,
10132	10231	and record types without needing any extra setup. If you need to pass {#link\|cflags\|Using -target and -cflags#}
10133	10232	to clang, or if you would like to edit the translated code, it is recommended to use
10134		<code class="shell">zig translate-c</code> and save the results to a file. Common reasons for editing
	10233	<kbd>zig translate-c</kbd> and save the results to a file. Common reasons for editing
10135	10234	the generated code include: changing {#syntax#}anytype{#endsyntax#} parameters in function-like macros to more
10136	10235	specific types; changing {#syntax#}[c]T{#endsyntax#} pointers to {#syntax#}[]T{#endsyntax#} or
10137	10236	{#syntax#}*T{#endsyntax#} pointers for improved type safety; and
...	...	@@ -10142,14 +10241,14 @@ pub extern fn do_something(foo: enum_FOO) c_int;</code></pre>
10142	10241	{#header_close#}
10143	10242	{#header_open\|C Translation Caching#}
10144	10243	<p>
10145		The C translation feature (whether used via <code class="shell">zig translate-c</code> or
	10244	The C translation feature (whether used via <kbd>zig translate-c</kbd> or
10146	10245	{#syntax#}@cImport{#endsyntax#}) integrates with the Zig caching system. Subsequent runs with
10147	10246	the same source file, target, and cflags will use the cache instead of repeatedly translating
10148	10247	the same code.
10149	10248	</p>
10150	10249	<p>
10151	10250	To see where the cached files are stored when compiling code that uses {#syntax#}@cImport{#endsyntax#},
10152		use the <code class="shell">--verbose-cimport</code> flag:
	10251	use the <kbd>--verbose-cimport</kbd> flag:
10153	10252	</p>
10154	10253	{#code_begin\|exe\|verbose#}
10155	10254	{#link_libc#}
...	...	@@ -10163,10 +10262,10 @@ pub fn main() void {
10163	10262	}
10164	10263	{#code_end#}
10165	10264	<p>
10166		<code class="shell">cimport.h</code> contains the file to translate (constructed from calls to
	10265	<code class="file">cimport.h</code> contains the file to translate (constructed from calls to
10167	10266	{#syntax#}@cInclude{#endsyntax#}, {#syntax#}@cDefine{#endsyntax#}, and {#syntax#}@cUndef{#endsyntax#}),
10168		<code class="shell">cimport.h.d</code> is the list of file dependencies, and
10169		<code class="shell">cimport.zig</code> contains the translated output.
	10267	<code class="file">cimport.h.d</code> is the list of file dependencies, and
	10268	<code class="file">cimport.zig</code> contains the translated output.
10170	10269	</p>
10171	10270	{#see_also\|Import from C Header File\|C Translation CLI\|@cInclude\|@cImport#}
10172	10271	{#header_close#}
...	...	@@ -10206,22 +10305,22 @@ pub fn main() void {
10206	10305	Zig.
10207	10306	</p>
10208	10307	<p>Consider the following example:</p>
10209		<p class="file">macro.c</p>
10210		<pre><code class="c">#define MAKELOCAL(NAME, INIT) int NAME = INIT
	10308	{#syntax_block\|c\|macro.c#}#define MAKELOCAL(NAME, INIT) int NAME = INIT
10211	10309	int foo(void) {
10212	10310	MAKELOCAL(a, 1);
10213	10311	MAKELOCAL(b, 2);
10214	10312	return a + b;
10215		}</code></pre>
10216		<pre><code class="shell">$ zig translate-c macro.c > macro.zig
10217		</code></pre>
10218		<p class="file">macro.zig</p>
10219		<pre>{#syntax#}pub export fn foo() c_int {
	10313	}
	10314	{#end_syntax_block#}
	10315	{#shell_samp#}$ zig translate-c macro.c > macro.zig{#end_shell_samp#}
	10316	{#code_begin\|syntax\|macro#}
	10317	pub export fn foo() c_int {
10220	10318	var a: c_int = 1;
10221	10319	var b: c_int = 2;
10222	10320	return a + b;
10223	10321	}
10224		pub const MAKELOCAL = @compileError("unable to translate C expr: unexpected token .Equal"); // macro.c:1:9{#endsyntax#}</pre>
	10322	pub const MAKELOCAL = @compileError("unable to translate C expr: unexpected token .Equal"); // macro.c:1:9
	10323	{#code_end#}
10225	10324	<p>Note that {#syntax#}foo{#endsyntax#} was translated correctly despite using a non-translateable
10226	10325	macro. {#syntax#}MAKELOCAL{#endsyntax#} was demoted to {#syntax#}@compileError{#endsyntax#} since
10227	10326	it cannot be expressed as a Zig function; this simply means that you cannot directly use
...	...	@@ -10272,31 +10371,27 @@ pub const MAKELOCAL = @compileError("unable to translate C expr: unexpected toke
10272	10371	to call into. The {#syntax#}export{#endsyntax#} keyword in front of functions, variables, and types causes them to
10273	10372	be part of the library API:
10274	10373	</p>
10275		<p class="file">mathtest.zig</p>
10276		{#code_begin\|syntax#}
	10374	{#code_begin\|syntax\|mathtest#}
10277	10375	export fn add(a: i32, b: i32) i32 {
10278	10376	return a + b;
10279	10377	}
10280	10378	{#code_end#}
10281	10379	<p>To make a static library:</p>
10282		<pre><code class="shell">$ zig build-lib mathtest.zig
10283		</code></pre>
	10380	{#shell_samp#}$ zig build-lib mathtest.zig{#end_shell_samp#}
10284	10381	<p>To make a shared library:</p>
10285		<pre><code class="shell">$ zig build-lib mathtest.zig -dynamic
10286		</code></pre>
	10382	{#shell_samp#}$ zig build-lib mathtest.zig -dynamic{#end_shell_samp#}
10287	10383	<p>Here is an example with the {#link\|Zig Build System#}:</p>
10288		<p class="file">test.c</p>
10289		<pre><code class="cpp">// This header is generated by zig from mathtest.zig
	10384	{#syntax_block\|c\|test.c#}// This header is generated by zig from mathtest.zig
10290	10385	#include "mathtest.h"
10291		#include <stdio.h>
	10386	#include <stdio.h>
10292	10387
10293	10388	int main(int argc, char **argv) {
10294	10389	int32_t result = add(42, 1337);
10295	10390	printf("%d\n", result);
10296	10391	return 0;
10297		}</code></pre>
10298		<p class="file">build.zig</p>
10299		{#code_begin\|syntax#}
	10392	}
	10393	{#end_syntax_block#}
	10394	{#code_begin\|syntax\|build#}
10300	10395	const Builder = @import("std").build.Builder;
10301	10396
10302	10397	pub fn build(b: *Builder) void {
...	...	@@ -10315,18 +10410,15 @@ pub fn build(b: *Builder) void {
10315	10410	test_step.dependOn(&run_cmd.step);
10316	10411	}
10317	10412	{#code_end#}
10318		<p class="file">terminal</p>
10319		<pre><code class="shell">$ zig build test
10320		1379
10321		</code></pre>
	10413	{#shell_samp#}$ zig build test
	10414	1379{#end_shell_samp#}
10322	10415	{#see_also\|export#}
10323	10416	{#header_close#}
10324	10417	{#header_open\|Mixing Object Files#}
10325	10418	<p>
10326	10419	You can mix Zig object files with any other object files that respect the C ABI. Example:
10327	10420	</p>
10328		<p class="file">base64.zig</p>
10329		{#code_begin\|syntax#}
	10421	{#code_begin\|syntax\|base64#}
10330	10422	const base64 = @import("std").base64;
10331	10423
10332	10424	export fn decode_base_64(
...	...	@@ -10343,12 +10435,11 @@ export fn decode_base_64(
10343	10435	return decoded_size;
10344	10436	}
10345	10437	{#code_end#}
10346		<p class="file">test.c</p>
10347		<pre><code class="cpp">// This header is generated by zig from base64.zig
	10438	{#syntax_block\|c\|test.c#}// This header is generated by zig from base64.zig
10348	10439	#include "base64.h"
10349	10440
10350		#include <string.h>
10351		#include <stdio.h>
	10441	#include <string.h>
	10442	#include <stdio.h>
10352	10443
10353	10444	int main(int argc, char **argv) {
10354	10445	const char *encoded = "YWxsIHlvdXIgYmFzZSBhcmUgYmVsb25nIHRvIHVz";
...	...	@@ -10359,9 +10450,9 @@ int main(int argc, char **argv) {
10359	10450	puts(buf);
10360	10451
10361	10452	return 0;
10362		}</code></pre>
10363		<p class="file">build.zig</p>
10364		{#code_begin\|syntax#}
	10453	}
	10454	{#end_syntax_block#}
	10455	{#code_begin\|syntax\|build#}
10365	10456	const Builder = @import("std").build.Builder;
10366	10457
10367	10458	pub fn build(b: *Builder) void {
...	...	@@ -10374,10 +10465,9 @@ pub fn build(b: *Builder) void {
10374	10465	exe.install();
10375	10466	}
10376	10467	{#code_end#}
10377		<p class="file">terminal</p>
10378		<pre><code class="shell">$ zig build
	10468	{#shell_samp#}$ zig build
10379	10469	$ ./zig-out/bin/test
10380		all your base are belong to us</code></pre>
	10470	all your base are belong to us{#end_shell_samp#}
10381	10471	{#see_also\|Targets\|Zig Build System#}
10382	10472	{#header_close#}
10383	10473	{#header_close#}
...	...	@@ -10395,9 +10485,7 @@ export fn add(a: i32, b: i32) void {
10395	10485	print(a + b);
10396	10486	}
10397	10487	{#code_end#}
10398		{#header_close#}
10399		<p class="file">test.js</p>
10400		<pre><code>const fs = require('fs');
	10488	{#syntax_block\|javascript\|test.js#}const fs = require('fs');
10401	10489	const source = fs.readFileSync("./math.wasm");
10402	10490	const typedArray = new Uint8Array(source);
10403	10491
...	...	@@ -10407,9 +10495,10 @@ WebAssembly.instantiate(typedArray, {
10407	10495	}}).then(result => {
10408	10496	const add = result.instance.exports.add;
10409	10497	add(1, 2);
10410		});</code></pre>
10411		<pre><code>$ node test.js
10412		The result is 3</code></pre>
	10498	});{#end_syntax_block#}
	10499	{#shell_samp#}$ node test.js
	10500	The result is 3{#end_shell_samp#}
	10501	{#header_close#}
10413	10502	{#header_open\|WASI#}
10414	10503	<p>Zig's support for WebAssembly System Interface (WASI) is under active development.
10415	10504	Example of using the standard library and reading command line arguments:</p>
...	...	@@ -10428,10 +10517,10 @@ pub fn main() !void {
10428	10517	}
10429	10518	}
10430	10519	{#code_end#}
10431		<pre><code>$ wasmtime args.wasm 123 hello
	10520	{#shell_samp#}$ wasmtime args.wasm 123 hello
10432	10521	0: args.wasm
10433	10522	1: 123
10434		2: hello</code></pre>
	10523	2: hello{#end_shell_samp#}
10435	10524	<p>A more interesting example would be extracting the list of preopens from the runtime.
10436	10525	This is now supported in the standard library via {#syntax#}std.fs.wasi.PreopenList{#endsyntax#}:</p>
10437	10526	{#code_begin\|exe\|preopens#}
...	...	@@ -10453,9 +10542,9 @@ pub fn main() !void {
10453	10542	}
10454	10543	}
10455	10544	{#code_end#}
10456		<pre><code>$ wasmtime --dir=. preopens.wasm
	10545	{#shell_samp#}$ wasmtime --dir=. preopens.wasm
10457	10546	0: Preopen{ .fd = 3, .type = PreopenType{ .Dir = '.' } }
10458		</code></pre>
	10547	{#end_shell_samp#}
10459	10548	{#header_close#}
10460	10549	{#header_close#}
10461	10550	{#header_open\|Targets#}
...	...	@@ -10464,7 +10553,7 @@ pub fn main() !void {
10464	10553	what it looks like to execute <code>zig targets</code> on a Linux x86_64
10465	10554	computer:
10466	10555	</p>
10467		<pre><code class="shell">$ zig targets
	10556	{#shell_samp#}$ zig targets
10468	10557	Architectures:
10469	10558	arm
10470	10559	v8_4a
...	...	@@ -10701,7 +10790,7 @@ Available libcs:
10701	10790	wasm32-wasi-musl
10702	10791	x86_64-linux-gnu
10703	10792	x86_64-linux-gnux32
10704		x86_64-linux-musl</code></pre>
	10793	x86_64-linux-musl{#end_shell_samp#}
10705	10794	<p>
10706	10795	The Zig Standard Library ({#syntax#}@import("std"){#endsyntax#}) has architecture, environment, and operating system
10707	10796	abstractions, and thus takes additional work to support more platforms.
...	...	@@ -10771,9 +10860,9 @@ coding style.
10771	10860	<p>
10772	10861	File names fall into two categories: types and namespaces. If the file
10773	10862	(implicitly a struct) has top level fields, it should be named like any
10774		other struct with fields using {#syntax#}TitleCase{#endsyntax#}. Otherwise,
10775		it should use {#syntax#}snake_case{#endsyntax#}. Directory names should be
10776		{#syntax#}snake_case{#endsyntax#}.
	10863	other struct with fields using <code class="file">TitleCase</code>. Otherwise,
	10864	it should use <code class="file">snake_case</code>. Directory names should be
	10865	<code class="file">snake_case</code>.
10777	10866	</p>
10778	10867	<p>
10779	10868	These are general rules of thumb; if it makes sense to do something different,
...	...	@@ -10782,7 +10871,7 @@ coding style.
10782	10871	</p>
10783	10872	{#header_close#}
10784	10873	{#header_open\|Examples#}
10785		<pre>{#syntax#}
	10874	{#syntax_block\|zig\|style_example.zig#}
10786	10875	const namespace_name = @import("dir_name/file_name.zig");
10787	10876	const TypeName = @import("dir_name/TypeName.zig");
10788	10877	var global_var: i32 = undefined;
...	...	@@ -10826,9 +10915,9 @@ const XmlParser = struct {
10826	10915
10827	10916	// The initials BE (Big Endian) are just another word in Zig identifier names.
10828	10917	fn readU32Be() u32 {}
10829		{#endsyntax#}</pre>
	10918	{#end_syntax_block#}
10830	10919	<p>
10831		See the Zig Standard Library for more examples.
	10920	See the {#link\|Zig Standard Library#} for more examples.
10832	10921	</p>
10833	10922	{#header_close#}
10834	10923	{#header_open\|Doc Comment Guidance#}
...	...	@@ -10863,7 +10952,7 @@ fn readU32Be() u32 {}
10863	10952	but use of hard tabs is discouraged. See {#link\|Grammar#}.
10864	10953	</p>
10865	10954	<p>
10866		Note that running <code>zig fmt</code> on a source file will implement all recommendations mentioned here.
	10955	Note that running <kbd>zig fmt</kbd> on a source file will implement all recommendations mentioned here.
10867	10956	Note also that the stage1 compiler does <a href="https://github.com/ziglang/zig/wiki/FAQ#why-does-zig-force-me-to-use-spaces-instead-of-tabs">not yet support CR or HT</a> control characters.
10868	10957	</p>
10869	10958	<p>
...	...	@@ -10881,18 +10970,18 @@ fn readU32Be() u32 {}
10881	10970	{#header_open\|Keyword Reference#}
10882	10971	<div class="table-wrapper">
10883	10972	<table>
	10973	<caption>Keywords</caption>
	10974	<thead>
10884	10975	<tr>
10885		<th>
10886		Keyword
10887		</th>
10888		<th>
10889		Description
10890		</th>
	10976	<th scope="col">Keyword</th>
	10977	<th scope="col">Description</th>
10891	10978	</tr>
	10979	</thead>
	10980	<tbody>
10892	10981	<tr>
10893		<td>
	10982	<th scope="row">
10894	10983	<pre>{#syntax#}align{#endsyntax#}</pre>
10895		</td>
	10984	</th>
10896	10985	<td>
10897	10986	{#syntax#}align{#endsyntax#} can be used to specify the alignment of a pointer.
10898	10987	It can also be used after a variable or function declaration to specify the alignment of pointers to that variable or function.
...	...	@@ -10902,9 +10991,9 @@ fn readU32Be() u32 {}
10902	10991	</td>
10903	10992	</tr>
10904	10993	<tr>
10905		<td>
	10994	<th scope="row">
10906	10995	<pre>{#syntax#}allowzero{#endsyntax#}</pre>
10907		</td>
	10996	</th>
10908	10997	<td>
10909	10998	The pointer attribute {#syntax#}allowzero{#endsyntax#} allows a pointer to have address zero.
10910	10999	<ul>
...	...	@@ -10913,9 +11002,9 @@ fn readU32Be() u32 {}
10913	11002	</td>
10914	11003	</tr>
10915	11004	<tr>
10916		<td>
	11005	<th scope="row">
10917	11006	<pre>{#syntax#}and{#endsyntax#}</pre>
10918		</td>
	11007	</th>
10919	11008	<td>
10920	11009	The boolean operator {#syntax#}and{#endsyntax#}.
10921	11010	<ul>
...	...	@@ -10924,9 +11013,9 @@ fn readU32Be() u32 {}
10924	11013	</td>
10925	11014	</tr>
10926	11015	<tr>
10927		<td>
	11016	<th scope="row">
10928	11017	<pre>{#syntax#}anyframe{#endsyntax#}</pre>
10929		</td>
	11018	</th>
10930	11019	<td>
10931	11020	{#syntax#}anyframe{#endsyntax#} can be used as a type for variables which hold pointers to function frames.
10932	11021	<ul>
...	...	@@ -10935,9 +11024,9 @@ fn readU32Be() u32 {}
10935	11024	</td>
10936	11025	</tr>
10937	11026	<tr>
10938		<td>
	11027	<th scope="row">
10939	11028	<pre>{#syntax#}anytype{#endsyntax#}</pre>
10940		</td>
	11029	</th>
10941	11030	<td>
10942	11031	Function parameters and struct fields can be declared with {#syntax#}anytype{#endsyntax#} in place of the type.
10943	11032	The type will be inferred where the function is called or the struct is instantiated.
...	...	@@ -10947,9 +11036,9 @@ fn readU32Be() u32 {}
10947	11036	</td>
10948	11037	</tr>
10949	11038	<tr>
10950		<td>
	11039	<th scope="row">
10951	11040	<pre>{#syntax#}asm{#endsyntax#}</pre>
10952		</td>
	11041	</th>
10953	11042	<td>
10954	11043	{#syntax#}asm{#endsyntax#} begins an inline assembly expression. This allows for directly controlling the machine code generated on compilation.
10955	11044	<ul>
...	...	@@ -10958,9 +11047,9 @@ fn readU32Be() u32 {}
10958	11047	</td>
10959	11048	</tr>
10960	11049	<tr>
10961		<td>
	11050	<th scope="row">
10962	11051	<pre>{#syntax#}async{#endsyntax#}</pre>
10963		</td>
	11052	</th>
10964	11053	<td>
10965	11054	{#syntax#}async{#endsyntax#} can be used before a function call to get a pointer to the function's frame when it suspends.
10966	11055	<ul>
...	...	@@ -10969,9 +11058,9 @@ fn readU32Be() u32 {}
10969	11058	</td>
10970	11059	</tr>
10971	11060	<tr>
10972		<td>
	11061	<th scope="row">
10973	11062	<pre>{#syntax#}await{#endsyntax#}</pre>
10974		</td>
	11063	</th>
10975	11064	<td>
10976	11065	{#syntax#}await{#endsyntax#} can be used to suspend the current function until the frame provided after the {#syntax#}await{#endsyntax#} completes.
10977	11066	{#syntax#}await{#endsyntax#} copies the value returned from the target function's frame to the caller.
...	...	@@ -10981,9 +11070,9 @@ fn readU32Be() u32 {}
10981	11070	</td>
10982	11071	</tr>
10983	11072	<tr>
10984		<td>
	11073	<th scope="row">
10985	11074	<pre>{#syntax#}break{#endsyntax#}</pre>
10986		</td>
	11075	</th>
10987	11076	<td>
10988	11077	{#syntax#}break{#endsyntax#} can be used with a block label to return a value from the block.
10989	11078	It can also be used to exit a loop before iteration completes naturally.
...	...	@@ -10993,9 +11082,9 @@ fn readU32Be() u32 {}
10993	11082	</td>
10994	11083	</tr>
10995	11084	<tr>
10996		<td>
	11085	<th scope="row">
10997	11086	<pre>{#syntax#}catch{#endsyntax#}</pre>
10998		</td>
	11087	</th>
10999	11088	<td>
11000	11089	{#syntax#}catch{#endsyntax#} can be used to evaluate an expression if the expression before it evaluates to an error.
11001	11090	The expression after the {#syntax#}catch{#endsyntax#} can optionally capture the error value.
...	...	@@ -11005,9 +11094,9 @@ fn readU32Be() u32 {}
11005	11094	</td>
11006	11095	</tr>
11007	11096	<tr>
11008		<td>
	11097	<th scope="row">
11009	11098	<pre>{#syntax#}comptime{#endsyntax#}</pre>
11010		</td>
	11099	</th>
11011	11100	<td>
11012	11101	{#syntax#}comptime{#endsyntax#} before a declaration can be used to label variables or function parameters as known at compile time.
11013	11102	It can also be used to guarantee an expression is run at compile time.
...	...	@@ -11017,9 +11106,9 @@ fn readU32Be() u32 {}
11017	11106	</td>
11018	11107	</tr>
11019	11108	<tr>
11020		<td>
	11109	<th scope="row">
11021	11110	<pre>{#syntax#}const{#endsyntax#}</pre>
11022		</td>
	11111	</th>
11023	11112	<td>
11024	11113	{#syntax#}const{#endsyntax#} declares a variable that can not be modified.
11025	11114	Used as a pointer attribute, it denotes the value referenced by the pointer cannot be modified.
...	...	@@ -11029,9 +11118,9 @@ fn readU32Be() u32 {}
11029	11118	</td>
11030	11119	</tr>
11031	11120	<tr>
11032		<td>
	11121	<th scope="row">
11033	11122	<pre>{#syntax#}continue{#endsyntax#}</pre>
11034		</td>
	11123	</th>
11035	11124	<td>
11036	11125	{#syntax#}continue{#endsyntax#} can be used in a loop to jump back to the beginning of the loop.
11037	11126	<ul>
...	...	@@ -11040,9 +11129,9 @@ fn readU32Be() u32 {}
11040	11129	</td>
11041	11130	</tr>
11042	11131	<tr>
11043		<td>
	11132	<th scope="row">
11044	11133	<pre>{#syntax#}defer{#endsyntax#}</pre>
11045		</td>
	11134	</th>
11046	11135	<td>
11047	11136	{#syntax#}defer{#endsyntax#} will execute an expression when control flow leaves the current block.
11048	11137	<ul>
...	...	@@ -11051,9 +11140,9 @@ fn readU32Be() u32 {}
11051	11140	</td>
11052	11141	</tr>
11053	11142	<tr>
11054		<td>
	11143	<th scope="row">
11055	11144	<pre>{#syntax#}else{#endsyntax#}</pre>
11056		</td>
	11145	</th>
11057	11146	<td>
11058	11147	{#syntax#}else{#endsyntax#} can be used to provide an alternate branch for {#syntax#}if{#endsyntax#}, {#syntax#}switch{#endsyntax#},
11059	11148	{#syntax#}while{#endsyntax#}, and {#syntax#}for{#endsyntax#} expressions.
...	...	@@ -11066,9 +11155,9 @@ fn readU32Be() u32 {}
11066	11155	</td>
11067	11156	</tr>
11068	11157	<tr>
11069		<td>
	11158	<th scope="row">
11070	11159	<pre>{#syntax#}enum{#endsyntax#}</pre>
11071		</td>
	11160	</th>
11072	11161	<td>
11073	11162	{#syntax#}enum{#endsyntax#} defines an enum type.
11074	11163	<ul>
...	...	@@ -11077,9 +11166,9 @@ fn readU32Be() u32 {}
11077	11166	</td>
11078	11167	</tr>
11079	11168	<tr>
11080		<td>
	11169	<th scope="row">
11081	11170	<pre>{#syntax#}errdefer{#endsyntax#}</pre>
11082		</td>
	11171	</th>
11083	11172	<td>
11084	11173	{#syntax#}errdefer{#endsyntax#} will execute an expression when control flow leaves the current block if the function returns an error.
11085	11174	<ul>
...	...	@@ -11088,9 +11177,9 @@ fn readU32Be() u32 {}
11088	11177	</td>
11089	11178	</tr>
11090	11179	<tr>
11091		<td>
	11180	<th scope="row">
11092	11181	<pre>{#syntax#}error{#endsyntax#}</pre>
11093		</td>
	11182	</th>
11094	11183	<td>
11095	11184	{#syntax#}error{#endsyntax#} defines an error type.
11096	11185	<ul>
...	...	@@ -11099,9 +11188,9 @@ fn readU32Be() u32 {}
11099	11188	</td>
11100	11189	</tr>
11101	11190	<tr>
11102		<td>
	11191	<th scope="row">
11103	11192	<pre>{#syntax#}export{#endsyntax#}</pre>
11104		</td>
	11193	</th>
11105	11194	<td>
11106	11195	{#syntax#}export{#endsyntax#} makes a function or variable externally visible in the generated object file.
11107	11196	Exported functions default to the C calling convention.
...	...	@@ -11111,9 +11200,9 @@ fn readU32Be() u32 {}
11111	11200	</td>
11112	11201	</tr>
11113	11202	<tr>
11114		<td>
	11203	<th scope="row">
11115	11204	<pre>{#syntax#}extern{#endsyntax#}</pre>
11116		</td>
	11205	</th>
11117	11206	<td>
11118	11207	{#syntax#}extern{#endsyntax#} can be used to declare a function or variable that will be resolved at link time, when linking statically
11119	11208	or at runtime, when linking dynamically.
...	...	@@ -11123,9 +11212,9 @@ fn readU32Be() u32 {}
11123	11212	</td>
11124	11213	</tr>
11125	11214	<tr>
11126		<td>
	11215	<th scope="row">
11127	11216	<pre>{#syntax#}false{#endsyntax#}</pre>
11128		</td>
	11217	</th>
11129	11218	<td>
11130	11219	The boolean value {#syntax#}false{#endsyntax#}.
11131	11220	<ul>
...	...	@@ -11134,9 +11223,9 @@ fn readU32Be() u32 {}
11134	11223	</td>
11135	11224	</tr>
11136	11225	<tr>
11137		<td>
	11226	<th scope="row">
11138	11227	<pre>{#syntax#}fn{#endsyntax#}</pre>
11139		</td>
	11228	</th>
11140	11229	<td>
11141	11230	{#syntax#}fn{#endsyntax#} declares a function.
11142	11231	<ul>
...	...	@@ -11145,9 +11234,9 @@ fn readU32Be() u32 {}
11145	11234	</td>
11146	11235	</tr>
11147	11236	<tr>
11148		<td>
	11237	<th scope="row">
11149	11238	<pre>{#syntax#}for{#endsyntax#}</pre>
11150		</td>
	11239	</th>
11151	11240	<td>
11152	11241	A {#syntax#}for{#endsyntax#} expression can be used to iterate over the elements of a slice, array, or tuple.
11153	11242	<ul>
...	...	@@ -11156,9 +11245,9 @@ fn readU32Be() u32 {}
11156	11245	</td>
11157	11246	</tr>
11158	11247	<tr>
11159		<td>
	11248	<th scope="row">
11160	11249	<pre>{#syntax#}if{#endsyntax#}</pre>
11161		</td>
	11250	</th>
11162	11251	<td>
11163	11252	An {#syntax#}if{#endsyntax#} expression can test boolean expressions, optional values, or error unions.
11164	11253	For optional values or error unions, the if expression can capture the unwrapped value.
...	...	@@ -11168,9 +11257,9 @@ fn readU32Be() u32 {}
11168	11257	</td>
11169	11258	</tr>
11170	11259	<tr>
11171		<td>
	11260	<th scope="row">
11172	11261	<pre>{#syntax#}inline{#endsyntax#}</pre>
11173		</td>
	11262	</th>
11174	11263	<td>
11175	11264	{#syntax#}inline{#endsyntax#} can be used to label a loop expression such that it will be unrolled at compile time.
11176	11265	It can also be used to force a function to be inlined at all call sites.
...	...	@@ -11180,9 +11269,9 @@ fn readU32Be() u32 {}
11180	11269	</td>
11181	11270	</tr>
11182	11271	<tr>
11183		<td>
	11272	<th scope="row">
11184	11273	<pre>{#syntax#}noalias{#endsyntax#}</pre>
11185		</td>
	11274	</th>
11186	11275	<td>
11187	11276	The {#syntax#}noalias{#endsyntax#} keyword.
11188	11277	<ul>
...	...	@@ -11191,9 +11280,9 @@ fn readU32Be() u32 {}
11191	11280	</td>
11192	11281	</tr>
11193	11282	<tr>
11194		<td>
	11283	<th scope="row">
11195	11284	<pre>{#syntax#}nosuspend{#endsyntax#}</pre>
11196		</td>
	11285	</th>
11197	11286	<td>
11198	11287	The {#syntax#}nosuspend{#endsyntax#} keyword can be used in front of a block, statement or expression, to mark a scope where no suspension points are reached.
11199	11288	In particular, inside a {#syntax#}nosuspend{#endsyntax#} scope:
...	...	@@ -11209,9 +11298,9 @@ fn readU32Be() u32 {}
11209	11298	</td>
11210	11299	</tr>
11211	11300	<tr>
11212		<td>
	11301	<th scope="row">
11213	11302	<pre>{#syntax#}null{#endsyntax#}</pre>
11214		</td>
	11303	</th>
11215	11304	<td>
11216	11305	The optional value {#syntax#}null{#endsyntax#}.
11217	11306	<ul>
...	...	@@ -11220,9 +11309,9 @@ fn readU32Be() u32 {}
11220	11309	</td>
11221	11310	</tr>
11222	11311	<tr>
11223		<td>
	11312	<th scope="row">
11224	11313	<pre>{#syntax#}or{#endsyntax#}</pre>
11225		</td>
	11314	</th>
11226	11315	<td>
11227	11316	The boolean operator {#syntax#}or{#endsyntax#}.
11228	11317	<ul>
...	...	@@ -11231,9 +11320,9 @@ fn readU32Be() u32 {}
11231	11320	</td>
11232	11321	</tr>
11233	11322	<tr>
11234		<td>
	11323	<th scope="row">
11235	11324	<pre>{#syntax#}orelse{#endsyntax#}</pre>
11236		</td>
	11325	</th>
11237	11326	<td>
11238	11327	{#syntax#}orelse{#endsyntax#} can be used to evaluate an expression if the expression before it evaluates to null.
11239	11328	<ul>
...	...	@@ -11242,9 +11331,9 @@ fn readU32Be() u32 {}
11242	11331	</td>
11243	11332	</tr>
11244	11333	<tr>
11245		<td>
	11334	<th scope="row">
11246	11335	<pre>{#syntax#}packed{#endsyntax#}</pre>
11247		</td>
	11336	</th>
11248	11337	<td>
11249	11338	The {#syntax#}packed{#endsyntax#} keyword before a struct definition changes the struct's in-memory layout
11250	11339	to the guaranteed {#syntax#}packed{#endsyntax#} layout.
...	...	@@ -11254,9 +11343,9 @@ fn readU32Be() u32 {}
11254	11343	</td>
11255	11344	</tr>
11256	11345	<tr>
11257		<td>
	11346	<th scope="row">
11258	11347	<pre>{#syntax#}pub{#endsyntax#}</pre>
11259		</td>
	11348	</th>
11260	11349	<td>
11261	11350	The {#syntax#}pub{#endsyntax#} in front of a top level declaration makes the declaration available
11262	11351	to reference from a different file than the one it is declared in.
...	...	@@ -11266,9 +11355,9 @@ fn readU32Be() u32 {}
11266	11355	</td>
11267	11356	</tr>
11268	11357	<tr>
11269		<td>
	11358	<th scope="row">
11270	11359	<pre>{#syntax#}resume{#endsyntax#}</pre>
11271		</td>
	11360	</th>
11272	11361	<td>
11273	11362	{#syntax#}resume{#endsyntax#} will continue execution of a function frame after the point the function was suspended.
11274	11363	<ul>
...	...	@@ -11277,9 +11366,9 @@ fn readU32Be() u32 {}
11277	11366	</td>
11278	11367	</tr>
11279	11368	<tr>
11280		<td>
	11369	<th scope="row">
11281	11370	<pre>{#syntax#}return{#endsyntax#}</pre>
11282		</td>
	11371	</th>
11283	11372	<td>
11284	11373	{#syntax#}return{#endsyntax#} exits a function with a value.
11285	11374	<ul>
...	...	@@ -11288,9 +11377,9 @@ fn readU32Be() u32 {}
11288	11377	</td>
11289	11378	</tr>
11290	11379	<tr>
11291		<td>
	11380	<th scope="row">
11292	11381	<pre>{#syntax#}linksection{#endsyntax#}</pre>
11293		</td>
	11382	</th>
11294	11383	<td>
11295	11384	The {#syntax#}linksection{#endsyntax#} keyword.
11296	11385	<ul>
...	...	@@ -11299,9 +11388,9 @@ fn readU32Be() u32 {}
11299	11388	</td>
11300	11389	</tr>
11301	11390	<tr>
11302		<td>
	11391	<th scope="row">
11303	11392	<pre>{#syntax#}struct{#endsyntax#}</pre>
11304		</td>
	11393	</th>
11305	11394	<td>
11306	11395	{#syntax#}struct{#endsyntax#} defines a struct.
11307	11396	<ul>
...	...	@@ -11310,9 +11399,9 @@ fn readU32Be() u32 {}
11310	11399	</td>
11311	11400	</tr>
11312	11401	<tr>
11313		<td>
	11402	<th scope="row">
11314	11403	<pre>{#syntax#}suspend{#endsyntax#}</pre>
11315		</td>
	11404	</th>
11316	11405	<td>
11317	11406	{#syntax#}suspend{#endsyntax#} will cause control flow to return to the call site or resumer of the function.
11318	11407	{#syntax#}suspend{#endsyntax#} can also be used before a block within a function,
...	...	@@ -11323,9 +11412,9 @@ fn readU32Be() u32 {}
11323	11412	</td>
11324	11413	</tr>
11325	11414	<tr>
11326		<td>
	11415	<th scope="row">
11327	11416	<pre>{#syntax#}switch{#endsyntax#}</pre>
11328		</td>
	11417	</th>
11329	11418	<td>
11330	11419	A {#syntax#}switch{#endsyntax#} expression can be used to test values of a common type.
11331	11420	{#syntax#}switch{#endsyntax#} cases can capture field values of a {#link\|Tagged union#}.
...	...	@@ -11335,9 +11424,9 @@ fn readU32Be() u32 {}
11335	11424	</td>
11336	11425	</tr>
11337	11426	<tr>
11338		<td>
	11427	<th scope="row">
11339	11428	<pre>{#syntax#}test{#endsyntax#}</pre>
11340		</td>
	11429	</th>
11341	11430	<td>
11342	11431	The {#syntax#}test{#endsyntax#} keyword can be used to denote a top-level block of code
11343	11432	used to make sure behavior meets expectations.
...	...	@@ -11347,9 +11436,9 @@ fn readU32Be() u32 {}
11347	11436	</td>
11348	11437	</tr>
11349	11438	<tr>
11350		<td>
	11439	<th scope="row">
11351	11440	<pre>{#syntax#}threadlocal{#endsyntax#}</pre>
11352		</td>
	11441	</th>
11353	11442	<td>
11354	11443	{#syntax#}threadlocal{#endsyntax#} can be used to specify a variable as thread-local.
11355	11444	<ul>
...	...	@@ -11358,9 +11447,9 @@ fn readU32Be() u32 {}
11358	11447	</td>
11359	11448	</tr>
11360	11449	<tr>
11361		<td>
	11450	<th scope="row">
11362	11451	<pre>{#syntax#}true{#endsyntax#}</pre>
11363		</td>
	11452	</th>
11364	11453	<td>
11365	11454	The boolean value {#syntax#}true{#endsyntax#}.
11366	11455	<ul>
...	...	@@ -11369,9 +11458,9 @@ fn readU32Be() u32 {}
11369	11458	</td>
11370	11459	</tr>
11371	11460	<tr>
11372		<td>
	11461	<th scope="row">
11373	11462	<pre>{#syntax#}try{#endsyntax#}</pre>
11374		</td>
	11463	</th>
11375	11464	<td>
11376	11465	{#syntax#}try{#endsyntax#} evaluates an error union expression.
11377	11466	If it is an error, it returns from the current function with the same error.
...	...	@@ -11382,9 +11471,9 @@ fn readU32Be() u32 {}
11382	11471	</td>
11383	11472	</tr>
11384	11473	<tr>
11385		<td>
	11474	<th scope="row">
11386	11475	<pre>{#syntax#}undefined{#endsyntax#}</pre>
11387		</td>
	11476	</th>
11388	11477	<td>
11389	11478	{#syntax#}undefined{#endsyntax#} can be used to leave a value uninitialized.
11390	11479	<ul>
...	...	@@ -11393,9 +11482,9 @@ fn readU32Be() u32 {}
11393	11482	</td>
11394	11483	</tr>
11395	11484	<tr>
11396		<td>
	11485	<th scope="row">
11397	11486	<pre>{#syntax#}union{#endsyntax#}</pre>
11398		</td>
	11487	</th>
11399	11488	<td>
11400	11489	{#syntax#}union{#endsyntax#} defines a union.
11401	11490	<ul>
...	...	@@ -11404,23 +11493,23 @@ fn readU32Be() u32 {}
11404	11493	</td>
11405	11494	</tr>
11406	11495	<tr>
11407		<td>
	11496	<th scope="row">
11408	11497	<pre>{#syntax#}unreachable{#endsyntax#}</pre>
11409		</td>
	11498	</th>
11410	11499	<td>
11411	11500	{#syntax#}unreachable{#endsyntax#} can be used to assert that control flow will never happen upon a particular location.
11412	11501	Depending on the build mode, {#syntax#}unreachable{#endsyntax#} may emit a panic.
11413	11502	<ul>
11414		<li>Emits a panic in {#syntax#}Debug{#endsyntax#} and {#syntax#}ReleaseSafe{#endsyntax#} mode, or when using <code>zig test</code>.</li>
11415		<li>Does not emit a panic in {#syntax#}ReleaseFast{#endsyntax#} mode, unless <code>zig test</code> is being used.</li>
	11503	<li>Emits a panic in {#syntax#}Debug{#endsyntax#} and {#syntax#}ReleaseSafe{#endsyntax#} mode, or when using <kbd>zig test</kbd>.</li>
	11504	<li>Does not emit a panic in {#syntax#}ReleaseFast{#endsyntax#} mode, unless <kbd>zig test</kbd> is being used.</li>
11416	11505	<li>See also {#link\|unreachable#}</li>
11417	11506	</ul>
11418	11507	</td>
11419	11508	</tr>
11420	11509	<tr>
11421		<td>
	11510	<th scope="row">
11422	11511	<pre>{#syntax#}usingnamespace{#endsyntax#}</pre>
11423		</td>
	11512	</th>
11424	11513	<td>
11425	11514	{#syntax#}usingnamespace{#endsyntax#} is a top-level declaration that imports all the public declarations of the operand,
11426	11515	which must be a struct, union, or enum, into the current scope.
...	...	@@ -11430,9 +11519,9 @@ fn readU32Be() u32 {}
11430	11519	</td>
11431	11520	</tr>
11432	11521	<tr>
11433		<td>
	11522	<th scope="row">
11434	11523	<pre>{#syntax#}var{#endsyntax#}</pre>
11435		</td>
	11524	</th>
11436	11525	<td>
11437	11526	{#syntax#}var{#endsyntax#} declares a variable that may be modified.
11438	11527	<ul>
...	...	@@ -11441,9 +11530,9 @@ fn readU32Be() u32 {}
11441	11530	</td>
11442	11531	</tr>
11443	11532	<tr>
11444		<td>
	11533	<th scope="row">
11445	11534	<pre>{#syntax#}volatile{#endsyntax#}</pre>
11446		</td>
	11535	</th>
11447	11536	<td>
11448	11537	{#syntax#}volatile{#endsyntax#} can be used to denote loads or stores of a pointer have side effects.
11449	11538	It can also modify an inline assembly expression to denote it has side effects.
...	...	@@ -11453,9 +11542,9 @@ fn readU32Be() u32 {}
11453	11542	</td>
11454	11543	</tr>
11455	11544	<tr>
11456		<td>
	11545	<th scope="row">
11457	11546	<pre>{#syntax#}while{#endsyntax#}</pre>
11458		</td>
	11547	</th>
11459	11548	<td>
11460	11549	A {#syntax#}while{#endsyntax#} expression can be used to repeatedly test a boolean, optional, or error union expression,
11461	11550	and cease looping when that expression evaluates to false, null, or an error, respectively.
...	...	@@ -11464,6 +11553,7 @@ fn readU32Be() u32 {}
11464	11553	</ul>
11465	11554	</td>
11466	11555	</tr>
	11556	</tbody>
11467	11557	</table>
11468	11558	</div>
11469	11559	{#header_close#}
...	...	@@ -12034,7 +12124,7 @@ keyword <- KEYWORD_align / KEYWORD_allowzero / KEYWORD_and / KEYWORD_anyframe
12034	12124	<li>Together we serve the users.</li>
12035	12125	</ul>
12036	12126	{#header_close#}
12037		</div></div>
	12127	</main></div>
12038	12128	</div>
12039	12129	</body>
12040	12130	</html>