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

2023-04-13 Thread Eirik Bjørsnøs 
>
> Any thoughts?
>

I'll add my own thoughts, which is that busy developers cannot be expected
to do the "right thing" if they don't understand the API Note.

Improving the note such that more developers understand the consequences of
using the method should help developers write more correct code.

Thanks,
Eirik.

>

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

2023-04-13 Thread 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