# Class: com.pnfsoftware.jeb.util.format.Formatter A collection of binary and number formatting and escaping methods. ## Constructor: Formatter ## Static Method: addCustomPrintableCharRange - parameter: `begin`, type: `int` - parameter: `end`, type: `int` - parameter: `printable`, type: `boolean` Description: Add a custom range used by [#isPrintableChar(char)](#isPrintableChar(char)). parameter: begin: start character, included parameter: end: end character, excluded parameter: printable: true to force the range as printable, false to force it as non\-printable ## Static Method: byteArrayToHex - parameter: `data`, type: `byte[]` - return type: `java.lang.CharSequence` Description: see also: Formatter#byteArrayToHex(byte[], int, int) ## Static Method: byteArrayToHex - parameter: `data`, type: `byte[]` - parameter: `pos`, type: `int` - parameter: `end`, type: `int` - return type: `java.lang.CharSequence` Description: Same as [Formatter#byteArrayToHexString(byte[], int, int)](Formatter#byteArrayToHexString(byte[], int, int)), but returns a raw [CharSequence](CharSequence) parameter: data: byte array to convert parameter: pos: first byte position parameter: end: last byte position \(excluded\) return: the [CharSequence](CharSequence) representation see also: Formatter#byteArrayToHexString(byte[], int, int) ## Static Method: byteArrayToHex - parameter: `data`, type: `byte[]` - parameter: `pos`, type: `int` - parameter: `end`, type: `int` - parameter: `asciiString`, type: `boolean` - parameter: `bytesPerLine`, type: `int` - return type: `java.lang.CharSequence` Description: Return the upper\-case hexadecimal String representation of some bytes. parameter: data: byte array to convert parameter: pos: first byte position parameter: end: last byte position \(excluded\) parameter: asciiString: when true, return the hexadecimal along with its readable ASCII characters; else, see [that method](#byteArrayToHex(byte[], int, int)). 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 parameter: bytesPerLine: maximum number of bytes per line for hexadecimal representation \(zero or negative means no max\) return: the [CharSequence](CharSequence) representation ## Static Method: byteArrayToHexString - parameter: `data`, type: `byte[]` - return type: `java.lang.String` Description: see also: Formatter#byteArrayToHexString(byte[], int, int) ## Static Method: byteArrayToHexString - parameter: `data`, type: `byte[]` - parameter: `pos`, type: `int` - return type: `java.lang.String` Description: see also: Formatter#byteArrayToHexString(byte[], int, int) ## Static Method: byteArrayToHexString - parameter: `data`, type: `byte[]` - parameter: `pos`, type: `int` - parameter: `end`, type: `int` - return type: `java.lang.String` Description: Return the [String](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" ``` parameter: data: byte array to convert parameter: pos: first byte position parameter: end: last byte position \(excluded\) return: the [String](String) representation ## Static Method: escapeAllCharacters - parameter: `s`, type: `java.lang.CharSequence` - return type: `java.lang.String` Description: Force\-escape a string to a sequence of `\\u` character codes. All characters, regardless of their [printability](#escapeString(CharSequence, boolean)), are escaped. parameter: s: a string return: the escaped string ## Static Method: escapeByte - parameter: `ch`, type: `int` - return type: `java.lang.String` Description: Convert a byte to character such that a byte `0xBB` is converted to character `»`, and escape the resulting character. parameter: ch: byte value to escape return: the escaped character string ## Static Method: escapeBytes - parameter: `bytes`, type: `byte[]` - parameter: `offset`, type: `int` - parameter: `size`, type: `int` - return type: `java.lang.String` Description: 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. parameter: bytes: bytes array parameter: offset: start index parameter: size: count of bytes to escape return: the escaped string ## Static Method: escapeBytes - parameter: `bytes`, type: `byte[]` - return type: `java.lang.String` Description: 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. parameter: bytes: bytes array return: the escaped string ## Static Method: escapeCharacter - parameter: `c`, type: `char` - parameter: `keepUnicodePrintables`, type: `boolean` - return type: `java.lang.String` Description: Escape a character, if necessary. parameter: c: the character to be escaped parameter: keepUnicodePrintables: if true, a printable Unicode, non\-ASCII character will be left unescaped return: a string representing the escaped character ## Static Method: escapeCharacter - parameter: `c`, type: `char` - return type: `java.lang.String` Description: Escape a character, keeping Unicode printable characters. parameter: c: the character to escape return: a string representing the escaped character ## Static Method: escapeString - parameter: `s`, type: `java.lang.CharSequence` - return type: `java.lang.String` Description: Escape a string. Unicode printable characters are not escaped \(refer to [#isPrintableChar(char)](#isPrintableChar(char))\). Refer to [#escapeString(CharSequence, int, boolean, Set)](#escapeString(CharSequence, int, boolean, Set)). parameter: s: a [CharSequence](CharSequence) return: the escaped string ## Static Method: escapeString - parameter: `s`, type: `java.lang.CharSequence` - parameter: `keepUnicodePrintables`, type: `boolean` - return type: `java.lang.String` Description: Escape a string. Refer to [#escapeString(CharSequence, int, boolean, Set)](#escapeString(CharSequence, int, boolean, Set)). parameter: s: a [CharSequence](CharSequence) parameter: keepUnicodePrintables: if true, unicode printable characters are not escaped \(refer to [#isPrintableChar(char)](#isPrintableChar(char))\). return: the escaped string ## Static Method: escapeString - parameter: `s`, type: `java.lang.CharSequence` - parameter: `directionalityEnclosure`, type: `int` - parameter: `keepUnicodePrintables`, type: `boolean` - parameter: `doNotEscapeList`, type: `java.util.Set` - return type: `java.lang.String` Description: Escape a [CharSequence](CharSequence). parameter: s: the [CharSequence](CharSequence) to be escaped parameter: 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 parameter: keepUnicodePrintables: if true, unicode printable characters are not escaped \(refer to [#isPrintableChar(char)](#isPrintableChar(char))\), eg, KCJ/Russian/etc. character sets parameter: doNotEscapeList: optional collection of characters that won't be escaped return: the escaped string ## Static Method: escapeToJavaStringArray - parameter: `objects`, type: `java.util.Collection` - return type: `java.lang.String` Description: 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](#escapeString(CharSequence)) toString\(\) representation of the collection elements. parameter: objects: a collection of any objects return: the string representation of a string array ## Static Method: formatBinaryBlock - parameter: `data`, type: `byte[]` - parameter: `offset`, type: `int` - parameter: `size`, type: `int` - parameter: `offsetDelta`, type: `long` - parameter: `is64bit`, type: `boolean` - return type: `java.lang.CharSequence` Description: 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. parameter: data: bytes buffer parameter: offset: beginning of bytes sequence to be formatted parameter: size: number of bytes to be formatted parameter: offsetDelta: an offset delta parameter: is64bit: indicates if the prefix offset should be formatted as a 64\-bit or 32\-bit value return: a formatted [CharSequence](CharSequence) ## Static Method: formatBinaryBlock - parameter: `data`, type: `byte[]` - parameter: `offset`, type: `int` - parameter: `size`, type: `int` - parameter: `offsetDelta`, type: `int` - return type: `java.lang.CharSequence` Description: Format a block of bytes. Same as [formatBinaryBlock\(data, offset, size, offsetDelta, false\)](#formatBinaryBlock(byte[], int, int, long, boolean)) parameter: data: bytes buffer parameter: offset: beginning of bytes sequence to be formatted parameter: size: number of bytes to be formatted parameter: offsetDelta: offset delta subtracted from displayed offsets return: a formatted [CharSequence](CharSequence) ## Static Method: formatBinaryBlock - parameter: `data`, type: `byte[]` - parameter: `offset`, type: `int` - parameter: `size`, type: `int` - return type: `java.lang.CharSequence` Description: Format a block of bytes. Same as [formatBinaryBlock\(data, offset, size, 0\)](#formatBinaryBlock(byte[], int, int, int)) parameter: data: bytes buffer parameter: offset: beginning of bytes sequence to be formatted parameter: size: number of bytes to be formatted return: a formatted [CharSequence](CharSequence) ## Static Method: formatBinaryBlock - parameter: `data`, type: `byte[]` - return type: `java.lang.CharSequence` Description: Format a block of bytes. Same as [formatBinaryBlock\(data, 0, data.length\)](#formatBinaryBlock(byte[], int, int)) parameter: data: bytes buffer return: a formatted [CharSequence](CharSequence) ## Static Method: formatBinaryLine - parameter: `data`, type: `byte[]` - parameter: `offset`, type: `int` - parameter: `size`, type: `int` - parameter: `minVirtualSize`, type: `int` - return type: `java.lang.CharSequence` Description: Format a block of bytes as a hexadecimal [CharSequence](CharSequence) representation. Bytes will be represented space\-separated. parameter: data: bytes buffer parameter: offset: beginning of bytes sequence to be formatted parameter: size: number of bytes to be formatted parameter: minVirtualSize: minimum number of bytes that the resulting string is supposed to represent; phantom bytes \(formatted as empty space\) will be appended if necessary return: a formatted [CharSequence](CharSequence) ## Static Method: formatBinaryLine - parameter: `data`, type: `byte[]` - parameter: `offset`, type: `int` - parameter: `size`, type: `int` - parameter: `minVirtualSize`, type: `int` - parameter: `separateWithSpace`, type: `boolean` - return type: `java.lang.CharSequence` Description: Format a block of bytes as a hexadecimal [CharSequence](CharSequence) representation. parameter: data: bytes buffer parameter: offset: beginning of bytes sequence to be formatted parameter: size: number of bytes to be formatted parameter: minVirtualSize: minimum number of bytes represented by the result; phantom bytes are rendered as empty space if necessary parameter: separateWithSpace: true to insert a space after each formatted byte return: a formatted [CharSequence](CharSequence) ## Static Method: formatBinaryLine - parameter: `data`, type: `byte[]` - parameter: `offset`, type: `int` - parameter: `size`, type: `int` - return type: `java.lang.CharSequence` Description: Format a block of bytes. Same as [formatBinaryLine\(data, 0, size, size\)](#formatBinaryLine(byte[], int, int, int)). parameter: data: bytes buffer parameter: offset: beginning of bytes sequence to be formatted parameter: size: number of bytes to be formatted return: a formatted [CharSequence](CharSequence) ## Static Method: formatBinaryLine - parameter: `data`, type: `byte[]` - return type: `java.lang.CharSequence` Description: Format a block of bytes. Same as [formatBinaryLine\(data, 0, data.length, 0\)](#formatBinaryLine(byte[], int, int, int)). parameter: data: bytes buffer return: a formatted string ## Static Method: formatBinaryLineTruncate - parameter: `data`, type: `byte[]` - parameter: `offset`, type: `int` - parameter: `size`, type: `int` - parameter: `maxSize`, type: `int` - parameter: `truncateChar`, type: `char` - return type: `java.lang.CharSequence` Description: Format a fixed\-width hexadecimal byte line, truncating excess bytes. parameter: data: bytes buffer parameter: offset: beginning of bytes sequence to be formatted parameter: size: number of bytes to be formatted parameter: maxSize: maximum number of bytes to render parameter: truncateChar: character appended when the byte sequence is truncated return: a formatted [CharSequence](CharSequence) ## Static Method: formatBinaryLineTruncate - parameter: `data`, type: `byte[]` - parameter: `offset`, type: `int` - parameter: `size`, type: `int` - parameter: `fixedCount`, type: `int` - return type: `java.lang.CharSequence` Description: Format a fixed\-width hexadecimal byte line, truncating excess bytes with a plus sign. parameter: data: bytes buffer parameter: offset: beginning of bytes sequence to be formatted parameter: size: number of bytes to be formatted parameter: fixedCount: maximum number of bytes to render return: a formatted [CharSequence](CharSequence) ## Static Method: formatHexNumbers - parameter: `list`, type: `java.util.Collection` - return type: `java.lang.String` Description: Format a collection of numbers as upper\-case hexadecimal values. parameter: list: numbers to format return: a bracketed, comma\-separated list of hexadecimal values ## Static Method: formatNumbers - parameter: `list`, type: `java.util.Collection` - parameter: `base`, type: `int` - parameter: `pfx`, type: `java.lang.String` - parameter: `sfx`, type: `java.lang.String` - return type: `java.lang.String` Description: Format a collection of numbers in the requested base. parameter: list: numbers to format parameter: base: numeric base; supported values are 8, 10, and 16 parameter: pfx: optional prefix added before each number parameter: sfx: optional suffix added after each number return: a bracketed, comma\-separated list of formatted values ## Static Method: hexStringToByteArray - parameter: `s`, type: `java.lang.String` - parameter: `pos`, type: `int` - parameter: `end`, type: `int` - return type: `byte[]` Description: 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 ``` parameter: s: Input String parameter: pos: the start parsing position parameter: end: the end parsing position return: the byte array ## Static Method: hexStringToByteArray - parameter: `s`, type: `java.lang.String` - return type: `byte[]` Description: Convert a series of hexadecimal String to a byte array. Remove potential "h" suffix and "0x" prefix. parameter: s: Input String return: the byte array ## Static Method: htmlEscape - parameter: `str`, type: `java.lang.String` - return type: `java.lang.String` Description: Escape HTML 4 entities by their `&xxx;` equivalents. Line\-feeds are **not** replaced by the \(unescaped\) `
` tag. parameter: str: the string to escape return: the escaped string ## Static Method: htmlEscape - parameter: `str`, type: `java.lang.String` - parameter: `replaceNewlinesByBR`, type: `boolean` - return type: `java.lang.String` Description: Escape HTML 4 entities by their `&xxx;` equivalents. parameter: str: the string to escape parameter: replaceNewlinesByBR: if true, new\-line combos \(CR, LF, or CRLF\) are replaced by the \(unescaped\) `
` tag followed by the original new\-line combo return: the escaped string ## Static Method: integerToAlphaString - parameter: `n`, type: `int` - return type: `java.lang.String` Description: 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 ... ``` parameter: n: an integer, treated as unsigned return: a string associated to this integer ## Static Method: isPrintableChar - parameter: `c`, type: `char` - return type: `boolean` Description: 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)](#addCustomPrintableCharRange(int, int, boolean)) and [#resetCustomPrintableCharRanges()](#resetCustomPrintableCharRanges()). parameter: c: the input character return: true if the character is printable ## Static Method: resetCustomPrintableCharRanges Description: Clear all custom printable and non\-printable character ranges. ## Static Method: toHexString - parameter: `v`, type: `long` - parameter: `upperCase`, type: `boolean` - parameter: `padZero`, type: `int` - return type: `java.lang.String` Description: Convert a long to its hex representation. parameter: v: long to convert parameter: upperCase: true if the hex must be in upper case parameter: padZero: indicate the number of characters that will be output \(will pad with zeroes\) return: The hex representation ## Static Method: toHexString - parameter: `v`, type: `long` - parameter: `upperCase`, type: `boolean` - return type: `java.lang.String` Description: Convert a long to its hex representation. parameter: v: long to convert parameter: upperCase: true if the hex must be in upper case return: The hex representation ## Static Method: toHexString - parameter: `v`, type: `int` - parameter: `upperCase`, type: `boolean` - parameter: `padZero`, type: `int` - return type: `java.lang.String` Description: Convert a int to its hex representation. parameter: v: int to convert parameter: upperCase: true if the hex must be in upper case parameter: padZero: indicate the number of characters that will be output \(will pad with zeroes\) return: The hex representation ## Static Method: toHexString - parameter: `v`, type: `int` - parameter: `upperCase`, type: `boolean` - return type: `java.lang.String` Description: Convert an int to its hex representation. parameter: v: int to convert parameter: upperCase: true if the hex must be in upper case return: The hex representation ## Static Method: toHexString - parameter: `v`, type: `short` - parameter: `upperCase`, type: `boolean` - parameter: `padZero`, type: `int` - return type: `java.lang.String` Description: Convert a short to its hex representation. parameter: v: short to convert parameter: upperCase: true if the hex must be in upper case parameter: padZero: indicate the number of characters that will be output \(will pad with zeroes\) return: The hex representation ## Static Method: toHexString - parameter: `v`, type: `short` - parameter: `upperCase`, type: `boolean` - return type: `java.lang.String` Description: Convert a short to its hex representation. parameter: v: short to convert parameter: upperCase: true if the hex must be in upper case return: The hex representation ## Static Method: toHexString - parameter: `v`, type: `byte` - parameter: `upperCase`, type: `boolean` - parameter: `padZero`, type: `int` - return type: `java.lang.String` Description: Convert a byte to its hex representation. parameter: v: byte to convert parameter: upperCase: true if the hex must be in upper case parameter: padZero: indicate the number of characters that will be output \(will pad with zeroes\) return: The hex representation ## Static Method: toHexString - parameter: `v`, type: `byte` - parameter: `upperCase`, type: `boolean` - return type: `java.lang.String` Description: Convert a byte to its hex representation. parameter: v: byte to convert parameter: upperCase: true if the hex must be in upper case return: The hex representation ## Static Method: toString - parameter: `o`, type: `java.lang.Object` - return type: `java.lang.String` Description: Pretty\-format any object, using a [PrettyPrinter](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. parameter: o: an object return: a decent string representation of the object ## Static Method: unescapeString - parameter: `s`, type: `java.lang.String` - return type: `java.lang.String` Description: Unescape a string escaped with standard String\-formatter backslash\-based escape sequences. parameter: s: an escaped string, allowed escapes: \\\\ \\' \\" \\n \\r \\t \\b \\f \\u???? \\x?? return: the unescaped string throws: if an error occurs ## Static Method: wordWrap - parameter: `str`, type: `java.lang.String` - parameter: `wrapLength`, type: `int` - parameter: `wrapType`, type: `int` - return type: `java.util.List` Description: 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. parameter: str: the text buffer to be wrapped parameter: wrapLength: wrapping length, must be strictly positive parameter: 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\) return: an array of strings