Hex formatting and parsing utility

Summary

A hexadecimal formatting and parsing API is added to java.util.

Problem

Within OpenJDK, there are several different implementations of formatting and parsing of hexadecimal strings. Adding a supported API allows refactoring to a common and efficient implementation.

Common to the existing implementations are the choice of delimiter between hexadecimal values and the choice of uppercase or lowercase letters. Existing uses have prefixes and/or suffixes for individual values. Producing strings from a byte array is common as is appending to an existing StringBuffer. Existing conversions of primitive values from and to hexadecimal are spread across several APIs and classes including the wrapper types and Character.

Solution

The java.util.HexFormat class is introduced to provide static factories returning HexFormat instances with the choice of delimiter, prefix, suffix, and uppercase or lowercase. The HexFormat class is final, immutable and thread safe and is a value-based class. The methods directly support conversions to and from byte arrays, the most common case. Primitive types can be converted to and from hexadecimal using HexFormat parameters.

The API proposed has been modified to use the same indexing model that is used arrays and strings based on 'fromIndex' and 'toIndex'. The earlier draft was based on 'index' and 'length'. Using the same indexing model in HexFormat as is used for other operations can make it easier to prevent bugs related to indexing.

Informative links will be added to Integer.toHexString() and Long.toHexString() to make developers aware of HexFormat as an alternative.

Specification

public final class java.util.HexFormat {
  public static java.util.HexFormat of();
  public static java.util.HexFormat ofDelimiter(java.lang.String);
  public java.util.HexFormat withDelimiter(java.lang.String);
  public java.util.HexFormat withPrefix(java.lang.String);
  public java.util.HexFormat withSuffix(java.lang.String);
  public java.util.HexFormat withUpperCase();
  public java.util.HexFormat withLowerCase();
  public java.lang.String delimiter();
  public java.lang.String prefix();
  public java.lang.String suffix();
  public boolean isUpperCase();
  public java.lang.String formatHex(byte[]);

  public java.lang.String formatHex(byte[], int, int);
  public <A extends java.lang.Appendable> A formatHex(A, byte[]);
  public <A extends java.lang.Appendable> A formatHex(A, byte[], int, int);
  public byte[] parseHex(java.lang.CharSequence);

  public byte[] parseHex(java.lang.CharSequence, int, int);
  public byte[] parseHex(char[], int, int);
  public char toLowHexDigit(int);
  public char toHighHexDigit(int);
  public java.lang.String toHexDigits(byte);
  public <A extends java.lang.Appendable> A toHexDigits(A, byte);
  public java.lang.String toHexDigits(char);
  public java.lang.String toHexDigits(short);
  public java.lang.String toHexDigits(int);
  public java.lang.String toHexDigits(long);
  public java.lang.String toHexDigits(long, int);
  public boolean isHexDigit(int);
  public int fromHexDigit(int);
  public int fromHexDigits(java.lang.CharSequence);
  public int fromHexDigits(java.lang.CharSequence, int, int);
  public long fromHexDigitsToLong(java.lang.CharSequence);
  public long fromHexDigitsToLong(java.lang.CharSequence, int, int);
  public boolean equals(java.lang.Object);
  public int hashCode();
  public java.lang.String toString();
}

public class java.lang.Integer {
    // An informative link to java.util.HexFormat is added to the javadoc for method toHexString().
}

public class java.lang.Long {
    // An informative link to java.util.HexFormat is added to the javadoc for method toHexString().
}

Details provided in attached javadoc hexformat-7.zip. hexformat-7.zip contains javadoc clarifications and formatting improvements as compared to hexformat-4.zip.

The latest javadoc is available at: http://cr.openjdk.java.net/~rriggs/8251989-hex-formatter/java.base/java/util/HexFormat.html