feat(bigquery-jdbc): implement picosecond temporal math and formatting engine

[keshavdandeva]

b/544839231

This PR implements the core temporal normalization and mathematical formatting engine in BigQueryTemporalUtility to support high-precision TIMESTAMP(12) (picosecond) retrieval across both 6-digit microsecond and 12-digit picosecond scales.

Key Changes

• High-Precision Formatting:
  • formatTimestampString: Formats epoch decimal strings into standard UTC JDBC timestamp format (yyyy-MM-dd HH:mm:ss.ffffff[ffffff]) with deterministic FLOOR/DOWN truncation to prevent sub-second rollover on pre- and post-1970 epochs as well as scientific notation (1.69E9).
  • formatTimestampStringFromIso: Linear 3-phase normalizer that preserves sub-nanosecond fractional digits (>9 digits) before passing base date-time components to JDK JSR-310 for UTC offset shifting.
  • formatTimestampStringFromMicroseconds: Direct epoch microsecond formatter with zero-allocation in-place digit padding.
• Sub-Nanosecond Parser Safety:
  • parseEpochDecimalToInstant: Safely converts high-precision decimal epoch strings to Instant by truncating sub-nanoseconds to avoid arithmetic overflow.
  • Clamped sub-second fractional digits to 9 digits in boxTimestamp, boxDateTime, and boxTime to protect legacy JDBC/JDK parsers from DateTimeParseException on 12-digit literals.
• Zero-Allocation Buffer Optimization:
  • Replaced manual component getter calls with thread-safe DateTimeFormatter.formatTo().
  • Refactored appendPadded to fill pre-allocated StringBuilder buffers in-place without intermediate heap string allocations.
• Unit Tests:
  • Added focused unit tests in BigQueryTemporalUtilityTest covering 12-digit precision formatting, 6-digit truncation, rollover prevention, pre-1970 negative epochs, scientific notation, and timezone boundary shifts.

[gemini-code-assist]

Code Review

This pull request introduces high-precision temporal formatting and parsing capabilities to BigQueryTemporalUtility to handle sub-nanosecond (picosecond) precision and prevent parser failures. Key additions include methods for parsing epoch decimals to Instant, formatting timestamp strings with configurable precision, and truncating sub-second fractions to nanoseconds. Unit tests have been expanded to cover these new features. The review feedback highlights a correctness bug in parseEpochDecimalToInstant when handling negative epoch decimals with sub-nanosecond precision, which causes incorrect rounding, and suggests adding a corresponding test case to prevent regressions.

[keshavdandeva]

/gemini review

[gemini-code-assist]

Code Review

This pull request enhances BigQueryTemporalUtility to support high-precision temporal formatting and parsing, specifically handling picosecond-level precision and preventing sub-second rollover. Feedback on the changes includes suggestions to trim trailing spaces before replacing spaces with 'T' to prevent parsing failures, and to robustly determine the correct timezone offset index when both '+' and '-' signs are present in the input string.