lib/string-escape.x

Escaped spelling of canonical strings.

Primary API

String

String.unescape

meta native String String.unescape(String str)

Decodes supported backslash escapes in str into a canonical String. Standard single-byte escapes, up to two hexadecimal digits after x, u, or U, and up to three octal digits are consumed. A backslash-newline is removed, an unknown escape yields its following byte, and a trailing backslash is dropped. Null input returns NULL and input without a backslash is returned unchanged.

Raises: <bad-arg> for an octal escape above \377, which does not fit a byte, or <alloc-fail> while constructing a changed result.

Source: lib/string-escape.x:124

Advanced and interop API

String

String.escape

meta native String String.escape(String str)

Returns a canonical escaped representation of the bytes in str. Common control and delimiter bytes use named escapes, printable ASCII is copied, and every other byte uses a three-digit octal escape. Null input or an oversized result returns NULL.

Raises: <alloc-fail> while constructing the result.

Source: lib/string-escape.x:33

String.parse

meta native String String.parse(String str)

Returns the canonical unescaped contents of str. Matching outer %"..." or "..." delimiters are removed; unquoted input is unescaped directly. Null or empty input returns NULL. An unquoted input without backslashes is returned unchanged.

Raises: <alloc-fail> while copying or decoding.

Source: lib/string-escape.x:232

String.parse_char

meta native int String.parse_char(String str)

Parses one leading single-quoted escaped or literal byte, or returns -1. The opening quote, one decoded byte, and a closing quote are required. Text after that closing quote is ignored. A decoded NUL is returned as zero; malformed and null input returns -1, as does an octal escape above \377, which does not fit a byte.

Source: lib/string-escape.x:213

String.repr

String String.repr(String str)

Returns a canonical quoted and escaped representation of str. Empty input returns the canonical literal spelling "\"\"".

Raises: <alloc-fail> while escaping or formatting a nonempty String.

Source: lib/string-escape.x:92

String.write_repr

Buffer String.write_repr(String str, Buffer out)

Appends a quoted escaped representation of str to borrowed out. Bytes are streamed without first allocating an intermediate String. The same out is returned and not retained. Text written before a failure remains in the Buffer.

Raises: any cause from Buffer.write_char or Buffer.write_len.

Source: lib/string-escape.x:103

Design notes

This module translates between a String’s bytes and their escaped spelling inside a C or x2c string literal: escape, repr, and write_repr write it, and unescape, parse, and parse_char read it. A changed result is built in a String.malloc buffer and finalized by String.intern_free, so the canonical header stays private to string.x.

Tests and examples

make verify (unittest/test-string.x).