TinyMUX

Math and Numeric Functions

Softcode

TinyMUX provides a broad set of math and numeric functions covering arithmetic, comparison, bitwise operations, trigonometry, exponentials, randomness, list aggregation, vector math, and base conversion. Every value in softcode is a string, so these functions parse their arguments as numbers, perform the operation, and return a string result.

Numeric Types

TinyMUX works with two numeric types: integers and IEEE 754 double-precision floating-point numbers. Functions that accept <number> generally accept either type. If any argument is floating-point, the result is typically floating-point. Integer-specific functions (the i-prefix family) truncate to integers. Special floating-point values +Inf, -Inf, Ind (indeterminate, e.g. sqrt(-1)), and NaN propagate through calculations rather than producing errors.

Basic Arithmetic

add(), sub(), mul() perform addition, subtraction, and multiplication. add() and mul() accept up to 100 arguments. All three accept floating-point inputs and return floating-point results when appropriate. Division comes in several forms:

  • fdiv(<a>,<b>) – floating-point division. fdiv(16,3) returns 5.333333.
  • idiv(<a>,<b>) – integer division, truncated toward zero. idiv(-17,3) returns -5. div() is an alias for idiv().
  • floordiv(<a>,<b>) – integer division, rounded toward negative infinity. floordiv(-17,3) returns -6.
  • mod(<a>,<b>) – integer remainder paired with floordiv(). For positive <b>, the result is always non-negative. mod(-9,5) returns 1.
  • fmod(<a>,<b>) – floating-point remainder. fmod(6.1,2.5) returns 1.0999999999999996.

The identity floordiv(x,y)*y + mod(x,y) == x always holds.

inc(<n>) and dec(<n>) add or subtract 1 and are faster than the equivalent add() or sub() calls. Both truncate decimals.

Integer-Specific Arithmetic

iadd(), isub(), imul(), and idiv() mirror their non-prefixed counterparts but use strict integer math. iadd() and imul() accept up to 100 arguments. These are faster when all values are known to be integers.

Comparison

gt(), gte(), lt(), lte(), eq(), and neq() compare two integers and return 1 or 0. Non-numeric strings are treated as 0, so eq(foo, bar) returns 1. comp(<a>,<b>[,<type>]) performs string comparison returning -1, 0, or 1. By default it uses Unicode collation; pass c for case-insensitive or a for legacy ASCII byte-order.

Bitwise Operations

  • band(<a>,<b>[,...]) – bitwise AND.
  • bor(<a>,<b>[,...]) – bitwise OR.
  • bxor(<a>,<b>[,...]) – bitwise exclusive OR.
  • bnand(<a>,<b>) – AND of <a> with the complement of <b>, forcing specific bits off.
  • shl(<n>,<count>) – left shift, equivalent to multiplying by 2^count.
  • shr(<n>,<count>) – right shift, equivalent to dividing by 2^count.

All operands are integers. band(), bor(), and bxor() accept multiple arguments.

Rounding and Truncation

  • abs(<n>) – absolute value.
  • sign(<n>) – returns -1, 0, or 1.
  • round(<n>,<places>) – round to <places> decimal positions. Negative values round to tens, hundreds, etc.
  • trunc(<n>) – truncate toward zero. trunc(-5.2) returns -5.
  • ceil(<n>) – smallest integer greater than or equal to <n>. ceil(-5.2) returns -5.
  • floor(<n>) – largest integer less than or equal to <n>. floor(-5.2) returns -6.

Trigonometry

All trigonometric functions accept an optional <units> argument: radians (default), degrees, or gradians (or just the first letter).

  • sin(), cos(), tan() – standard trig functions.
  • asin(), acos(), atan() – inverse trig functions.
  • atan2(<y>,<x>[,<units>]) – two-argument arctangent, returning an angle in all four quadrants.

Exponential and Logarithmic

  • exp(<power>) – e raised to <power>.
  • ln(<n>) – natural logarithm (base e). ln(0) returns -Inf.
  • log(<n>[,<base>]) – logarithm, defaulting to base 10. Use e for <base> for a natural logarithm.
  • sqrt(<n>) – square root. Negative input returns Ind.
  • power(<base>,<exp>) – raise <base> to <exp>. <base> may not be negative.

Constants

pi() returns 3.141592653589793. e() returns 2.718281828459045.

Random Numbers

  • rand(<n>) – random integer from 0 to n-1. rand(<lower>,<upper>) returns an integer in the inclusive range.
  • lrand(<lower>,<upper>,<count>[,<delim>]) – list of random integers in the given range.
  • die(<rolls>,<sides>) – simulates dice rolls. die(2,6) gives a result from 2 to 12.
  • pickrand(<list>[,<delim>]) – picks a random element from a list.
  • choose(<items>,<weights>[,<delim>]) – weighted random selection. choose(1 2 3,1 0 0) always returns 1.

List Math

  • ladd(<list>[,<delim>]) – sum of a list of numbers.
  • lmax(<list>[,<delim>]) – maximum value in a list.
  • lmin(<list>[,<delim>]) – minimum value in a list.
  • lmath(<op>,<list>[,<delim>]) – general list math supporting add, sub, mul, div, mod, min, max, mean, median, and stddev.

Vector Math

Vectors are space-separated (or delimiter-separated) lists of numbers, up to 20 dimensions. All vector functions accept optional delimiter and output-delimiter arguments.

  • vadd(<v1>,<v2>) / vsub(<v1>,<v2>) – element-wise addition and subtraction.
  • vmul(<v>,<s>) – scalar multiplication, or element-wise multiplication if both arguments are vectors.
  • vdot(<v1>,<v2>) – dot product (scalar result).
  • vcross(<v1>,<v2>) – cross product (3D vectors only).
  • vmag(<v>) – magnitude (Euclidean length).
  • vunit(<v>) – unit vector in the same direction.
  • vdim(<v>) – number of dimensions.

Distance and Base Conversion

dist2d(<x1>,<y1>,<x2>,<y2>) and dist3d(<x1>,<y1>,<z1>,<x2>,<y2>,<z2>) return Euclidean distances in 2D and 3D respectively.

baseconv(<number>,<from>,<to>) converts between bases 2 through 64. Bases 36 and under use 0-9A-Z. Bases above 36 use the URL-safe Base64 alphabet.

Floating-Point Precision

The float_precision config parameter (wizard-only) controls how floating-point results are displayed. When set to a non-negative value such as 6, results are rounded to that many decimal places and trailing zeros are stripped—matching TinyMUSH behavior. When set to -1 (the default), TinyMUX uses a full-precision approach that emits the fewest digits needed to uniquely identify the internal double value. For example, sub(1.01,1) returns 0.01000000000000001 at full precision but 0.01 at precision 6.

Common Pitfalls

Floating-point comparison. Because 0.1 cannot be represented exactly in binary floating-point, eq(add(0.1,0.2),0.3) may not return 1. Use round() before comparing, or work in integer units (cents instead of dollars).

Comparison treats non-numbers as zero. eq(), gt(), and friends parse non-numeric strings as 0, so eq(foo,bar) returns 1.

Division semantics. idiv() truncates toward zero; floordiv() truncates toward negative infinity. The choice matters for negative operands. mod() pairs with floordiv(); remainder() pairs with idiv().