Constructor functions and cast expressions accept an expression and return a value of a given type. They both convert a source value SV, of a source type, ST to a target value TV, of the given target type TT.
Constructor functions and cast expressions have identical semantics but different syntax. The name of the constructor function is the same as the name of the built-in [XML Schema Part 2: Datatypes Second Edition] datatype or the datatype defined in Section 2.7 Schema Information DM31 of [XQuery and XPath Data Model (XDM) 3.1] (see 20.1 Constructor functions for XML Schema built-in atomic types) or the user-derived datatype (see 20.5 Constructor functions for user-defined atomic and union types) that is the target for the conversion, and the semantics are exactly the same as for a cast expression; for example, xs:date("2003-01-01") means exactly the same as "2003-01-01" cast as xs:date?.
The cast expression takes a type name to indicate the target type of the conversion. See Section 3.14.2 Cast XP31. If the type name allows the empty sequence and the expression to be cast is the empty sequence, the empty sequence is returned. If the type name does not allow the empty sequence and the expression to be cast is the empty sequence, a type error is raised [err:XPTY0004]XP.
Where the argument to a cast is a literal, the result of the function may be evaluated statically; if an error is encountered during such evaluation, it may be reported as a static error.
The general rules for casting from primitive types to primitive types are defined in 21.1 Casting from primitive types to primitive types, and subsections describe the rules for specific target types. The general rules for casting from xs:string (and xs:untypedAtomic) follow in 21.2 Casting from xs:string and xs:untypedAtomic. Casting to non-primitive types, including atomic types derived by restriction, union types, and list types, is described in 21.3 Casting involving non-primitive types. Casting from derived types is defined in 21.3.4 Casting from derived types to parent types, 21.3.5 Casting within a branch of the type hierarchy and 21.3.6 Casting across the type hierarchy.
Casting is not supported to or from xs:anySimpleType. Casting to xs:anySimpleType is not permitted and raises a static error: [err:XPST0080]XP.
Similarly, casting is not supported to or from xs:anyAtomicType and will raise a static error: [err:XPST0080]XP. There are no atomic items with the type annotation xs:anyAtomicType, although this can be a statically inferred type.
Changes in 4.0 ⬇ ⬆
This section now uses the term primitive type strictly to refer to the 20 atomic types that are not derived by restriction from another atomic type: that is, the 19 primitive atomic types defined in XSD, plus xs:untypedAtomic. The three types xs:integer, xs:dayTimeDuration, and xs:yearMonthDuration, which have custom casting rules but are not strictly-speaking primitive, are now handled in other subsections. [Issue 1401 PR 1409]
This section defines casting between ·primitive types· (specifically, the 19 primitive types defined in [XML Schema Part 2: Datatypes Second Edition] plus xs:untypedAtomic. The type conversions that are supported between primitive atomic types are indicated in the table below; casts between other (non-primitive) types are defined in terms of these primitives.
Where the target type TT is a primitive type, the result TV will always be an instance of TT. The result may also be an instance of a type derived from TT: for example casting an xs:NCNameSV to xs:stringmay return SV unchanged, with its original type annotation.
In this table, there is a row for each ·primitive type· acting as the source of the conversion and there is a column for each ·primitive type· acting as the target of the conversion. The intersections of rows and columns contain one of three characters:
Y indicates that a conversion from values of the type to which the row applies to the type to which the column applies is supported;
N indicates that there are no supported conversions from values of the type to which the row applies to the type to which the column applies;
M indicates that a conversion from values of the type to which the row applies to the type to which the column applies may succeed for some values in the value space and fail for others.
There is no row or column for xs:untypedAtomic because the casting rules are exactly the same as for xs:string. When casting from xs:string or xs:untypedAtomic the semantics in 21.2 Casting from xs:string and xs:untypedAtomic apply, regardless of target type.
[XML Schema Part 2: Datatypes Second Edition] defines xs:NOTATION as an abstract type. Thus, casting to xs:NOTATION from any other type including xs:NOTATION is not permitted and raises a static error [err:XPST0080]XP. However, casting from one subtype of xs:NOTATION to another subtype of xs:NOTATION is permitted.
Casting is not supported to or from xs:anySimpleType. Thus, there is no row or column for this type in the table below. For any node that has not been validated or has been validated as xs:anySimpleType, the typed value of the node is an atomic item of type xs:untypedAtomic. There are no atomic items with the type annotation xs:anySimpleType at runtime. Casting to xs:anySimpleType is not permitted and raises a static error: [err:XPST0080]XP.
Similarly, casting is not supported to or from xs:anyAtomicType and will raise a static error: [err:XPST0080]XP. There are no atomic items with the type annotation xs:anyAtomicType at runtime, although this can be a statically inferred type.
If casting is attempted from an ST to a TT for which casting is not supported, as defined in the table below, a type error is raised [err:XPTY0004]XP.
In the following table, the columns and rows are identified by short codes that identify simple types as follows:
aURI = xs:anyURI
b64 = xs:base64Binary
bool = xs:boolean
dat = xs:date
gDay = xs:gDay
dbl = xs:double
dec = xs:decimal
dT = xs:dateTime
dur = xs:duration
flt = xs:float
hxB = xs:hexBinary
gMD = xs:gMonthDay
gMon = xs:gMonth
NOT = xs:NOTATION
QN = xs:QName
str = xs:string
tim = xs:time
gYM = xs:gYearMonth
gYr = xs:gYear
In the following table, the notation “S\T” indicates that the source (“S”) of the conversion is indicated in the column below the notation and that the target (“T”) is indicated in the row to the right of the notation.
| S\T | str | flt | dbl | dec | dur | dT | tim | dat | gYM | gYr | gMD | gDay | gMon | bool | b64 | hxB | aURI | QN | NOT |
|---|
| str | Y | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M |
|---|
| flt | Y | Y | Y | M | N | N | N | N | N | N | N | N | N | Y | N | N | N | N | N |
|---|
| dbl | Y | Y | Y | M | N | N | N | N | N | N | N | N | N | Y | N | N | N | N | N |
|---|
| dec | Y | Y | Y | Y | N | N | N | N | N | N | N | N | N | Y | N | N | N | N | N |
|---|
| dur | Y | N | N | N | Y | N | N | N | N | N | N | N | N | N | N | N | N | N | N |
|---|
| dT | Y | N | N | N | N | Y | Y | Y | Y | Y | Y | Y | Y | N | N | N | N | N | N |
|---|
| tim | Y | N | N | N | N | N | Y | N | N | N | N | N | N | N | N | N | N | N | N |
|---|
| dat | Y | N | N | N | N | Y | N | Y | Y | Y | Y | Y | Y | N | N | N | N | N | N |
|---|
| gYM | Y | N | N | N | N | N | N | N | Y | N | N | N | N | N | N | N | N | N | N |
|---|
| gYr | Y | N | N | N | N | N | N | N | N | Y | N | N | N | N | N | N | N | N | N |
|---|
| gMD | Y | N | N | N | N | N | N | N | N | N | Y | N | N | N | N | N | N | N | N |
|---|
| gDay | Y | N | N | N | N | N | N | N | N | N | N | Y | N | N | N | N | N | N | N |
|---|
| gMon | Y | N | N | N | N | N | N | N | N | N | N | N | Y | N | N | N | N | N | N |
|---|
| bool | Y | Y | Y | Y | N | N | N | N | N | N | N | N | N | Y | N | N | N | N | N |
|---|
| b64 | Y | N | N | N | N | N | N | N | N | N | N | N | N | N | Y | Y | N | N | N |
|---|
| hxB | Y | N | N | N | N | N | N | N | N | N | N | N | N | N | Y | Y | N | N | N |
|---|
| aURI | Y | N | N | N | N | N | N | N | N | N | N | N | N | N | N | N | Y | N | N |
|---|
| QN | Y | N | N | N | N | N | N | N | N | N | N | N | N | N | N | N | N | Y | M |
|---|
| NOT | Y | N | N | N | N | N | N | N | N | N | N | N | N | N | N | N | N | Y | M |
|---|
Any atomic item SV can be cast to xs:string.
The resulting xs:string value TV depends on the source type ST as follows.
If SV is an instance of xs:string, TV is an instance of xs:string comprising the same sequence of characters as SV.
Note:
The implementation is free to return SV unchanged, including its original type annotation.
If SV is an instance of xs:anyURI, the result TV is an instance of xs:string comprising the same sequence of characters as SV, but with a type annotation of xs:anyURI. No escaping of special characters takes place.
If SV is an instance of xs:QName or xs:NOTATION:
if the qualified name has a prefix, then TV is the concatenation of the prefix of SV, a single colon (:), and the local name of SV.
otherwise TV is the local name of SV.
If SV is an instance of xs:numeric, the rules in 21.1.2.1 Casting numeric values to xs:string apply.
If SV is an instance of xs:dateTime, xs:date or xs:time, the rules in 21.1.2.2 Casting date/time values to xs:string apply.
If ST is xs:duration, or any subtype thereof including xs:yearMonthDuration and xs:dayTimeDuration, then the rules in 21.1.2.3 Casting xs:duration values to xs:string apply.
In all other cases, TV is the [XML Schema Part 2: Datatypes Second Edition] canonical representation of SV. For datatypes that do not have a canonical representation defined an ·implementation-dependent· canonical representation may be used.
To cast as xs:untypedAtomic the value is cast as xs:string, as described above, and the type annotation changed to xs:untypedAtomic.
The following rules apply when the source type ST is xs:decimal, xs:double, or xs:float, or any subtype of these including xs:integer.
If SV is an instance of xs:decimal, then the canonical representation of SV is returned, as defined in [XSD 1.1 Part 2]. Specifically, see [TITLE OF XS2 SPEC, TITLE OF f-decimalCanmap SECTION]XS2.If SV is an instance of xs:decimal, then the canonical representation of SV is returned, as defined in [XSD 1.1 Part 2]. Specifically, see decimalCanonicalMap.If SV is an instance of xs:decimal, then the canonical representation of SV is returned, as defined in [XSD 1.1 Part 2]. Specifically, see [TITLE OF XS2 SPEC, TITLE OF f-decimalCanmap SECTION]XS2decimalCanonicalMap.
Note:
Unlike previous versions of this specification, no special rule is given for the case where SV is an instance of xs:integer. This is because the general rule for xs:decimal gives the same result. The result in this case will be a sequence of decimal digits in the range U+0030 (DIGIT ZERO, 0) to U+0039 (DIGIT NINE, 9) , optionally preceded by a minus sign, with no leading zeroes. For example: 42, -1, 0, or 1000000000.
Note:
An xs:decimal that is equal to an integer is converted to a string as if it were first cast to an xs:integer. Specifically, there will be no decimal point and no fractional part.
If the value is not equal to an integer, then there will be a decimal point and a fractional part, which will be a sequence of decimal digits with no trailing zeroes. For example: 42.3, -1.5, or 0.00001.
If SV is an instance of xs:float or xs:double, then:
TV will be an xs:string in the lexical space of xs:double or xs:float that when converted to an xs:double or xs:float under the rules of 21.2 Casting from xs:string and xs:untypedAtomic produces a value that is equal to SV, or is NaN if SV is NaN. In addition, TV must satisfy the constraints in the following sub-bullets.
If SV has an absolute value that is greater than or equal to 0.000001 (one millionth) and less than 1000000 (one million), then the value is converted to an xs:decimal and the resulting xs:decimal is converted to an xs:string according to the rules above, as though using an implementation of xs:decimal that imposes no limits on the totalDigits or fractionDigits facets.
If SV has the value positive or negative zero, TV is "0" or "-0" respectively.
If SV is positive or negative infinity, TV is the string "INF" or "-INF" respectively.
In other cases, the result consists of a mantissa, which has the lexical form of an xs:decimal, followed by the letter "E", followed by an exponent which has the lexical form of an xs:integer. Leading zeroes and "+" signs are prohibited in the exponent. For the mantissa, there must be a decimal point, and there must be exactly one digit before the decimal point, which must be non-zero. The "+" sign is prohibited. There must be at least one digit after the decimal point. Apart from this mandatory digit, trailing zero digits are prohibited.
Note:
The above rules allow more than one representation of the same value. For example, the xs:float value whose exact decimal representation is 1.26743223E15 might be represented by any of the strings "1.26743223E15", "1.26743222E15" or "1.26743224E15" (inter alia). It is implementation-dependent which of these representations is chosen.
Note:
The string representations of numeric values are backwards compatible with XPath 1.0 except for the special values positive and negative infinity, negative zero and values outside the range 1.0e-6 to 1.0e+6.
Changes in 4.0 ⬇ ⬆
The rules for conversion of durations to strings are now defined entirely in terms of XSD 1.1 canonical mappings, since the XSD 1.1 rules deliver exactly the same result as the XPath 3.1 rules. [Issue 1401 PR 1409]
If SV is an instance of xs:duration (including its subtypes xs:yearMonthDuration and xs:dayTimeDuration), then TV is the canonical representation of SV as defined in [XSD 1.1 Part 2]. Specifically, see [TITLE OF XS2 SPEC, TITLE OF f-durationCanMap SECTION]XS2.If SV is an instance of xs:duration (including its subtypes xs:yearMonthDuration and xs:dayTimeDuration), then TV is the canonical representation of SV as defined in [XSD 1.1 Part 2]. Specifically, see durationCanonicalMap.If SV is an instance of xs:duration (including its subtypes xs:yearMonthDuration and xs:dayTimeDuration), then TV is the canonical representation of SV as defined in [XSD 1.1 Part 2]. Specifically, see [TITLE OF XS2 SPEC, TITLE OF f-durationCanMap SECTION]XS2durationCanonicalMap.
Note:
The rules have the effect of normalizing the value so that the number of months is always less than 12, the number of hours less than 24, and the number of minutes and seconds less than 60. Zero-valued components are omitted. Fractional seconds follow the same rules as xs:decimal. For example, the duration P15MT30H is represented as P1Y3M1DT6H. A zero-length duration is output as PT0S.
Note:
At the time of writing, the published XSD 1.1 recommendation contains cut-and-paste errors in the definition of the dayTimeDuration canonical mapping. The binding of variable s should be to dt's ·seconds· (not ·months·) component, and the return expression given as sgn & 'P' & ·duYearMonthCanonicalFragmentMap·(|s|) should read sgn & 'P' & ·duDayTimeCanonicalFragmentMap·(|s|)
In reading these XSD formulations, be aware that a & b represents string concatenation, while |s| computes the absolute value of a number.