diff --git a/doc/note/io-input-output.md b/doc/note/io-input-output.md index 0ed1a5bf..e651686c 100644 --- a/doc/note/io-input-output.md +++ b/doc/note/io-input-output.md @@ -102,21 +102,22 @@ Wuffs library) code to rewind the indexes (e.g. by compaction). Even though `ri` can not drop below its initial value, Wuffs code can still read the contents of the slice before `ri` (in sub-slice notation, -`data[0:ri]`) and it should still contain the `(pos + 0)`th, `(pos + 1)`th, +`data[0 .. ri]`) and it should still contain the `(pos + 0)`th, `(pos + 1)`th, etc. byte of the stream. -The contents of the slice after `wi` (in sub-slice notation, `data[wi:len]`) +The contents of the slice after `wi` (in sub-slice notation, `data[wi .. len]`) are undefined, and code should not rely on its values. When passing an `io_buffer` into a function, that function is free to modify anything in -`data[wi:len]`, for either value of `wi` before or after the function returns. +`data[wi .. len]`, for either value of `wi` before or after the function +returns. ## Compaction -Compacting an `io_buffer` moves any written but unread bytes (those in -`data[ri:wi]`) to the start of the buffer, and updates the metadata fields -`ri`, `wi` and `pos`. Equivalently, it moves the sliding window that is the -`io_buffer` as far forward as possible along the stream. +Compacting an `io_buffer` moves any written but unread bytes (those in `data[ri +.. wi]`) to the start of the buffer, and updates the metadata fields `ri`, `wi` +and `pos`. Equivalently, it moves the sliding window that is the `io_buffer` as +far forward as possible along the stream. This generally increases `(len - wi)`, the number of bytes available for writing, allowing for re-using the allocated buffer memory (the data slice). diff --git a/doc/note/slices-arrays-and-tables.md b/doc/note/slices-arrays-and-tables.md index 3581b992..0935ec9c 100644 --- a/doc/note/slices-arrays-and-tables.md +++ b/doc/note/slices-arrays-and-tables.md @@ -17,10 +17,10 @@ copy the elements. It has O(1) algorithmic complexity. Assigning to an array-typed variable copies the elements. It has O(length) algorithmic complexity. -Both `s[i:j]` and `a[i:j]` refer to slices, ranging from the `i`'th element -(inclusive) to the `j`'th element (exclusive). `i` can be omitted, implicitly -equalling zero. `j` can be omitted, implicitly equalling the length. For -example, `s[:5]` contains the first five elements of `s`. +Both `s[i .. j]` and `a[i .. j]` refer to slices, ranging from the `i`'th +element (inclusive) to the `j`'th element (exclusive). `i` can be omitted, +implicitly equalling zero. `j` can be omitted, implicitly equalling the length. +For example, `s[.. 5]` contains the first five elements of `s`. ## Tables @@ -51,9 +51,9 @@ even when an element occupies multiple bytes. ## Bounds Checking -An expression like `x[i:j]` is invalid unless the compiler can prove that `((0 -<= i) and (i <= j) and (j <= x.length()))`. For example, the expression `x[:]` -is always valid because the implicit `i` and `j` values are `0` and +An expression like `x[i .. j]` is invalid unless the compiler can prove that +`((0 <= i) and (i <= j) and (j <= x.length()))`. For example, the expression +`x[..]` is always valid because the implicit `i` and `j` values are `0` and `x.length()`, and a slice or array cannot have negative length. Similarly, an expression like `x[i]` is invalid unless there is a compile-time