RFR: 8251989: Hex formatting and parsing utility [v10]

[Roger Riggs]

On Fri, 27 Nov 2020 09:40:10 GMT, Chris Hegarty <chegar at openjdk.org> wrote:

>> Roger Riggs has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains 19 additional commits since the last revision:
>> 
>>  - Clarified that suffix() and prefix() methods do not return null, instead the empty string is returned.
>>  - Merge branch 'master' into 8251989-hex-formatter
>>  - Merge branch 'master' into 8251989-hex-formatter
>>  - Merge branch 'master' into 8251989-hex-formatter
>>  - The HexFormat API indexing model for array and string ranges is changed
>>    to describe the range using 'fromIndex (inclusive)' and 'toIndex (exclusive)'.
>>    
>>    Initially, it was specified as 'index' and 'length'. However, both byte arrays
>>    and strings used in the HexFormat API typically use fromIndex and toIndex
>>    to describe ranges.  Using the same indexing model can prevent mistakes.
>>    
>>    The change affects the methods and corresponding tests:
>>    
>>        formatHex(byte[] bytes, int fromIndex, int toIndex)
>>        formatHex(A out, byte[] bytes, int fromIndex, int toIndex)
>>        parseHex(char[] chars, int fromIndex, int toIndex)
>>        parseHex(CharSequence string, int fromIndex, int toIndex)
>>        fromHexDigits(CharSequence string, int fromIndex, int toIndex)
>>        fromHexDigitsToLong(CharSequence string, int fromIndex, int toIndex)
>>  - - Added @see and @link references to Integer.toHexString and Long.toHexString
>>    - Clarified parsing is case insensistive in various parse and fromXXX methods
>>    - Source level cleanup based on review comments
>>    - Expanded some javadoc tag text to make it more descriptive
>>    - Consistent use of 'hexadecimal' vs 'hex'
>>  - Review comment updates to class javadoc
>>  - Review comment updates, in the example code, and to describe the characters used to convert to hexadecimal
>>  - Correct length of StringBuilder in formatHex;
>>    Correct bug in formatHex(char[], 2, 3) and add test for subranges of char[]
>>  - Merge branch 'master' into 8251989-hex-formatter
>>  - ... and 9 more: https://git.openjdk.java.net/jdk/compare/9f01b66b...b19d2827
>
> src/java.base/share/classes/java/util/HexFormat.java line 71:
> 
>> 69:  * <p>
>> 70:  * For formatted hexadecimal string to byte array conversions the
>> 71:  * {@code parseHex} methods include {@link #parseHex(CharSequence) parseHex(string)} and
> 
> parseHex(string) -> parseHex(CharSequence)

The use of 'string' was intentional to make it easier to read and easier to understand the applicability.
In almost all cases the arguments will be String. The method signatures use CharSequence to enable other cases without needing to convert.

> src/java.base/share/classes/java/util/HexFormat.java line 528:
> 
>> 526:      * a range of the character array.
>> 527:      *
>> 528:      * Each byte value is parsed as the prefix, two case insensitive hexadecimal characters,
> 
> Each *char* value ...

The value being parsed is a byte, constructed from the input consisting of prefix, two hex characters, and the suffix.

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

PR: https://git.openjdk.java.net/jdk/pull/482