Struct Attribute 

pub struct Attribute<'a> {
    pub key: QName<'a>,
    pub value: Cow<'a, [u8]>,
}

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 normalized_value and decoded_and_normalized_value functions.

Fields

key: QName<'a>

The key to uniquely define the attribute.

If Attributes::with_checks is turned off, the key might not be unique.

value: Cow<'a, [u8]>

The raw value of the attribute.

Implementations

impl<'a> Attribute<'a>

pub fn normalized_value(&self, version: XmlVersion) -> XmlResult<Cow<'a, str>>

Returns the attribute value normalized as per the XML specification (or for 1.0).

The document must be UTF-8 encoded, or pre-processed using DecodingReader.

The characters \t, \r, \n are replaced with whitespace characters (0x20).

The following escape sequences are replaced with their unescaped equivalents:

Escape Sequence	Replacement
&lt;	<
&gt;	>
&amp;	&
&apos;	'
&quot;	"

This will allocate unless the raw attribute value does not require normalization.

Note, although you may use this library to parse HTML, you cannot use this method to get HTML content, because its returns normalized value: the following sequences are translated into a single space (U+0020) character:

• \r\n
• \r\x85 (only XML 1.1)
• \r
• \n
• \t
• \x85 (only XML 1.1)
• \x2028 (only XML 1.1)

The text in HTML normally is not normalized in any way; normalization is performed only in limited contexts and only for \r\n and \r.

See also normalized_value_with().

NOTE: If you are using this in a context where the input is not controlled, it is preferred to wrap the input stream in DecodingReader or to use decoded_and_normalized_value() instead.

pub fn normalized_value_with<'entity>( &self, version: XmlVersion, depth: usize, resolve_entity: impl FnMut(&str) -> Option<&'entity str>, ) -> XmlResult<Cow<'a, str>>

Returns the attribute value normalized as per the XML specification (or for 1.0), using a custom entity resolver.

The document must be UTF-8 encoded, or pre-processed using DecodingReader.

Do not use this method with HTML attributes.

The characters \t, \r, \n are replaced with whitespace characters (0x20).

A function for resolving entities can be provided as resolve_entity. This method does not resolve any predefined entities, but you can use resolve_predefined_entity in your function.

This will allocate unless the raw attribute value does not require normalization.

Note, although you may use this library to parse HTML, you cannot use this method to get HTML content, because its returns normalized value: the following sequences are translated into a single space (U+0020) character:

• \r\n
• \r\x85 (only XML 1.1)
• \r
• \n
• \t
• \x85 (only XML 1.1)
• \x2028 (only XML 1.1)

The text in HTML normally is not normalized in any way; normalization is performed only in limited contexts and only for \r\n and \r.

See also normalized_value().

NOTE: If you are using this in a context where the input is not controlled, it is preferred to wrap the input stream in DecodingReader or to use decoded_and_normalized_value_with() instead.

Parameters

• depth: maximum number of nested entities that can be expanded. If expansion chain will be more that this value, the function will return EscapeError::TooManyNestedEntities
• resolve_entity: a function to resolve entity. This function could be called multiple times on the same input and can return different values in each case for the same input, although it is not recommended

pub fn decoded_and_normalized_value( &self, version: XmlVersion, decoder: Decoder, ) -> XmlResult<Cow<'a, str>>

Decodes using a provided reader and returns the attribute value normalized as per the XML specification (or for 1.0).

Do not use this method with HTML attributes.

The characters \t, \r, \n are replaced with whitespace characters (0x20).

The following escape sequences are replaced with their unescaped equivalents:

Escape Sequence	Replacement
&lt;	<
&gt;	>
&amp;	&
&apos;	'
&quot;	"

This will allocate unless the raw attribute value does not require normalization.

Note, although you may use this library to parse HTML, you cannot use this method to get HTML content, because its returns normalized value: the following sequences are translated into a single space (U+0020) character:

• \r\n
• \r\x85 (only XML 1.1)
• \r
• \n
• \t
• \x85 (only XML 1.1)
• \x2028 (only XML 1.1)

The text in HTML normally is not normalized in any way; normalization is performed only in limited contexts and only for \r\n and \r.

See also decoded_and_normalized_value_with()

pub fn decoded_and_normalized_value_with<'entity>( &self, version: XmlVersion, decoder: Decoder, depth: usize, resolve_entity: impl FnMut(&str) -> Option<&'entity str>, ) -> XmlResult<Cow<'a, str>>

Decodes using a provided reader and returns the attribute value normalized as per the XML specification (or for 1.0), using a custom entity resolver.

Do not use this method with HTML attributes.

The characters \t, \r, \n are replaced with whitespace characters (0x20).

A function for resolving entities can be provided as resolve_entity. This method does not resolve any predefined entities, but you can use resolve_predefined_entity in your function.

This will allocate unless the raw attribute value does not require normalization.

Note, although you may use this library to parse HTML, you cannot use this method to get HTML content, because its returns normalized value: the following sequences are translated into a single space (U+0020) character:

• \r\n
• \r\x85 (only XML 1.1)
• \r
• \n
• \t
• \x85 (only XML 1.1)
• \x2028 (only XML 1.1)

The text in HTML normally is not normalized in any way; normalization is performed only in limited contexts and only for \r\n and \r.

See also decoded_and_normalized_value()

Parameters

• depth: maximum number of nested entities that can be expanded. If expansion chain will be more that this value, the function will return EscapeError::TooManyNestedEntities
• resolve_entity: a function to resolve entity. This function could be called multiple times on the same input and can return different values in each case for the same input, although it is not recommended

pub fn unescape_value(&self) -> XmlResult<Cow<'a, str>>

👎Deprecated:

use Self::normalized_value()

Available on non-crate feature encoding only.

Returns the unescaped value.

This is normally the value you are interested in. Escape sequences such as > are replaced with their unescaped equivalents such as >.

This will allocate if the value contains any escape sequences.

See also unescape_value_with()

NOTE: Because this method is available only if encoding feature is not enabled, should only be used by applications. Libs should use decoded_and_normalized_value() instead, because if lib will be used in a project which depends on quick_xml with encoding feature enabled, the lib will fail to compile due to feature unification.

pub fn unescape_value_with<'entity>( &self, resolve_entity: impl FnMut(&str) -> Option<&'entity str>, ) -> XmlResult<Cow<'a, str>>

👎Deprecated:

use Self::normalized_value_with()

Available on non-crate feature encoding only.

Decodes using UTF-8 then unescapes the value, using custom entities.

This is normally the value you are interested in. Escape sequences such as > are replaced with their unescaped equivalents such as >. 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 unescape_value()

NOTE: Because this method is available only if encoding feature is not enabled, should only be used by applications. Libs should use decoded_and_normalized_value_with() instead, because if lib will be used in a project which depends on quick_xml with encoding feature enabled, the lib will fail to compile due to feature unification.

pub fn decode_and_unescape_value( &self, decoder: Decoder, ) -> XmlResult<Cow<'a, str>>

👎Deprecated:

use Self::decoded_and_normalized_value()

Decodes then unescapes the value.

This will allocate if the value contains any escape sequences or in non-UTF-8 encoding.

pub fn decode_and_unescape_value_with<'entity>( &self, decoder: Decoder, resolve_entity: impl FnMut(&str) -> Option<&'entity str>, ) -> XmlResult<Cow<'a, str>>

👎Deprecated:

use Self::decoded_and_normalized_value_with()

Decodes then unescapes the value with custom entities.

This will allocate if the value contains any escape sequences or in non-UTF-8 encoding.

pub fn as_bool(&self) -> Option<bool>

If attribute value represents valid boolean values, returns Some, otherwise returns None.

The valid boolean representations are only "true", "false", "1", and "0".

Examples

use quick_xml::events::attributes::Attribute;

let attr = Attribute::from(("attr", "false"));
assert_eq!(attr.as_bool(), Some(false));

let attr = Attribute::from(("attr", "0"));
assert_eq!(attr.as_bool(), Some(false));

let attr = Attribute::from(("attr", "true"));
assert_eq!(attr.as_bool(), Some(true));

let attr = Attribute::from(("attr", "1"));
assert_eq!(attr.as_bool(), Some(true));

let attr = Attribute::from(("attr", "not bool"));
assert_eq!(attr.as_bool(), None);

Trait Implementations

impl<'a> Clone for Attribute<'a>

fn clone(&self) -> Attribute<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for Attribute<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> From<(&'a [u8], &'a [u8])> for Attribute<'a>

fn from(val: (&'a [u8], &'a [u8])) -> Attribute<'a>

Creates new attribute from raw bytes. Does not apply any transformation to both key and value.

Examples

use quick_xml::events::attributes::Attribute;

let features = Attribute::from(("features".as_bytes(), "Bells & whistles".as_bytes()));
assert_eq!(features.value, "Bells & whistles".as_bytes());

impl<'a> From<(&'a str, &'a str)> for Attribute<'a>

fn from(val: (&'a str, &'a str)) -> Attribute<'a>

Creates new attribute from text representation. Key is stored as-is, but the value will be escaped.

Examples

use quick_xml::events::attributes::Attribute;

let features = Attribute::from(("features", "Bells & whistles"));
assert_eq!(features.value, "Bells & whistles".as_bytes());

impl<'a> From<(&'a str, Cow<'a, str>)> for Attribute<'a>

fn from(val: (&'a str, Cow<'a, str>)) -> Attribute<'a>

Creates new attribute from text representation. Key is stored as-is, but the value will be escaped.

Examples

use pretty_assertions::assert_eq;
use quick_xml::events::attributes::Attribute;

let features = Attribute::from(("features", Cow::Borrowed("Bells & whistles")));
assert_eq!(features.value, "Bells & whistles".as_bytes());

impl<'a> From<Attr<&'a [u8]>> for Attribute<'a>

fn from(attr: Attr<&'a [u8]>) -> Self

Converts to this type from the input type.

impl<'a> PartialEq for Attribute<'a>

fn eq(&self, other: &Attribute<'a>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> Eq for Attribute<'a>

impl<'a> StructuralPartialEq for Attribute<'a>