From e383ce5d823a21bd82511ab9c10aa916fcc8cebd Mon Sep 17 00:00:00 2001 From: Arseny Kapoulkine Date: Sun, 19 Mar 2023 15:41:31 -0700 Subject: [PATCH] docs: Update HTML documentation --- docs/manual.html | 32 ++++++++++++++++++++++++++++++-- 1 file changed, 30 insertions(+), 2 deletions(-) diff --git a/docs/manual.html b/docs/manual.html index 01f233c..46bfc34 100644 --- a/docs/manual.html +++ b/docs/manual.html @@ -1807,7 +1807,7 @@ You should use the usual bitwise arithmetics to manipulate the bitmask: to enabl Since this flag significantly changes the DOM structure it is only recommended for parsing documents with many PCDATA nodes in memory-constrained environments. This flag is off by default.

  • -

    parse_fragment determines if document should be treated as a fragment of a valid XML. Parsing document as a fragment leads to top-level PCDATA content (i.e. text that is not located inside a node) to be added to a tree, and additionally treats documents without element nodes as valid and permits multiple top-level element nodes. This flag is off by default.

    +

    parse_fragment determines if document should be treated as a fragment of a valid XML. Parsing document as a fragment leads to top-level PCDATA content (i.e. text that is not located inside a node) to be added to a tree, and additionally treats documents without element nodes as valid and permits multiple top-level element nodes (currently multiple top-level element nodes are also permitted when the flag is off, but that behavior should not be relied on). This flag is off by default.

    • @@ -2207,6 +2207,31 @@ Since a lot of document traversal consists of finding the node/attribute with th 
    for (pugi::xml_node tool = tools.child("Tool"); tool; tool = tool.next_sibling("Tool"))
    +
    +

    attribute function needs to look for the target attribute by name. If a node has many attributes, finding each by name can be time consuming. If you have an idea of how attributes are ordered in the node, you can use a faster function:

    +
    +
    +
    +
    xml_attribute xml_node::attribute(const char_t* name, xml_attribute& hint) const;
    +
    +
    +
    +

    The extra hint argument is used to guess where the attribute might be, and is updated to the location of the next attribute so that if you search for multiple attributes in the right order, the performance is maximized. Note that hint has to be either null or has to belong to the node, otherwise the behavior is undefined.

    +
    +
    +

    You can use this function as follows:

    +
    +
    +
    +
    xml_attribute hint;
+xml_attribute id = node.attribute("id", hint);
+xml_attribute name = node.attribute("name", hint);
+xml_attribute version = node.attribute("version", hint);
    +
    +
    +
    +

    This code is correct regardless of the order of the attributes, but it’s faster if "id", "name" and "version" occur in that order.

    +

    Occasionally the needed node is specified not by the unique name but instead by the value of some attribute; for example, it is common to have node collections with each node having a unique id: <group><item id="1"/> <item id="2"/></group>. There are two functions for finding child nodes based on the attribute values:

    @@ -5781,6 +5806,9 @@ If exceptions are disabled, then in the event of parsing failure the query is in 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; + + xml_attribute attribute(const char_t* name, xml_attribute& hint) const; + xml_node find_child_by_attribute(const char_t* name, const char_t* attr_name, const char_t* attr_value) const; xml_node find_child_by_attribute(const char_t* attr_name, const char_t* attr_value) const; @@ -6067,7 +6095,7 @@ If exceptions are disabled, then in the event of parsing failure the query is in