Files
wuffs/doc/std/README.md
T
Claude f33e9f3377 std/softfloat: add bit-exact IEEE 754 binary64/binary32 arithmetic
Wuffs the Language has no floating point types, but some reference
implementations (notably the brotli encoder) make decisions with double and
float arithmetic and libm's log2. Porting them with byte-identical output
needs bit-exact floating point results.

This package implements f64 and f32 add, sub, mul, div, fma, comparisons,
min/max, integer conversions and f64<->f32 conversions on bit patterns,
with round-to-nearest-even, subnormals, infinities and NaNs, following the
structure of Berkeley SoftFloat 3. It also ports glibc 2.39's x86-64
__log2_fma log2 implementation (the variant selected on CPUs with FMA and
AVX2), following the shipped machine code's fused operations.

Verification: test/c/std/softfloat.c checks every operation against the C
compiler's native arithmetic on edge cases and random operands. The
script/manual-test-softfloat-*.c programs run 10^8 random operations per
operation group and compare log2_u64 against libm for every integer in
[1, 2^32) plus 10^7 larger values; all with zero mismatches.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011NoosQNe7DKWnqDCBeqw1p
2026-10-26 22:46:32 +00:00

89 lines
2.7 KiB
Markdown

# Standard Library
Wuffs' standard library consists of multiple packages, each implementing a
particular file format or algorithm. Those packages can be grouped into several
categories:
- [Compression Decoders](/doc/std/compression-decoders.md).
- [Hashers](/doc/std/hashers.md).
- [Image Decoders](/doc/std/image-decoders.md).
Other packages include [std/softfloat](/std/softfloat/README.md), which
implements bit-exact IEEE 754 floating point arithmetic using only integers.
The general pattern is that a package `foo` (e.g. `jpeg`, `png`) contains a
struct `bar` (e.g. `hasher`, `decoder`, etc) that implements a
package-independent interface. For example, every compression decoder struct
would have a `transform_io` method. In C, this would be invoked as
```
// Allocate and initialize the struct.
wuffs_foo__decoder* dec = etc;
// Do the work. Error checking is not shown, for brevity.
wuffs_base__status status = wuffs_foo__decoder__transform_io(dec, etc);
```
When that C library is used as C++, that last line can be shortened:
```
wuffs_base__status status = dec->transform_io(etc);
```
See also the [glossary](/doc/glossary.md), as well as the notes on:
- [Coroutines](/doc/note/coroutines.md).
- [Initialization](/doc/note/initialization.md).
- [Statuses](/doc/note/statuses.md).
## Modules and Dependencies
By default, building Wuffs' standard library builds the entire thing (provided
that you've defined the `WUFFS_IMPLEMENTATION` C macro), implementing a variety
of codecs and file formats.
Packages can be individually allow-listed, for smaller binaries and faster
compiles. Opt in by also defining `WUFFS_CONFIG__MODULES` and then also
`WUFFS_CONFIG__MODULE__ETC` for each `ETC` (and its dependencies, listed below)
to enable.
- `ADLER32: BASE`
- `BMP: BASE`
- `BZIP2: BASE`
- `CBOR: BASE`
- `CRC32: BASE`
- `CRC64: BASE`
- `DEFLATE: BASE`
- `ETC2: BASE`
- `GIF: BASE`
- `GZIP: BASE, CRC32, DEFLATE`
- `HANDSUM: BASE`
- `JPEG: BASE`
- `JSON: BASE`
- `LZIP: BASE, CRC32, LZMA`
- `LZMA: BASE`
- `LZW: BASE`
- `NETPBM: BASE`
- `NIE: BASE`
- `PNG: BASE, ADLER32, CRC32, DEFLATE, ZLIB`
- `QOI: BASE`
- `SHA256: BASE`
- `SOFTFLOAT: BASE`
- `TGA: BASE`
- `THUMBHASH: BASE`
- `VP8: BASE`
- `WBMP: BASE`
- `WEBP: BASE, VP8`
- `XXHASH32: BASE`
- `XXHASH64: BASE`
- `XZ: BASE, CRC32, CRC64, LZMA, SHA256`
- `ZLIB: BASE, ADLER32, DEFLATE`
For the [auxiliary modules](/doc/note/auxiliary-code.md):
- `AUX_CBOR: AUX_BASE, BASE, CBOR`
- `AUX_IMAGE: AUX_BASE, BASE` and whichever image-related modules (and their
dependencies) you want, e.g. `GIF`, `PNG`, etc.
- `AUX_JSON: AUX_BASE, BASE, JSON`