Enum Column 

pub enum Column {
    F64(Buffer<f64>),
    F32(Buffer<f32>),
    Bool(Buffer<bool>, Validity),
    I64(Buffer<i64>, Validity),
    I32(Buffer<i32>, Validity),
    Str(StrBuffer, Validity),
    Datetime(Buffer<i64>),
}

A typed, contiguous column of values. The value buffer is a Buffer — owned (Arc-shared, cheap clone, copy-on-write mutation) or a zero-copy borrow of foreign (Arrow / NumPy) memory.

Variants

F64(Buffer<f64>)

64-bit floats; NaN denotes missing.

F32(Buffer<f32>)

32-bit floats (narrow storage); NaN denotes missing.

Bool(Buffer<bool>, Validity)

Booleans (comparison / signal results); Validity marks missing cells.

I64(Buffer<i64>, Validity)

64-bit signed integers; Validity marks missing cells.

I32(Buffer<i32>, Validity)

32-bit signed integers (narrow storage); Validity marks missing cells.

Str(StrBuffer, Validity)

UTF-8 strings; Validity marks missing cells.

Datetime(Buffer<i64>)

Datetimes as i64 nanoseconds since the Unix epoch (UTC-naive).

Implementations

impl Column

pub fn to_datetime(&self) -> Result<Column>

Parse this column into a Column::Datetime (epoch ns). Str cells are parsed via datetime::parse_ns; an already-Datetime column is shared back (cheap). Errors on an unparseable cell or an unsupported dtype.

pub fn to_datetime_tz(&self, tz: Tz) -> Result<Column>

Parse a string column to a UTC Datetime column, interpreting naive strings in tz (offset-aware strings are absolute; an existing Datetime column is already UTC and returned as-is). The tz is then attached to the index (storage stays UTC).

pub fn epoch_to_datetime(&self, unit: &str) -> Result<Column>

Interpret a numeric (epoch) column as a UTC Datetime column, scaling by unit ("s" / "ms" / "us" / "ns"). Float epochs are truncated to the whole unit (matching a NumPy / pandas astype('datetime64[unit]') cast). The robust ingestion path for exchange APIs that return numeric timestamps.

pub fn epoch_to_datetime_rounded(&self, unit: &str) -> Result<Column>

Like epoch_to_datetime but rounds float epochs to the nearest nanosecond, preserving sub-unit fractions (matching pandas.to_datetime(..., unit=...)). Identical for integer columns.

pub fn cast(&self, to: DType) -> Result<Column>

Cast to another dtype (best-effort, pandas astype-like). A no-op when already the target dtype.

impl Column

pub fn require_numeric(&self) -> Result<()>

Error if this column is not numeric (float / int / bool — bool acts as 0/1). The guard for the numeric-only operations (arithmetic, reductions): a Str / Datetime column would funnel through to_f64_vec to NaN (str) or a quantized epoch (datetime), which the API contract (C4) forbids as a silent lossy conversion.

pub fn binary(&self, other: &Column, op: BinOp) -> Result<Column>

Binary + - * against other, dtype-preserving via binary_supertype (int ∘ int → i64, else f64). bool ∘ bool is logical, matching pandas: + is OR, * is AND, - is an error (numpy disallows bool subtraction); bool ∘ number promotes (bool acts as 0/1). Wrapping int ops match pandas overflow. Equal lengths assumed.

pub fn div(&self, other: &Column) -> Result<Column>

True division self / other (pandas /): always float. bool / bool is an error, matching pandas (division is not defined on bool).

pub fn floordiv(&self, other: &Column) -> Result<Column>

Floor division self // other (pandas //), dtype-preserving like pandas: int // int stays integer (the supertype, exact even past 2^53) unless a present divisor is 0, in which case the whole result is float64 (inf / -inf / nan) — exactly how pandas computes it; anything involving a float is float64. NA in either operand propagates. bool // bool is an error, like true division.

pub fn compare(&self, other: &Column, op: CmpOp) -> Result<Column>

Element-wise comparison (pandas == != < <= > >=) producing a non-nullable bool mask (decision ②): str / datetime / bool compare by their native value (NOT through the to_f64_vec funnel, which maps str to NaN and loses datetime precision), numeric kinds compare as f64. A missing slot (either side NA) follows IEEE — != is true, every other op false, matching the existing numeric comparison. Comparing two incompatible kinds (e.g. str vs a number) is a VolasError::DType. Equal lengths assumed.

pub fn logical(&self, other: &Column, op: BoolOp) -> Column

Three-valued logical and / or / xor (pandas & / | / ^), Kleene semantics: a present false makes and false and a present true makes or true even when the other side is missing; otherwise a missing operand yields NA. A non-bool operand is read as x != 0 (present). Equal lengths.

pub fn not(&self) -> Column

Logical NOT (pandas ~), propagating missing (NA in -> NA out). A non-bool column is read as x != 0 first.

pub fn sum(&self) -> Scalar

Sum, dtype-preserving (pandas): a float column -> float, int/bool -> i64 (bool counts trues). Computed natively (i64 in i64, exact past 2^53).

pub fn prod(&self) -> Scalar

Product, dtype-preserving (float -> float, int/bool -> i64).

pub fn extreme(&self, want_max: bool) -> Scalar

Minimum (want_max = false) / maximum, dtype-preserving (float -> float, int -> i64, bool -> bool). Empty / all-missing -> F64(NaN).

impl Column

pub fn slice(&self, start: usize, end: usize) -> Column

A contiguous [start, end) slice (a fresh buffer).

pub fn take(&self, idx: &[usize]) -> Column

Gather the given positions into a new column (fancy indexing).

pub fn take_optional(&self, idx: &[Option<usize>]) -> Column

Gather optional positions into a new column of the SAME dtype: Some(i) reads row i, None is a missing cell (dtype-preserving NA — int/bool/str grow a validity hole, float NaN, datetime NaT). Backs the window first / last aggregations.

pub fn count(&self) -> usize

Number of present (non-missing) values (pandas count): len - null_count, reading the validity for every dtype (a float NaN, an int/bool/str NA, a datetime NaT).

pub fn nunique(&self) -> usize

Number of distinct present values (pandas nunique, dropna=True).

pub fn unique_indices(&self) -> Vec<usize>

First-appearance index of each distinct value (pandas unique order), including one missing slot if the column has any NA — so takeing these indices yields the distinct values with a single NA where present.

pub fn argsort(&self, ascending: bool) -> Vec<usize>

Indices that sort the column (pandas sort_values), stable, with every missing value placed last regardless of ascending (pandas na_position = 'last'). Present values compare per dtype (float by value, str lexically).

pub fn arg_extreme(&self, want_max: bool) -> Option<usize>

Position of the maximum (want_max) or minimum present value, dtype-aware via cmp_at — numeric by value, str lexically, datetime by raw i64 (so sub-256ns ordering survives, unlike the to_f64_vec funnel which collapses it past 2^53). Ties keep the FIRST occurrence (pandas idxmax/idxmin). None if every value is missing. The typed basis of idxmax / idxmin / min / max.

pub fn cum_extreme(&self, want_max: bool) -> Result<Column>

Cumulative running extreme (pandas cummax if want_max, else cummin), dtype-aware and dtype-preserving via cmp_at: numeric by value, str lexically, datetime by instant. A present cell takes the running extreme of the present values seen so far; a missing cell stays missing (skipped, not filled — pandas cummax([3, NA, 5]) == [3, NA, 5]). Built by gathering each output position from the cell that holds its running extreme (or itself, when missing).

pub fn rank(&self, method: RankMethod, ascending: bool, pct: bool) -> Vec<f64>

Order-based rank (pandas rank, 1-based, missing -> NaN), dtype-aware via cmp_at: numeric by value, str lexically, datetime by raw i64, bool by false < true. The result is always f64 (ties can average to x.5), so rank is order-based, not a numeric-arithmetic op.

pub fn append(&mut self, other: &Column) -> Result<()>

Append another column of the same dtype, copy-on-write (grows in place when the buffer is uniquely owned).

pub fn append_missing(&mut self, len: usize) -> Result<()>

Extend a stale computed column with placeholder missing values, avoiding a temporary one-row Column allocation on the live append path.

pub fn append_na(&mut self, len: usize)

Extend a plain (non-computed) column with len genuine missing values, dtype-preserving: float / datetime use their in-band sentinel (NaN / NaT), while int / bool / str grow the validity bitmap with len invalid bits. Used when a column is absent from an appended frame; a cached directive instead uses the cheaper [append_missing] placeholder, which fulfill overwrites.

pub fn scatter(&self, positions: &[usize], values: &Column) -> Result<Column>

Scatter values into self at positions — the single assignment primitive behind every surface (df.loc / iloc / at / iat = , Series setitem, and boolean-mask assignment; a scalar write passes a length-1 values, which broadcasts). It keeps self’s dtype and updates its validity: each written position takes the source’s presence, every other position keeps its own. The dtype rules are:

• a float target absorbs any numeric source (a missing source -> in-band NaN);
• an int target stays int — a present integral value is stored, a missing / NaN source marks the cell NA (no float widening, per the NA model), a present non-integral value is a lossy VolasError::DType;
• a Bool / Str / Datetime target requires a matching-kind source (else a DType error); a missing source marks the cell NA (NaT for datetime).

positions are assumed in bounds (callers validate the mask / index).

pub fn combine_at( &mut self, row: usize, op: CombineOp, src: &Column, src_row: usize, ) -> Result<()>

Fold src[src_row] into cell row in place, per op — the allocation-free core of the live tf-fold’s forming-bar update (the incremental dual of [crate::Agg::reduce] over the period). Writes through Buffer::make_mut, so it is O(1) on a uniquely-owned buffer (one copy-on-write after a slice). Only numeric / datetime columns are supported — Bool / Str return a DType error, and the caller (fold_append) falls back to the batch reduce for those.

Max / Min / Sum keep the destination’s validity (a forming aggregate is always present, matching the batch reduce’s all-valid result); Replace (period last) copies the source cell’s value AND validity.

pub fn equals(&self, other: &Column) -> bool

Value equality where NaN == NaN (pandas equals semantics), unlike the derived PartialEq (which uses IEEE NaN != NaN).

impl Column

pub fn cumsum(&self) -> Result<Column>

Cumulative sum (pandas cumsum, skipna), dtype-preserving (bool -> int64 counting trues). Missing values are skipped and stay missing (NA in → NA out).

pub fn cummax(&self) -> Result<Column>

Cumulative maximum (pandas cummax), dtype-preserving (bool running OR). Missing values are skipped and stay missing.

pub fn cummin(&self) -> Result<Column>

Cumulative minimum (pandas cummin), dtype-preserving (bool running AND). Missing values are skipped and stay missing.

pub fn cumprod(&self) -> Result<Column>

Cumulative product (pandas cumprod), dtype-preserving (bool -> int64). Missing values are skipped and stay missing.

pub fn abs(&self) -> Result<Column>

Element-wise absolute value (pandas abs), dtype-preserving. abs of a missing (NaN) stays missing; abs(i64::MIN) wraps to i64::MIN (pandas); a bool column is unchanged (abs(bool) == bool).

pub fn round(&self, decimals: i32) -> Result<Column>

Round to decimals places (pandas round), dtype-preserving: banker’s (half-to-even) for floats, and for ints an identity at decimals >= 0 or a banker’s round to the nearest power-of-ten multiple at negative decimals.

pub fn clip(&self, lower: Option<f64>, upper: Option<f64>) -> Result<Column>

Clamp to [lower, upper] (either bound optional), pandas clip. Stays in the column dtype when every present bound fits it losslessly; otherwise (an int column with a non-integral bound) promotes to float, matching pandas.

pub fn shift(&self, n: isize) -> Column

Shift values by n periods (pandas shift), dtype-preserving for every dtype (str included). Vacated cells become missing (NaN for float, volas.NA for int/bool/str, NaT for datetime); a shifted-in value keeps its own missingness.

pub fn diff(&self, n: isize) -> Result<Column>

Discrete difference x[i] - x[i-n] (pandas diff), dtype-preserving: the first n cells (the shift gap) are missing. diff is subtraction, so it inherits binary’s rules: int stays int (NA gap), bool-bool subtraction is unsupported, and str / datetime raise — a datetime difference is a timedelta64, the open O3 decision, not a float64-of-ns.

pub fn fillna(&self, value: f64) -> Result<Column>

Replace missing cells with the constant value (pandas fillna), dtype-preserving when value fits the dtype, else promoting an int column to float (a non-integral fill).

pub fn fill_dir(&self, forward: bool) -> Column

Forward-fill (forward = true, pandas ffill) or backward-fill (bfill) missing cells from the nearest present value in that direction, dtype-preserving; leading / trailing cells with no source stay missing.

pub fn select( &self, cond: &[bool], other: &Column, target: DType, ) -> Result<Column>

where / mask core: pick self where cond is true, else other, producing target dtype (the caller resolves keep-vs-promote so the fill’s value/type is accounted for). Picks i64 natively when target is I64 (no f64 round-trip, so large ints stay exact). Equal lengths assumed.

impl Column

pub fn f64(v: Vec<f64>) -> Column

Build an F64 column.

pub fn f32(v: Vec<f32>) -> Column

Build an F32 column.

pub fn i32(v: Vec<i32>) -> Column

Build an I32 column (all values present).

pub fn bool(v: Vec<bool>) -> Column

Build a Bool column (all values present).

pub fn i64(v: Vec<i64>) -> Column

Build an I64 column (all values present).

pub fn i64_with(v: Vec<i64>, validity: Validity) -> Column

Build an I64 column with an explicit validity (missing-aware).

pub fn i32_with(v: Vec<i32>, validity: Validity) -> Column

Build an I32 column with an explicit validity (missing-aware).

pub fn bool_with(v: Vec<bool>, validity: Validity) -> Column

Build a Bool column with an explicit validity (missing-aware).

pub fn str(v: Vec<String>) -> Column

Build a Str column (all values present).

pub fn str_with(v: Vec<String>, validity: Validity) -> Column

Build a Str column with an explicit validity (missing-aware).

pub fn datetime(v: Vec<i64>) -> Column

Build a Datetime column (epoch nanoseconds).

pub fn na_of(dtype: DType, len: usize) -> Column

An all-missing column of dtype with len rows — the dtype-preserving default other for where / mask (so a kept value stays in its dtype and a replaced one becomes NA, never an f64-funnel NaN).

pub fn len(&self) -> usize

Number of elements.

pub fn is_empty(&self) -> bool

Whether the column has no elements.

pub fn dtype(&self) -> DType

The logical dtype of the column.

pub fn is_valid(&self, i: usize) -> bool

Whether the value at i is present (not volas.NA). Each dtype reads its natural missing representation: a float NaN, an int/bool validity mask, or a datetime NaT (i64::MIN). i is assumed in bounds.

pub fn get_i64(&self, i: usize) -> i64

Read cell i as i64 (any integer / datetime / bool dtype; truncates a float, 0 for Str). The integer counterpart of Self::get_f64, for the in-place tf-fold’s combine on integer / datetime columns.

pub fn null_count(&self) -> usize

Count of missing (volas.NA) values.

pub fn as_f64(&self) -> Option<&[f64]>

Borrow the underlying f64 slice, if this is an F64 column.

pub fn as_bool(&self) -> Option<&[bool]>

Borrow the underlying bool slice, if this is a Bool column.

pub fn as_i64(&self) -> Option<&[i64]>

Borrow the underlying i64 slice, if this is an I64 column.

pub fn str_at(&self, i: usize) -> Option<&str>

The i-th string of a Str column as &str, if this is a Str column.

pub fn as_datetime(&self) -> Option<&[i64]>

Borrow the underlying epoch-ns slice, if this is a Datetime column.

pub fn to_f64_vec(&self) -> Vec<f64>

Materialize the values as f64 (bool -> 0.0/1.0, i64 / datetime -> as f64, str -> NaN). Used to feed indicator kernels, which operate on f64.

pub fn get_f64(&self, i: usize) -> f64

Value at position i coerced to f64, ignoring validity (a missing cell reads its raw placeholder). Used only by the logical-op coercion in bool_at; NumPy export goes through the validity-aware to_f64_vec.

pub fn to_f32_vec(&self) -> Vec<f32>

The column as f32 values (an F32 column directly; else converted).

Trait Implementations

impl Clone for Column

fn clone(&self) -> Column

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Column

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for Column

fn eq(&self, other: &Column) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Column