Skip to content

docs: say exactly where the calendar factories' limits come from (#450) - #455

Merged
CaffeinatedCoder merged 2 commits into
mainfrom
docs/450-calendar-factory-wording
Oct 25, 2026
Merged

CaffeinatedCoder merged 2 commits into
mainfrom
docs/450-calendar-factory-wording

Conversation

@CaffeinatedCoder

Copy link
Copy Markdown
Owner

Closes #450

Problem

Three sentences about the calendar factories in docs/efcore.md#what-runs-where were imprecise:

  1. The LocalDateRange/YearMonthRange row, the EF Core README, the four calendar entries in translation-support.json and NodaCalendarFactoryClientSideTests' summary said "the years before 4713 BC have no PostgreSQL date", and led with -infinity. PostgreSQL's first date is 4714-11-24 BC. The month and the year that hold it can't be built (date_trunc raises "timestamp out of range"), with Npgsql's infinity conversions on or off.
  2. "The first and last periods end at -infinity and infinity": the first period starts there. With Npgsql.DisableDateTimeInfinityConversions set, both are the days themselves.
  3. "PostgreSQL raises an error that names the argument": a month, a quarter and the year 0 go to make_date, whose error shows the date it was asked to build (Quarter(2026, 5) → 2026-13-01). Only the year and week guards name the argument.

Change

  • (1) The same reason, in all five places.
  • (2) The extremes sentence is reworded, and E76's quote follows it.
  • (3) The error sentence says which argument gives which message.

The decision to keep the NodaTime forms in memory is unchanged.

Tests

Docs only. Each statement was measured on PostgreSQL 16.15: '4714-11-24 BC'::date works and '4714-11-23 BC'::date doesn't; date_trunc('month'|'year', …) over PostgreSQL's first day raises; and make_date(2026, 13, 1) and make_date(0, 6, 1) print the date. OracleCatalogueTests holds E76's quote to the new sentence. The conventions tests (417) pass.

🤖 Generated with Claude Code

- PostgreSQL's first date is 4714-11-24 BC, so the month and the year that hold it
  have no start, with Npgsql's infinity conversions on or off. That, not -infinity,
  is why the LocalDateRange and YearMonthRange forms stay in memory. Five places.
- The first period starts at -infinity and the last ends at infinity, and both are
  the days themselves with Npgsql.DisableDateTimeInfinityConversions. E76 follows.
- An out-of-range month, quarter or year 0 raises make_date's own error, which shows
  the date it was asked for (Quarter(2026, 5) reports 2026-13-01); the year and week
  guards name the argument.

Measured on PostgreSQL 16.15.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@CaffeinatedCoder
CaffeinatedCoder merged commit fd4ad50 into main Oct 25, 2026
14 checks passed
@CaffeinatedCoder
CaffeinatedCoder deleted the docs/450-calendar-factory-wording branch October 25, 2026 19:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/ranges Range unions, variants and the shape engines documentation Improvements or additions to documentation package/efcore Affects CodoMetis.ValueRanges.EFCore.PostgreSQL package/efcore-nodatime Affects CodoMetis.ValueRanges.EFCore.PostgreSQL.NodaTime

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: calendar factory rows in What runs where — PostgreSQL's first date, the extremes with the conversions off, Quarter's error text

1 participant