RFR 8251989: Hex formatter and parser utility

[Roger Riggs]

Hi Douglas,

On 8/27/20 10:37 AM, Douglas Surber wrote:
> The meaning of prefix and suffix is not specified in formatter​(boolean uppercase, String delimiter,String prefix, String suffix). It isn't specified whether they precede and follow the entire formatted value or each byte. The class comment clarifies but I shouldn't have to go there to discover this.
>
> I was surprised at the meaning for prefix and suffix. The seem pointless to me. It is trivial to enclose the entire formatted value with a prefix and suffix without using these arguments. If they were prefix and suffix for each individual byte, that would be much more useful. For example, how can I format a byte sequence like this?
>
> 	0x00 0x01 0x02 0x0d 0x0e 0x0f
>
> 	format(false, " 0x", "0x", "")
>
> doesn't work because an empty byte array would be
>
> 	0x
>
> instead of an empty string.

The prefix and suffix concepts first appeared in the StringJoiner.
In the Hex context, they can be used to construct a complete string 
efficiently.
For example a mac address.  [50:2b:7f:e8:6a:e2]

I have tried out the use of prefix and suffix as you did above and 
noticed the same limitation.

I did run across several examples in the OpenJDK code where an empty 
string had a different representation
and it might reasonable to have a replacement for an empty array.
Though the factory methods are about the limits for numbers of args.
A more fluent builder API has been suggested.

The javadoc can be expanded upon to make it clearer.

Thanks, Roger


>
> Douglas
>
>> On Aug 27, 2020, at 4:55 AM, core-libs-dev-request at openjdk.java.net wrote:
>>
>> Message: 1
>> Date: Wed, 26 Aug 2020 21:34:47 -0400
>> From: Roger Riggs <Roger.Riggs at oracle.com <mailto:Roger.Riggs at oracle.com>>
>> To: core-libs-dev <core-libs-dev at openjdk.java.net <mailto:core-libs-dev at openjdk.java.net>>
>> Subject: RFR 8251989: Hex formatter and parser utility
>> Message-ID: <6378b60b-7a45-d8b0-5ebd-3d3bf9144401 at oracle.com <mailto:6378b60b-7a45-d8b0-5ebd-3d3bf9144401 at oracle.com>>
>> Content-Type: text/plain; charset=utf-8; format=flowed
>>
>> 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 <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/ <http://cr.openjdk.java.net/~rriggs/webrev-hex-formatter-8251989/>
>>
>> CSR:
>> https://bugs.openjdk.java.net/browse/JDK-8251991 <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/ <http://cr.openjdk.java.net/~rriggs/hex-encoder-javadoc/>
>>
>>