Saturating Math Generator Reference

tool::test_data::SaturatingMathTool generates reviewed arithmetic boundary fixtures. See Generate Saturating Math Data for the regeneration workflow.

Configuration and Options

The required [generate_saturating_math_data] section has a text setting output_directory, defaulting to test/unittest/data/saturating_math. Its checked-in configuration is tool/conf/tools/generate_saturating_math_data.elcl. --output-directory (-o) overrides the setting; --check (-c) compares without writing or creating directories. Paths must remain inside the project. Configuration, path types, and all six destination paths are validated before generation.

Independent Arithmetic

impl::SaturatingMathData caches the boundary samples, bounds, and decimal representations for the signed and unsigned 8-, 16-, 32-, and 64-bit types. It uses BigInteger for exact calculations and explicit comparisons with target bounds. Expectations do not call the saturating operations being tested.

The six tables preserve the reviewed boundary sample sets and type ordering. Division truncates toward zero; remainders retain the dividend’s sign. Zero divisors are excluded. The signed minimum divided by minus one saturates to the maximum, while its modulo result is zero.

Output and Rendering

cast.txt contains target type, source type, input, expected output, and an overflow flag. add.txt, subtract.txt, multiply.txt, divide.txt, and modulo.txt contain the operand types, operand values, expected result, and an overflow flag; each file’s schema header defines the field order. The shared test_data/table.tpl template supplies notices, schema headers, and row iteration. Native code supplies structured render values, representing numbers outside signed 64-bit range as decimal strings.

All tables are prepared before publication. ProjectFiles::updateText() retains equivalent existing files and atomically replaces each changed file. An operating-system failure during publication can leave previously published files updated. See Framework Reference for comparison and path contracts and Rendering Configuration for notice configuration.

Verification

FixtureGeneratorsTest covers boundary calculations, repeatability, options, configuration precedence, confined paths, destination conflicts, check mode, and preservation of equivalent CRLF files. Generation and integration tests use the FullRun tag; see Run the tool tests.