Files
wuffs/doc/std
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
..
2023-10-14 23:56:41 +11:00
2022-06-03 14:15:13 +10:00

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:

Other packages include std/softfloat, 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, as well as the notes on:

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:

  • 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