READMEihb2032/MoonFrame/types does not have a README file
#DataError
pub(all) suberror DataError {
ColumnNotFound(String)
DuplicateColumn(String)
TypeMismatch(TypeMismatchDetail)
LengthMismatch
IndexOutOfBounds(Int)
ParseError(ParseErrorDetail)
InvalidOperation(String)
IoError(String)
Unsupported(String)
NullInNonNullable(String)
} derive(Eq, Debug)Unified error type for all MoonFrame operations.
#DataError::message
Human-readable message describing the error.
#CellParseLocation
Identifies how a typed cell's 1-based source position is reported.
Row is used by CSV, Record by JSON arrays, and Line by NDJSON.
#CellParseLocation::equal
#CellParseLocation::not_equal
#ClosedInterval
Which endpoints an is_between range includes — Polars' closed.
Both (the default) is lo <= x <= hi; Left / Right open the other
end; None excludes both (lo < x < hi).
#ClosedInterval::not_equal
#DataType
Logical data type for a column.
Null is the dtype of a missing value, not of a column: it is what
Scalar::Null.dtype() reports, and so what a TypeMismatch's "expected T,
got Null" names when a null cell reaches a typed read. A hand-built Schema
may also carry it, but nothing materialises a column on it —
DataFrame::empty raises Unsupported for such a field, cast refuses it
as a target, and no reader infers it: an all-null probe window falls back
to String (see docs/type-inference.md).
Concrete columns always carry one of the other variants.
#DataType::is_bool
true only for the Bool variant.
#DataType::is_float
true only for the Float variant.
#DataType::is_integer
true only for the Int variant.
#DataType::is_numeric
true for Int and Float — both are usable in numeric reductions.
#DataType::is_string
true only for the String variant.
#Field
Column metadata: a name, the column's logical DataType, and a declared
nullable flag.
nullable = false is a declared constraint that DataFrame::from_rows
enforces: row data placing a Scalar::Null in such a column raises
NullInNonNullable(name). (DataFrame::empty builds 0-row columns, so it
can never violate the constraint.) The flag is never inferred from a
column's contents: the constructor's nullable default — and so
DataFrame::DataFrame and the IO readers — always sets nullable = true,
so a nullable = false field only ever originates from an explicit
Field::Field(..., nullable=false) in a caller-supplied schema.
Once declared, it travels with the cells it describes. Every operation that
moves a column carries its field rather than re-deriving one:
Field::rename (and so DataFrame::rename / rename_with, which change
nothing but the name), Schema::select / Schema::rename, the row-only
frame transforms that reuse their input's schema verbatim (head / tail
/ slice / filter / sort / unique / fill_null / …), and the
projections: a select or with_columns entry that is a bare col("x")
(or an aliased one, which carries the field renamed), every column drop
or select leaves in place, and the counter-prepending with_row_index.
A column replaced through with_columns takes the field of whichever
column now supplies its cells.
An operation that computes cells derives a fresh field instead, with the
constructor default: arithmetic, aggregations, cast, fill_null as an
expression, group_by(...).agg(...), join (an outer one introduces
nulls), and the summary frames (describe / null_count / sum / …).
The declaration was made about the input's cells, not about these.
That split is what keeps the flag honest without ever inspecting a column:
it is validated once, by from_rows, and thereafter only accompanies cells
it was validated against — the operations that carry it drop, reorder or
rename, and never introduce a value.
The fields are priv, so the struct is opaque outside this package: build
one through Field::Field(...) and read it through name() / dtype() /
nullable(). That is what actually keeps a future field additive — a
readable field is also matchable, and MoonBit requires a struct pattern
to name every field or carry .., so a public field's arrival would break
a caller's pattern exactly as a new pub(all) enum variant breaks a
match.
#Field::Field
Build a field. nullable defaults to true, the common setting for
inferred CSV / JSON columns; pass nullable=false to declare the
constraint DataFrame::from_rows enforces.
#Field::nullable
The declared nullable flag (see the type doc for how DataFrame::from_rows
enforces it).
#Field::rename
Return a copy of this field with a new name.
#NullOrder
Where missing cells go relative to non-missing ones. Missing means
either a Null slot (validity bit 0) or — for Float columns —
NaN. The plan specifies that NaN is treated identically to Null
for ordering, so callers don't need a separate knob.
#ParseErrorDetail
pub(all) enum ParseErrorDetail {
Message(String)
Cell(CellParseLocation, String, Int, DataType, String)
} derive(Eq, Debug)Structured details carried by DataError::ParseError.
#ParseErrorDetail::equal
#ParseErrorDetail::not_equal
#Scalar
A single cell value in a DataFrame.
Null represents a missing value. The as_* conversions raiseTypeMismatch(Expected(expected, got, "")) on a wrong dtype (got = Null for a null
cell). Comparisons raise TypeMismatch(...) on Null, or
TypeMismatch(Operation("compare", left, right)) on an incomparable non-null pair —
callers must check is_null() first or handle the error.
The Float variant carries a 64-bit Double; the Int variant carries
a 64-bit Int64. Use as_float for explicit access; Int is also
accepted via numeric promotion to Double.
#Scalar::as_bool
Bool cells return their value; other concrete variants and Null
raise TypeMismatch(Expected(...)).
#Scalar::as_float
Float cells return their Double; Int cells are promoted to
Double; other concrete variants and Null raise TypeMismatch(Expected(...)).
#Scalar::as_int
Int cells return their Int64; other concrete variants and Null
raise TypeMismatch(Expected(...)).
#Scalar::as_string
String cells return their value; other concrete variants and Null
raise TypeMismatch(Expected(...)).
#Scalar::dtype
The DataType corresponding to this value's variant.
#Scalar::eq
Equality between two Scalars. Two Nulls, or Null and a value,
raise TypeMismatch — callers must guard nullability explicitly. Mixed
numeric types (Int vs Float) compare exactly — the Int64 is not
promoted to Double, so two distinct values never collide above 2^53
(e.g. Int(9007199254740993) is not equal to
Float(9007199254740992.0), and Int64::MAX is not equal to the 2^63
Double a promotion would round it to). This is a deliberate departure
from Polars' Float64-supertype promotion, chosen for correctness. NaN
follows IEEE 754 (NaN == NaN is false).
#Scalar::gt
Strict greater-than, defined as other.lt(self) — same Null-raise and
ordering rules as lt. The delegation transposes the operands, so the
incomparable-dtypes diagnostic is issued here first, in the caller's
operand order — Int(1).gt(String("x")) reports "Int and String", not
the transposed pair eq / lt / lte would never produce.
#Scalar::gte
Greater-than-or-equal, defined as other.lte(self) — same rules as
lte, with gt's call-order diagnostic for an incomparable pair.
#Scalar::is_null
true only for the Null (missing-value) variant.
#Scalar::lt
Strict less-than. NaN follows IEEE 754: any comparison involving NaN
returns false. Null short-circuits to raise. Mixed Int-vs-Float
ordering is exact (no Int→Double promotion), so it never mis-orders
two distinct values across the 2^53 boundary — the same deliberate
departure from Polars as eq.
#Scalar::lte
Less-than-or-equal — eq or lt. Shares their Null-raise and exact
Int/Float comparison semantics.
#Schema
Ordered list of Fields describing a DataFrame's columns.
Construction always validates uniqueness of names; once built, a
Schema is guaranteed to have no duplicate column names.
The fields array is priv: build a schema with Schema::Schema and read a
copy via fields() / field_names(). External code cannot reach or
mutate the backing array, so a validated schema stays valid.
index is the name→position map behind index_of, and through it field /
select / rename. It is derived from fields and built in lock-step with
it, never separately: the constructors are the only writers, and each one
builds both. Uniqueness is what makes it total — every name maps to exactly
the position that carries it — so it is the same validation pass that
establishes both. A schema is immutable, so one scan at construction replaces
a scan per lookup: resolving c names against a c-column schema was O(c²)
while every resolution walked the array, which is the shape a wide select
or rename hits.
#Schema::Schema
Build a schema from a list of fields. raise DuplicateColumn(name) on
the first repeated name.
The input array is copied, so mutating fields after construction
cannot alter the schema or break the validated no-duplicates invariant.
The type's own constructor, like Field::Field — the spelling every
canonically-constructed type in MoonFrame uses.
#Schema::field
Return the Field for name, or raise ColumnNotFound(name).
#Schema::field_at
Return the Field at position i, or raise IndexOutOfBounds(i).
#Schema::field_names
Column names in declaration order.
#Schema::fields
Return a snapshot of the schema's fields.
A fresh array is returned so callers cannot mutate the schema in place
and break the "no duplicate names" invariant enforced by Schema::Schema.
#Schema::index_of
The index of the column named name, or raise ColumnNotFound(name).
O(1) — the name index is built once, when the schema is.
#Schema::is_empty
true when the schema has no columns.
#Schema::rename
Rename old_name to new_name. Raises if old_name is missing or
new_name collides with another existing column.
#Schema::select
Project a sub-schema by name, preserving the order of names. Missing
names raise ColumnNotFound(name); duplicates inside names
raise DuplicateColumn(name).
#SortOrder
Direction of a sort key. Asc sorts smaller values first, Desc
sorts larger values first. The convention applies to every dtype:
Int / Float use numeric ordering, Bool uses false < true,
String uses lexicographic comparison.
#TypeMismatchDetail
Structured details carried by DataError::TypeMismatch.
#TypeMismatchDetail::equal
#TypeMismatchDetail::not_equal
A lightweight DataFrame and tabular-data library for MoonBit
dataframedata-analysiscsvtabular
0.6.0
Apache-2.0
Updated 17 days ago
47 downloadsDependencies
- moonbitlang/x0.4.47
- moonbit-community/NyaCSV0.3.3
- moonbitlang/quickcheck0.14.0