RFR: 8256828: ostream::print_cr() truncates buffer in copy-through case [v4]

[David Holmes]

On Tue, 4 Jun 2024 07:00:56 GMT, David Holmes <dholmes at openjdk.org> wrote:

>> If you go for a clear behavior description, there are a few infos missing:
>> - result_len contains the length of the returned string, including trailing cr, excluding trailing nul
>> - function will always print the trailing cr regardless of truncation (e.g., print_cr("abc") with output buffer of 2 will just return a cr).
>> 
>> But I wonder whether we can shorten the description to something like this:
>> 
>> "Function will return a formatted string. It may bypass the caller-provided output buffer, returning the provided format string directly, if no formatting or copying is needed."
>
>> result_len contains the length of the returned string, including trailing cr, excluding trailing nul
> 
> Yes I state that it is the length of the returned string as per strlen.
> 
> Yes I can clarify cr is always printed.
> 
>> It may bypass the caller-provided output buffer, returning the provided format string directly, if no formatting or copying is needed
> 
> Well it _will_ bypass in those cases, though you then need to know when "no copying is needed". The idea was to clearly document the behaviour so that people would no longer be surprised or make assumptions/interepretations.

I've simplified and clarified and even expanded the comment block describing the behaviour.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/19512#discussion_r1625504156