README- UCellParseLocation
- UChartKind
- UChartSpec
- UClosedInterval
- UCsvReadOptions
- UCsvWriteOptions
- UDataError
- UDataFrame
- UDataType
- UExpr
- UField
- UHtmlOptions
- UJoinOptions
- UJoinType
- UJsonReadOptions
- UKeepStrategy
- ULazyFrame
- UOnParseError
- UParseErrorDetail
- UPivotAgg
- UQuantileInterpolation
- URankMethod
- UScalar
- USchema
- USeries
- UTypeMismatchDetail
- UVegaType
- Vcol
- Vcols
- Vformat_vega_lite
- Vlit
- Vlit_bool
- Vlit_float
- Vlit_int
- Vlit_series
- Vlit_str
- Vmap_many
- Vread_csv
- Vread_json
- Vread_ndjson
- Vscan_csv
- Vscan_json
- Vscan_ndjson
- Vwhen
- Vwrite_csv
- Vwrite_json
- Vwrite_ndjson
- Vwrite_vega_lite
ihb2032/MoonFrame/expr does not have a README file
Expr
pub struct Expr {
// private fields
}A composable column expression — the reified upgrade over the closure-based
surfaces (the original row-predicate closure) and pre-materialised Series
columns. An Expr is built through the constructor functions
(col / lit / lit_* / when), the operator impls, and the methods,
so every tree is well-formed by construction; the when chain stages
through the WhenThen / WhenThenElse types below, completing as a
Ternary. Building one is
total — unknown columns and dtype mismatches surface at evaluation time
(in frame), never here.
The type is opaque: it wraps an ExprNode AST and exposes no
variants. Outside this package an expression is a value you build and pass
on, or render with to_string — there is no matching on its shape. The AST
itself is module-internal, in a package a downstream module cannot import
at all, so no caller can name a node, match
one, or hold one: adding a node for a new operator breaks nobody.
The shape is not observable either: there is no == on an expression. One
existed, comparing the two trees, and it made how an operator lowers a
promise to callers — normalising a tree or merging two node kinds would
have changed what compared equal without changing what any expression
means. to_string() is what a caller inspects with instead; it renders
what it prints, so two literal series differing only in their cells render
alike.
The engine reads the shape through four accessors beside the type —
node() hands over the wrapped AST, and children() /
referenced_columns() / output_name() answer its introspection
questions. frame and lazy are in-module and match ExprNode
directly.
The wrapped AST carries ExprNode children, not Expr, so this package
bridges the two: a constructor unwraps its child Exprs with .node, and
the children accessor below wraps ExprNode children back into Expr. The
nodes, in construction-route order:
- Col / Lit / LitSeries — leaves (col, lit / lit_*, lit_series); a LitSeries embeds a pre-materialised Series;
- Binary — arithmetic + - * /, comparisons, Kleene & / |;
- Unary — -e, .not(), the null / NaN / finiteness probes, the dt_* calendar quartet, .abs() / .floor() / .ceil() / .sign() / .round(), and the always-Float math family .sin() … .sqrt() (.atan2() / .hypot() ride Binary);
- Agg — .sum() / .mean() / … reductions;
- Str — the .str_* namespace;
- Positional — the history-dependent transforms (.shift(n) / .diff(n), the .cum_* running aggregates, .rank(how~), .arg_sort(), the .rolling_* windowed statistics, .forward_fill() / .backward_fill(), .unique_counts(), .is_first_distinct() / .is_last_distinct()), whose cell reads its neighbours or the column's occurrence structure;
- Cast — .cast(dtype); Alias — .with_alias(name);
- Ternary — when(c).then(a).otherwise(b);
- FillNull / FillNan — .fill_null(v) / .fill_nan(v), dedicated nodes (not lowered to a Ternary) so the operand appears once and a chained coalesce stays linear;
- Diff / Clip — .diff(n) / .clip(lower?, upper?), likewise dedicated (not lowered to - shift(n) / a nested when) so the operand appears once and a chained difference or clamp stays linear;
- IsIn / IsBetween — the membership / range predicates, likewise dedicated so the operand is evaluated once;
- Map / MapBatches — the row-wise / batched closure escape hatches (.map_elements() / map_many() / .map_batches()), the function opaque so each is identified by its (label, inputs) (MapBatches also by its returns_scalar flag).
a & b — logical AND over Bool expressions, with Kleene three-valued
null semantics (false & null = false, true & null = null). & is
MoonBit's only overloadable conjunction (&& is built-in short-circuit
syntax). For chains that read better without operators, the impl method
itself is the alias: a.land(b) — and is a MoonBit reserved word
(mutual recursion), so the core trait's own spelling serves instead.
a | b — logical OR over Bool expressions, with Kleene three-valued
null semantics (true | null = true, false | null = null). Same
operator-choice rationale as &; the method alias is likewise the impl
spelling, a.lor(b) (paired with land rather than a lone or).
a / b — division, always Float: Int operands promote, and division
by zero follows IEEE 754 (±inf / nan) on every backend rather than
trapping — Int division-by-zero behaviour differs across backends, so
it is never emitted. A null on either side nulls the output cell.
Render the documented operator form, e.g.
(col(revenue) - col(cost)) as profit: columns as col(name), bare
literals (strings quoted, the null literal as null), binary nodes
parenthesised infix, prefix (-e) / (not e), the remaining unary
probes and Agg / Cast as postfix method calls, Alias as
expr as name, Ternary mirroring its when(c).then(a).otherwise(b)
construction route, a Map as map("label", [inputs]), and a
LitSeries as lit_series("name", len). Handwritten because
derive(Show) is deprecated — and the derived variant form would leak
construction-route noise into explain output anyway.
Handwritten Debug: the ExprNode Map / MapBatches closures
have no Debug, so neither the AST node nor the Expr wrapping it can
derive one. The debug form delegates to
the Show rendering (to_string), which already presents every variant —
Map by its (label, inputs), the closure opaque — in the documented
operator form. Debug output surfaces in debug_inspect and in the failure
message of any assertion over something that embeds an expression — the
handle itself has no equality to fail. Repr's public constructor wraps
the Show rendering's string directly.
Expr::abs
a.abs() — absolute value. Int → Int (Int64::MIN wraps, like Neg);
Float → Float (|NaN| = NaN, |-0.0| = 0.0). A null stays null; a
non-numeric operand raises TypeMismatch.
Expr::acos
a.acos() — the arccosine, always Float (Int promotes to
Double, like /); a cell outside the [-1, 1] domain (including
±inf) is NaN under IEEE 754. A null stays null; a non-numeric operand
raises TypeMismatch.
Expr::acosh
a.acosh() — the inverse hyperbolic cosine, always Float (Int
promotes to Double, like /); a cell below 1 (including ±inf's
domain miss and negatives) is NaN under IEEE 754. A null stays null; a
non-numeric operand raises TypeMismatch.
Expr::arg_max
Window-local position of the maximum over the evaluation scope — arg_min
with the order reversed, sharing its dtype-total, NaN-skipping, and
earliest-tie rules.
Expr::arg_min
Window-local position of the minimum over the evaluation scope, as an
Int — min's positional twin. Total over every dtype (NaN skipped
like min), a tie keeps the earliest position (deterministic), and
an empty / all-null scope reduces to null.
Expr::arg_sort
The stable permutation that would sort the operand: an Int column
holding, for each output row, the operand position that lands there —
non-null positions ordered by value (ties in input order), the null
positions' own indices placed per nulls_last~ (false mirrors the
sort kernel's nulls-first default). descending~ flips the value
order. Feed it to gather to reorder a frame.
Expr::asin
a.asin() — the arcsine, always Float (Int promotes to Double,
like /); a cell outside the [-1, 1] domain (including ±inf) is
NaN under IEEE 754. A null stays null; a non-numeric operand raises
TypeMismatch.
Expr::asinh
a.asinh() — the inverse hyperbolic sine, always Float (Int
promotes to Double, like /), total under IEEE 754. A null stays null;
a non-numeric operand raises TypeMismatch.
Expr::atan
a.atan() — the arctangent, always Float (Int promotes to
Double, like /), total under IEEE 754. A null stays null; a
non-numeric operand raises TypeMismatch.
Expr::atan2
a.atan2(b) — the two-argument arctangent atan2(a, b) (angle of the
point (b, a)), always Float (Int operands promote to Double,
like /), total under IEEE 754 — the sign of a zero operand is
observable (atan2(±0.0, -1.0) = ±π), and a NaN on either side gives
NaN. A null on either side nulls the output cell; a non-numeric
operand raises TypeMismatch.
Expr::atanh
a.atanh() — the inverse hyperbolic tangent, always Float (Int
promotes to Double, like /); a cell outside (-1, 1) is NaN except
±1 itself, which gives ±inf under IEEE 754. A null stays null; a
non-numeric operand raises TypeMismatch.
Expr::backward_fill
Replace each null cell with the nearest present value below it —
forward_fill's mirror, trailing null runs staying null, with the same
limit? cap and dtype-generic copying.
Expr::cast
Cast the operand to target at evaluation time, delegating to
Series::cast (so the supported dtype pairs — and the Unsupported
cases — are exactly the eager ones).
Expr::cbrt
a.cbrt() — the cube root, always Float (Int promotes to
Double, like /), exact on every Double including negatives and
±inf (cbrt(-8) = -2); only NaN maps to NaN. A null stays null; a
non-numeric operand raises TypeMismatch.
Expr::ceil
a.ceil() — round toward +∞ to an integer value. Float → Float; Int →Int unchanged. ±inf / NaN pass through. A null stays null; a
non-numeric operand raises TypeMismatch.
Expr::clip
Clamp each cell into [lower?, upper?]: a cell below lower? becomes
it, one above upper? becomes it, one inside passes through, and a null
cell stays null (the bounds are not applied to it). A null bound cell
leaves the operand cell untouched — a null bound is no bound on that
side, not a null answer. Either bound may be omitted — one-sided clamps —
and both omitted is the identity. With both bounds given the lower clamp
runs first, so a degenerate pair (lower? above upper?) clamps every
cell to upper?. Carried by a dedicated node that embeds the operand
once — the nested when composition embedded it four times — so a
chained clamp stays linear. Dtype unification and the NaN-stays-put
reading (no comparison holds against NaN) are the comparison kernel's
own. The result keeps the operand's own name, so a column bound does
not hand with_columns the bound's name.
Expr::cos
a.cos() — the cosine, always Float (Int promotes to Double,
like /): cos(±inf) / cos(NaN) are NaN under IEEE 754. A null stays
null; a non-numeric operand raises TypeMismatch.
Expr::cosh
a.cosh() — the hyperbolic cosine, always Float (Int promotes to
Double, like /); an out-of-range result is ±inf under IEEE 754. A
null stays null; a non-numeric operand raises TypeMismatch.
Expr::count
Count of non-null cells of the operand over the evaluation scope
(Series::count semantics).
Expr::cum_count
Running count of the operand's non-null cells,
total over every dtype: a null slot repeats the count the prior cell
reached ([x, k, null, d] counts 1, 2, 2, 3). Always an Int column.
reverse~ counts from the end.
Expr::cum_max
Running maximum of the operand's non-null cells — cum_min with the
order reversed, sharing every rule.
Expr::cum_min
Running minimum of the operand's non-null cells,
with cum_sum's null / reverse~ rules; a NaN is skipped (the
extrema rule, not the sum's). Numeric only.
Expr::cum_prod
Running product of the operand's non-null cells,
with cum_sum's null / NaN / reverse~ rules. Numeric only.
Expr::cum_sum
Running sum of the operand's non-null cells: a null
slot keeps its null while the running total skips it, a NaN enters the
total and stays. Numeric only. reverse~ accumulates from the end.
Expr::diff
Cell-wise difference against the cell n rows above (default n = 1):
exactly the semantics of self - self.shift(n) — the leading n slots
null, a null in either operand null, and the subtraction under the
arithmetic kernel's dtype rules (Int stays Int, a Float operand
promotes) — but carried by a dedicated node that embeds the operand
once, so a chained difference stays linear where the composition
embedded it twice and grew exponentially with chain length. There is no
length-changing spelling here — no variant drops the nulled rows.
Expr::dt_day_of_week
The ISO weekday of each Date cell — Monday 1 through Sunday 7 (the
epoch is a Thursday, and dates before 1970 land on the right day too).
Expr::dt_month
The calendar month of each Date cell, 1–12.
Expr::dt_year
The calendar year of each Date cell — the shared dt_* contract, the
component being the four-digit year.
Expr::eq
a.eq(b) — elementwise equality, producing a Bool column. The whole
comparison family is methods, not operators: MoonBit pins the Eq /
Compare traits to Bool / Int returns, so they cannot build an
Expr — and the postfix method binds tighter than & / | anyway, so
a.gt(x) & b.lt(y) needs no parentheses. A null on either side nulls
the output cell.
Expr::exp
a.exp() — the exponential, always Float (Int promotes to
Double, like /); an out-of-range result is +inf under IEEE 754
(exp(-inf) = 0). A null stays null; a non-numeric operand raises
TypeMismatch.
Expr::fill_nan
Replace every NaN cell of self with value, keeping the non-NaN
cells (including true nulls) verbatim. The dual of fill_null: where
fill_null replaces missing cells and leaves NaN (a value) alone,
fill_nan replaces NaN and leaves nulls alone.
It evaluates exactly like
when(self.is_not_nan()).then(self).otherwise(value) — named after
self (the operand), and a null cell — for which is_not_nan is null
— falls through the Kleene ternary to a null result, never to value.
The branches unify their dtype like any ternary (Int meets Float by
promoting to Float, any other mismatch is a TypeMismatch). Unlike
that ternary spelling, the dedicated FillNan node holds (and
evaluates) self once, so a chain of fills stays linear in tree size
and work. Building the node is total.
Expr::fill_null
Replace every null cell of self with value, keeping the non-null
cells verbatim — a coalesce of self over value when value is
itself a column. value is any expression: a literal (lit_int(0)),
another column (col("fallback")), or a computed tree.
It evaluates exactly like
when(self.is_not_null()).then(self).otherwise(value) — the result is
named after self (the filled column), never after value, so
with_columns([col("x").fill_null(...)]) replaces "x" in place. The
branches must unify their dtype the way a ternary's do — Int meets
Float by promoting to Float, any other mismatch is a TypeMismatch
at evaluation. A non-null NaN is a value (validity 1), so it is
kept, not filled; only true nulls are replaced. Unlike that ternary
spelling, the dedicated FillNull node holds (and evaluates) self
once, so the chained-coalesce idiom
(col("a").fill_null(col("b")).fill_null(lit_int(0))) stays linear in
tree size and work — the lowering embedded self twice and grew
exponentially with chain length. Building the node is total; errors
surface when a consuming verb evaluates it — and the value branch is
evaluated even where nothing needs filling, so fill_null(lit(Scalar::Null))
is an Unsupported from the null literal, not a no-op.
Expr::first
First cell of the operand over the evaluation scope, in row order, keeping
the operand's dtype. Positional — a null first cell is null, an empty scope
is null, and a present NaN passes through verbatim.
Expr::floor
a.floor() — round toward −∞ to an integer value. Float → Float; Int →Int unchanged (an integer is its own floor). ±inf / NaN pass through.
A null stays null; a non-numeric operand raises TypeMismatch.
Expr::floor_div
a.floor_div(b) — floor (integer) division, rounding the quotient toward
negative infinity. Named, not an operator: MoonBit's // is a line
comment. Same-dtype Int / Int → Int (-7 // 2 = -4, not the -3
truncation gives); any Float operand promotes the result to Float
(floor(a / b)). Int division by zero yields a null cell (integers
have no infinity, and a backend integer divide would trap); Float
division by zero follows IEEE 754 (±inf / nan) like /. A null on
either side nulls the output cell; a non-numeric operand raises
TypeMismatch.
Expr::forward_fill
Replace each null cell with the nearest present value above it — a
leading null run before any present cell stays null. limit? caps how
many consecutive null slots a single present value may fill (None =
unlimited — a run longer than the limit keeps its tail null); limit
below 1 is InvalidOperation at evaluation. Dtype-generic — the values
copied are the operand's own cells. Positional, so a row permutation is
observable (the optimizer fences it).
Expr::ge
a.ge(b) — elementwise >= (Bool column, null-propagating).
Expr::gt
a.gt(b) — elementwise > (Bool column, null-propagating).
Expr::hypot
a.hypot(b) — the Euclidean norm sqrt(a² + b²) computed without
intermediate overflow, always Float (Int operands promote to
Double, like /), total under IEEE 754; hypot(±0.0, x) treats the
zero's sign as unobservable, matching abs. A null on either side nulls
the output cell; a non-numeric operand raises TypeMismatch.
Expr::is_between
a.is_between(lo, hi) — a Bool column, true where a falls in the
range. closed picks which endpoints count: Both (the default) is
lo <= a <= hi, Left / Right open the other end, and None
excludes both. Equivalent to the matching ge / gt and le / lt pair
joined by land — it inherits their exact Int/Float ordering, String
/ Bool ordering, Kleene null propagation, and TypeMismatch on an
unorderable pair — but as a dedicated node the operand a is evaluated
once.
Expr::is_finite
Whether each cell is a finite number — a present Float cell unless it
is NaN or an infinity; a present Int cell always; a null cell null
(Kleene). Numeric only — a non-numeric operand is TypeMismatch.
Expr::is_first_distinct
Whether each cell is its value's first occurrence — a Bool per
cell, the shared distinct keying, so the first null is first-distinct.
The complement filter to unique(keep=First):
filter(col(x).is_first_distinct()) keeps one row per distinct value
in first-appearance order.
Expr::is_in
a.is_in(members) — a Bool column, true where the cell equals one of
the literal members. Each member is compared exactly as a.eq(lit(member))
would — the general path is an OR of eq over the set, and a
String / Bool / Int column whose members share its dtype takes an
equivalent single-pass membership test instead: Int / Float
members compare across types exactly (no 2^53 collision), and a member
whose dtype cannot compare with the column raises TypeMismatch. A Null
member matches nothing (it has no value to equal), an empty set is false
for every present cell, and a null cell yields null.
Expr::is_infinite
Whether each cell is an infinity — the Float infinities alone (NaN
is a value, not an infinity: false here and under is_finite both);
a present Int cell never; a null cell null. Numeric only.
Expr::is_last_distinct
Whether each cell is its value's last occurrence — the trailing
mirror of is_first_distinct.
Expr::is_nan
Bool column that is true where the operand holds the IEEE NaN value.
The operand must be numeric: an Int cell is never NaN (false), a
Float cell is tested by Double::is_nan, and a non-numeric operand
is a TypeMismatch at evaluation. Unlike is_null, this propagates
nulls — a missing cell is neither NaN nor not, so the result cell is
null — since NaN is a real value distinct from a missing one. Building
the node is total.
Expr::is_not_nan
Bool column that is true where the operand is a non-NaN numeric value
— the complement of is_nan on non-null cells, propagating nulls the same
way (a missing cell stays null). Same numeric-operand requirement.
Expr::is_not_null
Bool column that is true where the operand is non-null — the
complement of is_null, equally total.
Expr::is_null
Bool column that is true where the operand is null. Reads validity
only, so the result is itself never null (total).
Expr::last
Last cell of the operand over the evaluation scope, in row order, keeping
the operand's dtype. The positional mirror of first.
Expr::le
a.le(b) — elementwise <= (Bool column, null-propagating).
Expr::ln
a.ln() — the natural logarithm, always Float (Int promotes to
Double, like /); ln(0) is -inf, a negative cell is NaN, under
IEEE 754. A null stays null; a non-numeric operand raises TypeMismatch.
Expr::log10
a.log10() — the base-10 logarithm, always Float (Int promotes
to Double, like /); log10(0) is -inf, a negative cell is NaN,
under IEEE 754. A null stays null; a non-numeric operand raises
TypeMismatch.
Expr::log2
a.log2() — the base-2 logarithm, always Float (Int promotes to
Double, like /); log2(0) is -inf, a negative cell is NaN, under
IEEE 754. A null stays null; a non-numeric operand raises TypeMismatch.
Expr::lt
a.lt(b) — elementwise < (Bool column, null-propagating).
Expr::map_batches
Apply a host closure to self's whole evaluated column at once — the
batched escape hatch. Where map_elements hands f one Scalar per
row, map_batches hands it the entire Series and takes back a
Series, so a vectorised kernel (a cumulative sum, a rank, a rolling
window) runs once over the column rather than cell by cell. label
names the step in explain / Show; the closure is opaque to
introspection, rendering, and to the optimizer, which treats the node
as a barrier because it cannot see through it.
Building the node is total; f runs at evaluation and may raise.
Unlike map_elements, whose per-row closure simply never runs on an
empty frame, f receives its operand's whole column — an empty one
included: selecting over a zero-row frame hands f a 0-row Series,
and so does the grouped aggregation's dtype probe when there are zero
groups or every reduced cell is null. That empty-input call is the
contract: a closure must be total over an empty series — answer an
empty series of its output dtype — and not assume its input has rows.
The returned series rides the same length contract as lit_series: a
frame-tall result passes through, a length-1 result broadcasts, any other
length raises LengthMismatch in the consuming verb. The result is named
after self, so with_alias renames it, and its backend is canonicalised
(an all-valid numeric result lands on Numeric) so collect ≡ execute.
Set returns_scalar when f reduces its input to a length-1 series: it
marks the node as a per-group reduction so it is accepted as a custom
aggregation inside group_by(...).agg([...]), where f receives each
group's rows and must return a length-1 series (a non-length-1 result
raises LengthMismatch at collect). Left false (the default), the node
is a plain row-wise expression and the optimizer treats it — like
map_elements — as a value-and-shape barrier that no filter sinks across.
Expr::map_elements
Apply a host closure to each row of self — the single-input escape
hatch. Where the operators and methods above cover the documented
algebra, map_elements reaches past it: f receives the operand's
cell as a Scalar (a null cell as Scalar::Null) and returns the
output cell. label names the step in
explain / Show output — the function itself is opaque to
introspection, to rendering, and to the optimizer, which treats the node as
a barrier because it cannot see through the closure.
Building the node is total; f runs at evaluation, once per row, and
may raise (the error propagates from the consuming verb). The output
column's dtype is that of the first non-null Scalar the closure
returns, except that a closure returning both Int and Float cells
promotes the column to Float — the engine's Int → Float rule — rather
than nulling whichever type came second. A closure whose branches
return other mixed dtypes — Int with Decimal, or Decimal at two
scales — does not error: every cell the first-returned dtype cannot
hold lands as a null, the layer's deliberate tolerance (the strict
Series::from_scalars raises where the map path nulls; a mis-typed
branch shows up as nulls in the result, so check the dtype when a
closure has more than one return type). An all-null (or empty) result has
no such cell, so its dtype
falls back to self's own dtype, yielding an all-null (or empty)
column of that dtype rather than the Unsupported a bare Null literal
raises. Only the dtype is borrowed; the result's backend follows its own
content, as every computed column's does. The result is named after
self (its leftmost column), so with_alias renames it.
Use it inside with_columns / select / filter like any other
expression; the optimizer treats it as a value barrier (it can raise on
values), so no filter sinks across it.
Expr::max
Maximum of the operand over the evaluation scope (Series::max
semantics: NaN and nulls are skipped).
Expr::mean
Mean of the operand over the evaluation scope (Series::mean
semantics: NaN propagates, nulls are skipped).
Expr::median
Median of the operand over the evaluation scope. Nulls are skipped, and a
NaN propagates (like sum / mean; min / max are the order
statistics that skip it, and sort orders NaN as the largest value). An
all-missing scope reduces to null, and a non-numeric operand is
TypeMismatch. Always a Float (Int widens), so an even count averages
its two middles.
Expr::min
Minimum of the operand over the evaluation scope (Series::min
semantics: NaN and nulls are skipped).
Expr::mode
The most frequent non-null value over the evaluation scope — total over
every dtype, nulls skipped, keeping the operand's dtype. A tie keeps the
first-appearing value among the tied — one deterministic answer. An
empty / all-null scope reduces to null.
Expr::modulo
a.modulo(b) — remainder (a named method — % maps to no Expr
operator). Same-dtype Int / Int → Int carrying the dividend's sign
(-7 % 2 = -1); any Float operand promotes to Float, the remainder
keeping the dividend's sign there too (fmod — not the IEEE 754
remainder, whose quotient rounds to nearest).
Int modulo by zero yields a null cell (as for floor_div); Float
modulo by zero is NaN. A null on either side nulls the output cell; a
non-numeric operand raises TypeMismatch.
Expr::n_unique
Number of distinct values of the operand over the evaluation scope
(Series::n_unique semantics: a null cell counts as one distinct value,
every NaN is one bucket, -0.0 folds into +0.0). Total over every
dtype, never null — an Int.
Expr::ne
a.ne(b) — elementwise inequality (Bool column, null-propagating).
Expr::not
Kleene logical negation of a Bool expression (not(null) = null).
A method because MoonBit has no overloadable unary ~ / !.
Expr::pow
a.pow(b) — exponentiation, always Float (Int operands promote to
Double, like /): total for every base / exponent — a negative exponent,
a negative or fractional base, and overflow all resolve under IEEE 754
(0.0 ** 0.0 = 1.0, an out-of-range result is ±inf, an invalid one
NaN). A null on either side nulls the output cell; a non-numeric operand
raises TypeMismatch.
Expr::quantile
q-th quantile of the operand over the evaluation scope (default
interpolation=Nearest): the sorted non-null cells read at q * (m - 1),
so an even count picks a middle cell rather than averaging (Linear
gives the median's average). Nulls are skipped, a NaN propagates (the
median rule), an all-missing scope reduces to null, a non-numeric
operand is TypeMismatch, and a q outside [0, 1] is
InvalidOperation at evaluation — tree building stays total. Always a
Float (Int widens).
Expr::rank
Rank the operand's cells among its non-null cells: how~ picks the tie
rule (Average default — the mean of the tied ranks, a Float column;
Min / Max / Dense / Ordinal an Int column), descending~
flips the order, ties keep input order, null cells stay null, and a
NaN ranks past every other value (the total order sort uses).
Expr::rolling_max
Rolling maximum over a window_size-wide trailing window —
rolling_min with the order reversed.
Expr::rolling_mean
Rolling arithmetic mean over a window_size-wide trailing window —
always Float.
Expr::rolling_median
Rolling median over a window_size-wide trailing window — always
Float (Int widens), the two middles averaged on an even count.
Expr::rolling_min
Rolling minimum over a window_size-wide trailing window — NaN
skipped, the operand's dtype kept.
Expr::rolling_std
Rolling sample standard deviation (ddof = 1) over a window_size-wide
trailing window — Float; a single-value window has no sample
denominator and is null.
Expr::rolling_sum
Rolling sum over a window_size-wide trailing window — the shared
rolling contract, the statistic keeping the operand's dtype.
Expr::rolling_variance
Rolling sample variance (ddof = 1) over a window_size-wide trailing
window (spelled out — var is a reserved word).
Expr::round
a.round() — round to the nearest integer value, ties to even (banker's
rounding: 2.5 and 3.5 both round to 2 and 4, 0.5 → 0).
Float → Float; Int → Int unchanged (an integer is its own rounding).
±inf / NaN pass through and ±0.0 keeps its sign. A null stays null;
a non-numeric operand raises TypeMismatch. decimals (default 0)
rounds to that many decimal places — decimals=2 sends 1.005 to 1.0
or 1.01 as binary floating point dictates. A negative decimals clamps
to 0, and an Int column is the identity at any setting. So is a place
finer than the value's own resolution: round(decimals=20) returns
123456.789 unchanged rather than perturbing it by an ulp. (The other
rounding modes remain a deferred additive refinement; this is the
ties-to-even form.)
Expr::shift
Shift the operand's cells by n positions: a positive n moves values
down — each row reads the cell n rows above, SQL's LAG — a negative
one moves them up (LEAD), and n = 0 is the
identity. The n vacated edge slots take fill_value~ (a Scalar that
must type like the operand, Null by default for a plain gap). Nulls
are values: they shift with everything else, and a shifted-in gap is
fill_value, not the shifted-out neighbour's null. Building is total;
a mistyped fill surfaces as TypeMismatch at evaluation.
Expr::sign
a.sign() — -1 / 0 / +1 by sign, in the operand's own dtype (Int →Int, Float → Float). Float NaN stays NaN and ±0.0 gives 0.0. A
null stays null; a non-numeric operand raises TypeMismatch.
Expr::sin
a.sin() — the sine, always Float (Int promotes to Double, like
/): sin(±inf) / sin(NaN) are NaN under IEEE 754. A null stays
null; a non-numeric operand raises TypeMismatch.
Expr::sinh
a.sinh() — the hyperbolic sine, always Float (Int promotes to
Double, like /); an out-of-range result is ±inf under IEEE 754. A
null stays null; a non-numeric operand raises TypeMismatch.
Expr::sqrt
a.sqrt() — the square root, always Float (Int promotes to
Double, like /); a negative cell is NaN and sqrt(±0.0) = ±0.0
under IEEE 754. A null stays null; a non-numeric operand raises
TypeMismatch.
Expr::std
Sample standard deviation of the operand over the evaluation scope
(ddof = 1): NaN propagates through the mean, nulls are skipped, fewer
than two non-null cells reduce to null, and a non-numeric operand is
TypeMismatch. Always a Float.
Expr::str_contains
A Bool column that is true where the cell contains pattern.
literal defaults to true, matching pattern as a plain substring;
literal=false reads it as a POSIX regular expression (the core
engine's dialect, so character classes are [[:digit:]] / [[:alpha:]],
not the PCRE \d / \w, which raise). A regex is compiled once per
evaluation, so an invalid pattern raises InvalidOperation then. Null
cells stay null.
Expr::str_count_matches
Count the non-overlapping matches of the POSIX regular expression pattern
in each cell — an Int column, 0 where the pattern does not match. An
all-valid result rides the Numeric fast path, like str_len_chars. The
regex dialect and the invalid-pattern error are str_contains's; a null
cell stays null and a non-String operand raises TypeMismatch.
Expr::str_ends_with
A Bool column that is true where the cell ends with suffix.
Null cells stay null.
Expr::str_extract
Extract a substring matched by the POSIX regular expression pattern — a
nullable String column. group (default 0, the whole match)
selects a capture group; a cell that does not match, or whose chosen group
did not participate, yields null. The regex dialect and the
invalid-pattern error are str_contains's; a null cell stays null and a
non-String operand raises TypeMismatch.
Expr::str_len_bytes
The number of UTF-8 bytes in each cell of a String column, as an Int
(the encoded byte length): an ASCII character is 1, a é is 2, and a
supplementary-plane emoji is 4 (vs str_len_chars, which counts every
character as 1). Null cells stay null; an all-valid result rides the
Numeric fast path.
Expr::str_len_chars
The number of Unicode characters in each cell of a String column, as an
Int: a supplementary-plane character counts once, not as its two
UTF-16 code units. Null cells stay null; an all-valid result rides the
Numeric fast path like every computed numeric column.
Expr::str_pad_end
Right-pad each cell of a String column with fill until it is width
characters long — the mirror of str_pad_start.
Expr::str_pad_start
Left-pad each cell of a String column with fill until it is width
characters long. A cell already at least width characters is
unchanged (never truncated); null cells stay null. The width counts
characters, consistent with str_len_chars.
Expr::str_replace
Replace the first occurrence of pattern with value in each cell of a
String column. literal defaults to true (plain substring);
literal=false reads pattern as a POSIX regular expression (same
dialect and invalid-pattern error as str_contains), with value
inserted literally — no capture-group references yet. A cell without
a match is unchanged; null cells stay null.
Expr::str_replace_all
Replace every occurrence of pattern with value in each cell, the
all-occurrences mirror of str_replace — including its literal
parameter and default.
Expr::str_reverse
Reverse the Unicode characters of each cell of a String column. Surrogate
pairs are respected (reversal is by codepoint, not UTF-16 unit); null
cells stay null.
Expr::str_slice
Substring of each cell by character position.
offset is a 0-based character index; a negative offset counts from the
end (-2 starts two characters before the end). length is the number of
characters (omitted → to the end); a length of zero or less yields the
empty string. Both are clamped to the cell — an offset past the end gives
"", and a length past the end stops at the end — so it never raises on a
value. Character-based (surrogate pairs are never split), consistent with
str_len_chars; a null cell stays null and a non-String operand raises
TypeMismatch.
Expr::str_split_get
The index-th field of each cell split on the literal separator sep, as a
nullable String. index is 0-based; a cell with fewer than
index + 1 fields (or a negative index) yields null. "a,b,c" split
on "," at index 1 is "b". Null cells stay null. An empty separator
splits into single characters (index 0 of "abc" is "a") — a deliberate
spelling of the underlying split (no leading empty field).
Expr::str_starts_with
A Bool column that is true where the cell starts with prefix.
Null cells stay null.
Expr::str_strip_chars
Strip leading and trailing characters from every cell of a String column.
With chars omitted, the default set is the Unicode White_Space
property (ASCII whitespace plus NBSP, the narrow no-break space, the
ideographic space, …); with chars given, every character in that
string is a strip target (order and repeats do not matter). Null cells
stay null.
Expr::str_to_lowercase
Lowercase every cased letter of a String column — the case mirror of
str_to_uppercase: default conversion, expansions and all (İ
lowercases to i + combining dot above).
Expr::str_to_uppercase
Uppercase every cased letter of a String column through the Unicode
default case conversion: the simple one-to-one mappings (é → É,
Greek and Cyrillic across their alphabets) plus the SpecialCasing
expansions, so ß uppercases to SS and the fi ligature to FI — a
cell's length can grow. The locale-conditional rules are deliberately
absent: this is the default conversion, which carries no locale (the
Turkish dotless-i rules stay a caller's rewrite). Characters with no
case mapping (CJK, emoji, digits, …) pass through. Null cells stay
null, the result keeps the operand's column name, and a non-String
operand is a TypeMismatch at evaluation. The leading method
of the string namespace.
Expr::str_zfill
Left-pad each cell of a String column with '0' until it is width
characters long — like str_pad_start('0') but sign-aware: a
leading '+' / '-' keeps its place and the zeros are inserted after
it ("-5" to width 4 is "-005", not "00-5"). A cell already at
least width characters is unchanged (never truncated); null cells
stay null. The width counts characters, consistent with
str_len_chars.
Expr::sum
Sum of the operand over the evaluation scope (whole frame, or one group
under agg). Inherits Series::sum semantics: NaN propagates,
nulls are skipped, non-numeric operands are TypeMismatch.
Expr::tan
a.tan() — the tangent, always Float (Int promotes to Double,
like /); tan(±π/2) is finite only as rounded input dictates and
tan(±inf) / tan(NaN) are NaN under IEEE 754. A null stays null; a
non-numeric operand raises TypeMismatch.
Expr::tanh
a.tanh() — the hyperbolic tangent, always Float (Int promotes
to Double, like /), total under IEEE 754 (tanh(±inf) = ±1). A null
stays null; a non-numeric operand raises TypeMismatch.
Expr::unique_counts
How many times each cell's own value occurs in the column — an Int
per cell, keyed by the shared distinct normalisation (NaN one bucket,
-0.0 folded, a null its own bucket: a null cell reports the null
count). Total over every dtype.
Expr::variance
Sample variance of the operand over the evaluation scope (ddof = 1); the
square of std, with the identical null / NaN / dtype rules. Always a
Float. Spelled variance because var is a reserved MoonBit word (the
with_alias / .land() situation).
Expr::with_alias
Name the result column ((col("revenue") - col("cost")).with_alias("profit")). Without an alias, an expression is named after
its leftmost column reference, or "literal" for a column-less tree.
Called with_alias — alias itself is a MoonBit reserved word.
WhenThen
pub struct WhenThen {
// private fields
}First step of the conditional chain
when(cond).then(a).otherwise(b) — holds the Bool condition until
then supplies the matching branch. Constructible only through when,
which is a pub function and so cannot return a priv type — that, and
nothing else, is why the struct is pub. Its field is private, so the only
thing a caller can do with a WhenThen is call then.
WhenThen::then
Supply the branch taken where the condition is true.
WhenThenElse
pub struct WhenThenElse {
// private fields
}Second step of the conditional chain — condition plus then branch,
waiting for otherwise to complete the expression. Same private-field
rationale as WhenThen: the only move is otherwise.
WhenThenElse::otherwise
Supply the branch taken where the condition is false, completing the
conditional as a Ternary expression node.
col
Reference a column by name, for the operator call shape
col("a") + col("b"). The name resolves at evaluation time —
ColumnNotFound then if the frame has no such column; building the
reference itself is total. A free function, like the lit* family — the
facade re-exports it.
Example
test "col: renders as a reference" {
inspect(col("qty").to_string(), content="col(qty)")
}cols
Build a column-reference list from names: cols(["a", "b"]) is exactly
[col("a"), col("b")]. The ergonomic shorthand for the common case of
projecting (or dropping) several existing columns by name through the
expression verbs — df.select(cols(["a", "b"])) reads almost like the
names-only projection it replaces. Each name resolves at evaluation
time, exactly like col; building the list is total.
Example
test "cols: shorthand for the reference list" {
debug_inspect(
cols(["a", "b"]).map(e => e.to_string()),
content="[\"col(a)\", \"col(b)\"]",
)
}lit
Embed a literal Scalar. At evaluation it becomes a length-1 column
broadcast against its siblings. Prefer the typed shorthands
(lit_int / lit_float / lit_str / lit_bool), which avoid
spelling the Scalar variant at call sites.
Example
test "lit: embeds any Scalar" {
inspect(lit(@types.Scalar::Int(3L)).to_string(), content="3")
}lit_bool
Bool literal.
Example
test "lit_bool: renders bare" {
inspect(lit_bool(true).to_string(), content="true")
}lit_float
Float literal.
Example
test "lit_float: whole values keep their point" {
inspect(lit_float(2.0).to_string(), content="2.0")
}lit_int
Int literal (64-bit, like every MoonFrame integer cell).
Example
test "lit_int: renders bare" {
inspect(lit_int(5L).to_string(), content="5")
}lit_series
Embed a pre-materialised Series as a literal column, so a ready-made
column joins a pipeline beside the declarative col(...) ... expressions
(df.with_columns([lit_series(s), (col("a") + col("b")).with_alias("c")])).
At evaluation the series is used as-is: a length-1 series broadcasts over
the evaluation height (like a scalar lit), a series whose length matches
the frame supplies one cell per row, and any other length raises
LengthMismatch. The result column keeps the series' own name unless
with_alias overrides it — so with_columns([lit_series(s)]) adds, or
in-place replaces, a column named s.name(). A free function (the argument
is a Series, not an Expr), like the lit_* family and map_many.
Building the node is total; the length check happens at evaluation, in
frame.
Example
test "lit_series: names its column after the series" {
let s = @series.Series::from_ints("score", [1, 2])
inspect(lit_series(s).output_name(), content="score")
}lit_str
String literal.
Example
test "lit_str: renders quoted" {
inspect(lit_str("ab").to_string(), content="\"ab\"")
}map_many
Apply a host closure across several input columns, row by row — the
multi-input escape hatch, and the reified replacement for the original
closure filter predicate: f is handed one Scalar per input
in inputs order (null cells as Scalar::Null) and is called for every
row, so a row predicate is a map_many(..., f) returning a Bool. A
free function rather than a method (there is no single self); inputs
may mix columns, literals, and aggregations, the length-1 results
broadcasting over the row count. Same opacity, totality, dtype
inference, naming (after the leftmost input), and value-barrier rules as
map_elements — with the dtype fallback reading the leftmost input,
whatever it is, so only an empty inputs leaves an all-null result with no
witness and raises Unsupported. The inputs array is copied, so mutating
it after construction cannot alter the built expression.
Example
test "map_many: drops to a host closure" {
let total = map_many(label="total", [col("a"), col("b")], cells => {
@types.Scalar::Int(cells[0].as_int() + cells[1].as_int())
})
inspect(total.to_string(), content="map(\"total\", [col(a), col(b)])")
}when
Open a conditional expression: when(cond).then(a).otherwise(b)
evaluates to a where cond is true, b where it is false, and
null where cond is null. The chain is the only construction route, so
a conditional is complete by the time it becomes an Expr.
Example
test "when: the chain is the only construction route" {
let tagged = when(col("qty").gt(lit_int(5)))
.then(lit_str("big"))
.otherwise(lit_str("small"))
inspect(
tagged.to_string(),
content="when((col(qty) > 5)).then(\"big\").otherwise(\"small\")",
)
}Install
Download zipA lightweight DataFrame and tabular-data library for MoonBit
dataframedata-analysiscsvtabular
Apache-2.0
Updated 6 days ago
160 downloads