Top Description Inners Fields Constructors Methods
java.util

public final Class HexFormat

extends Object
Class Inheritance
Imports
jdk.internal.access.JavaLangAccess, .SharedSecrets, jdk.internal.util.HexDigits, java.io.IOException, .UncheckedIOException, java.nio.CharBuffer, java.nio.charset.CharacterCodingException, .StandardCharsets
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 java.io.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 using fromHexDigits(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 the HexFormat 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 the HexFormat 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 of HexFormat may have unpredictable results and should be avoided. The equals 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

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static enum
HexFormat.Case

Field Summary

Modifier and TypeField and Description
private final String
delimiter

private final HexFormat.Case
digitCase

private static final byte[]
DIGITS

private static final byte[]
EMPTY_BYTES

private static final HexFormat
HEX_FORMAT

Format each byte of an array as a pair of hexadecimal digits.

private static final HexFormat
HEX_UPPER_FORMAT

private static final JavaLangAccess
jla

private final String
prefix

private final String
suffix

Constructor Summary

AccessConstructor and Description
private
HexFormat(String
a delimiter, non-null
delimiter, String
a prefix, non-null
prefix, String
a suffix, non-null
suffix, HexFormat.Case
enum indicating how to case digits
digitCase)

Returns a HexFormat with a delimiter, prefix, suffix, and array of digits.

Method Summary

Modifier and TypeMethod and Description
private static int

Returns:

the length of the range
checkDigitCount(int
the initial index of the range, inclusive
fromIndex, int
the final index of the range, exclusive.
toIndex, int
the maximum allowed
limit)

Check the number of requested digits against a limit.

private static void
checkLiteral(CharSequence
a CharSequence
string, int
the index of the literal in the CharSequence
index, String
the expected literal
literal)

Compare the literal and throw an exception if it does not match.

private static int

Returns:

the length
checkMaxArraySize(long
the requested size of a byte array.
length)

Checked that the requested size for the result string is less than or equal to the max array size.

public String

Returns:

the delimiter, non-null, may be empty ""
delimiter()

Returns the delimiter between hexadecimal values in formatted hexadecimal strings.

public boolean

Returns:

true if the other object is a HexFormat and the parameters uppercase, delimiter, prefix, and suffix are equal; otherwise false
equals(Object
an object, may be null
o)

Overrides java.lang.Object.equals.

Returns true if the other object is a HexFormat with the same parameters.

private static String

Returns:

a string with newline characters escaped
escapeNL(String
a string
string)

Expands new line characters to escaped newlines for display.

public String

Returns:

a string hexadecimal formatting of the byte array
formatHex(byte[]
a non-null array of bytes
bytes)

Returns a hexadecimal string formatted from a byte array.

public String

Returns:

a string hexadecimal formatting each byte of the array range
formatHex(byte[]
a non-null array of bytes
bytes, int
the initial index of the range, inclusive
fromIndex, int
the final index of the range, exclusive
toIndex)

Returns a hexadecimal string formatted from a byte array range.

public <
The type of Appendable
A extends Appendable> A

Returns:

the Appendable
formatHex(A
an Appendable, non-null
out, byte[]
a byte array
bytes)

Appends formatted hexadecimal strings from a byte array to the Appendable.

public <
The type of Appendable
A extends Appendable> A

Returns:

the Appendable
formatHex(A
an Appendable, non-null
out, byte[]
a byte array, non-null
bytes, int
the initial index of the range, inclusive
fromIndex, int
the final index of the range, exclusive.
toIndex)

Appends formatted hexadecimal strings from a byte array range to the Appendable.

private String

Returns:

a String formatted or null for non-single byte delimiter or non-empty prefix or suffix
formatOptDelimiter(byte[]
the bytes, non-null
bytes, int
the initial index of the range, inclusive
fromIndex, int
the final index of the range, exclusive.
toIndex)

Returns a string formatting of the range of bytes optimized for a single allocation.

public static int

Returns:

the value 0-15
fromHexDigit(int
a character or codepoint
ch)

Returns the value for the hexadecimal character or codepoint.

private static int

Returns:

the value parsed from the string range
fromHexDigits(CharSequence
a CharSequence containing the characters
string, int
the index of the first character of the range
index)

Returns a value parsed from two hexadecimal characters in a string.

public static int

Returns:

the value parsed from the string
fromHexDigits(CharSequence
a CharSequence containing up to eight hexadecimal characters
string)

Returns the int value parsed from a string of up to eight hexadecimal characters.

public static int

Returns:

the value parsed from the string range
fromHexDigits(CharSequence
a CharSequence containing the characters
string, int
the initial index of the range, inclusive
fromIndex, int
the final index of the range, exclusive.
toIndex)

Returns the int value parsed from a string range of up to eight hexadecimal characters.

public static long

Returns:

the value parsed from the string
fromHexDigitsToLong(CharSequence
a CharSequence containing up to sixteen hexadecimal characters
string)

Returns the long value parsed from a string of up to sixteen hexadecimal characters.

public static long

Returns:

the value parsed from the string range
fromHexDigitsToLong(CharSequence
a CharSequence containing the characters
string, int
the initial index of the range, inclusive
fromIndex, int
the final index of the range, exclusive.
toIndex)

Returns the long value parsed from a string range of up to sixteen hexadecimal characters.

public int

Returns:

a hashcode for this HexFormat
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hashcode for this HexFormat.

public static boolean

Returns:

true if the character is valid a hexadecimal character, otherwise false
isHexDigit(int
a codepoint
ch)

Returns true if the character is a valid hexadecimal character or codepoint.

public boolean

Returns:

true if the hexadecimal digits are uppercase, otherwise false
isUpperCase()

Returns true if the hexadecimal digits are uppercase, otherwise false.

public static HexFormat

Returns:

a hexadecimal formatter with no delimiter and lowercase characters
of()

Returns a hexadecimal formatter with no delimiter and lowercase characters.

public static HexFormat

Returns:

a HexFormat with the delimiter and lowercase characters
ofDelimiter(String
a delimiter, non-null, may be empty
delimiter)

Returns a hexadecimal formatter with the delimiter and lowercase characters.

public byte[]

Returns:

a byte array with the values parsed from the string
parseHex(CharSequence
a string containing the byte values with prefix, hexadecimal digits, suffix, and delimiters
string)

Returns a byte array containing hexadecimal values parsed from the string.

public byte[]

Returns:

a byte array with the values parsed from the string range
parseHex(CharSequence
a string range containing hexadecimal digits, delimiters, prefix, and suffix.
string, int
the initial index of the range, inclusive
fromIndex, int
the final index of the range, exclusive.
toIndex)

Returns a byte array containing hexadecimal values parsed from a range of the string.

public byte[]

Returns:

a byte array with the values parsed from the character array range
parseHex(char[]
a character array range containing an even number of hexadecimal digits, delimiters, prefix, and suffix.
chars, int
the initial index of the range, inclusive
fromIndex, int
the final index of the range, exclusive.
toIndex)

Returns a byte array containing hexadecimal values parsed from a range of the character array.

private static byte[]

Returns:

a byte array
parseNoDelimiter(CharSequence
a string containing an even number of only hex digits
string)

Returns a byte array containing the parsed hex digits.

public String

Returns:

the prefix, non-null, may be empty ""
prefix()

Returns the prefix used for each hexadecimal value in formatted hexadecimal strings.

public String

Returns:

the suffix, non-null, may be empty ""
suffix()

Returns the suffix used for each hexadecimal value in formatted hexadecimal strings.

public <
The type of Appendable
A extends Appendable> A

Returns:

the Appendable
toHexDigits(A
an Appendable, non-null
out, byte
a byte value
value)

Appends two hexadecimal characters for the byte value to the Appendable.

public String

Returns:

the two hexadecimal characters for the byte value
toHexDigits(byte
a byte value
value)

Returns the two hexadecimal characters for the byte value.

public String

Returns:

the four hexadecimal characters for the char value
toHexDigits(char
a char value
value)

Returns the four hexadecimal characters for the char value.

public String

Returns:

the four hexadecimal characters for the short value
toHexDigits(short
a short value
value)

Returns the four hexadecimal characters for the short value.

public String

Returns:

the eight hexadecimal characters for the int value
toHexDigits(int
an int value
value)

Returns the eight hexadecimal characters for the int value.

public String

Returns:

the sixteen hexadecimal characters for the long value
toHexDigits(long
a long value
value)

Returns the sixteen hexadecimal characters for the long value.

public String

Returns:

the hexadecimal characters for the long value
toHexDigits(long
a long value
value, int
the number of hexadecimal digits to return, 0 to 16
digits)

Returns up to sixteen hexadecimal characters for the long value.

public char

Returns:

the hexadecimal character for the bits 4-7 of the value
toHighHexDigit(int
a value, only bits 4-7 of the value are used
value)

Returns the hexadecimal character for the high 4 bits of the value considering it to be a byte.

public char

Returns:

the hexadecimal character for the low 4 bits 0-3 of the value
toLowHexDigit(int
a value, only the low 4 bits 0-3 of the value are used
value)

Returns the hexadecimal character for the low 4 bits of the value considering it to be a byte.

public String

Returns:

a description of this HexFormat
toString()

Overrides java.lang.Object.toString.

Returns a description of the formatter parameters for uppercase, delimiter, prefix, and suffix.

public HexFormat

Returns:

a copy of this HexFormat with the delimiter
withDelimiter(String
the delimiter, non-null, may be empty
delimiter)

Returns a copy of this HexFormat with the delimiter.

public HexFormat

Returns:

a copy of this HexFormat with lowercase hexadecimal characters
withLowerCase()

Returns a copy of this HexFormat to use lowercase hexadecimal characters.

public HexFormat

Returns:

a copy of this HexFormat with the prefix
withPrefix(String
a prefix, non-null, may be empty
prefix)

Returns a copy of this HexFormat with the prefix.

public HexFormat

Returns:

a copy of this HexFormat with the suffix
withSuffix(String
a suffix, non-null, may be empty
suffix)

Returns a copy of this HexFormat with the suffix.

public HexFormat

Returns:

a copy of this HexFormat with uppercase hexadecimal characters
withUpperCase()

Returns a copy of this HexFormat to use uppercase hexadecimal characters.

Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAllwaitwaitwait

Field Detail

delimiterback to summary
private final String delimiter
digitCaseback to summary
private final HexFormat.Case digitCase
DIGITSback to summary
private static final byte[] DIGITS
EMPTY_BYTESback to summary
private static final byte[] EMPTY_BYTES
HEX_FORMATback to summary
private static final HexFormat HEX_FORMAT

Format each byte of an array as a pair of hexadecimal digits. The hexadecimal characters are from lowercase alpha digits.

HEX_UPPER_FORMATback to summary
private static final HexFormat HEX_UPPER_FORMAT
jlaback to summary
private static final JavaLangAccess jla
prefixback to summary
private final String prefix
suffixback to summary
private final String suffix

Constructor Detail

HexFormatback to summary
private HexFormat(String delimiter, String prefix, String suffix, HexFormat.Case digitCase)

Returns a HexFormat with a delimiter, prefix, suffix, and array of digits.

Parameters
delimiter:String

a delimiter, non-null

prefix:String

a prefix, non-null

suffix:String

a suffix, non-null

digitCase:HexFormat.Case

enum indicating how to case digits

Exceptions
NullPointerException:
if any argument is null

Method Detail

checkDigitCountback to summary
private static int checkDigitCount(int fromIndex, int toIndex, int limit)

Check the number of requested digits against a limit.

Parameters
fromIndex:int

the initial index of the range, inclusive

toIndex:int

the final index of the range, exclusive.

limit:int

the maximum allowed

Returns:int

the length of the range

checkLiteralback to summary
private static void checkLiteral(CharSequence string, int index, String literal)

Compare the literal and throw an exception if it does not match. Pre-condition: index + literal.length() <= string.length().

Parameters
string:CharSequence

a CharSequence

index:int

the index of the literal in the CharSequence

literal:String

the expected literal

Exceptions
IllegalArgumentException:
if the literal is not present
checkMaxArraySizeback to summary
private static int checkMaxArraySize(long length)

Checked that the requested size for the result string is less than or equal to the max array size.

Parameters
length:long

the requested size of a byte array.

Returns:int

the length

Exceptions
OutOfMemoryError:
if the size is larger than Integer.MAX_VALUE
delimiterback to summary
public String delimiter()

Returns the delimiter between hexadecimal values in formatted hexadecimal strings.

Returns:String

the delimiter, non-null, may be empty ""

equalsback to summary
public boolean equals(Object o)

Overrides java.lang.Object.equals.

Returns true if the other object is a HexFormat with the same parameters.

Parameters
o:Object

an object, may be null

Returns:boolean

true if the other object is a HexFormat and the parameters uppercase, delimiter, prefix, and suffix are equal; otherwise false

Annotations
@Override
escapeNLback to summary
private static String escapeNL(String string)

Expands new line characters to escaped newlines for display.

Parameters
string:String

a string

Returns:String

a string with newline characters escaped

formatHexback to summary
public String formatHex(byte[] bytes)

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 to formatHex(bytes, 0, bytes.length)).

Parameters
bytes:byte[]

a non-null array of bytes

Returns:String

a string hexadecimal formatting of the byte array

formatHexback to summary
public String formatHex(byte[] bytes, int fromIndex, int toIndex)

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:byte[]

a non-null array of bytes

fromIndex:int

the initial index of the range, inclusive

toIndex:int

the final index of the range, exclusive

Returns:String

a string hexadecimal formatting each byte of the array range

Exceptions
IndexOutOfBoundsException:
if the array range is out of bounds
formatHexback to summary
public <A extends Appendable> A formatHex(A out, byte[] bytes)

Appends formatted hexadecimal strings from a byte array to the 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.

Parameters
<A>
The type of Appendable
out:A

an Appendable, non-null

bytes:byte[]

a byte array

Returns:A

the Appendable

Exceptions
UncheckedIOException:
if an I/O exception occurs appending to the output
formatHexback to summary
public <A extends Appendable> A formatHex(A out, byte[] bytes, int fromIndex, int toIndex)

Appends formatted hexadecimal strings from a byte array range to the 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.

Parameters
<A>
The type of Appendable
out:A

an Appendable, non-null

bytes:byte[]

a byte array, non-null

fromIndex:int

the initial index of the range, inclusive

toIndex:int

the final index of the range, exclusive.

Returns:A

the Appendable

Exceptions
IndexOutOfBoundsException:
if the array range is out of bounds
UncheckedIOException:
if an I/O exception occurs appending to the output
formatOptDelimiterback to summary
private String formatOptDelimiter(byte[] bytes, int fromIndex, int toIndex)

Returns a string formatting of the range of bytes optimized for a single allocation. Prefix and suffix must be empty and the delimiter must be empty or a single byte character, otherwise null is returned.

Parameters
bytes:byte[]

the bytes, non-null

fromIndex:int

the initial index of the range, inclusive

toIndex:int

the final index of the range, exclusive.

Returns:String

a String formatted or null for non-single byte delimiter or non-empty prefix or suffix

fromHexDigitback to summary
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:int

a character or codepoint

Returns:int

the value 0-15

Exceptions
NumberFormatException:
if the codepoint is not a hexadecimal character
fromHexDigitsback to summary
private static int fromHexDigits(CharSequence string, int index)

Returns a value parsed from two hexadecimal characters in a string. The characters in the range from index to index + 1, inclusive, must be valid hex digits according to fromHexDigit(int).

Parameters
string:CharSequence

a CharSequence containing the characters

index:int

the index of the first character of the range

Returns:int

the value parsed from the string range

Exceptions
NumberFormatException:
if any of the characters in the range is not a hexadecimal character
IndexOutOfBoundsException:
if the range is out of bounds for the CharSequence
fromHexDigitsback to summary
public static int fromHexDigits(CharSequence string)

Returns the 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.

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). HexFormat uses only hexadecimal characters "0-9", "A-F" and "a-f". Signed hexadecimal strings can be parsed with Integer#parseInt(String, int).

Parameters
string:CharSequence

a CharSequence containing up to eight hexadecimal characters

Returns:int

the value parsed from the string

Exceptions
IllegalArgumentException:
if the string length is greater than eight (8) or if any of the characters is not a hexadecimal character
fromHexDigitsback to summary
public static int fromHexDigits(CharSequence string, int fromIndex, int toIndex)

Returns the 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.

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). HexFormat uses only hexadecimal characters "0-9", "A-F" and "a-f". Signed hexadecimal strings can be parsed with Integer#parseInt(String, int).

Parameters
string:CharSequence

a CharSequence containing the characters

fromIndex:int

the initial index of the range, inclusive

toIndex:int

the final index of the range, exclusive.

Returns:int

the value parsed from the string range

Exceptions
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
fromHexDigitsToLongback to summary
public static long fromHexDigitsToLong(CharSequence string)

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 using fromHexDigit(int) to form an unsigned value. The value is zero extended to 64 bits and is returned as a long.

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). HexFormat uses only hexadecimal characters "0-9", "A-F" and "a-f". Signed hexadecimal strings can be parsed with Long#parseLong(String, int).

Parameters
string:CharSequence

a CharSequence containing up to sixteen hexadecimal characters

Returns:long

the value parsed from the string

Exceptions
IllegalArgumentException:
if the string length is greater than sixteen (16) or if any of the characters is not a hexadecimal character
fromHexDigitsToLongback to summary
public static long fromHexDigitsToLong(CharSequence string, int fromIndex, int toIndex)

Returns the long value parsed from a string range of up to sixteen 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 64 bits and is returned as a long.

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). HexFormat uses only hexadecimal characters "0-9", "A-F" and "a-f". Signed hexadecimal strings can be parsed with Long#parseLong(String, int).

Parameters
string:CharSequence

a CharSequence containing the characters

fromIndex:int

the initial index of the range, inclusive

toIndex:int

the final index of the range, exclusive.

Returns:long

the value parsed from the string range

Exceptions
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
hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Returns a hashcode for this HexFormat.

Returns:int

a hashcode for this HexFormat

Annotations
@Override
isHexDigitback to summary
public static boolean isHexDigit(int ch)

Returns 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.
Parameters
ch:int

a codepoint

Returns:boolean

true if the character is valid a hexadecimal character, otherwise false

isUpperCaseback to summary
public boolean isUpperCase()

Returns true if the hexadecimal digits are uppercase, otherwise false.

Returns:boolean

true if the hexadecimal digits are uppercase, otherwise false

ofback to summary
public static HexFormat of()

Returns a hexadecimal formatter with no delimiter and lowercase characters. The delimiter, prefix, and suffix are empty. The methods withDelimiter, withUpperCase, withLowerCase, withPrefix, and withSuffix return copies of formatters with new parameters.

Returns:HexFormat

a hexadecimal formatter with no delimiter and lowercase characters

ofDelimiterback to summary
public static HexFormat ofDelimiter(String delimiter)

Returns a hexadecimal formatter with the delimiter and lowercase characters. The prefix and suffix are empty. The methods withDelimiter, withUpperCase, withLowerCase, withPrefix, and withSuffix return copies of formatters with new parameters.

Parameters
delimiter:String

a delimiter, non-null, may be empty

Returns:HexFormat

a HexFormat with the delimiter and lowercase characters

parseHexback to summary
public byte[] parseHex(CharSequence string)

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:CharSequence

a string containing the byte values with prefix, hexadecimal digits, suffix, and delimiters

Returns:byte[]

a byte array with the values parsed from the string

Exceptions
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
parseHexback to summary
public byte[] parseHex(CharSequence string, int fromIndex, int toIndex)

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:CharSequence

a string range containing hexadecimal digits, delimiters, prefix, and suffix.

fromIndex:int

the initial index of the range, inclusive

toIndex:int

the final index of the range, exclusive.

Returns:byte[]

a byte array with the values parsed from the string range

Exceptions
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
parseHexback to summary
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:char[]

a character array range containing an even number of hexadecimal digits, delimiters, prefix, and suffix.

fromIndex:int

the initial index of the range, inclusive

toIndex:int

the final index of the range, exclusive.

Returns:byte[]

a byte array with the values parsed from the character array range

Exceptions
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
parseNoDelimiterback to summary
private static byte[] parseNoDelimiter(CharSequence string)

Returns a byte array containing the parsed hex digits. A valid string consists only of an even number of hex digits.

Parameters
string:CharSequence

a string containing an even number of only hex digits

Returns:byte[]

a byte array

Exceptions
IllegalArgumentException:
if the string length is not valid or the string contains non-hexadecimal characters
prefixback to summary
public String prefix()

Returns the prefix used for each hexadecimal value in formatted hexadecimal strings.

Returns:String

the prefix, non-null, may be empty ""

suffixback to summary
public String suffix()

Returns the suffix used for each hexadecimal value in formatted hexadecimal strings.

Returns:String

the suffix, non-null, may be empty ""

toHexDigitsback to summary
public <A extends Appendable> A toHexDigits(A out, byte value)

Appends two hexadecimal characters for the byte value to the 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.

Parameters
<A>
The type of Appendable
out:A

an Appendable, non-null

value:byte

a byte value

Returns:A

the Appendable

Exceptions
UncheckedIOException:
if an I/O exception occurs appending to the output
toHexDigitsback to summary
public String toHexDigits(byte value)

Returns the two hexadecimal characters for the 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.

Parameters
value:byte

a byte value

Returns:String

the two hexadecimal characters for the byte value

toHexDigitsback to summary
public String toHexDigits(char value)

Returns the four hexadecimal characters for the 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.

Parameters
value:char

a char value

Returns:String

the four hexadecimal characters for the char value

toHexDigitsback to summary
public String toHexDigits(short value)

Returns the four hexadecimal characters for the 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.

Parameters
value:short

a short value

Returns:String

the four hexadecimal characters for the short value

toHexDigitsback to summary
public String toHexDigits(int value)

Returns the eight hexadecimal characters for the 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.

Parameters
value:int

an int value

Returns:String

the eight hexadecimal characters for the int value

See Also
Integer#toHexString
toHexDigitsback to summary
public String toHexDigits(long value)

Returns the sixteen hexadecimal characters for the 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.

Parameters
value:long

a long value

Returns:String

the sixteen hexadecimal characters for the long value

See Also
Long#toHexString
toHexDigitsback to summary
public String toHexDigits(long value, int digits)

Returns up to sixteen hexadecimal characters for the 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.

Parameters
value:long

a long value

digits:int

the number of hexadecimal digits to return, 0 to 16

Returns:String

the hexadecimal characters for the long value

Exceptions
IllegalArgumentException:
if digits is negative or greater than 16
toHighHexDigitback to summary
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 parameter 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".

Parameters
value:int

a value, only bits 4-7 of the value are used

Returns:char

the hexadecimal character for the bits 4-7 of the value

toLowHexDigitback to summary
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 parameter 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".

Parameters
value:int

a value, only the low 4 bits 0-3 of the value are used

Returns:char

the hexadecimal character for the low 4 bits 0-3 of the value

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Returns a description of the formatter parameters for uppercase, delimiter, prefix, and suffix.

Returns:String

a description of this HexFormat

Annotations
@Override
withDelimiterback to summary
public HexFormat withDelimiter(String delimiter)

Returns a copy of this HexFormat with the delimiter.

Parameters
delimiter:String

the delimiter, non-null, may be empty

Returns:HexFormat

a copy of this HexFormat with the delimiter

withLowerCaseback to summary
public HexFormat withLowerCase()

Returns a copy of this HexFormat to use lowercase hexadecimal characters. The lowercase hexadecimal characters are "0-9", "a-f".

Returns:HexFormat

a copy of this HexFormat with lowercase hexadecimal characters

withPrefixback to summary
public HexFormat withPrefix(String prefix)

Returns a copy of this HexFormat with the prefix.

Parameters
prefix:String

a prefix, non-null, may be empty

Returns:HexFormat

a copy of this HexFormat with the prefix

withSuffixback to summary
public HexFormat withSuffix(String suffix)

Returns a copy of this HexFormat with the suffix.

Parameters
suffix:String

a suffix, non-null, may be empty

Returns:HexFormat

a copy of this HexFormat with the suffix

withUpperCaseback to summary
public HexFormat withUpperCase()

Returns a copy of this HexFormat to use uppercase hexadecimal characters. The uppercase hexadecimal characters are "0-9", "A-F".

Returns:HexFormat

a copy of this HexFormat with uppercase hexadecimal characters

java.util back to summary

private final Enum HexFormat.Case

extends Enum<HexFormat.Case>
Class Inheritance

Field Summary

Modifier and TypeField and Description
public static final HexFormat.Case
LOWERCASE

public static final HexFormat.Case
UPPERCASE

Constructor Summary

AccessConstructor and Description
private
Case()

Method Summary

Modifier and TypeMethod and Description
public static HexFormat.Case
valueOf(String name)

public static HexFormat.Case[]
values()

Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

LOWERCASEback to summary
public static final HexFormat.Case LOWERCASE
UPPERCASEback to summary
public static final HexFormat.Case UPPERCASE

Constructor Detail

Caseback to summary
private Case()

Method Detail

valueOfback to summary
public static HexFormat.Case valueOf(String name)
valuesback to summary
public static HexFormat.Case[] values()