pugi Namespace Reference

Detailed Description

The PugiXML Parser namespace.


Classes

class  xpath_query
 A class that holds compiled XPath query and allows to evaluate query result. More...
class  xml_writer
 Abstract writer class. More...
class  xml_writer_file
 xml_writer implementation for FILE* More...
class  xml_writer_stream
 xml_writer implementation for streams More...
class  xml_attribute
 A light-weight wrapper for manipulating attributes in DOM tree. More...
class  xml_node
 A light-weight wrapper for manipulating nodes in DOM tree. More...
class  xml_node_iterator
 Child node iterator. More...
class  xml_attribute_iterator
 Attribute iterator. More...
class  xml_tree_walker
 Abstract tree walker class. More...
struct  transfer_ownership_tag
 Struct used to distinguish parsing with ownership transfer from parsing without it. More...
struct  xml_parse_result
 Parser result. More...
class  xml_document
 Document class (DOM tree root). More...
class  xpath_exception
 XPath exception class. More...
class  xpath_node
 XPath node class. More...
class  xpath_node_set
 Not necessarily ordered constant collection of XPath nodes. More...

Typedefs

typedef char char_t
 Character type used for all internal storage and operations; depends on PUGIXML_WCHAR_MODE.
typedef std::basic_string<
char, std::char_traits< char >,
std::allocator< char > > 		string_t
 String type used for operations that work with STL string; depends on PUGIXML_WCHAR_MODE.
typedef void *(* allocation_function )(size_t size)
 Memory allocation function.
typedef void(* deallocation_function )(void *ptr)
 Memory deallocation function.

Enumerations

enum  xml_node_type {
  node_null, node_document, node_element, node_pcdata,
  node_cdata, node_comment, node_pi, node_declaration
}
 Tree node classification. More...
enum  encoding_t {
  encoding_auto, encoding_utf8, encoding_utf16_le, encoding_utf16_be,
  encoding_utf16, encoding_utf32_le, encoding_utf32_be, encoding_utf32,
  encoding_wchar
}
 These flags determine the encoding of input data for XML document. More...
enum  xpath_type_t {
  xpath_type_none, xpath_type_node_set, xpath_type_number, xpath_type_string,
  xpath_type_boolean
}
 XPath query return type classification. More...
enum  xml_parse_status {
  status_ok = 0, status_file_not_found, status_io_error, status_out_of_memory,
  status_internal_error, status_unrecognized_tag, status_bad_pi, status_bad_comment,
  status_bad_cdata, status_bad_doctype, status_bad_pcdata, status_bad_start_element,
  status_bad_attribute, status_bad_end_element, status_end_element_mismatch
}
 Parsing status enumeration, returned as part of xml_parse_result struct. More...

Functions

std::basic_string< char, std::char_traits<
char >, std::allocator< char
> > PUGIXML_FUNCTION 		as_utf8 (const wchar_t *str)
 Convert wide string to utf8.
PUGIXML_DEPRECATED std::basic_string<
wchar_t, std::char_traits<
wchar_t >, std::allocator<
wchar_t > > PUGIXML_FUNCTION 		as_utf16 (const char *str)
 Convert utf8 to wide string.
std::basic_string< wchar_t,
std::char_traits< wchar_t >,
std::allocator< wchar_t
> > PUGIXML_FUNCTION 		as_wide (const char *str)
 Convert utf8 to wide string.
void PUGIXML_FUNCTION set_memory_management_functions (allocation_function allocate, deallocation_function deallocate)
 Override default memory management functions.
allocation_function PUGIXML_FUNCTION get_memory_allocation_function ()
 Get current memory allocation function.
deallocation_function PUGIXML_FUNCTION get_memory_deallocation_function ()
 Get current memory deallocation function.

Variables

const unsigned int parse_minimal = 0x0000
 Minimal parsing mode.
const unsigned int parse_pi = 0x0001
 This flag determines if processing instructions (nodes with type node_pi; such nodes have the form of <? target content ?> or <? target ?> in XML) are to be put in DOM tree.
const unsigned int parse_comments = 0x0002
 This flag determines if comments (nodes with type node_comment; such nodes have the form of in XML) are to be put in DOM tree.
const unsigned int parse_cdata = 0x0004
 This flag determines if CDATA sections (nodes with type node_cdata; such nodes have the form of <![CDATA[[content]]> in XML) are to be put in DOM tree.
const unsigned int parse_ws_pcdata = 0x0008
 This flag determines if nodes with PCDATA (regular text) that consist only of whitespace characters are to be put in DOM tree.
const unsigned int parse_escapes = 0x0010
 This flag determines if character and entity references are to be expanded during the parsing process.
const unsigned int parse_eol = 0x0020
 This flag determines if EOL handling (that is, replacing sequences 0x0d 0x0a by a single 0x0a character, and replacing all standalone 0x0d characters by 0x0a) is to be performed on input data (that is, comments contents, PCDATA/CDATA contents and attribute values).
PUGIXML_DEPRECATED const unsigned
int 		parse_wnorm_attribute = 0x0040
 This flag determines if attribute value normalization should be performed for all attributes.
const unsigned int parse_wconv_attribute = 0x0080
 This flag determines if attribute value normalization should be performed for all attributes.
const unsigned int parse_declaration = 0x0100
 This flag determines if XML document declaration (this node has the form of <?xml .
const unsigned int parse_default = parse_cdata | parse_escapes | parse_wconv_attribute | parse_eol
 This is the default set of flags.
const unsigned int format_indent = 0x01
 Indent the nodes that are written to output stream with as many indentation strings as deep the node is in DOM tree.
const unsigned int format_write_bom = 0x02
 This flag determines if encoding-specific BOM is to be written to output stream.
PUGIXML_DEPRECATED const unsigned
int 		format_write_bom_utf8 = format_write_bom
const unsigned int format_raw = 0x04
 If this flag is on, no indentation is performed and no line breaks are written to output file.
const unsigned int format_no_declaration = 0x08
 If this flag is on, no default XML declaration is written to output file.
const unsigned int format_default = format_indent
 This is the default set of formatting flags.

Typedef Documentation

typedef void*(* pugi::allocation_function)(size_t size)
 

Memory allocation function.

Parameters:
size - allocation size
Returns:
pointer to allocated memory on success, NULL on failure

typedef void(* pugi::deallocation_function)(void *ptr)
 

Memory deallocation function.

Parameters:
ptr - pointer to memory previously allocated by allocation function

Enumeration Type Documentation

enum pugi::xml_node_type
 

Tree node classification.

Enumerator:
node_null  Undifferentiated entity.
node_document  A document tree's absolute root.
node_element  E.g. '<...>'.
node_pcdata  E.g. '>...<'.
node_cdata  E.g. '<![CDATA[...]]>'.
node_comment  E.g. ''.
node_pi  E.g. '<?...?>'.
node_declaration  E.g. '<?xml ...?>'.

enum pugi::encoding_t
 

These flags determine the encoding of input data for XML document.

Default mode is encoding_auto, which means that document encoding is autodetected from BOM and necessary encoding conversions are applied. You can override this mode by using any of the specific encodings.

Enumerator:
encoding_auto  Auto-detect input encoding using BOM or </<? detection; use UTF8 if BOM is not found.
encoding_utf8  UTF8 encoding.
encoding_utf16_le  Little-endian UTF16.
encoding_utf16_be  Big-endian UTF16.
encoding_utf16  UTF16 with native endianness.
encoding_utf32_le  Little-endian UTF32.
encoding_utf32_be  Big-endian UTF32.
encoding_utf32  UTF32 with native endianness.
encoding_wchar  The same encoding wchar_t has (either UTF16 or UTF32).

enum pugi::xpath_type_t
 

XPath query return type classification.

Enumerator:
xpath_type_none  Unknown type (query failed to compile).
xpath_type_node_set  Node set (xpath_node_set).
xpath_type_number  Number.
xpath_type_string  String.
xpath_type_boolean  Boolean.

enum pugi::xml_parse_status
 

Parsing status enumeration, returned as part of xml_parse_result struct.

Enumerator:
status_ok  No error.
status_file_not_found  File was not found during load_file().
status_io_error  Error reading from file/stream.
status_out_of_memory  Could not allocate memory.
status_internal_error  Internal error occured.
status_unrecognized_tag  Parser could not determine tag type.
status_bad_pi  Parsing error occured while parsing document declaration/processing instruction (<?...?>).
status_bad_comment  Parsing error occured while parsing comment ().
status_bad_cdata  Parsing error occured while parsing CDATA section (<![CDATA[...]]>).
status_bad_doctype  Parsing error occured while parsing document type declaration.
status_bad_pcdata  Parsing error occured while parsing PCDATA section (>...<).
status_bad_start_element  Parsing error occured while parsing start element tag (<name ...>).
status_bad_attribute  Parsing error occured while parsing element attribute.
status_bad_end_element  Parsing error occured while parsing end element tag (</name>).
status_end_element_mismatch  There was a mismatch of start-end tags (closing tag had incorrect name, some tag was not closed or there was an excessive closing tag).

Function Documentation

std::basic_string<char, std::char_traits<char>, std::allocator<char> > PUGIXML_FUNCTION pugi::as_utf8 (  const wchar_t *  str  ) 
 

Convert wide string to utf8.

Parameters:
str - input wide string string
Returns:
output UTF8 string

PUGIXML_DEPRECATED std::basic_string<wchar_t, std::char_traits<wchar_t>, std::allocator<wchar_t> > PUGIXML_FUNCTION pugi::as_utf16 (  const char *  str  ) 
 

Convert utf8 to wide string.

Parameters:
str - input UTF8 string
Returns:
output wide string string
Deprecated:
This function is deprecated and will be removed in future versions; use as_wide instead

std::basic_string<wchar_t, std::char_traits<wchar_t>, std::allocator<wchar_t> > PUGIXML_FUNCTION pugi::as_wide (  const char *  str  ) 
 

Convert utf8 to wide string.

Parameters:
str - input UTF8 string
Returns:
output wide string string

void PUGIXML_FUNCTION pugi::set_memory_management_functions (  allocation_function  allocate,
deallocation_function  deallocate
) 
 

Override default memory management functions.

All subsequent allocations/deallocations will be performed via supplied functions. Take care not to change memory management functions if any xml_document instances are still alive - this is considered undefined behaviour (expect crashes/memory damages/etc.).

Parameters:
allocate - allocation function
deallocate - deallocation function
Note:
XPath-related allocations, as well as allocations in functions that return std::string (xml_node::path, as_utf8, as_wide) are not performed via these functions.

If you're using parse() with ownership transfer, you have to allocate the buffer you pass to parse() with allocation function you set via this function.

allocation_function PUGIXML_FUNCTION pugi::get_memory_allocation_function (   ) 
 

Get current memory allocation function.

Returns:
memory allocation function
See also:
set_memory_management_functions

deallocation_function PUGIXML_FUNCTION pugi::get_memory_deallocation_function (   ) 
 

Get current memory deallocation function.

Returns:
memory deallocation function
See also:
set_memory_management_functions

Variable Documentation

const unsigned int pugi::parse_minimal = 0x0000
 

Minimal parsing mode.

Equivalent to turning all other flags off. This set of flags means that pugixml does not add pi/cdata sections or comments to DOM tree and does not perform any conversions for input data, meaning fastest parsing.

const unsigned int pugi::parse_pi = 0x0001
 

This flag determines if processing instructions (nodes with type node_pi; such nodes have the form of <? target content ?> or <? target ?> in XML) are to be put in DOM tree.

If this flag is off, they are not put in the tree, but are still parsed and checked for correctness.

The corresponding node in DOM tree will have type node_pi, name "target" and value "content", if any.

Note that <?xml ...?> (document declaration) is not considered to be a PI.

This flag is off by default.

const unsigned int pugi::parse_comments = 0x0002
 

This flag determines if comments (nodes with type node_comment; such nodes have the form of in XML) are to be put in DOM tree.

If this flag is off, they are not put in the tree, but are still parsed and checked for correctness.

The corresponding node in DOM tree will have type node_comment, empty name and value "content".

This flag is off by default.

const unsigned int pugi::parse_cdata = 0x0004
 

This flag determines if CDATA sections (nodes with type node_cdata; such nodes have the form of <![CDATA[[content]]> in XML) are to be put in DOM tree.

If this flag is off, they are not put in the tree, but are still parsed and checked for correctness.

The corresponding node in DOM tree will have type node_cdata, empty name and value "content".

This flag is on by default.

const unsigned int pugi::parse_ws_pcdata = 0x0008
 

This flag determines if nodes with PCDATA (regular text) that consist only of whitespace characters are to be put in DOM tree.

Often whitespace-only data is not significant for the application, and the cost of allocating and storing such nodes (both memory and speed-wise) can be significant. For example, after parsing XML string "<node> <a/> </node>", <node> element will have 3 children when parse_ws_pcdata is set (child with type node_pcdata and value=" ", child with type node_element and name "a", and another child with type node_pcdata and value=" "), and only 1 child when parse_ws_pcdata is not set.

This flag is off by default.

const unsigned int pugi::parse_escapes = 0x0010
 

This flag determines if character and entity references are to be expanded during the parsing process.

Character references are &#...; or &x...; (... is Unicode numeric representation of character in either decimal (&#...;) or hexadecimal (&x...;) form), entity references are &...; Note that as pugixml does not handle DTD, the only allowed entities are predefined ones - &lt;, &gt;, &amp;, &apos; and &quot;. If character/entity reference can not be expanded, it is leaved as is, so you can do additional processing later. Reference expansion is performed in attribute values and PCDATA content.

This flag is on by default.

const unsigned int pugi::parse_eol = 0x0020
 

This flag determines if EOL handling (that is, replacing sequences 0x0d 0x0a by a single 0x0a character, and replacing all standalone 0x0d characters by 0x0a) is to be performed on input data (that is, comments contents, PCDATA/CDATA contents and attribute values).

This flag is on by default.

PUGIXML_DEPRECATED const unsigned int pugi::parse_wnorm_attribute = 0x0040
 

This flag determines if attribute value normalization should be performed for all attributes.

This means, that: 1. Whitespace characters (new line, tab and space) are replaced with space (' ') 2. Afterwards sequences of spaces are replaced with a single space 3. Leading/trailing whitespace characters are trimmed

This flag is off by default.

Deprecated:
This flag is deprecated

const unsigned int pugi::parse_wconv_attribute = 0x0080
 

This flag determines if attribute value normalization should be performed for all attributes.

This means, that whitespace characters (new line, tab and space) are replaced with space (' '). Note, that the actions performed while this flag is on are also performed if parse_wnorm_attribute is on, so this flag has no effect if parse_wnorm_attribute flag is set.

This flag is on by default.

const unsigned int pugi::parse_declaration = 0x0100
 

This flag determines if XML document declaration (this node has the form of <?xml .

.. ?> in XML) are to be put in DOM tree. If this flag is off, it is not put in the tree, but is still parsed and checked for correctness.

The corresponding node in DOM tree will have type node_declaration, name "xml" and attributes, if any.

This flag is off by default.

const unsigned int pugi::parse_default = parse_cdata | parse_escapes | parse_wconv_attribute | parse_eol
 

This is the default set of flags.

It includes parsing CDATA sections (comments/PIs are not parsed), performing character and entity reference expansion, replacing whitespace characters with spaces in attribute values and performing EOL handling. Note, that PCDATA sections consisting only of whitespace characters are not parsed (by default) for performance reasons.

const unsigned int pugi::format_indent = 0x01
 

Indent the nodes that are written to output stream with as many indentation strings as deep the node is in DOM tree.

This flag is on by default.

const unsigned int pugi::format_write_bom = 0x02
 

This flag determines if encoding-specific BOM is to be written to output stream.

This flag is off by default.

PUGIXML_DEPRECATED const unsigned int pugi::format_write_bom_utf8 = format_write_bom
 

Deprecated:
This constant is deprecated and will be removed in future versions; use format_write_bom instead

const unsigned int pugi::format_raw = 0x04
 

If this flag is on, no indentation is performed and no line breaks are written to output file.

This means that the data is written to output stream as is.

This flag is off by default.

const unsigned int pugi::format_no_declaration = 0x08
 

If this flag is on, no default XML declaration is written to output file.

This means that there will be no XML declaration in output stream unless there was one in XML document (i.e. if it was parsed with parse_declaration flag).

This flag is off by default.

const unsigned int pugi::format_default = format_indent
 

This is the default set of formatting flags.

It includes indenting nodes depending on their depth in DOM tree.

Generated on Tue May 25 23:22:40 2010 for pugixml by  doxygen 1.4.6-NO