diff --git a/CHANGELOG.md b/CHANGELOG.md index 2ddad04..940e442 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed +- Output escaping copies the verbatim runs between escapable characters in bulk instead of rebuilding the value one character at a time. `Escaping.text` and `Escaping.attribute` appended each character on its own (`result += String(character)` for every unescaped character) when a value needed escaping, so re-escaping a text node that holds a single `&` rebuilt it grapheme by grapheme. They now copy each run between escapable characters in a single append and rewrite only the markers (`&`, `<`, `>`, the attribute quote and whitespace, and, in ASCII-only mode, non-ASCII characters). The no-escaping-needed fast path is unchanged. The output is byte-identical. Measured `serialize` ~7% faster on the 20k-item generated corpus (whose decoded text re-escapes an `&`) via a same-machine-state A/B. Verified by a per-character-oracle differential with multibyte cases (`EscapingBulkCopyTests`), the Apache Xalan gold-output and C14N canonicalization suites, and an adversarial review including a 400k-input fuzz. + - `parseTree` assembles the mutable `TreeNode` tree directly from the event stream instead of building the immutable value `Node` tree and converting it. The old path allocated two full trees: the parser built a value `Node` tree, then `TreeNode.init(_:)` walked it to build the reference tree. `Parser.buildTree` is the direct counterpart to the value-tree assembler, the same iterative event loop with the same element stack and the same well-formedness guards (it throws on an unmatched end tag and on a document with no element), but it accumulates `TreeNode` children per frame and adopts them when the element closes, so the tree is allocated once. The produced tree is identical, the same node kinds, names, attributes, values, child order, and parent links. Measured `parse` ~8% faster on the 20k-item generated corpus via a same-machine-state A/B. Verified by a structural differential against the convert-from-`Node` path (`ParseTreeDirectBuildTests`), the full suite and the W3C XML conformance, RELAX NG, and Apache Xalan corpora (which all materialize trees through `parseTree`), and an adversarial equivalence review. - The entity decoder finds its markers at the byte level. `EntityExpander.expand` located the next `&`, `<`, and `;` with `String.firstIndex` over graphemes, decoding every literal byte of the run into a grapheme just to look for a one-byte marker. All three markers are ASCII, so a UTF-8 index is a valid string index: the scan now runs over `raw.utf8` and the found index still subscripts the string directly. The decoded text is unchanged, including text where the markers follow multibyte UTF-8 (precomposed, combining, and astral characters all keep the marker on a grapheme boundary). Measured `parse` ~5.5% faster on the 20k-item generated corpus via a same-machine-state A/B. Verified by the decode differential (`EntityDecodeBulkTests`, extended with multibyte-boundary cases) and the W3C XML conformance corpora. diff --git a/Sources/Emitting/Escaping.swift b/Sources/Emitting/Escaping.swift index 19c8dcf..21b6463 100644 --- a/Sources/Emitting/Escaping.swift +++ b/Sources/Emitting/Escaping.swift @@ -12,15 +12,28 @@ extension PureXML.Emitting { return value } var result = "" - for character in value { - switch character { - case "&": result += "&" - case "<": result += "<" - case ">": result += ">" - case "\r" where escapeCarriageReturn: result += " " - default: result += plain(character, asciiOnly: asciiOnly) + var runStart = value.startIndex + var index = value.startIndex + while index < value.endIndex { + let character = value[index] + let escaped: String? = switch character { + case "&": "&" + case "<": "<" + case ">": ">" + case "\r" where escapeCarriageReturn: " " + default: asciiOnly ? plainIfNonASCII(character) : nil } + let next = value.index(after: index) + if let escaped { + // Copy the verbatim run before this character in one append + // rather than appending each unescaped character on its own. + if runStart < index { result += value[runStart ..< index] } + result += escaped + runStart = next + } + index = next } + if runStart < value.endIndex { result += value[runStart...] } return result } @@ -40,6 +53,14 @@ extension PureXML.Emitting { return false } + /// In ASCII-only mode, the numeric-reference escaping of a character that + /// carries a non-ASCII scalar, or nil when the character is pure ASCII and + /// so is copied verbatim with its run. + private static func plainIfNonASCII(_ character: Character) -> String? { + guard character.unicodeScalars.contains(where: { $0.value > 0x7F }) else { return nil } + return plain(character, asciiOnly: true) + } + /// A character verbatim, or, in ASCII-only mode, each of its non-ASCII /// scalars as a numeric character reference so the output is pure ASCII. private static func plain(_ character: Character, asciiOnly: Bool) -> String { @@ -58,24 +79,39 @@ extension PureXML.Emitting { return value } var result = "" - for character in value { - if character == quote { - result += quote == "'" ? "'" : """ - continue - } - switch character { - case "&": result += "&" - case "<": result += "<" - case ">": result += ">" - case "\t": result += " " - case "\n": result += " " - case "\r": result += " " - default: result += plain(character, asciiOnly: asciiOnly) + var runStart = value.startIndex + var index = value.startIndex + while index < value.endIndex { + let character = value[index] + let next = value.index(after: index) + if let escaped = attributeEscape(character, quote: quote, asciiOnly: asciiOnly) { + if runStart < index { result += value[runStart ..< index] } + result += escaped + runStart = next } + index = next } + if runStart < value.endIndex { result += value[runStart...] } return result } + /// The escaped form of one attribute-value character, or nil when it is + /// copied verbatim. Split out so ``attribute`` stays a simple run loop. + private static func attributeEscape(_ character: Character, quote: Character, asciiOnly: Bool) -> String? { + if character == quote { + return quote == "'" ? "'" : """ + } + switch character { + case "&": return "&" + case "<": return "<" + case ">": return ">" + case "\t": return " " + case "\n": return " " + case "\r": return " " + default: return asciiOnly ? plainIfNonASCII(character) : nil + } + } + /// Whether ``attribute`` would change `value`: it escapes the quote, the /// markup characters, the whitespace characters, and (in ASCII-only mode) /// any non-ASCII byte. Every trigger is ASCII bar the non-ASCII lead. diff --git a/Tests/EscapingBulkCopyTests.swift b/Tests/EscapingBulkCopyTests.swift new file mode 100644 index 0000000..f4ed99c --- /dev/null +++ b/Tests/EscapingBulkCopyTests.swift @@ -0,0 +1,79 @@ +import Testing +@testable import PureXML + +/// `Escaping.text` and `Escaping.attribute` copy the verbatim runs between +/// escapable characters in bulk instead of appending each character one at a +/// time. These pin the escaped output against the per-character reference for +/// markers at the start, end, and adjacent; long verbatim runs around them; +/// multibyte runs (the copied run spans whole graphemes); both quote styles; +/// and ASCII-only mode (where a non-ASCII character escapes and an ASCII one is +/// copied with its run). +@Suite("Escaping bulk-copy equivalence") +struct EscapingBulkCopyTests { + private typealias Escaping = PureXML.Emitting.Escaping + + /// The per-character escaping the bulk path replaced, kept here as the oracle. + private func referenceText(_ value: String, asciiOnly: Bool, escapeCarriageReturn: Bool) -> String { + var result = "" + for character in value { + switch character { + case "&": result += "&" + case "<": result += "<" + case ">": result += ">" + case "\r" where escapeCarriageReturn: result += " " + default: + if asciiOnly { + for scalar in character.unicodeScalars { + result += scalar.value > 0x7F ? "&#x\(String(scalar.value, radix: 16, uppercase: true));" : String(scalar) + } + } else { + result += String(character) + } + } + } + return result + } + + private static let texts = [ + "plain text no markup", + "a & b < c > d", + "&<>", "&start", "end&", "&&&", + "café & thé", "e\u{0301} < x", "\u{1F600}&\u{1F601}", + "tab\tnewline\ncr\r", "naïve résumé", + String(repeating: "x", count: 300) + "&" + String(repeating: "y", count: 300), + ] + + @Test("text bulk-escape matches the per-character reference") + func test_textEquivalence() { + for value in Self.texts { + for asciiOnly in [false, true] { + for escapeCR in [false, true] { + #expect( + Escaping.text(value, asciiOnly: asciiOnly, escapeCarriageReturn: escapeCR) + == referenceText(value, asciiOnly: asciiOnly, escapeCarriageReturn: escapeCR), + "text mismatch for \(value.debugDescription) ascii=\(asciiOnly) cr=\(escapeCR)", + ) + } + } + } + } + + @Test("attribute bulk-escape escapes quotes, markup, and whitespace") + func test_attributeEquivalence() { + #expect(Escaping.attribute(#"a "b" c"#, quote: "\"") == "a "b" c") + #expect(Escaping.attribute("a 'b' c", quote: "'") == "a 'b' c") + #expect(Escaping.attribute(#"a "b" 'c'"#, quote: "\"") == #"a "b" 'c'"#) + #expect(Escaping.attribute("x & y < z", quote: "\"") == "x & y < z") + #expect(Escaping.attribute("tab\tnl\ncr\r", quote: "\"") == "tab nl cr ") + #expect(Escaping.attribute("café & \"q\"", quote: "\"") == "café & "q"") + #expect(Escaping.attribute("no escapes here", quote: "\"") == "no escapes here") + } + + @Test("a document with re-escaped content round-trips identically") + func test_documentRoundTrip() throws { + let document = #"t & u < v"# + let tree = try PureXML.parseTree(document) + let again = try PureXML.parseTree(PureXML.serialize(tree.node)) + #expect(PureXML.serialize(tree.node) == PureXML.serialize(again.node)) + } +} diff --git a/docs/benchmarks.md b/docs/benchmarks.md index 9bb9538..2d4d4be 100644 --- a/docs/benchmarks.md +++ b/docs/benchmarks.md @@ -74,6 +74,7 @@ offsets throughout; libxml2's xmlReadMemory takes an int byte count). | 20 | adopt prepared children when materializing the tree instead of appending them one at a time: building the mutable `TreeNode` tree from the parsed value `Node` ran `append` per child, which detaches the child from any old parent, checks for a cycle, and grows the children array element by element; the converted children are freshly built and parentless, so `TreeNode.init(adopting:)` takes the prepared array directly and only wires each child's parent. Identical tree (parent-wiring differential + W3C conformance + adversarial review; same-state A/B, ~12%) | 0.106 s (~6.5x) | unchanged | unchanged | | 21 | scan for the entity decoder's markers at the byte level: `EntityExpander.expand` found the next `&`, `<`, and `;` with `String.firstIndex` over graphemes; since all three are ASCII, a UTF-8 index is a valid string index, so the scan runs over `raw.utf8` and skips decoding every literal byte into a grapheme just to look for a marker. Same decoded text (the bulk + 4 multibyte-boundary cases in the decode differential + W3C conformance; same-state A/B, ~5.5%) | 0.099 s (~6.1x) | unchanged | unchanged | | 22 | build the mutable `TreeNode` tree directly from the event stream instead of building the value `Node` tree and converting it: `parseTree` ran `TreeNode(parse(...))`, allocating two full trees (the value tree, then a converted reference tree). `Parser.buildTree` is the direct counterpart to `build` (same event loop, stack discipline, and well-formedness guards) that accumulates `TreeNode` children per frame and adopts them when an element closes, so the tree is allocated once. Identical tree (structural differential against the convert path + the whole suite and conformance corpora, which all run through `parseTree`, + adversarial review; same-state A/B, ~8%) | 0.090 s (~5.5x) | unchanged | unchanged | +| 23 | bulk-copy the verbatim runs when escaping output: `Escaping.text`/`attribute` rebuilt a value that needed escaping character by character (`result += String(character)` per unescaped character), so re-escaping a text node that holds a single `&` rebuilt it grapheme by grapheme; they now copy each run between escapable characters in one append and only the markers are rewritten. The `*NeedsEscaping` fast path (no rebuild when nothing needs escaping) is unchanged. Byte-identical output (per-character-oracle differential with multibyte cases + Apache Xalan gold output + C14N suite + adversarial 400k fuzz; same-state A/B, ~7%) | unchanged | unchanged | 0.029 s (~2.8x) | ## Profile findings (first sample, parse path)