JDK 17 Java HexFormat

1. Overview

In this article, we will learn the new Java utility class HexFormat added to the standard library package java.util in Java SE \ JDK 17 release.

This HexFormat converts between bytes and chars and hex-encoded strings. It is immutable and thread-safe so multiple threads can invoke the methods of this class without any problems.

It also supports additional formatting markups such as prefixes and suffixes and delimiters. These markups are applicable only between byte arrays and hex conversion.

1.1. HexaDecimal number system

HexaDecimal numeral system represents numbers using base 16. There are totally 16 Hexadecimal digits. They are the same as the decimal digits up to 9, but then there are the letters A-F in place of the decimal numbers 10 to 15:

Hexadecimal:	0	1	2	3	4	5	6	7	8	9	A	B	C	D	E	F
Decimal:	0	1	2	3	4	5	6	7	8	9	10	11	12	13	14	15

So a single Hexadecimal digit can show 16 different values instead of the normal 10. To know more about the Hexadecimal number system, see this page.

Always keep in mind that 4 bits (a nibble) are represented by a single hexadecimal digit.

2. Java HexFormat in JDK 17

HexFormat introduced in Java JDK 17 supports conversion between the following types and Hexadecimal:

1. Byte
2. Char
3. Int
4. Long
5. Byte Array
6. char array

As a first step, you must retrieve the instance of HexFormat class using any of the following factory methods:

1. of() – No delimiter. However, you can update delimiter later using helper method withDelimiter(String delimiter) based on your demands.
2. ofDelimiter(String delimiter) – Specified delimiter.

Both of the above hexadecimal formatters return the hexadecimal values in lowercase letters (a to f). However, you can change this behavior by using the utility method withUpperCase(). The below code returns hexadecimal in the upper case. i.e., 7F.

HexFormat hex = HexFormat.of().withUpperCase();
byte b = 127;
String byteStr = hex.toHexDigits(b);
System.out.println("toHexDigits(byte) : " + byteStr);

The following section covers conversion between primitive types, chars and hexadecimal strings. To learn about byte arrays and hexadecimal conversions, refer to this detailed article.

3. Java HexFormat – Primitive to Hexadecimal String conversion

The HexFormat class contains the toHexDigits method to convert primitive types to a hexadecimal string. By default, the output hexadecimal string would be lowercase (0-9, a-f). However, you can use withUpperCase method to convert the lower case hexadecimal to upper case.

Additional formating options such as delimiter, prefix and suffix are not applicable to these methods.

3.1. HexFormat – Byte to Hexadecimal

You can use toHexDigits(byte value) method to convert a byte to a hexadecimal digit lowercase. Since Byte is a 8-Bit integer, it always returns two hexadecimal digits, each corresponding to 4 bits.

For example, the below byte contains a decimal value of 10. As you know, the hexadecimal equivalent for the decimal 10 is A. When you run the following code, it would return 0a (two hexadecimal digits with prefix 0).

byte b = 10;
String byteStr = hex.toHexDigits(b);
System.out.println("toHexDigits(byte) : " + byteStr); 

3.2. HexFormat – Char to Hexadecimal

You can use toHexDigits(char value) method to convert a char to a hexadecimal digit lower case. Since char is a 16-Bit integer, it always returns four hexadecimal digits, each corresponding to 4 bits.

First, it converts the char value to its Unicode decimal value. Then, it converts that decimal to a hexadecimal value. For example, the below hexChar is Quadrant upper left and lower left and lower right. If you run the below code, it would return 2599 as output. First, it converts the hexChar to 9625 decimal value. Then, converts 9625 decimal to 2599.

char hexChar = '▙';
String charStr = hex.toHexDigits(hexChar);
System.out.println("toHexDigits(char) : " + charStr);

3.3. HexFormat – Short to Hexadecimal

You can use toHexDigits(short value) method to convert a short to a hexadecimal digit lower case. Since short is a 16-Bit integer, it always returns four hexadecimal digits, each corresponding to 4 bits.

For example, it converts the following short of value 33 to hexadecimal value 0021 (total of 4 digits).

short shortValue = 33;
System.out.println("toHexDigits(short) : " + hex.toHexDigits(shortValue));

3.4. HexFormat – Int to Hexadecimal

You can use toHexDigits(int value) method to convert a decimal value of Int type to a hexadecimal digit lower case. Since short is a 32-Bit integer, it always returns eight hexadecimal digits, each corresponding to 4 bits.

For example, it converts the following int of decimal value 33 to hexadecimal value 00000021 (total of 8 digits).

int intValue = 33;
System.out.println("toHexDigits(int) : " + hex.toHexDigits(intValue));

3.5. HexFormat – Long to Hexadecimal

You can use toHexDigits(long value) method to convert a decimal value of Long type to a hexadecimal digit lower case. Since long is a 64-Bit integer, it always returns sixteen hexadecimal digits, each corresponding to 4 bits.

For example, it converts the following long of decimal value 33 to hexadecimal value 0000000000000021 (total of 8 digits).

int intValue = 33;
System.out.println("toHexDigits(long) : " + hex.toHexDigits(intValue));

However, you can also control the number of digits to return 0 to 16. For example, the below code returns only 2 digits 21 (right to left) rather than returning all 16 digits (0000000000000021).

long longValue = 33;
System.out.println("toHexDigits(long) : " + hex.toHexDigits(longValue, 2));

4. Java HexFormat – Hexadecimal string to primitive

The HexFormat class has the fromHexDigit and fromHexDigits method to convert the hexadecimal back to primitive types. The delimiter, prefix, suffix, and uppercase parameters are not applicable. It accepts hexadecimal in uppercase as well as lowercase.

4.1. Convert a single hexadecimal character to int

To convert a single hexadecimal character to int, you can use fromHexDigit method. It is a static method so invoke it using the class name.

For example, the below hexValue string “7F” has two hexadecimal digits. Assume you want to take the second character in the hexValue string and convert it to Decimal.

The fromHexDigit takes the “F” hexadecimal digit and converts it to decimal equivalent (15).

String hexValue = "7F";
int decimalValue = HexFormat.fromHexDigit(hexValue.charAt(1));
System.out.println("fromHexDigit(int ch)" + decimalValue);

4.2. Convert string to decimal int

You can convert the entire or part of the hexadecimal string to decimal using:

1. fromHexDigits(CharSequence string)
2. fromHexDigits(CharSequence string, int fromIndex, int toIndex) – toIndex not inclusive

In the below example, the entire hexValue is converted to 32649 decimal value. Also part of the string converted to 127.

String hexValue = "7F89";
decimalValue = HexFormat.fromHexDigits(hexValue);
System.out.println("fromHexDigit(CharSequence ch)" + decimalValue);

	     
decimalValue = HexFormat.fromHexDigits(hexValue, 0, 2);
System.out.println("fromHexDigit(CharSequence ch, int fromIndex, int toIndex)" + decimalValue);

4.3. Convert string to decimal long

You can convert the entire or part of the hexadecimal string to decimal using:

1. fromHexDigitsTo Long(CharSequence string)
2. fromHexDigitsTo Long(CharSequence string, int fromIndex, int toIndex) – toIndex not inclusive

In the below example, the entire hexValue is converted to 32649 decimal value. Also part of the string converted to 127.

String hexValue = "7F89";
decimalValue = HexFormat.fromHexDigitsToLong(hexValue);
System.out.println("fromHexDigitsToLong(CharSequence ch)" + decimalValue);

	     
decimalValue = HexFormat.fromHexDigitsToLong(hexValue, 0, 2);
System.out.println("fromHexDigitsToLong(CharSequence ch, int fromIndex, int toIndex)" + decimalValue);

3. Conclusion

To sum up, we have learned to use HexFormat class introduced in Java SE \ JDK 17 to convert various types to HexaDecimal string and vice versa.