mirror of
https://github.com/ddidderr/wuffs.git
synced 2026-11-20 00:47:28 +01:00
Fix some typos in the documentation.
And some minor clean-ups. There should be no semantic changes to the documentation in this patch.
This commit is contained in:
1 parent
6f7e9dfa26
commit
e9fdc38300
19 files changed
+39
-41
No files matched your search
@@ -10,7 +10,7 @@ Similarly, an expression like `x[i]` is invalid unless there is a compile-time
|
||||
proof that `i` is in-bounds: that `((0 <= i) and (i < x.length()))`. Proofs can
|
||||
involve natural bounds (e.g. if `i` has type `base.u8` then `(0 <= i)` is
|
||||
trivially true since a `base.u8` is unsigned),
|
||||
[refinements](/doc/glossary.md#refinement-type) (e.g. if `i`has type
|
||||
[refinements](/doc/glossary.md#refinement-type) (e.g. if `i` has type
|
||||
`base.u32[..= 100]` then 100 is an inclusive upper bound for `i`),
|
||||
[facts](/doc/note/facts.md) (e.g. an explicit prior check `if i < x.length()`)
|
||||
and [interval arithmetic](/doc/note/interval-arithmetic.md) (e.g. for an
|
||||
|
||||
+1
-1
@@ -11,7 +11,7 @@ Impure functions are marked with a `!` at their definition and at call sites.
|
||||
Coroutines are similarly marked, with a `?`. Pure functions have no mark.
|
||||
|
||||
For those used to C/C++ syntax, in Wuffs, the unary not operator is spelled
|
||||
`not` instead of `!`, and Wuffs has no ternary operator like C/C++'s `?`.
|
||||
`not` instead of `!`, and Wuffs has no ternary operator like C/C++'s `?:`.
|
||||
|
||||
Sub-expressions in Wuffs must be pure. Only the outermost function call can
|
||||
have a `!` or `?` mark. You can't write:
|
||||
|
||||
+4
-4
@@ -105,7 +105,7 @@ line of code:
|
||||
arms (e.g. those that end with a `break`, `continue` or `return` statement)
|
||||
are not considered during reconciliation.
|
||||
- The start of a while loop can come from not just its preceding line of code,
|
||||
but also from any explicit `continue`'s inside that loop, and the implicit
|
||||
but also from any explicit `continue`s inside that loop, and the implicit
|
||||
`continue` at the closing `}` curly brace.
|
||||
- Similarly, the line of code immediately after the entire while loop can come
|
||||
from an explicit `break` or if the while condition fails.
|
||||
@@ -138,9 +138,9 @@ while n_bits < n_extra_bits,
|
||||
The `pre`, `post` and `inv` keywords introduce loop pre-conditions,
|
||||
post-conditions and invariants (things that are both). The snippet above means
|
||||
that the Wuffs compiler has to verify all three conditions at every place this
|
||||
loop exits: at the implicit `break` if the `n_Bits < n_extra_bits` evaluates
|
||||
false (which in this case trivially proves the third condition), but also at
|
||||
every explicit `break` for that loop within its body.
|
||||
loop exits: at the implicit `break` if the expression `n_bits < n_extra_bits`
|
||||
evaluates to false (which in this case trivially proves the third condition),
|
||||
but also at every explicit `break` for that loop within its body.
|
||||
|
||||
Similarly, it has to verify only the first two conditions at every place this
|
||||
loop repeats (at its initial execution, at every explicit `continue` and at the
|
||||
|
||||
@@ -5,7 +5,7 @@ Outside of the Wuffs base package, every Wuffs struct has an implicit
|
||||
Wuffs' C language form, the `initialize` function for the `foo` package's `bar`
|
||||
struct is called `wuffs_foo__bar__initialize`. The function takes four
|
||||
arguments (or, in C++, the `initialize` method takes three arguments, with the
|
||||
implicit `this` pointer argument);
|
||||
implicit `this` pointer argument):
|
||||
|
||||
- A pointer to the `wuffs_foo__bar` object: the `this` pointer.
|
||||
- The size (in bytes) of that object. Conceptually, this is
|
||||
|
||||
@@ -48,11 +48,10 @@ etcetera
|
||||
i = i + 1
|
||||
```
|
||||
|
||||
fails the compile-time bounds / overflow checker, because the assignment's
|
||||
RHS's (Right Hand Side's) range, `[1 ..= 11]`, is not wholly contained by the
|
||||
LHS (Left Hand Side) variable's range: `i` has range `[0 ..= 10]`. If `i` had
|
||||
an unrefined type, such as `base.u32`, then this is essentially an overflow
|
||||
check.
|
||||
fails the compile-time bounds/overflow checker, because the assignment's RHS's
|
||||
(Right Hand Side's) range, `[1 ..= 11]`, is not wholly contained by the LHS
|
||||
(Left Hand Side) variable's range: `i` has range `[0 ..= 10]`. If `i` had an
|
||||
unrefined type, such as `base.u32`, then this is essentially an overflow check.
|
||||
|
||||
|
||||
## Masking Array Indexes
|
||||
|
||||
@@ -8,7 +8,7 @@ prove that you can't misuse a capability, even when given malicious input.
|
||||
Instead, the code that calls into Wuffs libraries is responsible for
|
||||
interfacing with e.g. the file system or the network system. An `io_buffer` is
|
||||
the mechanism for transferring data into and out of Wuffs libraries. For
|
||||
example, when decompressing gzip, there are two `io_buffer`'s: the caller fills
|
||||
example, when decompressing gzip, there are two `io_buffer`s: the caller fills
|
||||
a source buffer with e.g. the compressed file's contents and the callee (the
|
||||
Wuffs library) reads compressed bytes from that source buffer and writes
|
||||
decompressed bytes to a destination buffer.
|
||||
@@ -35,19 +35,18 @@ Reading from an `io_buffer`, e.g. copying from a buffer to a file, increments
|
||||
An invariant condition is that `((0 <= ri) and (ri <= wi) and (wi <= len))`.
|
||||
|
||||
Having separate read and write indexes simplifies connecting a sequence of
|
||||
filters or processors with `io_buffer`'s, similar to connecting Unix processes
|
||||
filters or processors with `io_buffer`s, similar to connecting Unix processes
|
||||
with pipes. Each filter reads from the previous buffer and writes to the next
|
||||
buffer. Each buffer is written to by the previous filter and is read from by
|
||||
the next filter. There's no need to flip a buffer between reading and writing
|
||||
modes. Nonetheless, `io_buffer`'s are generally not thread-safe.
|
||||
modes. Nonetheless, `io_buffer`s are generally not thread-safe.
|
||||
|
||||
Continuing the "decompressing gzip" example, the application would write to the
|
||||
source buffer by copying from e.g. `/dev/stdin`. The Wuffs library would read
|
||||
Continuing the "decompressing gzip" example, the application would write to
|
||||
the source buffer by copying from e.g. `stdin`. The Wuffs library would read
|
||||
from the source buffer and write to the destination buffer. The application
|
||||
would read from the destination buffer by copying to e.g. `stdout`. Buffer
|
||||
space can be re-used, via compaction (see below), so that neither the source
|
||||
(`/dev/stdin`) or destination (`/dev/stdout`) data needs to be entirely in
|
||||
memory at any point.
|
||||
or destination data needs to be entirely in memory at any point.
|
||||
|
||||
For example, an `io_buffer` of length 8 could have 4 bytes available to read
|
||||
and 1 byte available to write. If 1 byte was written, there would then be 5
|
||||
@@ -100,9 +99,9 @@ at the time of the call. When considering a function as a 'black box', the two
|
||||
indexes can only travel forward, and it is up to the application code (not
|
||||
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
|
||||
Even though `ri` cannot 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]`)
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Iterate Loops
|
||||
|
||||
Iterate loops are syntactic sugar for partitioning a variable sized input slice
|
||||
into fixed sized chunk slices (with possible smaller-sized remainders).
|
||||
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).
|
||||
|
||||
|
||||
@@ -118,6 +118,6 @@ Guide](https://afrantzis.github.io/pixel-format-guide/).
|
||||
## API Stability
|
||||
|
||||
The `wuffs_base__pixel_format` bit packing is documented for explanation and to
|
||||
assist in debugging (e.g. `printf`'ing the bits in `%x` format). However, do
|
||||
assist in debugging (e.g. `printf`ing the bits in `%x` format). However, do
|
||||
not manipulate its bits directly; they are private implementation details. Use
|
||||
functions such as `wuffs_base__pixel_format__num_planes` instead.
|
||||
@@ -124,6 +124,6 @@ Cb, Cr) and a `denominator_y` of 1, 1 and 1. The `uint32_t` encoding is
|
||||
## API Stability
|
||||
|
||||
The `wuffs_base__pixel_subsampling` bit packing is documented for explanation
|
||||
and to assist in debugging (e.g. `printf`'ing the bits in `%x` format).
|
||||
and to assist in debugging (e.g. `printf`ing the bits in `%x` format).
|
||||
However, do not manipulate its bits directly; they are private implementation
|
||||
details. Use functions such as `wuffs_base__pixel_subsampling__bias_x` instead.
|
||||
+1
-1
@@ -15,7 +15,7 @@ entire image, and different implementations choose a different default color
|
||||
for the outside pixels: opaque black, transparent black, or something else.
|
||||
|
||||
Wuffs, out of the box, makes particular choices (typically mimicking the de
|
||||
facto canonical implementation), but enabling various quirks result in
|
||||
facto canonical implementation), but enabling various quirks results in
|
||||
different choices. In particular, quirks are useful in regression testing that
|
||||
Wuffs and another implementation produce the same output for the same input,
|
||||
even for malformed input.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Ranges and Rects
|
||||
|
||||
Ranges are finite numerical intervals, e.g. "all integers `i` such that `(m <=
|
||||
i)` and `(i < n)`. The high end bound is sometimes exclusive, `(i < n)`, and
|
||||
i)` and `(i < n)`". The high end bound is sometimes exclusive, `(i < n)`, and
|
||||
sometimes inclusive, `(i <= n)`.
|
||||
|
||||
In Wuffs syntax, similar to Rust syntax, the exclusive range is `m .. n` and
|
||||
|
||||
@@ -17,8 +17,8 @@ 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,
|
||||
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`.
|
||||
|
||||
|
||||
@@ -69,7 +69,7 @@ receiver"` is an error and `"$short read"` is a suspension:
|
||||
|
||||
In terms of C implementation, a status value is just its string message: a
|
||||
`const char *`, with `ok` being the null pointer. That C string is statically
|
||||
allocated and should never be `free`'d. Status values can be compared by the
|
||||
allocated and should never be `free`d. Status values can be compared by the
|
||||
`==` operator and not just by `strcmp`.
|
||||
|
||||
The C string's contents has the Wuffs package name inserted by the Wuffs
|
||||
|
||||
Reference in new issue
Block a user