Module partition 

Partition-typed stdlib nodes — SRD 71 §“Functions that consume partitions”.

Each node takes a polydat::iteration::cursor_partition::Partition value (carried through Polydat wires as Value::Ext) via the polydat::derive_support::Ext combinator and projects it into the u64 ordinal space the rest of the workload expects. These are the canonical primitives for “use the active partition’s range in a per-cycle binding”:

• cardinality — partition size.
• start_of — partition’s lower bound (inclusive).
• end_of — partition’s upper bound (exclusive).
• idx_of — 0-based partition index.
• mod_in — modulo-mapped ordinal that stays inside the partition.
• at — bounds-checked offset into the partition.
• clamp_in — saturating projection into the partition.
• random_in — hash-mapped ordinal inside the partition, deterministic per seed.
• subdivide — split a partition into n near-equal sub-partitions.
• partitions — parse a string spec into a PartitionList.
• partition_count, partition_at — the length of a list and one of its partitions by position.

All of these are deterministic and JIT-friendly at the call site (the partition value is effectively-const for a scope activation, so the eval reduces to a small constant arithmetic expression).

Naming note: subdivide here takes a partition and returns sub-partitions. The numeric comprehension generator that yields evenly spaced values over a [start, end) interval is linear_starts(start, end, n) (with linear_steps as its inclusive fence-post sibling) — see SRD 18c.

Structs

At

at(p, i) — bounds-checked p.start_ord + i. Use when iteration is meant to consume each ordinal exactly once. Panics at eval time if i >= cardinality(p). Prefer mod_in for the wrapping case.

Cardinality

Number of ordinals in the partition.

ClampIn

clamp_in(n, p) — saturating projection into the partition. max(p.start_ord, min(n, p.end_ord - 1)). Unlike mod_in, values outside the partition saturate at the boundary rather than wrapping. Degenerate cardinality=0 returns the start.

CountOf

Total number of partitions in the list this partition was resolved as part of. 1 for a single-partition spec. The function spelling of the partition_count projection — pairs with idx_of for “i of n” labelling.

EndOf

Partition’s end ordinal (exclusive).

IdxOf

0-based position in the partition list.

ModIn

mod_in(n, p) = p.start_ord + (n mod cardinality(p)). Maps an arbitrary integer (typically a per-cycle ordinal) into the partition’s range, wrapping. Degenerate cardinality=0 returns the partition’s start ordinal.

PartitionAt

The i-th partition of a list, by position. Panics when i is out of range, like at does for ordinals.

PartitionCount

Number of partitions in a list.

Partitions

Parse a string spec into a PartitionList. The base extent for resolution comes from a constant arg (default 100, so pure-percentage specs produce partitions in [0, 100) ordinal space). Useful for constructing partition values inline when a cursor’s over clause needs an explicit list.

RandomIn

random_in(p, seed) — deterministic hash-mapped ordinal inside the partition: p.start_ord + hash(seed) mod cardinality(p). Same SplitMix64 entropy source as hash(...), so equal seeds always land on the same ordinal. Use for random-access patterns that must stay inside the active partition; prefer mod_in when sequential coverage matters. Degenerate cardinality=0 returns the partition’s start.

StartOf

Partition’s start ordinal (inclusive).

Subdivide

subdivide(p, n) — split a partition into n contiguous sub-partitions whose sizes differ by at most one ordinal. Indices restart at 0; base_extent propagates from the parent; the percentage fields interpolate the parent’s span. Boundaries match the */N spec tail token exactly (both route through the same splitter). Panics at eval time when n is 0 or exceeds the partition’s cardinality — every sub-partition must be non-empty.