From aaa30fc5a6dfc8158161fc87978c2e73da8447d3 Mon Sep 17 00:00:00 2001 From: Nigel Tao Date: Thu, 19 Dec 2019 00:24:39 +1100 Subject: [PATCH] Add doc/note/iterate-loops.md --- doc/note/iterate-loops.md | 40 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 doc/note/iterate-loops.md diff --git a/doc/note/iterate-loops.md b/doc/note/iterate-loops.md new file mode 100644 index 00000000..1b62a97a --- /dev/null +++ b/doc/note/iterate-loops.md @@ -0,0 +1,40 @@ +# Iterate Loops + +Iterate loops are syntactic sugar for partitioning a variable sized input slice +into fixed sized chunk slices (with possible smaller-sized remainders). +Individual chunks' fixed sizes are typically easier for +[bounds-checking](/doc/note/bounds-checking.md). + +For example, with primarily 8 length chunks, a 26 length input can be processed +in five chunks (of length 8, 8, 8, 1 and 1). Accessing `chunk[7]` is trivially +in-bounds if `chunk.length()` is exactly 8. + +``` +var chunk : slice base.u8 +var input : slice base.u8 + +etc + +iterate (chunk = input)(length: 8, unroll: 2) { + // Within this block, chunk.length() is always 8. For a 26 length input, + // this block will run three times: + // - with "chunk = input[0 .. 8]", + // - with "chunk = input[8 .. 16]", + // - with "chunk = input[16 .. 24]". + etc + +} else (length: 1, unroll: 1) { + // Each block of the iterate loop only runs after all previous blocks (in + // this case the only previous block) are exhausted: the remaining input is + // shorter than each of their given lengths. + // + // Within this block, chunk.length() is always 1. Continuing the previous + // example, this block will run two times: + // - with "chunk = input[24 .. 25]", + // - with "chunk = input[25 .. 26]". + etc +} +``` + +Chunk processing (i.e. loop bodies) can also be unrolled, which affects +performance but not semantics.