libxml++: xmlpp::TextReader Class Reference

libxml++ 5.6.1

Public Types | Public Member Functions | List of all members
xmlpp::TextReader Class Reference

A TextReader-style XML parser. More...

`#include <libxml++/parsers/textreader.h>`

Inheritance diagram for xmlpp::TextReader:
[legend]

## Public Types
enum class | NodeType { InternalError = -1 , None = 0 , Element = 1 , Attribute = 2 , Text = 3 , CDATA = 4 , EntityReference = 5 , Entity = 6 , ProcessingInstruction = 7 , Comment = 8 , Document = 9 , DocumentType = 10 , DocumentFragment = 11 , Notation = 12 , Whitespace = 13 , SignificantWhitespace = 14 , EndElement = 15 , EndEntity = 16 , XmlDeclaration = 17 }
| Node type of the current node. More...
enum class | ParserProperties { LoadDtd = 1 , DefaultAttrs = 2 , Validate = 3 , SubstEntities = 4 }
enum class | ReadState { InternalError = -1 , Initial = 0 , Interactive = 1 , Error = 2 , EndOfFile = 3 , Closed = 4 , Reading = 5 }
using | size_type = unsigned int

## Public Member Functions
| TextReader (const unsigned char *data, size_type size, const ustring & uri=ustring())
| Creates a new TextReader object which parses in memory data.
| TextReader (const ustring & URI)
| Creates a new TextReader object to parse a file or URI.
| TextReader (struct _xmlTextReader * cobj)
| Wraps a TextReader object from an underlying libxml object.
| ~TextReader () override
void | close ()
Node * | expand ()
| Expand the current node.
ustring | get_attribute (const ustring & local_name, const ustring & ns_uri) const
| Gets the value of the specified attribute.
ustring | get_attribute (const ustring & name) const
| Gets the value of the attribute with the specified qualified name.
ustring | get_attribute (int number) const
| Gets the value of the attribute with the specified index relative to the containing element.
std::optional< ustring > | get_attribute2 (const ustring & local_name, const ustring & ns_uri) const
| Gets the value of the specified attribute.
std::optional< ustring > | get_attribute2 (const ustring & name) const
| Gets the value of the attribute with the specified qualified name.
std::optional< ustring > | get_attribute2 (int number) const
| Gets the value of the attribute with the specified index relative to the containing element.
int | get_attribute_count () const
| Gets the number of attributes on the current node.
ustring | get_base_uri () const
| Gets the base Uniform Resource Identifier (URI) of the current node.
std::optional< ustring > | get_base_uri2 () const
| Gets the base Uniform Resource Identifier (URI) of the current node.
Node * | get_current_node ()
| Get a pointer to the current node.
const Node * | get_current_node () const
| Get a pointer to the current node.
int | get_depth () const
| Gets the depth of the current node in the XML document.
ustring | get_local_name () const
| Gets the local name of the node.
std::optional< ustring > | get_local_name2 () const
| Gets the local name of the node.
ustring | get_name () const
| Gets the qualified name of the node, equal to Prefix:LocalName.
std::optional< ustring > | get_name2 () const
| Gets the qualified name of the node, equal to Prefix:LocalName.
ustring | get_namespace_uri () const
| Gets the URI defining the namespace associated with the node.
std::optional< ustring > | get_namespace_uri2 () const
| Gets the URI defining the namespace associated with the node.
NodeType | get_node_type () const
| Get the node type of the current node.
bool | get_normalization () const
bool | get_parser_property (ParserProperties property) const
ustring | get_prefix () const
| Get the namespace prefix associated with the current node.
std::optional< ustring > | get_prefix2 () const
| Get the namespace prefix associated with the current node.
char | get_quote_char () const
| Get the quotation mark character used to enclose the value of an attribute.
ReadState | get_read_state () const
| Gets the read state of the reader.
ustring | get_value () const
| Gets the text value of the node.
std::optional< ustring > | get_value2 () const
| Gets the text value of the node.
ustring | get_xml_lang () const
| Gets the xml:lang scope within which the node resides.
std::optional< ustring > | get_xml_lang2 () const
| Gets the xml:lang scope within which the node resides.
bool | has_attributes () const
| Gets a value indicating whether the current node has any attributes.
bool | has_value () const
| Whether the node can have a text value.
bool | is_default () const
| Whether an Attribute node was generated from the default value defined in the DTD or schema.
bool | is_empty_element () const
| Check if the current node is empty.
bool | is_valid () const
ustring | lookup_namespace (const ustring & prefix) const
| Resolves a namespace prefix in the scope of the current element.
std::optional< ustring > | lookup_namespace2 (const ustring & prefix) const
| Resolves a namespace prefix in the scope of the current element.
bool | move_to_attribute (const ustring & local_name, const ustring & ns_uri)
bool | move_to_attribute (const ustring & name)
bool | move_to_attribute (int number)
bool | move_to_element ()
bool | move_to_first_attribute ()
bool | move_to_next_attribute ()
bool | next ()
bool | read ()
| Moves the position of the current instance to the next node in the stream, exposing its properties.
bool | read_attribute_value ()
| Parses an attribute value into one or more Text and EntityReference nodes.
ustring | read_inner_xml ()
| Reads the contents of the current node, including child nodes and markup.
std::optional< ustring > | read_inner_xml2 ()
| Reads the contents of the current node, including child nodes and markup.
ustring | read_outer_xml ()
| Reads the current node and its contents, including child nodes and markup.
std::optional< ustring > | read_outer_xml2 ()
| Reads the current node and its contents, including child nodes and markup.
ustring | read_string ()
| Reads the contents of an element or a text node as a string.
std::optional< ustring > | read_string2 ()
| Reads the contents of an element or a text node as a string.
void | set_normalization (bool value)
void | set_parser_property (ParserProperties property, bool value)
Public Member Functions inherited from xmlpp::NonCopyable
| NonCopyable (const NonCopyable &)=delete
| NonCopyable (NonCopyable &&)=delete
NonCopyable & | operator= (const NonCopyable &)=delete
NonCopyable & | operator= (NonCopyable &&)=delete

## Additional Inherited Members
Protected Member Functions inherited from xmlpp::NonCopyable
| NonCopyable () noexcept
virtual | ~NonCopyable ()

## Detailed Description

A TextReader-style XML parser.

A reader that provides fast, non-cached, forward-only access to XML data, in the style of .Net's XmlTextReader class.

## Member Typedef Documentation

## ◆ size_type

using xmlpp::TextReader::size_type = unsigned int

## Member Enumeration Documentation

## ◆ NodeType

enum class xmlpp::TextReader::NodeType
| strong

Node type of the current node.

See DotGNU's XmlNodeType enum.

Enumerator
InternalError |
None |
Element |
Attribute |
Text |
CDATA |
EntityReference |
Entity |
ProcessingInstruction |
Comment |
Document |
DocumentType |
DocumentFragment |
Notation |
Whitespace |
SignificantWhitespace |
EndElement |
EndEntity |
XmlDeclaration |

## ◆ ParserProperties

enum class xmlpp::TextReader::ParserProperties
| strong

Enumerator
LoadDtd |
DefaultAttrs |
Validate |
SubstEntities |

## ◆ ReadState

enum class xmlpp::TextReader::ReadState
| strong

Enumerator
InternalError |
Initial |
Interactive |
Error |
EndOfFile |
Closed |
Reading |

## Constructor & Destructor Documentation

## ◆ TextReader() [1/3]

xmlpp::TextReader::TextReader | ( | struct _xmlTextReader * | cobj | ) |

Wraps a TextReader object from an underlying libxml object.

The TextReader takes ownership of cobj.

Parameters

  cobj | The underlying libxml xmlTextReader object.

## ◆ TextReader() [2/3]

xmlpp::TextReader::TextReader | ( | const ustring & | URI | ) |

Creates a new TextReader object to parse a file or URI.

Parameters

  URI | The URI to read.

Exceptions

  xmlpp::internal_error | If an xmlTextReader object cannot be created.

## ◆ TextReader() [3/3]

xmlpp::TextReader::TextReader | ( | const unsigned char * | data,
|  | size_type | size,
|  | const ustring & | uri = `ustring()`
| ) |  |

Creates a new TextReader object which parses in memory data.

Parameters

  data | The data to parse.
  size | The number of bytes in data.
  uri | The base URI to use for the document.

Exceptions

  xmlpp::internal_error | If an xmlTextReader object cannot be created.

## ◆ ~TextReader()

xmlpp::TextReader::~TextReader | ( |  | ) |
| override

## Member Function Documentation

## ◆ close()

void xmlpp::TextReader::close | ( |  | ) |

## ◆ expand()

Node * xmlpp::TextReader::expand | ( |  | ) |

Expand the current node.

Reads the contents of the current node and the full subtree. It then makes the subtree available until the next call to read() or next().

Warning
  The C++ wrappers are not deleted. Using this method causes memory leaks, unless you call xmlpp::Node::free_wrappers(), which is not intended to be called by the application.

Returns
  A pointer to the current node, or `nullptr` in case of error.

Exceptions

  xmlpp::parse_error |
  xmlpp::validity_error |

## ◆ get_attribute() [1/3]

ustring xmlpp::TextReader::get_attribute | ( | const ustring & | local_name,
|  | const ustring & | ns_uri
| ) |  | const

Gets the value of the specified attribute.

Parameters

  local_name | The local name of the attribute.
  ns_uri | The namespace URI of the attribute.

Returns
  The value of the specified attribute, or an empty ustring in case of error.

Exceptions

  xmlpp::parse_error |
  xmlpp::validity_error |

Deprecated:
  5.6: Use get_attribute2(const ustring&, const ustring&) const instead.

## ◆ get_attribute() [2/3]

ustring xmlpp::TextReader::get_attribute | ( | const ustring & | name | ) | const

Gets the value of the attribute with the specified qualified name.

Parameters

  name | The qualified name of the attribute.

Returns
  The value of the specified attribute, or an empty ustring in case of error.

Exceptions

  xmlpp::parse_error |
  xmlpp::validity_error |

Deprecated:
  5.6: Use get_attribute2(const ustring&) const instead.

## ◆ get_attribute() [3/3]

ustring xmlpp::TextReader::get_attribute | ( | int | number | ) | const

Gets the value of the attribute with the specified index relative to the containing element.

Parameters

  number | The zero-based index of the attribute relative to the containing element.

Returns
  The value of the specified attribute, or an empty ustring in case of error.

Exceptions

  xmlpp::parse_error |
  xmlpp::validity_error |

Deprecated:
  5.6: Use get_attribute2(int) const instead.

## ◆ get_attribute2() [1/3]

std::optional< ustring > xmlpp::TextReader::get_attribute2 | ( | const ustring & | local_name,
|  | const ustring & | ns_uri
| ) |  | const

Gets the value of the specified attribute.

Parameters

  local_name | The local name of the attribute.
  ns_uri | The namespace URI of the attribute.

Returns
  The value of the specified attribute, or no value in case of error.

Exceptions

  xmlpp::parse_error |
  xmlpp::validity_error |

Since libxml++ 5.6:

## ◆ get_attribute2() [2/3]

std::optional< ustring > xmlpp::TextReader::get_attribute2 | ( | const ustring & | name | ) | const

Gets the value of the attribute with the specified qualified name.

Parameters

  name | The qualified name of the attribute.

Returns
  The value of the specified attribute, or no value in case of error.

Exceptions

  xmlpp::parse_error |
  xmlpp::validity_error |

Since libxml++ 5.6:

## ◆ get_attribute2() [3/3]

std::optional< ustring > xmlpp::TextReader::get_attribute2 | ( | int | number | ) | const

Gets the value of the attribute with the specified index relative to the containing element.

Parameters

  number | The zero-based index of the attribute relative to the containing element.

Returns
  The value of the specified attribute, or no value in case of error.

Exceptions

  xmlpp::parse_error |
  xmlpp::validity_error |

Since libxml++ 5.6:

## ◆ get_attribute_count()

int xmlpp::TextReader::get_attribute_count | ( |  | ) | const

Gets the number of attributes on the current node.

Returns
  The number of attributes on the current node, or zero if the current node does not support attributes, or -1 in case of error.

Exceptions

  xmlpp::parse_error |
  xmlpp::validity_error |

## ◆ get_base_uri()

ustring xmlpp::TextReader::get_base_uri | ( |  | ) | const

Gets the base Uniform Resource Identifier (URI) of the current node.

Returns
  The base URI of the current node or an empty ustring if not available.

Exceptions

  xmlpp::parse_error |
  xmlpp::validity_error |

Deprecated:
  5.6: Use get_base_uri2() instead.

## ◆ get_base_uri2()

std::optional< ustring > xmlpp::TextReader::get_base_uri2 | ( |  | ) | const

Gets the base Uniform Resource Identifier (URI) of the current node.

Returns
  The base URI of the current node, or no value if not available.

Exceptions

  xmlpp::parse_error |
  xmlpp::validity_error |

Since libxml++ 5.6:

## ◆ get_current_node() [1/2]

Node * xmlpp::TextReader::get_current_node | ( |  | ) |

Get a pointer to the current node.

Warning
  This is dangerous because the underlying node may be destroyed on the next read. The C++ wrapper is not deleted. Using this method causes memory leaks, unless you call xmlpp::Node::free_wrappers(), which is not intended to be called by the application.

Returns
  A pointer to the current node, or `nullptr` in case of error.

## ◆ get_current_node() [2/2]

const Node * xmlpp::TextReader::get_current_node | ( |  | ) | const

Get a pointer to the current node.

Warning
  See the non-const get_current_node().

Returns
  A pointer to the current node, or `nullptr` in case of error.

## ◆ get_depth()

int xmlpp::TextReader::get_depth | ( |  | ) | const

Gets the depth of the current node in the XML document.

Returns
  The depth of the current node in the XML document, or -1 in case of error.

## ◆ get_local_name()

ustring xmlpp::TextReader::get_local_name | ( |  | ) | const

Gets the local name of the node.

Returns
  The local name of the node, or an empty ustring if not available.

Exceptions

  xmlpp::parse_error |
  xmlpp::validity_error |

Deprecated:
  5.6: Use get_local_name2() instead.

## ◆ get_local_name2()

std::optional< ustring > xmlpp::TextReader::get_local_name2 | ( |  | ) | const

Gets the local name of the node.

Returns
  The local name of the node, or no value if not available.

Exceptions

  xmlpp::parse_error |
  xmlpp::validity_error |

Since libxml++ 5.6:

## ◆ get_name()

ustring xmlpp::TextReader::get_name | ( |  | ) | const

Gets the qualified name of the node, equal to Prefix:LocalName.

Returns
  The qualified name of the node, or an empty ustring if not available.

Exceptions

  xmlpp::parse_error |
  xmlpp::validity_error |

Deprecated:
  5.6: Use get_name2() instead.

## ◆ get_name2()

std::optional< ustring > xmlpp::TextReader::get_name2 | ( |  | ) | const

Gets the qualified name of the node, equal to Prefix:LocalName.

Returns
  The qualified name of the node, or no value if not available.

Exceptions

  xmlpp::parse_error |
  xmlpp::validity_error |

Since libxml++ 5.6:

## ◆ get_namespace_uri()

ustring xmlpp::TextReader::get_namespace_uri | ( |  | ) | const

Gets the URI defining the namespace associated with the node.

Returns
  The namespace URI, or an empty ustring if not available.

Deprecated:
  5.6: Use get_namespace_uri2() instead.

## ◆ get_namespace_uri2()

std::optional< ustring > xmlpp::TextReader::get_namespace_uri2 | ( |  | ) | const

Gets the URI defining the namespace associated with the node.

Returns
  The namespace URI, or no value if not available.

Since libxml++ 5.6:

## ◆ get_node_type()

NodeType xmlpp::TextReader::get_node_type | ( |  | ) | const

Get the node type of the current node.

Returns
  The xmlpp::TextReader::NodeType of the current node. In case of error, either returns xmlpp::TextReader::NodeType::InternalError or throws an exception.

Exceptions

  xmlpp::parse_error |
  xmlpp::validity_error |

## ◆ get_normalization()

bool xmlpp::TextReader::get_normalization | ( |  | ) | const

## ◆ get_parser_property()

bool xmlpp::TextReader::get_parser_property | ( | ParserProperties | property | ) | const

## ◆ get_prefix()

ustring xmlpp::TextReader::get_prefix | ( |  | ) | const

Get the namespace prefix associated with the current node.

Returns
  The namespace prefix, or an empty string if not available.

Deprecated:
  5.6: Use get_prefix2() instead.

## ◆ get_prefix2()

std::optional< ustring > xmlpp::TextReader::get_prefix2 | ( |  | ) | const

Get the namespace prefix associated with the current node.

Returns
  The namespace prefix, or no value if not available.

Since libxml++ 5.6:

## ◆ get_quote_char()

char xmlpp::TextReader::get_quote_char | ( |  | ) | const

Get the quotation mark character used to enclose the value of an attribute.

Returns
  Returns " or ' and -1 in case of error.

## ◆ get_read_state()

ReadState xmlpp::TextReader::get_read_state | ( |  | ) | const

Gets the read state of the reader.

Returns
  The state value, or xmlpp::TextReader::ReadState::InternalError in case of error.

## ◆ get_value()

ustring xmlpp::TextReader::get_value | ( |  | ) | const

Gets the text value of the node.

Returns
  The text value, or an empty ustring if not available.

Exceptions

  xmlpp::parse_error |
  xmlpp::validity_error |

Deprecated:
  5.6: Use get_value2() instead.

## ◆ get_value2()

std::optional< ustring > xmlpp::TextReader::get_value2 | ( |  | ) | const

Gets the text value of the node.

Returns
  The text value, or no value if not available.

Exceptions

  xmlpp::parse_error |
  xmlpp::validity_error |

Since libxml++ 5.6:

## ◆ get_xml_lang()

ustring xmlpp::TextReader::get_xml_lang | ( |  | ) | const

Gets the xml:lang scope within which the node resides.

Returns
  The xml:lang value, or an empty ustring if not available.

Deprecated:
  5.6: Use get_xml_lang2() instead.

## ◆ get_xml_lang2()

std::optional< ustring > xmlpp::TextReader::get_xml_lang2 | ( |  | ) | const

Gets the xml:lang scope within which the node resides.

Returns
  The xml:lang value, or no value if not available.

Since libxml++ 5.6:

## ◆ has_attributes()

bool xmlpp::TextReader::has_attributes | ( |  | ) | const

Gets a value indicating whether the current node has any attributes.

Returns
  true if the current has attributes, false otherwise.

## ◆ has_value()

bool xmlpp::TextReader::has_value | ( |  | ) | const

Whether the node can have a text value.

Returns
  true if the current node can have an associated text value, false otherwise.

## ◆ is_default()

bool xmlpp::TextReader::is_default | ( |  | ) | const

Whether an Attribute node was generated from the default value defined in the DTD or schema.

Returns
  true if defaulted, false otherwise.

## ◆ is_empty_element()

bool xmlpp::TextReader::is_empty_element | ( |  | ) | const

Check if the current node is empty.

Returns
  true if empty, false otherwise.

## ◆ is_valid()

bool xmlpp::TextReader::is_valid | ( |  | ) | const

## ◆ lookup_namespace()

ustring xmlpp::TextReader::lookup_namespace | ( | const ustring & | prefix | ) | const

Resolves a namespace prefix in the scope of the current element.

Parameters

  prefix | The prefix whose namespace URI is to be resolved. To return the default namespace, specify an empty string.

Returns
  The the namespace URI to which the prefix maps, or an empty ustring in case of error.

Exceptions

  xmlpp::parse_error |
  xmlpp::validity_error |

Deprecated:
  5.6: Use lookup_namespace2() instead.

## ◆ lookup_namespace2()

std::optional< ustring > xmlpp::TextReader::lookup_namespace2 | ( | const ustring & | prefix | ) | const

Resolves a namespace prefix in the scope of the current element.

Parameters

  prefix | The prefix whose namespace URI is to be resolved. To return the default namespace, specify an empty string.

Returns
  The the namespace URI to which the prefix maps, or no value in case of error.

Exceptions

  xmlpp::parse_error |
  xmlpp::validity_error |

Since libxml++ 5.6:

## ◆ move_to_attribute() [1/3]

bool xmlpp::TextReader::move_to_attribute | ( | const ustring & | local_name,
|  | const ustring & | ns_uri
| ) |  |

## ◆ move_to_attribute() [2/3]

bool xmlpp::TextReader::move_to_attribute | ( | const ustring & | name | ) |

## ◆ move_to_attribute() [3/3]

bool xmlpp::TextReader::move_to_attribute | ( | int | number | ) |

## ◆ move_to_element()

bool xmlpp::TextReader::move_to_element | ( |  | ) |

## ◆ move_to_first_attribute()

bool xmlpp::TextReader::move_to_first_attribute | ( |  | ) |

## ◆ move_to_next_attribute()

bool xmlpp::TextReader::move_to_next_attribute | ( |  | ) |

## ◆ next()

bool xmlpp::TextReader::next | ( |  | ) |

## ◆ read()

bool xmlpp::TextReader::read | ( |  | ) |

Moves the position of the current instance to the next node in the stream, exposing its properties.

Returns
  true if the node was read successfully, false if there are no more nodes to read.

Exceptions

  xmlpp::parse_error |
  xmlpp::validity_error |

## ◆ read_attribute_value()

bool xmlpp::TextReader::read_attribute_value | ( |  | ) |

Parses an attribute value into one or more Text and EntityReference nodes.

Returns
  A bool where true indicates the attribute value was parsed, and false indicates the reader was not positioned on an attribute node or all the attribute values have been read.

Exceptions

  xmlpp::parse_error |
  xmlpp::validity_error |

## ◆ read_inner_xml()

ustring xmlpp::TextReader::read_inner_xml | ( |  | ) |

Reads the contents of the current node, including child nodes and markup.

Returns
  A ustring containing the XML content, or an empty ustring if the current node is neither an element nor attribute, or has no child nodes.

Exceptions

  xmlpp::parse_error |
  xmlpp::validity_error |

Deprecated:
  5.6: Use read_inner_xml2() instead.

## ◆ read_inner_xml2()

std::optional< ustring > xmlpp::TextReader::read_inner_xml2 | ( |  | ) |

Reads the contents of the current node, including child nodes and markup.

Returns
  A std::optional<ustring> containing the XML content, or no value if the current node is neither an element nor attribute, or has no child nodes.

Exceptions

  xmlpp::parse_error |
  xmlpp::validity_error |

Since libxml++ 5.6:

## ◆ read_outer_xml()

ustring xmlpp::TextReader::read_outer_xml | ( |  | ) |

Reads the current node and its contents, including child nodes and markup.

Returns
  A ustring containing the XML content, or an empty ustring if the current node is neither an element nor attribute.

Exceptions

  xmlpp::parse_error |
  xmlpp::validity_error |

Deprecated:
  5.6: Use read_outer_xml2() instead.

## ◆ read_outer_xml2()

std::optional< ustring > xmlpp::TextReader::read_outer_xml2 | ( |  | ) |

Reads the current node and its contents, including child nodes and markup.

Returns
  A std::optional<ustring> containing the XML content, or no value if the current node is neither an element nor attribute.

Exceptions

  xmlpp::parse_error |
  xmlpp::validity_error |

Since libxml++ 5.6:

## ◆ read_string()

ustring xmlpp::TextReader::read_string | ( |  | ) |

Reads the contents of an element or a text node as a string.

Returns
  A ustring containing the contents of the Element or Text node, or an empty ustring if the reader is positioned on any other type of node.

Exceptions

  xmlpp::parse_error |
  xmlpp::validity_error |

Deprecated:
  5.6: Use read_string2() instead.

## ◆ read_string2()

std::optional< ustring > xmlpp::TextReader::read_string2 | ( |  | ) |

Reads the contents of an element or a text node as a string.

Returns
  A std::optional<ustring> containing the contents of the Element or Text node, or no value if the reader is positioned on any other type of node.

Exceptions

  xmlpp::parse_error |
  xmlpp::validity_error |

Since libxml++ 5.6:

## ◆ set_normalization()

void xmlpp::TextReader::set_normalization | ( | bool | value | ) |

## ◆ set_parser_property()

void xmlpp::TextReader::set_parser_property | ( | ParserProperties | property,
|  | bool | value
| ) |  |