public final class HexFormat
extends java.lang.Object
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.
| Modifier and Type | Method and Description |
|---|---|
java.lang.String |
delimiter()
Returns the delimiter between hexadecimal values in formatted hexadecimal strings.
|
boolean |
equals(java.lang.Object o)
Returns
true if the other object is a HexFormat
with the same parameters. |
<A extends java.lang.Appendable> |
formatHex(A out,
byte[] bytes)
Appends formatted hexadecimal strings from a byte array to the
Appendable. |
<A extends java.lang.Appendable> |
formatHex(A out,
byte[] bytes,
int fromIndex,
int toIndex)
Appends formatted hexadecimal strings from a byte array range to the
Appendable. |
java.lang.String |
formatHex(byte[] bytes)
Returns a hexadecimal string formatted from a byte array.
|
java.lang.String |
formatHex(byte[] bytes,
int fromIndex,
int toIndex)
Returns a hexadecimal string formatted from a byte array range.
|
static int |
fromHexDigit(int ch)
Returns the value for the hexadecimal character or codepoint.
|
static int |
fromHexDigits(java.lang.CharSequence string)
Returns the
int value parsed from a string of up to eight hexadecimal characters. |
static int |
fromHexDigits(java.lang.CharSequence string,
int fromIndex,
int toIndex)
Returns the
int value parsed from a string range of up to eight hexadecimal
characters. |
static long |
fromHexDigitsToLong(java.lang.CharSequence string)
Returns the long value parsed from a string of up to sixteen hexadecimal characters.
|
static long |
fromHexDigitsToLong(java.lang.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 this
HexFormat. |
static boolean |
isHexDigit(int ch)
Returns
true if the character is a valid hexadecimal character or codepoint. |
boolean |
isUpperCase()
Returns
true if the hexadecimal digits are uppercase,
otherwise false. |
static HexFormat |
of()
Returns a hexadecimal formatter with no delimiter and lowercase characters.
|
static HexFormat |
ofDelimiter(java.lang.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(java.lang.CharSequence string)
Returns a byte array containing hexadecimal values parsed from the string.
|
byte[] |
parseHex(java.lang.CharSequence string,
int fromIndex,
int toIndex)
Returns a byte array containing hexadecimal values parsed from a range of the string.
|
java.lang.String |
prefix()
Returns the prefix used for each hexadecimal value in formatted hexadecimal strings.
|
java.lang.String |
suffix()
Returns the suffix used for each hexadecimal value in formatted hexadecimal strings.
|
<A extends java.lang.Appendable> |
toHexDigits(A out,
byte value)
Appends two hexadecimal characters for the byte value to the
Appendable. |
java.lang.String |
toHexDigits(byte value)
Returns the two hexadecimal characters for the
byte value. |
java.lang.String |
toHexDigits(char value)
Returns the four hexadecimal characters for the
char value. |
java.lang.String |
toHexDigits(int value)
Returns the eight hexadecimal characters for the
int value. |
java.lang.String |
toHexDigits(long value)
Returns the sixteen hexadecimal characters for the
long value. |
java.lang.String |
toHexDigits(long value,
int digits)
Returns up to sixteen hexadecimal characters for the
long value. |
java.lang.String |
toHexDigits(short value)
Returns the four hexadecimal characters for the
short value. |
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.
|
java.lang.String |
toString()
Returns a description of the formatter parameters for uppercase,
delimiter, prefix, and suffix.
|
HexFormat |
withDelimiter(java.lang.String delimiter)
Returns a copy of this
HexFormat with the delimiter. |
HexFormat |
withLowerCase()
Returns a copy of this
HexFormat to use lowercase hexadecimal characters. |
HexFormat |
withPrefix(java.lang.String prefix)
Returns a copy of this
HexFormat with the prefix. |
HexFormat |
withSuffix(java.lang.String suffix)
Returns a copy of this
HexFormat with the suffix. |
HexFormat |
withUpperCase()
Returns a copy of this
HexFormat to use uppercase hexadecimal characters. |
public static HexFormat of()
withDelimiter,
withUpperCase, withLowerCase,
withPrefix, and withSuffix
return copies of formatters with new parameters.public static HexFormat ofDelimiter(java.lang.String delimiter)
withDelimiter,
withUpperCase, withLowerCase,
withPrefix, and withSuffix
return copies of formatters with new parameters.delimiter - a delimiter, non-null, may be emptyHexFormat with the delimiter and lowercase characterspublic HexFormat withDelimiter(java.lang.String delimiter)
HexFormat with the delimiter.delimiter - the delimiter, non-null, may be emptyHexFormat with the delimiterpublic HexFormat withPrefix(java.lang.String prefix)
HexFormat with the prefix.prefix - a prefix, non-null, may be emptyHexFormat with the prefixpublic HexFormat withSuffix(java.lang.String suffix)
HexFormat with the suffix.suffix - a suffix, non-null, may be emptyHexFormat with the suffixpublic HexFormat withUpperCase()
HexFormat to use uppercase hexadecimal characters.
The uppercase hexadecimal characters are "0-9", "A-F".HexFormat with uppercase hexadecimal characterspublic HexFormat withLowerCase()
HexFormat to use lowercase hexadecimal characters.
The lowercase hexadecimal characters are "0-9", "a-f".HexFormat with lowercase hexadecimal characterspublic java.lang.String delimiter()
""public java.lang.String prefix()
""public java.lang.String suffix()
""public boolean isUpperCase()
true if the hexadecimal digits are uppercase,
otherwise false.true if the hexadecimal digits are uppercase,
otherwise falsepublic java.lang.String formatHex(byte[] bytes)
formatHex(bytes, 0, bytes.length)).bytes - a non-null array of bytespublic java.lang.String formatHex(byte[] bytes,
int fromIndex,
int toIndex)
bytes - a non-null array of bytesfromIndex - the initial index of the range, inclusivetoIndex - the final index of the range, exclusivejava.lang.IndexOutOfBoundsException - if the array range is out of boundspublic <A extends java.lang.Appendable> A formatHex(A out,
byte[] bytes)
Appendable.
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 the Appendable methods.A - The type of Appendableout - an Appendable, non-nullbytes - a byte arrayAppendablejava.io.UncheckedIOException - if an I/O exception occurs appending to the outputpublic <A extends java.lang.Appendable> A formatHex(A out,
byte[] bytes,
int fromIndex,
int toIndex)
Appendable.
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 the Appendable methods.A - The type of Appendableout - an Appendable, non-nullbytes - a byte array, non-nullfromIndex - the initial index of the range, inclusivetoIndex - the final index of the range, exclusive.Appendablejava.lang.IndexOutOfBoundsException - if the array range is out of boundsjava.io.UncheckedIOException - if an I/O exception occurs appending to the outputpublic byte[] parseHex(java.lang.CharSequence string)
string - a string containing the byte values with prefix, hexadecimal digits, suffix,
and delimitersjava.lang.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 valuepublic byte[] parseHex(java.lang.CharSequence string,
int fromIndex,
int toIndex)
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.java.lang.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 valuejava.lang.IndexOutOfBoundsException - if the string range is out of boundspublic byte[] parseHex(char[] chars,
int fromIndex,
int toIndex)
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.java.lang.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 valuejava.lang.IndexOutOfBoundsException - if the character array range is out of boundspublic char toLowHexDigit(int value)
isUpperCase() is true the
character returned for values 10-15 is uppercase "A-F",
otherwise the character returned is lowercase "a-f".
The values in the range 0-9 are returned as "0-9".value - a value, only the low 4 bits 0-3 of the value are used0-3 of the valuepublic char toHighHexDigit(int value)
isUpperCase() is true the
character returned for values 10-15 is uppercase "A-F",
otherwise the character returned is lowercase "a-f".
The values in the range 0-9 are returned as "0-9".value - a value, only bits 4-7 of the value are used4-7 of the valuepublic <A extends java.lang.Appendable> A toHexDigits(A out,
byte value)
Appendable.
Each nibble (4 bits) from most significant to least significant of the value
is formatted as if by toLowHexDigit(nibble).
The hexadecimal characters are appended in one or more calls to the
Appendable methods. The delimiter, prefix and suffix are not used.A - The type of Appendableout - an Appendable, non-nullvalue - a byte valueAppendablejava.io.UncheckedIOException - if an I/O exception occurs appending to the outputpublic java.lang.String toHexDigits(byte value)
byte value.
Each nibble (4 bits) from most significant to least significant of the value
is formatted as if by toLowHexDigit(nibble).
The delimiter, prefix and suffix are not used.value - a byte valuepublic java.lang.String toHexDigits(char value)
char value.
Each nibble (4 bits) from most significant to least significant of the value
is formatted as if by toLowHexDigit(nibble).
The delimiter, prefix and suffix are not used.value - a char valuechar valuepublic java.lang.String toHexDigits(short value)
short value.
Each nibble (4 bits) from most significant to least significant of the value
is formatted as if by toLowHexDigit(nibble).
The delimiter, prefix and suffix are not used.value - a short valueshort valuepublic java.lang.String toHexDigits(int value)
int value.
Each nibble (4 bits) from most significant to least significant of the value
is formatted as if by toLowHexDigit(nibble).
The delimiter, prefix and suffix are not used.value - an int valueint valueInteger.toHexString(int)public java.lang.String toHexDigits(long value)
long value.
Each nibble (4 bits) from most significant to least significant of the value
is formatted as if by toLowHexDigit(nibble).
The delimiter, prefix and suffix are not used.value - a long valuelong valueLong.toHexString(long)public java.lang.String toHexDigits(long value,
int digits)
long value.
Each nibble (4 bits) from most significant to least significant of the value
is formatted as if by toLowHexDigit(nibble).
The delimiter, prefix and suffix are not used.value - a long valuedigits - the number of hexadecimal digits to return, 0 to 16long valuejava.lang.IllegalArgumentException - if digits is negative or greater than 16public static boolean isHexDigit(int ch)
true 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.
ch - a codepointtrue if the character is valid a hexadecimal character,
otherwise falsepublic static int fromHexDigit(int ch)
(ch - '0') for '0' through '9' inclusive,
(ch - 'A' + 10) for 'A' through 'F' inclusive, and
(ch - 'a' + 10) for 'a' through 'f' inclusive.
ch - a character or codepoint0-15java.lang.NumberFormatException - if the codepoint is not a hexadecimal characterpublic static int fromHexDigits(java.lang.CharSequence string)
int value parsed from a string of up to eight hexadecimal characters.
The hexadecimal characters are parsed from most significant to least significant
using fromHexDigit(int) to form an unsigned value.
The value is zero extended to 32 bits and is returned as an int.string - a CharSequence containing up to eight hexadecimal charactersjava.lang.IllegalArgumentException - if the string length is greater than eight (8) or
if any of the characters is not a hexadecimal characterpublic static int fromHexDigits(java.lang.CharSequence string,
int fromIndex,
int toIndex)
int value parsed from a string range of up to eight hexadecimal
characters.
The characters in the range fromIndex to toIndex, exclusive,
are parsed from most significant to least significant
using fromHexDigit(int) to form an unsigned value.
The value is zero extended to 32 bits and is returned as an int.string - a CharSequence containing the charactersfromIndex - the initial index of the range, inclusivetoIndex - the final index of the range, exclusive.java.lang.IndexOutOfBoundsException - if the range is out of bounds
for the CharSequencejava.lang.IllegalArgumentException - if length of the range is greater than eight (8) or
if any of the characters is not a hexadecimal characterpublic static long fromHexDigitsToLong(java.lang.CharSequence string)
fromHexDigit(int) to form an unsigned value.
The value is zero extended to 64 bits and is returned as a long.string - a CharSequence containing up to sixteen hexadecimal charactersjava.lang.IllegalArgumentException - if the string length is greater than sixteen (16) or
if any of the characters is not a hexadecimal characterpublic static long fromHexDigitsToLong(java.lang.CharSequence string,
int fromIndex,
int toIndex)
fromIndex to toIndex, exclusive,
are parsed from most significant to least significant
using fromHexDigit(int) to form an unsigned value.
The value is zero extended to 64 bits and is returned as a long.string - a CharSequence containing the charactersfromIndex - the initial index of the range, inclusivetoIndex - the final index of the range, exclusive.java.lang.IndexOutOfBoundsException - if the range is out of bounds
for the CharSequencejava.lang.IllegalArgumentException - if the length of the range is greater than sixteen (16) or
if any of the characters is not a hexadecimal characterpublic boolean equals(java.lang.Object o)
true if the other object is a HexFormat
with the same parameters.equals in class java.lang.Objecto - an object, may be nulltrue if the other object is a HexFormat and the parameters
uppercase, delimiter, prefix, and suffix are equal;
otherwise falsepublic int hashCode()
HexFormat.hashCode in class java.lang.ObjectHexFormatpublic java.lang.String toString()
toString in class java.lang.ObjectHexFormat