Crate fp_types 

Foundational value-type abstractions for frankenpandas — the enums, structs, and free functions that every other crate (fp-columnar, fp-index, fp-frame, fp-io, …) consumes when representing scalar data, dtypes, missing values, and time deltas.

The types here intentionally stay tiny and dependency-light (serde, thiserror) so they can sit at the bottom of the workspace dep graph.

Core value types

• DType: the dtype enum — Null, Bool, Int64, Float64, Utf8, Categorical, Timedelta64, Datetime64, Period, Interval, Sparse. Drives column / series storage decisions across the workspace.
• Scalar: the per-cell value enum, parameterized by DType. Each variant holds the actual data (Int64(i64), Float64(f64), Utf8(String), …) plus the Null(NullKind) variant for missing values.
• NullKind: distinguishes the three pandas missing-value “flavors” — Null (Python None / SQL NULL), NaN (floating-point not-a-number), NaT (timedelta / datetime not-a-time). Scalar::Null(...) carries the kind so downstream code can preserve pandas semantics.
• SparseDType: descriptor for sparse-encoded dtypes (paired value dtype + fill value).

Time / duration types

• Timedelta: nanosecond-precision duration with arithmetic helpers (Timedelta::add, Timedelta::sub, Timedelta::mul_scalar, Timedelta::div_scalar, Timedelta::div_timedelta) that propagate NaT per pandas semantics. TimedeltaComponents breaks a timedelta into days/hours/minutes/seconds/nanos for display.
• Timestamp: nanosecond-precision wall-clock timestamp with optional timezone. Includes floor / ceil / round helpers and NaT propagation.

Dtype inference + casting

• infer_dtype: derive a DType from a slice of scalars (used during DataFrame construction).
• common_dtype: pandas-style dtype promotion for binary ops.
• cast_scalar / cast_scalar_owned: convert a scalar to a target dtype with explicit error reporting on impossible casts.

Missing-value helpers

Free fns matching pd.isna / pd.notna / pd.fillna / pd.dropna plus the nan* aggregations (nansum, nanmean, nancount, nanmin, nanmax, nanmedian, nanvar, nanstd) that mirror pandas’ missing-aware reductions.

Error reporting

Errors are explicit enums via thiserror: TypeError for dtype-related failures (incompatible-cast, no-common-dtype) and TimedeltaError for parse failures.

Structs

Interval

A bounded numeric interval between two f64 endpoints.

Period

A single pandas-style Period value.

SparseDType

Timedelta

TimedeltaComponents

Timestamp

A nanosecond-precision point in time, Unix-epoch anchored.

Enums

DType

IntervalClosed

Endpoint-inclusion policy for an Interval.

NullKind

PeriodFreq

Period frequency code. Matches pandas offset alias core set.

Scalar

TimedeltaError

TypeError

Functions

cast_scalar

Cast a scalar reference to a target dtype (clones only when conversion is needed).

cast_scalar_owned

Cast a scalar to a target dtype, taking ownership to avoid redundant clones when the value already has the correct type (AG-03: identity-cast skip).

common_dtype

count_na

dropna

fill_na

infer_dtype

interval_range_by_periods

Build periods equal-width intervals spanning [start, end].

interval_range_by_step

Build equal-step-width intervals spanning [start, end].

isna

isnull

nanall

nanany

nanargmax

Position (in the original slice) of the non-missing maximum.

nanargmin

Position (in the original slice) of the non-missing minimum.

nancount

nancummax

Cumulative maximum respecting null propagation.

nancummin

Cumulative minimum respecting null propagation.

nancumprod

Cumulative product respecting null propagation.

nancumsum

Matches np.nancumsum / pd.Series.cumsum(). Missing input positions pass through as Null(NaN) in the output; the running sum ignores those positions when accumulating.

nankurt

Excess sample kurtosis (Fisher’s definition, bias-corrected) over non-missing values.

nanmax

nanmean

nanmedian

nanmin

nannunique

Count of unique non-missing values.

nanprod

Product of non-missing values. Returns 1.0 for empty input (matching pandas).

nanptp

Peak-to-peak range of non-missing values (max − min).

nanquantile

Linear-interpolation quantile over non-missing numeric values.

nansem

Standard error of the mean over non-missing values.

nanskew

Sample skewness (bias-corrected, Fisher-Pearson) over non-missing values.

nanstd

nansum

nanvar

notna

notnull

period_range

Build periods consecutive Periods starting at start.