RFR: 8338140: (str) Add notes to String.trim and String.isEmpty pointing to newer APIs

[Stuart Marks]

On Wed, 11 Jun 2025 23:57:48 GMT, Naoto Sato <naoto at openjdk.org> wrote:

>> src/java.base/share/classes/java/lang/String.java line 3837:
>> 
>>> 3835:      *
>>> 3836:      * @apiNote
>>> 3837:      * This method uses a ASCII-based definition of space characters that are to be
>> 
>> "a ASCII" or "an ASCII"?
>
> In fact, "ASCII-based definition of space characters" is kind of unclear to me. How about explicitly specify them as C0 controls and the space, or exactly quote the space definition in the first paragraph?

Oh yeah, that should be "an ASCII...."

But maybe we should change the wording per @naotoj's comment. I don't want to repeat the specification above, but rather I want to describe it in terms of what the thinking was at the time it was introduced in JDK 1.0. For comparison, in JDK 1.0, the way to create a String from bytes was to fill in the upper 8 bits of a char using a constant "hibyte" parameter of the String(byte[], int) constructor, which is now deprecated. So this was very much an ASCII-centric view of the world.

The trim() method first appeared in 1.0 but its original specification mentioned white space without defining it. The 1.1 specification gained some details, saying

> Removes white space from both ends of this string.
>
> All characters that have codes less than or equal to '\u0020' (the space character) are considered to be white space. 

>From the 1996 or 1997 view of the world, I'd describe this as "space plus ASCII control characters." Would something like that make more sense?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/25762#discussion_r2141308311