.Dd September 24, 2026 .Dt TUMBLER 3 .Os .Sh NAME .Nm tumbler .Nd dotted integer coordinates and Xanadu tumbler arithmetic .Sh SYNOPSIS .In tumbler.h .Ft tumbler_result_t .Fn tumbler_parse "const char *text" "tumbler_t *out" .Ft void .Fn tumbler_free "tumbler_t *t" .Ft tumbler_result_t .Fn tumbler_to_string "const tumbler_t *t" "char **out" .Ft int .Fn tumbler_compare "const tumbler_t *a" "const tumbler_t *b" .Ft tumbler_result_t .Fn tumbler_add "const tumbler_t *position" "const tumbler_t *offset" "tumbler_t *out" .Ft tumbler_result_t .Fn tumbler_subtract_strong "const tumbler_t *position" "const tumbler_t *offset" "tumbler_t *out" .Ft tumbler_result_t .Fn tumbler_subtract_weak "const tumbler_t *position" "const tumbler_t *offset" "tumbler_t *out" .Ft tumbler_result_t .Fn tumbler_subtract "const tumbler_t *a" "const tumbler_t *b" "tumbler_t *out" .Sh DESCRIPTION The .Nm module provides the small tumbler primitive used by the enfilade. A tumbler is a finite sequence of unsigned integer fields written in dotted form, such as .Ql 1.2.3 . .Pp The implementation stores each field as a .Vt uint64_t . The historical Xanadu system used arbitrary-precision Humbers; this package intentionally does not implement that representation. .Sh PARSING .Fn tumbler_parse parses one or more unsigned decimal fields separated by periods. On success it allocates the field array in .Vt tumbler_t . The caller must release it with .Fn tumbler_free . .Pp Examples: .Bd -literal -offset indent 1 1.2 1.2.3 0.1.0.7 .Ed .Pp Malformed input includes an empty string, a leading or trailing period, two periods in succession, non-decimal characters, and negative fields. .Sh COMPARISON .Fn tumbler_compare returns a negative value, zero, or a positive value according as .Fa a is less than, equal to, or greater than .Fa b . .Pp Comparison is performed from the most significant field toward the least significant. A missing field is treated as zero for comparison. Thus: .Bd -literal -offset indent 1 < 1.1 < 1.1.1 < 1.2 < 2 .Ed .Pp This is the infinitesimal-style tumbler ordering used by the small Udanax-derived tumbler implementations. In this implementation, trailing zero fields do not change comparison order. .Sh ADDITION .Fn tumbler_add implements Xanadu tumbler addition. The operands have different roles: .Fa position is a position and .Fa offset is a distance to move forward. .Pp The procedure is: .Bl -enum .It Copy fields from the position while the corresponding offset fields are zero. .It At the first non-zero offset field, add it to the corresponding position field. .It Copy the remaining offset fields into the result. .El .Pp For example: .Bd -literal -offset indent 3 + 2.16.3 = 5.16.3 25.6.46.93 + 0.0.3.1.21 = 25.6.49.1.21 .Ed .Pp Addition is non-commutative. .Sh SUBTRACTION The historical system distinguishes strong and weak subtraction. .Fn tumbler_subtract_strong implements strong subtraction and .Fn tumbler_subtract_weak implements weak subtraction. .Pp Strong subtraction preserves matching leading fields as zero until the first difference, subtracts there, then copies the remaining fields from the position. It requires .Fa position not be less than .Fa offset . .Pp For example: .Bd -literal -offset indent 1.4.3 s- 1.1.1 = 0.3.3 0.1.2.3.4.5.6 s- 0.1.2.3.3.3.3 = 0.0.0.0.1.5.6 .Ed .Pp Weak subtraction preserves the position through leading zero offset fields, then subtracts the first non-zero offset field and stops. For example: .Bd -literal -offset indent 1.4.3 w- 1.1.1 = 0 0.3.3.3.4.5.6 w- 0.1.1.3.3.3.3 = 0.2 .Ed .Pp .Fn tumbler_subtract is the generalized difference operation used by the Xanadu system. If .Fa a is greater than .Fa b , strong subtraction computes .Ql a - b . Otherwise weak subtraction computes .Ql b - a . The result is therefore never negative. .Sh MEMORY All parsed and arithmetic result tumblers own heap storage for their digit arrays. The caller is responsible for calling .Fn tumbler_free . .Pp Strings returned by .Fn tumbler_to_string are allocated with .Xr malloc 3 and are released with .Xr free 3 . .Sh ERRORS The result structure uses these codes: .Bl -tag -width TUMBLER_ERR_UNDERFLOW .It Dv TUMBLER_OK Success. .It Dv TUMBLER_ERR_NULL A required pointer was null. .It Dv TUMBLER_ERR_INVALID The tumbler representation is malformed. .It Dv TUMBLER_ERR_NOMEM Memory allocation failed. .It Dv TUMBLER_ERR_OVERFLOW An integer field or arithmetic result exceeded .Vt uint64_t . .It Dv TUMBLER_ERR_UNDERFLOW A subtraction would require a negative field. .El .Sh SEE ALSO .Xr enfilade 3 , .Xr tumbler-s7 7 , .Xr enfilade-s7 7 .Sh REFERENCES .Pp .Lk https://sentido-labs.com/en/library/201904240732/Xanadu%20Hypertext%20Documents.html .Pp .Lk https://pypi.org/project/xanalogica.tumbler/