RFD: Notes in String.toUpperCase(), String.toLowerCase() could be more specific refering to "locale"

[Eirik Bjørsnøs]

Hello,

During a discussion about the deprecation of String.toLowerCase(),
String.toUpperCase [1], it occurred to me that the current Note in the API
documentation could be more specific when talking about locales.

Before going ahead and suggesting a PR/CSR, I'd like to socialize the idea
that we could improve the Notes in these somewhat suspicious methods.

The current notes look like this:

Note: This method is locale sensitive, and may produce unexpected
> results if used for strings that are intended to be interpreted locale
> independently.


Sensitive to which locale? Independently of which locale?

It then goes on to say:

To obtain correct results for locale insensitive strings, use
> toUpperCase(Locale.ROOT)


What are "locale insensitive strings"?

Here is an attempt to be more specific:

Note: This method is sensitive to the default locale for this instance
> of the Java Virtual Machine. It  may produce unexpected
> results if used for strings that are intended to be interpreted
> independent of the default locale.


For the last part, I suggest using "language/country neutral results"
instead of "locale insensitive strings":

To obtain language/country neutral results, use toLowerCase(Locale.ROOT)


Any thoughts?

Thanks,
Eirik.
[1] https://github.com/openjdk/jdk/pull/13434#issuecomment-1505832883
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/core-libs-dev/attachments/20230413/74ffd8ae/attachment.htm>