net.lbruun.hexutils

Class Hex

java.lang.Object

net.lbruun.hexutils.Hex

public class Hex
extends Object

Utilities for converting byte(s) into hexadecimal character/string representation and vice versa. Methods are optimized for speed.

Hexadecimal output produced by this class will always use exactly two characters per byte, in other words hex values lower than or equal to 'F' will be left-padded with a '0'.

A delimiter can optionally be used to separate the byte values in the hexadecimal representation. The characters in the delimiter must be printable characters from the US_ASCII character set and it must furthermore not contain any of the characters used to represent the hex values themselves (characters 0-9, A-f and a-f).

JDK 17 introduces HexFormat class which can often be used instead of this class.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Hex.HexCase Case used for hex string.

Field Summary

Fields

Modifier and Type	Field and Description
static char[]	HEX_CHARS_LOWER Characters allowed in hex representation (lower-case)
static char[]	HEX_CHARS_UPPER Characters allowed in hex representation (upper-case)
static String	HEX_REGEXP_CHARCLASS Regular expression character set with the characters that are allowed in hex representation.

Method Summary

Modifier and Type	Method and Description
static char[]	bytesToHex(byte[] bytes, Hex.HexCase caseType, String delim) Converts a byte array to its hexadecimal representation.
static String	bytesToHexStr(byte[] bytes, Hex.HexCase caseType) Converts a byte array to its hexadecimal representation and returns the result as a string.
static String	bytesToHexStr(byte[] bytes, Hex.HexCase caseType, String delim) Converts a byte array to its hexadecimal representation and returns the result as a string.
static StringBuilder	bytesToHexStr(byte[] bytes, Hex.HexCase caseType, StringBuilder sb) Converts a byte array to its hexadecimal representation and appends the result to the provided StringBuilder.
static StringBuilder	bytesToHexStr(byte[] bytes, Hex.HexCase caseType, String delim, StringBuilder sb) Converts a byte array to its hexadecimal representation and appends the result to the provided StringBuilder.
static void	bytesToHexStreaming(InputStream is, OutputStream os, Hex.HexCase caseType, String delim) Converts a stream of bytes (from an InputStream) to its hexadecimal character representation and writes the result to the provided OutputStream.
static void	bytesToHexStreaming(Path in, Path out, Hex.HexCase caseType, String delim, int maxCharsPerLine, OpenOption... outOptions) Converts the content of a file to its hexadecimal character representation and writes the result to another file.
static char[]	byteToHex(byte b, Hex.HexCase caseType) Converts a single byte to its hexadecimal representation.
static byte	hexCharToByte(char c1, char c2) Converts a hex character pair into a byte.
static byte[]	hexStrToBytes(char[] chars) Converts a character sequence (a string) consisting of hexadecimal characters into a byte array.
static byte[]	hexStrToBytes(char[] chars, String delim) Converts a character sequence (a string) consisting of hexadecimal characters into a byte array.
static byte[]	hexStrToBytes(CharSequence s) Converts a character sequence (a string) consisting of hexadecimal characters into a byte array.
static byte[]	hexStrToBytes(CharSequence s, String delim) Converts a character sequence (a string) consisting of hexadecimal characters into a byte array.
static void	hexToBytesStreaming(InputStream is, OutputStream os, String delim) Converts an input stream of hexadecimal characters characters into bytes and writes the resulting bytes to output stream.
static void	hexToBytesStreaming(Path in, Path out, String delim, OpenOption... outOptions) Converts the content of a hex file file to its byte representation and writes the result to another file.
static boolean	isHexChar(char c) Tests if a character is a hex character.
static boolean	isHexStr(String str) Tests if a string only contains hex characters.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

HEX_CHARS_LOWER

public static final char[] HEX_CHARS_LOWER

Characters allowed in hex representation (lower-case)

HEX_CHARS_UPPER

public static final char[] HEX_CHARS_UPPER

Characters allowed in hex representation (upper-case)

HEX_REGEXP_CHARCLASS

public static final String HEX_REGEXP_CHARCLASS

Regular expression character set with the characters that are allowed in hex representation. (both upper and lower case characters)

See Also:

Constant Field Values

Method Detail

byteToHex

public static char[] byteToHex(byte b,
                               Hex.HexCase caseType)

Converts a single byte to its hexadecimal representation.

Parameters:

b - input

caseType - if the hexadecimal representation should be in upper or lower case

Returns:

char array of length 2

bytesToHex

public static char[] bytesToHex(byte[] bytes,
                                Hex.HexCase caseType,
                                String delim)

Converts a byte array to its hexadecimal representation.

Parameters:

bytes - input

caseType - if the hexadecimal representation should be in upper or lower case

delim - optional delimiter between byte values in the encoded output, may be null

Returns:

hexadecimal representation

bytesToHexStr

public static String bytesToHexStr(byte[] bytes,
                                   Hex.HexCase caseType,
                                   String delim)

Converts a byte array to its hexadecimal representation and returns the result as a string.

Parameters:

bytes - input

caseType - if the hexadecimal representation should be in upper or lower case

delim - optional delimiter between byte values in the encoded output, may be null

Returns:

hexadecimal representation

bytesToHexStr

public static String bytesToHexStr(byte[] bytes,
                                   Hex.HexCase caseType)

Converts a byte array to its hexadecimal representation and returns the result as a string.

Parameters:

bytes - input

caseType - if the hexadecimal representation should be in upper or lower case

Returns:

hexadecimal representation

bytesToHexStr

public static StringBuilder bytesToHexStr(byte[] bytes,
                                          Hex.HexCase caseType,
                                          String delim,
                                          StringBuilder sb)

Converts a byte array to its hexadecimal representation and appends the result to the provided StringBuilder.

Parameters:

bytes - input

caseType - if the hexadecimal representation should be in upper or lower case

delim - optional delimiter between byte values in the encoded output, may be null

sb - the StringBuilder to append to (not null)

Returns:

the StringBuilder (same as the input 'sb')

bytesToHexStr

public static StringBuilder bytesToHexStr(byte[] bytes,
                                          Hex.HexCase caseType,
                                          StringBuilder sb)

Converts a byte array to its hexadecimal representation and appends the result to the provided StringBuilder.

Parameters:

bytes - input

caseType - if the hexadecimal representation should be in upper or lower case

sb - the StringBuilder to append to (not null)

Returns:

the StringBuilder (same as the input 'sb')

bytesToHexStreaming

public static void bytesToHexStreaming(InputStream is,
                                       OutputStream os,
                                       Hex.HexCase caseType,
                                       String delim)
                                throws IOException

Converts a stream of bytes (from an InputStream) to its hexadecimal character representation and writes the result to the provided OutputStream. This method provides a way to convert large amounts of binary data without causing an out-of-memory error.

The method reads from the InputStream until end-of-stream or an error occurs. Neither the InputStream nor the OutputStream is closed by the method.

Note that representing large binary data structures in base16 encoded format (another word for hexadecimal character representation) is very inefficient compared to for example base64 encoding. Base64 encoding is almost always preferable.

When dealing with files it is likely to be considerably faster if a buffered stream is used.

Parameters:

is - input

os - output

caseType - if the hexadecimal representation should be in upper or lower case

delim - optional delimiter between byte values in the encoded output, may be null

Throws:

IOException - if reading from the provided InputStream or writing to the provided OutputStream causes an exception.

See Also:

bytesToHexStreaming(Path, Path, HexCase, String, int, OpenOption...)

bytesToHexStreaming

public static void bytesToHexStreaming(Path in,
                                       Path out,
                                       Hex.HexCase caseType,
                                       String delim,
                                       int maxCharsPerLine,
                                       OpenOption... outOptions)
                                throws IOException

Converts the content of a file to its hexadecimal character representation and writes the result to another file.

Assuming the delimiter is either null or some simple character(s) like '-' then it can be guaranteed that the output file will consist only of printable characters: 0-9, A-F or a-f as well as what is in the optional delimiter.

Using the maxCharsPerLine parameter the output file can optionally be written with line breaks so that the file will look more like a text file. The line break character(s) used will be according to platform.

Note that representing large binary data structures in base16 encoded format (another word for hexadecimal character representation) is very inefficient compared to for example base64 encoding. Base64 encoding is almost always preferable.

Parameters:

in - input file

out - output file

caseType - if the hexadecimal representation should be in upper or lower case

delim - optional delimiter between byte values in the encoded output, may be null

maxCharsPerLine - maximum number of characters per line in the output file or -1 to not break the output into lines.

outOptions - options specifying how the output file is opened.

Throws:

IOException - if reading from the input file or writing to the output file causes an exception.

hexCharToByte

public static byte hexCharToByte(char c1,
                                 char c2)

Converts a hex character pair into a byte. For example the pair '7' and 'D' returns the byte value 125.

The input values must be only the characters 0-9, A-F and a-f.

Parameters:

c1 - first character of pair

c2 - second character of pair

Returns:

Throws:

IllegalArgumentException - if either c1 or c2 is an illegal character.

hexStrToBytes

public static byte[] hexStrToBytes(char[] chars,
                                   String delim)

Converts a character sequence (a string) consisting of hexadecimal characters into a byte array.

The input must consist only of characters 0-9, A-F and a-f as well as the characters from the optional delimiter.

Parameters:

chars - input

delim - optional delimiter between byte values in the hex string input, may be null. If the hex string was created with a delimiter the then same delimiter must be used here.

Returns:

byte array or null if chars is null.

Throws:

HexConversionException - if input character array contains illegal chars

hexStrToBytes

public static byte[] hexStrToBytes(char[] chars)

Converts a character sequence (a string) consisting of hexadecimal characters into a byte array.

The input must consist only of characters 0-9, A-F and a-f.

Parameters:

chars - input

Returns:

byte array or null if chars is null.

hexStrToBytes

public static byte[] hexStrToBytes(CharSequence s,
                                   String delim)

Converts a character sequence (a string) consisting of hexadecimal characters into a byte array.

The input must consist only of characters 0-9, A-F and a-f as well as the characters from the optional delimiter.

Parameters:

s - input

delim - optional delimiter between byte values in the hex string input, may be null. If the hex string was created with a delimiter the then same delimiter must be used here.

Returns:

byte array or null if input s is null.

Throws:

HexConversionException - if input CharSequence contains illegal chars

hexStrToBytes

public static byte[] hexStrToBytes(CharSequence s)

Converts a character sequence (a string) consisting of hexadecimal characters into a byte array.

The input must consist only of characters 0-9, A-F and a-f.

Parameters:

s - input

Returns:

byte array or null if input s is null.

Throws:

HexConversionException - if input CharSequence contains illegal chars

hexToBytesStreaming

public static void hexToBytesStreaming(InputStream is,
                                       OutputStream os,
                                       String delim)
                                throws IOException

Converts an input stream of hexadecimal characters characters into bytes and writes the resulting bytes to output stream.

The input stream must contain only bytes which complies with one of the following:

• Is a hex character as per isHexChar(char).
• Is an EOL character (decimal 10 and 13).
• Is a character from the delimiter string.

As such the method can read output produced by bytesToHexStreaming() methods of this class.

The input stream is read until end-of-stream or an error occurs. Neither the input stream nor the output stream is closed by this method. You must do this yourself.

Parameters:

is - input

os - output

delim -

Throws:

HexConversionException - if input stream contains invalid characters

IOException - if reading from the input stream or writing to the output stream causes an exception.

hexToBytesStreaming

public static void hexToBytesStreaming(Path in,
                                       Path out,
                                       String delim,
                                       OpenOption... outOptions)
                                throws IOException

Converts the content of a hex file file to its byte representation and writes the result to another file.

The input file must contain only bytes which complies with one of the following:

• Is a hex character as per isHexChar(char).
• Is an EOL character (decimal 10 and 13).
• Is a character from the delimiter string.

As such the method can read output produced by bytesToHexStreaming() methods of this class.

Parameters:

in - input file

out - output file

delim - optional delimiter between byte values in the encoded output, may be null. If the input file uses a delimiter between hex pairs then the same delimiter must be specified here.

outOptions - options specifying how the output file is opened.

Throws:

IOException - if reading from the input file or writing to the output file causes an exception.

HexConversionException - if input file contains invalid characters

isHexStr

public static boolean isHexStr(String str)

Tests if a string only contains hex characters. Testing is done as per isHexChar(char) method.

Parameters:

str - input

Returns:

true if all characters in str are hex characters, false otherwise or if str is null.

isHexChar

public static boolean isHexChar(char c)

Tests if a character is a hex character. This means any of the following characters:

• 0-9
• A-F
• a-f

Parameters:

c - the character to test

Returns:

true if the character is a hex character, otherwise false