XML processing utilities. More...

Classes
class	attribute_ref
	A reference to an XML attribute. More...
class	attributes_view
	A view over the attributes of an XML node. More...
class	children_view
	A view over the direct children of an XML node. More...
class	descendants_view
	A view over all descendants of an XML node (recursive). More...
struct	iterator_state
	Shared state for XML iterators to coordinate traversal. More...
class	node_ref
	A reference to the current XML node in the reader. More...
class	nodes_view
	A view over a sequence of XML nodes. More...
class	reader
	A forward-only, non-cached XML reader. More...

Enumerations
enum class	reader_blanks { keep , ignore }
	Options for handling blank nodes in the XML reader. More...
enum class	node_type { none = 0 , element = 1 , attribute = 2 , text = 3 , cdata = 4 , entity_reference = 5 , entity = 6 , processing_instruction = 7 , comment = 8 , document = 9 , document_type = 10 , document_fragment = 11 , notation = 12 , whitespace = 13 , significant_whitespace = 14 , end_element = 15 , end_entity = 16 , xml_declaration = 17 }
	Represents the type of an XML node. More...

Functions
template<typename T, safety_policy safety_level> requires convert::conversion_implementation_exists<T, std::string_view>
std::optional< T >	convert_impl (const attribute_ref< safety_level > &attr, convert::dest_type_tag< T >) noexcept
	Conversion implementation to convert an attribute_ref to another type T. This is done by attempting to convert the attribute's string value.
template<safety_policy safety_level>
attributes_view< safety_level >	attributes (const node_ref< safety_level > &node)
	A factory function to create an attributes_view with a specified safety policy.
template<safety_policy safety_level>
checked< std::optional< std::string_view >, safety_level >	attribute_value (const node_ref< safety_level > &node, std::string_view name)
	A convenience helper to find an attribute by name.
template<typename T, safety_policy safety_level> requires convert::conversion_implementation_exists<T, std::string_view>
checked< std::optional< T >, safety_level >	attribute_value (const node_ref< safety_level > &node, std::string_view name)
	A convenience helper to find an attribute by name and convert its value to a specific type.
template<safety_policy safety_level>
children_view< safety_level >	children (const node_ref< safety_level > &node)
	Returns a view of the direct children of the given node.
template<safety_policy safety_level>
children_view< safety_level >	children (reader< safety_level > &reader)
	Returns a view of the top-level children in the reader.
template<safety_policy safety_level>
descendants_view< safety_level >	descendants (const node_ref< safety_level > &node)
	Returns a view of all descendants of the given node.
template<safety_policy safety_level>
descendants_view< safety_level >	descendants (reader< safety_level > &reader)
	Returns a view of all descendants in the reader (entire document).
template<typename T, safety_policy safety_level> requires convert::conversion_implementation_exists<T, std::string_view>
std::optional< T >	convert_impl (const node_ref< safety_level > &node, convert::dest_type_tag< T >) noexcept
	Conversion implementation to convert a node_ref to another type T. This is done by attempting to convert the node's string value.
template<safety_policy safety_level>
nodes_view< safety_level >	nodes (const node_ref< safety_level > &node)
	Creates a view of nodes starting from the given node's state.
template<safety_policy safety_level>
nodes_view< safety_level >	nodes (reader< safety_level > &reader)
	Creates a view of nodes from the reader.
template<safety_policy safety_level>
node_ref< safety_level >	root_element (reader< safety_level > &reader)
	Finds and returns the root element of the XML document.

Detailed Description

XML processing utilities.

Enumeration Type Documentation

◆ node_type

enum class docwire::xml::node_type

strong

Represents the type of an XML node.

Definition at line 30 of file xml_reader.h.

◆ reader_blanks

enum class docwire::xml::reader_blanks

strong

Options for handling blank nodes in the XML reader.

Definition at line 26 of file xml_reader.h.

Function Documentation

◆ attribute_value() [1/2]

template<typename T, safety_policy safety_level>
requires convert::conversion_implementation_exists<T, std::string_view>

checked< std::optional< T >, safety_level > docwire::xml::attribute_value	(	const node_ref< safety_level > &	node,
		std::string_view	name )

A convenience helper to find an attribute by name and convert its value to a specific type.

Template Parameters

T	The target type for conversion.
safety_level	The safety policy for the node reference and attribute access.

Parameters

node	The XML node to search within.
name	The name of the attribute to find.

Warning: This function relies on a single-pass XML reader.

Returns: An std::optional<T> containing the converted value if the attribute is found and conversion succeeds, otherwise std::nullopt.

See also: XML parsing example

Definition at line 108 of file xml_attributes.h.

◆ attribute_value() [2/2]

template<safety_policy safety_level>

checked< std::optional< std::string_view >, safety_level > docwire::xml::attribute_value	(	const node_ref< safety_level > &	node,
		std::string_view	name )

A convenience helper to find an attribute by name.

Template Parameters

safety_level The safety policy to use.

Parameters

node	The XML node to search within.
name	The name of the attribute to find.

Warning: This function relies on a single-pass XML reader.

Returns: An std::optional<std::string_view> containing the attribute's value if found, otherwise std::nullopt.

See also: XML parsing example

Examples: xml_parsing_example.cpp.

Definition at line 88 of file xml_attributes.h.

◆ attributes()

template<safety_policy safety_level>

attributes_view< safety_level > docwire::xml::attributes ( const node_ref< safety_level > & node )

A factory function to create an attributes_view with a specified safety policy.

Parameters

node	The XML node whose attributes will be viewed.

Template Parameters

safety_level The safety policy to use.

Warning: This function relies on a single-pass XML reader.

Returns: An attributes_view for the given node.

See also: XML parsing example

Examples: xml_parsing_example.cpp.

Definition at line 73 of file xml_attributes.h.

◆ children() [1/2]

template<safety_policy safety_level>

children_view< safety_level > docwire::xml::children ( const node_ref< safety_level > & node )

Returns a view of the direct children of the given node.

Template Parameters

safety_level The safety policy to use.

Parameters

node	The node to retrieve children for.

Warning: This function relies on a single-pass XML reader.

See also: XML parsing example

Examples: xml_parsing_example.cpp.

Definition at line 119 of file xml_children.h.

◆ children() [2/2]

template<safety_policy safety_level>

children_view< safety_level > docwire::xml::children ( reader< safety_level > & reader )

Returns a view of the top-level children in the reader.

Template Parameters

safety_level The safety policy to use.

Parameters

reader The XML reader to traverse.

Warning: This function relies on a single-pass XML reader.

See also: XML parsing example

Definition at line 132 of file xml_children.h.

◆ convert_impl() [1/2]

template<typename T, safety_policy safety_level>
requires convert::conversion_implementation_exists<T, std::string_view>

std::optional< T > docwire::xml::convert_impl	(	const attribute_ref< safety_level > &	attr,
		convert::dest_type_tag< T >	)

noexcept

Conversion implementation to convert an attribute_ref to another type T. This is done by attempting to convert the attribute's string value.

Template Parameters

T	The target type.
safety_level	The safety policy.

Definition at line 57 of file xml_attribute_ref.h.

◆ convert_impl() [2/2]

template<typename T, safety_policy safety_level>
requires convert::conversion_implementation_exists<T, std::string_view>

std::optional< T > docwire::xml::convert_impl	(	const node_ref< safety_level > &	node,
		convert::dest_type_tag< T >	)

noexcept

Conversion implementation to convert a node_ref to another type T. This is done by attempting to convert the node's string value.

Template Parameters

T	The target type.
safety_level	The safety policy.

Definition at line 68 of file xml_node_ref.h.

◆ descendants() [1/2]

template<safety_policy safety_level>

descendants_view< safety_level > docwire::xml::descendants ( const node_ref< safety_level > & node )

Returns a view of all descendants of the given node.

Template Parameters

safety_level The safety policy to use.

Parameters

node	The node to retrieve descendants for.

Warning: This function relies on a single-pass XML reader.

See also: XML parsing example

Definition at line 128 of file xml_descendants.h.

◆ descendants() [2/2]

template<safety_policy safety_level>

descendants_view< safety_level > docwire::xml::descendants ( reader< safety_level > & reader )

Returns a view of all descendants in the reader (entire document).

Template Parameters

safety_level The safety policy to use.

Parameters

reader The XML reader to traverse.

Warning: This function relies on a single-pass XML reader.

See also: XML parsing example

Definition at line 141 of file xml_descendants.h.

◆ nodes() [1/2]

template<safety_policy safety_level>

nodes_view< safety_level > docwire::xml::nodes ( const node_ref< safety_level > & node )

Creates a view of nodes starting from the given node's state.

Template Parameters

safety_level The safety policy.

Parameters

node	The reference node.

Warning: This function relies on a single-pass XML reader.

Definition at line 104 of file xml_nodes.h.

◆ nodes() [2/2]

template<safety_policy safety_level>

nodes_view< safety_level > docwire::xml::nodes ( reader< safety_level > & reader )

Creates a view of nodes from the reader.

Template Parameters

safety_level The safety policy.

Parameters

reader The XML reader.

Warning: This function relies on a single-pass XML reader.

Definition at line 116 of file xml_nodes.h.

◆ root_element()

template<safety_policy safety_level>

node_ref< safety_level > docwire::xml::root_element ( reader< safety_level > & reader )

Finds and returns the root element of the XML document.

Template Parameters

safety_level The safety policy to use.

Parameters

reader The XML reader to search.

Exceptions

docwire::error with docwire::errors::uninterpretable_data tag attached if no root element is found.

Warning: This function advances the single-pass XML reader.

See also: XML parsing example

Examples: xml_parsing_example.cpp.

Definition at line 32 of file xml_root_element.h.

Classes

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ node_type

◆ reader_blanks

Function Documentation

◆ attribute_value() [1/2]

◆ attribute_value() [2/2]

◆ attributes()

◆ children() [1/2]

◆ children() [2/2]

◆ convert_impl() [1/2]

◆ convert_impl() [2/2]

◆ descendants() [1/2]

◆ descendants() [2/2]

◆ nodes() [1/2]

◆ nodes() [2/2]

◆ root_element()