* Example usage: *
{@code
* // Display the hexadecimal representation of the local Internet Protocol (IP) address
* System.out.println(Hex.toString(InetAddress.getLocalHost().getAddress()));
*
* // Initialize a 16-byte array from a hexadecimal string
* byte[] bytes = Hex.fromString("a1a2a3a4a5a6a7a8a9aaabacadaeaf");
*
* // Dump a Java class file to the standard output stream
* Hex.dump(Files.readAllBytes(Paths.get("MyApp.class")), System.out);
*
* // Dump a file to the standard output stream, skipping blocks of content comprising all zeros
* try (InputStream in = new FileInputStream("mydata.bin")) {
* Hex.dumpAsStream(in)
* .filter(s ->
* !s.contains("00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00"))
* .forEachOrdered(System.out::println);
* }
*
* // Write the hexadecimal representation of a file to the standard output stream in 32-byte chunks
* Hex.stream(Files.readAllBytes(Paths.get("mydata.bin")), 32)
* .forEachOrdered(System.out::println);
* }
*
* @since 10
*/
public final class Hex {
private static final char[] HEX_DIGITS = "0123456789abcdef".toCharArray();
private static final int CHUNK_SIZE = 16;
private Hex() {}
/**
* Returns a hexadecimal string representation of the contents of a
* binary buffer.
* * The binary value is converted to a string comprising pairs of * hexadecimal digits using only the following ASCII characters: *
* {@code 0123456789abcdef} ** * @param bytes a binary buffer * @return a hexadecimal string representation of the binary buffer. * The string length is twice the buffer length. * @throws NullPointerException if {@code bytes} is {@code null} */ public static String toString(byte[] bytes) { Objects.requireNonNull(bytes, "bytes"); return toString(bytes, 0, bytes.length); } /** * Returns a hexadecimal string representation of the contents of a * range within a binary buffer. *
* The binary value is converted to a string comprising pairs of * hexadecimal digits using only the following ASCII characters: *
* {@code 0123456789abcdef} ** The range to be converted extends from index {@code fromIndex}, * inclusive, to index {@code toIndex}, exclusive. * (If {@code fromIndex==toIndex}, the range to be converted is empty.) * * @param bytes a binary buffer * @param fromIndex the index of the first byte (inclusive) to be converted * @param toIndex the index of the last byte (exclusive) to be converted * @return a hexadecimal string representation of the binary buffer. * The string length is twice the number of bytes converted. * @throws NullPointerException if {@code bytes} is {@code null} * @throws IllegalArgumentException if {@code fromIndex > toIndex} * @throws ArrayIndexOutOfBoundsException * if {@code fromIndex < 0} or {@code toIndex > bytes.length} */ public static String toString(byte[] bytes, int fromIndex, int toIndex) { Objects.requireNonNull(bytes, "bytes"); Arrays.rangeCheck(bytes.length, fromIndex, toIndex); StringBuilder hexString = new StringBuilder((toIndex - fromIndex) * 2); for (int i = fromIndex; i < toIndex; i++) { hexString.append(HEX_DIGITS[(bytes[i] >> 4) & 0xF]); hexString.append(HEX_DIGITS[(bytes[i] & 0xF)]); } return hexString.toString(); } /** * Returns a stream of hexadecimal string representations of the contents * of a binary buffer. *
* The binary values are converted to strings comprising pairs of * hexadecimal digits using only the following ASCII characters: *
* {@code 0123456789abcdef} ** * @param bytes a binary buffer * @param chunkSize the number of bytes per hexadecimal string * (defaults to 16 if omitted) * @return a stream of hexadecimal strings representating the binary buffer. * Each string length is twice the {@code chunkSize} * (but the final string may be shorter). * @throws NullPointerException if {@code bytes} is {@code null} */ public static Stream
* The binary values are converted to strings comprising pairs of * hexadecimal digits using only the following ASCII characters: *
* {@code 0123456789abcdef} ** The range to be converted extends from index {@code fromIndex}, * inclusive, to index {@code toIndex}, exclusive. * (If {@code fromIndex==toIndex}, the range to be converted is empty.) * * TBD * @param bytes a binary buffer * @param fromIndex the index of the first byte (inclusive) to be converted * @param toIndex the index of the last byte (exclusive) to be converted * @param chunkSize the number of bytes per hexadecimal string * (defaults to 16 if omitted) * @return a stream of hexadecimal strings representating the binary buffer. * Each string length is twice the {@code chunkSize} * (but the final string may be shorter). * @throws NullPointerException if {@code bytes} is {@code null} * @throws IllegalArgumentException if {@code fromIndex > toIndex} * @throws ArrayIndexOutOfBoundsException * if {@code fromIndex < 0} or {@code toIndex > bytes.length} */ public static Stream
* The binary value is generated from pairs of hexadecimal digits that use * only the following ASCII characters: *
* {@code 0123456789abcdef} ** * @param hexString an even numbered sequence of hexadecimal digits * @return a binary buffer * @throws IllegalArgumentException if {@code hexString} has an odd number * of digits or contains an illegal hexadecimal character * @throws NullPointerException if {@code hexString} is {@code null} */ public static byte[] fromString(CharSequence hexString) { Objects.requireNonNull(hexString, "hexString"); int len = hexString.length(); if (len % 2 != 0) { throw new IllegalArgumentException( "contains an odd number of digits: " + hexString); } byte[] bytes = new byte[len / 2]; for (int i = 0; i < len; i += 2) { int high = hexToBinary(hexString.charAt(i)); int low = hexToBinary(hexString.charAt(i + 1)); if (high == -1 || low == -1) { throw new IllegalArgumentException( "contains an illegal hexadecimal character: " + hexString); } bytes[i / 2] = (byte) (high * 16 + low); } return bytes; } /** * Returns a binary buffer coresponding to a range within the sequence of * hexadecimal digits. *
* The binary value is generated from pairs of hexadecimal digits that use * only the following ASCII characters: *
* {@code 0123456789abcdef} ** * @param hexString an even numbered sequence of hexadecimal digits * @param fromIndex the index of the first digit (inclusive) to be converted * @param toIndex the index of the last digit (exclusive) to be converted * @return a binary buffer * @throws IllegalArgumentException if {@code hexString} has an odd number * of digits or contains an illegal hexadecimal character * @throws NullPointerException if {@code hexString} is {@code null} * @throws IllegalArgumentException if {@code fromIndex > toIndex} * @throws ArrayIndexOutOfBoundsException * if {@code fromIndex < 0} or {@code toIndex > hexString.length()} */ public static byte[] fromString(CharSequence hexString, int fromIndex, int toIndex) { Objects.requireNonNull(hexString, "hexString"); return fromString(hexString, 0, hexString.length()); } /** * Generates a hexadecimal dump of the contents of a binary buffer, * as a stream of hexadecimal strings. *
* It outputs the same format as {@link #dump(byte[],OutputStream)},
* without the line separator characters.
* When the input is not a multiple of 16-bytes then the final chunk
* is shorter than 16-bytes.
*
* @param bytes a binary buffer
* @return a stream of hexadecimal strings
* @throws NullPointerException if {@code bytes} is {@code null}
*/
public static Stream
* It outputs the same format as {@link #dump(byte[],OutputStream)},
* without the line separator characters.
* When the input is not a multiple of 16-bytes then the final chunk
* is shorter than 16-bytes.
* The range to be converted extends from index {@code fromIndex},
* inclusive, to index {@code toIndex}, exclusive.
* (If {@code fromIndex==toIndex}, the range to be converted is empty.)
*
* @param bytes a binary buffer
* @param fromIndex the index of the first byte (inclusive) to be converted
* @param toIndex the index of the last byte (exclusive) to be converted
* @return a stream of hexadecimal strings
* @throws NullPointerException if {@code bytes} is {@code null}
* @throws IllegalArgumentException if {@code fromIndex > toIndex}
* @throws ArrayIndexOutOfBoundsException
* if {@code fromIndex < 0} or {@code toIndex > bytes.length}
*/
public static Stream
* It outputs the same format as {@link #dump(byte[],OutputStream)},
* without the line separator characters.
* When the input is not a multiple of 16-bytes then the final chunk
* is shorter than 16-bytes.
*
* On return, the input stream will be at end of stream.
* This method does not close the input stream and may block indefinitely
* reading from it. The behavior for the case where it is
* asynchronously closed, or the thread interrupted,
* is highly input stream specific, and therefore not specified.
*
* If an I/O error occurs reading from the input stream then it may not be
* at end of stream and may be in an inconsistent state. It is strongly
* recommended that the input stream be promptly closed if an I/O error
* occurs.
*
* @param in the input stream, non-null
* @return a stream of hexadecimal strings
* @throws NullPointerException if {@code in} is {@code null}
*/
public static Stream
* This is useful when analyzing binary data.
* The general output format is as follows:
*
* This method does not close the output stream and may block indefinitely
* writing to it. The behavior for the case where it is
* asynchronously closed, or the thread interrupted,
* is highly output stream specific, and therefore not specified.
*
* If an I/O error occurs writing to the output stream, then it may be
* in an inconsistent state. It is strongly recommended that the output
* stream be promptly closed if an I/O error occurs.
*
* @param bytes the binary buffer
* @param out the output stream, non-null
* @throws IOException if an I/O error occurs when writing
* @throws NullPointerException if {@code bytes} or {@code out} is
* {@code null}
*/
public static void dump(byte[] bytes, OutputStream out) throws IOException {
Objects.requireNonNull(bytes, "bytes");
dump(bytes, 0, bytes.length, out);
}
/**
* Generates a hexadecimal dump of the contents of a range within a
* binary buffer and writes it to the output stream.
* It outputs the same format as {@link #dump(byte[],OutputStream)}.
*
* The range to be converted extends from index {@code fromIndex},
* inclusive, to index {@code toIndex}, exclusive.
* (If {@code fromIndex==toIndex}, the range to be converted is empty.)
*
* This method does not close the output stream and may block indefinitely
* writing to it. The behavior for the case where it is
* asynchronously closed, or the thread interrupted,
* is highly output stream specific, and therefore not specified.
*
* If an I/O error occurs writing to the output stream, then it may be
* in an inconsistent state. It is strongly recommended that the output
* stream be promptly closed if an I/O error occurs.
*
* @param bytes the binary buffer
* @param fromIndex the index of the first byte (inclusive) to be converted
* @param toIndex the index of the last byte (exclusive) to be converted
* @param out the output stream, non-null
* @throws IOException if an I/O error occurs when writing
* @throws NullPointerException if {@code bytes} or {@code out} is
* {@code null}
* @throws IllegalArgumentException if {@code fromIndex > toIndex}
* @throws ArrayIndexOutOfBoundsException
* if {@code fromIndex < 0} or {@code toIndex > bytes.length}
*/
public static void dump(byte[] bytes, int fromIndex, int toIndex,
OutputStream out) throws IOException {
dumpAsStream(bytes, fromIndex, toIndex)
.forEachOrdered(getPrintStream(out)::println);
}
/**
* Generates a hexadecimal dump of the contents of an input stream and
* writes it to the output stream.
* It outputs the same format as {@link #dump(byte[],OutputStream)}.
*
* Reads all bytes from the input stream.
* On return, the input stream will be at end of stream. This method does
* not close either stream and may block indefinitely reading from the
* input stream, or writing to the output stream. The behavior for the case
* where the input and/or output stream is asynchronously closed,
* or the thread interrupted, is highly input stream and output stream
* specific, and therefore not specified.
*
* If an I/O error occurs reading from the input stream or writing to the
* output stream, then it may do so after some bytes have been read or
* written. Consequently the input stream may not be at end of stream and
* one, or both, streams may be in an inconsistent state. It is strongly
* recommended that both streams be promptly closed if an I/O error occurs.
*
* @param in the input stream, non-null
* @param out the output stream, non-null
* @throws IOException if an I/O error occurs when reading or writing
* @throws NullPointerException if {@code in} or {@code out} is {@code null}
*/
public static void dump(InputStream in, OutputStream out)
throws IOException {
dumpAsStream(in)
.forEachOrdered(getPrintStream(out)::println);
}
//VR: TBD: check for (total + chunk - 1) > Integer.MAX_VALUE ??
private static int roundUp(int total, int chunk) {
return (total + chunk - 1) / chunk;
}
private static String readChunk(InputStream inStream, int counter)
throws IOException {
byte[] buffer = new byte[CHUNK_SIZE];
int n = inStream.readNBytes(buffer, 0, buffer.length);
if (n == 0) {
return null;
}
return chunk(counter, buffer, 0, n);
}
private static String chunk(int counter, byte[] bytes) {
int fromIndex = counter * CHUNK_SIZE;
int toIndex = fromIndex + CHUNK_SIZE;
if (toIndex > bytes.length) {
toIndex = bytes.length;
}
return chunk(counter, bytes, fromIndex, toIndex);
}
private static String chunk(int counter, byte[] bytes, int fromIndex,
int toIndex) {
StringBuilder hex = new StringBuilder(CHUNK_SIZE * 3 + 1);
StringBuilder ascii = new StringBuilder(CHUNK_SIZE);
boolean hasDivider = false;
for (int j = fromIndex; j < toIndex; j++) {
// Hex digits
hex.append(HEX_DIGITS[(bytes[j] >> 4) & 0xF]);
hex.append(HEX_DIGITS[(bytes[j] & 0xF)]);
if (j == fromIndex + (CHUNK_SIZE / 2 - 1)) {
hex.append(" ");
hasDivider = true;
} else {
hex.append(" ");
}
// Printable ASCII
if (bytes[j] < ' ' || bytes[j] > '~') {
ascii.append('.');
} else {
ascii.append((char) bytes[j]);
}
}
// Pad the final chunk, if shorter
int chunkLength = toIndex - fromIndex;
if (chunkLength < CHUNK_SIZE) {
int padding = CHUNK_SIZE - chunkLength;
for (int k = 0; k < padding; k++) {
hex.append(" ");
ascii.append(' ');
}
if (!hasDivider) {
hex.append(' ');
}
}
return String.format("%08x %s |%s|",
counter * CHUNK_SIZE, hex.toString(), ascii.toString());
}
private static PrintStream getPrintStream(OutputStream out)
throws IOException {
Objects.requireNonNull(out, "out");
PrintStream ps = null;
if (out instanceof PrintStream) {
ps = (PrintStream) out;
} else {
ps = new PrintStream(out, true); // auto flush
}
return ps;
}
private static int hexToBinary(char ch) {
if ('0' <= ch && ch <= '9') {
return ch - '0';
}
if ('A' <= ch && ch <= 'F') {
return ch - 'A' + 10;
}
if ('a' <= ch && ch <= 'f') {
return ch - 'a' + 10;
}
return -1;
}
}
* xxxxxxxx 00 11 22 33 44 55 66 77 88 99 aa bb cc dd ee ff |................|
*
* where '{@code xxxxxxxx}' is the offset into the buffer in 16-byte chunks,
* followed by ASCII coded hexadecimal bytes, followed by the ASCII
* representation of the bytes, or {@code '.'} if it is non-printable.
* A non-printable character is one outside the ASCII range
* {@code ' '} through {@code '~'}
* ({@code '\u005Cu0020'} through {@code '\u005Cu007E'}).
* Output lines are separated by the platform-specific line separator.
* When the input is not a multiple of 16-bytes then the final line is
* shorter than normal.
*