22 General utilities library [utilities]

22.14 Formatting [format]

22.14.6 Formatter [format.formatter]

22.14.6.4 Formatting escaped characters and strings [format.string.escaped]

A character or string can be formatted as escaped to make it more suitable for debugging or for logging.

The escaped string E representation of a string S is constructed by encoding a sequence of characters as follows.

The associated character encoding CE for charT (Table 12) is used to both interpret S and construct E.

(2.1)
U+0022 quotation mark (") is appended to E.
(2.2)
For each code unit sequence X in S that either encodes a single character, is a shift sequence, or is a sequence of ill-formed code units, processing is in order as follows:
- (2.2.1)
  If X encodes a single character C, then:
  - (2.2.1.1)
    If C is one of the characters in Table 75, then the two characters shown as the corresponding escape sequence are appended to E.
  - (2.2.1.2)
    Otherwise, if C is not U+0020 space and
    (2.2.1.2.1)
    CE is UTF-8, UTF-16, or UTF-32 and C corresponds to a Unicode scalar value whose Unicode property General_Category has a value in the groups Separator (Z) or Other (C), as described by UAX #44 of the Unicode Standard, or
    (2.2.1.2.2)
    CE is UTF-8, UTF-16, or UTF-32 and C corresponds to a Unicode scalar value with the Unicode property Grapheme_Extend=Yes as described by UAX #44 of the Unicode Standard and C is not immediately preceded in S by a character P appended to E without translation to an escape sequence, or
    (2.2.1.2.3)
    CE is neither UTF-8, UTF-16, nor UTF-32 and C is one of an implementation-defined set of separator or non-printable characters
    then the sequence \u{hex-digit-sequence} is appended to E, where hex-digit-sequence is the shortest hexadecimal representation of C using lower-case hexadecimal digits.
  - (2.2.1.3)
    Otherwise, C is appended to E.
- (2.2.2)
  Otherwise, if X is a shift sequence, the effect on E and further decoding of S is unspecified.
  Recommended practice: A shift sequence should be represented in E such that the original code unit sequence of S can be reconstructed.
- (2.2.3)
  Otherwise (X is a sequence of ill-formed code units), each code unit U is appended to E in order as the sequence \x{hex-digit-sequence}, where hex-digit-sequence is the shortest hexadecimal representation of U using lower-case hexadecimal digits.
(2.3)
Finally, U+0022 quotation mark (") is appended to E.

Table 75: Mapping of characters to escape sequences [tab:format.escape.sequences]

🔗	Character	Escape sequence
🔗	U+0009 character tabulation	\t
🔗	U+000a line feed	\n
🔗	U+000d carriage return	\r
🔗	U+0022 quotation mark	\"
🔗	U+005c reverse solidus	\\

The escaped string representation of a character C is equivalent to the escaped string representation of a string of C, except that:

(3.1)
the result starts and ends with U+0027 apostrophe (') instead of U+0022 quotation mark ("), and
(3.2)
if C is U+0027 apostrophe, the two characters \' are appended to E, and
(3.3)
if C is U+0022 quotation mark, then C is appended unchanged.

[Example 1: string s0 = format("[{}]", "h\tllo"); // s0 has value: [h llo] string s1 = format("[{:?}]", "h\tllo"); // s1 has value: ["h\tllo"] string s2 = format("[{:?}]", "Спасибо, Виктор ♥!"); // s2 has value: ["Спасибо, Виктор ♥!"] string s3 = format("[{:?}, {:?}]", '\'', '"'); // s3 has value: ['\'', '"'] // The following examples assume use of the UTF-8 encoding string s4 = format("[{:?}]", string("\0 \n \t \x02 \x1b", 9)); // s4 has value: ["\u{0} \n \t \u{2} \u{1b}"] string s5 = format("[{:?}]", "\xc3\x28"); // invalid UTF-8, s5 has value: ["\x{c3}("] string s6 = format("[{:?}]", "🤷🏻‍♂️"); // s6 has value: ["🤷\u{200d}♂\u{fe0f}"] string s7 = format("[{:?}]", "\u0301"); // s7 has value: ["\u{301}"] string s8 = format("[{:?}]", "\\\u0301"); // s8 has value: ["\\\u{301}"] string s9 = format("[{:?}]", "e\u0301\u0323"); // s9 has value: ["ẹ́"] — end example]