summaryrefslogtreecommitdiff
path: root/src/pugixml.hpp
diff options
context:
space:
mode:
Diffstat (limited to 'src/pugixml.hpp')
-rw-r--r--src/pugixml.hpp1893
1 files changed, 329 insertions, 1564 deletions
diff --git a/src/pugixml.hpp b/src/pugixml.hpp
index 12b8f49..80fe6d8 100644
--- a/src/pugixml.hpp
+++ b/src/pugixml.hpp
@@ -81,228 +81,109 @@ namespace std
// Character interface macros
#ifdef PUGIXML_WCHAR_MODE
# define PUGIXML_TEXT(t) L ## t
-
-namespace pugi
-{
- /// Character type used for all internal storage and operations; depends on PUGIXML_WCHAR_MODE
- typedef wchar_t char_t;
-
-#ifndef PUGIXML_NO_STL
- /// String type used for operations that work with STL string; depends on PUGIXML_WCHAR_MODE
- typedef std::basic_string<wchar_t, std::char_traits<wchar_t>, std::allocator<wchar_t> > string_t;
-#endif
-}
+# define PUGIXML_CHAR wchar_t
#else
# define PUGIXML_TEXT(t) t
+# define PUGIXML_CHAR char
+#endif
namespace pugi
{
- /// Character type used for all internal storage and operations; depends on PUGIXML_WCHAR_MODE
- typedef char char_t;
+ // Character type used for all internal storage and operations; depends on PUGIXML_WCHAR_MODE
+ typedef PUGIXML_CHAR char_t;
-# ifndef PUGIXML_NO_STL
- // GCC 3.4 has a bug which prevents string_t instantiation using char_t, so we have to use char type explicitly
- /// String type used for operations that work with STL string; depends on PUGIXML_WCHAR_MODE
- typedef std::basic_string<char, std::char_traits<char>, std::allocator<char> > string_t;
-# endif
-}
+#ifndef PUGIXML_NO_STL
+ // String type used for operations that work with STL string; depends on PUGIXML_WCHAR_MODE
+ typedef std::basic_string<PUGIXML_CHAR, std::char_traits<PUGIXML_CHAR>, std::allocator<PUGIXML_CHAR> > string_t;
#endif
+}
-/// The PugiXML Parser namespace.
+// The PugiXML namespace
namespace pugi
{
- /// Tree node classification.
+ // Tree node types
enum xml_node_type
{
- 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 ...?>'
+ node_null, // Empty (null) node handle
+ node_document, // A document tree's absolute root
+ node_element, // Element tag, i.e. '<node/>'
+ node_pcdata, // Plain character data, i.e. 'text'
+ node_cdata, // Character data, i.e. '<![CDATA[text]]>'
+ node_comment, // Comment tag, i.e. '<!-- text -->'
+ node_pi, // Processing instruction, i.e. '<?name?>'
+ node_declaration // Document declaration, i.e. '<?xml version="1.0"?>'
};
// Parsing options
- /**
- * 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 parse_minimal = 0x0000;
-
- /**
- * 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 parse_pi = 0x0001;
-
- /**
- * This flag determines if comments (nodes with type node_comment; such nodes have the form of
- * <!-- 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_comment, empty name and value "content".
- *
- * This flag is off by default.
- */
- const unsigned int parse_comments = 0x0002;
-
- /**
- * 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 parse_cdata = 0x0004;
-
- /**
- * 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 parse_ws_pcdata = 0x0008;
-
- /**
- * This flag determines if character and entity references are to be expanded during the parsing
- * process. Character references are &amp;#...; or &amp;#x...; (... is Unicode numeric representation of
- * character in either decimal (&amp;#...;) or hexadecimal (&amp;#x...;) form), entity references are &amp;...;
- * Note that as pugixml does not handle DTD, the only allowed entities are predefined ones -
- * &amp;lt;, &amp;gt;, &amp;amp;, &amp;apos; and &amp;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 parse_escapes = 0x0010;
-
- /**
- * 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.
- */
- const unsigned int parse_eol = 0x0020;
+ // Minimal parsing mode (equivalent to turning all other flags off).
+ // Only elements and PCDATA sections are added to the DOM tree, no text conversions are performed.
+ const unsigned int parse_minimal = 0x0000;
+
+ // This flag determines if processing instructions (node_pi) are added to the DOM tree. This flag is off by default.
+ const unsigned int parse_pi = 0x0001;
+
+ // This flag determines if comments (node_comment) are added to the DOM tree. This flag is off by default.
+ const unsigned int parse_comments = 0x0002;
+
+ // This flag determines if CDATA sections (node_cdata) are added to the DOM tree. This flag is on by default.
+ const unsigned int parse_cdata = 0x0004;
+
+ // This flag determines if plain character data (node_pcdata) that consist only of whitespace are added to the DOM tree.
+ // This flag is off by default; turning it on usually results in slower parsing and more memory consumption.
+ const unsigned int parse_ws_pcdata = 0x0008;
+
+ // This flag determines if character and entity references are expanded during parsing. This flag is on by default.
+ const unsigned int parse_escapes = 0x0010;
+
+ // This flag determines if EOL characters are normalized (converted to #xA) during parsing. This flag is on by default.
+ const unsigned int parse_eol = 0x0020;
- /**
- * 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.
- */
- const unsigned int parse_wnorm_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.
- * New line characters are always treated as if parse_eol is set, i.e. \r\n is converted to single space.
- *
- * This flag is on by default.
- */
- const unsigned int parse_wconv_attribute = 0x0040;
+ // This flag determines if attribute values are normalized using CDATA normalization rules during parsing. This flag is on by default.
+ const unsigned int parse_wconv_attribute = 0x0040;
+
+ // This flag determines if attribute values are normalized using NMTOKENS normalization rules during parsing. This flag is off by default.
+ const unsigned int parse_wnorm_attribute = 0x0080;
- /**
- * 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 parse_declaration = 0x0100;
-
- /**
- * 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 parse_default = parse_cdata | parse_escapes | parse_wconv_attribute | parse_eol;
-
- /**
- * These flags determine the encoding of input data for XML document. Default mode is encoding_auto,
- * which means that document encoding is auto-detected from BOM and necessary encoding conversions are
- * applied. You can override this mode by using any of the specific encodings.
- */
+ // This flag determines if document declaration (node_declaration) is added to the DOM tree. This flag is off by default.
+ const unsigned int parse_declaration = 0x0100;
+
+ // The default parsing mode.
+ // Elements, PCDATA and CDATA sections are added to the DOM tree, character/reference entities are expanded,
+ // End-of-Line characters are normalized, attribute values are normalized using CDATA normalization rules.
+ const unsigned int parse_default = parse_cdata | parse_escapes | parse_wconv_attribute | parse_eol;
+
+ // These flags determine the encoding of input data for XML document
enum xml_encoding
{
- 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)
+ 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)
};
// Formatting flags
- /**
- * 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 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 format_indent = 0x01;
- /**
- * This flag determines if encoding-specific BOM is to be written to output stream.
- *
- * This flag is off by default.
- */
+ // Write encoding-specific BOM to the output stream. This flag is off by default.
const unsigned int format_write_bom = 0x02;
- /**
- * 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 format_raw = 0x04;
+ // Use raw output mode (no indentation and no line breaks are written). This flag is off by default.
+ const unsigned int format_raw = 0x04;
- /**
- * 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.
- */
+ // Omit default XML declaration even if there is no declaration in the document. This flag is off by default.
const unsigned int format_no_declaration = 0x08;
- /**
- * This is the default set of formatting flags. It includes indenting nodes depending on their
- * depth in DOM tree.
- */
- const unsigned int format_default = format_indent;
+ // The default set of formatting flags.
+ // Nodes are indented depending on their depth in DOM tree, a default declaration is output if document has none.
+ const unsigned int format_default = format_indent;
// Forward declarations
struct xml_attribute_struct;
@@ -322,38 +203,21 @@ namespace pugi
class xpath_variable_set;
#endif
- /**
- * Abstract writer class
- * \see xml_node::print
- */
+ // Writer interface for node printing (see xml_node::print)
class PUGIXML_CLASS xml_writer
{
public:
- /**
- * Virtual destructor
- */
virtual ~xml_writer() {}
- /**
- * Write memory chunk into stream/file/whatever
- *
- * \param data - data pointer
- * \param size - data size
- */
+ // Write memory chunk into stream/file/whatever
virtual void write(const void* data, size_t size) = 0;
};
- /** xml_writer implementation for FILE*
- * \see xml_writer
- */
+ // xml_writer implementation for FILE*
class PUGIXML_CLASS xml_writer_file: public xml_writer
{
public:
- /**
- * Construct writer instance
- *
- * \param file - this is FILE* object, void* is used to avoid header dependencies on stdio
- */
+ // Construct writer from a FILE* object; void* is used to avoid header dependencies on stdio
xml_writer_file(void* file);
virtual void write(const void* data, size_t size);
@@ -363,24 +227,12 @@ namespace pugi
};
#ifndef PUGIXML_NO_STL
- /** xml_writer implementation for streams
- * \see xml_writer
- */
+ // xml_writer implementation for streams
class PUGIXML_CLASS xml_writer_stream: public xml_writer
{
public:
- /**
- * Construct writer instance
- *
- * \param stream - output stream object
- */
+ // Construct writer from an output stream object
xml_writer_stream(std::basic_ostream<char, std::char_traits<char> >& stream);
-
- /**
- * Construct writer instance
- *
- * \param stream - output stream object
- */
xml_writer_stream(std::basic_ostream<wchar_t, std::char_traits<wchar_t> >& stream);
virtual void write(const void* data, size_t size);
@@ -391,11 +243,7 @@ namespace pugi
};
#endif
- /**
- * A light-weight wrapper for manipulating attributes in DOM tree.
- * Note: xml_attribute does not allocate any memory for the attribute it wraps; it only wraps a
- * pointer to existing attribute.
- */
+ // A light-weight handle for manipulating attributes in DOM tree
class PUGIXML_CLASS xml_attribute
{
friend class xml_attribute_iterator;
@@ -404,242 +252,67 @@ namespace pugi
private:
xml_attribute_struct* _attr;
- /// \internal Safe bool type
typedef xml_attribute_struct* xml_attribute::*unspecified_bool_type;
- /// \internal Initializing constructor
explicit xml_attribute(xml_attribute_struct* attr);
public:
- /**
- * Default constructor. Constructs an empty attribute.
- */
+ // Default constructor. Constructs an empty attribute.
xml_attribute();
- public:
- /**
- * Safe bool conversion.
- * Allows xml_node to be used in a context where boolean variable is expected, such as 'if (node)'.
- */
+ // Safe bool conversion operator
operator unspecified_bool_type() const;
// Borland C++ workaround
bool operator!() const;
- /**
- * Compare wrapped pointer to the attribute to the pointer that is wrapped by \a r.
- *
- * \param r - value to compare to
- * \return comparison result
- */
+ // Comparison operators (compares wrapped attribute pointers)
bool operator==(const xml_attribute& r) const;
-
- /**
- * Compare wrapped pointer to the attribute to the pointer that is wrapped by \a r.
- *
- * \param r - value to compare to
- * \return comparison result
- */
bool operator!=(const xml_attribute& r) const;
-
- /**
- * Compare wrapped pointer to the attribute to the pointer that is wrapped by \a r.
- *
- * \param r - value to compare to
- * \return comparison result
- */
bool operator<(const xml_attribute& r) const;
-
- /**
- * Compare wrapped pointer to the attribute to the pointer that is wrapped by \a r.
- *
- * \param r - value to compare to
- * \return comparison result
- */
bool operator>(const xml_attribute& r) const;
-
- /**
- * Compare wrapped pointer to the attribute to the pointer that is wrapped by \a r.
- *
- * \param r - value to compare to
- * \return comparison result
- */
bool operator<=(const xml_attribute& r) const;
-
- /**
- * Compare wrapped pointer to the attribute to the pointer that is wrapped by \a r.
- *
- * \param r - value to compare to
- * \return comparison result
- */
bool operator>=(const xml_attribute& r) const;
- public:
- /**
- * Get next attribute in attribute list of node that contains the attribute.
- *
- * \return next attribute, if any; empty attribute otherwise
- */
- xml_attribute next_attribute() const;
+ // Check if attribute is empty
+ bool empty() const;
- /**
- * Get previous attribute in attribute list of node that contains the attribute.
- *
- * \return previous attribute, if any; empty attribute otherwise
- */
- xml_attribute previous_attribute() const;
+ // Get attribute name/value, or "" if attribute is empty
+ const char_t* name() const;
+ const char_t* value() const;
- /**
- * Cast attribute value as int.
- *
- * \return attribute value as int, or 0 if conversion did not succeed or attribute is empty
- */
+ // Get attribute value as a number, or 0 if conversion did not succeed or attribute is empty
int as_int() const;
-
- /**
- * Cast attribute value as unsigned int.
- *
- * \return attribute value as unsigned int, or 0 if conversion did not succeed or attribute is empty
- * \note values out of non-negative int range (usually [0, 2^31-1]) get clamped to range boundaries
- */
unsigned int as_uint() const;
-
- /**
- * Cast attribute value as double.
- *
- * \return attribute value as double, or 0.0 if conversion did not succeed or attribute is empty
- */
double as_double() const;
-
- /**
- * Cast attribute value as float.
- *
- * \return attribute value as float, or 0.0f if conversion did not succeed or attribute is empty
- */
float as_float() const;
- /**
- * Cast attribute value as bool. Returns true for attributes with values that start with '1',
- * 't', 'T', 'y', 'Y', returns false for other attributes.
- *
- * \return attribute value as bool, or false if conversion did not succeed or attribute is empty
- */
+ // Get attribute value as bool (returns true if first character is in '1tTyY' set), or false if attribute is empty
bool as_bool() const;
- /// \internal Document order or 0 if not set
- const void* document_order() const;
-
- public:
- /**
- * Set attribute value to \a rhs.
- *
- * \param rhs - new attribute value
- * \return self
- */
- xml_attribute& operator=(const char_t* rhs);
-
- /**
- * Set attribute value to \a rhs.
- *
- * \param rhs - new attribute value
- * \return self
- */
- xml_attribute& operator=(int rhs);
-
- /**
- * Set attribute value to \a rhs.
- *
- * \param rhs - new attribute value
- * \return self
- */
- xml_attribute& operator=(unsigned int rhs);
-
- /**
- * Set attribute value to \a rhs.
- *
- * \param rhs - new attribute value
- * \return self
- */
- xml_attribute& operator=(double rhs);
-
- /**
- * Set attribute value to either 'true' or 'false' (depends on whether \a rhs is true or false).
- *
- * \param rhs - new attribute value
- * \return self
- */
- xml_attribute& operator=(bool rhs);
-
- /**
- * Set attribute name to \a rhs.
- *
- * \param rhs - new attribute name
- * \return success flag (call fails if attribute is empty or there is not enough memory)
- */
+ // Set attribute name/value (returns false if attribute is empty or there is not enough memory)
bool set_name(const char_t* rhs);
-
- /**
- * Set attribute value to \a rhs.
- *
- * \param rhs - new attribute value
- * \return success flag (call fails if attribute is empty or there is not enough memory)
- */
bool set_value(const char_t* rhs);
- /**
- * Set attribute value to \a rhs.
- *
- * \param rhs - new attribute value
- * \return success flag (call fails if attribute is empty or there is not enough memory)
- */
+ // Set attribute value with type conversion (numbers are converted to strings, boolean is converted to "true"/"false")
bool set_value(int rhs);
-
- /**
- * Set attribute value to \a rhs.
- *
- * \param rhs - new attribute value
- * \return success flag (call fails if attribute is empty or there is not enough memory)
- */
bool set_value(unsigned int rhs);
-
- /**
- * Set attribute value to \a rhs.
- *
- * \param rhs - new attribute value
- * \return success flag (call fails if attribute is empty or there is not enough memory)
- */
bool set_value(double rhs);
-
- /**
- * Set attribute value to either 'true' or 'false' (depends on whether \a rhs is true or false).
- *
- * \param rhs - new attribute value
- * \return success flag (call fails if attribute is empty or there is not enough memory)
- */
bool set_value(bool rhs);
- public:
- /**
- * Check if attribute is empty.
- *
- * \return true if attribute is empty, false otherwise
- */
- bool empty() const;
+ // Set attribute value (equivalent to set_value without error checking)
+ xml_attribute& operator=(const char_t* rhs);
+ xml_attribute& operator=(int rhs);
+ xml_attribute& operator=(unsigned int rhs);
+ xml_attribute& operator=(double rhs);
+ xml_attribute& operator=(bool rhs);
- public:
- /**
- * Get attribute name.
- *
- * \return attribute name, or "" if attribute is empty
- */
- const char_t* name() const;
+ // Get next/previous attribute in the attribute list of the parent node
+ xml_attribute next_attribute() const;
+ xml_attribute previous_attribute() const;
- /**
- * Get attribute value.
- *
- * \return attribute value, or "" if attribute is empty
- */
- const char_t* value() const;
+ // This function is for internal use
+ const void* document_order() const;
};
#ifdef __BORLANDC__
@@ -648,11 +321,7 @@ namespace pugi
bool PUGIXML_FUNCTION operator||(const xml_attribute& lhs, bool rhs);
#endif
- /**
- * A light-weight wrapper for manipulating nodes in DOM tree.
- * Note: xml_node does not allocate any memory for the node it wraps; it only wraps a pointer to
- * existing node.
- */
+ // A light-weight handle for manipulating nodes in DOM tree
class PUGIXML_CLASS xml_node
{
friend class xml_attribute_iterator;
@@ -661,411 +330,101 @@ namespace pugi
protected:
xml_node_struct* _root;
- /// \internal Safe bool type
typedef xml_node_struct* xml_node::*unspecified_bool_type;
- /// \internal Initializing constructor
explicit xml_node(xml_node_struct* p);
public:
- /**
- * Default constructor. Constructs an empty node.
- */
+ // Default constructor. Constructs an empty node.
xml_node();
- public:
- /**
- * Safe bool conversion.
- * Allows xml_node to be used in a context where boolean variable is expected, such as 'if (node)'.
- */
+ // Safe bool conversion operator
operator unspecified_bool_type() const;
// Borland C++ workaround
bool operator!() const;
- /**
- * Compare wrapped pointer to the attribute to the pointer that is wrapped by \a r.
- *
- * \param r - value to compare to
- * \return comparison result
- */
+ // Comparison operators (compares wrapped node pointers)
bool operator==(const xml_node& r) const;
-
- /**
- * Compare wrapped pointer to the attribute to the pointer that is wrapped by \a r.
- *
- * \param r - value to compare to
- * \return comparison result
- */
bool operator!=(const xml_node& r) const;
-
- /**
- * Compare wrapped pointer to the attribute to the pointer that is wrapped by \a r.
- *
- * \param r - value to compare to
- * \return comparison result
- */
bool operator<(const xml_node& r) const;
-
- /**
- * Compare wrapped pointer to the attribute to the pointer that is wrapped by \a r.
- *
- * \param r - value to compare to
- * \return comparison result
- */
bool operator>(const xml_node& r) const;
-
- /**
- * Compare wrapped pointer to the attribute to the pointer that is wrapped by \a r.
- *
- * \param r - value to compare to
- * \return comparison result
- */
bool operator<=(const xml_node& r) const;
-
- /**
- * Compare wrapped pointer to the attribute to the pointer that is wrapped by \a r.
- *
- * \param r - value to compare to
- * \return comparison result
- */
bool operator>=(const xml_node& r) const;
- public:
- /**
- * Node iterator type (for child nodes).
- * \see xml_node_iterator
- */
- typedef xml_node_iterator iterator;
-
- /**
- * Node iterator type (for child nodes).
- * \see xml_attribute_iterator
- */
- typedef xml_attribute_iterator attribute_iterator;
-
- /**
- * Access the begin iterator for this node's collection of child nodes.
- *
- * \return iterator that points to the first child node, or past-the-end iterator if node is empty or has no children
- */
- iterator begin() const;
-
- /**
- * Access the end iterator for this node's collection of child nodes.
- *
- * \return past-the-end iterator for child list
- */
- iterator end() const;
-
- /**
- * Access the begin iterator for this node's collection of attributes.
- *
- * \return iterator that points to the first attribute, or past-the-end iterator if node is empty or has no attributes
- */
- attribute_iterator attributes_begin() const;
-
- /**
- * Access the end iterator for this node's collection of attributes.
- *
- * \return past-the-end iterator for attribute list
- */
- attribute_iterator attributes_end() const;
-
- public:
- /**
- * Check if node is empty.
- *
- * \return true if node is empty, false otherwise
- */
+ // Check if node is empty.
bool empty() const;
- public:
- /**
- * Get node type
- *
- * \return node type; node_null for empty nodes
- */
+ // Get node type
xml_node_type type() const;
- /**
- * Get node name (element name for element nodes, PI target for PI)
- *
- * \return node name, if any; "" otherwise
- */
+ // Get node name/value, or "" if node is empty or it has no name/value
const char_t* name() const;
-
- /**
- * Get node value (comment/PI/PCDATA/CDATA contents, depending on node type)
- *
- * \return node value, if any; "" otherwise
- */
const char_t* value() const;
- /**
- * Get child with the specified name
- *
- * \param name - child name
- * \return child with the specified name, if any; empty node otherwise
- */
- xml_node child(const char_t* name) const;
-
- /**
- * Get attribute with the specified name
- *
- * \param name - attribute name
- * \return attribute with the specified name, if any; empty attribute otherwise
- */
- xml_attribute attribute(const char_t* name) const;
+ // Get attribute list
+ xml_attribute first_attribute() const;
+ xml_attribute last_attribute() const;
- /**
- * Get first of following sibling nodes with the specified name
- *
- * \param name - sibling name
- * \return node with the specified name, if any; empty node otherwise
- */
- xml_node next_sibling(const char_t* name) const;
+ // Get children list
+ xml_node first_child() const;
+ xml_node last_child() const;
- /**
- * Get following sibling
- *
- * \return following sibling node, if any; empty node otherwise
- */
+ // Get next/previous sibling in the children list of the parent node
xml_node next_sibling() const;
-
- /**
- * Get first of preceding sibling nodes with the specified name
- *
- * \param name - sibling name
- * \return node with the specified name, if any; empty node otherwise
- */
- xml_node previous_sibling(const char_t* name) const;
-
- /**
- * Get preceding sibling
- *
- * \return preceding sibling node, if any; empty node otherwise
- */
xml_node previous_sibling() const;
-
- /**
- * Get parent node
- *
- * \return parent node if any; empty node otherwise
- */
+
+ // Get parent node
xml_node parent() const;
- /**
- * Get root of DOM tree this node belongs to.
- *
- * \return tree root
- */
+ // Get root of DOM tree this node belongs to
xml_node root() const;
- /**
- * Get child value of current node; that is, value of the first child node of type PCDATA/CDATA
- *
- * \return child value of current node, if any; "" otherwise
- */
+ // Get child, attribute or next/previous sibling with the specified name
+ xml_node child(const char_t* name) const;
+ xml_attribute attribute(const char_t* name) const;
+ xml_node next_sibling(const char_t* name) const;
+ xml_node previous_sibling(const char_t* name) const;
+
+ // Get child value of current node; that is, value of the first child node of type PCDATA/CDATA
const char_t* child_value() const;
- /**
- * Get child value of child with specified name. \see child_value
- * node.child_value(name) is equivalent to node.child(name).child_value()
- *
- * \param name - child name
- * \return child value of specified child node, if any; "" otherwise
- */
+ // Get child value of child with specified name. Equivalent to child(name).child_value().
const char_t* child_value(const char_t* name) const;
- public:
- /**
- * Set node name to \a rhs (for PI/element nodes). \see name
- *
- * \param rhs - new node name
- * \return success flag (call fails if node is of the wrong type or there is not enough memory)
- */
+ // Set node name/value (returns false if node is empty, there is not enough memory, or node can not have name/value)
bool set_name(const char_t* rhs);
-
- /**
- * Set node value to \a rhs (for PI/PCDATA/CDATA/comment nodes). \see value
- *
- * \param rhs - new node value
- * \return success flag (call fails if node is of the wrong type or there is not enough memory)
- */
bool set_value(const char_t* rhs);
-
- /**
- * Add attribute with specified name (for element nodes)
- *
- * \param name - attribute name
- * \return added attribute, or empty attribute if there was an error (wrong node type)
- */
+
+ // Add attribute with specified name. Returns added attribute, or empty attribute on errors.
xml_attribute append_attribute(const char_t* name);
-
- /**
- * Insert attribute with specified name after \a attr (for element nodes)
- *
- * \param name - attribute name
- * \param attr - attribute to insert a new one after
- * \return inserted attribute, or empty attribute if there was an error (wrong node type, or attr does not belong to node)
- */
xml_attribute insert_attribute_after(const char_t* name, const xml_attribute& attr);
-
- /**
- * Insert attribute with specified name before \a attr (for element nodes)
- *
- * \param name - attribute name
- * \param attr - attribute to insert a new one before
- * \return inserted attribute, or empty attribute if there was an error (wrong node type, or attr does not belong to node)
- */
xml_attribute insert_attribute_before(const char_t* name, const xml_attribute& attr);
- /**
- * Add a copy of the specified attribute (for element nodes)
- *
- * \param proto - attribute prototype which is to be copied
- * \return inserted attribute, or empty attribute if there was an error (wrong node type)
- */
+ // Add a copy of the specified attribute. Returns added attribute, or empty attribute on errors.
xml_attribute append_copy(const xml_attribute& proto);
-
- /**
- * Insert a copy of the specified attribute after \a attr (for element nodes)
- *
- * \param proto - attribute prototype which is to be copied
- * \param attr - attribute to insert a new one after
- * \return inserted attribute, or empty attribute if there was an error (wrong node type, or attr does not belong to node)
- */
xml_attribute insert_copy_after(const xml_attribute& proto, const xml_attribute& attr);
-
- /**
- * Insert a copy of the specified attribute before \a attr (for element nodes)
- *
- * \param proto - attribute prototype which is to be copied
- * \param attr - attribute to insert a new one before
- * \return inserted attribute, or empty attribute if there was an error (wrong node type, or attr does not belong to node)
- */
xml_attribute insert_copy_before(const xml_attribute& proto, const xml_attribute& attr);
- /**
- * Add child node with specified type (for element nodes)
- *
- * \param type - node type
- * \return added node, or empty node if there was an error (wrong node type)
- */
+ // Add child node with specified type. Returns added node, or empty node on errors.
xml_node append_child(xml_node_type type = node_element);
-
- /**
- * Insert child node with specified type after \a node (for element nodes)
- *
- * \param type - node type
- * \param node - node to insert a new one after
- * \return inserted node, or empty node if there was an error (wrong node type, or \a node is not a child of this node)
- */
xml_node insert_child_after(xml_node_type type, const xml_node& node);
-
- /**
- * Insert child node with specified type before \a node (for element nodes)
- *
- * \param type - node type
- * \param node - node to insert a new one before
- * \return inserted node, or empty node if there was an error (wrong node type, or \a node is not a child of this node)
- */
xml_node insert_child_before(xml_node_type type, const xml_node& node);
- /**
- * Add a copy of the specified node as a child (for element nodes)
- *
- * \param proto - node prototype which is to be copied
- * \return inserted node, or empty node if there was an error (wrong node type)
- */
+ // Add a copy of the specified node as a child. Returns added node, or empty node on errors.
xml_node append_copy(const xml_node& proto);
-
- /**
- * Insert a copy of the specified node after \a node (for element nodes)
- *
- * \param proto - node prototype which is to be copied
- * \param node - node to insert a new one after
- * \return inserted node, or empty node if there was an error (wrong node type, or \a node is not a child of this node)
- */
xml_node insert_copy_after(const xml_node& proto, const xml_node& node);
-
- /**
- * Insert a copy of the specified node before \a node (for element nodes)
- *
- * \param proto - node prototype which is to be copied
- * \param node - node to insert a new one before
- * \return inserted node, or empty node if there was an error (wrong node type, or \a node is not a child of this node)
- */
xml_node insert_copy_before(const xml_node& proto, const xml_node& node);
- /**
- * Remove specified attribute
- *
- * \param a - attribute to be removed
- * \return success flag
- */
+ // Remove specified attribute
bool remove_attribute(const xml_attribute& a);
-
- /**
- * Remove attribute with the specified name, if any
- *
- * \param name - attribute name
- * \return success flag
- */
bool remove_attribute(const char_t* name);
- /**
- * Remove specified child
- *
- * \param n - child node to be removed
- * \return success flag
- */
+ // Remove specified child
bool remove_child(const xml_node& n);
-
- /**
- * Remove child with the specified name, if any
- *
- * \param name - child name
- * \return success flag
- */
bool remove_child(const char_t* name);
- public:
- /**
- * Get first attribute
- *
- * \return first attribute, if any; empty attribute otherwise
- */
- xml_attribute first_attribute() const;
-
- /**
- * Get last attribute
- *
- * \return last attribute, if any; empty attribute otherwise
- */
- xml_attribute last_attribute() const;
-
- /**
- * Get first child
- *
- * \return first child, if any; empty node otherwise
- */
- xml_node first_child() const;
-
- /**
- * Get last child
- *
- * \return last child, if any; empty node otherwise
- */
- xml_node last_child() const;
-
- /**
- * Find attribute using predicate
- *
- * \param pred - predicate, that takes xml_attribute and returns bool
- * \return first attribute for which predicate returned true, or empty attribute
- */
+ // Find attribute using predicate. Returns first attribute for which predicate returned true.
template <typename Predicate> xml_attribute find_attribute(Predicate pred) const
{
if (!_root) return xml_attribute();
@@ -1077,12 +436,7 @@ namespace pugi
return xml_attribute();
}
- /**
- * Find child node using predicate
- *
- * \param pred - predicate, that takes xml_node and returns bool
- * \return first child node for which predicate returned true, or empty node
- */
+ // Find child node using predicate. Returns first child for which predicate returned true.
template <typename Predicate> xml_node find_child(Predicate pred) const
{
if (!_root) return xml_node();
@@ -1094,12 +448,7 @@ namespace pugi
return xml_node();
}
- /**
- * Find node from subtree using predicate
- *
- * \param pred - predicate, that takes xml_node and returns bool
- * \return first node from subtree for which predicate returned true, or empty node
- */
+ // Find node from subtree using predicate. Returns first node from subtree (depth-first), for which predicate returned true.
template <typename Predicate> xml_node find_node(Predicate pred) const
{
if (!_root) return xml_node();
@@ -1123,136 +472,57 @@ namespace pugi
return xml_node();
}
- /**
- * Find child node with the specified name that has specified attribute
- *
- * \param name - child node name
- * \param attr_name - attribute name of child node
- * \param attr_value - attribute value of child node
- * \return first matching child node, or empty node
- */
+ // Find child node by attribute name/value
xml_node find_child_by_attribute(const char_t* name, const char_t* attr_name, const char_t* attr_value) const;
-
- /**
- * Find child node that has specified attribute
- *
- * \param attr_name - attribute name of child node
- * \param attr_value - attribute value of child node
- * \return first matching child node, or empty node
- */
xml_node find_child_by_attribute(const char_t* attr_name, const char_t* attr_value) const;
#ifndef PUGIXML_NO_STL
- /**
- * Get the absolute node path from root as a text string.
- *
- * \param delimiter - delimiter character to insert between element names
- * \return path string (e.g. '/bookstore/book/author').
- */
+ // Get the absolute node path from root as a text string.
string_t path(char_t delimiter = '/') const;
#endif
- /**
- * Search for a node by path.
- * \param path - path string; e.g. './foo/bar' (relative to node), '/foo/bar' (relative
- * to root), '../foo/bar'.
- * \param delimiter - delimiter character to use while tokenizing path
- * \return matching node, if any; empty node otherwise
- */
+ // Search for a node by path consisting of node names and . or .. elements.
xml_node first_element_by_path(const char_t* path, char_t delimiter = '/') const;
- /**
- * Recursively traverse subtree with xml_tree_walker
- * \see xml_tree_walker::begin
- * \see xml_tree_walker::for_each
- * \see xml_tree_walker::end
- *
- * \param walker - tree walker to traverse subtree with
- * \return traversal result
- */
+ // Recursively traverse subtree with xml_tree_walker
bool traverse(xml_tree_walker& walker);
#ifndef PUGIXML_NO_XPATH
- /**
- * Select single node by evaluating XPath query
- *
- * \param query - query string
- * \return first node from the resulting node set by document order, or empty node if none found
- */
+ // Select single node by evaluating XPath query. Returns first node from the resulting node set.
xpath_node select_single_node(const char_t* query, xpath_variable_set* variables = 0) const;
-
- /**
- * Select single node by evaluating XPath query
- *
- * \param query - compiled query
- * \return first node from the resulting node set by document order, or empty node if none found
- */
xpath_node select_single_node(const xpath_query& query) const;
- /**
- * Select node set by evaluating XPath query
- *
- * \param query - query string
- * \return resulting node set
- */
+ // Select node set by evaluating XPath query
xpath_node_set select_nodes(const char_t* query, xpath_variable_set* variables = 0) const;
-
- /**
- * Select node set by evaluating XPath query
- *
- * \param query - compiled query
- * \return resulting node set
- */
xpath_node_set select_nodes(const xpath_query& query) const;
#endif
- /// \internal Document order or 0 if not set
- const void* document_order() const;
-
- /**
- * Print subtree to writer
- *
- * \param writer - writer object
- * \param indent - indentation string
- * \param flags - formatting flags
- * \param encoding - encoding used for writing
- * \param depth - starting depth (used for indentation)
- */
+ // Print subtree using a writer object
void print(xml_writer& writer, const char_t* indent = PUGIXML_TEXT("\t"), unsigned int flags = format_default, xml_encoding encoding = encoding_auto, unsigned int depth = 0) const;
#ifndef PUGIXML_NO_STL
- /**
- * Print subtree to stream
- *
- * \param os - output stream
- * \param indent - indentation string
- * \param flags - formatting flags
- * \param encoding - encoding used for writing
- * \param depth - starting depth (used for indentation)
- */
+ // Print subtree to stream
void print(std::basic_ostream<char, std::char_traits<char> >& os, const char_t* indent = PUGIXML_TEXT("\t"), unsigned int flags = format_default, xml_encoding encoding = encoding_auto, unsigned int depth = 0) const;
-
- /**
- * Print subtree to stream
- *
- * \param os - output stream
- * \param indent - indentation string
- * \param flags - formatting flags
- * \param encoding - encoding used for writing
- * \param depth - starting depth (used for indentation)
- */
void print(std::basic_ostream<wchar_t, std::char_traits<wchar_t> >& os, const char_t* indent = PUGIXML_TEXT("\t"), unsigned int flags = format_default, unsigned int depth = 0) const;
#endif
- /**
- * Get node offset in parsed file/string (in bytes) for debugging purposes
- *
- * \return offset in bytes to start of node data, or -1 in case of error
- * \note This will return -1 if node information changed to the extent that it's no longer possible to calculate offset, for example
- * if element node name has significantly changed; this is guaranteed to return correct offset only for nodes that have not changed
- * since parsing.
- */
+ // Child nodes iterators
+ typedef xml_node_iterator iterator;
+
+ iterator begin() const;
+ iterator end() const;
+
+ // Attribute iterators
+ typedef xml_attribute_iterator attribute_iterator;
+
+ attribute_iterator attributes_begin() const;
+ attribute_iterator attributes_end() const;
+
+ // Get node offset in parsed file/string (in char_t units) for debugging purposes
ptrdiff_t offset_debug() const;
+
+ // This function is for internal use
+ const void* document_order() const;
};
#ifdef __BORLANDC__
@@ -1261,10 +531,7 @@ namespace pugi
bool PUGIXML_FUNCTION operator||(const xml_node& lhs, bool rhs);
#endif
- /**
- * Child node iterator.
- * It's a bidirectional iterator with value type 'xml_node'.
- */
+ // Child node iterator (a bidirectional iterator over a collection of xml_node)
class PUGIXML_CLASS xml_node_iterator
{
friend class xml_node;
@@ -1273,13 +540,10 @@ namespace pugi
xml_node _wrap;
xml_node _parent;
- /// \internal Initializing constructor
xml_node_iterator(xml_node_struct* ref, xml_node_struct* parent);
public:
- /**
- * Iterator traits
- */
+ // Iterator traits
typedef ptrdiff_t difference_type;
typedef xml_node value_type;
typedef xml_node* pointer;
@@ -1289,81 +553,27 @@ namespace pugi
typedef std::bidirectional_iterator_tag iterator_category;
#endif
- /**
- * Default constructor
- */
+ // Default constructor
xml_node_iterator();
- /**
- * Initializing constructor
- *
- * \param node - node that iterator will point at
- */
+ // Construct an iterator which points to the specified node
xml_node_iterator(const xml_node& node);
- /**
- * Check if this iterator is equal to \a rhs
- *
- * \param rhs - other iterator
- * \return comparison result
- */
+ // Iterator operators
bool operator==(const xml_node_iterator& rhs) const;
-
- /**
- * Check if this iterator is not equal to \a rhs
- *
- * \param rhs - other iterator
- * \return comparison result
- */
bool operator!=(const xml_node_iterator& rhs) const;
- /**
- * Dereferencing operator
- *
- * \return reference to the node iterator points at
- */
xml_node& operator*();
-
- /**
- * Member access operator
- *
- * \return pointer to the node iterator points at
- */
xml_node* operator->();
- /**
- * Pre-increment operator
- *
- * \return self
- */
const xml_node_iterator& operator++();
-
- /**
- * Post-increment operator
- *
- * \return old value
- */
xml_node_iterator operator++(int);
-
- /**
- * Pre-decrement operator
- *
- * \return self
- */
+
const xml_node_iterator& operator--();
-
- /**
- * Post-decrement operator
- *
- * \return old value
- */
xml_node_iterator operator--(int);
};
- /**
- * Attribute iterator.
- * It's a bidirectional iterator with value type 'xml_attribute'.
- */
+ // Attribute iterator (a bidirectional iterator over a collection of xml_attribute)
class PUGIXML_CLASS xml_attribute_iterator
{
friend class xml_node;
@@ -1372,13 +582,10 @@ namespace pugi
xml_attribute _wrap;
xml_node _parent;
- /// \internal Initializing constructor
xml_attribute_iterator(xml_attribute_struct* ref, xml_node_struct* parent);
public:
- /**
- * Iterator traits
- */
+ // Iterator traits
typedef ptrdiff_t difference_type;
typedef xml_attribute value_type;
typedef xml_attribute* pointer;
@@ -1388,82 +595,27 @@ namespace pugi
typedef std::bidirectional_iterator_tag iterator_category;
#endif
- /**
- * Default constructor
- */
+ // Default constructor
xml_attribute_iterator();
- /**
- * Initializing constructor
- *
- * \param attr - attribute that iterator will point at
- * \param parent - parent node of the attribute
- */
+ // Construct an iterator which points to the specified attribute
xml_attribute_iterator(const xml_attribute& attr, const xml_node& parent);
- /**
- * Check if this iterator is equal to \a rhs
- *
- * \param rhs - other iterator
- * \return comparison result
- */
+ // Iterator operators
bool operator==(const xml_attribute_iterator& rhs) const;
-
- /**
- * Check if this iterator is not equal to \a rhs
- *
- * \param rhs - other iterator
- * \return comparison result
- */
bool operator!=(const xml_attribute_iterator& rhs) const;
- /**
- * Dereferencing operator
- *
- * \return reference to the node iterator points at
- */
xml_attribute& operator*();
-
- /**
- * Member access operator
- *
- * \return pointer to the node iterator points at
- */
xml_attribute* operator->();
- /**
- * Pre-increment operator
- *
- * \return self
- */
const xml_attribute_iterator& operator++();
-
- /**
- * Post-increment operator
- *
- * \return old value
- */
xml_attribute_iterator operator++(int);
-
- /**
- * Pre-decrement operator
- *
- * \return self
- */
+
const xml_attribute_iterator& operator--();
-
- /**
- * Post-decrement operator
- *
- * \return old value
- */
xml_attribute_iterator operator--(int);
};
- /**
- * Abstract tree walker class
- * \see xml_node::traverse
- */
+ // Abstract tree walker class (see xml_node::traverse)
class PUGIXML_CLASS xml_tree_walker
{
friend class xml_node;
@@ -1472,110 +624,69 @@ namespace pugi
int _depth;
protected:
- /**
- * Get node depth
- *
- * \return node depth
- */
+ // Get current traversal depth
int depth() const;
public:
- /**
- * Default constructor
- */
xml_tree_walker();
-
- /**
- * Virtual destructor
- */
virtual ~xml_tree_walker();
- public:
- /**
- * Callback that is called when traversal of node begins.
- *
- * \return returning false will abort the traversal
- */
- virtual bool begin(xml_node&);
-
- /**
- * Callback that is called for each node traversed
- *
- * \return returning false will abort the traversal
- */
- virtual bool for_each(xml_node&) = 0;
-
- /**
- * Callback that is called when traversal of node ends.
- *
- * \return returning false will abort the traversal
- */
- virtual bool end(xml_node&);
- };
+ // Callback that is called when traversal begins
+ virtual bool begin(xml_node& node);
+
+ // Callback that is called for each node traversed
+ virtual bool for_each(xml_node& node) = 0;
- /**
- * Struct used to distinguish parsing with ownership transfer from parsing without it.
- * \see xml_document::parse
- */
- struct transfer_ownership_tag {};
+ // Callback that is called when traversal ends
+ virtual bool end(xml_node& node);
+ };
- /**
- * Parsing status enumeration, returned as part of xml_parse_result struct
- */
+ // Parsing status, returned as part of xml_parse_result object
enum xml_parse_status
{
- status_ok = 0, ///< 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 occurred
-
- status_unrecognized_tag, ///< Parser could not determine tag type
-
- status_bad_pi, ///< Parsing error occurred while parsing document declaration/processing instruction (<?...?>)
- status_bad_comment, ///< Parsing error occurred while parsing comment (<!--...-->)
- status_bad_cdata, ///< Parsing error occurred while parsing CDATA section (<![CDATA[...]]>)
- status_bad_doctype, ///< Parsing error occurred while parsing document type declaration
- status_bad_pcdata, ///< Parsing error occurred while parsing PCDATA section (>...<)
- status_bad_start_element, ///< Parsing error occurred while parsing start element tag (<name ...>)
- status_bad_attribute, ///< Parsing error occurred while parsing element attribute
- status_bad_end_element, ///< Parsing error occurred 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)
+ status_ok = 0, // 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 occurred
+
+ status_unrecognized_tag, // Parser could not determine tag type
+
+ status_bad_pi, // Parsing error occurred while parsing document declaration/processing instruction
+ status_bad_comment, // Parsing error occurred while parsing comment
+ status_bad_cdata, // Parsing error occurred while parsing CDATA section
+ status_bad_doctype, // Parsing error occurred while parsing document type declaration
+ status_bad_pcdata, // Parsing error occurred while parsing PCDATA section
+ status_bad_start_element, // Parsing error occurred while parsing start element tag
+ status_bad_attribute, // Parsing error occurred while parsing element attribute
+ status_bad_end_element, // Parsing error occurred while parsing end element tag
+ 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)
};
- /**
- * Parser result
- */
+ // Parsing result
struct PUGIXML_CLASS xml_parse_result
{
- /// Parsing status (\see xml_parse_status)
+ // Parsing status (see xml_parse_status)
xml_parse_status status;
- /// Last parsed offset (in bytes from file/string start)
+ // Last parsed offset (in char_t units from start of input data)
ptrdiff_t offset;
- /// Source document encoding
+ // Source document encoding
xml_encoding encoding;
- xml_parse_result(): status(status_internal_error), offset(0), encoding(encoding_auto)
- {
- }
+ // Default constructor, initializes object to failed state
+ xml_parse_result();
- /// Cast to bool operator
- operator bool() const
- {
- return status == status_ok;
- }
+ // Cast to bool operator
+ operator bool() const;
- /// Get error description
+ // Get error description
const char* description() const;
};
- /**
- * Document class (DOM tree root).
- * This class has non-copyable semantics (private copy constructor/assignment operator).
- */
+ // Document class (DOM tree root)
class PUGIXML_CLASS xml_document: public xml_node
{
private:
@@ -1583,6 +694,7 @@ namespace pugi
char _memory[192];
+ // Non-copyable semantics
xml_document(const xml_document&);
const xml_document& operator=(const xml_document&);
@@ -1593,184 +705,48 @@ namespace pugi
xml_parse_result load_buffer_impl(void* contents, size_t size, unsigned int options, xml_encoding encoding, bool is_mutable, bool own);
public:
- /**
- * Default constructor, makes empty document
- */
+ // Default constructor, makes empty document
xml_document();
- /**
- * Destructor
- */
+ // Destructor, invalidates all node/attribute handles to this document
~xml_document();
public:
#ifndef PUGIXML_NO_STL
- /**
- * Load document from stream.
- *
- * \param stream - stream with XML data
- * \param options - parsing options
- * \param encoding - source data encoding
- * \return parsing result
- */
+ // Load document from stream.
xml_parse_result load(std::basic_istream<char, std::char_traits<char> >& stream, unsigned int options = parse_default, xml_encoding encoding = encoding_auto);
-
- /**
- * Load document from stream.
- *
- * \param stream - stream with XML data
- * \param options - parsing options
- * \return parsing result
- */
xml_parse_result load(std::basic_istream<wchar_t, std::char_traits<wchar_t> >& stream, unsigned int options = parse_default);
#endif
- /**
- * Load document from string. String has to be zero-terminated. No encoding conversions are applied.
- *
- * \param contents - input string
- * \param options - parsing options
- * \return parsing result
- */
+ // Load document from zero-terminated string. No encoding conversions are applied.
xml_parse_result load(const char_t* contents, unsigned int options = parse_default);
- /**
- * Parse the given XML string in-situ.
- * The string is modified; you should ensure that string data will persist throughout the
- * document's lifetime. Although, document does not gain ownership over the string, so you
- * should free the memory occupied by it manually.
- *
- * \param xmlstr - read/write string with XML data
- * \param options - parsing options
- * \return parsing result
- *
- * \deprecated This function is deprecated and will be removed in future versions; use xml_document::load_buffer_inplace instead
- */
- PUGIXML_DEPRECATED xml_parse_result parse(char* xmlstr, unsigned int options = parse_default);
-
- /**
- * Parse the given XML string in-situ (gains ownership).
- * The string is modified; document gains ownership over the string, so you don't have to worry
- * about it's lifetime.
- * Call example: doc.parse(transfer_ownership_tag(), string, options);
- *
- * \param xmlstr - read/write string with XML data
- * \param options - parsing options
- * \return parsing result
- *
- * \deprecated This function is deprecated and will be removed in future versions; use xml_document::load_buffer_inplace_own instead
- */
- PUGIXML_DEPRECATED xml_parse_result parse(const transfer_ownership_tag&, char* xmlstr, unsigned int options = parse_default);
-
- /**
- * Load document from file
- *
- * \param path - file path
- * \param options - parsing options
- * \param encoding - source data encoding
- * \return parsing result
- */
+ // Load document from file
xml_parse_result load_file(const char* path, unsigned int options = parse_default, xml_encoding encoding = encoding_auto);
-
- /**
- * Load document from file
- *
- * \param path - file path
- * \param options - parsing options
- * \param encoding - source data encoding
- * \return parsing result
- */
xml_parse_result load_file(const wchar_t* path, unsigned int options = parse_default, xml_encoding encoding = encoding_auto);
- /**
- * Load document from buffer
- *
- * \param contents - buffer contents
- * \param size - buffer size in bytes
- * \param options - parsing options
- * \param encoding - source data encoding
- * \return parsing result
- */
+ // Load document from buffer. Copies/converts the buffer, so it may be deleted or changed after the function returns.
xml_parse_result load_buffer(const void* contents, size_t size, unsigned int options = parse_default, xml_encoding encoding = encoding_auto);
- /**
- * Load document from buffer in-situ.
- * The buffer is modified; you should ensure that buffer data will persist throughout the document's
- * lifetime. Document does not gain ownership over the buffer, so you should free the buffer memory manually.
- *
- * \param contents - buffer contents
- * \param size - buffer size in bytes
- * \param options - parsing options
- * \param encoding - source data encoding
- * \return parsing result
- */
+ // Load document from buffer, using the buffer for in-place parsing (the buffer is modified and used for storage of document data).
+ // You should ensure that buffer data will persist throughout the document's lifetime, and free the buffer memory manually once document is destroyed.
xml_parse_result load_buffer_inplace(void* contents, size_t size, unsigned int options = parse_default, xml_encoding encoding = encoding_auto);
- /**
- * Load document from buffer in-situ (gains buffer ownership).
- * The buffer is modified; you should ensure that buffer data will persist throughout the document's
- * lifetime. Document gains ownership over the buffer, so you should allocate the buffer with pugixml
- * allocation function.
- *
- * \param contents - buffer contents
- * \param size - buffer size in bytes
- * \param options - parsing options
- * \param encoding - source data encoding
- * \return parsing result
- */
+ // Load document from buffer, using the buffer for in-place parsing (the buffer is modified and used for storage of document data).
+ // You should allocate the buffer with pugixml allocation function; document will free the buffer when it is no longer needed (you can't use it anymore).
xml_parse_result load_buffer_inplace_own(void* contents, size_t size, unsigned int options = parse_default, xml_encoding encoding = encoding_auto);
- /**
- * Save XML to writer
- *
- * \param writer - writer object
- * \param indent - indentation string
- * \param flags - formatting flags
- * \param encoding - encoding used for writing
- */
+ // Save XML document to writer (semantics is slightly different from xml_node::print, see documentation for details).
void save(xml_writer& writer, const char_t* indent = PUGIXML_TEXT("\t"), unsigned int flags = format_default, xml_encoding encoding = encoding_auto) const;
#ifndef PUGIXML_NO_STL
- /**
- * Save XML to stream
- *
- * \param stream - output stream
- * \param indent - indentation string
- * \param flags - formatting flags
- * \param encoding - encoding used for writing
- */
+ // Save XML document to stream (semantics is slightly different from xml_node::print, see documentation for details).
void save(std::basic_ostream<char, std::char_traits<char> >& stream, const char_t* indent = PUGIXML_TEXT("\t"), unsigned int flags = format_default, xml_encoding encoding = encoding_auto) const;
-
- /**
- * Save XML to stream
- *
- * \param stream - output stream
- * \param indent - indentation string
- * \param flags - formatting flags
- */
void save(std::basic_ostream<wchar_t, std::char_traits<wchar_t> >& stream, const char_t* indent = PUGIXML_TEXT("\t"), unsigned int flags = format_default) const;
#endif
- /**
- * Save XML to file
- *
- * \param path - file path
- * \param indent - indentation string
- * \param flags - formatting flags
- * \param encoding - encoding used for writing
- * \return success flag
- */
+ // Save XML to file
bool save_file(const char* path, const char_t* indent = PUGIXML_TEXT("\t"), unsigned int flags = format_default, xml_encoding encoding = encoding_auto) const;
-
- /**
- * Save XML to file
- *
- * \param path - file path
- * \param indent - indentation string
- * \param flags - formatting flags
- * \param encoding - encoding used for writing
- * \return success flag
- */
bool save_file(const wchar_t* path, const char_t* indent = PUGIXML_TEXT("\t"), unsigned int flags = format_default, xml_encoding encoding = encoding_auto) const;
};
@@ -1778,198 +754,155 @@ namespace pugi
class xpath_ast_node;
class xpath_allocator;
- /// XPath query return type classification
+ // XPath query return type
enum xpath_value_type
{
- 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
+ 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
};
+ // XPath parsing result
struct PUGIXML_CLASS xpath_parse_result
{
- /// Error message (0 if no error)
+ // Error message (0 if no error)
const char* error;
- /// Last parsed offset (in characters from string start)
+ // Last parsed offset (in char_t units from string start)
ptrdiff_t offset;
- xpath_parse_result(): error("Internal error"), offset(0)
- {
- }
+ // Default constructor, initializes object to failed state
+ xpath_parse_result();
- /// Cast to bool operator
- operator bool() const
- {
- return error == 0;
- }
+ // Cast to bool operator
+ operator bool() const;
- /// Get error description
+ // Get error description
const char* description() const;
};
- /**
- * A class that holds XPath variable
- */
+ // A single XPath variable
class PUGIXML_CLASS xpath_variable
{
friend class xpath_variable_set;
protected:
- // Non-copyable semantics
- xpath_variable(const xpath_variable&);
- xpath_variable& operator=(const xpath_variable&);
-
xpath_value_type _type;
xpath_variable* _next;
- xpath_variable() {}
- ~xpath_variable() {}
+ xpath_variable();
+ // Non-copyable semantics
+ xpath_variable(const xpath_variable&);
+ xpath_variable& operator=(const xpath_variable&);
+
public:
+ // Get variable name
const char_t* name() const;
+
+ // Get variable type
xpath_value_type type() const;
+ // Get variable value; no type conversion is performed, default value (false, NaN, empty string, empty node set) is returned on type mismatch error
bool get_boolean() const;
double get_number() const;
const char_t* get_string() const;
const xpath_node_set& get_node_set() const;
+ // Set variable value; no type conversion is performed, false is returned on type mismatch error
bool set(bool value);
bool set(double value);
bool set(const char_t* value);
bool set(const xpath_node_set& value);
};
- /**
- * A class that holds XPath variables
- */
+ // A set of XPath variables
class PUGIXML_CLASS xpath_variable_set
{
private:
+ xpath_variable* _data[64];
+
// Non-copyable semantics
xpath_variable_set(const xpath_variable_set&);
xpath_variable_set& operator=(const xpath_variable_set&);
- xpath_variable* _data[64];
-
xpath_variable* find(const char_t* name) const;
public:
+ // Default constructor/destructor
xpath_variable_set();
~xpath_variable_set();
+ // Add a new variable or get the existing one, if the types match
xpath_variable* add(const char_t* name, xpath_value_type type);
+ // Set value of an existing variable; no type conversion is performed, false is returned if there is no such variable or if types mismatch
bool set(const char_t* name, bool value);
bool set(const char_t* name, double value);
bool set(const char_t* name, const char_t* value);
bool set(const char_t* name, const xpath_node_set& value);
+ // Get existing variable by name
xpath_variable* get(const char_t* name);
const xpath_variable* get(const char_t* name) const;
};
- /**
- * A class that holds compiled XPath query and allows to evaluate query result
- */
+ // A compiled XPath query object
class PUGIXML_CLASS xpath_query
{
private:
- // Non-copyable semantics
- xpath_query(const xpath_query&);
- xpath_query& operator=(const xpath_query&);
-
xpath_allocator* _alloc;
xpath_ast_node* _root;
xpath_parse_result _result;
- /// \internal Safe bool type
typedef xpath_ast_node* xpath_query::*unspecified_bool_type;
+ // Non-copyable semantics
+ xpath_query(const xpath_query&);
+ xpath_query& operator=(const xpath_query&);
+
public:
- /**
- * Constructor from string with XPath expression.
- * Throws xpath_exception on compilation error, std::bad_alloc on out of memory error.
- *
- * \param query - string with XPath expression
- */
+ // Construct a compiled object from XPath expression.
+ // If PUGIXML_NO_EXCEPTIONS is not defined, throws xpath_exception on compilation errors.
explicit xpath_query(const char_t* query, xpath_variable_set* variables = 0);
- /**
- * Destructor
- */
+ // Destructor
~xpath_query();
- /**
- * Get query expression return type
- *
- * \return expression return type
- **/
+ // Get query expression return type
xpath_value_type return_type() const;
- /**
- * Evaluate expression as boolean value for the context node \a n.
- * If expression does not directly evaluate to boolean, the expression result is converted
- * as through boolean() XPath function call.
- * Throws std::bad_alloc on out of memory error.
- *
- * \param n - context node
- * \return evaluation result
- */
+ // Evaluate expression as boolean value in the specified context; performs type conversion if necessary.
+ // If PUGIXML_NO_EXCEPTIONS is not defined, throws std::bad_alloc on out of memory errors.
bool evaluate_boolean(const xpath_node& n) const;
- /**
- * Evaluate expression as double value for the context node \a n.
- * If expression does not directly evaluate to double, the expression result is converted
- * as through number() XPath function call.
- * Throws std::bad_alloc on out of memory error.
- *
- * \param n - context node
- * \return evaluation result
- */
+ // Evaluate expression as double value in the specified context; performs type conversion if necessary.
+ // If PUGIXML_NO_EXCEPTIONS is not defined, throws std::bad_alloc on out of memory errors.
double evaluate_number(const xpath_node& n) const;
#ifndef PUGIXML_NO_STL
- /**
- * Evaluate expression as string value for the context node \a n.
- * If expression does not directly evaluate to string, the expression result is converted
- * as through string() XPath function call.
- * Throws std::bad_alloc on out of memory error.
- *
- * \param n - context node
- * \return evaluation result
- */
+ // Evaluate expression as string value in the specified context; performs type conversion if necessary.
+ // If PUGIXML_NO_EXCEPTIONS is not defined, throws std::bad_alloc on out of memory errors.
string_t evaluate_string(const xpath_node& n) const;
#endif
- /**
- * Evaluate expression as string value for the context node \a n.
- * If expression does not directly evaluate to string, the expression result is converted
- * as through string() XPath function call.
- * Throws std::bad_alloc on out of memory error.
- *
- * \param n - context node
- * \return evaluation result
- */
+ // Evaluate expression as string value in the specified context; performs type conversion if necessary.
+ // At most capacity characters are written to the destination buffer, full result size is returned (includes terminating zero).
+ // If PUGIXML_NO_EXCEPTIONS is not defined, throws std::bad_alloc on out of memory errors.
+ // If PUGIXML_NO_EXCEPTIONS is defined, returns empty set instead.
size_t evaluate_string(char_t* buffer, size_t capacity, const xpath_node& n) const;
- /**
- * Evaluate expression as node set for the context node \a n.
- * If expression does not directly evaluate to node set, throws xpath_exception.
- * Throws std::bad_alloc on out of memory error.
- *
- * \param n - context node
- * \return evaluation result
- */
+ // Evaluate expression as node set in the specified context.
+ // If PUGIXML_NO_EXCEPTIONS is not defined, throws xpath_exception on type mismatch and std::bad_alloc on out of memory errors.
+ // If PUGIXML_NO_EXCEPTIONS is defined, returns empty node set instead.
xpath_node_set evaluate_node_set(const xpath_node& n) const;
- // Get parsing result
+ // Get parsing result (used to get compilation errors in PUGIXML_NO_EXCEPTIONS mode)
const xpath_parse_result& result() const;
- // Safe bool conversion
+ // Safe bool conversion operator
operator unspecified_bool_type() const;
// Borland C++ workaround
@@ -1977,112 +910,56 @@ namespace pugi
};
#ifndef PUGIXML_NO_EXCEPTIONS
- /**
- * XPath exception class.
- */
+ // XPath exception class
class PUGIXML_CLASS xpath_exception: public std::exception
{
private:
xpath_parse_result _result;
public:
- /**
- * Construct exception from parse result
- *
- */
+ // Construct exception from parse result
explicit xpath_exception(const xpath_parse_result& result);
- /**
- * Return error message
- *
- * \return error message
- */
+ // Get error message
virtual const char* what() const throw();
+ // Get parse result
const xpath_parse_result& result() const;
};
#endif
- /**
- * XPath node class.
- *
- * XPath defines node to be either xml_node or xml_attribute in pugixml terminology, so xpath_node
- * is either xml_node or xml_attribute.
- */
+ // XPath node class (either xml_node or xml_attribute)
class PUGIXML_CLASS xpath_node
{
private:
xml_node _node;
xml_attribute _attribute;
- /// \internal Safe bool type
typedef xml_node xpath_node::*unspecified_bool_type;
public:
- /**
- * Construct empty XPath node
- */
+ // Default constructor; constructs empty XPath node
xpath_node();
- /**
- * Construct XPath node from XML node
- *
- * \param node - XML node
- */
+ // Construct XPath node from XML node/attribute
xpath_node(const xml_node& node);
-
- /**
- * Construct XPath node from XML attribute
- *
- * \param attribute - XML attribute
- * \param parent - attribute's parent node
- */
xpath_node(const xml_attribute& attribute, const xml_node& parent);
- /**
- * Get XML node, if any
- *
- * \return contained XML node, empty node otherwise
- */
+ // Get node/attribute, if any
xml_node node() const;
-
- /**
- * Get XML attribute, if any
- *
- * \return contained XML attribute, if any, empty attribute otherwise
- */
xml_attribute attribute() const;
- /**
- * Get parent of contained XML attribute, if any
- *
- * \return parent of contained XML attribute, if any, empty node otherwise
- */
+ // Get parent of contained node/attribute
xml_node parent() const;
- /**
- * Safe bool conversion.
- * Allows xpath_node to be used in a context where boolean variable is expected, such as 'if (node)'.
- */
+ // Safe bool conversion operator
operator unspecified_bool_type() const;
// Borland C++ workaround
bool operator!() const;
- /**
- * Compares two XPath nodes
- *
- * \param n - XPath node to compare to
- * \return comparison result
- */
+ // Comparison operators
bool operator==(const xpath_node& n) const;
-
- /**
- * Compares two XPath nodes
- *
- * \param n - XPath node to compare to
- * \return comparison result
- */
bool operator!=(const xpath_node& n) const;
};
@@ -2092,199 +969,87 @@ namespace pugi
bool PUGIXML_FUNCTION operator||(const xpath_node& lhs, bool rhs);
#endif
- /**
- * Not necessarily ordered constant collection of XPath nodes
- */
+ // A fixed-size collection of XPath nodes
class PUGIXML_CLASS xpath_node_set
{
public:
- /// Collection type
+ // Collection type
enum type_t
{
- type_unsorted, ///< Not ordered
- type_sorted, ///< Sorted by document order (ascending)
- type_sorted_reverse ///< Sorted by document order (descending)
+ type_unsorted, // Not ordered
+ type_sorted, // Sorted by document order (ascending)
+ type_sorted_reverse // Sorted by document order (descending)
};
- /// Constant iterator type
+ // Constant iterator type
typedef const xpath_node* const_iterator;
- private:
- type_t _type;
-
- xpath_node _storage;
-
- xpath_node* _begin;
- xpath_node* _end;
-
- void _assign(const_iterator begin, const_iterator end);
-
- public:
- /**
- * Default constructor
- * Constructs empty set
- */
+ // Default constructor. Constructs empty set.
xpath_node_set();
- /**
- * Constructor from contents
- */
+ // Constructs a set from iterator range; data is not checked for duplicates and is not sorted according to provided type, so be careful
xpath_node_set(const_iterator begin, const_iterator end, type_t type = type_unsorted);
- /**
- * Destructor
- */
+ // Destructor
~xpath_node_set();
- /**
- * Copy constructor
- *
- * \param ns - set to copy
- */
+ // Copy constructor/assignment operator
xpath_node_set(const xpath_node_set& ns);
-
- /**
- * Assignment operator
- *
- * \param ns - set to assign
- * \return self
- */
xpath_node_set& operator=(const xpath_node_set& ns);
- /**
- * Get collection type
- *
- * \return collection type
- */
+ // Get collection type
type_t type() const;
- /**
- * Get collection size
- *
- * \return collection size
- */
+ // Get collection size
size_t size() const;
- /**
- * Get element with the specified index
- *
- * \param index - requested index
- * \return element
- */
+ // Indexing operator
const xpath_node& operator[](size_t index) const;
- /**
- * Get begin constant iterator for collection
- *
- * \return begin constant iterator
- */
+ // Collection iterators
const_iterator begin() const;
-
- /**
- * Get end iterator for collection
- *
- * \return end iterator
- */
const_iterator end() const;
-
- /**
- * Sort the collection in ascending/descending order by document order
- *
- * \param reverse - whether to sort in ascending (false) or descending (true) order
- */
+
+ // Sort the collection in ascending/descending order by document order
void sort(bool reverse = false);
- /**
- * Get first node in the collection by document order
- *
- * \return first node by document order
- * \note set.first() is not equal to set[0], since operator[] does not take document order into account
- */
+ // Get first node in the collection by document order
xpath_node first() const;
- /**
- * Return true if collection is empty
- *
- * \return true if collection is empty, false otherwise
- */
+ // Check if collection is empty
bool empty() const;
+
+ private:
+ type_t _type;
+
+ xpath_node _storage;
+
+ xpath_node* _begin;
+ xpath_node* _end;
+
+ void _assign(const_iterator begin, const_iterator end);
};
#endif
#ifndef PUGIXML_NO_STL
- /**
- * Convert wide string to UTF8
- *
- * \param str - input wide string string
- * \return output UTF8 string
- */
+ // Convert wide string to UTF8
std::basic_string<char, std::char_traits<char>, std::allocator<char> > PUGIXML_FUNCTION as_utf8(const wchar_t* str);
- /**
- * Convert UTF8 to wide string
- *
- * \param str - input UTF8 string
- * \return output wide string string
- *
- * \deprecated This function is deprecated and will be removed in future versions; use as_wide instead
- */
- 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
- *
- * \param str - input UTF8 string
- * \return output wide string string
- */
+ // 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);
#endif
- /**
- * Memory allocation function
- *
- * \param size - allocation size
- * \return pointer to allocated memory on success, NULL on failure
- */
+ // Memory allocation function interface; returns pointer to allocated memory or NULL on failure
typedef void* (*allocation_function)(size_t size);
- /**
- * Memory deallocation function
- *
- * \param ptr - pointer to memory previously allocated by allocation function
- */
+ // Memory deallocation function interface
typedef void (*deallocation_function)(void* ptr);
- /**
- * 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.).
- *
- * \param allocate - allocation function
- * \param 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.
- * \note 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.
- */
+ // Override default memory management functions. All subsequent allocations/deallocations will be performed via supplied functions.
void PUGIXML_FUNCTION set_memory_management_functions(allocation_function allocate, deallocation_function deallocate);
- /**
- * Get current memory allocation function
- *
- * \return memory allocation function
- * \see set_memory_management_functions
- */
+ // Get current memory management functions
allocation_function PUGIXML_FUNCTION get_memory_allocation_function();
-
- /**
- * Get current memory deallocation function
- *
- * \return memory deallocation function
- * \see set_memory_management_functions
- */
deallocation_function PUGIXML_FUNCTION get_memory_deallocation_function();
}