On Tue, 3 Mar 2026 10:32:55 GMT, Eirik Bjørsnøs <[email protected]> wrote:
>> Thanks, ideas for better language are welcome. I think ideally readers would
>> come away with the understanding that they should always prefer this method
>> to calling `getBytes(cs).length`.
>>
>>> This may be read as a strong promise that performance will always be better
>>> which may be a difficult promise to keep.
>>
>> Thinking about this a bit more, I think it should usually be possible to
>> keep that promise, an implementation can always fall back to using
>> `getBytes(cs).length` for a particular charset. But I guess once the
>> implementation of `encodedLength` diverges from `getBytes(cs).length`, it's
>> conceivable that a compiler could do a better job of optimizing
>> `getBytes(cs).length`, especially if it's able to do escape analysis and
>> eliminate the array.
>>
>> And also technically for the case where `encodedLength` falls back to
>> `getBytes(cs).length` it's slightly _worse_ because it's doing
>> `getBytes(cs).length` and a bit of additional work to check if the provided
>> charsets is one of the ones it can optimize.
>>
>> I went looking for some other discussions of performance in javadoc for
>> inspiration
>>
>> `String#lines`
>>
>>> This method provides better performance than split("\R") by supplying
>>> elements lazily and by faster search of new line terminators.
>>
>> `Boolean(boolean)` (and other boxed primitive constructors)
>>
>>> The static factory {@link #valueOf(boolean)} is generally a better choice,
>>> as it is likely to yield significantly better space and time performance.
>>
>> So perhaps something like
>>
>>> This method is generally a better choice than calling than {@link
>>> #getBytes(Charset) getBytes(cs).length}, as it may provide better space and
>>> time performance.
>>
>> or
>>
>>> This method may provide better space and time performance than {@link
>>> #getBytes(Charset) getBytes(cs).length}.
>>
>> what do you think?
>
>> This method may provide better space and time performance than {@link
>> #getBytes(Charset) getBytes(cs).length}.
>>
>> what do you think?
>
> I like this since it succinctly answers the user's question "Why/when should
> I consider using this method over getBytes(Charset).length?", without
> providing too many testable assertions or classifying choices as more or less
> good or bad.
>
> However, I think my usefullness here is perhaps asking questions rather than
> answering them :-) I'm sure other experienced reviewers can provide feedback
> on phrasing which feels in place with this API.
I think the API note (since integrated) is okay. The audience for this method
is more advanced libraries, I wouldn't expect 99% of developers to use it.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/28454#discussion_r2888636270
