libxml++ 5.0.1

- Main Page
- Related Pages
- Namespaces
- Classes

- Class List
- Class Index
- Class Hierarchy
- Class Members

Classes | Public Member Functions | Protected Member Functions | List of all members
xmlpp::Document Class Reference

Represents an XML document in the DOM model. More...

`#include <libxml++/document.h>`

Inheritance diagram for xmlpp::Document:
[legend]

## Public Member Functions
LIBXMLPP_API | Document (const ustring& version="1.0")
| Create a new document. More...
LIBXMLPP_API | Document (_xmlDoc* doc)
| Create a new C++ wrapper for an xmlDoc struct. More...
LIBXMLPP_API | ~Document () override
LIBXMLPP_API CommentNode* | add_comment (const ustring& content)
| Append a new comment node. More...
LIBXMLPP_API ProcessingInstructionNode* | add_processing_instruction (const ustring& name, const ustring& content)
| Append a new processing instruction node. More...
LIBXMLPP_API _xmlDoc* | cobj () noexcept
| Access the underlying libxml implementation. More...
LIBXMLPP_API const _xmlDoc* | cobj () const noexcept
| Access the underlying libxml implementation. More...
LIBXMLPP_API Element* | create_root_node (const ustring& name, const ustring& ns_uri=ustring(), const ustring& ns_prefix=ustring())
| Create the root element node. More...
LIBXMLPP_API Element* | create_root_node_by_import (const Node* node, bool recursive=true)
| Create a root element node by importing the node from another document, without affecting the source node. More...
LIBXMLPP_API ustring | get_encoding () const
LIBXMLPP_API Dtd* | get_internal_subset () const
| Get the internal subset of this document. More...
LIBXMLPP_API Element* | get_root_node ()
| Return the root node. More...
LIBXMLPP_API const Element* | get_root_node () const
| Return the root node. More...
LIBXMLPP_API int | process_xinclude (bool generate_xinclude_nodes=true, bool fixup_base_uris=true)
| Perform XInclude substitution on the XML document. More...
virtual LIBXMLPP_API void | set_entity_declaration (const ustring& name, XmlEntityType type, const ustring& publicId, const ustring& systemId, const ustring& content)
| Add an Entity declaration to the document. More...
LIBXMLPP_API void | set_internal_subset (const ustring& name, const ustring& external_id, const ustring& system_id)
| Create the internal subset of this document. More...
LIBXMLPP_API void | write_to_file (const std::string& filename, const ustring& encoding=ustring())
| Write the document to a file. More...
LIBXMLPP_API void | write_to_file_formatted (const std::string& filename, const ustring& encoding=ustring())
| Write the document to a file. More...
LIBXMLPP_API void | write_to_stream (std::ostream& output, const ustring& encoding=ustring())
| Write the document to a std::ostream. More...
LIBXMLPP_API void | write_to_stream_formatted (std::ostream& output, const ustring& encoding=ustring())
| Write the document to a std::ostream. More...
LIBXMLPP_API ustring | write_to_string (const ustring& encoding=ustring())
| Write the document to the memory. More...
LIBXMLPP_API ustring | write_to_string_formatted (const ustring& encoding=ustring())
| Write the document to the memory. More...

## Protected Member Functions
LIBXMLPP_API _xmlEntity* | get_entity (const ustring& name)
| Retrieve an Entity. More...
Protected Member Functions inherited from xmlpp::NonCopyable
| NonCopyable () noexcept
| NonCopyable (const NonCopyable&)=delete
| NonCopyable (NonCopyable&&)=delete
virtual | ~NonCopyable ()
NonCopyable& | operator= (const NonCopyable&)=delete
NonCopyable& | operator= (NonCopyable&&)=delete

## Detailed Description

Represents an XML document in the DOM model.

## Constructor & Destructor Documentation

LIBXMLPP_API xmlpp::Document::Document | ( | const ustring& | version = `"1.0"` | ) |
| explicit

Create a new document.

Parameters

  version | XML version.

Exceptions

  xmlpp::internal_error | If memory allocation fails.

LIBXMLPP_API xmlpp::Document::Document | ( | _xmlDoc * | doc | ) |
| explicit

Create a new C++ wrapper for an xmlDoc struct.

The created xmlpp::Document takes ownership of the xmlDoc. When the Document is deleted, so is the xmlDoc and all its nodes.

Parameters

  doc | A pointer to an xmlDoc struct. Must not be `nullptr`.

Exceptions

  xmlpp::internal_error | If doc is `nullptr`.

LIBXMLPP_API xmlpp::Document::~Document | ( |  | ) |
| override

## Member Function Documentation

LIBXMLPP_API CommentNode* xmlpp::Document::add_comment | ( | const ustring& | content | ) |

Append a new comment node.

Parameters

  content | The text. This should be unescaped - see ContentNode::set_content().

Returns
  The new comment node.

Exceptions

  xmlpp::internal_error |

LIBXMLPP_API ProcessingInstructionNode* xmlpp::Document::add_processing_instruction | ( | const ustring& | name,
|  | const ustring& | content
| ) |  |

Append a new processing instruction node.

Since libxml++ 2.36:

Parameters

  name | The name of the application to which the instruction is directed.
  content | The content of the instruction. This should be unescaped - see ContentNode::set_content().

Returns
  The new processing instruction node.

Exceptions

  xmlpp::internal_error |

LIBXMLPP_API _xmlDoc* xmlpp::Document::cobj | ( |  | ) |
| noexcept

Access the underlying libxml implementation.

LIBXMLPP_API const _xmlDoc* xmlpp::Document::cobj | ( |  | ) | const
| noexcept

Access the underlying libxml implementation.

LIBXMLPP_API Element* xmlpp::Document::create_root_node | ( | const ustring& | name,
|  | const ustring& | ns_uri = `ustring()`,
|  | const ustring& | ns_prefix = `ustring()`
| ) |  |

Create the root element node.

If the document already contains a root element node, it is replaced, and the old root element node and all its descendants are deleted.

Parameters

  name | The node's name.
  ns_uri | The namespace URI. A namespace declaration will be added to this node, because it could not have been declared before.
  ns_prefix | The namespace prefix to associate with the namespace. If no namespace prefix is specified then the namespace URI will be the default namespace.

Returns
  A pointer to the new root node.

Exceptions

  xmlpp::internal_error | If memory allocation fails.
  xmlpp::exception | If a new namespace node cannot be created.

LIBXMLPP_API Element* xmlpp::Document::create_root_node_by_import | ( | const Node* | node,
|  | bool | recursive = `true`
| ) |  |

Create a root element node by importing the node from another document, without affecting the source node.

If the document already contains a root element node, it is replaced, and the old root element node and all its descendants are deleted.

Parameters

  node | The node to copy and insert as the root node of the document. It must be an element node.
  recursive | Whether to import the child nodes also. Defaults to true.

Returns
  A pointer to the new root node

Exceptions

  xmlpp::exception | If the node can't be copied.

LIBXMLPP_API ustring xmlpp::Document::get_encoding | ( |  | ) | const

Returns
  The encoding used in the source from which the document has been loaded.

LIBXMLPP_API _xmlEntity* xmlpp::Document::get_entity | ( | const ustring& | name | ) |
| protected

Retrieve an Entity.

The entity can be from an external subset or internally declared.

Parameters

  name | The name of the entity to get.

Returns
  A pointer to the libxml2 entity structure, or `nullptr` if not found.

LIBXMLPP_API Dtd* xmlpp::Document::get_internal_subset | ( |  | ) | const

Get the internal subset of this document.

Returns
  A pointer to the DTD, or `nullptr` if not found.

LIBXMLPP_API Element* xmlpp::Document::get_root_node | ( |  | ) |

Return the root node.

This function does not create a default root node if it doesn't exist.

Returns
  A pointer to the root node if it exists, `nullptr` otherwise.

LIBXMLPP_API const Element* xmlpp::Document::get_root_node | ( |  | ) | const

Return the root node.

This function does not create a default root node if it doesn't exist.

Returns
  A pointer to the root node if it exists, `nullptr` otherwise.

LIBXMLPP_API int xmlpp::Document::process_xinclude | ( | bool | generate_xinclude_nodes = `true`,
|  | bool | fixup_base_uris = `true`
| ) |  |

Perform XInclude substitution on the XML document.

XInclude substitution may both add and delete nodes in the document, as well as change the type of some nodes. All pointers to deleted nodes and nodes whose type is changed become invalid. (The node type represented by an underlying xmlNode struct can change. The type of a C++ wrapper can't change. The old wrapper is deleted, and a new one is created if and when it's required.)

Parser::set_parser_options() and DomParser::set_xinclude_options() do not affect Document::process_xinclude().

Since libxml++ 2.36:

Parameters

  generate_xinclude_nodes | Generate XIncludeStart and XIncludeEnd nodes.
  fixup_base_uris | Add or replace xml:base attributes in included element nodes, if necessary to preserve the target of relative URIs.

Returns
  The number of substitutions.

Exceptions

  xmlpp::exception |

virtual LIBXMLPP_API void xmlpp::Document::set_entity_declaration | ( | const ustring& | name,
|  | XmlEntityType | type,
|  | const ustring& | publicId,
|  | const ustring& | systemId,
|  | const ustring& | content
| ) |  |
| virtual

Add an Entity declaration to the document.

Parameters

  name | The name of the entity that will be used in an entity reference.
  type | The type of entity.
  publicId | The public ID of the subset.
  systemId | The system ID of the subset.
  content | The value of the Entity. In entity reference substitutions, this is the replacement value.

Exceptions

  xmlpp::internal_error |

LIBXMLPP_API void xmlpp::Document::set_internal_subset | ( | const ustring& | name,
|  | const ustring& | external_id,
|  | const ustring& | system_id
| ) |  |

Create the internal subset of this document.

If the document already has an internal subset, a new one is not created.

Parameters

  name | The DTD name.
  external_id | The external (PUBLIC) ID, or an empty string.
  system_id | The system ID, or an empty string.

LIBXMLPP_API void xmlpp::Document::write_to_file | ( | const std::string & | filename,
|  | const ustring& | encoding = `ustring()`
| ) |  |

Write the document to a file.

Parameters

  filename |
  encoding | If not provided, UTF-8 is used

Exceptions

  xmlpp::exception |

LIBXMLPP_API void xmlpp::Document::write_to_file_formatted | ( | const std::string & | filename,
|  | const ustring& | encoding = `ustring()`
| ) |  |

Write the document to a file.

The output is formatted by inserting whitespaces, which is easier to read for a human, but may insert unwanted significant whitespaces. Use with care !

Parameters

  filename |
  encoding | If not provided, UTF-8 is used

Exceptions

  xmlpp::exception |

LIBXMLPP_API void xmlpp::Document::write_to_stream | ( | std::ostream & | output,
|  | const ustring& | encoding = `ustring()`
| ) |  |

Write the document to a std::ostream.

Parameters

  output | A reference to the stream in which the document will be written
  encoding | If not provided, UTF-8 is used

Exceptions

  xmlpp::exception |
  xmlpp::internal_error |

Warning
  This method is much less efficient than write_to_string if you want to dump the document to a buffer or the standard output. Writing to a fstream is almost as fast as write_to_file

LIBXMLPP_API void xmlpp::Document::write_to_stream_formatted | ( | std::ostream & | output,
|  | const ustring& | encoding = `ustring()`
| ) |  |

Write the document to a std::ostream.

The output is formatted by inserting whitespaces, which is easier to read for a human, but may insert unwanted significant whitespaces. Use with care !

Parameters

  output | A reference to the stream in which the document will be written
  encoding | If not provided, UTF-8 is used

Exceptions

  xmlpp::exception |
  xmlpp::internal_error |

Warning
  See write_to_stream

LIBXMLPP_API ustring xmlpp::Document::write_to_string | ( | const ustring& | encoding = `ustring()` | ) |

Write the document to the memory.

Parameters

  encoding | If not provided, UTF-8 is used

Returns
  The written document.

Exceptions

  xmlpp::exception |

LIBXMLPP_API ustring xmlpp::Document::write_to_string_formatted | ( | const ustring& | encoding = `ustring()` | ) |

Write the document to the memory.

The output is formatted by inserting whitespaces, which is easier to read for a human, but may insert unwanted significant whitespaces. Use with care !

Parameters

  encoding | If not provided, UTF-8 is used

Returns
  The written document.

Exceptions

  xmlpp::exception |