fix: truncate scalar timestamps in their own unit in date_trunc

[namanjain24-sudo]

Which issue does this PR close?

• Closes date_trunc rejects scalar timestamps that array evaluation accepts #25432.

Rationale for this change

process_scalar always went through general_date_trunc, which converts the value to nanoseconds before truncating. A Timestamp(Second), Timestamp(Millisecond) or Timestamp(Microsecond) value outside the nanosecond range (after 2262 or before 1677) therefore failed with Timestamp ... out of range.

process_array does not convert for the fine granularities: when granularity.is_fine_granularity(), or the value has no timezone and the granularity is hour or day, it truncates in the input's own unit with plain arithmetic. So the same value succeeded in a column and failed as a scalar:

SELECT date_trunc('second', to_timestamp_seconds(10000000000));
-- Execution error: Timestamp 10000000000 out of range

SELECT date_trunc('second', to_timestamp_seconds(ts)) FROM (VALUES (10000000000)) AS t(ts);
-- 2286-11-20T17:46:40

What changes are included in this PR?

The scalar path now takes the same route as the array path:

• truncates_in_input_unit is the condition process_array already used, now shared by both paths.
• fine_granularity_unit is the unit table from general_date_trunc_array_fine_granularity, moved out so both paths read it.
• date_trunc_fine_granularity truncates one value in its own unit, with the checked subtraction and error message the array path already used for values near i64::MIN. The array path's slow branch now calls it too.

For those granularities, a scalar and a one-row column now run the same function, so they accept the same values and give the same result. Everything else (week, month, quarter, year, and hour/day with a timezone) still goes through general_date_trunc on both paths, so it is unchanged and still limited to the nanosecond range for both scalars and columns.

One existing test changes. date_trunc('hour', arrow_cast(9223372036854775807, 'Timestamp(Second, None)')) was expected to fail with Timestamp 9223372036854775807 out of range. That test comes from #22262, whose goal was an error instead of a panic, and a column holding that value already succeeds. As a scalar it now succeeds too, so the test uses week, which still converts to nanoseconds on both paths and so still covers the error.

Are these changes tested?

• New unit test scalar_and_array_accept_timestamps_beyond_nanosecond_range evaluates date_trunc on a scalar and on a one-row column with the same value, for all three coarser-than-nanosecond units, with and without a timezone, and for values before 1677 and after 2262, and checks that both succeed with the same result.
• New sqllogictest queries in datetime/timestamps.slt cover the issue's scalar and column queries, plus millisecond and microsecond scalars.
• With the scalar change disabled, the new unit test fails, and the three new scalar queries fail with the error from the issue (Timestamp 10000000000 out of range, etc.), while the column query passes as it does on main.
• cargo test -p datafusion-functions (384 passed), the full sqllogictest suite (520 files), cargo fmt and cargo clippy -p datafusion-functions --all-targets --all-features -- -D warnings pass.

Are there any user-facing changes?

date_trunc on a scalar timestamp outside the nanosecond range now returns the same result as on a column, instead of an out-of-range error, for microsecond, millisecond, second and minute, and for hour and day without a timezone. No API changes.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 94.78261% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.38%. Comparing base (ccfe704) to head (5c830eb).
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
datafusion/functions/src/datetime/date_trunc.rs	94.78%	3 Missing and 3 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #25498      +/-   ##
==========================================
- Coverage   82.38%   82.38%   -0.01%     
==========================================
  Files        1138     1138              
  Lines      433733   434398     +665     
  Branches   433733   434398     +665     
==========================================
+ Hits       357331   357872     +541     
- Misses      54848    54889      +41     
- Partials    21554    21637      +83     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[benbellick]

IIUC we above do some work to turn tu into unit via fine_granularity_unit and then do the same computation again inside of this function date_trunc_fine_granularity. That feels like:

1. duplicated work, and
2. a potential source of confusion while reading the code

I think it is worth coming up with a simplification. What you think?

[namanjain24-sudo]

Good catch, agreed. In 5c830eb the slow branch now passes the unit it already has to a small truncate_to_unit(value, unit, granularity), and the scalar path looks the unit up once, so date_trunc_fine_granularity is gone.

[benbellick]

worth seeing if there is a regression. Have you tried the date_trunc_minute_1000 benchmark?

[namanjain24-sudo]

Ran it against the branch's base (ccfe704) on the same machine, together with the other date_trunc benches: date_trunc_minute_1000 went from 1.246 µs to 1.232 µs, and the rest are within noise. That matches the change, since the array hot loop is the same and only the unit table moved into a helper.

[benbellick]

This isn't going to make sense as a comment once this is merged. I would either include the issue number for future reference or get rid of the mention of the issue, whatever is the standard in this repo (I'm not sure). Thanks!

[namanjain24-sudo]

Fair point. I reworded it to say what it checks and added the issue link, the same way other comments under datetime/ link theirs.