Crate retex_arith 

TeX-exact fixed-point arithmetic.

TeX does all dimension arithmetic with integers. A dimension is a scaled value: an i32 counting units of 2⁻¹⁶ pt (sp). Results must match TeX bit for bit, so every routine here follows the specification in TeX: The Program (§99–§108) and the e-TeX expression routines (\numexpr, \dimexpr) exactly, including the overflow rules.

Overflow is reported as Overflow. TeX sets its global arith_error flag in that case and the caller decides what to do; callers that need TeX’s exact fallback values get them from the documented error variants.

Modules

random

METAFONT’s random number generator, which LuaTeX uses for \uniformdeviate, \normaldeviate and the tex library’s randomizers.

Structs

DivResult

Quotient and remainder from x_over_n and xn_over_d.

Overflow

An arithmetic overflow, equivalent to TeX setting arith_error.

Scaled

A scaled dimension: an integer number of sp (2⁻¹⁶ pt).

Constants

INFINITY

The largest legal integer, 2³¹ − 1 (TeX’s infinity).

INF_BAD

Badness of an infinitely bad box (§108).

MAX_DIMEN

The largest legal dimension, \maxdimen = 16383.99999 pt (§421).

TWO

Two points in scaled units, used by decimal rounding (§102).

UNITY

One point in scaled units (2¹⁶ sp).

Functions

add_or_sub

e-TeX add_or_sub: computes x ± y, failing if the absolute value of the result would exceed max_answer.

badness

badness(t, s) (§108): approximately 100(t/s)³, capped at INF_BAD. t is the excess or shortfall, s the available stretch or shrink.

fract

e-TeX fract(x, n, d, max_answer): ⌊xn/d + ½⌋ computed without overflow, failing if the result exceeds max_answer. This is a transcription of the e-TeX algorithm.

half

half(x) (§100): x/2 rounded, with odd values rounded towards +∞.

mult_and_add

mult_and_add (§105): computes n*x + y, failing if the absolute value would exceed max_answer.

mult_integers

mult_integers(n, x) (§105): the result must fit in 2³¹ − 1.

nx_plus_y

nx_plus_y(n, x, y) (§105) for dimensions: the result must be at most 2³⁰ − 1 in absolute value.

print_scaled

Appends TeX’s decimal form of a scaled value to out (§103). It prints the shortest decimal that rounds back to the same scaled value, always with at least one digit after the point.

quotient

e-TeX quotient(n, d): the rounded quotient ⌊n/d + ½⌋, with the sign applied symmetrically.

round_decimals

round_decimals (§102): converts the decimal fraction .d₀d₁…dₖ₋₁ to scaled units, rounded. digits holds the digit values (0–9). TeX only looks at the first 17 digits; callers must truncate to that.

x_over_n

x_over_n (§106): divides scaled x by integer n, truncating towards zero. Division by zero is an overflow; in that case TeX returns quotient 0 and remainder x, available via x_over_n_unchecked.

x_over_n_unchecked

x_over_n without the error, returning TeX’s fallback {quotient: 0, remainder: x} when n == 0.

xn_over_d

xn_over_d (§107): computes x*n/d for 0 ≤ n, d ≤ 2¹⁶, truncating towards zero. TeX simulates 48-bit arithmetic with 15-bit pieces; this is a direct transcription of that algorithm so that overflow is detected in exactly the same cases. Division by zero is an overflow (Lua code can set a space factor of zero, for instance).