ddn.util.json_escape¶

JSON and JSON5 string escaping utilities for the D programming language.

Overview¶

This module provides efficient, allocation-aware routines for escaping strings according to JSON and JSON5 specifications. It is used internally by ddn.var and ddn.data.json5 to produce correctly escaped string literals during serialization.

Features:

Fast-path detection: Strings requiring no escaping are returned as-is.
Standard short escapes: \b, \f, \n, \r, \t for common control characters.
Unicode escapes: \uXXXX for control characters and optionally all non-ASCII code points.
Surrogate pairs: Proper handling for code points above U+FFFF when asciiOnly is enabled.
Configurable quotes: Support for both " and ' (JSON5 single-quoted strings).
Memory safe: @safe implementations throughout.

Functions¶

`escapeJSONString`¶

string escapeJSONString(const string s, const char quote = '"', const bool asciiOnly = false) @safe

Escapes a UTF-8 string for inclusion in a JSON/JSON5 string literal.

This function returns the escaped string without surrounding quotes.

Parameters:

Name	Type	Default	Description
`s`	`string`	—	Input UTF-8 string
`quote`	`char`	`'"'`	Quote character that must be escaped (`'"'` or `'\''`)
`asciiOnly`	`bool`	`false`	When `true`, escape non-ASCII code points using `\uXXXX`

Returns: The escaped string. When no escaping is required and asciiOnly == false, returns s unchanged.

Example:

import ddn.util.json_escape;

// Basic escaping
assert(escapeJSONString("hello\nworld") == "hello\\nworld");

// Escaping quotes
assert(escapeJSONString("say \"hi\"") == "say \\\"hi\\\"");

// Single quote escaping for JSON5
assert(escapeJSONString("it's easy", '\'') == "it\\'s easy");

// ASCII-only output
string ascii = escapeJSONString("café ☕", '"', true);
// Result: "caf\\u00E9 \\u2615"

Escape Sequences:

Character	Escape
`\b` (backspace)	`\\b`
`\f` (form feed)	`\\f`
`\n` (newline)	`\\n`
`\r` (carriage return)	`\\r`
`\t` (tab)	`\\t`
`\\` (backslash)	`\\\\`
`"` (double quote)	`\\"` (when `quote == '"'`)
`'` (single quote)	`\\'` (when `quote == '\''`)
Control chars (0x00–0x1F)	`\\u00XX`
Non-ASCII (when `asciiOnly`)	`\\uXXXX` or surrogate pairs

`writeJSONString`¶

void writeJSONString(Sink)(const(char)[] s, ref Sink sink, const bool asciiOnly = false, const char quote = '"') @safe

Writes a quoted and escaped JSON string directly to an output sink.

This function writes the complete string literal including surrounding quotes.

Template Parameters:

Name	Description
`Sink`	Output range type (e.g., `Appender!string`)

Parameters:

Name	Type	Default	Description
`s`	`const(char)[]`	—	Input string to escape and write
`sink`	`ref Sink`	—	Output sink to write to
`asciiOnly`	`bool`	`false`	When `true`, escape non-ASCII code points
`quote`	`char`	`'"'`	Quote character to use (`'"'` or `'\''`)

Example:

import ddn.util.json_escape;
import std.array : appender;

// Write a double-quoted JSON string
auto buf = appender!string();
writeJSONString("say \"hi\"", buf);
assert(buf.data == `"say \"hi\""`);

// Write a single-quoted JSON5 string
buf.clear();
writeJSONString("it's easy", buf, false, '\'');
assert(buf.data == "'it\\'s easy'");

// ASCII-only output
buf.clear();
writeJSONString("日本語", buf, true);
// Result: "\u65E5\u672C\u8A9E"

Performance Considerations¶

Zero-copy fast path: Strings without special characters are returned without allocation when using escapeJSONString.
Pre-allocated buffers: Output buffer is pre-sized based on input length to minimize reallocations.
Efficient hex encoding: Manual hex digit emission avoids std.format overhead.
Single pass: Input is scanned once for both detection and transformation.

Integration¶

This module is used internally by:

ddn.var.toJSON() — For JSON serialization of var values.
ddn.data.json5.toJSON5() — For JSON5 serialization.
ddn.data.json5.toJSON() — For strict JSON serialization.

You can also use it directly when building custom serializers or when you need fine-grained control over string escaping.