ddn.df.reshape

The reshape layer of ddn.df: pivot and unpivot (ADR-2026-10-24-20).

Both reshapes are eager-only - a pivot's output schema is a function of the data, which no lazy plan knows before the input is examined; lazy users collect() first (disclosed, never silent). The implementation reuses the grouping machinery (first-appearance group order, row lists), the aggregation kernels of the groupby layer (their empty-list semantics - sum/count 0, first/last/min/ max/mean null - ARE the pivot missing-cell policy) and the cast layer; no new computation path exists here.

Every ambiguous case has a defined, fail-loud outcome: duplicate cells error unless an aggregate is chosen, generated names colliding with index columns error, heterogeneous unpivot values reject instead of stringifying (the numeric join lattice of ADR-2026-10-24-19 promotes; everything else errors naming the pair). The output shape is discovered before any cell is written - one sized pass, no partial garbage.

Copyright

License

BSD-3-Clause

enum PivotAgg

fn duplicateCell isSignedKind joinValueDtypes onNamesOf pivot scalarText unpivot

Types 1

enumPivotAgg

The duplicate-cell policy of pivot (ADR-2026-10-24-20).

NONEDuplicates error (no silent pick); unique cells pass through, missing cells are null.

FIRSTThe first value of the cell, in row order.

LASTThe last value of the cell, in row order.

SUMThe sum, in the promoted dtype (empty cells 0).

MEANThe arithmetic mean (FLOAT64, FLOAT32 for FLOAT32; empty null).

MINThe minimum, total order on floats (empty null).

MAXThe maximum, total order on floats (empty null).

COUNTThe non-null count (empty cells 0; Polars' `len`).

Functions 7

DataFrame pivot(DataFrame df,  string[]  index,  string on,  string[]  values,
       PivotAgg agg =  PivotAgg.NONE)

Pivots the frame: the distinct values of `on` become output columns (first-appearance order), the distinct `index` tuples become output rows (first-appearance order), and the cells hold the `values...

private fn

DataFrameException duplicateCell(DataFrame df,  string[]  index,
       size_t[]  idxReps,  size_t g,  string on,  string onName,  size_t n)

DataFrame unpivot(DataFrame df,  string[]  valueColumns,
       string[]  indexColumns = [],  string variableName =  "variable",
       string valueName =  "value")

Unpivots the frame: the `valueColumns` stack into `variableName`/`valueName` pairs (value-column outer, input row inner), the `indexColumns` repeat per stacked column, and every other column is dro...

private fn

DataType joinValueDtypes(DataType a,  string an,  DataType b,
       string bn)

Joins two stacked value dtypes: identical dtypes stay; numeric dtypes join in the ADR-2026-10-24-19 lattice (all-integer INT64 with exact widening, any float FLOAT64, UINT64 meeting a signed intege...

private fnbool isSignedKind(Kind k) @safe pure nothrowReturns: whether the kind is a signed integer kind.

private fnstring[] onNamesOf(Series distinct)Renders the distinct on-values to their output column names: the CSV cell renderers (decimal integers, shortest-round-trip floats, `true`/`false`, strict temporals, strings as-is), null rendering t...

private fnstring scalarText(Series one)Renders the first value of a one-row STRING/numeric/temporal column to text (the duplicate-cell error's key text).