add(): Addition for Numbers, Units, and Collections

add() combines two or more compatible values. For ordinary numbers it performs familiar addition, but it is also valuable in programmatic expressions because it makes the operation explicit and composes naturally with other functions. For example, add(2, 3) returns 5.

Compatible inputs matter

Values must be mathematically compatible. Numbers can be added directly; compatible units can be converted and summed; and matrices generally require matching dimensions for element-wise addition. Adding incompatible dimensions, such as a length and a time, should be treated as an error rather than silently coerced.

Use subtract() to express a difference, multiply() for scaling, and sum() to aggregate a collection. For vectors and matrices, dot() is a different operation: it produces an inner product rather than a component-by-component sum.

Practical calculations

In a budget, add can combine expenses after bringing them to the same currency. In geometry, it can combine coordinate offsets. In a spreadsheet-like calculation, explicit add calls make nested formula order easy to read: add(base, multiply(rate, quantity)).

Floating-point arithmetic may show tiny rounding residues, so use round() when presenting monetary or measured results, not prematurely during intermediate calculations. Addition is associative in exact mathematics, but finite precision means that summing very differently sized values can slightly depend on order.