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)
      Parameters:
      data -
      offset -
      size -
      offsetDelta -
      Returns:
    • 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)
    • 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 -
      offset -
      size -
      Returns:
    • 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)
      Parameters:
      data -
      offset -
      size -
      maxSize -
      truncateChar -
      Returns:
    • formatBinaryLineTruncate

      public static CharSequence formatBinaryLineTruncate(byte[] data, int offset, int size, int fixedCount)
      Parameters:
      data -
      offset -
      size -
      fixedCount -
      Returns:
    • 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)
      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 String hexadecimal representation of a byte array. The hexadecimal part is returned as upper case.
      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 (otherwise, see byteArrayToHex(byte[], int, int) For example:
       ({10, 74, 101, 98}, 0, 4, true, 0x10) => "0A4A6562"    .Jeb
                  
      bytesPerLine - maximum number of bytes per line for hexadecimal representation
      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)
      Parameters:
      begin - start character, included
      end - end character, excluded
      printable -
    • resetCustomPrintableCharRanges

      public static void resetCustomPrintableCharRanges()
    • 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(char, char, 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 string, keeping unicode printable characters.
      Parameters:
      c -
      Returns:
    • 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)
      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 bytes to character such that a byte 0xBB is converted to character », and escape the resulting character.
      Parameters:
      ch -
      Returns:
    • formatHexNumbers

      public static String formatHexNumbers(Collection<? extends Number> list)
      Parameters:
      list -
      Returns:
    • formatNumbers

      public static String formatNumbers(Collection<? extends Number> list, int base, String pfx, String sfx)
      Parameters:
      list -
      base -
      Returns:
    • 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
       ...
       
      Negative numbers will generate a string prefixed by '-'.
      Parameters:
      n -
      Returns:
    • 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, line-feeds are replaced by the (unescaped) <br> tag
      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