HexFormat converts between bytes and chars and hex-encoded strings which may include
 additional formatting markup such as prefixes, suffixes, and delimiters.
 
 There are two factories of HexFormat with preset parameters of() and
 ofDelimiter(delimiter). For other parameter combinations
 the withXXX methods return copies of HexFormat modified
 withPrefix(String), withSuffix(String), withDelimiter(String)
 or choice of withUpperCase() or withLowerCase() parameters.
 
 For primitive to hexadecimal string conversions the toHexDigits
 methods include toHexDigits(byte), toHexDigits(int), and
 toHexDigits(long), etc. The default is to use lowercase characters "0-9","a-f".
 For conversions producing uppercase hexadecimal the characters are "0-9","A-F".
 Only the HexFormat.isUpperCase() parameter is
 considered; the delimiter, prefix and suffix are not used.
 
 For hexadecimal string to primitive conversions the fromHexDigits
 methods include fromHexDigits(string),
 fromHexDigitsToLong(string), and
 fromHexDigit(int) converts a single character or codepoint.
 For conversions from hexadecimal characters the digits and uppercase and lowercase
 characters in "0-9", "a-f", and "A-F" are converted to corresponding values
 0-15. The delimiter, prefix, suffix, and uppercase parameters are not used.
 
 For byte array to formatted hexadecimal string conversions
 the formatHex methods include formatHex(byte[])
 and formatHex(Appendable, byte[]).
 The formatted output is a string or is appended to an Appendable such as
 StringBuilder or PrintStream.
 Each byte value is formatted as the prefix, two hexadecimal characters from the
 uppercase or lowercase digits, and the suffix.
 A delimiter follows each formatted value, except the last.
 For conversions producing uppercase hexadecimal strings use withUpperCase().
 
 For formatted hexadecimal string to byte array conversions the
 parseHex methods include parseHex(CharSequence) and
 parseHex(char[], offset, length).
 Each byte value is parsed from the prefix, two case insensitive hexadecimal characters,
 and the suffix. A delimiter follows each formatted value, except the last.
- API Note:
- For example, an individual byte is converted to a string of hexadecimal digits using
 toHexDigits(int)and converted from a string to a primitive value usingfromHexDigits(string).HexFormat hex = HexFormat.of(); byte b = 127; String byteStr = hex.toHexDigits(b); byte byteVal = (byte)hex.fromHexDigits(byteStr); assert(byteStr.equals("7f")); assert(b == byteVal); // The hexadecimal digits are: "7f"For a comma ( ", ") separated format with a prefix ("#") using lowercase hex digits theHexFormatis:HexFormat commaFormat = HexFormat.ofDelimiter(", ").withPrefix("#"); byte[] bytes = {0, 1, 2, 3, 124, 125, 126, 127}; String str = commaFormat.formatHex(bytes); byte[] parsed = commaFormat.parseHex(str); assert(Arrays.equals(bytes, parsed)); // The formatted string is: "#00, #01, #02, #03, #7c, #7d, #7e, #7f"For a fingerprint of byte values that uses the delimiter colon ( ":") and uppercase characters theHexFormatis:HexFormat formatFingerprint = HexFormat.ofDelimiter(":").withUpperCase(); byte[] bytes = {0, 1, 2, 3, 124, 125, 126, 127}; String str = formatFingerprint.formatHex(bytes); byte[] parsed = formatFingerprint.parseHex(str); assert(Arrays.equals(bytes, parsed)); // The formatted string is: "00:01:02:03:7C:7D:7E:7F"This is a value-based class; use of identity-sensitive operations (including reference equality ( ==), identity hash code, or synchronization) on instances ofHexFormatmay have unpredictable results and should be avoided. Theequalsmethod should be used for comparisons.This class is immutable and thread-safe. Unless otherwise noted, passing a null argument to any method will cause a NullPointerExceptionto be thrown.
- Since:
- 17
- 
Method SummaryModifier and TypeMethodDescriptionReturns the delimiter between hexadecimal values in formatted hexadecimal strings.booleanReturnstrueif the other object is aHexFormatwith the same parameters.formatHex(byte[] bytes) Returns a hexadecimal string formatted from a byte array.formatHex(byte[] bytes, int fromIndex, int toIndex) Returns a hexadecimal string formatted from a byte array range.<A extends Appendable>
 AformatHex(A out, byte[] bytes) Appends formatted hexadecimal strings from a byte array to theAppendable.<A extends Appendable>
 AformatHex(A out, byte[] bytes, int fromIndex, int toIndex) Appends formatted hexadecimal strings from a byte array range to theAppendable.static intfromHexDigit(int ch) Returns the value for the hexadecimal character or codepoint.static intfromHexDigits(CharSequence string) Returns theintvalue parsed from a string of up to eight hexadecimal characters.static intfromHexDigits(CharSequence string, int fromIndex, int toIndex) Returns theintvalue parsed from a string range of up to eight hexadecimal characters.static longfromHexDigitsToLong(CharSequence string) Returns the long value parsed from a string of up to sixteen hexadecimal characters.static longfromHexDigitsToLong(CharSequence string, int fromIndex, int toIndex) Returns the long value parsed from a string range of up to sixteen hexadecimal characters.inthashCode()Returns a hashcode for thisHexFormat.static booleanisHexDigit(int ch) Returnstrueif the character is a valid hexadecimal character or codepoint.booleanReturnstrueif the hexadecimal digits are uppercase, otherwisefalse.static HexFormatof()Returns a hexadecimal formatter with no delimiter and lowercase characters.static HexFormatofDelimiter(String delimiter) Returns a hexadecimal formatter with the delimiter and lowercase characters.byte[]parseHex(char[] chars, int fromIndex, int toIndex) Returns a byte array containing hexadecimal values parsed from a range of the character array.byte[]parseHex(CharSequence string) Returns a byte array containing hexadecimal values parsed from the string.byte[]parseHex(CharSequence string, int fromIndex, int toIndex) Returns a byte array containing hexadecimal values parsed from a range of the string.prefix()Returns the prefix used for each hexadecimal value in formatted hexadecimal strings.suffix()Returns the suffix used for each hexadecimal value in formatted hexadecimal strings.toHexDigits(byte value) Returns the two hexadecimal characters for thebytevalue.toHexDigits(char value) Returns the four hexadecimal characters for thecharvalue.toHexDigits(int value) Returns the eight hexadecimal characters for theintvalue.toHexDigits(long value) Returns the sixteen hexadecimal characters for thelongvalue.toHexDigits(long value, int digits) Returns up to sixteen hexadecimal characters for thelongvalue.toHexDigits(short value) Returns the four hexadecimal characters for theshortvalue.<A extends Appendable>
 AtoHexDigits(A out, byte value) Appends two hexadecimal characters for the byte value to theAppendable.chartoHighHexDigit(int value) Returns the hexadecimal character for the high 4 bits of the value considering it to be a byte.chartoLowHexDigit(int value) Returns the hexadecimal character for the low 4 bits of the value considering it to be a byte.toString()Returns a description of the formatter parameters for uppercase, delimiter, prefix, and suffix.withDelimiter(String delimiter) Returns a copy of thisHexFormatwith the delimiter.Returns a copy of thisHexFormatto use lowercase hexadecimal characters.withPrefix(String prefix) Returns a copy of thisHexFormatwith the prefix.withSuffix(String suffix) Returns a copy of thisHexFormatwith the suffix.Returns a copy of thisHexFormatto use uppercase hexadecimal characters.
- 
Method Details- 
ofReturns a hexadecimal formatter with no delimiter and lowercase characters. The delimiter, prefix, and suffix are empty. The methodswithDelimiter,withUpperCase,withLowerCase,withPrefix, andwithSuffixreturn copies of formatters with new parameters.- Returns:
- a hexadecimal formatter with no delimiter and lowercase characters
 
- 
ofDelimiterReturns a hexadecimal formatter with the delimiter and lowercase characters. The prefix and suffix are empty. The methodswithDelimiter,withUpperCase,withLowerCase,withPrefix, andwithSuffixreturn copies of formatters with new parameters.- Parameters:
- delimiter- a delimiter, non-null, may be empty
- Returns:
- a HexFormatwith the delimiter and lowercase characters
 
- 
withDelimiterReturns a copy of thisHexFormatwith the delimiter.- Parameters:
- delimiter- the delimiter, non-null, may be empty
- Returns:
- a copy of this HexFormatwith the delimiter
 
- 
withPrefixReturns a copy of thisHexFormatwith the prefix.- Parameters:
- prefix- a prefix, non-null, may be empty
- Returns:
- a copy of this HexFormatwith the prefix
 
- 
withSuffixReturns a copy of thisHexFormatwith the suffix.- Parameters:
- suffix- a suffix, non-null, may be empty
- Returns:
- a copy of this HexFormatwith the suffix
 
- 
withUpperCaseReturns a copy of thisHexFormatto use uppercase hexadecimal characters. The uppercase hexadecimal characters are"0-9", "A-F".- Returns:
- a copy of this HexFormatwith uppercase hexadecimal characters
 
- 
withLowerCaseReturns a copy of thisHexFormatto use lowercase hexadecimal characters. The lowercase hexadecimal characters are"0-9", "a-f".- Returns:
- a copy of this HexFormatwith lowercase hexadecimal characters
 
- 
delimiterReturns the delimiter between hexadecimal values in formatted hexadecimal strings.- Returns:
- the delimiter, non-null, may be empty ""
 
- 
prefixReturns the prefix used for each hexadecimal value in formatted hexadecimal strings.- Returns:
- the prefix, non-null, may be empty ""
 
- 
suffixReturns the suffix used for each hexadecimal value in formatted hexadecimal strings.- Returns:
- the suffix, non-null, may be empty ""
 
- 
isUpperCasepublic boolean isUpperCase()Returnstrueif the hexadecimal digits are uppercase, otherwisefalse.- Returns:
- trueif the hexadecimal digits are uppercase, otherwise- false
 
- 
formatHexReturns a hexadecimal string formatted from a byte array. Each byte value is formatted as the prefix, two hexadecimal characters selected from uppercase or lowercase digits, and the suffix. A delimiter follows each formatted value, except the last. The behavior is equivalent toformatHex(bytes, 0, bytes.length)).- Parameters:
- bytes- a non-null array of bytes
- Returns:
- a string hexadecimal formatting of the byte array
 
- 
formatHexReturns a hexadecimal string formatted from a byte array range. Each byte value is formatted as the prefix, two hexadecimal characters selected from uppercase or lowercase digits, and the suffix. A delimiter follows each formatted value, except the last.- Parameters:
- bytes- a non-null array of bytes
- fromIndex- the initial index of the range, inclusive
- toIndex- the final index of the range, exclusive
- Returns:
- a string hexadecimal formatting each byte of the array range
- Throws:
- IndexOutOfBoundsException- if the array range is out of bounds
 
- 
formatHexAppends formatted hexadecimal strings from a byte array to theAppendable. Each byte value is formatted as the prefix, two hexadecimal characters selected from uppercase or lowercase digits, and the suffix. A delimiter follows each formatted value, except the last. The formatted hexadecimal strings are appended in zero or more calls to theAppendablemethods.- Type Parameters:
- A- The type of- Appendable
- Parameters:
- out- an- Appendable, non-null
- bytes- a byte array
- Returns:
- the Appendable
- Throws:
- UncheckedIOException- if an I/O exception occurs appending to the output
 
- 
formatHexAppends formatted hexadecimal strings from a byte array range to theAppendable. Each byte value is formatted as the prefix, two hexadecimal characters selected from uppercase or lowercase digits, and the suffix. A delimiter follows each formatted value, except the last. The formatted hexadecimal strings are appended in zero or more calls to theAppendablemethods.- Type Parameters:
- A- The type of- Appendable
- Parameters:
- out- an- Appendable, non-null
- bytes- a byte array, non-null
- fromIndex- the initial index of the range, inclusive
- toIndex- the final index of the range, exclusive.
- Returns:
- the Appendable
- Throws:
- IndexOutOfBoundsException- if the array range is out of bounds
- UncheckedIOException- if an I/O exception occurs appending to the output
 
- 
parseHexReturns a byte array containing hexadecimal values parsed from the string. Each byte value is parsed from the prefix, two case insensitive hexadecimal characters, and the suffix. A delimiter follows each formatted value, except the last. The delimiters, prefixes, and suffixes strings must be present; they may be empty strings. A valid string consists only of the above format.- Parameters:
- string- a string containing the byte values with prefix, hexadecimal digits, suffix, and delimiters
- Returns:
- a byte array with the values parsed from the string
- Throws:
- IllegalArgumentException- if the prefix or suffix is not present for each byte value, the byte values are not hexadecimal characters, or if the delimiter is not present after all but the last byte value
 
- 
parseHexReturns a byte array containing hexadecimal values parsed from a range of the string. Each byte value is parsed from the prefix, two case insensitive hexadecimal characters, and the suffix. A delimiter follows each formatted value, except the last. The delimiters, prefixes, and suffixes strings must be present; they may be empty strings. A valid string consists only of the above format.- Parameters:
- string- a string range containing hexadecimal digits, delimiters, prefix, and suffix.
- fromIndex- the initial index of the range, inclusive
- toIndex- the final index of the range, exclusive.
- Returns:
- a byte array with the values parsed from the string range
- Throws:
- IllegalArgumentException- if the prefix or suffix is not present for each byte value, the byte values are not hexadecimal characters, or if the delimiter is not present after all but the last byte value
- IndexOutOfBoundsException- if the string range is out of bounds
 
- 
parseHexpublic byte[] parseHex(char[] chars, int fromIndex, int toIndex) Returns a byte array containing hexadecimal values parsed from a range of the character array. Each byte value is parsed from the prefix, two case insensitive hexadecimal characters, and the suffix. A delimiter follows each formatted value, except the last. The delimiters, prefixes, and suffixes strings must be present; they may be empty strings. A valid character array range consists only of the above format.- Parameters:
- chars- a character array range containing an even number of hexadecimal digits, delimiters, prefix, and suffix.
- fromIndex- the initial index of the range, inclusive
- toIndex- the final index of the range, exclusive.
- Returns:
- a byte array with the values parsed from the character array range
- Throws:
- IllegalArgumentException- if the prefix or suffix is not present for each byte value, the byte values are not hexadecimal characters, or if the delimiter is not present after all but the last byte value
- IndexOutOfBoundsException- if the character array range is out of bounds
 
- 
toLowHexDigitpublic char toLowHexDigit(int value) Returns the hexadecimal character for the low 4 bits of the value considering it to be a byte. If the parameterisUpperCase()istruethe character returned for values10-15is uppercase"A-F", otherwise the character returned is lowercase"a-f". The values in the range0-9are returned as"0-9".- Parameters:
- value- a value, only the low 4 bits- 0-3of the value are used
- Returns:
- the hexadecimal character for the low 4 bits 0-3of the value
 
- 
toHighHexDigitpublic char toHighHexDigit(int value) Returns the hexadecimal character for the high 4 bits of the value considering it to be a byte. If the parameterisUpperCase()istruethe character returned for values10-15is uppercase"A-F", otherwise the character returned is lowercase"a-f". The values in the range0-9are returned as"0-9".- Parameters:
- value- a value, only bits- 4-7of the value are used
- Returns:
- the hexadecimal character for the bits 4-7of the value
 
- 
toHexDigitsAppends two hexadecimal characters for the byte value to theAppendable. Each nibble (4 bits) from most significant to least significant of the value is formatted as if bytoLowHexDigit(nibble). The hexadecimal characters are appended in one or more calls to theAppendablemethods. The delimiter, prefix and suffix are not used.- Type Parameters:
- A- The type of- Appendable
- Parameters:
- out- an- Appendable, non-null
- value- a byte value
- Returns:
- the Appendable
- Throws:
- UncheckedIOException- if an I/O exception occurs appending to the output
 
- 
toHexDigitsReturns the two hexadecimal characters for thebytevalue. Each nibble (4 bits) from most significant to least significant of the value is formatted as if bytoLowHexDigit(nibble). The delimiter, prefix and suffix are not used.- Parameters:
- value- a byte value
- Returns:
- the two hexadecimal characters for the byte value
 
- 
toHexDigitsReturns the four hexadecimal characters for thecharvalue. Each nibble (4 bits) from most significant to least significant of the value is formatted as if bytoLowHexDigit(nibble). The delimiter, prefix and suffix are not used.- Parameters:
- value- a- charvalue
- Returns:
- the four hexadecimal characters for the charvalue
 
- 
toHexDigitsReturns the four hexadecimal characters for theshortvalue. Each nibble (4 bits) from most significant to least significant of the value is formatted as if bytoLowHexDigit(nibble). The delimiter, prefix and suffix are not used.- Parameters:
- value- a- shortvalue
- Returns:
- the four hexadecimal characters for the shortvalue
 
- 
toHexDigitsReturns the eight hexadecimal characters for theintvalue. Each nibble (4 bits) from most significant to least significant of the value is formatted as if bytoLowHexDigit(nibble). The delimiter, prefix and suffix are not used.- Parameters:
- value- an- intvalue
- Returns:
- the eight hexadecimal characters for the intvalue
- See Also:
 
- 
toHexDigitsReturns the sixteen hexadecimal characters for thelongvalue. Each nibble (4 bits) from most significant to least significant of the value is formatted as if bytoLowHexDigit(nibble). The delimiter, prefix and suffix are not used.- Parameters:
- value- a- longvalue
- Returns:
- the sixteen hexadecimal characters for the longvalue
- See Also:
 
- 
toHexDigitsReturns up to sixteen hexadecimal characters for thelongvalue. Each nibble (4 bits) from most significant to least significant of the value is formatted as if bytoLowHexDigit(nibble). The delimiter, prefix and suffix are not used.- Parameters:
- value- a- longvalue
- digits- the number of hexadecimal digits to return, 0 to 16
- Returns:
- the hexadecimal characters for the longvalue
- Throws:
- IllegalArgumentException- if- digitsis negative or greater than 16
 
- 
isHexDigitpublic static boolean isHexDigit(int ch) Returnstrueif the character is a valid hexadecimal character or codepoint. The valid hexadecimal characters are:- '0' ('\u0030')through- '9' ('\u0039')inclusive,
- 'A' ('\u0041')through- 'F' ('\u0046')inclusive, and
- 'a' ('\u0061')through- 'f' ('\u0066')inclusive.
 - Parameters:
- ch- a codepoint
- Returns:
- trueif the character is valid a hexadecimal character, otherwise- false
 
- 
fromHexDigitpublic static int fromHexDigit(int ch) Returns the value for the hexadecimal character or codepoint. The value is:- (ch - '0')for- '0'through- '9'inclusive,
- (ch - 'A' + 10)for- 'A'through- 'F'inclusive, and
- (ch - 'a' + 10)for- 'a'through- 'f'inclusive.
 - Parameters:
- ch- a character or codepoint
- Returns:
- the value 0-15
- Throws:
- NumberFormatException- if the codepoint is not a hexadecimal character
 
- 
fromHexDigitsReturns theintvalue parsed from a string of up to eight hexadecimal characters. The hexadecimal characters are parsed from most significant to least significant usingfromHexDigit(int)to form an unsigned value. The value is zero extended to 32 bits and is returned as anint.- API Note:
- Integer.parseInt(s, 16)and- Integer.parseUnsignedInt(s, 16)are similar but allow all Unicode hexadecimal digits defined by- Character.digit(ch, 16).- HexFormatuses only hexadecimal characters- "0-9",- "A-F"and- "a-f". Signed hexadecimal strings can be parsed with- Integer.parseInt(String, int).
- Parameters:
- string- a CharSequence containing up to eight hexadecimal characters
- Returns:
- the value parsed from the string
- Throws:
- IllegalArgumentException- if the string length is greater than eight (8) or if any of the characters is not a hexadecimal character
 
- 
fromHexDigitsReturns theintvalue parsed from a string range of up to eight hexadecimal characters. The characters in the rangefromIndextotoIndex, exclusive, are parsed from most significant to least significant usingfromHexDigit(int)to form an unsigned value. The value is zero extended to 32 bits and is returned as anint.- API Note:
- Integer.parseInt(s, 16)and- Integer.parseUnsignedInt(s, 16)are similar but allow all Unicode hexadecimal digits defined by- Character.digit(ch, 16).- HexFormatuses only hexadecimal characters- "0-9",- "A-F"and- "a-f". Signed hexadecimal strings can be parsed with- Integer.parseInt(String, int).
- Parameters:
- string- a CharSequence containing the characters
- fromIndex- the initial index of the range, inclusive
- toIndex- the final index of the range, exclusive.
- Returns:
- the value parsed from the string range
- Throws:
- IndexOutOfBoundsException- if the range is out of bounds for the- CharSequence
- IllegalArgumentException- if length of the range is greater than eight (8) or if any of the characters is not a hexadecimal character
 
- 
fromHexDigitsToLongReturns the long value parsed from a string of up to sixteen hexadecimal characters. The hexadecimal characters are parsed from most significant to least significant usingfromHexDigit(int)to form an unsigned value. The value is zero extended to 64 bits and is returned as along.- API Note:
- Long.parseLong(s, 16)and- Long.parseUnsignedLong(s, 16)are similar but allow all Unicode hexadecimal digits defined by- Character.digit(ch, 16).- HexFormatuses only hexadecimal characters- "0-9",- "A-F"and- "a-f". Signed hexadecimal strings can be parsed with- Long.parseLong(String, int).
- Parameters:
- string- a CharSequence containing up to sixteen hexadecimal characters
- Returns:
- the value parsed from the string
- Throws:
- IllegalArgumentException- if the string length is greater than sixteen (16) or if any of the characters is not a hexadecimal character
 
- 
fromHexDigitsToLongReturns the long value parsed from a string range of up to sixteen hexadecimal characters. The characters in the rangefromIndextotoIndex, exclusive, are parsed from most significant to least significant usingfromHexDigit(int)to form an unsigned value. The value is zero extended to 64 bits and is returned as along.- API Note:
- Long.parseLong(s, 16)and- Long.parseUnsignedLong(s, 16)are similar but allow all Unicode hexadecimal digits defined by- Character.digit(ch, 16).- HexFormatuses only hexadecimal characters- "0-9",- "A-F"and- "a-f". Signed hexadecimal strings can be parsed with- Long.parseLong(String, int).
- Parameters:
- string- a CharSequence containing the characters
- fromIndex- the initial index of the range, inclusive
- toIndex- the final index of the range, exclusive.
- Returns:
- the value parsed from the string range
- Throws:
- IndexOutOfBoundsException- if the range is out of bounds for the- CharSequence
- IllegalArgumentException- if the length of the range is greater than sixteen (16) or if any of the characters is not a hexadecimal character
 
- 
equalsReturnstrueif the other object is aHexFormatwith the same parameters.
- 
hashCodepublic int hashCode()Returns a hashcode for thisHexFormat.
- 
toStringReturns a description of the formatter parameters for uppercase, delimiter, prefix, and suffix.
 
-