# 22. Virtuoso Functions Guide - create-element

Chapter Contents | Prev | Next
Keyword Search:
www.openlinksw.com
docs.openlinksw.com
Book Home
Contents
Preface
Virtuoso Functions Guide
Administration
Aggregate Functions
Array Manipulation
BPEL APIs
Backup
Compression
Cursor
Date & Time Manipulation
Debug
Dictionary Manipulation
Encoding & Decoding
File Manipulation
Free Text
Hashing / Cryptographic
LDAP
Locale
Mail
Miscellaneous
Number
Remote SQL Data Source
Replication
SOAP
SQL
String
Transaction
Type Mapping
UDDI
User Defined Types & The CLR
Virtuoso Java PL API
Virtuoso Server Extension Interface (VSEI)
Web Server & Internet
XML
XPATH & XQUERY
and
append
assign
avg
boolean
ceiling
concat
contains
count
create-attribute
create-comment
create-element
create-pi
current
distinct
doc
document
document-literal
empty
ends-with
every
except
false
filter
floor
fn:collection
for
format-number
function-available
generate-id
id
if
intersect
is_after()
is_before()
key
lang
last
let
list()
local-name
max
min
name
namespace-uri
normalize-space
not
number
or
position
processxquery
processxslt
processxsql
progn()
replace()
round
serialize
shallow
some
starts-with
string
string-length
substring
substring-after
substring-before
sum
system-property
text_contains()
translate
true
tuple()
union
unordered
unparsed-entity-uri
urlify
xmlview
Functions Index

## create-element

Creates an element with specified name, attributes and children
node create-element ( head sequence, child1 any, child2 any, ... , childN any);
Description

This is an internal XQUERY function and you will probably never need to call it explicitely. It is not a part of library of standard XQUERY 1.0 functions.

This function creates a new "XML Tree" element whose name is a string-value of the first item of head sequence, with attributes and children specified by the rest of head sequence and by the list of arguments child1, child2, ... childN.

First of all, a new element will be created, without attributes or children. The name of element will be taken from the first item of the head sequence. Then attributes will be created from the second and third items of head, from fourth and fifth and so on. In every pair of items will specify name and value of some attribute. Non-string items will be converted to strings first. It is an error to specify the same attribute name twice in head sequence.

When the "opening tag" of the element is prepared, children are added, in the same order as they are specified by arguments child1, child2, ... childN. If the value of some argument is a sequences (e.g. a node-set), items of the sequence are added as separate children in the same order as they are in the sequence. Nodes are added "as-is", numbers, strings and other "scalar" values are converted to strings first and these strings are converted into PCDATA (text) children.

"Attribute descriptor" objects are not converted to children elements; if descriptor item is found, one attribute in the opening tag of the created element is added or changed and the descriptor is removed from the list of children.

When all children are prepared, some normalization is performed. If there are two or more adjacent PCDATA (text) children, they are replaced with one PCDATA children whose text is a concatenation of texts of all that children.

Parameters
head – Name of the element or a sequence of name and attributes of the element.
childI – Children node or sequence of children node.
Return Types

Node

Errors

SQLState | Error Code | Error Text | Description
--- | --- | --- | ---
XP001 | XPFC0 | At least one argument (name of element to be created) must be passed to create-element XPATH function. | create-element is called without arguments.
XP001 | XPFC1 | No name of element in the first argument of create-element XPATH function. | The head sequence is empty.
XP001 | XPFC2 | Last attribute has no value specified in the first argument of create-element XPATH function. | The head sequence is of even length.
XP001 | XPFC3 | Unsupported type of element of the first argument of create-element XPATH function. | Current version may create name and attributes of elements only from strings, entities and numbers.
XP001 | XPFC4 | Duplicate attribute names in first argument of create-element XPATH function. | Duplicate attribute names may appear in attribute descriptors but not in the head argument.
XP001 | XPFC5 | First argument of create-element XPATH function must be string, symbol or sequence of them. | The function was unable to prepare name of element.
XP001 | XPFC6 | Error in XPATH user extension function or internal error: sequence argument is not flat in create-element XPATH function. | A value of XQUERY "sequence" type should not contain other sequences as its items, i.e. it must be "flat".
XP001 | XPFC7 | Invalid special entity found in argument of create-element XPATH function. | An invalid object (probably built by XPATH extension function) is specified as child entity.
XP001 | XPFCA | Persistent XML entities are not fully supported by create-element XPATH function. | The function creates "XML Tree" element, "Persistent XML" entity can not become a children of "XML Tree".
XP001 | XPFCB | Unsupported type of argument in create-element XPATH function. | Some argument or some item of an argument may not be converted to a string or a node, so a children may not be created.

Examples

Two following XQUERY expressions are equivalent:

    <H1>{'Hello, '}<B>{'world'}</B></H1>
    create-element('H1', 'Hello, ', create-element('B', 'world'))

See Also

create-attribute()

create-comment()

create-pi()