From ee525c92a4c3bafa8f30c46e0303e0bca8f81860 Mon Sep 17 00:00:00 2001
From: Andrew Kelley
Date: Tue, 19 Jun 2018 17:21:08 -0400
Subject: [PATCH] langref: organize docs for inline loops and add note about
when to use it
---
doc/langref.html.in | 57 +++++++++++++++++++++++++++++++++------------
1 file changed, 42 insertions(+), 15 deletions(-)
diff --git a/doc/langref.html.in b/doc/langref.html.in
index 1bd28f9c3..bdc33cb80 100644
--- a/doc/langref.html.in
+++ b/doc/langref.html.in
@@ -2355,11 +2355,18 @@ fn eventuallyErrorSequence() error!u32 {
break :blk numbers_left;
};
}
+ {#code_end#}
+
+ {#header_open|inline while#}
+
+ While loops can be inlined. This causes the loop to be unrolled, which
+ allows the code to do some things which only work at compile time,
+ such as use types as first class values.
+
+ {#code_begin|test#}
+const assert = @import("std").debug.assert;
test "inline while loop" {
- // While loops can be inlined. This causes the loop to be unrolled, which
- // allows the code to do some things which only work at compile time,
- // such as use types as first class values.
comptime var i = 0;
var sum: usize = 0;
inline while (i < 3) : (i += 1) {
@@ -2378,6 +2385,16 @@ fn typeNameLength(comptime T: type) usize {
return @typeName(T).len;
}
{#code_end#}
+
+ It is recommended to use inline
loops only for one of these reasons:
+
+
+ - You need the loop to execute at {#link|comptime#} for the semantics to work.
+ -
+ You have a benchmark to prove that forcibly unrolling the loop in this way is measurably faster.
+
+
+ {#header_close#}
{#see_also|if|Optionals|Errors|comptime|unreachable#}
{#header_close#}
{#header_open|for#}
@@ -2445,15 +2462,20 @@ test "for else" {
break :blk sum;
};
}
-
+ {#code_end#}
+ {#header_open|inline for#}
+
+ For loops can be inlined. This causes the loop to be unrolled, which
+ allows the code to do some things which only work at compile time,
+ such as use types as first class values.
+ The capture value and iterator value of inlined for loops are
+ compile-time known.
+
+ {#code_begin|test#}
+const assert = @import("std").debug.assert;
test "inline for loop" {
const nums = []i32{2, 4, 6};
- // For loops can be inlined. This causes the loop to be unrolled, which
- // allows the code to do some things which only work at compile time,
- // such as use types as first class values.
- // The capture value and iterator value of inlined for loops are
- // compile-time known.
var sum: usize = 0;
inline for (nums) |i| {
const T = switch (i) {
@@ -2471,6 +2493,16 @@ fn typeNameLength(comptime T: type) usize {
return @typeName(T).len;
}
{#code_end#}
+
+ It is recommended to use inline
loops only for one of these reasons:
+
+
+ - You need the loop to execute at {#link|comptime#} for the semantics to work.
+ -
+ You have a benchmark to prove that forcibly unrolling the loop in this way is measurably faster.
+
+
+ {#header_close#}
{#see_also|while|comptime|Arrays|Slices#}
{#header_close#}
{#header_open|if#}
@@ -4222,13 +4254,8 @@ pub fn main() void {
task in userland. It does so without introducing another language on top of Zig, such as
a macro language or a preprocessor language. It's Zig all the way down.
- TODO: suggestion to not use inline unless necessary
{#header_close#}
- {#header_close#}
- {#header_open|inline#}
- TODO: inline while
- TODO: inline for
- TODO: suggestion to not use inline unless necessary
+ {#see_also|inline while|inline for#}
{#header_close#}
{#header_open|Assembly#}
TODO: example of inline assembly