Module eval 

Expression evaluator. Given a parsed Expr, a Row, and the row’s column schema, produce a Value. v0.4 implements:

• literals
• column lookups (bare and qualified t.col)
• unary minus / NOT
• binary arithmetic, comparison, AND, OR
• numeric widening (Int → BigInt → Float) at evaluation time
• SQL three-valued logic for NULL:
  • any arithmetic / comparison op with a NULL operand → NULL
  • TRUE OR NULL → TRUE, FALSE OR NULL → NULL,
  • FALSE AND NULL → FALSE, TRUE AND NULL → NULL,
  • NOT NULL → NULL

v0.4 deliberately does not implement: function calls, string concatenation, IS NULL / IS NOT NULL, BETWEEN, IN, etc. Those come later.

Modules

compiled

Compiled expressions — PG’s ExprState idea (cut 30, extracted from eval.rs; v7.32 perf knife D / architecture v2 P1).

Structs

EvalContext

Resolution context for evaluating a single row. table_alias is the alias (or table name) callers should accept as the qualifier on a column ref — e.g. FROM users AS u makes u.name valid and rejects other.name.

RenderStyle

XactView

v7.38 (T24) — the transaction-id surface PG’s txid_* family exposes. SPG’s writer versions ARE its transaction ids (row_header::next_version), so no separate xid counter is needed — this is the bridge U22 was waiting on.

Enums

DateOrder

DateStyleKind

EvalError

IntervalStyleKind

SequenceOp

v7.17.0 — sequence operation requested by an Expr eval.

Functions

cast_to_vector

Parse a Value::text("[1.0, 2.0, 3.0]") into a Value::vector(..). Mirrors pgvector’s '[..]'::vector cast. NULL casts as NULL.

cast_value

PG-style expr::TYPE coercion. NULL always casts as NULL.

days_from_civil

Inverse of civil_from_days — converts (year, month, day) to days since 1970-01-01. Out-of-range months / days saturate.

decode_tsquery_external

v7.12.0 — decode PG external form 'foo' & 'bar' | !'baz' into a TsQueryAst. v7.12.0 supports the canonical to_tsquery surface: single-quoted lexemes, & / | / !, parens, and phrase <N>. Bare lexemes are accepted too. Full plainto_tsquery / websearch_to_tsquery arrive in v7.12.1.

decode_tsvector_external

v7.12.0 — decode PG external form 'word':1,2A 'other':3 into a Vec<TsLexeme>. Lexemes are sorted ascending by word (with duplicates merged on positions) so the output matches the engine invariant. Empty input yields an empty vector.

eval_expr

format_bigint_array

v7.11.14 — render a BIGINT[] in PG’s external array form ({1,2,NULL}).

format_bool_array

v7.37.5 γ — render a BOOL[] in PG external form. PG uses single-letter t / f for booleans (matching the scalar wire convention).

format_bytea_array

v7.37.5 γ — render a BYTEA[] in PG external form. Each non-NULL element is \\x<hex> (the PG hex output form) and is double-quoted because the leading backslash is a PG array escape character.

format_bytea_hex

format_date

Render a Date (days since epoch) as YYYY-MM-DD. Negative values for pre-1970 dates render with a leading - on the year.

format_date_array

v7.37.5 γ — render a DATE[] in PG external form. Each non-NULL element is rendered as YYYY-MM-DD.

format_date_array_styled

Styled array renderers — {elem,…} with per-element styled text.

format_date_styled

format_date under a DateStyle. PG18 shapes: ISO 2024-03-15 · German 15.03.2024 · SQL 03/15/2024 (DMY 15/03/2024) · Postgres 03-15-2024 (DMY 15-03-2024). YMD field order affects only ISO-irrelevant styles’ INPUT; output falls back to the MDY arrangement (as PG does).

format_float

v7.17.0 Phase 3.P0-35 — PG money canonical text form, en_US PG float8out — the shortest round-trip decimal, rendered in scientific notation when the base-10 exponent is < -4 or > 14 (matching float.c’s choice), otherwise fixed. Learned from read01 float.c study: PG switches to 1e+15 / 1e-05 where SPG used to spell every digit (1000000000000000000000000000000). The exponent is read from Rust’s {:e} (exact — avoids log10 rounding at powers of ten) and reformatted to PG’s e±NN (sign always shown, ≥ 2 digits). Infinities / NaN / signed zero match float8out too.

format_float_array

v7.37.5 γ — render a FLOAT[] / DOUBLE PRECISION[] in PG external form. PG renders floats via the engine’s existing f64 → text path so this just calls Rust’s default Display.

format_float_array_styled

format_float_styled

PG float8out under extra_float_digits: >= 1 → shortest round-trip (format_float); <= 0 → %.{15+n}g.

format_int_array

v7.11.14 — render an INT[] in PG’s external array form ({1,2,NULL}). Integer payloads never need quoting. NULL elements use the literal token NULL.

format_interval

Render an Interval { months, days, micros } in a PG-ish shape. The output mirrors psql’s text format: years/months from the months part, days from its own dimension (no carry from micros — this is the PG-canonical separation so '1 day' ≠ '24 hours'), HH:MM:SS[.frac] from micros. v7.37.5 β added the days parameter for PG byte-equal; micros may still carry hours ≥ 24 (PG keeps the unnormalised form on the wire).

format_interval_array

v7.37.5 β-P4 — render an INTERVAL[] in PG’s external array form. Each non-NULL element is double-quoted because interval text contains spaces (1 day) and colons (24:00:00) that would confuse the comma-separated parse: {"1 day","24:00:00",NULL}. Inner " doesn’t occur in interval text so no escaping is needed; backslashes likewise can’t appear.

format_interval_array_styled

format_interval_styled

format_interval under an IntervalStyle (PG18 differential truth):

format_money

locale: $N,NNN.CC, negative → -$1.23. Mirrors PG’s cash_out for lc_monetary = 'en_US.UTF-8'.

format_money_array

v7.37.5 ζ-A — render a MONEY[] in PG external form. Each element is the canonical format_money output; the array wrapper is {...} with NULL elements as the literal token NULL.

format_numeric

format_numeric_array

v7.37.5 γ — render a NUMERIC[] in PG external form.

format_numeric_kind

Render a Numeric { scaled, scale } as its decimal text form. Negative scaled prepends - to the absolute value’s digits; the integer / fractional split is by character count, padding the fractional side with leading zeros to exactly scale chars. v7.38 (read01, T6) — render a NUMERIC honoring its special kind. Finite uses format_numeric; the specials render PG’s full-word spellings.

format_real

v7.38 (read01, T-float4) — PG float4out: the f32 shortest round-trip, in fixed-point for decimal exponents in -4..=5 and scientific otherwise (a tighter window than float8’s -4..=14, so 12345678::real = 1.2345678e+07 while 12345678::float8 stays 12345678).

format_real_styled

PG float4out under extra_float_digits: >= 1 → shortest round-trip (format_real); <= 0 → %.{6+n}g.

format_smallint_array

v7.37.5 γ — render a SMALLINT[] in PG external form.

format_text_array

v7.10.9 — render a TEXT[] in PG’s external array form ({a,b,NULL}). Elements containing whitespace, commas, quotes, or braces get double-quoted with \\ / \" escapes. NULL elements use the literal token NULL. Public so the wire layer can produce the canonical text-mode encoding.

format_time

v7.17.0 Phase 3.P0-32 — PG TIME canonical text form HH:MM:SS[.ffffff]. Mirrors PG time_out. Trailing zeros in the fractional component are stripped — 12:00:00.500000 renders as 12:00:00.5 to match PG’s text output.

format_timestamp

format_timestamp_array

v7.37.5 γ — render a TIMESTAMP[] (with_tz=false) or TIMESTAMPTZ[] (with_tz=true) in PG external form. Each non-NULL element is double-quoted because the canonical timestamp text contains a space (2024-06-01 12:00:00) that would otherwise split on commas wrong.

format_timestamp_array_styled

format_timestamp_styled

format_timestamp under a DateStyle. German/SQL prepend their date form; Postgres style is the asctime-like Dow Mon DD HH:MM:SS[.f] YYYY (DMY: Dow DD Mon …).

format_timestamptz

Render a Timestamp (microseconds since epoch) as YYYY-MM-DD HH:MM:SS[.fff...]. Trailing-zero fractional digits are dropped; a whole-second value has no fractional part. v7.15.0 — PG-canonical TIMESTAMPTZ wire format. Storage is the same i64 microseconds UTC as TIMESTAMP, but the canonical PG text output appends the session’s UTC-offset suffix (+00 for the default UTC session, the form pg_dump emits). Mailrs round-8 acceptance criterion: SELECT col FROM tstz should round-trip to a literal that re-INSERTs without semantic drift.

format_timestamptz_at

v7.38 (T-tstz Phase 2) — render a UTC instant in a fixed-offset zone: shift the wall clock by offset_micros, then append PG’s offset suffix (+09, -05, +05:30, +00). Minutes are shown only when non-zero, matching PG. UTC (offset_micros == 0) reproduces the old +00 output byte-for-byte.

format_timestamptz_styled

format_timestamptz under a DateStyle for the UTC session: ISO keeps the +00 offset suffix; the other styles append the zone NAME ( UTC), as PG does.

format_timestamptz_tz

v7.39 (tz epic) — the session-timezone-aware renderer: shift by the per-value offset; ISO appends the numeric offset (+09, +05:45), the other DateStyles append the zone designation — a named zone’s abbreviation (JST, EDT), a fixed offset’s numeric form, or UTC (all PG18-differential).

format_timetz

v7.17.0 Phase 3.P0-34 — PG TIMETZ canonical text form HH:MM:SS[.ffffff]±HH[:MM]. Mirrors PG timetz_out. The offset uses ±HH for whole-hour offsets and ±HH:MM for sub-hour offsets (matching PG’s “minimal display” rule).

format_tsquery

v7.12.0 — render a tsquery in PG’s external form. Operator precedence: ! > & > |. Phrase distance shown as <N>.

format_tsvector

v7.12.0 — render a tsvector in PG’s external form: 'lex':1,2A 'word':3 (single-quoted lexemes, optional :positions, optional weight letter A/B/C/D per position). Lexemes already arrive sorted + deduped from the engine. Used by the wire layer (OID 3614) and by SELECT-text output.

format_uuid_array

v7.37.5 γ — render a UUID[] in PG external form. UUID text is the canonical lowercase 8-4-4-4-12 hyphenated form; no quoting needed (hex + dashes, no spaces / commas).

gen_random_uuid_bytes

v7.17.0 — generate a RFC 4122 v4 (random) UUID. Layout: 16 random bytes with the version nibble (high nibble of byte 6) pinned to 0100 (= 4) and the variant top bits (high two bits of byte 8) pinned to 10 — exactly what PG’s gen_random_uuid() and the historical uuid-ossp uuid_generate_v4() produce.

parse_date_literal

Parse YYYY-MM-DD into a Date (days since Unix epoch). Returns None on shape / numeric failure; the engine surfaces that as a TypeMismatch with the original text included.

parse_date_literal_ordered

v7.39 (GUC knife 5) — DateOrder-aware date input. PG disambiguates a three-field numeric date (01/02/2024, 02.01.2024, 1/2/24) by the DateStyle field order: MDY reads month first (the default — so '01/02/2024' is Jan 2 even with no SET), DMY day first, YMD year first ('24/01/02', and '1/2/24' is 2001-02-24!). A two-digit year is < 70 → 20xx, >= 70 → 19xx. Field values that don’t fit the order error (MDY '13/02/2024' is out of range — PG does NOT auto-swap). ISO year-first four-digit forms parse the same under every order.

parse_timestamp_literal

Parse YYYY-MM-DD[ HH:MM:SS[.ffffff]] into a Timestamp (microseconds since Unix epoch). The time portion is optional; missing → midnight. The fractional portion accepts 1–6 digits and pads with zeros to microseconds.

parse_timestamp_literal_ordered

v7.39 (GUC knife 5) — DateOrder-aware timestamp input; the date part follows parse_date_literal_ordered’s disambiguation.

parse_timestamp_literal_tz_ordered

v7.39 (tz epic) — like parse_timestamp_literal_ordered but also reports whether the literal carried an explicit offset. A naive literal’s micros are the WALL clock (caller localises against the session zone for a timestamptz); an offset-bearing literal’s are UTC already.

parse_vector_text

Parse "[1.0, 2.0, -3]" into Vec<f32>. Returns None on malformed input.

value_to_text

value_to_text_styled

v7.39 (GUC knife 3) — the canonical renderer under a session RenderStyle (DateStyle / IntervalStyle / extra_float_digits). value_to_text is the default-style shorthand.

value_to_text_with_fsp

v7.39 (round 425) — render a value the way a MySQL client expects a column with a DECLARED fractional-seconds precision to look: EXACTLY fsp fractional digits, zero-padded (DATETIME(3) shows .250, and .000 for a whole second), or none at all at precision 0. PG’s renderer trims trailing zeros, which is right for PG and wrong for MySQL — the stored instant is identical either way.

Type Aliases

SequenceResolver

v7.17.0 — sequence-mutating callback used by apply_function for nextval / currval / setval. Implemented by the engine to thread &mut Catalog access through an immutable &EvalContext.