summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorArseny Kapoulkine <arseny.kapoulkine@gmail.com>2014-08-10 23:52:55 +0000
committerArseny Kapoulkine <arseny.kapoulkine@gmail.com>2014-08-10 23:52:55 +0000
commiteb3ca4e154d740ef5bdfdbcff80a1cb9ced80425 (patch)
tree17bdb5f4340dd7097e3b1faa711d4679fbaf46f5
parent54b68a32b4eb8216ed794f293c92b1e114b9dcad (diff)
docs: Add documentation for moving functions
git-svn-id: https://pugixml.googlecode.com/svn/trunk@1004 99668b35-9821-0410-8761-19e4c4f06640
-rw-r--r--docs/manual.qbk27
1 files changed, 27 insertions, 0 deletions
diff --git a/docs/manual.qbk b/docs/manual.qbk
index 12d85b0..2d13465 100644
--- a/docs/manual.qbk
+++ b/docs/manual.qbk
@@ -1368,6 +1368,27 @@ This is an example with one possible implementation of include tags in XML ([@sa
[endsect] [/clone]
+[section:move Moving nodes]
+
+[#xml_node::prepend_move][#xml_node::append_move][#xml_node::insert_move_after][#xml_node::insert_move_before]
+Sometimes instead of cloning a node you need to move an existing node to a different position in a tree. This can be accomplished by copying the node and removing the original; however, this is expensive since it results in a lot of extra operations. For moving nodes within the same document tree, you can use of the following functions instead:
+
+ xml_node xml_node::append_move(const xml_node& moved);
+ xml_node xml_node::prepend_move(const xml_node& moved);
+ xml_node xml_node::insert_move_after(const xml_node& moved, const xml_node& node);
+ xml_node xml_node::insert_move_before(const xml_node& moved, const xml_node& node);
+
+These functions mirror the structure of `append_copy`, `prepend_copy`, `insert_copy_before` and `insert_copy_after` - they take the handle to the moved object and move it to the appropriate place with all attributes and/or child nodes. The functions return the handle to the resulting object (which is the same as the moved object), or null handle on failure.
+
+The failure conditions resemble those of `append_child`, `insert_child_before` and related functions, [link xml_node::append_child consult their documentation for more information]. There are additional caveats specific to moving functions:
+
+* Moving null handles results in operation failure;
+* Moving is only possible for nodes that belong to the same document; attempting to move nodes between documents will fail.
+* `insert_move_after` and `insert_move_before` functions fail if the moved node is the same as the `node` argument (this operation would be a no-op otherwise).
+* It is impossible to move a subtree to a child of some node inside this subtree, i.e. `node.append_move(node.parent().parent());` will fail.
+
+[endsect] [/move]
+
[section:fragments Assembling document from fragments]
[#xml_node::append_buffer]
@@ -2440,6 +2461,12 @@ Classes:
* `xml_node `[link xml_node::insert_copy_before insert_copy_before]`(const xml_node& proto, const xml_node& node);`
[lbr]
+ * `xml_node `[link xml_node::append_move append_move]`(const xml_node& moved);`
+ * `xml_node `[link xml_node::prepend_move prepend_move]`(const xml_node& moved);`
+ * `xml_node `[link xml_node::insert_move_after insert_move_after]`(const xml_node& moved, const xml_node& node);`
+ * `xml_node `[link xml_node::insert_move_before insert_move_before]`(const xml_node& moved, const xml_node& node);`
+ [lbr]
+
* `bool `[link xml_node::remove_attribute remove_attribute]`(const xml_attribute& a);`
* `bool `[link xml_node::remove_attribute remove_attribute]`(const char_t* name);`
* `bool `[link xml_node::remove_child remove_child]`(const xml_node& n);`