Ensifer/doc/tumbler.3

.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/