Struct quick_xml::writer::Writer

source ·
pub struct Writer<W> { /* private fields */ }
Expand description

XML writer. Writes XML Events to a std::io::Write implementor.

§Examples

use quick_xml::events::{Event, BytesEnd, BytesStart};
use quick_xml::reader::Reader;
use quick_xml::writer::Writer;
use std::io::Cursor;

let xml = r#"<this_tag k1="v1" k2="v2"><child>text</child></this_tag>"#;
let mut reader = Reader::from_str(xml);
let mut writer = Writer::new(Cursor::new(Vec::new()));
loop {
    match reader.read_event() {
        Ok(Event::Start(e)) if e.name().as_ref() == b"this_tag" => {

            // crates a new element ... alternatively we could reuse `e` by calling
            // `e.into_owned()`
            let mut elem = BytesStart::new("my_elem");

            // collect existing attributes
            elem.extend_attributes(e.attributes().map(|attr| attr.unwrap()));

            // copy existing attributes, adds a new my-key="some value" attribute
            elem.push_attribute(("my-key", "some value"));

            // writes the event to the writer
            assert!(writer.write_event(Event::Start(elem)).is_ok());
        },
        Ok(Event::End(e)) if e.name().as_ref() == b"this_tag" => {
            assert!(writer.write_event(Event::End(BytesEnd::new("my_elem"))).is_ok());
        },
        Ok(Event::Eof) => break,
        // we can either move or borrow the event to write, depending on your use-case
        Ok(e) => assert!(writer.write_event(e.borrow()).is_ok()),
        Err(e) => panic!("Error at position {}: {:?}", reader.error_position(), e),
    }
}

let result = writer.into_inner().into_inner();
let expected = r#"<my_elem k1="v1" k2="v2" my-key="some value"><child>text</child></my_elem>"#;
assert_eq!(result, expected.as_bytes());

Implementations§

source§

impl<W: AsyncWrite + Unpin> Writer<W>

source

pub async fn write_event_async<'a, E: Into<Event<'a>>>( &mut self, event: E, ) -> Result<()>

Available on crate feature async-tokio only.

Writes the given event to the underlying writer. Async version of Writer::write_event.

source

pub async fn write_indent_async(&mut self) -> Result<()>

Available on crate feature async-tokio only.

Manually write a newline and indentation at the proper level. Async version of Writer::write_indent.

This method will do nothing if Writer was not constructed with Writer::new_with_indent.

source§

impl<W> Writer<W>

source

pub const fn new(inner: W) -> Writer<W>

Creates a Writer from a generic writer.

source

pub fn new_with_indent( inner: W, indent_char: u8, indent_size: usize, ) -> Writer<W>

Creates a Writer with configured indents from a generic writer.

source

pub fn into_inner(self) -> W

Consumes this Writer, returning the underlying writer.

source

pub fn get_mut(&mut self) -> &mut W

Get a mutable reference to the underlying writer.

source

pub const fn get_ref(&self) -> &W

Get a reference to the underlying writer.

source

pub fn create_element<'a, N>(&'a mut self, name: N) -> ElementWriter<'a, W>
where N: Into<Cow<'a, str>>,

Provides a simple, high-level API for writing XML elements.

Returns an ElementWriter that simplifies setting attributes and writing content inside the element.

§Example
use quick_xml::events::{BytesStart, BytesText, Event};
use quick_xml::writer::Writer;
use quick_xml::Error;
use std::io::Cursor;

let mut writer = Writer::new(Cursor::new(Vec::new()));

// writes <tag attr1="value1"/>
writer.create_element("tag")
    .with_attribute(("attr1", "value1"))  // chain `with_attribute()` calls to add many attributes
    .write_empty()?;

// writes <tag attr1="value1" attr2="value2">with some text inside</tag>
writer.create_element("tag")
    .with_attributes(vec![("attr1", "value1"), ("attr2", "value2")].into_iter())  // or add attributes from an iterator
    .write_text_content(BytesText::new("with some text inside"))?;

// writes <tag><fruit quantity="0">apple</fruit><fruit quantity="1">orange</fruit></tag>
writer.create_element("tag")
    // We need to provide error type, because it is not named somewhere explicitly
    .write_inner_content::<_, Error>(|writer| {
        let fruits = ["apple", "orange"];
        for (quant, item) in fruits.iter().enumerate() {
            writer
                .create_element("fruit")
                .with_attribute(("quantity", quant.to_string().as_str()))
                .write_text_content(BytesText::new(item))?;
        }
        Ok(())
    })?;
source§

impl<W: Write> Writer<W>

source

pub fn write_bom(&mut self) -> Result<()>

Write a Byte-Order-Mark character to the document.

§Example
use quick_xml::events::{BytesStart, BytesText, Event};
use quick_xml::writer::Writer;
use quick_xml::Error;
use std::io::Cursor;

let mut buffer = Vec::new();
let mut writer = Writer::new_with_indent(&mut buffer, b' ', 4);

writer.write_bom()?;
writer
    .create_element("empty")
    .with_attribute(("attr1", "value1"))
    .write_empty()
    .expect("failure");

assert_eq!(
    std::str::from_utf8(&buffer).unwrap(),
    "\u{FEFF}<empty attr1=\"value1\"/>"
);
source

pub fn write_event<'a, E: Into<Event<'a>>>(&mut self, event: E) -> Result<()>

Writes the given event to the underlying writer.

source

pub fn write_indent(&mut self) -> Result<()>

Manually write a newline and indentation at the proper level.

This can be used when the heuristic to line break and indent after any Event apart from Text fails such as when a Start occurs directly after Text.

This method will do nothing if Writer was not constructed with new_with_indent.

source

pub fn write_serializable<T: Serialize>( &mut self, tag_name: &str, content: &T, ) -> Result<(), DeError>

Available on crate feature serialize only.

Write an arbitrary serializable type

Note: If you are attempting to write XML in a non-UTF-8 encoding, this may not be safe to use. Rust basic types assume UTF-8 encodings.

#[derive(Debug, PartialEq, Serialize)]
struct MyData {
    question: String,
    answer: u32,
}

let data = MyData {
    question: "The Ultimate Question of Life, the Universe, and Everything".into(),
    answer: 42,
};

let mut buffer = Vec::new();
let mut writer = Writer::new_with_indent(&mut buffer, b' ', 4);

let start = BytesStart::new("root");
let end = start.to_end();

writer.write_event(Event::Start(start.clone()))?;
writer.write_serializable("my_data", &data)?;
writer.write_event(Event::End(end))?;

assert_eq!(
    std::str::from_utf8(&buffer)?,
    r#"<root>
    <my_data>
        <question>The Ultimate Question of Life, the Universe, and Everything</question>
        <answer>42</answer>
    </my_data>
</root>"#
);

Trait Implementations§

source§

impl<W: Clone> Clone for Writer<W>

source§

fn clone(&self) -> Writer<W>

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more

Auto Trait Implementations§

§

impl<W> Freeze for Writer<W>
where W: Freeze,

§

impl<W> RefUnwindSafe for Writer<W>
where W: RefUnwindSafe,

§

impl<W> Send for Writer<W>
where W: Send,

§

impl<W> Sync for Writer<W>
where W: Sync,

§

impl<W> Unpin for Writer<W>
where W: Unpin,

§

impl<W> UnwindSafe for Writer<W>
where W: UnwindSafe,

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

source§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.