RFR 8251989: Hex formatter and parser utility

[Chris Hegarty]

Roger,

> On 27 Aug 2020, at 02:34, Roger Riggs <Roger.Riggs at oracle.com> 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 

1. "Hex.Formatter formats bytes to a hex string or appends to
    StringBuilder.”

I wonder if this could be a bit more descriptive. What about something
like:

“Hex.Formatter transforms sequences of bytes into a formatted
hexadecimal string.”  What is a formatted hexadecimal string?  “A
formatted hexadecimal string consists solely of; an optional prefix, a
pair of hexadecimal characters ( THESE ARE ALREADY DEFINED ELSEWHERE),
an optional delimiter, and an optional suffix.”  Or some such wording.

2. I like the move to formatter/parser, but I now find myself looking
for an encoder/decoder ;-) It might be obvious, but could be worth
calling out explicitly, e.g. “A formatter with an empty prefix, suffix,
and delimiter, provides unformatted (plain) encoder functionality".
Similar for parser.   Maybe this is what “canonical” is referring to?
If so, I think it would be best to define it somewhere.

3. "The Hex class consists solely of factory methods for hexadecimal
(hex) formatters and parsers.”

It could be worth generalising the class-level description now, so as
to allow space for additional convenience methods in the future. ( A
while back I suggested not adding convenience methods yet, but I see
that Mark has suggested a couple of key conveniences )

-Chris.