authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2018-01-16 23:19:05-05:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2018-01-17 00:22:53-05:00
log2774fe8a1b5364729ad9faa1562e280f348c68bd
tree4888564682be6845d96a3e897df7c361b5b3519a
parent4bdfc8a10aec3c7bd02037312840315a5fccbbb0

docgen auto generates table of contents

See #465

3 files changed, 699 insertions(+), 400 deletions(-)

doc/docgen.zig+368-20
......@@ -1,10 +1,14 @@
11const std = @import("std");
22const io = std.io;
33const os = std.os;
4const warn = std.debug.warn;
5const mem = std.mem;
6
7pub const max_doc_file_size = 10 * 1024 * 1024;
48
59pub fn main() -> %void {
610 // TODO use a more general purpose allocator here
7 var inc_allocator = try std.heap.IncrementingAllocator.init(5 * 1024 * 1024);
11 var inc_allocator = try std.heap.IncrementingAllocator.init(max_doc_file_size);
812 defer inc_allocator.deinit();
913 const allocator = &inc_allocator.allocator;
1014
......@@ -25,39 +29,383 @@ pub fn main() -> %void {
2529 defer out_file.close();
2630
2731 var file_in_stream = io.FileInStream.init(&in_file);
28 var buffered_in_stream = io.BufferedInStream.init(&file_in_stream.stream);
32
33 const input_file_bytes = try file_in_stream.stream.readAllAlloc(allocator, max_doc_file_size);
2934
3035 var file_out_stream = io.FileOutStream.init(&out_file);
3136 var buffered_out_stream = io.BufferedOutStream.init(&file_out_stream.stream);
3237
33 gen(&buffered_in_stream.stream, &buffered_out_stream.stream);
34 try buffered_out_stream.flush();
38 const toc = try genToc(allocator, in_file_name, input_file_bytes);
3539
40 try genHtml(allocator, toc, &buffered_out_stream.stream);
41 try buffered_out_stream.flush();
3642}
3743
38const State = enum {
39 Start,
40 Derp,
44const Token = struct {
45 id: Id,
46 start: usize,
47 end: usize,
48
49 const Id = enum {
50 Invalid,
51 Content,
52 BracketOpen,
53 TagContent,
54 Separator,
55 BracketClose,
56 Eof,
57 };
4158};
4259
43// TODO look for code segments
60const Tokenizer = struct {
61 buffer: []const u8,
62 index: usize,
63 state: State,
64 source_file_name: []const u8,
4465
45fn gen(in: &io.InStream, out: &io.OutStream) {
46 var state = State.Start;
47 while (true) {
48 const byte = in.readByte() catch |err| {
49 if (err == error.EndOfStream) {
50 return;
51 }
52 std.debug.panic("{}", err);
66 const State = enum {
67 Start,
68 LBracket,
69 Hash,
70 TagName,
71 Eof,
72 };
73
74 fn init(source_file_name: []const u8, buffer: []const u8) -> Tokenizer {
75 return Tokenizer {
76 .buffer = buffer,
77 .index = 0,
78 .state = State.Start,
79 .source_file_name = source_file_name,
80 };
81 }
82
83 fn next(self: &Tokenizer) -> Token {
84 var result = Token {
85 .id = Token.Id.Eof,
86 .start = self.index,
87 .end = undefined,
5388 };
54 switch (state) {
55 State.Start => switch (byte) {
89 while (self.index < self.buffer.len) : (self.index += 1) {
90 const c = self.buffer[self.index];
91 switch (self.state) {
92 State.Start => switch (c) {
93 '{' => {
94 self.state = State.LBracket;
95 },
96 else => {
97 result.id = Token.Id.Content;
98 },
99 },
100 State.LBracket => switch (c) {
101 '#' => {
102 if (result.id != Token.Id.Eof) {
103 self.index -= 1;
104 self.state = State.Start;
105 break;
106 } else {
107 result.id = Token.Id.BracketOpen;
108 self.index += 1;
109 self.state = State.TagName;
110 break;
111 }
112 },
113 else => {
114 result.id = Token.Id.Content;
115 self.state = State.Start;
116 },
117 },
118 State.TagName => switch (c) {
119 '|' => {
120 if (result.id != Token.Id.Eof) {
121 break;
122 } else {
123 result.id = Token.Id.Separator;
124 self.index += 1;
125 break;
126 }
127 },
128 '#' => {
129 self.state = State.Hash;
130 },
131 else => {
132 result.id = Token.Id.TagContent;
133 },
134 },
135 State.Hash => switch (c) {
136 '}' => {
137 if (result.id != Token.Id.Eof) {
138 self.index -= 1;
139 self.state = State.TagName;
140 break;
141 } else {
142 result.id = Token.Id.BracketClose;
143 self.index += 1;
144 self.state = State.Start;
145 break;
146 }
147 },
148 else => {
149 result.id = Token.Id.TagContent;
150 self.state = State.TagName;
151 },
152 },
153 State.Eof => unreachable,
154 }
155 } else {
156 switch (self.state) {
157 State.Start, State.LBracket, State.Eof => {},
56158 else => {
57 out.writeByte(byte) catch unreachable;
159 result.id = Token.Id.Invalid;
58160 },
161 }
162 self.state = State.Eof;
163 }
164 result.end = self.index;
165 return result;
166 }
167
168 const Location = struct {
169 line: usize,
170 column: usize,
171 line_start: usize,
172 line_end: usize,
173 };
174
175 fn getTokenLocation(self: &Tokenizer, token: &const Token) -> Location {
176 var loc = Location {
177 .line = 0,
178 .column = 0,
179 .line_start = 0,
180 .line_end = 0,
181 };
182 for (self.buffer) |c, i| {
183 if (i == token.start) {
184 loc.line_end = i;
185 while (loc.line_end < self.buffer.len and self.buffer[loc.line_end] != '\n') : (loc.line_end += 1) {}
186 return loc;
187 }
188 if (c == '\n') {
189 loc.line += 1;
190 loc.column = 0;
191 loc.line_start = i + 1;
192 } else {
193 loc.column += 1;
194 }
195 }
196 return loc;
197 }
198};
199
200error ParseError;
201
202fn parseError(tokenizer: &Tokenizer, token: &const Token, comptime fmt: []const u8, args: ...) -> error {
203 const loc = tokenizer.getTokenLocation(token);
204 warn("{}:{}:{}: error: " ++ fmt ++ "\n", tokenizer.source_file_name, loc.line + 1, loc.column + 1, args);
205 if (loc.line_start <= loc.line_end) {
206 warn("{}\n", tokenizer.buffer[loc.line_start..loc.line_end]);
207 {
208 var i: usize = 0;
209 while (i < loc.column) : (i += 1) {
210 warn(" ");
211 }
212 }
213 {
214 const caret_count = token.end - token.start;
215 var i: usize = 0;
216 while (i < caret_count) : (i += 1) {
217 warn("~");
218 }
219 }
220 warn("\n");
221 }
222 return error.ParseError;
223}
224
225fn assertToken(tokenizer: &Tokenizer, token: &const Token, id: Token.Id) -> %void {
226 if (token.id != id) {
227 return parseError(tokenizer, token, "expected {}, found {}", @tagName(id), @tagName(token.id));
228 }
229}
230
231fn eatToken(tokenizer: &Tokenizer, id: Token.Id) -> %Token {
232 const token = tokenizer.next();
233 try assertToken(tokenizer, token, id);
234 return token;
235}
236
237const HeaderOpen = struct {
238 name: []const u8,
239 url: []const u8,
240 n: usize,
241};
242
243const Tag = enum {
244 Nav,
245 HeaderOpen,
246 HeaderClose,
247};
248
249const Node = union(enum) {
250 Content: []const u8,
251 Nav,
252 HeaderOpen: HeaderOpen,
253};
254
255const Toc = struct {
256 nodes: []Node,
257 toc: []u8,
258};
259
260const Action = enum {
261 Open,
262 Close,
263};
264
265fn genToc(allocator: &mem.Allocator, source_file_name: []const u8, input_file_bytes: []const u8) -> %Toc {
266 var tokenizer = Tokenizer.init(source_file_name, input_file_bytes);
267
268 var urls = std.HashMap([]const u8, Token, mem.hash_slice_u8, mem.eql_slice_u8).init(allocator);
269 defer urls.deinit();
270
271 var header_stack_size: usize = 0;
272 var last_action = Action.Open;
273
274 var toc_buf = try std.Buffer.initSize(allocator, 0);
275 defer toc_buf.deinit();
276
277 var toc_buf_adapter = io.BufferOutStream.init(&toc_buf);
278 var toc = &toc_buf_adapter.stream;
279
280 var nodes = std.ArrayList(Node).init(allocator);
281 defer nodes.deinit();
282
283 try toc.writeByte('\n');
284
285 while (true) {
286 const token = tokenizer.next();
287 switch (token.id) {
288 Token.Id.Eof => {
289 if (header_stack_size != 0) {
290 return parseError(&tokenizer, token, "unbalanced headers");
291 }
292 try toc.write(" </ul>\n");
293 break;
294 },
295 Token.Id.Content => {
296 try nodes.append(Node {.Content = input_file_bytes[token.start..token.end] });
297 },
298 Token.Id.BracketOpen => {
299 const tag_token = try eatToken(&tokenizer, Token.Id.TagContent);
300 const tag_name = input_file_bytes[tag_token.start..tag_token.end];
301
302 var tag: Tag = undefined;
303 if (mem.eql(u8, tag_name, "nav")) {
304 tag = Tag.Nav;
305 } else if (mem.eql(u8, tag_name, "header_open")) {
306 tag = Tag.HeaderOpen;
307 header_stack_size += 1;
308 } else if (mem.eql(u8, tag_name, "header_close")) {
309 if (header_stack_size == 0) {
310 return parseError(&tokenizer, tag_token, "unbalanced close header");
311 }
312 header_stack_size -= 1;
313 tag = Tag.HeaderClose;
314 } else {
315 return parseError(&tokenizer, tag_token, "unrecognized tag name: {}", tag_name);
316 }
317
318 var tag_content: ?[]const u8 = null;
319 const maybe_sep = tokenizer.next();
320 if (maybe_sep.id == Token.Id.Separator) {
321 const content_token = try eatToken(&tokenizer, Token.Id.TagContent);
322 tag_content = input_file_bytes[content_token.start..content_token.end];
323 _ = eatToken(&tokenizer, Token.Id.BracketClose);
324 } else {
325 try assertToken(&tokenizer, maybe_sep, Token.Id.BracketClose);
326 }
327
328 switch (tag) {
329 Tag.HeaderOpen => {
330 const content = tag_content ?? return parseError(&tokenizer, tag_token, "expected header content");
331 const urlized = try urlize(allocator, content);
332 try nodes.append(Node{.HeaderOpen = HeaderOpen {
333 .name = content,
334 .url = urlized,
335 .n = header_stack_size,
336 }});
337 if (try urls.put(urlized, tag_token)) |other_tag_token| {
338 parseError(&tokenizer, tag_token, "duplicate header url: #{}", urlized) catch {};
339 parseError(&tokenizer, other_tag_token, "other tag here") catch {};
340 return error.ParseError;
341 }
342 if (last_action == Action.Open) {
343 try toc.writeByte('\n');
344 try toc.writeByteNTimes(' ', header_stack_size * 4);
345 try toc.write("<ul>\n");
346 } else {
347 last_action = Action.Open;
348 }
349 try toc.writeByteNTimes(' ', 4 + header_stack_size * 4);
350 try toc.print("<li><a href=\"#{}\">{}</a>", urlized, content);
351 },
352 Tag.HeaderClose => {
353 if (last_action == Action.Close) {
354 try toc.writeByteNTimes(' ', 8 + header_stack_size * 4);
355 try toc.write("</ul></li>\n");
356 } else {
357 try toc.write("</li>\n");
358 last_action = Action.Close;
359 }
360 },
361 Tag.Nav => {
362 try nodes.append(Node.Nav);
363 },
364 }
365 },
366 else => return parseError(&tokenizer, token, "invalid token"),
367 }
368 }
369
370 return Toc {
371 .nodes = nodes.toOwnedSlice(),
372 .toc = toc_buf.toOwnedSlice(),
373 };
374}
375
376fn urlize(allocator: &mem.Allocator, input: []const u8) -> %[]u8 {
377 var buf = try std.Buffer.initSize(allocator, 0);
378 defer buf.deinit();
379
380 var buf_adapter = io.BufferOutStream.init(&buf);
381 var out = &buf_adapter.stream;
382 for (input) |c| {
383 switch (c) {
384 'a'...'z', 'A'...'Z', '_', '-' => {
385 try out.writeByte(c);
386 },
387 ' ' => {
388 try out.writeByte('-');
389 },
390 else => {},
391 }
392 }
393 return buf.toOwnedSlice();
394}
395
396fn genHtml(allocator: &mem.Allocator, toc: &const Toc, out: &io.OutStream) -> %void {
397 for (toc.nodes) |node| {
398 switch (node) {
399 Node.Content => |data| {
400 try out.write(data);
401 },
402 Node.Nav => {
403 try out.write(toc.toc);
404 },
405 Node.HeaderOpen => |info| {
406 try out.print("<h{} id=\"{}\">{}</h{}>\n", info.n, info.url, info.name, info.n);
59407 },
60 State.Derp => unreachable,
61408 }
62409 }
410
63411}
doc/langref.html.in+330-378
......@@ -31,221 +31,10 @@
3131 </head>
3232 <body>
3333 <div id="nav">
34 <ul>
35 <li><a href="#introduction">Introduction</a></li>
36 <li><a href="#hello-world">Hello World</a></li>
37 <li><a href="#source-encoding">Source Encoding</a></li>
38 <li><a href="#values">Values</a></li>
39 <ul>
40 <li><a href="#primitive-types">Primitive Types</a></li>
41 <li><a href="#primitive-values">Primitive Values</a></li>
42 <li><a href="#string-literals">String Literals</a>
43 <ul>
44 <li><a href="#string-literal-escapes">Escape Sequences</a></li>
45 <li><a href="#multiline-string-literals">Multiline String Literals</a></li>
46 </ul>
47 </li>
48 <li><a href="#values-assignment">Assignment</a></li>
49 </ul>
50 </li>
51 <li><a href="#integers">Integers</a>
52 <ul>
53 <li><a href="#integer-literals">Integer Literals</a></li>
54 <li><a href="#runtime-integer-values">Runtime Integer Values</a></li>
55 </ul>
56 </li>
57 <li><a href="#floats">Floats</a>
58 <ul>
59 <li><a href="#float-literals">Float Literals</a></li>
60 <li><a href="#float-operations">Floating Point Operations</a></li>
61 </ul>
62 </li>
63 <li><a href="#operators">Operators</a>
64 <ul>
65 <li><a href="#operators-table">Table of Operators</a></li>
66 <li><a href="#operators-precedence">Precedence</a></li>
67 </ul>
68 </li>
69 <li><a href="#arrays">Arrays</a></li>
70 <li><a href="#pointers">Pointers</a>
71 <ul>
72 <li><a href="#alignment">Alignment</a></li>
73 <li><a href="#type-based-alias-analysis">Type Based Alias Analysis</a></li>
74 </ul>
75 </li>
76 <li><a href="#slices">Slices</a></li>
77 <li><a href="#struct">struct</a></li>
78 <li><a href="#enum">enum</a></li>
79 <li><a href="#union">union</a></li>
80 <li><a href="#switch">switch</a></li>
81 <li><a href="#while">while</a></li>
82 <li><a href="#for">for</a></li>
83 <li><a href="#if">if</a></li>
84 <li><a href="#goto">goto</a></li>
85 <li><a href="#defer">defer</a></li>
86 <li><a href="#unreachable">unreachable</a>
87 <ul>
88 <li><a href="#unreachable-basics">Basics</a></li>
89 <li><a href="#unreachable-comptime">At Compile-Time</a></li>
90 </ul>
91 </li>
92 <li><a href="#noreturn">noreturn</a></li>
93 <li><a href="#functions">Functions</a>
94 <ul>
95 <li><a href="#functions-by-val-params">Pass-by-val Parameters</a>
96 </ul>
97 </li>
98 <li><a href="#errors">Errors</a></li>
99 <li><a href="#nullables">Nullables</a></li>
100 <li><a href="#casting">Casting</a></li>
101 <li><a href="#void">void</a></li>
102 <li><a href="#this">this</a></li>
103 <li><a href="#comptime">comptime</a>
104 <ul>
105 <li><a href="#introducing-compile-time-concept">Introducing the Compile-Time Concept</a></li>
106 <ul>
107 <li><a href="#compile-time-parameters">Compile-time parameters</a></li>
108 <li><a href="#compile-time-variables">Compile-time variables</a></li>
109 <li><a href="#compile-time-expressions">Compile-time expressions</a></li>
110 </ul>
111 <li><a href="#generic-data-structures">Generic Data Structures</a></li>
112 <li><a href="#case-study-printf">Case Study: printf in Zig</a></li>
113 </ul>
114 </li>
115 <li><a href="#inline">inline</a></li>
116 <li><a href="#assembly">assembly</a></li>
117 <li><a href="#atomics">Atomics</a></li>
118 <li><a href="#builtin-functions">Builtin Functions</a>
119 <ul>
120 <li><a href="#builtin-addWithOverflow">@addWithOverflow</a></li>
121 <li><a href="#builtin-alignCast">@alignCast</a></li>
122 <li><a href="#builtin-alignOf">@alignOf</a></li>
123 <li><a href="#builtin-ArgType">@ArgType</a></li>
124 <li><a href="#builtin-bitCast">@bitCast</a></li>
125 <li><a href="#builtin-breakpoint">@breakpoint</a></li>
126 <li><a href="#builtin-cDefine">@cDefine</a></li>
127 <li><a href="#builtin-cImport">@cImport</a></li>
128 <li><a href="#builtin-cInclude">@cInclude</a></li>
129 <li><a href="#builtin-cUndef">@cUndef</a></li>
130 <li><a href="#builtin-canImplicitCast">@canImplicitCast</a></li>
131 <li><a href="#builtin-clz">@clz</a></li>
132 <li><a href="#builtin-cmpxchg">@cmpxchg</a></li>
133 <li><a href="#builtin-compileError">@compileError</a></li>
134 <li><a href="#builtin-compileLog">@compileLog</a></li>
135 <li><a href="#builtin-ctz">@ctz</a></li>
136 <li><a href="#builtin-divExact">@divExact</a></li>
137 <li><a href="#builtin-divFloor">@divFloor</a></li>
138 <li><a href="#builtin-divTrunc">@divTrunc</a></li>
139 <li><a href="#builtin-embedFile">@embedFile</a></li>
140 <li><a href="#builtin-export">@export</a></li>
141 <li><a href="#builtin-tagName">@tagName</a></li>
142 <li><a href="#builtin-TagType">@TagType</a></li>
143 <li><a href="#builtin-EnumTagType">@EnumTagType</a></li>
144 <li><a href="#builtin-errorName">@errorName</a></li>
145 <li><a href="#builtin-errorReturnTrace">@errorReturnTrace</a></li>
146 <li><a href="#builtin-fence">@fence</a></li>
147 <li><a href="#builtin-fieldParentPtr">@fieldParentPtr</a></li>
148 <li><a href="#builtin-frameAddress">@frameAddress</a></li>
149 <li><a href="#builtin-import">@import</a></li>
150 <li><a href="#builtin-inlineCall">@inlineCall</a></li>
151 <li><a href="#builtin-intToPtr">@intToPtr</a></li>
152 <li><a href="#builtin-IntType">@IntType</a></li>
153 <li><a href="#builtin-maxValue">@maxValue</a></li>
154 <li><a href="#builtin-memberCount">@memberCount</a></li>
155 <li><a href="#builtin-memberName">@memberName</a></li>
156 <li><a href="#builtin-memberType">@memberType</a></li>
157 <li><a href="#builtin-memcpy">@memcpy</a></li>
158 <li><a href="#builtin-memset">@memset</a></li>
159 <li><a href="#builtin-minValue">@minValue</a></li>
160 <li><a href="#builtin-mod">@mod</a></li>
161 <li><a href="#builtin-mulWithOverflow">@mulWithOverflow</a></li>
162 <li><a href="#builtin-noInlineCall">@noInlineCall</a></li>
163 <li><a href="#builtin-offsetOf">@offsetOf</a></li>
164 <li><a href="#builtin-OpaqueType">@OpaqueType</a></li>
165 <li><a href="#builtin-panic">@panic</a></li>
166 <li><a href="#builtin-ptrCast">@ptrCast</a></li>
167 <li><a href="#builtin-ptrToInt">@ptrToInt</a></li>
168 <li><a href="#builtin-rem">@rem</a></li>
169 <li><a href="#builtin-returnAddress">@returnAddress</a></li>
170 <li><a href="#builtin-setDebugSafety">@setDebugSafety</a></li>
171 <li><a href="#builtin-setEvalBranchQuota">@setEvalBranchQuota</a></li>
172 <li><a href="#builtin-setFloatMode">@setFloatMode</a></li>
173 <li><a href="#builtin-setGlobalLinkage">@setGlobalLinkage</a></li>
174 <li><a href="#builtin-setGlobalSection">@setGlobalSection</a></li>
175 <li><a href="#builtin-shlExact">@shlExact</a></li>
176 <li><a href="#builtin-shlWithOverflow">@shlWithOverflow</a></li>
177 <li><a href="#builtin-shrExact">@shrExact</a></li>
178 <li><a href="#builtin-sizeOf">@sizeOf</a></li>
179 <li><a href="#builtin-subWithOverflow">@subWithOverflow</a></li>
180 <li><a href="#builtin-truncate">@truncate</a></li>
181 <li><a href="#builtin-typeId">@typeId</a></li>
182 <li><a href="#builtin-typeName">@typeName</a></li>
183 <li><a href="#builtin-typeOf">@typeOf</a></li>
184 </ul>
185 </li>
186 <li><a href="#build-mode">Build Mode</a>
187 <ul>
188 <li><a href="#build-mode-debug">Debug</a></li>
189 <li><a href="#build-mode-release-fast">ReleaseFast</a></li>
190 <li><a href="#build-mode-release-safe">ReleaseSafe</a></li>
191 </ul>
192 </li>
193 <li><a href="#undefined-behavior">Undefined Behavior</a>
194 <ul>
195 <li><a href="#undef-unreachable">Reaching Unreachable Code</a></li>
196 <li><a href="#undef-index-out-of-bounds">Index out of Bounds</a></li>
197 <li><a href="#undef-cast-negative-unsigned">Cast Negative Number to Unsigned Integer</a></li>
198 <li><a href="#undef-cast-truncates-data">Cast Truncates Data</a></li>
199 <li><a href="#undef-integer-overflow">Integer Overflow</a>
200 <ul>
201 <li><a href="#undef-int-overflow-default">Default Operations</a></li>
202 <li><a href="#undef-int-overflow-std">Standard Library Math Functions</a></li>
203 <li><a href="#undef-int-overflow-builtin">Builtin Overflow Functions</a></li>
204 <li><a href="#undef-int-overflow-wrap">Wrapping Operations</a></li>
205
206 </ul>
207 </li>
208 <li><a href="#undef-shl-overflow">Exact Left Shift Overflow</a></li>
209 <li><a href="#undef-shr-overflow">Exact Right Shift Overflow</a></li>
210 <li><a href="#undef-division-by-zero">Division by Zero</a></li>
211 <li><a href="#undef-remainder-division-by-zero">Remainder Division by Zero</a></li>
212 <li><a href="#undef-exact-division-remainder">Exact Division Remainder</a></li>
213 <li><a href="#undef-slice-widen-remainder">Slice Widen Remainder</a></li>
214 <li><a href="#undef-attempt-unwrap-null">Attempt to Unwrap Null</a></li>
215 <li><a href="#undef-attempt-unwrap-error">Attempt to Unwrap Error</a></li>
216 <li><a href="#undef-invalid-error-code">Invalid Error Code</a></li>
217 <li><a href="#undef-invalid-enum-cast">Invalid Enum Cast</a></li>
218 <li><a href="#undef-incorrect-pointer-alignment">Incorrect Pointer Alignment</a></li>
219 <li><a href="#undef-bad-union-field">Wrong Union Field Access</a></li>
220 </ul>
221 </li>
222 <li><a href="#memory">Memory</a></li>
223 <li><a href="#compile-variables">Compile Variables</a></li>
224 <li><a href="#root-source-file">Root Source File</a></li>
225 <li><a href="#zig-test">Zig Test</a></li>
226 <li><a href="#zig-build-system">Zig Build System</a></li>
227 <li><a href="#c">C</a>
228 <ul>
229 <li><a href="#c-type-primitives">C Type Primitives</a></li>
230 <li><a href="#c-string-literals">C String Literals</a></li>
231 <li><a href="#c-import">Import from C Header File</a></li>
232 <li><a href="#mixing-object-files">Mixing Object Files</a></li>
233 </ul>
234 </li>
235 <li><a href="#targets">Targets</a></li>
236 <li><a href="#style-guide">Style Guide</a>
237 <ul>
238 <li><a href="#style-guide-whitespace">Whitespace</a></li>
239 <li><a href="#style-guide-names">Names</a></li>
240 <li><a href="#style-guide-examples">Examples</a></li>
241 </ul>
242 </li>
243 <li><a href="#grammar">Grammar</a></li>
244 <li><a href="#zen">Zen</a></li>
245 </ul>
34 {#nav#}
24635 </div>
24736 <div id="contents">
248 <h1 id="introduction">Zig Documentation</h1>
37 {#header_open|Introduction#}
24938 <p>
25039 Zig is an open-source programming language designed for <strong>robustness</strong>,
25140 <strong>optimality</strong>, and <strong>clarity</strong>.
......@@ -264,7 +53,8 @@
26453 If you search for something specific in this documentation and do not find it,
26554 please <a href="https://github.com/zig-lang/www.ziglang.org/issues/new?title=I%20searched%20for%20___%20in%20the%20docs%20and%20didn%27t%20find%20it">file an issue</a> or <a href="https://webchat.freenode.net/?channels=%23zig">say something on IRC</a>.
26655 </p>
267 <h2 id="hello-world">Hello World</h2>
56 {#header_close#}
57 {#header_open|Hello World#}
26858 <pre><code class="zig">const std = @import("std");
26959
27060pub fn main() -&gt; %void {
......@@ -294,7 +84,8 @@ pub fn main() -&gt; %void {
29484 <li><a href="#errors">Errors</a></li>
29585 <li><a href="#root-source-file">Root Source File</a></li>
29686 </ul>
297 <h2 id="source-encoding">Source Encoding</h2>
87 {#header_close#}
88 {#header_open|Source Encoding#}
29889 <p>Zig source code is encoded in UTF-8. An invalid UTF-8 byte sequence results in a compile error.</p>
29990 <p>Throughout all zig source code (including in comments), some codepoints are never allowed:</p>
30091 <ul>
......@@ -303,7 +94,8 @@ pub fn main() -&gt; %void {
30394 </ul>
30495 <p>The codepoint U+000a (LF) (which is encoded as the single-byte value 0x0a) is the line terminator character. This character always terminates a line of zig source code (except possbly the last line of the file).</p>
30596 <p>For some discussion on the rationale behind these design decisions, see <a href="https://github.com/zig-lang/zig/issues/663">issue #663</a></p>
306 <h2 id="values">Values</h2>
97 {#header_close#}
98 {#header_open|Values#}
30799 <pre><code class="zig">const warn = @import("std").debug.warn;
308100const os = @import("std").os;
309101const assert = @import("std").debug.assert;
......@@ -373,7 +165,7 @@ value: error.ArgNotFound
373165error union 2
374166type: %i32
375167value: 1234</code></pre>
376 <h3 id="primitive-types">Primitive Types</h2>
168 {#header_open|Primitive Types#}
377169 <table>
378170 <tr>
379171 <th>
......@@ -606,7 +398,8 @@ value: 1234</code></pre>
606398 <li><a href="#void">void</a></li>
607399 <li><a href="#errors">Errors</a></li>
608400 </ul>
609 <h3 id="primitive-values">Primitive Values</h3>
401 {#header_close#}
402 {#header_open|Primitive Values#}
610403 <table>
611404 <tr>
612405 <th>
......@@ -638,7 +431,8 @@ value: 1234</code></pre>
638431 <li><a href="#nullables">Nullables</a></li>
639432 <li><a href="#this">this</a></li>
640433 </ul>
641 <h3 id="string-literals">String Literals</h3>
434 {#header_close#}
435 {#header_open|String Literals#}
642436 <pre><code class="zig">const assert = @import("std").debug.assert;
643437const mem = @import("std").mem;
644438
......@@ -663,7 +457,7 @@ Test 1/1 string literals...OK</code></pre>
663457 <li><a href="#arrays">Arrays</a></li>
664458 <li><a href="#zig-test">Zig Test</a></li>
665459 </ul>
666 <h4 id="string-literal-escapes">Escape Sequences</h4>
460 {#header_open|Escape Sequences#}
667461 <table>
668462 <tr>
669463 <th>
......@@ -711,7 +505,8 @@ Test 1/1 string literals...OK</code></pre>
711505 </tr>
712506 </table>
713507 <p>Note that the maximum valid Unicode point is <code>0x10ffff</code>.</p>
714 <h4 id="multiline-string-literals">Multiline String Literals</h4>
508 {#header_close#}
509 {#header_open|Multiline String Literals#}
715510 <p>
716511 Multiline string literals have no escapes and can span across multiple lines.
717512 To start a multiline string literal, use the <code>\\</code> token. Just like a comment,
......@@ -747,7 +542,9 @@ Test 1/1 string literals...OK</code></pre>
747542 <ul>
748543 <li><a href="#builtin-embedFile">@embedFile</a></li>
749544 </ul>
750 <h3 id="values-assignment">Assignment</h3>
545 {#header_close#}
546 {#header_close#}
547 {#header_open|Assignment#}
751548 <p>Use <code>const</code> to assign a value to an identifier:</p>
752549 <pre><code class="zig">const x = 1234;
753550
......@@ -798,14 +595,17 @@ test "init with undefined" {
798595}</code></pre>
799596 <pre><code class="sh">$ zig test test.zig
800597Test 1/1 init with undefined...OK</code></pre>
801 <h2 id="integers">Integers</h2>
802 <h3 id="integer-literals">Integer Literals</h3>
598 {#header_close#}
599 {#header_close#}
600 {#header_open|Integers#}
601 {#header_open|Integer Literals#}
803602 <pre><code class="zig">const decimal_int = 98222;
804603const hex_int = 0xff;
805604const another_hex_int = 0xFF;
806605const octal_int = 0o755;
807606const binary_int = 0b11110000;</code></pre>
808 <h3 id="runtime-integer-values">Runtime Integer Values</h3>
607 {#header_close#}
608 {#header_open|Runtime Integer Values#}
809609 <p>
810610 Integer literals have no size limitation, and if any undefined behavior occurs,
811611 the compiler catches it.
......@@ -833,8 +633,11 @@ const binary_int = 0b11110000;</code></pre>
833633 <li><a href="#undef-division-by-zero">Division By Zero</a></li>
834634 <li><a href="#undef-int-overflow-wrap">Wrapping Operations</a></li>
835635 </ul>
836 <h2 id="floats">Floats</h2>
837 <h3 id="float-literals">Float Literals</h3>
636 {#header_close#}
637 {#header_close#}
638 {#header_open|Floats#}
639 {#header_close#}
640 {#header_open|Float Literals#}
838641 <pre><code class="zig">const floating_point = 123.0E+77;
839642const another_float = 123.0;
840643const yet_another = 123.0e+77;
......@@ -842,7 +645,8 @@ const yet_another = 123.0e+77;
842645const hex_floating_point = 0x103.70p-5;
843646const another_hex_float = 0x103.70;
844647const yet_another_hex_float = 0x103.70P-5;</code></pre>
845 <h3 id="float-operations">Floating Point Operations</h3>
648 {#header_close#}
649 {#header_open|Floating Point Operations#}
846650 <p>By default floating point operations use <code>Optimized</code> mode,
847651 but you can switch to <code>Strict</code> mode on a per-block basis:</p>
848652 <p>foo.zig</p>
......@@ -881,8 +685,9 @@ strict = 9.765625e-3</code></pre>
881685 <li><a href="#builtin-setFloatMode">@setFloatMode</a></li>
882686 <li><a href="#undef-division-by-zero">Division By Zero</a></li>
883687 </ul>
884 <h2 id="operators">Operators</h2>
885 <h3 id="operators-table">Table of Operators</h2>
688 {#header_close#}
689 {#header_open|Operators#}
690 {#header_open|Table of Operators#}
886691 <table>
887692 <tr>
888693 <th>
......@@ -1470,7 +1275,8 @@ const ptr = &amp;x;
14701275 </td>
14711276 </tr>
14721277 </table>
1473 <h3 id="operators-precedence">Precedence</h3>
1278 {#header_close#}
1279 {#header_open|Precedence#}
14741280 <pre><code>x() x[] x.y
14751281!x -x -%x ~x *x &amp;x ?x %x %%x ??x
14761282x{}
......@@ -1485,7 +1291,9 @@ and
14851291or
14861292?? catch
14871293= *= /= %= += -= &lt;&lt;= &gt;&gt;= &amp;= ^= |=</code></pre>
1488 <h2 id="arrays">Arrays</h2>
1294 {#header_close#}
1295 {#header_close#}
1296 {#header_open|Arrays#}
14891297 <pre><code class="zig">const assert = @import("std").debug.assert;
14901298const mem = @import("std").mem;
14911299
......@@ -1599,7 +1407,8 @@ Test 4/4 array initialization with function calls...OK</code></pre>
15991407 <li><a href="#for">for</a></li>
16001408 <li><a href="#slices">Slices</a></li>
16011409 </ul>
1602 <h2 id="pointers">Pointers</h2>
1410 {#header_close#}
1411 {#header_open|Pointers#}
16031412 <pre><code class="zig">const assert = @import("std").debug.assert;
16041413
16051414test "address of syntax" {
......@@ -1737,7 +1546,7 @@ Test 5/8 volatile...OK
17371546Test 6/8 nullable pointers...OK
17381547Test 7/8 pointer casting...OK
17391548Test 8/8 pointer child type...OK</code></pre>
1740 <h3 id="alignment">Alignment</h3>
1549 {#header_open|Alignment#}
17411550 <p>
17421551 Each type has an <strong>alignment</strong> - a number of bytes such that,
17431552 when a value of the type is loaded from or stored to memory,
......@@ -1838,7 +1647,8 @@ Test 1/1 pointer alignment safety...incorrect alignment
18381647
18391648Tests failed. Use the following command to reproduce the failure:
18401649./test</code></pre>
1841 <h3 id="type-based-alias-analysis">Type Based Alias Analysis</h3>
1650 {#header_close#}
1651 {#header_open|Type Based Alias Analysis#}
18421652 <p>Zig uses Type Based Alias Analysis (also known as Strict Aliasing) to
18431653 perform some optimizations. This means that pointers of different types must
18441654 not alias the same memory, with the exception of <code>u8</code>. Pointers to
......@@ -1854,7 +1664,9 @@ Tests failed. Use the following command to reproduce the failure:
18541664 <li><a href="#slices">Slices</a></li>
18551665 <li><a href="#memory">Memory</a></li>
18561666 </ul>
1857 <h2 id="slices">Slices</h2>
1667 {#header_close#}
1668 {#header_close#}
1669 {#header_open|Slices#}
18581670 <pre><code class="zig">const assert = @import("std").debug.assert;
18591671
18601672test "basic slices" {
......@@ -1954,7 +1766,8 @@ Test 3/3 slice widening...OK</code></pre>
19541766 <li><a href="#for">for</a></li>
19551767 <li><a href="#arrays">Arrays</a></li>
19561768 </ul>
1957 <h2 id="struct">struct</h2>
1769 {#header_close#}
1770 {#header_open|struct#}
19581771 <pre><code class="zig">// Declare a struct.
19591772// Zig gives no guarantees about the order of fields and whether or
19601773// not there will be padding.
......@@ -2099,7 +1912,8 @@ Test 4/4 linked list...OK</code></pre>
20991912 <li><a href="#comptime">comptime</a></li>
21001913 <li><a href="#builtin-fieldParentPtr">@fieldParentPtr</a></li>
21011914 </ul>
2102 <h2 id="enum">enum</h2>
1915 {#header_close#}
1916 {#header_open|enum#}
21031917 <pre><code class="zig">const assert = @import("std").debug.assert;
21041918const mem = @import("std").mem;
21051919
......@@ -2216,7 +2030,8 @@ Test 8/8 @tagName...OK</code></pre>
22162030 <li><a href="#builtin-memberCount">@memberCount</a></li>
22172031 <li><a href="#builtin-tagName">@tagName</a></li>
22182032 </ul>
2219 <h2 id="union">union</h2>
2033 {#header_close#}
2034 {#header_open|union#}
22202035 <pre><code class="zig">const assert = @import("std").debug.assert;
22212036const mem = @import("std").mem;
22222037
......@@ -2323,7 +2138,8 @@ Test 7/7 @tagName...OK</code></pre>
23232138 Unions with an enum tag are generated as a struct with a tag field and union field. Zig
23242139 sorts the order of the tag and union field by the largest alignment.
23252140 </p>
2326 <h2 id="switch">switch</h2>
2141 {#header_close#}
2142 {#header_open|switch#}
23272143 <pre><code class="zig">const assert = @import("std").debug.assert;
23282144const builtin = @import("builtin");
23292145
......@@ -2426,7 +2242,8 @@ Test 3/3 switch inside function...OK</code></pre>
24262242 <li><a href="#builtin-compileError">@compileError</a></li>
24272243 <li><a href="#compile-variables">Compile Variables</a></li>
24282244 </ul>
2429 <h2 id="while">while</h2>
2245 {#header_close#}
2246 {#header_open|while#}
24302247 <pre><code class="zig">const assert = @import("std").debug.assert;
24312248
24322249test "while basic" {
......@@ -2595,7 +2412,8 @@ Test 8/8 inline while loop...OK</code></pre>
25952412 <li><a href="#comptime">comptime</a></li>
25962413 <li><a href="#unreachable">unreachable</a></li>
25972414 </ul>
2598 <h2 id="for">for</h2>
2415 {#header_close#}
2416 {#header_open|for#}
25992417 <pre><code class="zig">const assert = @import("std").debug.assert;
26002418
26012419test "for basics" {
......@@ -2696,7 +2514,8 @@ Test 4/4 inline for loop...OK</code></pre>
26962514 <li><a href="#arrays">Arrays</a></li>
26972515 <li><a href="#slices">Slices</a></li>
26982516 </ul>
2699 <h2 id="if">if</h2>
2517 {#header_close#}
2518 {#header_open|if#}
27002519 <pre><code class="zig">// If expressions have three uses, corresponding to the three types:
27012520// * bool
27022521// * ?T
......@@ -2814,7 +2633,8 @@ Test 3/3 if error union...OK</code></pre>
28142633 <li><a href="#nullables">Nullables</a></li>
28152634 <li><a href="#errors">Errors</a></li>
28162635 </ul>
2817 <h2 id="goto">goto</h2>
2636 {#header_close#}
2637 {#header_open|goto#}
28182638 <pre><code class="zig">const assert = @import("std").debug.assert;
28192639
28202640test "goto" {
......@@ -2830,7 +2650,7 @@ label:
28302650Test 1/1 goto...OK
28312651</code></pre>
28322652<p>Note that there are <a href="https://github.com/zig-lang/zig/issues/346">plans to remove goto</a></p>
2833 <h2 id="defer">defer</h2>
2653{{deheader_open:fer}}
28342654 <pre><code class="zig">const assert = @import("std").debug.assert;
28352655const printf = @import("std").io.stdout.printf;
28362656
......@@ -2920,7 +2740,8 @@ OK
29202740 <ul>
29212741 <li><a href="#errors">Errors</a></li>
29222742 </ul>
2923 <h2 id="unreachable">unreachable</h2>
2743 {#header_close#}
2744 {#header_open|unreachable#}
29242745 <p>
29252746 In <code>Debug</code> and <code>ReleaseSafe</code> mode, and when using <code>zig test</code>,
29262747 <code>unreachable</code> emits a call to <code>panic</code> with the message <code>reached unreachable code</code>.
......@@ -2930,7 +2751,7 @@ OK
29302751 will never be hit to perform optimizations. However, <code>zig test</code> even in <code>ReleaseFast</code> mode
29312752 still emits <code>unreachable</code> as calls to <code>panic</code>.
29322753 </p>
2933 <h3 id="unreachable-basics">Basics</h3>
2754 {#header_open|Basics#}
29342755 <pre><code class="zig">// unreachable is used to assert that control flow will never happen upon a
29352756// particular location:
29362757test "basic math" {
......@@ -2974,7 +2795,8 @@ lib/zig/std/special/bootstrap.zig:34:25: 0x0000000000214750 in ??? (test)
29742795
29752796Tests failed. Use the following command to reproduce the failure:
29762797./test</code></pre>
2977 <h3 id="unreachable-comptime">At Compile-Time</h3>
2798 {#header_close#}
2799 {#header_open|At Compile-Time#}
29782800 <pre><code class="zig">const assert = @import("std").debug.assert;
29792801
29802802comptime {
......@@ -2995,7 +2817,9 @@ test.zig:9:12: error: unreachable code
29952817 <li><a href="#build-mode">Build Mode</a></li>
29962818 <li><a href="#comptime">comptime</a></li>
29972819 </ul>
2998 <h2 id="noreturn">noreturn</h2>
2820 {#header_close#}
2821 {#header_close#}
2822 {#header_open|noreturn#}
29992823 <p>
30002824 <code>noreturn</code> is the type of:
30012825 </p>
......@@ -3029,7 +2853,8 @@ fn bar() -&gt; %u32 {
30292853}
30302854
30312855const assert = @import("std").debug.assert;</code></pre>
3032 <h2 id="functions">Functions</h2>
2856 {#header_close#}
2857 {#header_open|Functions#}
30332858 <pre><code class="zig">const assert = @import("std").debug.assert;
30342859
30352860// Functions are declared like this
......@@ -3091,7 +2916,7 @@ comptime {
30912916
30922917fn foo() { }</code></pre>
30932918 <pre><code class="sh">$ zig build-obj test.zig</code></pre>
3094 <h3 id="functions-by-val-params">Pass-by-value Parameters</h3>
2919 {#header_open|Pass-by-value Parameters#}
30952920 <p>
30962921 In Zig, structs, unions, and enums with payloads cannot be passed by value
30972922 to a function.
......@@ -3127,7 +2952,9 @@ export fn entry() {
31272952 the C ABI does allow passing structs and unions by value. So functions which
31282953 use the C calling convention may pass structs and unions by value.
31292954 </p>
3130 <h2 id="errors">Errors</h2>
2955 {#header_close#}
2956 {#header_close#}
2957 {#header_open|Errors#}
31312958 <p>
31322959 One of the distinguishing features of Zig is its exception handling strategy.
31332960 </p>
......@@ -3321,7 +3148,8 @@ pub fn parseU64(buf: []const u8, radix: u8) -&gt; %u64 {
33213148 <li><a href="#if">if</a></li>
33223149 <li><a href="#switch">switch</a></li>
33233150 </ul>
3324 <h2 id="nullables">Nullables</h2>
3151 {#header_close#}
3152 {#header_open|Nullables#}
33253153 <p>
33263154 One area that Zig provides safety without compromising efficiency or
33273155 readability is with the nullable type.
......@@ -3415,7 +3243,8 @@ fn doAThing() -&gt; ?&amp;Foo {
34153243 The optimizer can sometimes make better decisions knowing that pointer arguments
34163244 cannot be null.
34173245 </p>
3418 <h2 id="casting">Casting</h2>
3246 {#header_close#}
3247 {#header_open|Casting#}
34193248 <p>TODO: explain implicit vs explicit casting</p>
34203249 <p>TODO: resolve peer types builtin</p>
34213250 <p>TODO: truncate builtin</p>
......@@ -3424,24 +3253,27 @@ fn doAThing() -&gt; ?&amp;Foo {
34243253 <p>TODO: ptr to int builtin</p>
34253254 <p>TODO: ptrcast builtin</p>
34263255 <p>TODO: explain number literals vs concrete types</p>
3427 <h2 id="void">void</h2>
3256 {#header_close#}
3257 {#header_open|void#}
34283258 <p>TODO: assigning void has no codegen</p>
34293259 <p>TODO: hashmap with void becomes a set</p>
34303260 <p>TODO: difference between c_void and void</p>
34313261 <p>TODO: void is the default return value of functions</p>
34323262 <p>TODO: functions require assigning the return value</p>
3433 <h2 id="this">this</h2>
3263 {#header_close#}
3264 {#header_open|this#}
34343265 <p>TODO: example of this referring to Self struct</p>
34353266 <p>TODO: example of this referring to recursion function</p>
34363267 <p>TODO: example of this referring to basic block for @setDebugSafety</p>
3437 <h2 id="comptime">comptime</h2>
3268 {#header_close#}
3269 {#header_open|comptime#}
34383270 <p>
34393271 Zig places importance on the concept of whether an expression is known at compile-time.
34403272 There are a few different places this concept is used, and these building blocks are used
34413273 to keep the language small, readable, and powerful.
34423274 </p>
3443 <h3 id="introducing-compile-time-concept">Introducing the Compile-Time Concept</h3>
3444 <h4 id="compile-time-parameters">Compile-Time Parameters</h4>
3275 {#header_open|Introducing the Compile-Time Concept#}
3276 {#header_open|Compile-Time Parameters#}
34453277 <p>
34463278 Compile-time parameters is how Zig implements generics. It is compile-time duck typing.
34473279 </p>
......@@ -3549,7 +3381,8 @@ fn letsTryToCompareBools(a: bool, b: bool) -&gt; bool {
35493381 This works the same way for <code>switch</code> expressions - they are implicitly inlined
35503382 when the target expression is compile-time known.
35513383 </p>
3552 <h4 id="compile-time-variables">Compile-Time Variables</h4>
3384 {#header_close#}
3385 {#header_open|Compile-Time Variables#}
35533386 <p>
35543387 In Zig, the programmer can label variables as <code>comptime</code>. This guarantees to the compiler
35553388 that every load and store of the variable is performed at compile-time. Any violation of this results in a
......@@ -3631,7 +3464,8 @@ fn performFn(start_value: i32) -&gt; i32 {
36313464 later in this article, allows expressiveness that in other languages requires using macros,
36323465 generated code, or a preprocessor to accomplish.
36333466 </p>
3634 <h4 id="compile-time-expressions">Compile-Time Expressions</h4>
3467 {#header_close#}
3468 {#header_open|Compile-Time Expressions#}
36353469 <p>
36363470 In Zig, it matters whether a given expression is known at compile-time or run-time. A programmer can
36373471 use a <code>comptime</code> expression to guarantee that the expression will be evaluated at compile-time.
......@@ -3860,7 +3694,9 @@ fn sum(numbers: []i32) -&gt; i32 {
38603694 we could call the <code>sum</code> function as is with a slice of numbers whose length and values were
38613695 only known at run-time.
38623696 </p>
3863 <h3 id="generic-data-structures">Generic Data Structures</h3>
3697 {#header_close#}
3698 {#header_close#}
3699 {#header_open|Generic Data Structures#}
38643700 <p>
38653701 Zig uses these capabilities to implement generic data structures without introducing any
38663702 special-case syntax. If you followed along so far, you may already know how to create a
......@@ -3895,7 +3731,8 @@ fn sum(numbers: []i32) -&gt; i32 {
38953731 <code>Node</code> refers to itself as a pointer, which is not actually an infinite regression, so
38963732 it works fine.
38973733 </p>
3898 <h3 id="case-study-printf">Case Study: printf in Zig</h3>
3734 {#header_close#}
3735 {#header_open|Case Study: printf in Zig#}
38993736 <p>
39003737 Putting all of this together, let's seee how <code>printf</code> works in Zig.
39013738 </p>
......@@ -4045,35 +3882,42 @@ pub fn main(args: [][]u8) -&gt; %void {
40453882 a macro language or a preprocessor language. It's Zig all the way down.
40463883 </p>
40473884 <p>TODO: suggestion to not use inline unless necessary</p>
4048 <h2 id="inline">inline</h2>
3885 {#header_close#}
3886 {#header_close#}
3887 {#header_open|inline#}
40493888 <p>TODO: inline while</p>
40503889 <p>TODO: inline for</p>
40513890 <p>TODO: suggestion to not use inline unless necessary</p>
4052 <h2 id="assembly">Assembly</h2>
3891 {#header_close#}
3892 {#header_open|Assembly#}
40533893 <p>TODO: example of inline assembly</p>
40543894 <p>TODO: example of module level assembly</p>
40553895 <p>TODO: example of using inline assembly return value</p>
40563896 <p>TODO: example of using inline assembly assigning values to variables</p>
4057 <h2 id="atomics">Atomics</h2>
3897 {#header_close#}
3898 {#header_open|Atomics#}
40583899 <p>TODO: @fence()</p>
40593900 <p>TODO: @atomic rmw</p>
40603901 <p>TODO: builtin atomic memory ordering enum</p>
4061 <h2 id="builtin-functions">Builtin Functions</h2>
3902 {#header_close#}
3903 {#header_open|Builtin Functions#}
40623904 <p>
40633905 Builtin functions are provided by the compiler and are prefixed with <code>@</code>.
40643906 The <code>comptime</code> keyword on a parameter means that the parameter must be known
40653907 at compile time.
40663908 </p>
4067 <h3 id="builtin-addWithOverflow">@addWithOverflow</h3>
3909 {#header_open|@addWithOverflow#}
40683910 <pre><code class="zig">@addWithOverflow(comptime T: type, a: T, b: T, result: &amp;T) -&gt; bool</code></pre>
40693911 <p>
40703912 Performs <code>*result = a + b</code>. If overflow or underflow occurs,
40713913 stores the overflowed bits in <code>result</code> and returns <code>true</code>.
40723914 If no overflow or underflow occurs, returns <code>false</code>.
40733915 </p>
4074 <h3 id="builtin-ArgType">@ArgType</h3>
3916 {#header_close#}
3917 {#header_open|@ArgType#}
40753918 <p>TODO</p>
4076 <h3 id="builtin-bitCast">@bitCast</h3>
3919 {#header_close#}
3920 {#header_open|@bitCast#}
40773921 <pre><code class="zig">@bitCast(comptime DestType: type, value: var) -&gt; DestType</code></pre>
40783922 <p>
40793923 Converts a value of one type to another type.
......@@ -4094,7 +3938,8 @@ pub fn main(args: [][]u8) -&gt; %void {
40943938 <p>
40953939 Works at compile-time if <code>value</code> is known at compile time. It's a compile error to bitcast a struct to a scalar type of the same size since structs have undefined layout. However if the struct is packed then it works.
40963940 </p>
4097 <h3 id="builtin-breakpoint">@breakpoint</h3>
3941 {#header_close#}
3942 {#header_open|@breakpoint#}
40983943 <pre><code class="zig">@breakpoint()</code></pre>
40993944 <p>
41003945 This function inserts a platform-specific debug trap instruction which causes
......@@ -4104,7 +3949,8 @@ pub fn main(args: [][]u8) -&gt; %void {
41043949 This function is only valid within function scope.
41053950 </p>
41063951
4107 <h3 id="builtin-alignCast">@alignCast</h3>
3952 {#header_close#}
3953 {#header_open|@alignCast#}
41083954 <pre><code class="zig">@alignCast(comptime alignment: u29, ptr: var) -&gt; var</code></pre>
41093955 <p>
41103956 <code>ptr</code> can be <code>&amp;T</code>, <code>fn()</code>, <code>?&amp;T</code>,
......@@ -4114,7 +3960,8 @@ pub fn main(args: [][]u8) -&gt; %void {
41143960 <p>A <a href="#undef-incorrect-pointer-alignment">pointer alignment safety check</a> is added
41153961 to the generated code to make sure the pointer is aligned as promised.</p>
41163962
4117 <h3 id="builtin-alignOf">@alignOf</h3>
3963 {#header_close#}
3964 {#header_open|@alignOf#}
41183965 <pre><code class="zig">@alignOf(comptime T: type) -&gt; (number literal)</code></pre>
41193966 <p>
41203967 This function returns the number of bytes that this type should be aligned to
......@@ -4134,7 +3981,8 @@ comptime {
41343981 <li><a href="#alignment">Alignment</a></li>
41353982 </ul>
41363983
4137 <h3 id="builtin-cDefine">@cDefine</h3>
3984 {#header_close#}
3985 {#header_open|@cDefine#}
41383986 <pre><code class="zig">@cDefine(comptime name: []u8, value)</code></pre>
41393987 <p>
41403988 This function can only occur inside <code>@cImport</code>.
......@@ -4159,7 +4007,8 @@ comptime {
41594007 <li><a href="#builtin-cUndef">@cUndef</a></li>
41604008 <li><a href="#void">void</a></li>
41614009 </ul>
4162 <h3 id="builtin-cImport">@cImport</h3>
4010 {#header_close#}
4011 {#header_open|@cImport#}
41634012 <pre><code class="zig">@cImport(expression) -&gt; (namespace)</code></pre>
41644013 <p>
41654014 This function parses C code and imports the functions, types, variables, and
......@@ -4177,7 +4026,8 @@ comptime {
41774026 <li><a href="#builtin-cDefine">@cDefine</a></li>
41784027 <li><a href="#builtin-cUndef">@cUndef</a></li>
41794028 </ul>
4180 <h3 id="builtin-cInclude">@cInclude</h3>
4029 {#header_close#}
4030 {#header_open|@cInclude#}
41814031 <pre><code class="zig">@cInclude(comptime path: []u8)</code></pre>
41824032 <p>
41834033 This function can only occur inside <code>@cImport</code>.
......@@ -4193,7 +4043,8 @@ comptime {
41934043 <li><a href="#builtin-cDefine">@cDefine</a></li>
41944044 <li><a href="#builtin-cUndef">@cUndef</a></li>
41954045 </ul>
4196 <h3 id="builtin-cUndef">@cUndef</h3>
4046 {#header_close#}
4047 {#header_open|@cUndef#}
41974048 <pre><code class="zig">@cUndef(comptime name: []u8)</code></pre>
41984049 <p>
41994050 This function can only occur inside <code>@cImport</code>.
......@@ -4209,12 +4060,14 @@ comptime {
42094060 <li><a href="#builtin-cDefine">@cDefine</a></li>
42104061 <li><a href="#builtin-cInclude">@cInclude</a></li>
42114062 </ul>
4212 <h3 id="builtin-canImplicitCast">@canImplicitCast</h3>
4063 {#header_close#}
4064 {#header_open|@canImplicitCast#}
42134065 <pre><code class="zig">@canImplicitCast(comptime T: type, value) -&gt; bool</code></pre>
42144066 <p>
42154067 Returns whether a value can be implicitly casted to a given type.
42164068 </p>
4217 <h3 id="builtin-clz">@clz</h3>
4069 {#header_close#}
4070 {#header_open|@clz#}
42184071 <pre><code class="zig">@clz(x: T) -&gt; U</code></pre>
42194072 <p>
42204073 This function counts the number of leading zeroes in <code>x</code> which is an integer
......@@ -4228,7 +4081,8 @@ comptime {
42284081 If <code>x</code> is zero, <code>@clz</code> returns <code>T.bit_count</code>.
42294082 </p>
42304083
4231 <h3 id="builtin-cmpxchg">@cmpxchg</h3>
4084 {#header_close#}
4085 {#header_open|@cmpxchg#}
42324086 <pre><code class="zig">@cmpxchg(ptr: &amp;T, cmp: T, new: T, success_order: AtomicOrder, fail_order: AtomicOrder) -&gt; bool</code></pre>
42334087 <p>
42344088 This function performs an atomic compare exchange operation.
......@@ -4242,7 +4096,8 @@ comptime {
42424096 <li><a href="#compile-variables">Compile Variables</a></li>
42434097 </ul>
42444098
4245 <h3 id="builtin-compileError">@compileError</h3>
4099 {#header_close#}
4100 {#header_open|@compileError#}
42464101 <pre><code class="zig">@compileError(comptime msg: []u8)</code></pre>
42474102 <p>
42484103 This function, when semantically analyzed, causes a compile error with the
......@@ -4253,7 +4108,8 @@ comptime {
42534108 using <code>if</code> or <code>switch</code> with compile time constants,
42544109 and <code>comptime</code> functions.
42554110 </p>
4256 <h3 id="builtin-compileLog">@compileLog</h3>
4111 {#header_close#}
4112 {#header_open|@compileLog#}
42574113 <pre><code class="zig">@compileLog(args: ...)</code></pre>
42584114 <p>
42594115 This function prints the arguments passed to it at compile-time.
......@@ -4303,7 +4159,7 @@ test.zig:6:2: error: found compile log statement
43034159 program compiles successfully and the generated executable prints:
43044160 </p>
43054161<pre><code class="sh">Runtime in main, num1 = 100.</code></pre>
4306 <h3 id="builtin-ctz">@ctz</h3>
4162{{@ctheader_open:z}}
43074163 <pre><code class="zig">@ctz(x: T) -&gt; U</code></pre>
43084164 <p>
43094165 This function counts the number of trailing zeroes in <code>x</code> which is an integer
......@@ -4316,7 +4172,8 @@ test.zig:6:2: error: found compile log statement
43164172 <p>
43174173 If <code>x</code> is zero, <code>@ctz</code> returns <code>T.bit_count</code>.
43184174 </p>
4319 <h3 id="builtin-divExact">@divExact</h3>
4175 {#header_close#}
4176 {#header_open|@divExact#}
43204177 <pre><code class="zig">@divExact(numerator: T, denominator: T) -&gt; T</code></pre>
43214178 <p>
43224179 Exact division. Caller guarantees <code>denominator != 0</code> and
......@@ -4332,7 +4189,8 @@ test.zig:6:2: error: found compile log statement
43324189 <li><a href="#builtin-divFloor">@divFloor</a></li>
43334190 <li><code>@import("std").math.divExact</code></li>
43344191 </ul>
4335 <h3 id="builtin-divFloor">@divFloor</h3>
4192 {#header_close#}
4193 {#header_open|@divFloor#}
43364194 <pre><code class="zig">@divFloor(numerator: T, denominator: T) -&gt; T</code></pre>
43374195 <p>
43384196 Floored division. Rounds toward negative infinity. For unsigned integers it is
......@@ -4349,7 +4207,8 @@ test.zig:6:2: error: found compile log statement
43494207 <li><a href="#builtin-divExact">@divExact</a></li>
43504208 <li><code>@import("std").math.divFloor</code></li>
43514209 </ul>
4352 <h3 id="builtin-divTrunc">@divTrunc</h3>
4210 {#header_close#}
4211 {#header_open|@divTrunc#}
43534212 <pre><code class="zig">@divTrunc(numerator: T, denominator: T) -&gt; T</code></pre>
43544213 <p>
43554214 Truncated division. Rounds toward zero. For unsigned integers it is
......@@ -4366,7 +4225,8 @@ test.zig:6:2: error: found compile log statement
43664225 <li><a href="#builtin-divExact">@divExact</a></li>
43674226 <li><code>@import("std").math.divTrunc</code></li>
43684227 </ul>
4369 <h3 id="builtin-embedFile">@embedFile</h3>
4228 {#header_close#}
4229 {#header_open|@embedFile#}
43704230 <pre><code class="zig">@embedFile(comptime path: []const u8) -&gt; [X]u8</code></pre>
43714231 <p>
43724232 This function returns a compile time constant fixed-size array with length
......@@ -4380,17 +4240,20 @@ test.zig:6:2: error: found compile log statement
43804240 <ul>
43814241 <li><a href="#builtin-import">@import</a></li>
43824242 </ul>
4383 <h3 id="builtin-export">@export</h3>
4243 {#header_close#}
4244 {#header_open|@export#}
43844245 <pre><code class="zig">@export(comptime name: []const u8, target: var, linkage: builtin.GlobalLinkage) -&gt; []const u8</code></pre>
43854246 <p>
43864247 Creates a symbol in the output object file.
43874248 </p>
4388 <h3 id="builtin-tagName">@tagName</h3>
4249 {#header_close#}
4250 {#header_open|@tagName#}
43894251 <pre><code class="zig">@tagName(value: var) -&gt; []const u8</code></pre>
43904252 <p>
43914253 Converts an enum value or union value to a slice of bytes representing the name.
43924254 </p>
4393 <h3 id="builtin-TagType">@TagType</h3>
4255 {#header_close#}
4256 {#header_open|@TagType#}
43944257 <pre><code class="zig">@TagType(T: type) -&gt; type</code></pre>
43954258 <p>
43964259 For an enum, returns the integer type that is used to store the enumeration value.
......@@ -4398,7 +4261,8 @@ test.zig:6:2: error: found compile log statement
43984261 <p>
43994262 For a union, returns the enum type that is used to store the tag value.
44004263 </p>
4401 <h3 id="builtin-errorName">@errorName</h3>
4264 {#header_close#}
4265 {#header_open|@errorName#}
44024266 <pre><code class="zig">@errorName(err: error) -&gt; []u8</code></pre>
44034267 <p>
44044268 This function returns the string representation of an error. If an error
......@@ -4413,14 +4277,16 @@ test.zig:6:2: error: found compile log statement
44134277 or all calls have a compile-time known value for <code>err</code>, then no
44144278 error name table will be generated.
44154279 </p>
4416 <h3 id="builtin-errorReturnTrace">@errorReturnTrace</h3>
4280 {#header_close#}
4281 {#header_open|@errorReturnTrace#}
44174282 <pre><code class="zig">@errorReturnTrace() -&gt; ?&amp;builtin.StackTrace</code></pre>
44184283 <p>
44194284 If the binary is built with error return tracing, and this function is invoked in a
44204285 function that calls a function with an error or error union return type, returns a
44214286 stack trace object. Otherwise returns `null`.
44224287 </p>
4423 <h3 id="builtin-fence">@fence</h3>
4288 {#header_close#}
4289 {#header_open|@fence#}
44244290 <pre><code class="zig">@fence(order: AtomicOrder)</code></pre>
44254291 <p>
44264292 The <code>fence</code> function is used to introduce happens-before edges between operations.
......@@ -4432,13 +4298,15 @@ test.zig:6:2: error: found compile log statement
44324298 <ul>
44334299 <li><a href="#compile-variables">Compile Variables</a></li>
44344300 </ul>
4435 <h3 id="builtin-fieldParentPtr">@fieldParentPtr</h3>
4301 {#header_close#}
4302 {#header_open|@fieldParentPtr#}
44364303 <pre><code class="zig">@fieldParentPtr(comptime ParentType: type, comptime field_name: []const u8,
44374304 field_ptr: &amp;T) -&gt; &amp;ParentType</code></pre>
44384305 <p>
44394306 Given a pointer to a field, returns the base pointer of a struct.
44404307 </p>
4441 <h3 id="builtin-frameAddress">@frameAddress</h3>
4308 {#header_close#}
4309 {#header_open|@frameAddress#}
44424310 <pre><code class="zig">@frameAddress()</code></pre>
44434311 <p>
44444312 This function returns the base pointer of the current stack frame.
......@@ -4451,7 +4319,8 @@ test.zig:6:2: error: found compile log statement
44514319 <p>
44524320 This function is only valid within function scope.
44534321 </p>
4454 <h3 id="builtin-import">@import</h3>
4322 {#header_close#}
4323 {#header_open|@import#}
44554324 <pre><code class="zig">@import(comptime path: []u8) -&gt; (namespace)</code></pre>
44564325 <p>
44574326 This function finds a zig file corresponding to <code>path</code> and imports all the
......@@ -4474,7 +4343,8 @@ test.zig:6:2: error: found compile log statement
44744343 <li><a href="#compile-variables">Compile Variables</a></li>
44754344 <li><a href="#builtin-embedFile">@embedFile</a></li>
44764345 </ul>
4477 <h3 id="builtin-inlineCall">@inlineCall</h3>
4346 {#header_close#}
4347 {#header_open|@inlineCall#}
44784348 <pre><code class="zig">@inlineCall(function: X, args: ...) -&gt; Y</code></pre>
44794349 <p>
44804350 This calls a function, in the same way that invoking an expression with parentheses does:
......@@ -4493,17 +4363,20 @@ fn add(a: i32, b: i32) -&gt; i32 { a + b }</code></pre>
44934363 <ul>
44944364 <li><a href="#builtin-noInlineCall">@noInlineCall</a></li>
44954365 </ul>
4496 <h3 id="builtin-intToPtr">@intToPtr</h3>
4366 {#header_close#}
4367 {#header_open|@intToPtr#}
44974368 <pre><code class="zig">@intToPtr(comptime DestType: type, int: usize) -&gt; DestType</code></pre>
44984369 <p>
44994370 Converts an integer to a pointer. To convert the other way, use <a href="#builtin-ptrToInt">@ptrToInt</a>.
45004371 </p>
4501 <h3 id="builtin-IntType">@IntType</h3>
4372 {#header_close#}
4373 {#header_open|@IntType#}
45024374 <pre><code class="zig">@IntType(comptime is_signed: bool, comptime bit_count: u8) -&gt; type</code></pre>
45034375 <p>
45044376 This function returns an integer type with the given signness and bit count.
45054377 </p>
4506 <h3 id="builtin-maxValue">@maxValue</h3>
4378 {#header_close#}
4379 {#header_open|@maxValue#}
45074380 <pre><code class="zig">@maxValue(comptime T: type) -&gt; (number literal)</code></pre>
45084381 <p>
45094382 This function returns the maximum value of the integer type <code>T</code>.
......@@ -4511,7 +4384,8 @@ fn add(a: i32, b: i32) -&gt; i32 { a + b }</code></pre>
45114384 <p>
45124385 The result is a compile time constant.
45134386 </p>
4514 <h3 id="builtin-memberCount">@memberCount</h3>
4387 {#header_close#}
4388 {#header_open|@memberCount#}
45154389 <pre><code class="zig">@memberCount(comptime T: type) -&gt; (number literal)</code></pre>
45164390 <p>
45174391 This function returns the number of enum values in an enum type.
......@@ -4519,11 +4393,14 @@ fn add(a: i32, b: i32) -&gt; i32 { a + b }</code></pre>
45194393 <p>
45204394 The result is a compile time constant.
45214395 </p>
4522 <h3 id="builtin-memberName">@memberName</h3>
4396 {#header_close#}
4397 {#header_open|@memberName#}
45234398 <p>TODO</p>
4524 <h3 id="builtin-memberType">@memberType</h3>
4399 {#header_close#}
4400 {#header_open|@memberType#}
45254401 <p>TODO</p>
4526 <h3 id="builtin-memcpy">@memcpy</h3>
4402 {#header_close#}
4403 {#header_open|@memcpy#}
45274404 <pre><code class="zig">@memcpy(noalias dest: &amp;u8, noalias source: &amp;const u8, byte_count: usize)</code></pre>
45284405 <p>
45294406 This function copies bytes from one region of memory to another. <code>dest</code> and
......@@ -4540,7 +4417,8 @@ fn add(a: i32, b: i32) -&gt; i32 { a + b }</code></pre>
45404417 <p>There is also a standard library function for this:</p>
45414418 <pre><code class="zig">const mem = @import("std").mem;
45424419mem.copy(u8, dest[0...byte_count], source[0...byte_count]);</code></pre>
4543 <h3 id="builtin-memset">@memset</h3>
4420 {#header_close#}
4421 {#header_open|@memset#}
45444422 <pre><code class="zig">@memset(dest: &amp;u8, c: u8, byte_count: usize)</code></pre>
45454423 <p>
45464424 This function sets a region of memory to <code>c</code>. <code>dest</code> is a pointer.
......@@ -4556,7 +4434,8 @@ mem.copy(u8, dest[0...byte_count], source[0...byte_count]);</code></pre>
45564434 <p>There is also a standard library function for this:</p>
45574435 <pre><code>const mem = @import("std").mem;
45584436mem.set(u8, dest, c);</code></pre>
4559 <h3 id="builtin-minValue">@minValue</h3>
4437 {#header_close#}
4438 {#header_open|@minValue#}
45604439 <pre><code class="zig">@minValue(comptime T: type) -&gt; (number literal)</code></pre>
45614440 <p>
45624441 This function returns the minimum value of the integer type T.
......@@ -4564,7 +4443,8 @@ mem.set(u8, dest, c);</code></pre>
45644443 <p>
45654444 The result is a compile time constant.
45664445 </p>
4567 <h3 id="builtin-mod">@mod</h3>
4446 {#header_close#}
4447 {#header_open|@mod#}
45684448 <pre><code class="zig">@mod(numerator: T, denominator: T) -&gt; T</code></pre>
45694449 <p>
45704450 Modulus division. For unsigned integers this is the same as
......@@ -4579,14 +4459,16 @@ mem.set(u8, dest, c);</code></pre>
45794459 <li><a href="#builtin-rem">@rem</a></li>
45804460 <li><code>@import("std").math.mod</code></li>
45814461 </ul>
4582 <h3 id="builtin-mulWithOverflow">@mulWithOverflow</h3>
4462 {#header_close#}
4463 {#header_open|@mulWithOverflow#}
45834464 <pre><code class="zig">@mulWithOverflow(comptime T: type, a: T, b: T, result: &amp;T) -&gt; bool</code></pre>
45844465 <p>
45854466 Performs <code>*result = a * b</code>. If overflow or underflow occurs,
45864467 stores the overflowed bits in <code>result</code> and returns <code>true</code>.
45874468 If no overflow or underflow occurs, returns <code>false</code>.
45884469 </p>
4589 <h3 id="builtin-noInlineCall">@noInlineCall</h3>
4470 {#header_close#}
4471 {#header_open|@noInlineCall#}
45904472 <pre><code class="zig">@noInlineCall(function: var, args: ...) -&gt; var</code></pre>
45914473 <p>
45924474 This calls a function, in the same way that invoking an expression with parentheses does:
......@@ -4605,12 +4487,14 @@ fn add(a: i32, b: i32) -&gt; i32 { a + b }</code></pre>
46054487 <ul>
46064488 <li><a href="#builtin-inlineCall">@inlineCall</a></li>
46074489 </ul>
4608 <h3 id="builtin-offsetOf">@offsetOf</h3>
4490 {#header_close#}
4491 {#header_open|@offsetOf#}
46094492 <pre><code class="zig">@offsetOf(comptime T: type, comptime field_name: [] const u8) -&gt; (number literal)</code></pre>
46104493 <p>
46114494 This function returns the byte offset of a field relative to its containing struct.
46124495 </p>
4613 <h3 id="builtin-OpaqueType">@OpaqueType</h3>
4496 {#header_close#}
4497 {#header_open|@OpaqueType#}
46144498 <pre><code class="zig">@OpaqueType() -&gt; type</code></pre>
46154499 <p>
46164500 Creates a new type with an unknown size and alignment.
......@@ -4630,7 +4514,8 @@ export fn foo(w: &amp;Wat) {
46304514test.zig:5:9: error: expected type '&amp;Derp', found '&amp;Wat'
46314515 bar(w);
46324516 ^</code></pre>
4633 <h3 id="builtin-panic">@panic</h3>
4517 {#header_close#}
4518 {#header_open|@panic#}
46344519 <pre><code class="zig">@panic(message: []const u8) -&gt; noreturn</code></pre>
46354520 <p>
46364521 Invokes the panic handler function. By default the panic handler function
......@@ -4649,12 +4534,14 @@ test.zig:5:9: error: expected type '&amp;Derp', found '&amp;Wat'
46494534 <li><a href="#root-source-file">Root Source File</a></li>
46504535 </ul>
46514536
4652 <h3 id="builtin-ptrCast">@ptrCast</h3>
4537 {#header_close#}
4538 {#header_open|@ptrCast#}
46534539 <pre><code class="zig">@ptrCast(comptime DestType: type, value: var) -&gt; DestType</code></pre>
46544540 <p>
46554541 Converts a pointer of one type to a pointer of another type.
46564542 </p>
4657 <h3 id="builtin-ptrToInt">@ptrToInt</h3>
4543 {#header_close#}
4544 {#header_open|@ptrToInt#}
46584545 <pre><code class="zig">@ptrToInt(value: var) -&gt; usize</code></pre>
46594546 <p>
46604547 Converts <code>value</code> to a <code>usize</code> which is the address of the pointer. <code>value</code> can be one of these types:
......@@ -4667,7 +4554,8 @@ test.zig:5:9: error: expected type '&amp;Derp', found '&amp;Wat'
46674554 </ul>
46684555 <p>To convert the other way, use <a href="#builtin-intToPtr">@intToPtr</a></p>
46694556
4670 <h3 id="builtin-rem">@rem</h3>
4557 {#header_close#}
4558 {#header_open|@rem#}
46714559 <pre><code class="zig">@rem(numerator: T, denominator: T) -&gt; T</code></pre>
46724560 <p>
46734561 Remainder division. For unsigned integers this is the same as
......@@ -4682,7 +4570,8 @@ test.zig:5:9: error: expected type '&amp;Derp', found '&amp;Wat'
46824570 <li><a href="#builtin-mod">@mod</a></li>
46834571 <li><code>@import("std").math.rem</code></li>
46844572 </ul>
4685 <h3 id="builtin-returnAddress">@returnAddress</h3>
4573 {#header_close#}
4574 {#header_open|@returnAddress#}
46864575 <pre><code class="zig">@returnAddress()</code></pre>
46874576 <p>
46884577 This function returns a pointer to the return address of the current stack
......@@ -4696,13 +4585,15 @@ test.zig:5:9: error: expected type '&amp;Derp', found '&amp;Wat'
46964585 This function is only valid within function scope.
46974586 </p>
46984587
4699 <h3 id="builtin-setDebugSafety">@setDebugSafety</h3>
4588 {#header_close#}
4589 {#header_open|@setDebugSafety#}
47004590 <pre><code class="zig">@setDebugSafety(scope, safety_on: bool)</code></pre>
47014591 <p>
47024592 Sets whether debug safety checks are on for a given scope.
47034593 </p>
47044594
4705 <h3 id="builtin-setEvalBranchQuota">@setEvalBranchQuota</h3>
4595 {#header_close#}
4596 {#header_open|@setEvalBranchQuota#}
47064597 <pre><code class="zig">@setEvalBranchQuota(new_quota: usize)</code></pre>
47074598 <p>
47084599 Changes the maximum number of backwards branches that compile-time code
......@@ -4737,7 +4628,8 @@ test.zig:5:9: error: expected type '&amp;Derp', found '&amp;Wat'
47374628 <li><a href="#comptime">comptime</a></li>
47384629 </ul>
47394630
4740 <h3 id="builtin-setFloatMode">@setFloatMode</h3>
4631 {#header_close#}
4632 {#header_open|@setFloatMode#}
47414633 <pre><code class="zig">@setFloatMode(scope, mode: @import("builtin").FloatMode)</code></pre>
47424634 <p>
47434635 Sets the floating point mode for a given scope. Possible values are:
......@@ -4768,7 +4660,8 @@ test.zig:5:9: error: expected type '&amp;Derp', found '&amp;Wat'
47684660 <li><a href="#float-operations">Floating Point Operations</a></li>
47694661 </ul>
47704662
4771 <h3 id="builtin-setGlobalLinkage">@setGlobalLinkage</h3>
4663 {#header_close#}
4664 {#header_open|@setGlobalLinkage#}
47724665 <pre><code class="zig">@setGlobalLinkage(global_variable_name, comptime linkage: GlobalLinkage)</code></pre>
47734666 <p>
47744667 <code>GlobalLinkage</code> can be found with <code>@import("builtin").GlobalLinkage</code>.
......@@ -4777,12 +4670,14 @@ test.zig:5:9: error: expected type '&amp;Derp', found '&amp;Wat'
47774670 <ul>
47784671 <li><a href="#compile-variables">Compile Variables</a></li>
47794672 </ul>
4780 <h3 id="builtin-setGlobalSection">@setGlobalSection</h3>
4673 {#header_close#}
4674 {#header_open|@setGlobalSection#}
47814675 <pre><code class="zig">@setGlobalSection(global_variable_name, comptime section_name: []const u8) -&gt; bool</code></pre>
47824676 <p>
47834677 Puts the global variable in the specified section.
47844678 </p>
4785 <h3 id="builtin-shlExact">@shlExact</h3>
4679 {#header_close#}
4680 {#header_open|@shlExact#}
47864681 <pre><code class="zig">@shlExact(value: T, shift_amt: Log2T) -&gt; T</code></pre>
47874682 <p>
47884683 Performs the left shift operation (<code>&lt;&lt;</code>). Caller guarantees
......@@ -4797,7 +4692,8 @@ test.zig:5:9: error: expected type '&amp;Derp', found '&amp;Wat'
47974692 <li><a href="#builtin-shrExact">@shrExact</a></li>
47984693 <li><a href="#builtin-shlWithOverflow">@shlWithOverflow</a></li>
47994694 </ul>
4800 <h3 id="builtin-shlWithOverflow">@shlWithOverflow</h3>
4695 {#header_close#}
4696 {#header_open|@shlWithOverflow#}
48014697 <pre><code class="zig">@shlWithOverflow(comptime T: type, a: T, shift_amt: Log2T, result: &amp;T) -&gt; bool</code></pre>
48024698 <p>
48034699 Performs <code>*result = a &lt;&lt; b</code>. If overflow or underflow occurs,
......@@ -4813,7 +4709,8 @@ test.zig:5:9: error: expected type '&amp;Derp', found '&amp;Wat'
48134709 <li><a href="#builtin-shlExact">@shlExact</a></li>
48144710 <li><a href="#builtin-shrExact">@shrExact</a></li>
48154711 </ul>
4816 <h3 id="builtin-shrExact">@shrExact</h3>
4712 {#header_close#}
4713 {#header_open|@shrExact#}
48174714 <pre><code class="zig">@shrExact(value: T, shift_amt: Log2T) -&gt; T</code></pre>
48184715 <p>
48194716 Performs the right shift operation (<code>&gt;&gt;</code>). Caller guarantees
......@@ -4827,7 +4724,8 @@ test.zig:5:9: error: expected type '&amp;Derp', found '&amp;Wat'
48274724 <ul>
48284725 <li><a href="#builtin-shlExact">@shlExact</a></li>
48294726 </ul>
4830 <h3 id="builtin-sizeOf">@sizeOf</h3>
4727 {#header_close#}
4728 {#header_open|@sizeOf#}
48314729 <pre><code class="zig">@sizeOf(comptime T: type) -&gt; (number literal)</code></pre>
48324730 <p>
48334731 This function returns the number of bytes it takes to store <code>T</code> in memory.
......@@ -4835,14 +4733,16 @@ test.zig:5:9: error: expected type '&amp;Derp', found '&amp;Wat'
48354733 <p>
48364734 The result is a target-specific compile time constant.
48374735 </p>
4838 <h3 id="builtin-subWithOverflow">@subWithOverflow</h3>
4736 {#header_close#}
4737 {#header_open|@subWithOverflow#}
48394738 <pre><code class="zig">@subWithOverflow(comptime T: type, a: T, b: T, result: &amp;T) -&gt; bool</code></pre>
48404739 <p>
48414740 Performs <code>*result = a - b</code>. If overflow or underflow occurs,
48424741 stores the overflowed bits in <code>result</code> and returns <code>true</code>.
48434742 If no overflow or underflow occurs, returns <code>false</code>.
48444743 </p>
4845 <h3 id="builtin-truncate">@truncate</h3>
4744 {#header_close#}
4745 {#header_open|@truncate#}
48464746 <pre><code class="zig">@truncate(comptime T: type, integer) -&gt; T</code></pre>
48474747 <p>
48484748 This function truncates bits from an integer type, resulting in a smaller
......@@ -4865,7 +4765,8 @@ const b: u8 = @truncate(u8, a);
48654765 of endianness on the target platform.
48664766 </p>
48674767
4868 <h3 id="builtin-typeId">@typeId</h3>
4768 {#header_close#}
4769 {#header_open|@typeId#}
48694770 <pre><code class="zig">@typeId(comptime T: type) -&gt; @import("builtin").TypeId</code></pre>
48704771 <p>
48714772 Returns which kind of type something is. Possible values:
......@@ -4898,20 +4799,24 @@ const b: u8 = @truncate(u8, a);
48984799 Opaque,
48994800};</code></pre>
49004801
4901 <h3 id="builtin-typeName">@typeName</h3>
4802 {#header_close#}
4803 {#header_open|@typeName#}
49024804 <pre><code class="zig">@typeName(T: type) -&gt; []u8</code></pre>
49034805 <p>
49044806 This function returns the string representation of a type.
49054807 </p>
49064808
4907 <h3 id="builtin-typeOf">@typeOf</h3>
4809 {#header_close#}
4810 {#header_open|@typeOf#}
49084811 <pre><code class="zig">@typeOf(expression) -&gt; type</code></pre>
49094812 <p>
49104813 This function returns a compile-time constant, which is the type of the
49114814 expression passed as an argument. The expression is evaluated.
49124815 </p>
49134816
4914 <h2 id="build-mode">Build Mode</h2>
4817 {#header_close#}
4818 {#header_close#}
4819 {#header_open|Build Mode#}
49154820 <p>
49164821 Zig has three build modes:
49174822 </p>
......@@ -4935,21 +4840,23 @@ pub fn build(b: &amp;Builder) {
49354840 </p>
49364841 <pre><code class="sh"> -Drelease-safe=(bool) optimizations on and safety on
49374842 -Drelease-fast=(bool) optimizations on and safety off</code></pre>
4938 <h3 id="build-mode-debug">Debug</h2>
4843 {#header_open|Debug#}
49394844 <pre><code class="sh">$ zig build-exe example.zig</code></pre>
49404845 <ul>
49414846 <li>Fast compilation speed</li>
49424847 <li>Safety checks enabled</li>
49434848 <li>Slow runtime performance</li>
49444849 </ul>
4945 <h3 id="build-mode-release-fast">ReleaseFast</h2>
4850 {#header_close#}
4851 {#header_open|ReleaseFast#}
49464852 <pre><code class="sh">$ zig build-exe example.zig --release-fast</code></pre>
49474853 <ul>
49484854 <li>Fast runtime performance</li>
49494855 <li>Safety checks disabled</li>
49504856 <li>Slow compilation speed</li>
49514857 </ul>
4952 <h3 id="build-mode-release-safe">ReleaseSafe</h2>
4858 {#header_close#}
4859 {#header_open|ReleaseSafe#}
49534860 <pre><code class="sh">$ zig build-exe example.zig --release-safe</code></pre>
49544861 <ul>
49554862 <li>Medium runtime performance</li>
......@@ -4962,7 +4869,9 @@ pub fn build(b: &amp;Builder) {
49624869 <li><a href="#zig-build-system">Zig Build System</a></li>
49634870 <li><a href="#undefined-behavior">Undefined Behavior</a></li>
49644871 </ul>
4965 <h2 id="undefined-behavior">Undefined Behavior</h2>
4872 {#header_close#}
4873 {#header_close#}
4874 {#header_open|Undefined Behavior#}
49664875 <p>
49674876 Zig has many instances of undefined behavior. If undefined behavior is
49684877 detected at compile-time, Zig emits an error. Most undefined behavior that
......@@ -5000,7 +4909,7 @@ Test 1/1 safety check...reached unreachable code
50004909
50014910Tests failed. Use the following command to reproduce the failure:
50024911./test</code></pre>
5003 <h3 id="undef-unreachable">Reaching Unreachable Code</h3>
4912 {#header_open|Reaching Unreachable Code#}
50044913 <p>At compile-time:</p>
50054914 <pre><code class="zig">comptime {
50064915 assert(false);
......@@ -5019,7 +4928,8 @@ fn assert(ok: bool) {
50194928comptime {
50204929 ^</code></pre>
50214930 <p>At runtime crashes with the message <code>reached unreachable code</code> and a stack trace.</p>
5022 <h3 id="undef-index-out-of-bounds">Index out of Bounds</h3>
4931 {#header_close#}
4932 {#header_open|Index out of Bounds#}
50234933 <p>At compile-time:</p>
50244934 <pre><code class="zig">comptime {
50254935 const array = "hello";
......@@ -5030,7 +4940,8 @@ comptime {
50304940 const garbage = array[5];
50314941 ^</code></pre>
50324942 <p>At runtime crashes with the message <code>index out of bounds</code> and a stack trace.</p>
5033 <h3 id="undef-cast-negative-unsigned">Cast Negative Number to Unsigned Integer</h3>
4943 {#header_close#}
4944 {#header_open|Cast Negative Number to Unsigned Integer#}
50344945 <p>At compile-time:</p>
50354946 <pre><code class="zig">comptime {
50364947 const value: i32 = -1;
......@@ -5044,7 +4955,8 @@ comptime {
50444955 If you are trying to obtain the maximum value of an unsigned integer, use <code>@maxValue(T)</code>,
50454956 where <code>T</code> is the integer type, such as <code>u32</code>.
50464957 </p>
5047 <h3 id="undef-cast-truncates-data">Cast Truncates Data</h3>
4958 {#header_close#}
4959 {#header_open|Cast Truncates Data#}
50484960 <p>At compile-time:</p>
50494961 <pre><code class="zig">comptime {
50504962 const spartan_count: u16 = 300;
......@@ -5060,8 +4972,9 @@ test.zig:3:20: error: cast from 'u16' to 'u8' truncates bits
50604972 where <code>T</code> is the integer type, such as <code>u32</code>, and <code>value</code>
50614973 is the value you want to truncate.
50624974 </p>
5063 <h3 id="undef-integer-overflow">Integer Overflow</h3>
5064 <h4 id="undef-int-overflow-default">Default Operations</h4>
4975 {#header_close#}
4976 {#header_open|Integer Overflow#}
4977 {#header_open|Default Operations#}
50654978 <p>The following operators can cause integer overflow:</p>
50664979 <ul>
50674980 <li><code>+</code> (addition)</li>
......@@ -5083,7 +4996,8 @@ test.zig:3:20: error: cast from 'u16' to 'u8' truncates bits
50834996 byte += 1;
50844997 ^</code></pre>
50854998 <p>At runtime crashes with the message <code>integer overflow</code> and a stack trace.</p>
5086 <h4 id="undef-int-overflow-std">Standard Library Math Functions</h4>
4999 {#header_close#}
5000 {#header_open|Standard Library Math Functions#}
50875001 <p>These functions provided by the standard library return possible errors.</p>
50885002 <ul>
50895003 <li><code>@import("std").math.add</code></li>
......@@ -5112,7 +5026,8 @@ pub fn main() -&gt; %void {
51125026 <pre><code class="sh">$ zig build-exe test.zig
51135027$ ./test
51145028unable to add one: Overflow</code></pre>
5115 <h4 id="undef-int-overflow-builtin">Builtin Overflow Functions</h4>
5029 {#header_close#}
5030 {#header_open|Builtin Overflow Functions#}
51165031 <p>
51175032 These builtins return a <code>bool</code> of whether or not overflow
51185033 occurred, as well as returning the overflowed bits:
......@@ -5140,7 +5055,8 @@ pub fn main() -&gt; %void {
51405055 <pre><code class="sh">$ zig build-exe test.zig
51415056$ ./test
51425057overflowed result: 9</code></pre>
5143 <h4 id="undef-int-overflow-wrap">Wrapping Operations</h4>
5058 {#header_close#}
5059 {#header_open|Wrapping Operations#}
51445060 <p>
51455061 These operations have guaranteed wraparound semantics.
51465062 </p>
......@@ -5159,7 +5075,9 @@ test "wraparound addition and subtraction" {
51595075 const max_val = min_val -% 1;
51605076 assert(max_val == @maxValue(i32));
51615077}</code></pre>
5162 <h3 id="undef-shl-overflow">Exact Left Shift Overflow</h3>
5078 {#header_close#}
5079 {#header_close#}
5080 {#header_open|Exact Left Shift Overflow#}
51635081 <p>At compile-time:</p>
51645082 <pre><code class="zig">comptime {
51655083 const x = @shlExact(u8(0b01010101), 2);
......@@ -5169,7 +5087,8 @@ test "wraparound addition and subtraction" {
51695087 const x = @shlExact(u8(0b01010101), 2);
51705088 ^</code></pre>
51715089 <p>At runtime crashes with the message <code>left shift overflowed bits</code> and a stack trace.</p>
5172 <h3 id="undef-shr-overflow">Exact Right Shift Overflow</h3>
5090 {#header_close#}
5091 {#header_open|Exact Right Shift Overflow#}
51735092 <p>At compile-time:</p>
51745093 <pre><code class="zig">comptime {
51755094 const x = @shrExact(u8(0b10101010), 2);
......@@ -5179,7 +5098,8 @@ test "wraparound addition and subtraction" {
51795098 const x = @shrExact(u8(0b10101010), 2);
51805099 ^</code></pre>
51815100 <p>At runtime crashes with the message <code>right shift overflowed bits</code> and a stack trace.</p>
5182 <h3 id="undef-division-by-zero">Division by Zero</h3>
5101 {#header_close#}
5102 {#header_open|Division by Zero#}
51835103 <p>At compile-time:</p>
51845104 <pre><code class="zig">comptime {
51855105 const a: i32 = 1;
......@@ -5192,7 +5112,8 @@ test "wraparound addition and subtraction" {
51925112 ^</code></pre>
51935113 <p>At runtime crashes with the message <code>division by zero</code> and a stack trace.</p>
51945114
5195 <h3 id="undef-remainder-division-by-zero">Remainder Division by Zero</h3>
5115 {#header_close#}
5116 {#header_open|Remainder Division by Zero#}
51965117 <p>At compile-time:</p>
51975118 <pre><code class="zig">comptime {
51985119 const a: i32 = 10;
......@@ -5205,11 +5126,14 @@ test "wraparound addition and subtraction" {
52055126 ^</code></pre>
52065127 <p>At runtime crashes with the message <code>remainder division by zero</code> and a stack trace.</p>
52075128
5208 <h3 id="undef-exact-division-remainder">Exact Division Remainder</h3>
5129 {#header_close#}
5130 {#header_open|Exact Division Remainder#}
52095131 <p>TODO</p>
5210 <h3 id="undef-slice-widen-remainder">Slice Widen Remainder</h3>
5132 {#header_close#}
5133 {#header_open|Slice Widen Remainder#}
52115134 <p>TODO</p>
5212 <h3 id="undef-attempt-unwrap-null">Attempt to Unwrap Null</h3>
5135 {#header_close#}
5136 {#header_open|Attempt to Unwrap Null#}
52135137 <p>At compile-time:</p>
52145138 <pre><code class="zig">comptime {
52155139 const nullable_number: ?i32 = null;
......@@ -5235,7 +5159,8 @@ pub fn main() -&gt; %void {
52355159 <pre><code class="sh">% zig build-exe test.zig
52365160$ ./test
52375161it's null</code></pre>
5238 <h3 id="undef-attempt-unwrap-error">Attempt to Unwrap Error</h3>
5162 {#header_close#}
5163 {#header_open|Attempt to Unwrap Error#}
52395164 <p>At compile-time:</p>
52405165 <pre><code class="zig">comptime {
52415166 const number = %%getNumberOrFail();
......@@ -5274,7 +5199,8 @@ fn getNumberOrFail() -&gt; %i32 {
52745199$ ./test
52755200got error: UnableToReturnNumber</code></pre>
52765201
5277 <h3 id="undef-invalid-error-code">Invalid Error Code</h3>
5202 {#header_close#}
5203 {#header_open|Invalid Error Code#}
52785204 <p>At compile-time:</p>
52795205 <pre><code class="zig">error AnError;
52805206comptime {
......@@ -5287,16 +5213,21 @@ comptime {
52875213 const invalid_err = error(number);
52885214 ^</code></pre>
52895215 <p>At runtime crashes with the message <code>invalid error code</code> and a stack trace.</p>
5290 <h3 id="undef-invalid-enum-cast">Invalid Enum Cast</h3>
5216 {#header_close#}
5217 {#header_open|Invalid Enum Cast#}
52915218 <p>TODO</p>
52925219
5293 <h3 id="undef-incorrect-pointer-alignment">Incorrect Pointer Alignment</h3>
5220 {#header_close#}
5221 {#header_open|Incorrect Pointer Alignment#}
52945222 <p>TODO</p>
52955223
5296 <h3 id="undef-bad-union-field">Wrong Union Field Access</h3>
5224 {#header_close#}
5225 {#header_open|Wrong Union Field Access#}
52975226 <p>TODO</p>
52985227
5299 <h2 id="memory">Memory</h2>
5228 {#header_close#}
5229 {#header_close#}
5230 {#header_open|Memory#}
53005231 <p>TODO: explain no default allocator in zig</p>
53015232 <p>TODO: show how to use the allocator interface</p>
53025233 <p>TODO: mention debug allocator</p>
......@@ -5308,7 +5239,8 @@ comptime {
53085239 <li><a href="#pointers">Pointers</a></li>
53095240 </ul>
53105241
5311 <h2 id="compile-variables">Compile Variables</h2>
5242 {#header_close#}
5243 {#header_open|Compile Variables#}
53125244 <p>
53135245 Compile variables are accessible by importing the <code>"builtin"</code> package,
53145246 which the compiler makes available to every Zig source file. It contains
......@@ -5478,7 +5410,8 @@ pub const link_libs = [][]const u8 {
54785410 <ul>
54795411 <li><a href="#build-mode">Build Mode</a></li>
54805412 </ul>
5481 <h2 id="root-source-file">Root Source File</h2>
5413 {#header_close#}
5414 {#header_open|Root Source File#}
54825415 <p>TODO: explain how root source file finds other files</p>
54835416 <p>TODO: pub fn main</p>
54845417 <p>TODO: pub fn panic</p>
......@@ -5486,17 +5419,20 @@ pub const link_libs = [][]const u8 {
54865419 <p>TODO: order independent top level declarations</p>
54875420 <p>TODO: lazy analysis</p>
54885421 <p>TODO: using comptime { _ = @import() }</p>
5489 <h2 id="zig-test">Zig Test</h2>
5422 {#header_close#}
5423 {#header_open|Zig Test#}
54905424 <p>TODO: basic usage</p>
54915425 <p>TODO: lazy analysis</p>
54925426 <p>TODO: --test-filter</p>
54935427 <p>TODO: --test-name-prefix</p>
54945428 <p>TODO: testing in releasefast and releasesafe mode. assert still works</p>
5495 <h2 id="zig-build-system">Zig Build System</h2>
5429 {#header_close#}
5430 {#header_open|Zig Build System#}
54965431 <p>TODO: explain purpose, it's supposed to replace make/cmake</p>
54975432 <p>TODO: example of building a zig executable</p>
54985433 <p>TODO: example of building a C library</p>
5499 <h2 id="c">C</h2>
5434 {#header_close#}
5435 {#header_open|C#}
55005436 <p>
55015437 Although Zig is independent of C, and, unlike most other languages, does not depend on libc,
55025438 Zig acknowledges the importance of interacting with existing C code.
......@@ -5504,7 +5440,7 @@ pub const link_libs = [][]const u8 {
55045440 <p>
55055441 There are a few ways that Zig facilitates C interop.
55065442 </p>
5507 <h3 id="c-type-primitives">C Type Primitives</h3>
5443 {#header_open|C Type Primitives#}
55085444 <p>
55095445 These have guaranteed C ABI compatibility and can be used like any other type.
55105446 </p>
......@@ -5524,7 +5460,8 @@ pub const link_libs = [][]const u8 {
55245460 <ul>
55255461 <li><a href="#primitive-types">Primitive Types</a></li>
55265462 </ul>
5527 <h3 id="c-string-literals">C String Literals</h3>
5463 {#header_close#}
5464 {#header_open|C String Literals#}
55285465 <pre><code class="zig">extern fn puts(&amp;const u8);
55295466
55305467pub fn main() -&gt; %void {
......@@ -5539,7 +5476,8 @@ pub fn main() -&gt; %void {
55395476 <ul>
55405477 <li><a href="#string-literals">String Literals</a></li>
55415478 </ul>
5542 <h3 id="c-import">Import from C Header File</h3>
5479 {#header_close#}
5480 {#header_open|Import from C Header File#}
55435481 <p>
55445482 The <code>@cImport</code> builtin function can be used
55455483 to directly import symbols from .h files:
......@@ -5574,11 +5512,13 @@ const c = @cImport({
55745512 <li><a href="#builtin-cUndef">@cUndef</a></li>
55755513 <li><a href="#builtin-import">@import</a></li>
55765514 </ul>
5577 <h3 id="mixing-object-files">Mixing Object Files</h3>
5515 {#header_close#}
5516 {#header_open|Mixing Object Files#}
55785517 <p>
55795518 You can mix Zig object files with any other object files that respect the C ABI. Example:
55805519 </p>
5581 <h4>base64.zig</h4>
5520 {#header_close#}
5521 {#header_open|base64.zig#}
55825522 <pre><code class="zig">const base64 = @import("std").base64;
55835523
55845524export fn decode_base_64(dest_ptr: &amp;u8, dest_len: usize,
......@@ -5592,7 +5532,7 @@ export fn decode_base_64(dest_ptr: &amp;u8, dest_len: usize,
55925532 return decoded_size;
55935533}
55945534</code></pre>
5595 <h4>test.c</h4>
5535{{teheader_open:st.c}}
55965536 <pre><code class="c">// This header is generated by zig from base64.zig
55975537#include "base64.h"
55985538
......@@ -5609,7 +5549,8 @@ int main(int argc, char **argv) {
56095549
56105550 return 0;
56115551}</code></pre>
5612 <h4>build.zig</h4>
5552 {#header_close#}
5553 {#header_open|build.zig#}
56135554 <pre><code class="zig">const Builder = @import("std").build.Builder;
56145555
56155556pub fn build(b: &amp;Builder) {
......@@ -5625,7 +5566,8 @@ pub fn build(b: &amp;Builder) {
56255566
56265567 b.default_step.dependOn(&amp;exe.step);
56275568}</code></pre>
5628 <h4>Terminal</h4>
5569 {#header_close#}
5570 {#header_open|Terminal#}
56295571 <pre><code class="sh">$ zig build
56305572$ ./test
56315573all your base are belong to us</code></pre>
......@@ -5634,7 +5576,9 @@ all your base are belong to us</code></pre>
56345576 <li><a href="#targets">Targets</a></li>
56355577 <li><a href="#zig-build-system">Zig Build System</a></li>
56365578 </ul>
5637 <h2 id="targets">Targets</h2>
5579 {#header_close#}
5580 {#header_close#}
5581 {#header_open|Targets#}
56385582 <p>
56395583 Zig supports generating code for all targets that LLVM supports. Here is
56405584 what it looks like to execute <code>zig targets</code> on a Linux x86_64
......@@ -5760,14 +5704,15 @@ Environments:
57605704 Linux x86_64. Not all standard library code requires operating system abstractions, however,
57615705 so things such as generic data structures work an all above platforms.
57625706 </p>
5763 <h2 id="style-guide">Style Guide</h2>
5707 {#header_close#}
5708 {#header_open|Style Guide#}
57645709 <p>
57655710These coding conventions are not enforced by the compiler, but they are shipped in
57665711this documentation along with the compiler in order to provide a point of
57675712reference, should anyone wish to point to an authority on agreed upon Zig
57685713coding style.
57695714 </p>
5770 <h3 id="style-guide-whitespace">Whitespace</h3>
5715 {#header_open|Whitespace#}
57715716 <ul>
57725717 <li>
57735718 4 space indentation
......@@ -5782,7 +5727,8 @@ coding style.
57825727 Line length: aim for 100; use common sense.
57835728 </li>
57845729 </ul>
5785 <h3 id="style-guide-names">Names</h3>
5730 {#header_close#}
5731 {#header_open|Names#}
57865732 <p>
57875733 Roughly speaking: <code>camelCaseFunctionName</code>, <code>TitleCaseTypeName</code>,
57885734 <code>snake_case_variable_name</code>. More precisely:
......@@ -5816,7 +5762,8 @@ coding style.
58165762 do what makes sense. For example, if there is an established convention such as
58175763 <code>ENOENT</code>, follow the established convention.
58185764 </p>
5819 <h3 id="style-guide-examples">Examples</h3>
5765 {#header_close#}
5766 {#header_open|Examples#}
58205767 <pre><code class="zig">const namespace_name = @import("dir_name/file_name.zig");
58215768var global_var: i32 = undefined;
58225769const const_name = 42;
......@@ -5858,7 +5805,9 @@ fn readU32Be() -&gt; u32 {}</code></pre>
58585805 <p>
58595806 See the Zig Standard Library for more examples.
58605807 </p>
5861 <h2 id="grammar">Grammar</h2>
5808 {#header_close#}
5809 {#header_close#}
5810 {#header_open|Grammar#}
58625811 <pre><code>Root = many(TopLevelItem) EOF
58635812
58645813TopLevelItem = ErrorValueDecl | CompTimeExpression(Block) | TopLevelDecl | TestDecl
......@@ -6010,7 +5959,8 @@ KeywordLiteral = "true" | "false" | "null" | "undefined" | "error" | "this" | "u
60105959ContainerDecl = option("extern" | "packed")
60115960 ("struct" option(GroupedExpression) | "union" option("enum" option(GroupedExpression) | GroupedExpression) | ("enum" option(GroupedExpression)))
60125961 "{" many(ContainerMember) "}"</code></pre>
6013 <h2 id="zen">Zen</h2>
5962 {#header_close#}
5963 {#header_open|Zen#}
60145964 <ul>
60155965 <li>Communicate intent precisely.</li>
60165966 <li>Edge cases matter.</li>
......@@ -6024,8 +5974,10 @@ ContainerDecl = option("extern" | "packed")
60245974 <li>Minimize energy spent on coding style.</li>
60255975 <li>Together we serve end users.</li>
60265976 </ul>
6027 <h2>TODO</h2>
5977 {#header_close#}
5978 {#header_open|TODO#}
60285979 <p>TODO: document changes from a31b23c46ba2a8c28df01adc1aa0b4d878b9a5cf (compile time reflection additions)</p>
5980 {#header_close#}
60295981 </div>
60305982 <script src="highlight/highlight.pack.js"></script>
60315983 <script>hljs.initHighlightingOnLoad();</script>
std/hash_map.zig+1-2
......@@ -62,8 +62,7 @@ pub fn HashMap(comptime K: type, comptime V: type,
6262 .allocator = allocator,
6363 .size = 0,
6464 .max_distance_from_start_index = 0,
65 // it doesn't actually matter what we set this to since we use wrapping integer arithmetic
66 .modification_count = undefined,
65 .modification_count = if (want_modification_safety) 0 else {},
6766 };
6867 }
6968