saxon:new-element

Returns a new element node, with given name and content.

new-element($name as union(xs:QName, xs:string), $content as item()*) ➔ document-node()

Arguments

 

$name

union(xs:QName, xs:string)

The name of the new element

 

$content

item()*

The content of the new element

Result

document-node()

Namespace

http://saxon.sf.net/

Saxon availability

Requires Saxon-PE or Saxon-EE. Implemented since Saxon 10.

Notes on the Saxon implementation

Available since Saxon 10.

Details

This function constructs a new parentless element node.

The name of the element node is determined by the first argument. This may be supplied either as an instance of either xs:string or xs:QName.

The name of the element may be supplied in a number of ways:

  • The first argument may be an xs:QName, in which case the element's name will have the prefix, namespace URI, and local name supplied in this QName.
  • The first argument may be an xs:string, that conforms to the rules for a valid xs:NCName. The element's name will have this local part, with no namespace URI or prefix.
  • The first argument may be an xs:string in the format Q{uri}local. The element's local name and namespace URI will be taken from this value, and the name will have no prefix (that is, the URI will be the default namespace).
  • The first argument may be an xs:string in the format prefix:local. In this case the the prefix must be declared in the static context of the function call, and the element's name will use this prefix and local name, together with the namespace URI associated with this prefix in the static context.

The content of the element node (that is, the children of the node) is formed by evaluating the second argument, and applying the rules given in the XSLT 3.0 specification section 5.7.1, Constructing Complex Content.

The base URI of the new element node is taken from the static base URI of the calling expression.

The type annotation of the new element node will be xs:untyped.

Namespace fixup is applied to the new element as described in the XSLT 3.0 specification to ensure that all namespaces used in element and attribute names are properly declared.

If the function is called twice with the same arguments, it is unpredictable whether it returns the same element node or different element nodes from the two invocations.

Notes:

  1. These rules are similar to the XQuery rules for the element {...} expression. However, there are some differences. Most notably, the XSLT rules allow multiple attribute nodes with the same name to appear in the content sequence (the last one wins). Furthermore, the error codes used for invalid conditions (such as the presence of maps or functions or conflicting namespace nodes in the content) are those given in the XSLT 3.0 specification.

  2. Any attribute nodes in the content sequence become attributes of the constructed element; they are not atomized to form text nodes.

  3. Since the declared type of the first argument is namespace sensitive, error XPTY0117 will be raised if an untyped atomic value (or an untyped node) is supplied as the actual argument. Conversion to a string should therefore be done explicitly. For example, to convert <prop name="x" value="y"/> to <x>y</x>, use saxon:new-element(string(@name), string(@value))

  4. Supplying a simple NCName as the first argument means the element will be in no namespace. The default namespace for elements is NOT used.

See also:

saxon:new-element()

saxon:new-attribute()

saxon:new-text()

saxon:new-comment()

saxon:new-processing-instruction()