8251989: Hex formatting and parsing utility

src/java.base/share/classes/java/lang/Integer.java

@@ -257,10 +257,18 @@ public static String toUnsignedString(int i, int radix) {
      * <blockquote>
      *  {@code Integer.toHexString(n).toUpperCase()}
      * </blockquote>
+     * <p>
+     * @apiNote
+     * {@link java.util.HexFormat} provides formatting and parsing
+     * of byte arrays and primitives to return a string or adding to an {@link Appendable}.
+     * HexFormat formats and parses uppercase or lowercase hexadecimal characters,
+     * with leading zeros and for byte arrays includes for each byte
+     * a delimiter, prefix, and suffix.
      *
      * @param   i   an integer to be converted to a string.
      * @return  the string representation of the unsigned integer value
      *          represented by the argument in hexadecimal (base&nbsp;16).
+     * @see java.util.HexFormat
      * @see #parseUnsignedInt(String, int)
      * @see #toUnsignedString(int, int)
      * @since   1.0.2

src/java.base/share/classes/java/lang/Long.java

@@ -292,11 +292,19 @@ private static BigInteger toUnsignedBigInteger(long i) {
      * <blockquote>
      *  {@code Long.toHexString(n).toUpperCase()}
      * </blockquote>
+     * <p>
+     * @apiNote
+     * {@link java.util.HexFormat} provides formatting and parsing
+     * of byte arrays and primitives to return a string or adding to an {@link Appendable}.
+     * HexFormat formats and parses uppercase or lowercase hexadecimal characters,
+     * with leading zeros and for byte arrays includes for each byte
+     * a delimiter, prefix, and suffix.
      *
      * @param   i   a {@code long} to be converted to a string.
      * @return  the string representation of the unsigned {@code long}
      *          value represented by the argument in hexadecimal
      *          (base&nbsp;16).
+     * @see java.util.HexFormat
      * @see #parseUnsignedLong(String, int)
      * @see #toUnsignedString(long, int)
      * @since   1.0.2

test/jdk/java/util/HexFormat/HexFormatTest.java

@@ -94,24 +94,24 @@ Object[][] HexStringsThrowing() {
     @DataProvider(name = "BadBytesThrowing")
     Object[][] badBytesThrowing() {
         return new Object[][]{
-                {new byte[1], 0, 2},        // bad length
-                {new byte[1], 1, 1},        // bad offset + length
-                {new byte[1], -1, 2},       // bad length
-                {new byte[1], -1, 1},       // bad offset + length
-                {new byte[1], 0, -1},       // bad length
-                {new byte[1], 1, -1},       // bad offset + length
+                {new byte[1], 0, 2},        // bad toIndex
+                {new byte[1], 1, 2},        // bad fromIndex + toIndex
+                {new byte[1], -1, 2},       // bad fromIndex
+                {new byte[1], -1, 1},       // bad fromIndex
+                {new byte[1], 0, -1},       // bad toIndex
+                {new byte[1], 1, -1},       // bad toIndex
         };
     }
 
     @DataProvider(name = "BadParseHexThrowing")
     Object[][] badParseHexThrowing() {
         return new Object[][]{
-                {"a", 0, 2, IndexOutOfBoundsException.class},        // bad length
-                {"b", 1, 1, IndexOutOfBoundsException.class},        // bad offset + length
-                {"a", -1, 2, IndexOutOfBoundsException.class},       // bad length
-                {"b", -1, 1, IndexOutOfBoundsException.class},       // bad offset + length
-                {"a", 0, -1, IndexOutOfBoundsException.class},       // bad length
-                {"b", 1, -1, IndexOutOfBoundsException.class},       // bad offset + length
+                {"a", 0, 2, IndexOutOfBoundsException.class},        // bad toIndex
+                {"b", 1, 2, IndexOutOfBoundsException.class},        // bad toIndex
+                {"a", -1, 2, IndexOutOfBoundsException.class},       // bad fromIndex
+                {"b", -1, 1, IndexOutOfBoundsException.class},       // bad fromIndex
+                {"a", 0, -1, IndexOutOfBoundsException.class},       // bad toIndex
+                {"b", 1, -1, IndexOutOfBoundsException.class},       // bad fromIndex + toIndex
                 {"76543210", 0, 7, IllegalArgumentException.class},  // odd number of digits
                 {"zz00", 0, 4, IllegalArgumentException.class},      // non-hex digits
                 {"00zz", 0, 4, IllegalArgumentException.class},      // non-hex digits
@@ -121,12 +121,12 @@ Object[][] badParseHexThrowing() {
     @DataProvider(name = "BadFromHexDigitsThrowing")
     Object[][] badHexDigitsThrowing() {
         return new Object[][]{
-                {"a", 0, 2, IndexOutOfBoundsException.class},        // bad length
-                {"b", 1, 1, IndexOutOfBoundsException.class},        // bad offset + length
-                {"a", -1, 2, IndexOutOfBoundsException.class},       // bad length
-                {"b", -1, 1, IndexOutOfBoundsException.class},       // bad offset + length
-                {"a", 0, -1, IndexOutOfBoundsException.class},       // bad length
-                {"b", 1, -1, IndexOutOfBoundsException.class},       // bad offset + length
+                {"a", 0, 2, IndexOutOfBoundsException.class},        // bad toIndex
+                {"b", 1, 2, IndexOutOfBoundsException.class},        // bad fromIndex + toIndex
+                {"a", -1, 2, IndexOutOfBoundsException.class},       // bad toIndex
+                {"b", -1, 1, IndexOutOfBoundsException.class},       // bad fromIndex + toIndex
+                {"a", 0, -1, IndexOutOfBoundsException.class},       // bad toIndex
+                {"b", 1, -1, IndexOutOfBoundsException.class},       // bad fromIndex + toIndex
         };
     }
 
@@ -309,12 +309,12 @@ static void badParseHex(String string, int offset, int length,
     }
 
     @Test(dataProvider = "BadFromHexDigitsThrowing")
-    static void badFromHexDigits(String string, int offset, int length,
+    static void badFromHexDigits(String string, int fromIndex, int toIndex,
                            Class<? extends Throwable> exClass) {
         assertThrows(exClass,
-                () -> HexFormat.of().fromHexDigits(string, offset, length));
+                () -> HexFormat.of().fromHexDigits(string, fromIndex, toIndex));
         assertThrows(exClass,
-                () -> HexFormat.of().fromHexDigitsToLong(string, offset, length));
+                () -> HexFormat.of().fromHexDigitsToLong(string, fromIndex, toIndex));
     }
 
     // Verify IAE for strings that are too long for the target primitive type
@@ -392,7 +392,7 @@ static void testParseHexStringRange(String delimiter, String prefix, String suff
         System.out.println("    formatted subrange: " +
                 s.substring(low * stride, high * stride - delimiter.length()));
         byte[] actual = hex.parseHex(s, low * stride,
-                high * stride - delimiter.length() - low * stride);
+                high * stride - delimiter.length());
         System.out.println("    parsed as: " + Arrays.toString(actual));
 
         assertEquals(actual.length, (high - low), "array length");
@@ -417,7 +417,7 @@ static void testFormatHexRangeString(String unused1, String unused2, String unus
         byte[] expected = genBytes('A', 15);
         int low = 1;
         int high = expected.length - 2;
-        String s = hex.formatHex(expected, low, high - low);
+        String s = hex.formatHex(expected, low, high);
         System.out.println("    formatted: " + s);
 
         byte[] actual = hex.parseHex(s);
@@ -448,7 +448,7 @@ static void testFormatHexRangeAppendable(String unused1, String unused2, String
         int low = 1;
         int high = expected.length - 2;
         StringBuilder sb = new StringBuilder();
-        StringBuilder s = hex.formatHex(sb, expected, low, high - low);
+        StringBuilder s = hex.formatHex(sb, expected, low, high);
         assertEquals(s, sb, "formatHex returned unknown StringBuilder");
         System.out.println("    formatted: " + s);
 
@@ -493,7 +493,7 @@ static void testFormatHexCharArrayIndexed(String delimiter, String prefix, Strin
                 s.substring(low * stride, high * stride - delimiter.length()));
         char[] chars = s.toCharArray();
         byte[] actual = hex.parseHex(chars, low * stride,
-                (high - low ) * stride - delimiter.length());
+                high * stride - delimiter.length());
         System.out.println("    parsed as: " + Arrays.toString(actual));
 
         assertEquals(actual.length, (high - low), "array length");