Rename functions for consistency

"unescape_and_decode" -> "decode_and_unescape"
"*_with_custom_entities" -> "*escape_with"

Changelog.md

@@ -111,7 +111,9 @@
 - [#412]: Change `read_to_end*` and `read_text_into` to accept `QName` instead of `AsRef<[u8]>`
 - [#415]: Changed custom entity unescaping API to accept closures rather than a mapping of entity to
   replacement text. This avoids needing to allocate a map and provides the user with more flexibility.
-
+- [#415]: Renamed many functions following the pattern `unescape_and_decode*` to `decode_and_unescape*`
+  to better communicate their function. Renamed functions following the pattern `*_with_custom_entities`
+  to `decode_and_unescape_with` to be more consistent across the API.
 - [#416]: `BytesStart::to_borrowed` renamed to `BytesStart::borrow`, the same method
   added to all events
 

examples/custom_entities.rs

@@ -47,7 +47,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
                         .attributes()
                         .map(|a| {
                             a.unwrap()
-                                .unescape_and_decode_value_with_custom_entities(&reader, |ent| {
+                                .decode_and_unescape_value_with(&reader, |ent| {
                                     custom_entities.get(ent).map(|s| s.as_str())
                                 })
                                 .unwrap()
@@ -60,7 +60,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
             Ok(Event::Text(ref e)) => {
                 println!(
                     "text value: {}",
-                    e.unescape_and_decode_with_custom_entities(&reader, |ent| custom_entities
+                    e.decode_and_unescape_with(&reader, |ent| custom_entities
                         .get(ent)
                         .map(|s| s.as_str()))
                         .unwrap()

src/events/attributes.rs

@@ -2,7 +2,7 @@
 //!
 //! Provides an iterator over attributes key/value pairs
 
-use crate::errors::{Error, Result as XmlResult};
+use crate::errors::Result as XmlResult;
 use crate::escape::{escape, unescape_with};
 use crate::name::QName;
 use crate::reader::{is_whitespace, Reader};
@@ -14,11 +14,11 @@ use std::{borrow::Cow, ops::Range};
 /// A struct representing a key/value XML attribute.
 ///
 /// Field `value` stores raw bytes, possibly containing escape-sequences. Most users will likely
-/// want to access the value using one of the [`unescaped_value`] and [`unescape_and_decode_value`]
+/// want to access the value using one of the [`unescaped_value`] and [`decode_and_unescape_value`]
 /// functions.
 ///
 /// [`unescaped_value`]: Self::unescaped_value
-/// [`unescape_and_decode_value`]: Self::unescape_and_decode_value
+/// [`decode_and_unescape_value`]: Self::decode_and_unescape_value
 #[derive(Clone, PartialEq)]
 pub struct Attribute<'a> {
     /// The key to uniquely define the attribute.
@@ -37,32 +37,33 @@ impl<'a> Attribute<'a> {
     ///
     /// This will allocate if the value contains any escape sequences.
     ///
-    /// See also [`unescaped_value_with_custom_entities()`](Self::unescaped_value_with_custom_entities)
+    /// See also [`unescaped_value_with()`](Self::unescaped_value_with)
     pub fn unescaped_value(&self) -> XmlResult<Cow<[u8]>> {
-        self.unescaped_value_with_custom_entities(|_| None)
+        self.unescaped_value_with(|_| None)
     }
 
     /// Returns the unescaped value, using custom entities.
     ///
     /// This is normally the value you are interested in. Escape sequences such as `&gt;` are
     /// replaced with their unescaped equivalents such as `>`.
-    /// Additional entities can be provided in `custom_entities`.
+    /// A fallback resolver for additional custom entities can be provided via
+    /// `resolve_entity`.
     ///
     /// This will allocate if the value contains any escape sequences.
     ///
     /// See also [`unescaped_value()`](Self::unescaped_value)
     ///
     /// # Pre-condition
     ///
-    /// The keys and values of `custom_entities`, if any, must be valid UTF-8.
-    pub fn unescaped_value_with_custom_entities<'s, 'entity>(
+    /// The implementation of `resolve_entity` is expected to operate over UTF-8 inputs.
+    pub fn unescaped_value_with<'s, 'entity>(
         &'s self,
         resolve_entity: impl Fn(&[u8]) -> Option<&'entity str>,
     ) -> XmlResult<Cow<'s, [u8]>> {
-        unescape_with(&*self.value, resolve_entity).map_err(Error::EscapeError)
+        Ok(unescape_with(&*self.value, resolve_entity)?)
     }
 
-    /// Decode then unescapes the value
+    /// Decodes then unescapes the value
     ///
     /// This allocates a `String` in all cases. For performance reasons it might be a better idea to
     /// instead use one of:
@@ -72,25 +73,25 @@ impl<'a> Attribute<'a> {
     ///
     /// [`unescaped_value()`]: Self::unescaped_value
     /// [`Reader::decoder().decode()`]: crate::reader::Decoder::decode
-    pub fn unescape_and_decode_value<B>(&self, reader: &Reader<B>) -> XmlResult<String> {
-        self.unescape_and_decode_value_with_custom_entities(reader, |_| None)
+    pub fn decode_and_unescape_value<B>(&self, reader: &Reader<B>) -> XmlResult<String> {
+        self.decode_and_unescape_value_with(reader, |_| None)
     }
 
-    /// Decode then unescapes the value with custom entities
+    /// Decodes then unescapes the value with custom entities
     ///
     /// This allocates a `String` in all cases. For performance reasons it might be a better idea to
     /// instead use one of:
     ///
     /// * [`Reader::decoder().decode()`], as it only allocates when the decoding can't be performed otherwise.
-    /// * [`unescaped_value_with_custom_entities()`], as it doesn't allocate when no escape sequences are used.
+    /// * [`unescaped_value_with()`], as it doesn't allocate when no escape sequences are used.
     ///
-    /// [`unescaped_value_with_custom_entities()`]: Self::unescaped_value_with_custom_entities
+    /// [`unescaped_value_with()`]: Self::unescaped_value_with
     /// [`Reader::decoder().decode()`]: crate::reader::Decoder::decode
     ///
     /// # Pre-condition
     ///
-    /// The keys and values of `custom_entities`, if any, must be valid UTF-8.
-    pub fn unescape_and_decode_value_with_custom_entities<'entity, B>(
+    /// The implementation of `resolve_entity` is expected to operate over UTF-8 inputs.
+    pub fn decode_and_unescape_value_with<'entity, B>(
         &self,
         reader: &Reader<B>,
         resolve_entity: impl Fn(&[u8]) -> Option<&'entity str>,

src/events/mod.rs

@@ -752,50 +752,50 @@ impl<'a> BytesText<'a> {
     /// Searches for '&' into content and try to escape the coded character if possible
     /// returns Malformed error with index within element if '&' is not followed by ';'
     ///
-    /// See also [`unescaped_with_custom_entities()`](Self::unescaped_with_custom_entities)
+    /// See also [`unescaped_with()`](Self::unescaped_with)
     pub fn unescaped(&self) -> Result<Cow<[u8]>> {
-        self.unescaped_with_custom_entities(|_| None)
+        self.unescaped_with(|_| None)
     }
 
     /// gets escaped content with custom entities
     ///
     /// Searches for '&' into content and try to escape the coded character if possible
     /// returns Malformed error with index within element if '&' is not followed by ';'
-    /// Additional entities can be provided in `custom_entities`.
+    /// A fallback resolver for additional custom entities can be provided via `resolve_entity`.
     ///
     /// # Pre-condition
     ///
     /// The implementation of `resolve_entity` is expected to operate over UTF-8 inputs.
     ///
     /// See also [`unescaped()`](Self::unescaped)
-    pub fn unescaped_with_custom_entities<'s, 'entity>(
+    pub fn unescaped_with<'s, 'entity>(
         &'s self,
         resolve_entity: impl Fn(&[u8]) -> Option<&'entity str>,
     ) -> Result<Cow<'s, [u8]>> {
-        unescape_with(self, resolve_entity).map_err(Error::EscapeError)
+        Ok(unescape_with(self, resolve_entity)?)
     }
 
     /// helper method to unescape then decode self using the reader encoding
     ///
     /// for performance reasons (could avoid allocating a `String`),
     /// it might be wiser to manually use
-    /// 1. BytesText::unescaped()
-    /// 2. Reader::decode(...)
-    pub fn unescape_and_decode<B>(&self, reader: &Reader<B>) -> Result<String> {
-        self.unescape_and_decode_with_custom_entities(reader, |_| None)
+    /// 1. Reader::decode(...)
+    /// 2. BytesText::unescaped()
+    pub fn decode_and_unescape<B>(&self, reader: &Reader<B>) -> Result<String> {
+        self.decode_and_unescape_with(reader, |_| None)
     }
 
     /// helper method to unescape then decode self using the reader encoding with custom entities
     ///
     /// for performance reasons (could avoid allocating a `String`),
     /// it might be wiser to manually use
-    /// 1. BytesText::unescaped()
-    /// 2. Reader::decode(...)
+    /// 1. Reader::decode(...)
+    /// 2. BytesText::unescaped()
     ///
     /// # Pre-condition
     ///
     /// The implementation of `resolve_entity` is expected to operate over UTF-8 inputs.
-    pub fn unescape_and_decode_with_custom_entities<'entity, B>(
+    pub fn decode_and_unescape_with<'entity, B>(
         &self,
         reader: &Reader<B>,
         resolve_entity: impl Fn(&[u8]) -> Option<&'entity str>,

src/lib.rs

@@ -59,7 +59,7 @@
 //!             }
 //!         },
 //!         // unescape and decode the text event using the reader encoding
-//!         Ok(Event::Text(e)) => txt.push(e.unescape_and_decode(&reader).unwrap()),
+//!         Ok(Event::Text(e)) => txt.push(e.decode_and_unescape(&reader).unwrap()),
 //!         Ok(Event::Eof) => break, // exits the loop when reaching end of file
 //!         Err(e) => panic!("Error at position {}: {:?}", reader.buffer_position(), e),
 //!         _ => (), // There are several other `Event`s we do not consider here

src/reader.rs

@@ -135,7 +135,7 @@ impl EncodingRef {
 ///                 _ => (),
 ///             }
 ///         },
-///         Ok(Event::Text(e)) => txt.push(e.unescape_and_decode(&reader).unwrap()),
+///         Ok(Event::Text(e)) => txt.push(e.decode_and_unescape(&reader).unwrap()),
 ///         Err(e) => panic!("Error at position {}: {:?}", reader.buffer_position(), e),
 ///         Ok(Event::Eof) => break,
 ///         _ => (),
@@ -496,7 +496,7 @@ impl<R: BufRead> Reader<R> {
     /// loop {
     ///     match reader.read_event_into(&mut buf) {
     ///         Ok(Event::Start(ref e)) => count += 1,
-    ///         Ok(Event::Text(e)) => txt.push(e.unescape_and_decode(&reader).expect("Error!")),
+    ///         Ok(Event::Text(e)) => txt.push(e.decode_and_unescape(&reader).expect("Error!")),
     ///         Err(e) => panic!("Error at position {}: {:?}", reader.buffer_position(), e),
     ///         Ok(Event::Eof) => break,
     ///         _ => (),
@@ -549,7 +549,7 @@ impl<R: BufRead> Reader<R> {
     ///             panic!("Undeclared namespace prefix {:?}", String::from_utf8(p))
     ///         }
     ///         Ok((_, Event::Text(e))) => {
-    ///             txt.push(e.unescape_and_decode(&reader).expect("Error!"))
+    ///             txt.push(e.decode_and_unescape(&reader).expect("Error!"))
     ///         },
     ///         Err(e) => panic!("Error at position {}: {:?}", reader.buffer_position(), e),
     ///         Ok((_, Event::Eof)) => break,
@@ -750,7 +750,7 @@ impl<R: BufRead> Reader<R> {
         let s = match self.read_event_into(buf) {
             Err(e) => return Err(e),
 
-            Ok(Event::Text(e)) => e.unescape_and_decode(self),
+            Ok(Event::Text(e)) => e.decode_and_unescape(self),
             Ok(Event::End(e)) if e.name() == end => return Ok("".to_string()),
             Ok(Event::Eof) => return Err(Error::UnexpectedEof("Text".to_string())),
             _ => return Err(Error::TextNotFound),

tests/test.rs

@@ -104,7 +104,7 @@ fn test_koi8_r_encoding() {
     loop {
         match r.read_event_into(&mut buf) {
             Ok(Text(e)) => {
-                e.unescape_and_decode(&r).unwrap();
+                e.decode_and_unescape(&r).unwrap();
             }
             Ok(Eof) => break,
             _ => (),

tests/unit_tests.rs

@@ -653,7 +653,7 @@ fn test_read_write_roundtrip_escape_text() -> Result<()> {
         match reader.read_event_into(&mut buf)? {
             Eof => break,
             Text(e) => {
-                let t = e.unescape_and_decode(&reader).unwrap();
+                let t = e.decode_and_unescape(&reader).unwrap();
                 assert!(writer
                     .write_event(Text(BytesText::from_plain_str(&t)))
                     .is_ok());