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 theHexFormat
is: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 theHexFormat
is: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 ofHexFormat
may have unpredictable results and should be avoided. Theequals
method 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
NullPointerException
to be thrown. - Since:
- 17
-
Method Summary
Modifier and TypeMethodDescriptionReturns the delimiter between hexadecimal values in formatted hexadecimal strings.boolean
Returnstrue
if the other object is aHexFormat
with 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 int
fromHexDigit
(int ch) Returns the value for the hexadecimal character or codepoint.static int
fromHexDigits
(CharSequence string) Returns theint
value parsed from a string of up to eight hexadecimal characters.static int
fromHexDigits
(CharSequence string, int fromIndex, int toIndex) Returns theint
value parsed from a string range of up to eight hexadecimal characters.static long
fromHexDigitsToLong
(CharSequence string) Returns the long value parsed from a string of up to sixteen hexadecimal characters.static long
fromHexDigitsToLong
(CharSequence string, int fromIndex, int toIndex) Returns the long value parsed from a string range of up to sixteen hexadecimal characters.int
hashCode()
Returns a hashcode for thisHexFormat
.static boolean
isHexDigit
(int ch) Returnstrue
if the character is a valid hexadecimal character or codepoint.boolean
Returnstrue
if the hexadecimal digits are uppercase, otherwisefalse
.static HexFormat
of()
Returns a hexadecimal formatter with no delimiter and lowercase characters.static HexFormat
ofDelimiter
(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 thebyte
value.toHexDigits
(char value) Returns the four hexadecimal characters for thechar
value.toHexDigits
(int value) Returns the eight hexadecimal characters for theint
value.toHexDigits
(long value) Returns the sixteen hexadecimal characters for thelong
value.toHexDigits
(long value, int digits) Returns up to sixteen hexadecimal characters for thelong
value.toHexDigits
(short value) Returns the four hexadecimal characters for theshort
value.<A extends Appendable>
AtoHexDigits
(A out, byte value) Appends two hexadecimal characters for the byte value to theAppendable
.char
toHighHexDigit
(int value) Returns the hexadecimal character for the high 4 bits of the value considering it to be a byte.char
toLowHexDigit
(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 thisHexFormat
with the delimiter.Returns a copy of thisHexFormat
to use lowercase hexadecimal characters.withPrefix
(String prefix) Returns a copy of thisHexFormat
with the prefix.withSuffix
(String suffix) Returns a copy of thisHexFormat
with the suffix.Returns a copy of thisHexFormat
to use uppercase hexadecimal characters.
-
Method Details
-
of
Returns a hexadecimal formatter with no delimiter and lowercase characters. The delimiter, prefix, and suffix are empty. The methodswithDelimiter
,withUpperCase
,withLowerCase
,withPrefix
, andwithSuffix
return copies of formatters with new parameters.- Returns:
- a hexadecimal formatter with no delimiter and lowercase characters
-
ofDelimiter
Returns a hexadecimal formatter with the delimiter and lowercase characters. The prefix and suffix are empty. The methodswithDelimiter
,withUpperCase
,withLowerCase
,withPrefix
, andwithSuffix
return copies of formatters with new parameters.- Parameters:
delimiter
- a delimiter, non-null, may be empty- Returns:
- a
HexFormat
with the delimiter and lowercase characters
-
withDelimiter
Returns a copy of thisHexFormat
with the delimiter.- Parameters:
delimiter
- the delimiter, non-null, may be empty- Returns:
- a copy of this
HexFormat
with the delimiter
-
withPrefix
Returns a copy of thisHexFormat
with the prefix.- Parameters:
prefix
- a prefix, non-null, may be empty- Returns:
- a copy of this
HexFormat
with the prefix
-
withSuffix
Returns a copy of thisHexFormat
with the suffix.- Parameters:
suffix
- a suffix, non-null, may be empty- Returns:
- a copy of this
HexFormat
with the suffix
-
withUpperCase
Returns a copy of thisHexFormat
to use uppercase hexadecimal characters. The uppercase hexadecimal characters are"0-9", "A-F"
.- Returns:
- a copy of this
HexFormat
with uppercase hexadecimal characters
-
withLowerCase
Returns a copy of thisHexFormat
to use lowercase hexadecimal characters. The lowercase hexadecimal characters are"0-9", "a-f"
.- Returns:
- a copy of this
HexFormat
with lowercase hexadecimal characters
-
delimiter
Returns the delimiter between hexadecimal values in formatted hexadecimal strings.- Returns:
- the delimiter, non-null, may be empty
""
-
prefix
Returns the prefix used for each hexadecimal value in formatted hexadecimal strings.- Returns:
- the prefix, non-null, may be empty
""
-
suffix
Returns the suffix used for each hexadecimal value in formatted hexadecimal strings.- Returns:
- the suffix, non-null, may be empty
""
-
isUpperCase
public boolean isUpperCase()Returnstrue
if the hexadecimal digits are uppercase, otherwisefalse
.- Returns:
true
if the hexadecimal digits are uppercase, otherwisefalse
-
formatHex
Returns 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
-
formatHex
Returns 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 bytesfromIndex
- the initial index of the range, inclusivetoIndex
- 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
-
formatHex
Appends 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 theAppendable
methods.- Type Parameters:
A
- The type ofAppendable
- Parameters:
out
- anAppendable
, non-nullbytes
- a byte array- Returns:
- the
Appendable
- Throws:
UncheckedIOException
- if an I/O exception occurs appending to the output
-
formatHex
Appends 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 theAppendable
methods.- Type Parameters:
A
- The type ofAppendable
- Parameters:
out
- anAppendable
, non-nullbytes
- a byte array, non-nullfromIndex
- the initial index of the range, inclusivetoIndex
- the final index of the range, exclusive.- Returns:
- the
Appendable
- Throws:
IndexOutOfBoundsException
- if the array range is out of boundsUncheckedIOException
- if an I/O exception occurs appending to the output
-
parseHex
Returns 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
-
parseHex
Returns 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, inclusivetoIndex
- 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 valueIndexOutOfBoundsException
- if the string range is out of bounds
-
parseHex
public 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, inclusivetoIndex
- 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 valueIndexOutOfBoundsException
- if the character array range is out of bounds
-
toLowHexDigit
public 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()
istrue
the character returned for values10-15
is uppercase"A-F"
, otherwise the character returned is lowercase"a-f"
. The values in the range0-9
are returned as"0-9"
.- Parameters:
value
- a value, only the low 4 bits0-3
of the value are used- Returns:
- the hexadecimal character for the low 4 bits
0-3
of the value
-
toHighHexDigit
public 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()
istrue
the character returned for values10-15
is uppercase"A-F"
, otherwise the character returned is lowercase"a-f"
. The values in the range0-9
are returned as"0-9"
.- Parameters:
value
- a value, only bits4-7
of the value are used- Returns:
- the hexadecimal character for the bits
4-7
of the value
-
toHexDigits
Appends 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 theAppendable
methods. The delimiter, prefix and suffix are not used.- Type Parameters:
A
- The type ofAppendable
- Parameters:
out
- anAppendable
, non-nullvalue
- a byte value- Returns:
- the
Appendable
- Throws:
UncheckedIOException
- if an I/O exception occurs appending to the output
-
toHexDigits
Returns the two hexadecimal characters for thebyte
value. 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
-
toHexDigits
Returns the four hexadecimal characters for thechar
value. 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
- achar
value- Returns:
- the four hexadecimal characters for the
char
value
-
toHexDigits
Returns the four hexadecimal characters for theshort
value. 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
- ashort
value- Returns:
- the four hexadecimal characters for the
short
value
-
toHexDigits
Returns the eight hexadecimal characters for theint
value. 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
- anint
value- Returns:
- the eight hexadecimal characters for the
int
value - See Also:
-
toHexDigits
Returns the sixteen hexadecimal characters for thelong
value. 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
- along
value- Returns:
- the sixteen hexadecimal characters for the
long
value - See Also:
-
toHexDigits
Returns up to sixteen hexadecimal characters for thelong
value. 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
- along
valuedigits
- the number of hexadecimal digits to return, 0 to 16- Returns:
- the hexadecimal characters for the
long
value - Throws:
IllegalArgumentException
- ifdigits
is negative or greater than 16
-
isHexDigit
public static boolean isHexDigit(int ch) Returnstrue
if 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:
true
if the character is valid a hexadecimal character, otherwisefalse
-
fromHexDigit
public 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
-
fromHexDigits
Returns theint
value 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)
andInteger.parseUnsignedInt(s, 16)
are similar but allow all Unicode hexadecimal digits defined byCharacter.digit(ch, 16)
.HexFormat
uses only hexadecimal characters"0-9"
,"A-F"
and"a-f"
. Signed hexadecimal strings can be parsed withInteger.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
-
fromHexDigits
Returns theint
value parsed from a string range of up to eight hexadecimal characters. The characters in the rangefromIndex
totoIndex
, 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)
andInteger.parseUnsignedInt(s, 16)
are similar but allow all Unicode hexadecimal digits defined byCharacter.digit(ch, 16)
.HexFormat
uses only hexadecimal characters"0-9"
,"A-F"
and"a-f"
. Signed hexadecimal strings can be parsed withInteger.parseInt(String, int)
.- Parameters:
string
- a CharSequence containing the charactersfromIndex
- the initial index of the range, inclusivetoIndex
- 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 theCharSequence
IllegalArgumentException
- if length of the range is greater than eight (8) or if any of the characters is not a hexadecimal character
-
fromHexDigitsToLong
Returns 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)
andLong.parseUnsignedLong(s, 16)
are similar but allow all Unicode hexadecimal digits defined byCharacter.digit(ch, 16)
.HexFormat
uses only hexadecimal characters"0-9"
,"A-F"
and"a-f"
. Signed hexadecimal strings can be parsed withLong.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
-
fromHexDigitsToLong
Returns the long value parsed from a string range of up to sixteen hexadecimal characters. The characters in the rangefromIndex
totoIndex
, 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)
andLong.parseUnsignedLong(s, 16)
are similar but allow all Unicode hexadecimal digits defined byCharacter.digit(ch, 16)
.HexFormat
uses only hexadecimal characters"0-9"
,"A-F"
and"a-f"
. Signed hexadecimal strings can be parsed withLong.parseLong(String, int)
.- Parameters:
string
- a CharSequence containing the charactersfromIndex
- the initial index of the range, inclusivetoIndex
- 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 theCharSequence
IllegalArgumentException
- if the length of the range is greater than sixteen (16) or if any of the characters is not a hexadecimal character
-
equals
Returnstrue
if the other object is aHexFormat
with the same parameters. -
hashCode
public int hashCode()Returns a hashcode for thisHexFormat
. -
toString
Returns a description of the formatter parameters for uppercase, delimiter, prefix, and suffix.
-