aws_smithy_xml/
unescape.rs

1/*
2 * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3 * SPDX-License-Identifier: Apache-2.0
4 */
5
6use crate::decode::XmlDecodeError;
7use std::borrow::Cow;
8
9/// Unescape XML encoded characters
10///
11/// This function will unescape the 4 literal escapes:
12/// - `&lt;`, `&gt;`, `&amp;`, `&quot;`, and `&apos;`
13/// - Decimal escapes: `&#123;`
14/// - Hex escapes: `&#xD;`
15///
16/// If no escape sequences are present, Cow<&'str> will be returned, avoiding the need
17/// to copy the String.
18pub(crate) fn unescape(s: &str) -> Result<Cow<'_, str>, XmlDecodeError> {
19    // no &, no need to escape anything
20    if !s.contains('&') {
21        return Ok(Cow::Borrowed(s));
22    }
23    // this will be strictly larger than required avoiding the need for another allocation
24    let mut res = String::with_capacity(s.len());
25    // could consider memchr as performance optimization
26    let mut sections = s.split('&');
27    // push content before the first &
28    if let Some(prefix) = sections.next() {
29        res.push_str(prefix);
30    }
31    for section in sections {
32        // entities look like &<somedata>;
33        match section.find(';') {
34            Some(idx) => {
35                let entity = &section[..idx];
36                match entity {
37                    "lt" => res.push('<'),
38                    "gt" => res.push('>'),
39                    "amp" => res.push('&'),
40                    "quot" => res.push('"'),
41                    "apos" => res.push('\''),
42                    entity => {
43                        // e.g. &#xD;
44                        let (entity, radix) = if let Some(entity) = entity.strip_prefix("#x") {
45                            (entity, 16)
46                        } else if let Some(entity) = entity.strip_prefix('#') {
47                            // e.g. &#123;
48                            (entity, 10)
49                        } else {
50                            return Err(XmlDecodeError::invalid_escape(entity));
51                        };
52                        let char_code = u32::from_str_radix(entity, radix).map_err(|_| {
53                            XmlDecodeError::invalid_escape(format!(
54                                "expected numeric escape in base {}; got: {}",
55                                radix, &entity
56                            ))
57                        })?;
58                        let chr = std::char::from_u32(char_code).ok_or_else(|| {
59                            XmlDecodeError::invalid_escape(format!(
60                                "invalid char code: {char_code}"
61                            ))
62                        })?;
63                        res.push(chr);
64                    }
65                }
66                // push everything from the `;` to the next `&`
67                res.push_str(&section[idx + 1..])
68            }
69            None => return Err(XmlDecodeError::invalid_escape("unterminated pattern")),
70        }
71    }
72    Ok(Cow::Owned(res))
73}
74
75#[cfg(test)]
76mod test {
77    use crate::unescape::unescape;
78    use std::borrow::Cow;
79
80    #[test]
81    fn basic_unescape() {
82        assert_eq!(
83            unescape("&lt; &gt; &apos; &quot; &amp;").unwrap(),
84            "< > ' \" &"
85        );
86        assert_eq!(
87            unescape("Since a &gt; b, b is less than a").unwrap(),
88            "Since a > b, b is less than a"
89        );
90    }
91
92    #[test]
93    fn no_need_to_escape() {
94        assert_eq!(unescape("hello 🍕!").unwrap(), Cow::Borrowed("hello 🍕!"));
95    }
96
97    #[test]
98    fn complex_unescape() {
99        // Test cases adapted from Apache Commons StringEscapeUtilsTest.java
100        assert_eq!(
101            unescape("a&lt;b&gt;c&quot;d&apos;e&amp;f;;").unwrap(),
102            "a<b>c\"d'e&f;;"
103        );
104        assert_eq!(unescape("&amp;lt;").unwrap(), "&lt;")
105    }
106
107    #[test]
108    fn newline_encoding() {
109        assert_eq!(unescape("&#10;").unwrap(), "\n");
110        assert_eq!(unescape("&#xD;").unwrap(), "\r");
111    }
112
113    #[test]
114    fn xml_eol_encoding() {
115        assert_eq!(unescape("&#xA; &#xA;").unwrap(), "\n \n");
116        assert_eq!(
117            unescape("a&#xD;&#xA; b&#xA; c&#xD;").unwrap(),
118            "a\r\n b\n c\r"
119        );
120        assert_eq!(
121            unescape("a&#xD;&#x85; b&#x85;").unwrap(),
122            "a\r\u{0085} b\u{0085}"
123        );
124        assert_eq!(
125            unescape("a&#xD;&#x2028; b&#x85; c&#x2028;").unwrap(),
126            "a\r\u{2028} b\u{0085} c\u{2028}"
127        );
128    }
129
130    #[test]
131    fn invalid_escapes() {
132        unescape("&lte;").expect_err("lte does not make a ≤");
133        unescape("&lt").expect_err("unterminated escape sequence");
134        unescape("&#Q1234;").expect_err("Q does not began a numeric sequence");
135        unescape("&#3.14;").expect_err("decimal escape");
136        unescape("&#xZZ").expect_err("Z is not hex");
137        unescape("here is a & but without an escape sequence...").expect_err("naked &");
138    }
139
140    use proptest::prelude::*;
141    proptest! {
142        #[test]
143        fn no_panics(s: String) {
144            let unescaped = unescape(&s);
145            // if the string needed to be escaped, we
146            if s.contains('&') {
147                assert!(
148                    matches!(unescaped, Ok(Cow::Owned(_)) | Err(_))
149                );
150            }
151        }
152    }
153}
aws_smithy_xml/unescape.rs

aws_smithy_xml/
unescape.rs
