pub fn decode_text(text: &BytesText<'_>) -> Result<String>Expand description
Decodes an XML text event’s content: character-encoding decoding (e.g.
UTF-16 to UTF-8) via quick_xml::events::BytesText::decode, plus a
defensive unescape() pass in case any literal &...; survived in the
event’s own bytes (see below for why that’s normally not needed).
§Why a Text event alone isn’t the whole story
Despite what a quick read of BytesText::decode’s doc comment might
suggest, a quick_xml Reader does not hand back one Event::Text
containing an entire text node’s escaped content verbatim. Starting
with the version this project depends on (quick_xml 0.41), any
&entity;/&#NNN; reference found in text content is split out into
its own dedicated event, quick_xml::events::Event::GeneralRef —
confirmed by reading quick_xml’s own Event enum documentation after
a real round-trip test (an apostrophe in a footnote’s text) came back
not as a literal ' and not restored to ', but entirely
missing, which a pure “forgot to unescape” bug wouldn’t explain (that
would leave the entity text verbatim, not delete it). The surrounding
plain-text fragments arrive as ordinary (already-unescaped-looking)
Text events; the reference itself must be resolved separately via
decode_general_ref and appended in between — see word-ooxml’s
parse_paragraph for the accumulation loop that does this. Callers
that only ever call .decode() (or this function) on Text events and
silently ignore GeneralRef — as this crate’s readers did before this
was diagnosed — see every entity vanish, not survive unescaped.
This function’s own unescape() call is consequently closer to a
no-op/safety-net for stray literal & sequences than the primary fix;
kept anyway since it’s harmless and cheap. See the CHANGELOG for the
full story.