Struct Attribute

Source

pub struct Attribute<'a> {
    pub key: QName<'a>,
    pub value: Cow<'a, str>,
}

Expand description

A struct representing a key/value XML attribute.

Field value stores the raw attribute value, possibly containing escape-sequences. Most users will likely want to access the value using the normalized_value method.

§Lifetime

'a is a lifetime of the owning event from which this attribute is derived.

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, str>

The raw value of the attribute.

Implementations§

Source §

impl<'a> Attribute<'a>

Source

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 characters \t, \r, \n are replaced with whitespace characters (0x20).

The following escape sequences are replaced with their unescaped equivalents:

Escape Sequence	Replacement
`<`	`<`
`>`	`>`
`&`	`&`
`'`	`'`
`"`	`"`

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.

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.

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.

§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

Source

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

👎Deprecated:

decoding is no longer needed, use normalized_value() instead

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

§Deprecation

Attribute values are now always stored as valid UTF-8 strings, so decoding is no longer needed. Use normalized_value() instead.

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
`<`	`<`
`>`	`>`
`&`	`&`
`'`	`'`
`"`	`"`

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.

Source

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>>

👎Deprecated:

decoding is no longer needed, use normalized_value_with() instead

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.

§Deprecation

Attribute values are now always stored as valid UTF-8 strings, so decoding is no longer needed. Use normalized_value_with() instead.

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.

§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

Source

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.

§Deprecation

Use normalized_value() instead.

Escape sequences such as > are replaced with their unescaped equivalents such as >.

This will allocate if the value contains any escape sequences.

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.

§Deprecation

Use normalized_value_with() instead.

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.

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

👎Deprecated:

decoding is no longer needed, use Self::normalized_value() instead

Decodes then unescapes the value.

§Deprecation

Attribute values are now always stored as valid UTF-8 strings, so decoding is no longer needed. Use normalized_value() instead.

This will allocate if the value contains any escape sequences.

Source

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

👎Deprecated:

decoding is no longer needed, use Self::normalized_value_with() instead

Decodes then unescapes the value with custom entities.

§Deprecation

Attribute values are now always stored as valid UTF-8 strings, so decoding is no longer needed. Use normalized_value_with() instead.

This will allocate if the value contains any escape sequences.

Source

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§

Source §

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

Source §

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

Returns a duplicate of the value. Read more

1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more

Source §

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

Source §

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

Formats the value using the given formatter. Read more

Source §

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

Source §

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

Source §

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.as_ref(), "Bells &amp; whistles");

Source §

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

Source §

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.as_ref(), "Bells &amp; whistles");

Source §