Struct Document

pub struct Document { /* private fields */ }

Represents a XML document or a document fragment.

To build a document from scratch, use Document::new.

To read and modify an existing document, use parse_* methods.

To write the document, use write_* methods.

Examples

use xml_doc::Document;

let mut doc = Document::parse_str(r#"<?xml version="1.0" encoding="UTF-8"?>
<package>
    <metadata>
        <author>Lewis Carol</author>
    </metadata>
</package>
"#).unwrap();
let author_elem = doc
  .root_element()
  .unwrap()
  .find(&doc, "metadata")
  .unwrap()
  .find(&doc, "author")
  .unwrap();
author_elem.set_text_content(&mut doc, "Lewis Carroll");
let xml = doc.write_str();

Implementations

impl Document

pub fn new() -> Document

Create a blank new xml document.

pub fn container(&self) -> Element

Get ‘container’ element of Document.

The document uses an invisible ‘container’ element which it uses to manage its root nodes.

Its parent is None, and trying to change its parent will return Error::ContainerCannotMove.

For the container element, only its children is relevant. Other attributes are not used.

pub fn is_empty(&self) -> bool

Returns true if document doesn’t have any nodes. Returns false if you added a node or parsed an xml.

You can only call parse_*() if document is empty.

pub fn root_nodes(&self) -> &Vec<Node>

Get root nodes of document.

pub fn root_element(&self) -> Option<Element>

Get first root node that is an element.

pub fn push_root_node(&mut self, node: Node) -> Result<()>

Push a node to end of root nodes. If doc has no Element, pushing a Node::Element is equivalent to setting it as root element.

impl Document

 

Parsing

Below are methods for parsing xml. Parsing from string, file, and reader is supported.

Call parse_*_with_opts with custom ReadOptions to change parser behaviour. Otherwise, ReadOptions::default() is used.

Errors

• Error::CannotDecode: Could not decode XML. XML declaration may have invalid encoding value.
• Error::MalformedXML: Could not read XML.
• Error::Io: IO Error

pub fn parse_str(str: &str) -> Result<Document>

pub fn parse_str_with_opts(str: &str, opts: ReadOptions) -> Result<Document>

pub fn parse_file<P: AsRef<Path>>(path: P) -> Result<Document>

pub fn parse_file_with_opts<P: AsRef<Path>>( path: P, opts: ReadOptions, ) -> Result<Document>

pub fn parse_reader<R: Read>(reader: R) -> Result<Document>

pub fn parse_reader_with_opts<R: Read>( reader: R, opts: ReadOptions, ) -> Result<Document>

impl Document

 

Writing

Below are methods for writing xml. The XML will be written in UTF-8.

pub fn write_file<P: AsRef<Path>>(&self, path: P) -> Result<()>

pub fn write_file_with_opts<P: AsRef<Path>>( &self, path: P, opts: WriteOptions, ) -> Result<()>

pub fn write_str(&self) -> Result<String>

pub fn write_str_with_opts(&self, opts: WriteOptions) -> Result<String>

pub fn write(&self, writer: &mut impl Write) -> Result<()>

pub fn write_with_opts( &self, writer: &mut impl Write, opts: WriteOptions, ) -> Result<()>

Trait Implementations

impl Debug for Document

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

Formats the value using the given formatter.

impl FromStr for Document

type Err = Error

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Document>

Parses a string s to return a value of this type.