# 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<java.lang.Character>`
- 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<? extends java.lang.Object>`
- 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<? extends java.lang.Number>`
- 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<? extends java.lang.Number>`
- 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\) `<br>
 ` 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\) `<br>` 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<java.lang.String>`

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

