cppdraft_translate/cppdraft/format/string/escaped.md

[format.string.escaped]

28 Text processing library [text]

28.5 Formatting [format]

28.5.6 Formatter [format.formatter]

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

1

#

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

2

#

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)](#2.2.1.1)
      If *C* is one of the characters in Table [114](#tab:format.escape.sequences "Table 114: Mapping of characters to escape sequences"),
      

then the two characters shown as the corresponding escape sequence are appended to E.

+
      [(2.2.1.2)](#2.2.1.2)
      Otherwise, if *C* is not U+0020 space and

  - [(2.2.1.2.1)](#2.2.1.2.1)

CE is UTF-8, UTF-16, or UTF-32 andC corresponds to a Unicode scalar value whose Unicode property General_Category has a value in the groupsSeparator (Z) or Other (C), as described by UAX #44 of the Unicode Standard, or

  - [(2.2.1.2.2)](#2.2.1.2.2)

CE is UTF-8, UTF-16, or UTF-32 andC corresponds to a Unicode scalar value with the Unicode property Grapheme_Extend=Yes as described by UAX #44 of the Unicode Standard andC 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)](#2.2.1.2.3)

CE is neither UTF-8, UTF-16, nor UTF-32 andC 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)](#2.2.1.3)
      Otherwise, *C* is appended to *E*[.](#2.2.1.3.sentence-1)

• (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 114 — 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	\

3

#

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}♂"] 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: ["ẹ́"] — end example]