net.sf.kdgcommons.util

Class HexDump

java.lang.Object

net.sf.kdgcommons.util.HexDump

public class HexDump
extends Object

Utility class to produce formatted hex output from arrays of bytes.

This output consists of the following three pieces, two of which are optional:

• An optional offset, tracking the number of bytes that have been dumped by this object.
• One or more two-character hex codes representing the input bytes, separated by spaces. The number of bytes shown per line may be limited by a constructor parameter.
• An optional character representation of the bytes in the previous segment. This may be limited to printable ASCII characters only, in which case any non-printable/non-ASCII characters are replaced by a specified character.

There are also multiple ways to get output:

• As a single String, with lines of output separated by newlines.
• As an iterator, where each iteration returns a single String containing a line of output.
• Written directly to a Writer.

The dumper may be invoked with varying input buffers, which may contain more or less bytes than desired per line. In such cases, the output will be broken or padded, such that the three segments occupy the same columns in each line (ie, if you have 16 bytes displayed in one line, and only 8 in the next, the second line will be padded so that the "printable characters" line up in both).

Constructor Summary

Constructors

Constructor and Description
HexDump() Convenience constructor, which emits 78-character-wide lines with the following characteristics: Shows offset, using 8-char wide counter followed by 2 chars 16 bytes per line Shows characters, limited to ASCII, with replacement by spaces, preceeded by 4 spaces
HexDump(int bytesPerLine, boolean showOffset, int offsetWidth, int spacesAfterOffset, boolean showChars, int spacesBeforeChars, boolean replaceNonAscii, char replacement) Base constructor, with all sorts of options.

Method Summary

Modifier and Type	Method and Description
Iterator<String>	iterator(byte[] buf) Creates an iterator over the entire passed buffer, where each call to next returns a line of output.
Iterator<String>	iterator(byte[] buf, int off, int len) Creates an iterator over a portion of the passed buffer, where each call to next returns a line of output.
void	setOffset(int value) Resets the offset counter to a specified value.
String	stringValue(byte[] buf) Returns a string containing the a dump of the entire passed buffer, with newlines separating each line of output.
String	stringValue(byte[] buf, int off, int len) Returns a string containing the a dump of the specified portion of a passed buffer, with newlines separating each line of output.
void	write(PrintWriter out, byte[] buf) Writes an entire buffer to the specified PrintWriter, as separate lines of output.
void	write(PrintWriter out, byte[] buf, int off, int len) Writes a portion of the passed buffer to the specified PrintWriter, as separate lines of output.

Methods inherited from class java.lang.Object

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

Constructor Detail

HexDump

public HexDump(int bytesPerLine,
               boolean showOffset,
               int offsetWidth,
               int spacesAfterOffset,
               boolean showChars,
               int spacesBeforeChars,
               boolean replaceNonAscii,
               char replacement)

Base constructor, with all sorts of options.

Parameters:

bytesPerLine - The number of bytes that will be dumped per "line" (aka iteration) of output.

showOffset - If true, the output lines will start with a hex counter showing position of the bytes in that line, relative to all bytes dumped by this object.

offsetWidth - Number of characters for offset field. The actual offset will be trimmed or left-zero- padded to this size.

spacesAfterOffset - Number of spaces to insert between offset field (if it's displayed) and hex bytes.

showChars - If true, the hex dump will be followed by the characters represented by those bytes.

spacesBeforeChars - If showing characters, the number of spaces inserted between the hex dump and characters.

replaceNonAscii - If true, only bytes between 32 and 126 will be displayed in the character output; all others will be replaced.

replacement - The character used to replace non-ASCII or non-printable characters. May be '\0', which may lead to ugly output.

HexDump

public HexDump()

Convenience constructor, which emits 78-character-wide lines with the following characteristics:

• Shows offset, using 8-char wide counter followed by 2 chars
• 16 bytes per line
• Shows characters, limited to ASCII, with replacement by spaces, preceeded by 4 spaces

Method Detail

setOffset

public void setOffset(int value)

Resets the offset counter to a specified value. Useful if the same dumper is reused for different output.

iterator

public Iterator<String> iterator(byte[] buf)

Creates an iterator over the entire passed buffer, where each call to next returns a line of output.

iterator

public Iterator<String> iterator(byte[] buf,
                                 int off,
                                 int len)

Creates an iterator over a portion of the passed buffer, where each call to next returns a line of output.

stringValue

public String stringValue(byte[] buf)

Returns a string containing the a dump of the entire passed buffer, with newlines separating each line of output.

stringValue

public String stringValue(byte[] buf,
                          int off,
                          int len)

Returns a string containing the a dump of the specified portion of a passed buffer, with newlines separating each line of output.

write

public void write(PrintWriter out,
                  byte[] buf)

Writes an entire buffer to the specified PrintWriter, as separate lines of output.

Caller is responsible for setting auto-flush if needed, as well as selecting an appropriate character set if using character displays (picking UTF-8 is a bad idea when outputting raw characters).

write

public void write(PrintWriter out,
                  byte[] buf,
                  int off,
                  int len)

Writes a portion of the passed buffer to the specified PrintWriter, as separate lines of output.

Caller is responsible for setting auto-flush if needed, as well as selecting an appropriate character set if using character displays (picking UTF-8 is a bad idea when outputting raw characters).