RFR 8251989: Hex formatter and parser utility

[Roger Riggs]

Hi Peter,

I made the same observation when exploring the API and ended up concluding
that the declared exceptions on Appendable made the API much harder to use.

Though the formatted characters can't be directly accumulated in the 
Appendable
it is possible to build the output in a StringBuilder and then append 
the StringBuilder
to the appendable with only a single copy since it is a CharSequence.
That would avoid the creation/allocation of a String as an intermediate 
step.

Thanks, Roger


On 8/27/20 1:21 PM, Peter Levart wrote:
> Hi Roger,
>
>
> About methods in Hex.Formatter that append to StringBuilder, like the 
> following one:
>
>
>     public StringBuilder format​(StringBuilder sb, byte[] bytes)
>
>
> ...I was thinking that such method could have more utility if it was 
> specified as:
>
>
>     public <A extends Appendable> A format(A appendable, byte[] bytes)
>
>
> For example, you could also format directly to PrintStream, Writer, 
> CharBuffer or any custom implementation. The only grief is that 
> Appendable methods are specified to throw IOException, but 
> Hex.Formatter.format(Appendable ... methods could be specified to wrap 
> such exception with UncheckedIOException. For usage with StringBuilder 
> this would not change anything as it never throws IOException.
>
> What do you think?
>
> Regards, Peter
>
>
> On 8/27/20 3:34 AM, Roger Riggs wrote:
>> Please review updates to the formatting and parsing API based on the 
>> last round of comments.
>> There are many changes, so it may be useful to read it as a fresh draft.
>>
>>  - Rename classes: Encoder -> Formatter; Decoder -> Parser
>>  - Rename methods: encode -> format; decode -> parse, etc.
>>  - Rename factory methods to match
>>  - Added a factory method and re-arrange arguments to make it more 
>> convenient
>>    to create uppercase formatters based on the existing uses.
>>  - The implementation has been updated based on the suggestions and 
>> API changes
>>
>> The webrev for applying the API to the security classes will be 
>> updated when the API settles down.
>>
>> JavaDoc:
>> http://cr.openjdk.java.net/~rriggs/hex-formatter/java.base/java/util/Hex.html 
>>
>>
>> Webrev:
>> http://cr.openjdk.java.net/~rriggs/webrev-hex-formatter-8251989/
>>
>> CSR:
>> https://bugs.openjdk.java.net/browse/JDK-8251991
>>
>> p.s.
>> The previous (encoder/decoder) javadoc has been renamed to:
>>    http://cr.openjdk.java.net/~rriggs/hex-encoder-javadoc/
>>
>>