When a DOM modification function adds some nodes to the tree, the content of these nodes comes from values of arguments of the function. In the most common case, some generic entity is created from one or more arguments and the function adds the content of the entity into the appropriate place of the document. This process is regulated by a small set of very intuitive rules.

All data to be inserted are calculated before any modification of the document is started. For example it is safe to insert into the document a fragment of this document, even if it contains the point of insertion; such operation will never cause infinite loops.

If an instance of XMLType is passed then its internal XML entity is used.

If an argument is neither an XML entity nor a string then it is cast to the string first.

If an argument is NULL then it is fully ignored, as if there is no such argument at all.

A root node of a document can not be added into the tree of other document. Instead, every child node of the root (i.e. every top-level node of the document) is added to the target document, the order of child nodes will be preserved. An XML document usually contains only one top-level element node, but it also can contain comment and processing instruction nodes at top-level. Depending on the application, such comments and instructions may be inappropriate in the middle of the modified document. Thus it is worth to check what the application should insert: the root node with everything inside or only a top-level element node.

If some function accepts a list of arguments as list of values to be inserted, these values will be concatenated into a single generic entity. It is important to remember that the XML document can not contain two neighbour text nodes. If two consecutive arguments are strings then a single node that is a concatenation of these string is added. If the value of one argument is a string and the value of the next argument is a tree fragment that starts with a string then this pair of strings will also be replaced with a concatenation of these strings. When a function inserts a text after some existing text node of the XML document, no new node is created and the existing text node is replaced with the text node that is the concatenation of old and new texts.

In general, you should not expect that adding N values into the document will add N new nodes to the document. It can add a lesser number of nodes due to ignoring NULLs and concatenating some texts. It can also add a greater number of nodes if some values are root nodes with many children.