authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2018-01-17 00:22:33-05:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2018-01-17 00:22:53-05:00
log5aefabe045ca9c6f961bb5354961fe483085f145
tree75b6100c1792c4789c757ee1ad8d0cf5c8e9b022
parent2774fe8a1b5364729ad9faa1562e280f348c68bd

docgen: validate See Also sections

See #465

3 files changed, 149 insertions(+), 353 deletions(-)

doc/docgen.zig+90-70
......@@ -35,9 +35,10 @@ pub fn main() -> %void {
3535 var file_out_stream = io.FileOutStream.init(&out_file);
3636 var buffered_out_stream = io.BufferedOutStream.init(&file_out_stream.stream);
3737
38 const toc = try genToc(allocator, in_file_name, input_file_bytes);
38 var tokenizer = Tokenizer.init(in_file_name, input_file_bytes);
39 var toc = try genToc(allocator, &tokenizer);
3940
40 try genHtml(allocator, toc, &buffered_out_stream.stream);
41 try genHtml(allocator, &tokenizer, &toc, &buffered_out_stream.stream);
4142 try buffered_out_stream.flush();
4243}
4344
......@@ -240,21 +241,22 @@ const HeaderOpen = struct {
240241 n: usize,
241242};
242243
243const Tag = enum {
244 Nav,
245 HeaderOpen,
246 HeaderClose,
244const SeeAlsoItem = struct {
245 name: []const u8,
246 token: Token,
247247};
248248
249249const Node = union(enum) {
250250 Content: []const u8,
251251 Nav,
252252 HeaderOpen: HeaderOpen,
253 SeeAlso: []const SeeAlsoItem,
253254};
254255
255256const Toc = struct {
256257 nodes: []Node,
257258 toc: []u8,
259 urls: std.HashMap([]const u8, Token, mem.hash_slice_u8, mem.eql_slice_u8),
258260};
259261
260262const Action = enum {
......@@ -262,11 +264,9 @@ const Action = enum {
262264 Close,
263265};
264266
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
267fn genToc(allocator: &mem.Allocator, tokenizer: &Tokenizer) -> %Toc {
268268 var urls = std.HashMap([]const u8, Token, mem.hash_slice_u8, mem.eql_slice_u8).init(allocator);
269 defer urls.deinit();
269 %defer urls.deinit();
270270
271271 var header_stack_size: usize = 0;
272272 var last_action = Action.Open;
......@@ -287,89 +287,98 @@ fn genToc(allocator: &mem.Allocator, source_file_name: []const u8, input_file_by
287287 switch (token.id) {
288288 Token.Id.Eof => {
289289 if (header_stack_size != 0) {
290 return parseError(&tokenizer, token, "unbalanced headers");
290 return parseError(tokenizer, token, "unbalanced headers");
291291 }
292292 try toc.write(" </ul>\n");
293293 break;
294294 },
295295 Token.Id.Content => {
296 try nodes.append(Node {.Content = input_file_bytes[token.start..token.end] });
296 try nodes.append(Node {.Content = tokenizer.buffer[token.start..token.end] });
297297 },
298298 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];
299 const tag_token = try eatToken(tokenizer, Token.Id.TagContent);
300 const tag_name = tokenizer.buffer[tag_token.start..tag_token.end];
301301
302 var tag: Tag = undefined;
303302 if (mem.eql(u8, tag_name, "nav")) {
304 tag = Tag.Nav;
303 _ = eatToken(tokenizer, Token.Id.BracketClose);
304
305 try nodes.append(Node.Nav);
305306 } else if (mem.eql(u8, tag_name, "header_open")) {
306 tag = Tag.HeaderOpen;
307 _ = eatToken(tokenizer, Token.Id.Separator);
308 const content_token = try eatToken(tokenizer, Token.Id.TagContent);
309 const content = tokenizer.buffer[content_token.start..content_token.end];
310 _ = eatToken(tokenizer, Token.Id.BracketClose);
311
307312 header_stack_size += 1;
313
314 const urlized = try urlize(allocator, content);
315 try nodes.append(Node{.HeaderOpen = HeaderOpen {
316 .name = content,
317 .url = urlized,
318 .n = header_stack_size,
319 }});
320 if (try urls.put(urlized, tag_token)) |other_tag_token| {
321 parseError(tokenizer, tag_token, "duplicate header url: #{}", urlized) catch {};
322 parseError(tokenizer, other_tag_token, "other tag here") catch {};
323 return error.ParseError;
324 }
325 if (last_action == Action.Open) {
326 try toc.writeByte('\n');
327 try toc.writeByteNTimes(' ', header_stack_size * 4);
328 try toc.write("<ul>\n");
329 } else {
330 last_action = Action.Open;
331 }
332 try toc.writeByteNTimes(' ', 4 + header_stack_size * 4);
333 try toc.print("<li><a href=\"#{}\">{}</a>", urlized, content);
308334 } else if (mem.eql(u8, tag_name, "header_close")) {
309335 if (header_stack_size == 0) {
310 return parseError(&tokenizer, tag_token, "unbalanced close header");
336 return parseError(tokenizer, tag_token, "unbalanced close header");
311337 }
312338 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;
339 _ = eatToken(tokenizer, Token.Id.BracketClose);
340
341 if (last_action == Action.Close) {
342 try toc.writeByteNTimes(' ', 8 + header_stack_size * 4);
343 try toc.write("</ul></li>\n");
344 } else {
345 try toc.write("</li>\n");
346 last_action = Action.Close;
347 }
348 } else if (mem.eql(u8, tag_name, "see_also")) {
349 var list = std.ArrayList(SeeAlsoItem).init(allocator);
350 %defer list.deinit();
351
352 while (true) {
353 const see_also_tok = tokenizer.next();
354 switch (see_also_tok.id) {
355 Token.Id.TagContent => {
356 const content = tokenizer.buffer[see_also_tok.start..see_also_tok.end];
357 try list.append(SeeAlsoItem {
358 .name = content,
359 .token = see_also_tok,
360 });
361 },
362 Token.Id.Separator => {},
363 Token.Id.BracketClose => {
364 try nodes.append(Node {.SeeAlso = list.toOwnedSlice() } );
365 break;
366 },
367 else => return parseError(tokenizer, see_also_tok, "invalid see_also token"),
359368 }
360 },
361 Tag.Nav => {
362 try nodes.append(Node.Nav);
363 },
369 }
370 } else {
371 return parseError(tokenizer, tag_token, "unrecognized tag name: {}", tag_name);
364372 }
365373 },
366 else => return parseError(&tokenizer, token, "invalid token"),
374 else => return parseError(tokenizer, token, "invalid token"),
367375 }
368376 }
369377
370378 return Toc {
371379 .nodes = nodes.toOwnedSlice(),
372380 .toc = toc_buf.toOwnedSlice(),
381 .urls = urls,
373382 };
374383}
375384
......@@ -393,7 +402,7 @@ fn urlize(allocator: &mem.Allocator, input: []const u8) -> %[]u8 {
393402 return buf.toOwnedSlice();
394403}
395404
396fn genHtml(allocator: &mem.Allocator, toc: &const Toc, out: &io.OutStream) -> %void {
405fn genHtml(allocator: &mem.Allocator, tokenizer: &Tokenizer, toc: &Toc, out: &io.OutStream) -> %void {
397406 for (toc.nodes) |node| {
398407 switch (node) {
399408 Node.Content => |data| {
......@@ -405,6 +414,17 @@ fn genHtml(allocator: &mem.Allocator, toc: &const Toc, out: &io.OutStream) -> %v
405414 Node.HeaderOpen => |info| {
406415 try out.print("<h{} id=\"{}\">{}</h{}>\n", info.n, info.url, info.name, info.n);
407416 },
417 Node.SeeAlso => |items| {
418 try out.write("<p>See also:</p><ul>\n");
419 for (items) |item| {
420 const url = try urlize(allocator, item.name);
421 if (!toc.urls.contains(url)) {
422 return parseError(tokenizer, item.token, "url not found: {}", url);
423 }
424 try out.print("<li><a href=\"#{}\">{}</a></li>\n", url, item.name);
425 }
426 try out.write("</ul>\n");
427 },
408428 }
409429 }
410430
doc/langref.html.in+55-283
......@@ -77,13 +77,7 @@ Hello, world!</code></pre>
7777pub fn main() -&gt; %void {
7878 warn("Hello, world!\n");
7979}</code></pre>
80 <p>See also:</p>
81 <ul>
82 <li><a href="#values">Values</a></li>
83 <li><a href="#builtin-import">@import</a></li>
84 <li><a href="#errors">Errors</a></li>
85 <li><a href="#root-source-file">Root Source File</a></li>
86 </ul>
80 {#see_also|Values|@import|Errors|Root Source File#}
8781 {#header_close#}
8882 {#header_open|Source Encoding#}
8983 <p>Zig source code is encoded in UTF-8. An invalid UTF-8 byte sequence results in a compile error.</p>
......@@ -391,13 +385,7 @@ value: 1234</code></pre>
391385 <td>an error code</td>
392386 </tr>
393387 </table>
394 <p>See also:</p>
395 <ul>
396 <li><a href="#integers">Integers</a></li>
397 <li><a href="#floats">Floats</a></li>
398 <li><a href="#void">void</a></li>
399 <li><a href="#errors">Errors</a></li>
400 </ul>
388 {#see_also|Integers|Floats|void|Errors#}
401389 {#header_close#}
402390 {#header_open|Primitive Values#}
403391 <table>
......@@ -426,11 +414,7 @@ value: 1234</code></pre>
426414 <td>refers to the thing in immediate scope</td>
427415 </tr>
428416 </table>
429 <p>See also:</p>
430 <ul>
431 <li><a href="#nullables">Nullables</a></li>
432 <li><a href="#this">this</a></li>
433 </ul>
417 {#see_also|Nullables|this#}
434418 {#header_close#}
435419 {#header_open|String Literals#}
436420 <pre><code class="zig">const assert = @import("std").debug.assert;
......@@ -452,11 +436,7 @@ test "string literals" {
452436}</code></pre>
453437 <pre><code class="sh">$ zig test string_literals.zig
454438Test 1/1 string literals...OK</code></pre>
455 <p>See also:</p>
456 <ul>
457 <li><a href="#arrays">Arrays</a></li>
458 <li><a href="#zig-test">Zig Test</a></li>
459 </ul>
439 {#see_also|Arrays|Zig Test#}
460440 {#header_open|Escape Sequences#}
461441 <table>
462442 <tr>
......@@ -538,10 +518,7 @@ Test 1/1 string literals...OK</code></pre>
538518 In this example the variable <code>c_string_literal</code> has type <code>&amp;const char</code> and
539519 has a terminating null byte.
540520 </p>
541 <p>See also:</p>
542 <ul>
543 <li><a href="#builtin-embedFile">@embedFile</a></li>
544 </ul>
521 {#see_also|@embedFile#}
545522 {#header_close#}
546523 {#header_close#}
547524 {#header_open|Assignment#}
......@@ -627,12 +604,7 @@ const binary_int = 0b11110000;</code></pre>
627604 integer overflow. Also available are operations such as <code>+%</code> and
628605 <code>-%</code> which are defined to have wrapping arithmetic on all targets.
629606 </p>
630 <p>See also:</p>
631 <ul>
632 <li><a href="#undef-integer-overflow">Integer Overflow</a></li>
633 <li><a href="#undef-division-by-zero">Division By Zero</a></li>
634 <li><a href="#undef-int-overflow-wrap">Wrapping Operations</a></li>
635 </ul>
607 {#see_also|Integer Overflow|Division by Zero|Wrapping Operations#}
636608 {#header_close#}
637609 {#header_close#}
638610 {#header_open|Floats#}
......@@ -680,11 +652,7 @@ $ zig build-exe test.zig --object foo.o
680652$ ./test
681653optimized = 1.0e-2
682654strict = 9.765625e-3</code></pre>
683 <p>See also:</p>
684 <ul>
685 <li><a href="#builtin-setFloatMode">@setFloatMode</a></li>
686 <li><a href="#undef-division-by-zero">Division By Zero</a></li>
687 </ul>
655 {#see_also|@setFloatMode|Division by Zero#}
688656 {#header_close#}
689657 {#header_open|Operators#}
690658 {#header_open|Table of Operators#}
......@@ -1402,11 +1370,7 @@ Test 1/4 iterate over an array...OK
14021370Test 2/4 modify an array...OK
14031371Test 3/4 compile-time array initalization...OK
14041372Test 4/4 array initialization with function calls...OK</code></pre>
1405 <p>See also:</p>
1406 <ul>
1407 <li><a href="#for">for</a></li>
1408 <li><a href="#slices">Slices</a></li>
1409 </ul>
1373 {#see_also|for|Slices#}
14101374 {#header_close#}
14111375 {#header_open|Pointers#}
14121376 <pre><code class="zig">const assert = @import("std").debug.assert;
......@@ -1659,11 +1623,7 @@ Tests failed. Use the following command to reproduce the failure:
16591623 <p>Instead, use <a href="#builtin-bitCast">@bitCast</a>:
16601624 <pre><code class="zig">@bitCast(u32, f32(12.34))</code></pre>
16611625 <p>As an added benefit, the <code>@bitcast</code> version works at compile-time.</p>
1662 <p>See also:</p>
1663 <ul>
1664 <li><a href="#slices">Slices</a></li>
1665 <li><a href="#memory">Memory</a></li>
1666 </ul>
1626 {#see_also|Slices|Memory#}
16671627 {#header_close#}
16681628 {#header_close#}
16691629 {#header_open|Slices#}
......@@ -1760,12 +1720,7 @@ test "slice widening" {
17601720Test 1/3 using slices for strings...OK
17611721Test 2/3 slice pointer...OK
17621722Test 3/3 slice widening...OK</code></pre>
1763 <p>See also:</p>
1764 <ul>
1765 <li><a href="#pointers">Pointers</a></li>
1766 <li><a href="#for">for</a></li>
1767 <li><a href="#arrays">Arrays</a></li>
1768 </ul>
1723 {#see_also|Pointers|for|Arrays#}
17691724 {#header_close#}
17701725 {#header_open|struct#}
17711726 <pre><code class="zig">// Declare a struct.
......@@ -1907,11 +1862,7 @@ Test 1/4 dot product...OK
19071862Test 2/4 struct namespaced variable...OK
19081863Test 3/4 field parent pointer...OK
19091864Test 4/4 linked list...OK</code></pre>
1910 <p>See also:</p>
1911 <ul>
1912 <li><a href="#comptime">comptime</a></li>
1913 <li><a href="#builtin-fieldParentPtr">@fieldParentPtr</a></li>
1914 </ul>
1865 {#see_also|comptime|@fieldParentPtr#}
19151866 {#header_close#}
19161867 {#header_open|enum#}
19171868 <pre><code class="zig">const assert = @import("std").debug.assert;
......@@ -2024,12 +1975,7 @@ Test 5/8 @TagType...OK
20241975Test 6/8 @memberCount...OK
20251976Test 7/8 @memberName...OK
20261977Test 8/8 @tagName...OK</code></pre>
2027 <p>See also:</p>
2028 <ul>
2029 <li><a href="#builtin-memberName">@memberName</a></li>
2030 <li><a href="#builtin-memberCount">@memberCount</a></li>
2031 <li><a href="#builtin-tagName">@tagName</a></li>
2032 </ul>
1978 {#see_also|@memberName|@memberCount|@tagName#}
20331979 {#header_close#}
20341980 {#header_open|union#}
20351981 <pre><code class="zig">const assert = @import("std").debug.assert;
......@@ -2235,13 +2181,7 @@ test "switch inside function" {
22352181Test 1/2 switch simple...OK
22362182Test 2/2 switch enum...OK
22372183Test 3/3 switch inside function...OK</code></pre>
2238 <p>See also:</p>
2239 <ul>
2240 <li><a href="#comptime">comptime</a></li>
2241 <li><a href="#enum">enum</a></li>
2242 <li><a href="#builtin-compileError">@compileError</a></li>
2243 <li><a href="#compile-variables">Compile Variables</a></li>
2244 </ul>
2184 {#see_also|comptime|enum|@compileError|Compile Variables#}
22452185 {#header_close#}
22462186 {#header_open|while#}
22472187 <pre><code class="zig">const assert = @import("std").debug.assert;
......@@ -2404,14 +2344,7 @@ Test 5/8 while loop continuation expression, more complicated...OK
24042344Test 6/8 while else...OK
24052345Test 7/8 while null capture...OK
24062346Test 8/8 inline while loop...OK</code></pre>
2407 <p>See also:</p>
2408 <ul>
2409 <li><a href="#if">if</a></li>
2410 <li><a href="#nullables">Nullables</a></li>
2411 <li><a href="#errors">Errors</a></li>
2412 <li><a href="#comptime">comptime</a></li>
2413 <li><a href="#unreachable">unreachable</a></li>
2414 </ul>
2347 {#see_also|if|Nullables|Errors|comptime|unreachable#}
24152348 {#header_close#}
24162349 {#header_open|for#}
24172350 <pre><code class="zig">const assert = @import("std").debug.assert;
......@@ -2507,13 +2440,7 @@ Test 1/4 for basics...OK
25072440Test 2/4 for reference...OK
25082441Test 3/4 for else...OK
25092442Test 4/4 inline for loop...OK</code></pre>
2510 <p>See also:</p>
2511 <ul>
2512 <li><a href="#while">while</a></li>
2513 <li><a href="#comptime">comptime</a></li>
2514 <li><a href="#arrays">Arrays</a></li>
2515 <li><a href="#slices">Slices</a></li>
2516 </ul>
2443 {#see_also|while|comptime|Arrays|Slices#}
25172444 {#header_close#}
25182445 {#header_open|if#}
25192446 <pre><code class="zig">// If expressions have three uses, corresponding to the three types:
......@@ -2628,29 +2555,9 @@ test "if error union" {
26282555Test 1/3 if boolean...OK
26292556Test 2/3 if nullable...OK
26302557Test 3/3 if error union...OK</code></pre>
2631 <p>See also:</p>
2632 <ul>
2633 <li><a href="#nullables">Nullables</a></li>
2634 <li><a href="#errors">Errors</a></li>
2635 </ul>
2558 {#see_also|Nullables|Errors#}
26362559 {#header_close#}
2637 {#header_open|goto#}
2638 <pre><code class="zig">const assert = @import("std").debug.assert;
2639
2640test "goto" {
2641 var value = false;
2642 goto label;
2643 value = true;
2644
2645label:
2646 assert(value == false);
2647}
2648</code></pre>
2649 <pre><code class="sh">$ zig test goto.zig
2650Test 1/1 goto...OK
2651</code></pre>
2652<p>Note that there are <a href="https://github.com/zig-lang/zig/issues/346">plans to remove goto</a></p>
2653{{deheader_open:fer}}
2560 {#header_open|defer#}
26542561 <pre><code class="zig">const assert = @import("std").debug.assert;
26552562const printf = @import("std").io.stdout.printf;
26562563
......@@ -2736,10 +2643,7 @@ encountered an error!
27362643end of function
27372644OK
27382645</code></pre>
2739 <p>See also:</p>
2740 <ul>
2741 <li><a href="#errors">Errors</a></li>
2742 </ul>
2646 {#see_also|Errors#}
27432647 {#header_close#}
27442648 {#header_open|unreachable#}
27452649 <p>
......@@ -2811,12 +2715,7 @@ comptime {
28112715test.zig:9:12: error: unreachable code
28122716 assert(@typeOf(unreachable) == noreturn);
28132717 ^</code></pre>
2814 <p>See also:</p>
2815 <ul>
2816 <li><a href="#zig-test">Zig Test</a></li>
2817 <li><a href="#build-mode">Build Mode</a></li>
2818 <li><a href="#comptime">comptime</a></li>
2819 </ul>
2718 {#see_also|Zig Test|Build Mode|comptime#}
28202719 {#header_close#}
28212720 {#header_close#}
28222721 {#header_open|noreturn#}
......@@ -3142,12 +3041,7 @@ pub fn parseU64(buf: []const u8, radix: u8) -&gt; %u64 {
31423041 in other languages.
31433042 </li>
31443043 </ul>
3145 <p>See also:</p>
3146 <ul>
3147 <li><a href="#defer">defer</a></li>
3148 <li><a href="#if">if</a></li>
3149 <li><a href="#switch">switch</a></li>
3150 </ul>
3044 {#see_also|defer|if|switch#}
31513045 {#header_close#}
31523046 {#header_open|Nullables#}
31533047 <p>
......@@ -3976,11 +3870,7 @@ comptime {
39763870 The result is a target-specific compile time constant. It is guaranteed to be
39773871 less than or equal to <a href="#builtin-sizeOf">@sizeOf(T)</a>.
39783872 </p>
3979 <p>See also:</p>
3980 <ul>
3981 <li><a href="#alignment">Alignment</a></li>
3982 </ul>
3983
3873 {#see_also|Alignment#}
39843874 {#header_close#}
39853875 {#header_open|@cDefine#}
39863876 <pre><code class="zig">@cDefine(comptime name: []u8, value)</code></pre>
......@@ -3999,14 +3889,7 @@ comptime {
39993889 Use the void value, like this:
40003890 </p>
40013891 <pre><code class="zig">@cDefine("_GNU_SOURCE", {})</code></pre>
4002 <p>See also:</p>
4003 <ul>
4004 <li><a href="#c-import">Import from C Header File</a></li>
4005 <li><a href="#builtin-cInclude">@cInclude</a></li>
4006 <li><a href="#builtin-cImport">@cImport</a></li>
4007 <li><a href="#builtin-cUndef">@cUndef</a></li>
4008 <li><a href="#void">void</a></li>
4009 </ul>
3892 {#see_also|Import from C Header File|@cInclude|@cImport|@cUndef|void#}
40103893 {#header_close#}
40113894 {#header_open|@cImport#}
40123895 <pre><code class="zig">@cImport(expression) -&gt; (namespace)</code></pre>
......@@ -4019,13 +3902,7 @@ comptime {
40193902 <code>@cInclude</code>, <code>@cDefine</code>, and <code>@cUndef</code> work
40203903 within this expression, appending to a temporary buffer which is then parsed as C code.
40213904 </p>
4022 <p>See also:</p>
4023 <ul>
4024 <li><a href="#c-import">Import from C Header File</a></li>
4025 <li><a href="#builtin-cInclude">@cInclude</a></li>
4026 <li><a href="#builtin-cDefine">@cDefine</a></li>
4027 <li><a href="#builtin-cUndef">@cUndef</a></li>
4028 </ul>
3905 {#see_also|Import from C Header File|@cInclude|@cDefine|@cUndef#}
40293906 {#header_close#}
40303907 {#header_open|@cInclude#}
40313908 <pre><code class="zig">@cInclude(comptime path: []u8)</code></pre>
......@@ -4036,13 +3913,7 @@ comptime {
40363913 This appends <code>#include <$path>\n</code> to the <code>c_import</code>
40373914 temporary buffer.
40383915 </p>
4039 <p>See also:</p>
4040 <ul>
4041 <li><a href="#c-import">Import from C Header File</a></li>
4042 <li><a href="#builtin-cImport">@cImport</a></li>
4043 <li><a href="#builtin-cDefine">@cDefine</a></li>
4044 <li><a href="#builtin-cUndef">@cUndef</a></li>
4045 </ul>
3916 {#see_also|Import from C Header File|@cImport|@cDefine|@cUndef#}
40463917 {#header_close#}
40473918 {#header_open|@cUndef#}
40483919 <pre><code class="zig">@cUndef(comptime name: []u8)</code></pre>
......@@ -4053,13 +3924,7 @@ comptime {
40533924 This appends <code>#undef $name</code> to the <code>@cImport</code>
40543925 temporary buffer.
40553926 </p>
4056 <p>See also:</p>
4057 <ul>
4058 <li><a href="#c-import">Import from C Header File</a></li>
4059 <li><a href="#builtin-cImport">@cImport</a></li>
4060 <li><a href="#builtin-cDefine">@cDefine</a></li>
4061 <li><a href="#builtin-cInclude">@cInclude</a></li>
4062 </ul>
3927 {#see_also|Import from C Header File|@cImport|@cDefine|@cInclude#}
40633928 {#header_close#}
40643929 {#header_open|@canImplicitCast#}
40653930 <pre><code class="zig">@canImplicitCast(comptime T: type, value) -&gt; bool</code></pre>
......@@ -4091,11 +3956,7 @@ comptime {
40913956 <code>AtomicOrder</code> can be found with <code>@import("builtin").AtomicOrder</code>.
40923957 </p>
40933958 <p><code>@typeOf(ptr).alignment</code> must be <code>&gt;= @sizeOf(T).</code></p>
4094 <p>See also:</p>
4095 <ul>
4096 <li><a href="#compile-variables">Compile Variables</a></li>
4097 </ul>
4098
3959 {#see_also|Compile Variables#}
40993960 {#header_close#}
41003961 {#header_open|@compileError#}
41013962 <pre><code class="zig">@compileError(comptime msg: []u8)</code></pre>
......@@ -4183,12 +4044,8 @@ test.zig:6:2: error: found compile log statement
41834044 <li><code>@divExact(6, 3) == 2</code></li>
41844045 <li><code>@divExact(a, b) * b == a</code></li>
41854046 </ul>
4186 <p>See also:</p>
4187 <ul>
4188 <li><a href="#builtin-divTrunc">@divTrunc</a></li>
4189 <li><a href="#builtin-divFloor">@divFloor</a></li>
4190 <li><code>@import("std").math.divExact</code></li>
4191 </ul>
4047 <p>For a function that returns a possible error code, use <code>@import("std").math.divExact</code>.</p>
4048 {#see_also|@divTrunc|@divFloor#}
41924049 {#header_close#}
41934050 {#header_open|@divFloor#}
41944051 <pre><code class="zig">@divFloor(numerator: T, denominator: T) -&gt; T</code></pre>
......@@ -4201,12 +4058,8 @@ test.zig:6:2: error: found compile log statement
42014058 <li><code>@divFloor(-5, 3) == -2</code></li>
42024059 <li><code>@divFloor(a, b) + @mod(a, b) == a</code></li>
42034060 </ul>
4204 <p>See also:</p>
4205 <ul>
4206 <li><a href="#builtin-divTrunc">@divTrunc</a></li>
4207 <li><a href="#builtin-divExact">@divExact</a></li>
4208 <li><code>@import("std").math.divFloor</code></li>
4209 </ul>
4061 <p>For a function that returns a possible error code, use <code>@import("std").math.divFloor</code>.</p>
4062 {#see_also|@divTrunc|@divExact#}
42104063 {#header_close#}
42114064 {#header_open|@divTrunc#}
42124065 <pre><code class="zig">@divTrunc(numerator: T, denominator: T) -&gt; T</code></pre>
......@@ -4219,12 +4072,8 @@ test.zig:6:2: error: found compile log statement
42194072 <li><code>@divTrunc(-5, 3) == -1</code></li>
42204073 <li><code>@divTrunc(a, b) + @rem(a, b) == a</code></li>
42214074 </ul>
4222 <p>See also:</p>
4223 <ul>
4224 <li><a href="#builtin-divFloor">@divFloor</a></li>
4225 <li><a href="#builtin-divExact">@divExact</a></li>
4226 <li><code>@import("std").math.divTrunc</code></li>
4227 </ul>
4075 <p>For a function that returns a possible error code, use <code>@import("std").math.divTrunc</code>.</p>
4076 {#see_also|@divFloor|@divExact#}
42284077 {#header_close#}
42294078 {#header_open|@embedFile#}
42304079 <pre><code class="zig">@embedFile(comptime path: []const u8) -&gt; [X]u8</code></pre>
......@@ -4236,10 +4085,7 @@ test.zig:6:2: error: found compile log statement
42364085 <p>
42374086 <code>path</code> is absolute or relative to the current file, just like <code>@import</code>.
42384087 </p>
4239 <p>See also:</p>
4240 <ul>
4241 <li><a href="#builtin-import">@import</a></li>
4242 </ul>
4088 {#see_also|@import#}
42434089 {#header_close#}
42444090 {#header_open|@export#}
42454091 <pre><code class="zig">@export(comptime name: []const u8, target: var, linkage: builtin.GlobalLinkage) -&gt; []const u8</code></pre>
......@@ -4294,10 +4140,7 @@ test.zig:6:2: error: found compile log statement
42944140 <p>
42954141 <code>AtomicOrder</code> can be found with <code>@import("builtin").AtomicOrder</code>.
42964142 </p>
4297 <p>See also:</p>
4298 <ul>
4299 <li><a href="#compile-variables">Compile Variables</a></li>
4300 </ul>
4143 {#see_also|Compile Variables#}
43014144 {#header_close#}
43024145 {#header_open|@fieldParentPtr#}
43034146 <pre><code class="zig">@fieldParentPtr(comptime ParentType: type, comptime field_name: []const u8,
......@@ -4338,11 +4181,7 @@ test.zig:6:2: error: found compile log statement
43384181 <li><code>@import("std")</code> - Zig Standard Library</li>
43394182 <li><code>@import("builtin")</code> - Compiler-provided types and variables</li>
43404183 </ul>
4341 <p>See also:</p>
4342 <ul>
4343 <li><a href="#compile-variables">Compile Variables</a></li>
4344 <li><a href="#builtin-embedFile">@embedFile</a></li>
4345 </ul>
4184 {#see_also|Compile Variables|@embedFile#}
43464185 {#header_close#}
43474186 {#header_open|@inlineCall#}
43484187 <pre><code class="zig">@inlineCall(function: X, args: ...) -&gt; Y</code></pre>
......@@ -4359,10 +4198,7 @@ fn add(a: i32, b: i32) -&gt; i32 { a + b }</code></pre>
43594198 Unlike a normal function call, however, <code>@inlineCall</code> guarantees that the call
43604199 will be inlined. If the call cannot be inlined, a compile error is emitted.
43614200 </p>
4362 <p>See also:</p>
4363 <ul>
4364 <li><a href="#builtin-noInlineCall">@noInlineCall</a></li>
4365 </ul>
4201 {#see_also|@noInlineCall#}
43664202 {#header_close#}
43674203 {#header_open|@intToPtr#}
43684204 <pre><code class="zig">@intToPtr(comptime DestType: type, int: usize) -&gt; DestType</code></pre>
......@@ -4454,11 +4290,8 @@ mem.set(u8, dest, c);</code></pre>
44544290 <li><code>@mod(-5, 3) == 1</code></li>
44554291 <li><code>@divFloor(a, b) + @mod(a, b) == a</code></li>
44564292 </ul>
4457 <p>See also:</p>
4458 <ul>
4459 <li><a href="#builtin-rem">@rem</a></li>
4460 <li><code>@import("std").math.mod</code></li>
4461 </ul>
4293 <p>For a function that returns an error code, see <code>@import("std").math.mod</code>.</p>
4294 {#see_also|@rem#}
44624295 {#header_close#}
44634296 {#header_open|@mulWithOverflow#}
44644297 <pre><code class="zig">@mulWithOverflow(comptime T: type, a: T, b: T, result: &amp;T) -&gt; bool</code></pre>
......@@ -4483,10 +4316,7 @@ fn add(a: i32, b: i32) -&gt; i32 { a + b }</code></pre>
44834316 Unlike a normal function call, however, <code>@noInlineCall</code> guarantees that the call
44844317 will not be inlined. If the call must be inlined, a compile error is emitted.
44854318 </p>
4486 <p>See also:</p>
4487 <ul>
4488 <li><a href="#builtin-inlineCall">@inlineCall</a></li>
4489 </ul>
4319 {#see_also|@inlineCall#}
44904320 {#header_close#}
44914321 {#header_open|@offsetOf#}
44924322 <pre><code class="zig">@offsetOf(comptime T: type, comptime field_name: [] const u8) -&gt; (number literal)</code></pre>
......@@ -4529,11 +4359,7 @@ test.zig:5:9: error: expected type '&amp;Derp', found '&amp;Wat'
45294359 <li>From library code, calling the programmer's panic function if they exposed one in the root source file.</li>
45304360 <li>When mixing C and Zig code, calling the canonical panic implementation across multiple .o files.</li>
45314361 </ul>
4532 <p>See also:</p>
4533 <ul>
4534 <li><a href="#root-source-file">Root Source File</a></li>
4535 </ul>
4536
4362 {#see_also|Root Source File#}
45374363 {#header_close#}
45384364 {#header_open|@ptrCast#}
45394365 <pre><code class="zig">@ptrCast(comptime DestType: type, value: var) -&gt; DestType</code></pre>
......@@ -4565,11 +4391,8 @@ test.zig:5:9: error: expected type '&amp;Derp', found '&amp;Wat'
45654391 <li><code>@rem(-5, 3) == -2</code></li>
45664392 <li><code>@divTrunc(a, b) + @rem(a, b) == a</code></li>
45674393 </ul>
4568 <p>See also:</p>
4569 <ul>
4570 <li><a href="#builtin-mod">@mod</a></li>
4571 <li><code>@import("std").math.rem</code></li>
4572 </ul>
4394 <p>For a function that returns an error code, see <code>@import("std").math.rem</code>.</p>
4395 {#see_also|@mod#}
45734396 {#header_close#}
45744397 {#header_open|@returnAddress#}
45754398 <pre><code class="zig">@returnAddress()</code></pre>
......@@ -4584,7 +4407,6 @@ test.zig:5:9: error: expected type '&amp;Derp', found '&amp;Wat'
45844407 <p>
45854408 This function is only valid within function scope.
45864409 </p>
4587
45884410 {#header_close#}
45894411 {#header_open|@setDebugSafety#}
45904412 <pre><code class="zig">@setDebugSafety(scope, safety_on: bool)</code></pre>
......@@ -4623,11 +4445,7 @@ test.zig:5:9: error: expected type '&amp;Derp', found '&amp;Wat'
46234445 <pre><code class="sh">$ ./zig build-obj test.zig</code></pre>
46244446 <p>(no output because it worked fine)</p>
46254447
4626 <p>See also:</p>
4627 <ul>
4628 <li><a href="#comptime">comptime</a></li>
4629 </ul>
4630
4448 {#see_also|comptime#}
46314449 {#header_close#}
46324450 {#header_open|@setFloatMode#}
46334451 <pre><code class="zig">@setFloatMode(scope, mode: @import("builtin").FloatMode)</code></pre>
......@@ -4655,21 +4473,14 @@ test.zig:5:9: error: expected type '&amp;Derp', found '&amp;Wat'
46554473 <code>Strict</code> - Floating point operations follow strict IEEE compliance.
46564474 </li>
46574475 </ul>
4658 <p>See also:</p>
4659 <ul>
4660 <li><a href="#float-operations">Floating Point Operations</a></li>
4661 </ul>
4662
4476 {#see_also|Floating Point Operations#}
46634477 {#header_close#}
46644478 {#header_open|@setGlobalLinkage#}
46654479 <pre><code class="zig">@setGlobalLinkage(global_variable_name, comptime linkage: GlobalLinkage)</code></pre>
46664480 <p>
46674481 <code>GlobalLinkage</code> can be found with <code>@import("builtin").GlobalLinkage</code>.
46684482 </p>
4669 <p>See also:</p>
4670 <ul>
4671 <li><a href="#compile-variables">Compile Variables</a></li>
4672 </ul>
4483 {#see_also|Compile Variables#}
46734484 {#header_close#}
46744485 {#header_open|@setGlobalSection#}
46754486 <pre><code class="zig">@setGlobalSection(global_variable_name, comptime section_name: []const u8) -&gt; bool</code></pre>
......@@ -4687,11 +4498,7 @@ test.zig:5:9: error: expected type '&amp;Derp', found '&amp;Wat'
46874498 The type of <code>shift_amt</code> is an unsigned integer with <code>log2(T.bit_count)</code> bits.
46884499 This is because <code>shift_amt &gt;= T.bit_count</code> is undefined behavior.
46894500 </p>
4690 <p>See also:</p>
4691 <ul>
4692 <li><a href="#builtin-shrExact">@shrExact</a></li>
4693 <li><a href="#builtin-shlWithOverflow">@shlWithOverflow</a></li>
4694 </ul>
4501 {#see_also|@shrExact|@shlWithOverflow#}
46954502 {#header_close#}
46964503 {#header_open|@shlWithOverflow#}
46974504 <pre><code class="zig">@shlWithOverflow(comptime T: type, a: T, shift_amt: Log2T, result: &amp;T) -&gt; bool</code></pre>
......@@ -4704,11 +4511,7 @@ test.zig:5:9: error: expected type '&amp;Derp', found '&amp;Wat'
47044511 The type of <code>shift_amt</code> is an unsigned integer with <code>log2(T.bit_count)</code> bits.
47054512 This is because <code>shift_amt &gt;= T.bit_count</code> is undefined behavior.
47064513 </p>
4707 <p>See also:</p>
4708 <ul>
4709 <li><a href="#builtin-shlExact">@shlExact</a></li>
4710 <li><a href="#builtin-shrExact">@shrExact</a></li>
4711 </ul>
4514 {#see_also|@shlExact|@shrExact#}
47124515 {#header_close#}
47134516 {#header_open|@shrExact#}
47144517 <pre><code class="zig">@shrExact(value: T, shift_amt: Log2T) -&gt; T</code></pre>
......@@ -4720,10 +4523,7 @@ test.zig:5:9: error: expected type '&amp;Derp', found '&amp;Wat'
47204523 The type of <code>shift_amt</code> is an unsigned integer with <code>log2(T.bit_count)</code> bits.
47214524 This is because <code>shift_amt &gt;= T.bit_count</code> is undefined behavior.
47224525 </p>
4723 <p>See also:</p>
4724 <ul>
4725 <li><a href="#builtin-shlExact">@shlExact</a></li>
4726 </ul>
4526 {#see_also|@shlExact|@shlWithOverflow#}
47274527 {#header_close#}
47284528 {#header_open|@sizeOf#}
47294529 <pre><code class="zig">@sizeOf(comptime T: type) -&gt; (number literal)</code></pre>
......@@ -4863,12 +4663,7 @@ pub fn build(b: &amp;Builder) {
48634663 <li>Safety checks enabled</li>
48644664 <li>Slow compilation speed</li>
48654665 </ul>
4866 <p>See also:</p>
4867 <ul>
4868 <li><a href="#compile-variables">Compile Variables</a></li>
4869 <li><a href="#zig-build-system">Zig Build System</a></li>
4870 <li><a href="#undefined-behavior">Undefined Behavior</a></li>
4871 </ul>
4666 {#see_also|Compile Variables|Zig Build System|Undefined Behavior#}
48724667 {#header_close#}
48734668 {#header_close#}
48744669 {#header_open|Undefined Behavior#}
......@@ -5234,10 +5029,7 @@ comptime {
52345029 <p>TODO: importance of checking for allocation failure</p>
52355030 <p>TODO: mention overcommit and the OOM Killer</p>
52365031 <p>TODO: mention recursion</p>
5237 <p>See also:</p>
5238 <ul>
5239 <li><a href="#pointers">Pointers</a></li>
5240 </ul>
5032 {#see_also|Pointers#}
52415033
52425034 {#header_close#}
52435035 {#header_open|Compile Variables#}
......@@ -5406,10 +5198,7 @@ pub const object_format = ObjectFormat.elf;
54065198pub const mode = Mode.ReleaseFast;
54075199pub const link_libs = [][]const u8 {
54085200};</code></pre>
5409 <p>See also:</p>
5410 <ul>
5411 <li><a href="#build-mode">Build Mode</a></li>
5412 </ul>
5201 {#see_also|Build Mode#}
54135202 {#header_close#}
54145203 {#header_open|Root Source File#}
54155204 <p>TODO: explain how root source file finds other files</p>
......@@ -5456,10 +5245,7 @@ pub const link_libs = [][]const u8 {
54565245 <li><code>c_longdouble</code></li>
54575246 <li><code>c_void</code></li>
54585247 </ul>
5459 <p>See also:</p>
5460 <ul>
5461 <li><a href="#primitive-types">Primitive Types</a></li>
5462 </ul>
5248 {#see_also|Primitive Types#}
54635249 {#header_close#}
54645250 {#header_open|C String Literals#}
54655251 <pre><code class="zig">extern fn puts(&amp;const u8);
......@@ -5472,10 +5258,7 @@ pub fn main() -&gt; %void {
54725258 c\\multiline C string literal
54735259 );
54745260}</code></pre>
5475 <p>See also:</p>
5476 <ul>
5477 <li><a href="#string-literals">String Literals</a></li>
5478 </ul>
5261 {#see_also|String Literals#}
54795262 {#header_close#}
54805263 {#header_open|Import from C Header File#}
54815264 <p>
......@@ -5504,14 +5287,7 @@ const c = @cImport({
55045287 }
55055288 @cInclude("soundio.h");
55065289});</code></pre>
5507 <p>See also:</p>
5508 <ul>
5509 <li><a href="#builtin-cImport">@cImport</a></li>
5510 <li><a href="#builtin-cInclude">@cInclude</a></li>
5511 <li><a href="#builtin-cDefine">@cDefine</a></li>
5512 <li><a href="#builtin-cUndef">@cUndef</a></li>
5513 <li><a href="#builtin-import">@import</a></li>
5514 </ul>
5290 {#see_also|@cImport|@cInclude|@cDefine|@cUndef|@import#}
55155291 {#header_close#}
55165292 {#header_open|Mixing Object Files#}
55175293 <p>
......@@ -5571,11 +5347,7 @@ pub fn build(b: &amp;Builder) {
55715347 <pre><code class="sh">$ zig build
55725348$ ./test
55735349all your base are belong to us</code></pre>
5574 <p>See also:</p>
5575 <ul>
5576 <li><a href="#targets">Targets</a></li>
5577 <li><a href="#zig-build-system">Zig Build System</a></li>
5578 </ul>
5350 {#see_also|Targets|Zig Build System#}
55795351 {#header_close#}
55805352 {#header_close#}
55815353 {#header_open|Targets#}
std/hash_map.zig+4
......@@ -109,6 +109,10 @@ pub fn HashMap(comptime K: type, comptime V: type,
109109 return hm.internalGet(key);
110110 }
111111
112 pub fn contains(hm: &Self, key: K) -> bool {
113 return hm.get(key) != null;
114 }
115
112116 pub fn remove(hm: &Self, key: K) -> ?&Entry {
113117 hm.incrementModificationCount();
114118 const start_index = hm.keyToIndex(key);