commensura.core — com.github.crinklywrappr/commensura 1.0.39

Public verbs for combining and converting quantities. All are plain vars (autocomplete-friendly, no clojure.core shadowing) and interoperate with plain numbers as dimensionless scalars.

(require '[commensura.units :as u] '[commensura.core :refer [by per plus minus pow to ratio]])

(to (by (u/feet 10) (u/feet 12) (u/feet 8)) u/gallons) ;=> 552960/77 gallon ≈ 7181.30 [volume] ; str/println form; prn wraps it in a ; #commensura/quantity tagged literal

Comparison verbs — the everyday lt?/le?/gt?/ge?/eq?/ne? (a physical, dimension-checked order that throws on overlapping intervals) plus the interval-aware certainly-…?/possibly-…? operators — order quantities by base magnitude, so (eq? (u/inch 12) (u/foot 1)) is true.

The verbs also accept Intervals (see commensura.interval); an interval accessor treats a bare quantity/number as a degenerate interval, so no scalar promotion is needed.

by clj

(by x)

(by x y)

(by x y & more)

Product of quantities/numbers/intervals/uncertains (dimensions add). Variadic.

certainly-eq? clj

(certainly-eq? x y)

x and y are the same single point (both collapse to one shared value).

certainly-ge? clj

(certainly-ge? x y)

x's low bound >= y's high bound: every value of x >= every value of y.

certainly-gt? clj

(certainly-gt? x y)

x's low bound is above y's high bound: every value of x > every value of y.

certainly-le? clj

(certainly-le? x y)

x's high bound <= y's low bound: every value of x <= every value of y.

certainly-lt? clj

(certainly-lt? x y)

x's high bound is below y's low bound: every value of x < every value of y.

certainly-ne? clj

(certainly-ne? x y)

x and y are disjoint: their ranges share no value.

defstep clj macro

(defstep name & fdecl)

Define a function whose call records as one provenance node (its internals forgotten). Like defn — a docstring and multiple arities are supported — each arity's body is wrapped in step with that arity's parameters as inputs (a variadic arity folds its rest args in), and the node's op is the new #'fully-qualified var:

(defstep sqrt [x] (c/pow x 1/2)) ; records #'…/sqrt over [x]; the inner pow leaves no trace (defstep root ([x] (c/pow x 1/2)) ([x n] (c/pow x (/ 1 n))))

defunit clj macro

(defunit sym expr)

(defunit sym a b)

(defunit sym doc mag dims)

Define a callable Unit var. The bound value is the new unit name: it prints under its own name, scales when called, and serves as a to/ratio target.

Four caller-facing forms — the 3-argument shape dispatches on whether its middle form is a number (⇒ literal) or not (⇒ docstring):

• (defunit sym expr) — the everyday form: expr is any quantity/number expression; its magnitude and dimensions become the unit's.
• (defunit sym doc expr) — as above, with a leading docstring on the var.
• (defunit sym magnitude dims) — a literal base-SI magnitude and dimension map, with no evaluation; the form the generated builtins emit.
• (defunit sym doc magnitude dims) — the literal form with a leading docstring (a generated builtin that carries a comment).

Examples:

(defunit beer (by (u/floz 12) (u/percent 3.2) (per u/water u/alcohol))) (beer 5) ;=> 5 beer (to (by u/magnum (u/percent 13.5)) beer) ;=> …how many beers in a magnum (ratio some-volume beer) ;=> …bare count of beers

(defunit smoot "Oliver Smoot's height (an MIT prank unit)" (u/inch 67))

(defunit foot 381/1250 {:length 1}) ; literal form (defunit gee "standard gravity" 196133/20000 {:length 1 :time -2})

eq? clj

(eq? x y)

Physical equality; throws on overlap.

ge? clj

(ge? x y)

Greater-or-equal; throws on overlap.

gt? clj

(gt? x y)

Greater than; throws on overlap.

le? clj

(le? x y)

Less-or-equal; throws on overlap.

lt? clj

(lt? x y)

Less than; throws on overlapping intervals.

minus clj

(minus x)

(minus x y)

(minus x y & more)

Difference of same-dimension quantities/intervals/uncertains; unary form negates.

money->quantity clj

(money->quantity money)

Convert an org.joda.money.Money into an exact commensura currency quantity. The Money's ISO code resolves to a live currency unit (through the currency resolver — require commensura.currency first) scaled by the Money's decimal amount, which re-enters the exact tower as a rational. Inverse of quantity->money (Money already sits at the currency's scale, so nothing is lost coming back).

(money->quantity (quantity->money (cur/USD 19.99))) ;=> 1999/100 USD ; == (cur/USD 19.99)

ne? clj

(ne? x y)

Physical inequality; throws on overlap.

per clj

(per x)

(per x y)

(per x y & more)

Quotient, left-associative: (per a b c) = a/b/c (dimensions subtract).

plus clj

(plus x)

(plus x y)

(plus x y & more)

Sum of same-dimension quantities/intervals/uncertains. Variadic.

possibly-eq? clj

(possibly-eq? x y)

x and y overlap: their ranges share a value.

possibly-ge? clj

(possibly-ge? x y)

Some value of x >= some value of y.

possibly-gt? clj

(possibly-gt? x y)

Some value of x > some value of y.

possibly-le? clj

(possibly-le? x y)

Some value of x <= some value of y.

possibly-lt? clj

(possibly-lt? x y)

Some value of x < some value of y.

possibly-ne? clj

(possibly-ne? x y)

x and y are not a single shared point.

pow clj

(pow x n)

Raise a quantity/interval/uncertain to an integer or rational power.

quantity->money clj

(quantity->money qty)

(quantity->money qty mode)

Convert a currency quantity to an org.joda.money.Money (via clojurewerkz/money). qty must carry a currency dimension of exponent 1; its ISO code is the currency term's name (dollar → USD). The displayed amount is rounded to the currency's decimal places — HALF_EVEN by default, or pass a java.math.RoundingMode.

This deliberately leaves commensura's exact tower: Money is a fixed-scale decimal, so an amount finer than the currency's minor unit is rounded. Throws on non-currency dimensions or a non-ISO code. Inverse of money->quantity (up to that scale-rounding).

(quantity->money (cur/USD 19.99)) ;=> USD 19.99 (quantity->money (cur/USD 19.995)) ;=> USD 20.00 (HALF_EVEN) (quantity->money (cur/USD 19.995) RoundingMode/FLOOR) ;=> USD 19.99

ratio clj

(ratio x target)

Dimensionless count: how many of target fit in x (quantity/interval/uncertain).

register-dimension! clj

(register-dimension! dims nm)

Give a human name to a dimension map, so quantities of that dimension print it in the trailing [..] slot (overriding any builtin). Returns the name.

(register-dimension! {:length 4} "quaternary space") (pow u/meter 4) ;=> 1 meter^4 ≈ 1.0 [quaternary space]

register-unit-resolver! clj

(register-unit-resolver! pred dispatch)

Install a resolver for a family of units derivable from their name rather than registered one by one (the extension seam behind commensura's own historical currencies). pred is name -> boolean; dispatch is name -> unit, invoked when a name isn't in the unit table and pred matches. So a #commensura/unit "…" literal (and to/ratio) reify the whole family on demand. Resolvers are tried in registration order, first match wins. Complements defunit (a single fixed unit).

span clj

(span x unit)

The extent of a range (Interval or Uncertain) as a single dimensioned quantity in unit: hi − lo re-expressed in unit. (span (iv/interval (u/meter 6) (u/meter 11)) u/foot) ⇒ ≈ 16.40 foot [length]; for an Uncertain it is the full 2σ width. A plain quantity is a point, so its span is 0. See ratio for the bare count and ticks for the individual marks along the span.

ticks clj

(ticks x unit)

Mark a range (Interval or Uncertain) off unit-by-unit — a unit ruler laid along the span: quantities from the low bound toward the high bound in increments of one unit, each expressed in unit. Half-open [lo, hi), like range — a mark landing exactly on hi is excluded, so each mark owns the cell [mark, mark+unit) and the cells tile the range without double-counting. Marks start at the low bound (so the first may be fractional in unit). Returns an eduction, so it reduces without an intermediate seq and composes with transducers and into:

(into [] (ticks (iv/interval (u/meter 6) (u/meter 11)) u/foot)) (into [] (map m/round) (ticks some-interval u/foot))

to clj

(to x target)

Re-express a quantity/interval/uncertain in a target unit (dimension-preserving). Uses only the target's unit basis: a scaled target's coefficient is ignored (and warns) — (to (u/mile 5) (u/foot 3)) gives feet, not 3-foot units. For "how many of a given quantity fit", use ratio. See q/to.

with-provenance clj macro

(with-provenance & body)

Evaluate body with provenance recording on, returning its value (now carrying history).