mixradix

Add, subtract and convert integers of any size in mixed radix bases, where every digit position has its own radix: hours:minutes:seconds, pounds:shillings:pence, feet:inches, or plain hexadecimal. Zero dependencies, bigint based, ESM with TypeScript types, with a command line tool. Works in Node.js 22+ and browsers (the CLI needs Node.js).

npm install mixradix
npx mixradix add 23:59:59 1 -b 24:60:60       # 1:0:0:0

Also available for Python as mixradix on PyPI, with the same behaviour and CLI.

Bases

A base lists one radix per digit position, most significant first, like the digits of a number:

| Base | Meaning | |---|---| | 10, 16, 2 | plain decimal, hexadecimal, binary | | 24:60:60 | hours:minutes:seconds (days above that have no limit) | | 20:12 | pounds:shillings:pence | | 24:60/wrap | a 24-hour clock that wraps around | | 2:3:4/repeat | ...2:2:3:4: the leftmost radix repeats |

The part after / is the overflow: what happens left of the leftmost radix.

| Overflow | What is left of the leftmost radix | Default for | |---|---|---| | repeat | the same radix again, forever | one radix (16) | | extend | one more digit with no limit | several radices (24:60:60) | | wrap | nothing: values wrap around modulo the product of the radices | |

So 30 days in 24:60:60 is 30:0:0:0, and in 24:60:60/wrap it is 0:0:0.

Numbers

• One character per digit (ff, 1011, case-insensitive) in a base with one radix of at most 36, like 16 or 2.
• Decimal digits separated by : (1:23:59) in every base.
• In a base like 24:60:60, text without : is a single digit: 45 is 45 seconds.
• A leading - or + sets the sign. With wrap, values are never negative.

Every digit must be below its position's radix, so 1:60:0 is rejected in 24:60:60.

Library

import { add, convert, MixedRadix, MixedRadixNumber, sub } from "mixradix";

// Quick string in, string out.
add("23:59:59", "1", { base: "24:60:60" });        // "1:0:0:0"
sub("1:0:0", "1", { base: "24:60:60", to: 10 });   // "3599"
convert(5000, { to: "24:60:60" });                 // "1:23:20"

// Bases and numbers.
const time = new MixedRadix("24:60:60");           // or new MixedRadix([24, 60, 60])
const t = time.parse("1:23:59");                   // or time.fromInt(5039)
t.value;                                           // 5039n
t.digits;                                          // [1n, 23n, 59n]
t.add(1).toString();                               // "1:24:0"
t.sub("0:23:59").toString();                       // "1:0:0"
t.to(10).toString();                               // "5039"
t.equals(5039);                                    // true: comparison is by value

const clock = new MixedRadix([24, 60], { overflow: "wrap" });
clock.parse("23:30").add("1:0").toString();        // "0:30"

new MixedRadixNumber("ff", 16).value;              // 255n

| API | What it does | |---|---| | new MixedRadix(base, { overflow }) | Base from "24:60:60", 16, or [24, 60, 60] | | .radices, .overflow, .maxDigits, .modulus | Describe the base | | .radixAt(p), .placeValue(p) | Radix and place value of position p (0 = least significant) | | .parse(text), .fromInt(n), .fromDigits(digits, { negative }) | Make a number (digits most significant first) | | new MixedRadixNumber(number, base = 10) | Number from text or an integer | | .value, .digits, .isNegative, .base | Read a number (bigint values) | | .add(x), .sub(x), .neg(), .abs() | Arithmetic, returning new numbers | | .compare(x), .equals(x) | Comparison by value | | .to(base), .toString(), .toBigInt() | Conversion | | add(...numbers, { base, to }), sub(...), convert(number, { to, base }) | String in, string out |

Integers can be number (safe integers only) or bigint. Operands can be other numbers in any base, integers, or text in the left operand's base. The result uses the left operand's base. Numbers and bases are immutable, and JSON.stringify writes them as their text.

Errors are MixedRadixError with subclasses InvalidBaseError, InvalidNumberError and DigitOutOfRangeError.

Command line

mixradix add <NUMBER> <NUMBER>... [-b BASE] [-t TO] [--json]
mixradix sub <NUMBER> <NUMBER>... [-b BASE] [-t TO] [--json]   (alias: subtract)
mixradix convert <NUMBER> -t TO [-b BASE] [--json]
mixradix info <BASE> [--json]

• -b, --base: the base the numbers are written in. Defaults to 10.
• -t, --to: the base to write the result in. Defaults to --base.
• Negative numbers work as they are: -5, -1:30, -ff. Only one that starts with an option letter, like -b1 in base 16, goes after --.

$ mixradix add 1:30 2:45 0:50 -b 60                  # sum of durations
5:5
$ mixradix sub 0:15 0:30 -b 24:60/wrap               # clock arithmetic
23:45
$ mixradix convert 100000 -t 24:60:60
1:3:46:40
$ mixradix convert -90 -t 60 --json
{"result":"-1:30","value":-90,"digits":[1,30],"negative":true,"base":"60"}
$ mixradix info 24:60/wrap
base:         24:60/wrap
overflow:     wrap (values wrap around modulo 1440)
digits:       exactly 2
place values: 60, 1
range:        0 to 1439

Exit codes: 0 on success, 1 for an invalid base or number, 2 for a usage error.

License

MIT OR Apache-2.0, at your option.