Utf8EscapeControlChars function

Declaration

function Utf8EscapeControlChars(S: string; 
 EscapeMode: TEscapeMode=emPascal; 
 CustomStrings: PEscapedStrings=Nil; 
 AMaxGrowFactor: Cardinal=0): string

Arguments

Function result

String with the escaped values for control characters found in S.

Description

Utf8EscapeControlChars translates control characters inside a UTF-8-encoded string into human-readable escaped format. S is the UTF-8-encoded string examined and converted in the routine. Characters in the TControlChars range (#0..#31) are converted into the human-readable values for the control characters in the format specified by EscapeMode, including:

emPascal

Pascal-style escape characters '#27'

emHexPascal

Pascal-style hexadecimal strings '#$1B'

emC

C-style strings '\e'

emHexC

C-style hexadecimal strings '\0x1B'

emAsciiControlNames

ASCII-style control names '[ESC]'

emPercent

Percent-encoded control characters '%0D'

emCustom

User-defined encoding style defined in the CustomStrings argument.

CustomStrings is a PEscapedStrings argument which contains the replacement values for control characters when EscapeMode is set to emCustom. It is a Pointer to the fixed-size TEscapedStrings array where the custom encoding is defined for the control characters. CustomStrings cannot be Nil (unassigned) when EscapeMode is set to emCustom; an EInvalidOp exception is raised if CustomStrings has not been assigned.

AMaxGrowFactor specifies the maximum growth allowed when converting S using the specified EscapeMode. Most escape encoding styles have a maximum growth factor of 3, 4, or 5. emCustom does not specify a growth factor limit (0 is used). The growth factor is calculated by examining each of the values in the fixed-length CustomStrings array. As a result, emCustom can be the slowest of the escape encoding styles.

Utf8EscapeControlChars calls FindInvalidUTF8Codepoint to see if S contains any invalid codepoints for the UTF-8 encoding. UTF8FixBroken is called to repair the input value.

Utf8EscapeControlChars iterates over the values in S, and converts any control character value in the range #0..#31 using a conversion table for the value in EscapeMode. All other character values (or byte values in a multi-byte UTF-8 code point) are included in the return value in their unmodified form.

Mainly used as a diagnostic or logging tool.

Modified in LazUtils version 5.0 to include new encoding styles in EscapeMode, and use of the CustomStrings argument.

See also

• TEscapeMode
• TEscapedStrings
• PEscapedStrings
• UTF8FixBroken