RFR: 8251989: Hex formatting and parsing utility [v9]
Marcono1234
github.com+11685886+marcono1234 at openjdk.java.net
Tue Oct 27 23:04:23 UTC 2020
On Tue, 27 Oct 2020 03:09:32 GMT, Roger Riggs <rriggs at openjdk.org> wrote:
>> java.util.HexFormat utility:
>>
>> - Format and parse hexadecimal strings, with parameters for delimiter, prefix, suffix and upper/lowercase
>> - Static factories and builder methods to create HexFormat copies with modified parameters.
>> - Consistent naming of methods for conversion of byte arrays to formatted strings and back: formatHex and parseHex
>> - Consistent naming of methods for conversion of primitive types: toHexDigits... and fromHexDigits...
>> - Prefix and suffixes now apply to each formatted value, not the string as a whole
>> - Using java.util.Appendable as a target for buffered conversions so output to Writers and PrintStreams
>> like System.out are supported in addition to StringBuilder. (IOExceptions are converted to unchecked exceptions)
>> - Immutable and thread safe, a "value-based" class
>>
>> See the [HexFormat javadoc](http://cr.openjdk.java.net/~rriggs/8251989-hex-formatter/java.base/java/util/HexFormat.html) for details.
>>
>> Review comments and suggestions welcome.
>
> Roger Riggs has updated the pull request incrementally with two additional commits since the last revision:
>
> - 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'
The changes look good, especially that `Integer.toHexString` and `Long.toHexString` now link to this new class!
src/java.base/share/classes/java/lang/Integer.java line 260:
> 258: * {@code Integer.toHexString(n).toUpperCase()}
> 259: * </blockquote>
> 260: * <p>
Is this needed? `@apiNote` is a block tag so should create a paragraph on its own.
src/java.base/share/classes/java/lang/Long.java line 295:
> 293: * {@code Long.toHexString(n).toUpperCase()}
> 294: * </blockquote>
> 295: * <p>
Is this needed? `@apiNote` is a block tag so should create a paragraph on its own.
src/java.base/share/classes/java/util/HexFormat.java line 316:
> 314: * @param bytes a non-null array of bytes
> 315: * @param fromIndex the initial index of the range, inclusive
> 316: * @param toIndex the final index of the range, exclusive.
Suggestion:
* @param toIndex the final index of the range, exclusive
The period at the end is inconsistent.
Applies to the other `@param toIndex` as well.
-------------
PR: https://git.openjdk.java.net/jdk/pull/482
More information about the core-libs-dev
mailing list