Skip to content

Convert 12 AM to hour 0 in the 12-hour (h/a) date format - #920

Merged
xerj-org merged 2 commits into
xerj-org:mainfrom
winklemad:fix-12am-twelve-hour-date-format
Sep 13, 2026
Merged

xerj-org merged 2 commits into
xerj-org:mainfrom
winklemad:fix-12am-twelve-hour-date-format

Conversation

@winklemad

Copy link
Copy Markdown
Contributor

What this changes, and why

In the 12-hour date format (h + a, e.g. format: "hh:mm a"), the AM/PM post-processing in parse_pattern_with (crates/xerj-query/src/dates.rs) only adjusts the PM side (1–11 → +12). An AM hour of 12 is left as 12 instead of wrapping to 0.

This contradicts the token's own docstring — "AM/PM marker (a); shifts a 12-hour value" — and java.time's h (clock-hour-of-am-pm) semantics that ES 8.13 follows: with an a marker, AM 12 → 0, PM 12 → 12, PM 1–11 → +12.

Consequences:

  • gte: "12:30 AM" under format: "hh:mm a" resolves to 1970-01-01T12:30 instead of 00:30.
  • A midnight-hour range {"range":{"t":{"gte":"12:00 AM","lt":"01:00 AM","format":"hh:mm a"}}} builds an inverted 12:00 <= t < 01:00 bound, so every document in the midnight hour is silently dropped.

The fix adds the missing AM branch (12 → 0; 1–11 unchanged). PM behaviour is byte-for-byte unchanged.

Evidence

# Before the fix — new regression test fails on the AM-12 case:
$ cargo test -p xerj-query twelve_hour_clock_converts
assertion `left == right` failed
  left: Some("1970-01-01T12:30:00.000Z")
 right: Some("1970-01-01T00:30:00.000Z")
test result: FAILED. 0 passed; 1 failed

# After the fix — passes (AM 12→00:30, AM 01→01:30, AM 11→11:30, PM 12→12:30, PM 01→13:30):
$ cargo test -p xerj-query
test result: ok. 187 passed; 0 failed   # was 186; +1 new test, no regression

$ cargo fmt -p xerj-query -- --check    # clean
$ cargo clippy -p xerj-query            # no warnings
$ cargo build --release -p xerj-query   # Finished `release` profile in ~59s

Checks

  • cargo fmt --all — cargo fmt -p xerj-query -- --check clean; cargo clippy -p xerj-query no warnings
  • Scoped release build: cargo build --release -p xerj-query (Finished, ~59s)
  • cargo test -p xerj-query passes (187 passed; 0 failed)
  • ES-YAML conformance suite — Not run (see below)
  • New ES-compatible behaviour has a matching YAML case — I added a Rust unit test (ampm_twelve_hour_tests) on the date-resolution path rather than a YAML case; happy to add a hh:mm a range case under engine/tests/es-compat-yaml/yaml/ if you'd prefer that form
  • Docs updated if user-visible behaviour changed — behaviour now matches the existing docstring; no doc change needed
  • Non-trivial audit — N/A: single-branch logic fix in one function, no operational/runnable-recipe surface

Not run: the full ES-YAML conformance suite (es-yaml-runner) — I did not build the full engine test crate. I ran the xerj-query unit suite, which exercises compile_formats → resolve_date_bound_str (the exact date-resolution path this touches) directly, and all 187 tests pass.

Provenance

  • Written by: an AI coding agent (Claude, via Claude Code), run by @winklemad, who reviewed every line and answers for it.
  • Verified (commands run, output observed):
    • resolve_date_bound_str("12:30 AM", false, compile_formats("hh:mm a")) → before: Some("1970-01-01T12:30:00.000Z"); after: Some("1970-01-01T00:30:00.000Z").
    • cargo test -p xerj-query → 187 passed / 0 failed (was 186 + the new test); cargo fmt --check, cargo clippy, cargo build --release -p xerj-query all clean.
  • Assumed (not tested, and what would falsify it):
    • This fix restores correct h + a AM/PM behaviour only. java.time's other hour letters are collapsed into one 0–23 Hour token here, so K (hour-of-am-pm 0–11) and k (clock-hour-of-day 1–24, where "24:00" should be 00:00) remain a separate, broader gap I did not address. Falsifiable by a format: "kk:mm" value "24:00" test.
  • Not run: the ES-YAML conformance suite, as noted above.

The AM/PM post-processing in `parse_pattern_with` only handled the PM side
(1-11 -> +12), so an AM hour of 12 was left as 12 instead of wrapping to 0.
A round bound like `gte: "12:30 AM"` under `format: "hh:mm a"` resolved to
12:30 instead of 00:30, and a midnight-hour range such as
`gte "12:00 AM", lt "01:00 AM"` built an inverted `12:00 <= t < 01:00`
bound that silently drops every document in that hour.

Handle the AM branch: 12 -> 0, 1-11 unchanged; PM behaviour is unchanged.
This matches java.time's `h` (clock-hour-of-am-pm) semantics that ES follows.
Add a regression test covering AM 12/01/11 and PM 12/01.
@cla-bot

cla-bot Bot commented Sep 10, 2026

Copy link
Copy Markdown

Thanks for this contribution — we'd like to merge it.

Before we can, we need a signed Contributor License Agreement from: @winklemad

It is a one-time thing per contributor, not per pull request. Read CLA.md, then open a small pull request adding your GitHub username to .contributors — that pull request is your signature, since it is made from your own account.

Once it is merged, comment @cla-bot check here and this check will go green. If you believe you are already covered, comment @cla-bot check and it will re-verify.

CI runs `cargo fmt --all --check`; rustfmt 1.9 wraps the five assert_eq!
lines in `ampm_twelve_hour_tests`. No behaviour change — the fix commit is
@winklemad's and is untouched.
@cla-bot cla-bot Bot added the cla-signed label Sep 13, 2026
@xerj-org

Copy link
Copy Markdown
Owner

@cla-bot check

@cla-bot

cla-bot Bot commented Sep 13, 2026

Copy link
Copy Markdown

Re-checking the CLA status for every commit author on this pull request…

@xerj-org
xerj-org merged commit 1302ac4 into xerj-org:main Sep 13, 2026
21 checks passed
@xerj-org

Copy link
Copy Markdown
Owner

Merged — thank you, and welcome. The fix is on main as your commit; the only thing added on our side was a cargo fmt pass on the test. The midnight-hour range bug this closes is a good one to have found.

@winklemad

Copy link
Copy Markdown
Contributor Author

Thanks Ivan — glad the repro made it a quick merge, and appreciate the welcome. That midnight-hour range case was a satisfying one to track down. I'll keep an eye on the repo and pick up more where it's useful.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants