RFR: 8366224: Introduce DecimalDigits.appendPair for efficient two-digit formatting and refactor DateTimeHelper

[Shaojin Wen]

On Wed, 27 Aug 2025 17:57:31 GMT, Roger Riggs <rriggs at openjdk.org> wrote:

>> This PR introduces a new efficient API for appending two-digit integers to StringBuilders and refactors DateTimeHelper to leverage this new functionality.
>> 
>> Changes include:
>> 
>> 1. New `appendPair` method for efficient two-digit integer formatting (00-99):
>>    - Added `AbstractStringBuilder.appendPair(int i)` with core implementation
>>    - Added `JavaLangAccess.appendPair(StringBuilder, int)` for internal access
>>    - Added `System.JavaLangAccessImpl.appendPair(StringBuilder, int)` bridge
>>    - Added `DecimalDigits.appendPair(StringBuilder, int)` public static utility method
>>    - Enhanced Javadoc documentation for all new methods
>> 
>> 2. Refactored `DateTimeHelper` to use the new `DecimalDigits.appendPair`:
>>    - Updated `DateTimeHelper.formatTo` methods for `LocalDate` and `LocalTime`
>>    - Replaced manual formatting logic with the new efficient two-digit appending
>>    - Improved code clarity and consistency in date/time formatting
>> 
>> These changes improve code clarity and performance when formatting two-digit numbers, particularly in date/time formatting scenarios.
>
> Generally, even with the performance benefits, this code is too narrow a use case to justify the hacking into AbstractStringBuilder and adding another package busting JavaLangAccess entry point.

Thank you for your feedback, @RogerRiggs.

I introduced this PR because I plan to optimize the performance of `java.time.format.DateTimeFormatter`'s `parse` and `format` methods. This is a very large change, and to facilitate code review, I am splitting the process into multiple smaller PRs. This allows us to achieve continuous improvement, and this PR is one part of that effort.

In future optimizations, I need to use `AbstractStringBuilder.appendPair` when writing values like Year/Month/DayOfMonth/Hour/Minute/Second within the `java.time.format.DateTimeFormatterBuilder$NumberPrinterParser#format` method.

In the current PR, using `appendPair` in `DateTimeHelper` to write month/dayOfMonth/hour/minute/second results in code that is more intuitive than the original.

*   Original


month = date.getMonthValue(),
day   = date.getDayOfMonth();

buf.append(month < 10 ? "-0" : "-").append(month)
   .append(day < 10 ? "-0" : "-").append(day);


*   Improved


buf.append('-');
DecimalDigits.appendPair(buf, date.getMonthValue());
buf.append('-');
DecimalDigits.appendPair(buf, date.getDayOfMonth());


The improved code is more readable than the original.

Placing `appendPair` in `DecimalDigits` alongside other `putPair` series methods also makes the code's purpose easier to understand.

`AbstractStringBuilder.appendPair` was introduced for the `java.time` format scenario, but it can also be used in `java.util.Formatter` in the future, or potentially with `StringTemplate` if it's introduced. My latest commit adds more usage scenarios in `core-libs`.

-------------

PR Comment: https://git.openjdk.org/jdk/pull/26911#issuecomment-3231113907