Package com.pnfsoftware.jeb.util.format

Class Formatter

java.lang.Object
com.pnfsoftware.jeb.util.format.Formatter
public class Formatter extends Object
A collection of binary and number formatting and escaping methods.

  • Constructor Details

    • Formatter

      public Formatter()

  • Method Details

    • formatBinaryBlock

      public static CharSequence formatBinaryBlock(byte[] data, int offset, int size, long offsetDelta, boolean is64bit)
      Format a block of bytes as a buffer of hexadecimal lines. Each line represents the 16 bytes of buffer data; it is prefixed by an optional offset (address) base and suffixed by the ASCII representation of the bytes. Note that non-printable, non-ASCII characters are represented as dots.
      Parameters:
      data - bytes buffer
      offset - beginning of bytes sequence to be formatted
      size - number of bytes to be formatted
      offsetDelta - an offset delta
      is64bit - indicates if the prefix offset should be formatted as a 64-bit or 32-bit value
      Returns:
      a formatted CharSequence

    • formatBinaryBlock

      public static CharSequence formatBinaryBlock(byte[] data, int offset, int size, int offsetDelta)
      Format a block of bytes. Same as formatBinaryBlock(data, offset, size, offsetDelta, false)
      Parameters:
      data - bytes buffer
      offset - beginning of bytes sequence to be formatted
      size - number of bytes to be formatted
      offsetDelta - offset delta subtracted from displayed offsets
      Returns:
      a formatted CharSequence

    • formatBinaryBlock

      public static CharSequence formatBinaryBlock(byte[] data, int offset, int size)
      Format a block of bytes. Same as formatBinaryBlock(data, offset, size, 0)
      Parameters:
      data - bytes buffer
      offset - beginning of bytes sequence to be formatted
      size - number of bytes to be formatted
      Returns:
      a formatted CharSequence

    • formatBinaryBlock

      public static CharSequence formatBinaryBlock(byte[] data)
      Format a block of bytes. Same as formatBinaryBlock(data, 0, data.length)
      Parameters:
      data - bytes buffer
      Returns:
      a formatted CharSequence

    • formatBinaryLine

      public static CharSequence formatBinaryLine(byte[] data, int offset, int size, int minVirtualSize)
      Format a block of bytes as a hexadecimal CharSequence representation. Bytes will be represented space-separated.
      Parameters:
      data - bytes buffer
      offset - beginning of bytes sequence to be formatted
      size - number of bytes to be formatted
      minVirtualSize - minimum number of bytes that the resulting string is supposed to represent; phantom bytes (formatted as empty space) will be appended if necessary
      Returns:
      a formatted CharSequence

    • formatBinaryLine

      public static CharSequence formatBinaryLine(byte[] data, int offset, int size, int minVirtualSize, boolean separateWithSpace)
      Format a block of bytes as a hexadecimal CharSequence representation.
      Parameters:
      data - bytes buffer
      offset - beginning of bytes sequence to be formatted
      size - number of bytes to be formatted
      minVirtualSize - minimum number of bytes represented by the result; phantom bytes are rendered as empty space if necessary
      separateWithSpace - true to insert a space after each formatted byte
      Returns:
      a formatted CharSequence

    • formatBinaryLine

      public static CharSequence formatBinaryLine(byte[] data, int offset, int size)
      Format a block of bytes. Same as formatBinaryLine(data, 0, size, size).
      Parameters:
      data - bytes buffer
      offset - beginning of bytes sequence to be formatted
      size - number of bytes to be formatted
      Returns:
      a formatted CharSequence

    • formatBinaryLine

      public static CharSequence formatBinaryLine(byte[] data)
      Format a block of bytes. Same as formatBinaryLine(data, 0, data.length, 0).
      Parameters:
      data - bytes buffer
      Returns:
      a formatted string

    • formatBinaryLineTruncate

      public static CharSequence formatBinaryLineTruncate(byte[] data, int offset, int size, int maxSize, char truncateChar)
      Format a fixed-width hexadecimal byte line, truncating excess bytes.
      Parameters:
      data - bytes buffer
      offset - beginning of bytes sequence to be formatted
      size - number of bytes to be formatted
      maxSize - maximum number of bytes to render
      truncateChar - character appended when the byte sequence is truncated
      Returns:
      a formatted CharSequence

    • formatBinaryLineTruncate

      public static CharSequence formatBinaryLineTruncate(byte[] data, int offset, int size, int fixedCount)
      Format a fixed-width hexadecimal byte line, truncating excess bytes with a plus sign.
      Parameters:
      data - bytes buffer
      offset - beginning of bytes sequence to be formatted
      size - number of bytes to be formatted
      fixedCount - maximum number of bytes to render
      Returns:
      a formatted CharSequence

    • byteArrayToHex

      public static CharSequence byteArrayToHex(byte[] data)
      See Also:

    • byteArrayToHexString

      public static String byteArrayToHexString(byte[] data)
      See Also:

    • byteArrayToHexString

      public static String byteArrayToHexString(byte[] data, int pos)
      See Also:

    • byteArrayToHexString

      public static String byteArrayToHexString(byte[] data, int pos, int end)
      Return the String hexadecimal representation of a byte array. The hexadecimal part is returned as upper case.
      For example: 
       ({10, 27, 56}, 0, 3) => "0A1B38"
 ({10, 27, 56}, 1, 2) => "1B"
      Parameters:
      data - byte array to convert
      pos - first byte position
      end - last byte position (excluded)
      Returns:
      the String representation

    • byteArrayToHex

      public static CharSequence byteArrayToHex(byte[] data, int pos, int end)
      Same as byteArrayToHexString(byte[], int, int), but returns a raw CharSequence
      Parameters:
      data - byte array to convert
      pos - first byte position
      end - last byte position (excluded)
      Returns:
      the CharSequence representation
      See Also:

    • byteArrayToHex

      public static CharSequence byteArrayToHex(byte[] data, int pos, int end, boolean asciiString, int bytesPerLine)
      Return the upper-case hexadecimal String representation of some bytes.
      Parameters:
      data - byte array to convert
      pos - first byte position
      end - last byte position (excluded)
      asciiString - when true, return the hexadecimal along with its readable ASCII characters; else, see that method. For example: 
       ({10, 74, 101, 98}, 0, 4, true, 0x10) => "0A4A6562"    .Jeb
      Note that `bytesPerLine` must be greater than zero when this flag is true, else it is ignored
      bytesPerLine - maximum number of bytes per line for hexadecimal representation (zero or negative means no max)
      Returns:
      the CharSequence representation

    • hexStringToByteArray

      public static byte[] hexStringToByteArray(String s, int pos, int end)
      Convert a series of hexadecimal String to a byte array. Input must be padded with zeroes. If data is invalid, a null array is returned. 
       hexStringToByteArray("1234ABCD", 0, 8) => {0x12, 0x23, 0xAB, 0xCD}
 hexStringToByteArray("1234ABCD", 0, 4) => {0x12, 0x23}
 hexStringToByteArray("1234ABCD", 0, 5) => null
      Parameters:
      s - Input String
      pos - the start parsing position
      end - the end parsing position
      Returns:
      the byte array

    • hexStringToByteArray

      public static byte[] hexStringToByteArray(String s)
      Convert a series of hexadecimal String to a byte array. Remove potential "h" suffix and "0x" prefix.
      Parameters:
      s - Input String
      Returns:
      the byte array

    • addCustomPrintableCharRange

      public static void addCustomPrintableCharRange(int begin, int end, boolean printable)
      Add a custom range used by isPrintableChar(char).
      Parameters:
      begin - start character, included
      end - end character, excluded
      printable - true to force the range as printable, false to force it as non-printable

    • resetCustomPrintableCharRanges

      public static void resetCustomPrintableCharRanges()
      Clear all custom printable and non-printable character ranges.

    • isPrintableChar

      public static boolean isPrintableChar(char c)
      Determine if a character is printable. By default, this method defines a character as `printable` if and only if:
      1- it is not an ISO control character
      2- it is not a surrogate (low or high)
      3- it is not a special character (block: SPECIAL)
      4- it is not a modifier character (categories: MODIFIER_LETTER, MODIFIER_SYMBOL)

      Tests 1 and 2 are always verified by this method (i.e. control chars and surrogate and NOT considered printable).
      Tests 3 and 4 can be globally bypassed and customized via via addCustomPrintableCharRange(int, int, boolean) and resetCustomPrintableCharRanges().

      Parameters:
      c - the input character
      Returns:
      true if the character is printable

    • escapeCharacter

      public static String escapeCharacter(char c, boolean keepUnicodePrintables)
      Escape a character, if necessary.
      Parameters:
      c - the character to be escaped
      keepUnicodePrintables - if true, a printable Unicode, non-ASCII character will be left unescaped
      Returns:
      a string representing the escaped character

    • escapeCharacter

      public static String escapeCharacter(char c)
      Escape a character, keeping Unicode printable characters.
      Parameters:
      c - the character to escape
      Returns:
      a string representing the escaped character

    • escapeString

      public static String escapeString(CharSequence s)
      Escape a string. Unicode printable characters are not escaped (refer to isPrintableChar(char)).

      Refer to escapeString(CharSequence, int, boolean, Set).

      Parameters:
      s - a CharSequence
      Returns:
      the escaped string

    • escapeString

      public static String escapeString(CharSequence s, boolean keepUnicodePrintables)
      Escape a string.

      Refer to escapeString(CharSequence, int, boolean, Set).

      Parameters:
      s - a CharSequence
      keepUnicodePrintables - if true, unicode printable characters are not escaped (refer to isPrintableChar(char)).
      Returns:
      the escaped string

    • escapeString

      public static String escapeString(CharSequence s, int directionalityEnclosure, boolean keepUnicodePrintables, Set<Character> doNotEscapeList)
      Escape a CharSequence.
      Parameters:
      s - the CharSequence to be escaped
      directionalityEnclosure - if non-0, a string containing RTL (right-to-left) characters will be enclosed in special Unicode characters to force directionality when embedding the string into another string:
      - -1: nothing added, nothing changed
      - 0: nothing added, directionality when embedding will be determined from the string and its context (keepUnicodePrintables will be reset to false if RTL chars are detected)
      - 1: force left-to-right for embedding
      - 2: force right-to-left for embedding
      keepUnicodePrintables - if true, unicode printable characters are not escaped (refer to isPrintableChar(char)), eg, KCJ/Russian/etc. character sets
      doNotEscapeList - optional collection of characters that won't be escaped
      Returns:
      the escaped string

    • unescapeString

      public static String unescapeString(String s) throws ParseException
      Unescape a string escaped with standard String-formatter backslash-based escape sequences.
      Parameters:
      s - an escaped string, allowed escapes: \\ \' \" \n \r \t \b \f \u???? \x??
      Returns:
      the unescaped string
      Throws:
      ParseException - if an error occurs

    • escapeAllCharacters

      public static String escapeAllCharacters(CharSequence s)
      Force-escape a string to a sequence of \\u character codes. All characters, regardless of their printability, are escaped.
      Parameters:
      s - a string
      Returns:
      the escaped string

    • escapeToJavaStringArray

      public static String escapeToJavaStringArray(Collection<? extends Object> objects)
      This handy method takes a collection of N objects as input and generates the string representation a string array containing N strings, each of which being the escaped toString() representation of the collection elements.
      Parameters:
      objects - a collection of any objects
      Returns:
      the string representation of a string array

    • escapeBytes

      public static String escapeBytes(byte[] bytes, int offset, int size)
      Convert bytes to a string of characters such that a byte 0xBB is converted to character », and escape the resulting string. Only ASCII-printable chars will be left unescaped, all other characters will be escaped.
      Parameters:
      bytes - bytes array
      offset - start index
      size - count of bytes to escape
      Returns:
      the escaped string

    • escapeBytes

      public static String escapeBytes(byte[] bytes)
      Convert bytes to a string of characters such that a byte 0xBB is converted to character », and escape the resulting string. Only ASCII-printable chars will be left unescaped, all other characters will be escaped.
      Parameters:
      bytes - bytes array
      Returns:
      the escaped string

    • escapeByte

      public static String escapeByte(int ch)
      Convert a byte to character such that a byte 0xBB is converted to character », and escape the resulting character.
      Parameters:
      ch - byte value to escape
      Returns:
      the escaped character string

    • formatHexNumbers

      public static String formatHexNumbers(Collection<? extends Number> list)
      Format a collection of numbers as upper-case hexadecimal values.
      Parameters:
      list - numbers to format
      Returns:
      a bracketed, comma-separated list of hexadecimal values

    • formatNumbers

      public static String formatNumbers(Collection<? extends Number> list, int base, String pfx, String sfx)
      Format a collection of numbers in the requested base.
      Parameters:
      list - numbers to format
      base - numeric base; supported values are 8, 10, and 16
      pfx - optional prefix added before each number
      sfx - optional suffix added after each number
      Returns:
      a bracketed, comma-separated list of formatted values

    • integerToAlphaString

      public static String integerToAlphaString(int n)
      Convert an integer to an alphabetic string, using the following pattern: 
       a: 0
 b: 1
 ...
 z: 25
 aa: 26
 ...
 az: 51
 ba: 52
 ...
 zzz: 26-1+26*26
 aaa: 26+26*26
 ...
 aaaa: 26+26*26+26*26*26
 ...
      Parameters:
      n - an integer, treated as unsigned
      Returns:
      a string associated to this integer

    • toHexString

      public static String toHexString(long v, boolean upperCase, int padZero)
      Convert a long to its hex representation.
      Parameters:
      v - long to convert
      upperCase - true if the hex must be in upper case
      padZero - indicate the number of characters that will be output (will pad with zeroes)
      Returns:
      The hex representation

    • toHexString

      public static String toHexString(long v, boolean upperCase)
      Convert a long to its hex representation.
      Parameters:
      v - long to convert
      upperCase - true if the hex must be in upper case
      Returns:
      The hex representation

    • toHexString

      public static String toHexString(int v, boolean upperCase, int padZero)
      Convert a int to its hex representation.
      Parameters:
      v - int to convert
      upperCase - true if the hex must be in upper case
      padZero - indicate the number of characters that will be output (will pad with zeroes)
      Returns:
      The hex representation

    • toHexString

      public static String toHexString(int v, boolean upperCase)
      Convert an int to its hex representation.
      Parameters:
      v - int to convert
      upperCase - true if the hex must be in upper case
      Returns:
      The hex representation

    • toHexString

      public static String toHexString(short v, boolean upperCase, int padZero)
      Convert a short to its hex representation.
      Parameters:
      v - short to convert
      upperCase - true if the hex must be in upper case
      padZero - indicate the number of characters that will be output (will pad with zeroes)
      Returns:
      The hex representation

    • toHexString

      public static String toHexString(short v, boolean upperCase)
      Convert a short to its hex representation.
      Parameters:
      v - short to convert
      upperCase - true if the hex must be in upper case
      Returns:
      The hex representation

    • toHexString

      public static String toHexString(byte v, boolean upperCase, int padZero)
      Convert a byte to its hex representation.
      Parameters:
      v - byte to convert
      upperCase - true if the hex must be in upper case
      padZero - indicate the number of characters that will be output (will pad with zeroes)
      Returns:
      The hex representation

    • toHexString

      public static String toHexString(byte v, boolean upperCase)
      Convert a byte to its hex representation.
      Parameters:
      v - byte to convert
      upperCase - true if the hex must be in upper case
      Returns:
      The hex representation

    • htmlEscape

      public static String htmlEscape(String str)
      Escape HTML 4 entities by their &xxx; equivalents. Line-feeds are not replaced by the (unescaped) <br> tag.
      Parameters:
      str - the string to escape
      Returns:
      the escaped string

    • htmlEscape

      public static String htmlEscape(String str, boolean replaceNewlinesByBR)
      Escape HTML 4 entities by their &xxx; equivalents.
      Parameters:
      str - the string to escape
      replaceNewlinesByBR - if true, new-line combos (CR, LF, or CRLF) are replaced by the (unescaped) <br> tag followed by the original new-line combo
      Returns:
      the escaped string

    • wordWrap

      public static List<String> wordWrap(String str, int wrapLength, int wrapType)
      Word-wrap a string. The result is a list of (CR)LF-empty lines whose lengths are equal to the provided wrapping length, modulo the wrapping style.
      Parameters:
      str - the text buffer to be wrapped
      wrapLength - wrapping length, must be strictly positive
      wrapType - wrapping type:
      0: strict (the wrapping length is not a hint, all lines will have the provided length, except for lines ending with a new-line character before the required limit; words may be cut)
      -1: forbid length crossing (i.e. the wrapping length is a hard hint; favor shorter lines; words may be cut)
      +1: allow length crossing (i.e. the wrapping length is a soft hint; favor longer lines)
      Returns:
      an array of strings

    • toString

      public static String toString(Object o)
      Pretty-format any object, using a PrettyPrinter object. Elements of arrays, collections, and maps are rendered individually. For non-basic types, toString is called. For maps, the key-value pairs are rendered one per line line. Indenting uses 2 white-space characters.
      Parameters:
      o - an object
      Returns:
      a decent string representation of the object