Main Page | Class Hierarchy | Class List | File List | Class Members

xml::document Class Reference

The xml::document class is used to hold the XML tree and various bits of information about it. More...

#include <document.h>

List of all members.

Public Types

typedef std::size_t size_type
 size type


Public Member Functions

 document (void)
 Create a new XML document with the default settings.

 document (const char *root_name)
 Create a new XML document and set the name of the root element to the given text.

 document (const node &n)
 Create a new XML document and set the root node.

 document (const document &other)
 Copy construct a new XML document.

documentoperator= (const document &other)
 Copy another document object into this one using the assignment operator.

void swap (document &other)
 Swap one xml::document object for another.

 ~document (void)
 Clean up after an XML document object.

const nodeget_root_node (void) const
 Get a reference to the root node of this document.

nodeget_root_node (void)
 Get a reference to the root node of this document.

void set_root_node (const node &n)
 Set the root node to the given node.

const std::string & get_version (void) const
 Get the XML version for this document.

void set_version (const char *version)
 Set the XML version number for this document.

const std::string & get_encoding (void) const
 Get the XML encoding for this document.

void set_encoding (const char *encoding)
 Set the XML encoding string.

bool get_is_standalone (void) const
 Find out if the current document is a standalone document.

void set_is_standalone (bool sa)
 Set the standalone flag.

bool process_xinclude (void)
 Walk through the document and expand <xi:include> elements.

bool has_internal_subset (void) const
 Test to see if this document has an internal subset.

bool has_external_subset (void) const
 Test to see if this document has an external subset.

bool validate (void)
 Validate this document against the DTD that has been attached to it.

bool validate (const char *dtdname)
 Parse the given DTD and try to validate this document against it.

size_type size (void) const
 Returns the number of child nodes of this document.

node::iterator begin (void)
 Get an iterator to the first child node of this document.

node::const_iterator begin (void) const
 Get a const_iterator to the first child node of this document.

node::iterator end (void)
 Get an iterator that points one past the last child node for this document.

node::const_iterator end (void) const
 Get a const_iterator that points one past the last child node for this document.

void push_back (const node &child)
 Add a child xml::node to this document.

node::iterator insert (const node &n)
 Insert a new child node.

node::iterator insert (node::iterator position, const node &n)
 Insert a new child node.

node::iterator replace (node::iterator old_node, const node &new_node)
 Replace the node pointed to by the given iterator with another node.

node::iterator erase (node::iterator to_erase)
 Erase the node that is pointed to by the given iterator.

node::iterator erase (node::iterator first, node::iterator last)
 Erase all nodes in the given range, from frist to last.

void save_to_string (std::string &s) const
 Convert the XML document tree into XML text data and place it into the given string.

bool save_to_file (const char *filename, int compression_level=0) const
 Convert the XML document tree into XML text data and place it into the given filename.


Friends

std::ostream & operator<< (std::ostream &stream, const document &doc)
 Convert the XML document tree into XML text data and then insert it into the given stream.


Detailed Description

The xml::document class is used to hold the XML tree and various bits of information about it.


Member Typedef Documentation

typedef std::size_t xml::document::size_type
 

size type


Constructor & Destructor Documentation

xml::document::document void   ) 
 

Create a new XML document with the default settings.

The new document will contain a root node with a name of "blank".

Author:
Peter Jones

xml::document::document const char *  root_name  )  [explicit]
 

Create a new XML document and set the name of the root element to the given text.

Parameters:
root_name What to set the name of the root element to.
Author:
Peter Jones

xml::document::document const node n  )  [explicit]
 

Create a new XML document and set the root node.

Parameters:
n The node to use as the root node. n will be copied.
Author:
Peter Jones

xml::document::document const document other  ) 
 

Copy construct a new XML document.

The new document will be an exact copy of the original.

Parameters:
other The other document object to copy from.
Author:
Peter Jones

xml::document::~document void   ) 
 

Clean up after an XML document object.

Author:
Peter Jones


Member Function Documentation

node::const_iterator xml::document::begin void   )  const
 

Get a const_iterator to the first child node of this document.

If what you really wanted was the root node (the first element) you should use the get_root_node() member function instead.

Returns:
A xml::node::const_iterator that points to the first child node.

An end const_iterator if there are no children in this document.

Author:
Peter Jones

node::iterator xml::document::begin void   ) 
 

Get an iterator to the first child node of this document.

If what you really wanted was the root node (the first element) you should use the get_root_node() member function instead.

Returns:
A xml::node::iterator that points to the first child node.

An end iterator if there are no children in this document

Author:
Peter Jones

node::const_iterator xml::document::end void   )  const
 

Get a const_iterator that points one past the last child node for this document.

Returns:
An end xml::node::const_iterator.
Author:
Peter Jones

node::iterator xml::document::end void   ) 
 

Get an iterator that points one past the last child node for this document.

Returns:
An end xml::node::iterator.
Author:
Peter Jones

node::iterator xml::document::erase node::iterator  first,
node::iterator  last
 

Erase all nodes in the given range, from frist to last.

This will invalidate any iterators that point to the nodes to be erased, or any pointers or references to those nodes.

Do not remove the root node using this member function. The same rules that apply to push_back apply here. If you try to erase the root node, an exception will be thrown.

Parameters:
first The first node in the range to be removed.
last An iterator that points one past the last node to erase. Think xml::node::end().
Returns:
An iterator that points to the node after the last one being erased.
See also:
xml::document::push_back
Author:
Peter Jones

node::iterator xml::document::erase node::iterator  to_erase  ) 
 

Erase the node that is pointed to by the given iterator.

The node and all its children will be removed from this node. This will invalidate any iterators that point to the node to be erased, or any pointers or references to that node.

Do not remove the root node using this member function. The same rules that apply to push_back apply here. If you try to erase the root node, an exception will be thrown.

Parameters:
to_erase An iterator that points to the node to be erased.
Returns:
An iterator that points to the node after the one being erased.
See also:
xml::document::push_back
Author:
Peter Jones

const std::string& xml::document::get_encoding void   )  const
 

Get the XML encoding for this document.

The default encoding is ISO-8859-1.

Returns:
The encoding string.
Author:
Peter Jones

bool xml::document::get_is_standalone void   )  const
 

Find out if the current document is a standalone document.

For generated documents, this will be the default. For parsed documents this will be set based on the XML processing instruction.

Returns:
True if this document is standalone.

False if this document is not standalone.

Author:
Peter Jones

node& xml::document::get_root_node void   ) 
 

Get a reference to the root node of this document.

If no root node has been set, the returned node will be a blank node. You should take caution to use a reference so that you don't copy the whole node tree!

Returns:
A reference to the root node.
Author:
Peter Jones

const node& xml::document::get_root_node void   )  const
 

Get a reference to the root node of this document.

If no root node has been set, the returned node will be a blank node. You should take caution to use a reference so that you don't copy the whole node tree!

Returns:
A const reference to the root node.
Author:
Peter Jones

const std::string& xml::document::get_version void   )  const
 

Get the XML version for this document.

For generated documents, the version will be the default. For parsed documents, this will be the version from the XML processing instruction.

Returns:
The XML version string for this document.
Author:
Peter Jones

bool xml::document::has_external_subset void   )  const
 

Test to see if this document has an external subset.

That is, it references a DTD from an external source, such as a file or URL.

Returns:
True if this document has an external subset.

False otherwise.

Author:
Peter Jones

bool xml::document::has_internal_subset void   )  const
 

Test to see if this document has an internal subset.

That is, DTD data that is declared within the XML document itself.

Returns:
True if this document has an internal subset.

False otherwise.

Author:
Peter Jones

node::iterator xml::document::insert node::iterator  position,
const node n
 

Insert a new child node.

The new node will be inserted before the node pointed to by the given iterator.

The rules from the push_back member function apply here. Don't add a node of type element.

Parameters:
position An iterator that points to the location where the new node should be inserted (before it).
n The node to insert as a child of this document.
Returns:
An iterator that points to the newly inserted node.
See also:
xml::document::push_back
Author:
Peter Jones

node::iterator xml::document::insert const node n  ) 
 

Insert a new child node.

The new node will be inserted at the end of the child list. This is similar to the xml::node::push_back member function except that an iterator to the inserted node is returned.

The rules from the push_back member function apply here. Don't add a node of type element.

Parameters:
n The node to insert as a child of this document.
Returns:
An iterator that points to the newly inserted node.
See also:
xml::document::push_back
Author:
Peter Jones

document& xml::document::operator= const document other  ) 
 

Copy another document object into this one using the assignment operator.

This document object will be an exact copy of the other document after the assignement.

Parameters:
other The document to copy from.
Returns:
*this.
Author:
Peter Jones

bool xml::document::process_xinclude void   ) 
 

Walk through the document and expand <xi:include> elements.

For more information, please see the w3c recomendation for XInclude. http://www.w3.org/2001/XInclude.

The return value of this function may change to int after a bug has been fixed in libxml2 (xmlXIncludeDoProcess).

Returns:
False if there was an error with substitutions.

True if there were no errors (with or without substitutions).

Author:
Peter Jones

Daniel Evison

void xml::document::push_back const node child  ) 
 

Add a child xml::node to this document.

You should not add a element type node, since there can only be one root node. This member function is only useful for adding processing instructions, comments, etc.. If you do try to add a node of type element, an exception will be thrown.

Parameters:
child The child xml::node to add.
Author:
Peter Jones

node::iterator xml::document::replace node::iterator  old_node,
const node new_node
 

Replace the node pointed to by the given iterator with another node.

The old node will be removed, including all its children, and replaced with the new node. This will invalidate any iterators that point to the node to be replaced, or any pointers or references to that node.

Do not replace this root node with this member function. The same rules that apply to push_back apply here. If you try to replace a node of type element, an exception will be thrown.

Parameters:
old_node An iterator that points to the node that should be removed.
new_node The node to put in old_node's place.
Returns:
An iterator that points to the new node.
See also:
xml::document::push_back
Author:
Peter Jones

bool xml::document::save_to_file const char *  filename,
int  compression_level = 0
const
 

Convert the XML document tree into XML text data and place it into the given filename.

Parameters:
filename The name of the file to place the XML text data into.
compression_level 0 is no compression, 1-9 allowed, where 1 is for better speed, and 9 is for smaller size
Returns:
True if the data was saved successfully.

False otherwise.

Author:
Peter Jones

void xml::document::save_to_string std::string &  s  )  const
 

Convert the XML document tree into XML text data and place it into the given string.

Parameters:
s The string to place the XML text data.
Author:
Peter Jones

void xml::document::set_encoding const char *  encoding  ) 
 

Set the XML encoding string.

If you don't set this, it will default to ISO-8859-1.

Parameters:
encoding The XML encoding to use.
Author:
Peter Jones

Dmitriy Nikitinskiy

void xml::document::set_is_standalone bool  sa  ) 
 

Set the standalone flag.

This will show up in the XML output in the correct processing instruction.

Parameters:
sa What to set the standalone flag to.
Author:
Peter Jones

void xml::document::set_root_node const node n  ) 
 

Set the root node to the given node.

A full copy is made and stored in the document object.

Parameters:
n The new root node to use.
Author:
Peter Jones

void xml::document::set_version const char *  version  ) 
 

Set the XML version number for this document.

This version string will be used when generating the XML output.

Parameters:
version The version string to use, like "1.0".
Author:
Peter Jones

size_type xml::document::size void   )  const
 

Returns the number of child nodes of this document.

This will always be at least one, since all xmlwrapp documents must have a root node. This member function is useful to find out how many document children there are, including processing instructions, comments, etc.

Returns:
The number of children nodes that this document has.
Author:
Peter Jones

void xml::document::swap document other  ) 
 

Swap one xml::document object for another.

Parameters:
other The other document to swap
Author:
Peter Jones

bool xml::document::validate const char *  dtdname  ) 
 

Parse the given DTD and try to validate this document against it.

If the DTD is valid, and the document is valid, this member function will return true.

If it returns false, you may want to send the document through xmllint to get the actual error messages.

This member function will add the parsed DTD to this document as the external subset after the validation. If there is already an external DTD attached to this document it will be removed and deleted.

Parameters:
dtdname A filename or URL for the DTD to use.
Returns:
True if the document is valid.

False if there was a problem with the DTD or XML doc.

Author:
Peter Jones

bool xml::document::validate void   ) 
 

Validate this document against the DTD that has been attached to it.

This would happen at parse time if there was a !DOCTYPE definition. If the DTD is valid, and the document is valid, this member function will return true.

If it returns false, you may want to send the document through xmllint to get the actual error messages.

Returns:
True if the document is valid.

False if there was a problem with the DTD or XML doc.

Author:
Peter Jones


Friends And Related Function Documentation

std::ostream& operator<< std::ostream &  stream,
const document doc
[friend]
 

Convert the XML document tree into XML text data and then insert it into the given stream.

Parameters:
stream The stream to insert the XML into.
doc The document to insert.
Returns:
The stream from the first parameter.
Author:
Peter Jones


The documentation for this class was generated from the following file:
Generated on Tue Oct 19 12:26:03 2004 for xmlwrapp by doxygen 1.3.6