RFR: 8357063: Document preconditions for DecimalDigits methods [v4]

[Jaikiran Pai]

On Fri, 16 May 2025 16:10:29 GMT, Shaojin Wen <swen at openjdk.org> wrote:

>> Similar to PR #24982 
>> Document preconditions on certain DecimalDigits methods that use operations either unsafe and/or without range checks.
>
> Shaojin Wen has updated the pull request incrementally with one additional commit since the last revision:
> 
>   warning

src/java.base/share/classes/jdk/internal/util/DecimalDigits.java line 348:

> 346:      */
> 347:     public static int getChars(long i, int index, char[] buf) {
> 348:         // Used by trusted callers.  Assumes all necessary bounds checks have been done by the caller.

Hello Shaojin, I think this was a misplaced comment previously. Looking at the implementation of this method, there's no "unsafe" access happening in this method's implementation. It ends up calling `putChar` which does a Java style array access and thus is backed by the language's bounds checking.

Removing this comment I believe is the right thing. Having said that, I am unsure the javadoc comment of this method should refer to `DecimalDigits#uncheckedGetCharsUTF16` because that is confusing and misleading.

Should we change the javadoc text of this method to:

> Places characters representing the long i into the character array buf. The characters are placed into the buffer backwards starting with the least significant digit at the specified index (exclusive), and working backwards from there.

Would that accurately describe what this method's implementation currently does?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/25246#discussion_r2098328985