This function serializes the supplied input sequence $arg as described in
fn:serialize( $arg as item()*xs:stringfn:serialize( $arg as item()*,$params as item()?xs:stringThe value of the first argument $arg acts as the input sequence to the serialization process,
which starts with sequence normalization.
The second argument $params, if present, provides serialization parameters. These may be supplied in either
of two forms:
As an output:serialization-parameters
element, having the format described in . In this case the type of the supplied
argument must match the required type element(output:serialization-parameters).
As a map. In this case the type of the supplied argument must match the required type map(*)
The single-argument version of this function has the same effect as the two-argument
version called with $params set to an empty sequence. This in turn is the
same as the effect of passing an output:serialization-parameters element
with no child elements.
The final stage of serialization, that is, encoding, is skipped. If the serializer does not allow this phase to be skipped, then the sequence of octets returned by the serializer is decoded into a string by reversing the character encoding performed in the final stage.
If the second argument is omitted, or is supplied in the form of an output:serialization-parameters
element, then the values of any serialization parameters that are not explicitly specified is implementation-defined,
and may depend on the context.
If the second argument is supplied as a map, then the option parameter conventions apply. In this case:
Each entry in the map defines one serialization parameter.
The key of the entry is an xs:string value in the cases of parameter names defined in these specifications, or an
xs:QName (with non-absent namespace) in the case of implementation-defined serialization parameters.
The required type of each parameter, and its default value, are defined by the following table. The default value is used when the map contains no entry for the parameter in question, and also when an entry is present, with the empty sequence as its value. The table also indicates how the value of the map entry is to be interpreted in cases where further explanation is needed.
allow-duplicate-names
|
xs:boolean?
|
true() means "yes", false() means "no" |
no
|
byte-order-mark
|
xs:boolean?
|
true() means "yes", false() means "no" |
no
|
cdata-section-elements
|
xs:QName*
|
()
|
|
doctype-public
|
xs:string?
|
Zero-length string and () both represent "absent" |
absent |
doctype-system
|
xs:string?
|
Zero-length string and () both represent "absent" |
absent |
encoding
|
xs:string?
|
utf-8
|
|
escape-uri-attributes
|
xs:boolean?
|
true() means "yes", false() means "no" |
yes
|
html-version
|
xs:decimal?
|
5
|
|
include-content-type
|
xs:boolean?
|
true() means "yes", false() means "no" |
yes
|
indent
|
xs:boolean?
|
true() means "yes", false() means "no" |
no
|
item-separator
|
xs:string?
|
absent | |
json-node-output-method
|
union(xs:string, xs:QName)?
|
See Notes 1, 2 |
xml
|
media-type
|
xs:string?
|
(a media type suitable for the chosen method) |
|
method
|
union(xs:string, xs:QName)?
|
See Notes 1, 2 |
xml
|
normalization-form
|
xs:string?
|
none
|
|
omit-xml-declaration
|
xs:boolean?
|
true() means "yes", false() means "no" |
yes
|
standalone
|
xs:boolean?
|
true() means "yes", false() means "no", () means "omit" |
omit
|
suppress-indentation
|
xs:QName*
|
()
|
|
undeclare-prefixes
|
xs:boolean?
|
true() means "yes", false() means "no" |
no
|
use-character-maps
|
map(xs:string, xs:string)?
|
See Note 3 |
map{}
|
version
|
xs:string?
|
1.0
|
Notes to the table:
The notation union(A, B) is used to represent a union type whose member types are A
and B.
If an xs:QName is supplied for the method or json-node-output-method
options, then it must have a non-absent namespace URI. This
means that system-defined serialization methods such as xml and json
are defined as strings, not as xs:QName values.
For the use-character-maps option, the value is a map, whose keys
are the characters to be mapped (as xs:string instances),
and whose corresponding values are the strings to be substituted for these characters.
The option parameter conventions
apply recursively to this nested map.
Given the variables:
let $params :=
let $data :=
The following call might produce the output shown:
The expression fn:serialize($data, $params) returns '<a b="3"/>'.
The following call would also produce the output shown (though the second argument could equally well be supplied
as an empty map (map{}), since both parameters are given their default values):
The expression fn:serialize($data, map{"method":"xml", "omit-xml-declaration":true()}) returns '<a b="3"/>'.
A type error occurs if the second argument
is present and does not match either of the types element(output:serialization-parameters)?
or map(*).
This is defined as a type error so that it can be enforced via the function signature by implementations that generalize the type system in a suitable way.
If the host language makes serialization an optional feature and the implementation does not support serialization, then a dynamic error is raised.
The serialization process will raise an error if $arg is an attribute or
namespace node.
When the second argument is supplied as a map,
and the supplied value is of the wrong type for the particular parameter, for example if the value of indent
is a string rather than a boolean, then as defined by the option parameter conventions,
a type error is raised.
If the value is of the correct type, but does not satisfy the rules for that
parameter defined in , then a dynamic error
is raised. (For example, this occurs if the map supplied to
use-character-maps includes a key that is a string whose length is not one (1)).
If any serialization error occurs, including the detection of an invalid value for a
serialization parameter as described above, this results in the fn:serialize call failing with
a dynamic error.
One use case for this function arises when there is a need to construct an XML document
containing nested XML documents within a CDATA section (or on occasions within a
comment). See fn:parse-xml for further details.
Another use case arises when there is a need to call an extension function that expects a lexical XML document as input.
There are also use cases where the application wants to post-process the output of a
query or transformation, for example by adding an internal DTD subset, or by inserting
proprietary markup delimiters such as the <% ... %> used by some
templating languages.
The ability to specify the serialization parameters in an output:serialization-parameters
element provides backwards compatibility with the 3.0 version of this specification; the ability to
use a map takes advantage of new features in the 3.1 version. The default parameter values are
implementation-defined when an output:serialization-parameters
element is used (or when the argument is omitted), but are fixed by this specification in the
case where a map (including an empty map) is supplied for the argument.