Constructor functions for built-in data types

Constructor functions convert an instance of one atomic type into an instance of a different atomic type. An implicitly-defined constructor function exists for each of the built-in atomic types that are defined in XML Schema. Constructor functions also exist for the data type xdt:untypedAtomic and the two derived data types xdt:yearMonthDuration and xdt:dayTimeDuration.

Constructor functions are not available for xs:NOTATION, xs:anyType, xs:anySimpleType, or xdt:anyAtomicType.

All constructor functions for built-in types share the following generic syntax:

Note: The semantics of the constructor function type-name(value) are defined to be equivalent to the expression (value cast as type-name?).

type-name: The QName of the target data type.
value: The value to be constructed as an instance of the target data type. Atomization is applied to the value. If the result of atomization is an empty sequence, the empty sequence is returned. If the result of atomization is a sequence of more than one item, an error is raised. Otherwise, the resulting atomic value is cast to the target type. For information about which types can be cast to which other types, see Type casting.

For example, the following diagram represents the syntax of the constructor function for the XML Schema data type xs:unsignedInt:

The value that can be passed to this constructor function is any atomic value that can be validly cast into the target data type. For example, the following invocations of this function return the same result, the xs:unsignedInt value 12:

xs:unsignedInt(12)
xs:unsignedInt("12")

In the first example, the numeric literal 12 is passed to the constructor function. Because the literal does not contain a decimal point, it is parsed as an xs:integer, and the xs:integer value is cast to the type xs:unsignedInt. In the second example, the string literal "12" is passed to the constructor function. The string literal is parsed as an xs:string, and the xs:string value is cast to the type xs:unsignedInt.

A constructor function can also be invoked with a node as its argument. In this case, Db2 XQuery atomizes the node to extract its typed value and then calls the constructor with that value. If the value that is passed to a constructor cannot be cast to the target data type, an error is returned.

The constructor function for xs:QName differs from the generic syntax for constructor functions in that the constructor function is constrained to take a string literal as its argument.

When casting a value to a data type, you can use the castable expression to test whether the value can be cast to the data type.