The Functions and Operators specification is intended primarily as a component that can be used by other specifications. Therefore, Functions and Operators relies on specifications that use it (such as , and ) to specify conformance criteria for their respective environments.

Authors of conformance criteria for the use of the Functions and Operators should pay particular attention to the following features:

In this document, text labeled as an example or as a Note is provided for explanatory purposes and is not normative.

The functions and operators discussed in this document are contained in one of several namespaces (see ) and referenced using an xs:QName.

This document uses conventional prefixes to refer to these namespaces. User-written applications can choose a different prefix to refer to the namespace, so long as it is bound to the correct URI. The host language may also define a default namespace for function calls, in which case function names in that namespace need not be prefixed at all. In many cases the default namespace will be http://www.w3.org/2005/xpath-functions, allowing a call on the fn:name function (for example) to be written as name() rather than fn:name(); in this document, however, all example function calls are explicitly prefixed.

The URIs of the namespaces and the conventional prefixes associated with them are:

In general, the specifications named above do not support function overloading in the sense that functions that have multiple signatures with the same name and the same number of parameters are not supported. Consequently, there are no such overloaded functions in this document except for legacy functions such as fn:string, which accepts a single parameter of a variety of types. In addition, it should be noted that the functions defined in that accept numeric parameters accept arguments of type xs:integer, xs:decimal, xs:float or xs:double. See . Operators such as "+" may be overloaded. This document does define some functions with more than one signature with the same name and different number of parameters. User-defined functions with more than one signature with the same name and different number of parameters are also supported.

Each function is defined by specifying its signature, a description of the return type and each of the parameters and its semantics. For many functions, examples are included to illustrate their use.

Each function's signature is presented in a form like this:

In this notation, function-name, in bold-face, is the name of the function whose signature is being specified. If the function takes no parameters, then the name is followed by an empty parameter list: "()"; otherwise, the name is followed by a parenthesized list of parameter declarations, each declaration specifies the static type of the parameter, in italics, and a descriptive, but non-normative, name. If there are two or more parameter declarations, they are separated by a comma. The return-type , also in italics, specifies the static type of the value returned by the function. The dynamic type returned by the function is the same as its static type or derived from the static type. All parameter types and return types are specified using the SequenceType notation defined in .

One function, fn:concat, has a variable number of arguments (two or more). More strictly, there is an infinite set of functions having the name fn:concat, with arity ranging from 2 to infinity. For this special case, a single function signature is given, with an ellipsis indicating an indefinite number of arguments.

In some cases the word numeric is used in function signatures as a shorthand to indicate the four numeric types: xs:integer, xs:decimal, xs:float and xs:double. For example, a function with the signature:

represents the following four function signatures:

For most functions there is an initial paragraph describing what the function does followed by semantic rules. These rules are meant to be followed in the order that they appear in this document.

In some cases, the static type returned by a function depends on the type(s) of its argument(s). These special functions are indicated by using bold italics for the return type. The semantic rules specifying the type of the value returned are documented in the function definition. The rules are described more formally in .

The function name is a QName as defined in and must adhere to its syntactic conventions. Following , function names are composed of English words separated by hyphens,"-". If a function name contains a datatype name, it may have intercapitalized spelling and is used in the function name as such. For example, fn:timezone-from-dateTime.

Rules for passing parameters to operators are described in the relevant sections of and . For example, the rules for passing parameters to arithmetic operators are described in . Specifically, rules for parameters of type xs:untypedAtomic and the empty sequence are specified in this section.

As is customary, the parameter type name indicates that the function or operator accepts arguments of that type, or types derived from it, in that position. This is called subtype substitution (See ). In addition, numeric type instances and instances of type xs:anyURI can be promoted to produce an argument of the required type. (See ).

Some functions accept a single value or the empty sequence as an argument and some may return a single value or the empty sequence. This is indicated in the function signature by following the parameter or return type name with a question mark: "?", indicating that either a single value or the empty sequence must appear. See below.

Note that this function signature is different from a signature in which the parameter is omitted. See, for example, the two signatures for fn:string. In the first signature, the parameter is omitted and the argument defaults to the context item, referred to as .. In the second signature, the argument must be present but may be the empty sequence, referred to as ().

Some functions accept a sequence of zero or more values as an argument. This is indicated by following the name of type of the items in the sequence with *. The sequence may contain zero or more items of the named type. For example, the function below accepts a sequence of xs:double and returns a xs:double or the empty sequence.

The diagrams below show how nodes, function items, primitive simple types, and user defined types fit together into a type system. This type system comprises two distinct hierarchies that both include the primitive simple types. In the diagrams, connecting lines represent relationships between derived types and the types from which they are derived; the arrowheads point toward the type from which they are derived. The dashed line represents relationships not present in this diagram, but that appear in one of the other diagrams. Dotted lines represent additional relationships that follow an evident pattern. The information that appears in each diagram is recapitulated in tabular form.

The xs:IDREFS, xs:NMTOKENS, and xs:ENTITIES types and the user-defined list and union types are special types in that these types are lists or unions rather than types derived by extension or restriction.

The first diagram and its corresponding table illustrate the item type hierarchy. In XDM, items include node types, function types, and built-in atomic types.

The terminology used to describe the functions and operators on is defined in the body of this specification. The terms defined in this section are used in building those definitions

In this document, as well as in , , and , the phrase an error is raised is used. Raising an error is equivalent to calling the fn:error function defined in this section with the provided error code.

The above phrase is normally accompanied by specification of a specific error, to wit: an error is raised [error code]. Each error defined in this document is identified by an xs:QName that is in the http://www.w3.org/2005/xqt-errors namespace, represented in this document by the err prefix. It is this xs:QName that is actually passed as an argument to the fn:error function. Calling this function raises an error. For a more detailed treatment of error handing, see and .

The fn:error function is a general function that may be called as above but may also be called from or applications with, for example, an xs:QName argument.

The operators described in this section are defined on the following numeric types. Each type whose name is indented is derived from the type whose name appears nearest above with one less level of indentation.

They also apply to types derived by restriction from the above types.

The following functions define the semantics of arithmetic operators defined in and on these numeric types.

The parameters and return types for the above operators are the basic numeric types: xs:integer, xs:decimal, xs:float and xs:double, and types derived from them. The word numeric in function signatures signifies these four types. For simplicity, each operator is defined to operate on operands of the same type and return the same type. The exceptions are op:numeric-divide, which returns an xs:decimal if called with two xs:integer operands and op:numeric-integer-divide which always returns an xs:integer.

If the two operands are not of the same type, subtype substitution and numeric type promotion are used to obtain two operands of the same type. and describe the semantics of these operations in detail.

The result type of operations depends on their argument datatypes and is defined in the following table:

These rules define any operation on any pair of arithmetic types. Consider the following example:

For this operation, xs:int must be converted to xs:double. This can be done, since by the rules above: xs:int can be substituted for xs:integer, xs:integer can be substituted for xs:decimal, xs:decimal can be promoted to xs:double. As far as possible, the promotions should be done in a single step. Specifically, when an xs:decimal is promoted to an xs:double, it should not be converted to an xs:float and then to xs:double, as this risks loss of precision.

As another example, a user may define height as a derived type of xs:integer with a minimum value of 20 and a maximum value of 100. He may then derive fenceHeight using an enumeration to restrict the permitted set of values to, say, 36, 48 and 60.

fenceHeight can be substituted for its base type height and height can be substituted for its base type xs:integer.

The basic rules for addition, subtraction, and multiplication of ordinary numbers are not set out in this specification; they are taken as given. In the case of xs:double and xs:float the rules are as defined in . The rules for handling division and modulus operations, as well as the rules for handling special values such as infinity and NaN, and exception conditions such as overflow and underflow, are described more explicitly since they are not necessarily obvious.

On overflow and underflow situations during arithmetic operations conforming implementations behave as follows:

The functions op:numeric-add, op:numeric-subtract, op:numeric-multiply, op:numeric-divide, op:numeric-integer-divide and op:numeric-mod are each defined for pairs of numeric operands, each of which has the same type:xs:integer, xs:decimal, xs:float, or xs:double. The functions op:numeric-unary-plus and op:numeric-unary-minus are defined for a single operand whose type is one of those same numeric types.

For xs:float and xs:double arguments, if either argument is NaN, the result is NaN.

For xs:decimal values the number of digits of precision returned by the numeric operators is . If the number of digits in the result exceeds the number of digits that the implementation supports, the result is truncated or rounded in an manner.

This specification defines the following comparison operators on numeric values. Comparisons take two arguments of the same type. If the arguments are of different types, one argument is promoted to the type of the other as described above in . Each comparison operator returns a boolean value. If either, or both, operands are NaN, false is returned.

The following functions are defined on numeric types. Each function returns a value of the same type as the type of its argument.

This section defines a function for formatting decimal and floating point numbers.

The functions in this section perform trigonometrical calculations on xs:double values. They are designed for use in applications performing geometrical computation, for example when generating SVG graphics.

Functions are provided to support the six most commonly used trigonometric calculations: sine, cosine and tangent, and their inverses arc sine, arc cosine, and arc tangent. Other functions such as secant, cosecant, and cotangent are not provided because they are easily computed in terms of these six.

In this section, when the rules for a function say that the returned value must be the xs:double either side of some mathematical quantity, then if the mathematical quantity is precisely representable in the value space of xs:double the exact result must be returned; otherwise it is acceptable to return either the nearest higher xs:double or the nearest lower xs:double, and it is implementation-dependent which of the two is returned.

The operators described in this section are defined on the following types. Each type whose name is indented is derived from the type whose name appears nearest above with one less level of indentation.

They also apply to user-defined types derived by restriction from the above types.

It is which version of is supported, but it is recommended that the most recent version of Unicode be used.

Unless explicitly stated, the xs:string values returned by the functions in this document are not normalized in the sense of .

The following functions are defined on values of type xs:string and types derived from it.

The functions described in the section examine a string $arg1 to see whether it contains another string $arg2 as a substring. The result depends on whether $arg2 is a substring of $arg1, and if so, on the range of characters in $arg1 which $arg2 matches.

When the Unicode codepoint collation is used, this simply involves determining whether $arg1 contains a contiguous sequence of characters whose codepoints are the same, one for one, with the codepoints of the characters in $arg2.

When a collation is specified, the rules are more complex.

All collations support the capability of deciding whether two strings are considered equal, and if not, which of the strings should be regarded as preceding the other. For functions such as fn:compare, this is all that is required. For other functions, such as fn:contains, the collation needs to support an additional property: it must be able to decompose the string into a sequence of collation units, each unit consisting of one or more characters, such that two strings can be compared by pairwise comparison of these units. ("collation unit" is equivalent to "collation element" as defined in .) The string $arg1 is then considered to contain $arg2 as a substring if the sequence of collation units corresponding to $arg2 is a subsequence of the sequence of the collation units corresponding to $arg1. The characters in $arg1 that match are the characters corresponding to these collation units.

This rule may occasionally lead to surprises. For example, consider a collation that treats "Jaeger" and "Jäger" as equal. It might do this by treating "ä" as representing two collation units, in which case the expression fn:contains("Jäger", "eg") will return true. Alternatively, a collation might treat "ae" as a single collation unit, in which case the expression fn:contains("Jaeger", "eg") will return false. The results of these functions thus depend strongly on the properties of the collation that is used.

In addition, collations may specify that some collation units should be ignored during matching. If hyphen is an ignored collation unit, then fn:contains("code-point", "codepoint") will be true, and fn:contains("codepoint", "-") will also be true.

In the definitions below, we refer to the terms match and minimal match as defined in definitions DS2 and DS4 of . In applying these definitions:

It is possible to define collations that do not have the ability to decompose a string into units suitable for substring matching. An argument to a function defined in this section may be a URI that identifies a collation that is able to compare two strings, but that does not have the capability to split the string into collation units. Such a collation may cause the function to fail, or to give unexpected results or it may be rejected as an unsuitable argument. The ability to decompose strings into collation units is an property of the collation.

The three functions described in this section make use of a regular expression syntax for pattern matching. This is described below.

Since no literals are defined in XPath to reference the constant boolean values true and false, two functions are provided for the purpose.

The following functions define the semantics of operators on boolean values in and :

The ordering operators op:boolean-less-than and op:boolean-greater-than are provided for application purposes and for compatibility with . The datatype xs:boolean is not ordered.

The following functions are defined on boolean values:

A processor that limits the number of digits in date and time datatype representations may encounter overflow and underflow conditions when it tries to execute the functions in . In these situations, the processor return P0M or PT0S in case of duration underflow and 00:00:00 in case of time underflow. It raise an error in case of overflow.

The value spaces of the two totally ordered subtypes of xs:duration described in are xs:integer months for xs:yearMonthDuration and xs:decimal seconds for xs:dayTimeDuration. If a processor limits the number of digits allowed in the representation of xs:integer and xs:decimal then overflow and underflow situations can arise when it tries to execute the functions in . In these situations the processor return zero in case of numeric underflow and P0M or PT0S in case of duration underflow. It raise an error in case of overflow.

Two totally ordered subtypes of xs:duration are defined in specification using the mechanisms described in for defining user-defined types. Additional details about these types is given below.

The following comparison operators are defined on the duration datatypes. Each operator takes two operands of the same type and returns an xs:boolean result. As discussed in , the order relation on xs:duration is not a total order but, rather, a partial order. For this reason, only equality is defined on xs:duration. A full complement of comparison and arithmetic functions are defined on the two subtypes of duration described in which do have a total order.

The duration datatype may be considered to be a composite datatypes in that it contains distinct properties or components. The extraction functions specified below extract a single component from a duration value. For xs:duration and its subtypes, including the two subtypes xs:yearMonthDuration and xs:dayTimeDuration, the components are normalized: this means that the seconds and minutes components will always be less than 60, the hours component less than 24, and the months component less than 12.

For operators that combine a duration and a date/time value, see .

The operators described in this section are defined on the following date and time types:

The only operations defined on xs:gYearMonth, xs:gYear, xs:gMonthDay, xs:gMonth and xs:gDay values are equality comparison and component extraction. For other types, further operations are provided, including order comparisons, arithmetic, formatted display, and timezone adjustment.

As defined in , xs:dateTime, xs:date, xs:time, xs:gYearMonth, xs:gYear, xs:gMonthDay, xs:gMonth, xs:gDay values, referred to collectively as date/time values, are represented as seven components or properties: year, month, day, hour, minute, second and timezone. The value of the first five components are xs:integers. The value of the second component is an xs:decimal and the value of the timezone component is an xs:dayTimeDuration. For all the primitive date/time datatypes, the timezone property is optional and may or may not be present. Depending on the datatype, some of the remaining six properties must be present and some must be absent. Absent, or missing, properties are represented by the empty sequence. This value is referred to as the local value in that the value retains its original timezone. Before comparing or subtracting xs:dateTime values, this local value be translated or normalized to UTC.

For xs:time, 00:00:00 and 24:00:00 are alternate lexical forms for the same value, whose canonical representation is 00:00:00. For xs:dateTime, a time component 24:00:00 translates to 00:00:00" of the following day.

A function is provided for constructing a xs:dateTime value from a xs:date value and a xs:time value.

The following comparison operators are defined on the date/time datatypes. Each operator takes two operands of the same type and returns an xs:boolean result.

also states that the order relation on date and time datatypes is not a total order but a partial order because these datatypes may or may not have a timezone. This is handled as follows. If either operand to a comparison function on date or time values does not have an (explicit) timezone then, for the purpose of the operation, an implicit timezone, provided by the dynamic context , is assumed to be present as part of the value. This creates a total order for all date and time values.

An xs:dateTime can be considered to consist of seven components: year, month, day, hour, minute, second and timezone. For xs:dateTime six components: year, month, day, hour, minute and second are required and timezone is optional. For other date/time values, of the first six components, some are required and others must be absent or missing. Timezone is always optional. For example, for xs:date, the year, month and day components are required and hour, minute and second components must be absent; for xs:time the hour, minute and second components are required and year, month and day are missing; for xs:gDay, day is required and year, month, hour, minute and second are missing.

Values of the date/time datatypes xs:time, xs:gMonthDay, xs:gMonth, and xs:gDay, can be considered to represent a sequence of recurring time instants or time periods. An xs:time occurs every day. An xs:gMonth occurs every year. Comparison operators on these datatypes compare the starting instants of equivalent occurrences in the recurring series. These xs:dateTime values are calculated as described below.

Comparison operators on xs:date, xs:gYearMonth and xs:gYear compare their starting instants. These xs:dateTime values are calculated as described below.

The starting instant of an occurrence of a date/time value is an xs:dateTime calculated by filling in the missing components of the local value from a reference xs:dateTime. An example of a suitable reference xs:dateTime is 1972-01-01T00:00:00. Then, for example, the starting instant corresponding to the xs:date value 2009-03-12 is 2009-03-12T00:00:00; the starting instant corresponding to the xs:time value 13:30:02 is 1972-01-01T13:30:02; and the starting instant corresponding to the gMonthDay value --02-29 is 1972-02-29T00:00:00 (which explains why a leap year was chosen for the reference).

If the xs:time value written as 24:00:00 is to be compared, filling in the missing components gives 1972-01-01T00:00:00, because 24:00:00 is an alternative representation of 00:00:00 (the lexical value "24:00:00" is converted to the time components {0,0,0} before the missing components are filled in). This has the consequence that when ordering xs:time values, 24:00:00 is considered to be earlier than 23:59:59. However, when ordering xs:dateTime values, a time component of 24:00:00 is considered equivalent to 00:00:00 on the following day.

Note that the reference xs:dateTime does not have a timezone. The timezone component is never filled in from the reference xs:dateTime. In some cases, if the date/time value does not have a timezone, the implicit timezone from the dynamic context is used as the timezone.

The date and time datatypes may be considered to be composite datatypes in that they contain distinct properties or components. The extraction functions specified below extract a single component from a date or time value. In all cases the local value (that is, the original value as written, without any timezone adjustment) is used.

These functions adjust the timezone component of an xs:dateTime, xs:date or xs:time value. The $timezone argument to these functions is defined as an xs:dayTimeDuration but must be a valid timezone value.

These functions support adding or subtracting a duration value to or from an xs:dateTime, an xs:date or an xs:time value. Appendix E of describes an algorithm for performing such operations.

Three functions are provided to represent dates and times as a string, using the conventions of a selected calendar, language, and country. The signatures are presented first, followed by the rules which apply to each of the functions.

In addition to the xs:QName constructor function, QName values can be constructed by combining a namespace URI, prefix, and local name, or by resolving a lexical QName against the in-scope namespaces of an element node. This section defines these functions. Leading and trailing whitespace, if present, is stripped from string arguments before the result is constructed.

This section specifies functions on QNames as defined in .

The following comparison operators on xs:base64Binary and xs:hexBinary values are defined. Comparisons take two operands of the same type; that is, both operands must be xs:base64Binary or both operands may be xs:hexBinary. Each returns a boolean value.

A value of type xs:hexBinary can be compared with a value of type xs:base64Binary by casting one value to the other type. See .

The following functions are defined on sequences.

As in the previous section, for the illustrative examples below, assume an XQuery or transformation operating on a non-empty Purchase Order document containing a number of line-item elements. The variable $seq is bound to the sequence of line-item nodes in document order. The variables $item1, $item2, etc. are bound to separate, individual line-item nodes in the sequence.

The following functions test the cardinality of their sequence arguments.

The functions fn:zero-or-one, fn:one-or-more, and fn:exactly-one defined in this section, check that the cardinality of a sequence is in the expected range. They are particularly useful with regard to static typing. For example, the function call fn:remove($seq, index-of($seq2, 'abc')) requires the result of the call on fn:index-of to be a singleton integer, but the static type system cannot infer this; writing the expression as fn:remove($seq, fn:exactly-one(fn:index-of($seq2, 'abc'))) will provide a suitable static type at query analysis time, and ensures that the length of the sequence is correct with a dynamic check at query execution time.

The type signatures for these functions deliberately declare the argument type as item()*, permitting a sequence of any length. A more restrictive signature would defeat the purpose of the function, which is to defer cardinality checking until query execution time.

As in the previous sections, for the illustrative examples below, assume an XQuery or transformation operating on a Purchase Order document containing a number of line-item elements. The variables $item1, $item2, etc. are bound to individual line-item nodes in the sequence. We use sequences of these nodes in some of the examples below.

Aggregate functions take a sequence as argument and return a single value computed from values in the sequence. Except for fn:count, the sequence must consist of values of a single type or one if its subtypes, or they must be numeric. xs:untypedAtomic values are permitted in the input sequence and handled by special conversion rules. The type of the items in the sequence must also support certain operations.

Every built-in atomic type that is defined in , except xs:anyAtomicType and xs:NOTATION, has an associated constructor function. xs:untypedAtomic, defined in and the two derived types xs:yearMonthDuration and xs:dayTimeDuration defined in also have associated constructor functions.

A constructor function is not defined for xs:anyAtomicType as there are no atomic values with type annotation xs:anyAtomicType at runtime, although this can be a statically inferred type. A constructor function is not defined for xs:NOTATION since it is defined as an abstract type in . If the static context (See ) contains a type derived from xs:NOTATION then a constructor function is defined for it. See .

The form of the constructor function for a type prefix:TYPE is:

If $arg is the empty sequence, the empty sequence is returned. For example, the signature of the constructor function corresponding to the xs:unsignedInt type defined in is:

Invoking the constructor function xs:unsignedInt(12) returns the xs:unsignedInt value 12. Another invocation of that constructor function that returns the same xs:unsignedInt value is xs:unsignedInt("12"). The same result would also be returned if the constructor function were to be invoked with a node that had a typed value equal to the xs:unsignedInt 12. The standard features described in would 'atomize' the node to extract its typed value and then call the constructor with that value. If the value passed to a constructor is illegal for the datatype to be constructed, an error is raised .

The semantics of the constructor function xs:TYPE(arg) are identical to the semantics of arg cast as xs:TYPE? . See .

If the argument to a constructor function is a literal, the result of the function may be evaluated statically; if an error is found during such evaluation, it may be reported as a static error.

Special rules apply to constructor functions for xs:QName and types derived from xs:QName and xs:NOTATION. See .

The following constructor functions for the built-in types are supported:

Special rules apply to constructor functions for the types xs:QName and xs:NOTATION, for two reasons:

These constraints result in the following restrictions:

When converting from an xs:string, the prefix within the lexical xs:QName supplied as the argument is resolved to a namespace URI using the statically known namespaces from the static context. If the lexical xs:QName has no prefix, the namespace URI of the resulting expanded-QName is the default element/type namespace from the static context. Components of the static context are discussed in . A static error is raised if the prefix is not bound in the static context. As described in , the supplied prefix is retained as part of the expanded-QName value.

For every atomic type in the static context (See ) that is derived from a primitive type, there is a constructor function (whose name is the same as the name of the type) whose effect is to create a value of that type from the supplied argument. The rules for constructing user-defined types are defined in the same way as the rules for constructing built-in derived types discussed in .

Special rules apply to constructor functions for types derived from xs:QName and xs:NOTATION. See .

Consider a situation where the static context contains a type called hatSize defined in a schema whose target namespace is bound to the prefix my. In such a case the constructor function:

is available to users.

To construct an instance of an atomic type that is not in a namespace, it is necessary to use a cast expression or undeclare the default function namespace. For example, if the user-defined type apple is derived from xs:integer but is not in a namespace, an instance of this type can be constructed as follows using a cast expression (this requires that the default element/type namespace is no namespace):

The following shows the use of the constructor function:

This section defines casting between the 19 primitive types defined in as well as xs:untypedAtomic, xs:integer and the two derived types of xs:duration (xs:yearMonthDuration and xs:dayTimeDuration). These four types are not primitive types but they are treated as primitive types in this section. The type conversions that are supported are indicated in the table below. In this table, there is a row for each primitive type with that type as the source of the conversion and there is a column for each primitive type 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; and 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 fails for others.

defines xs:NOTATION as an abstract type. Thus, casting to xs:NOTATION from any other type including xs:NOTATION is not permitted and raises . 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 value of type xs:untypedAtomic. There are no atomic values with the type annotation xs:anySimpleType at runtime. Casting to a type that is not atomic raises .

Similarly, casting is not supported to or from xs:anyAtomicType and will raise error . There are no atomic values 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 .

In the following table, the columns and rows are identified by short codes that identify simple types as follows:

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.

The following sub-sections define the semantics of casting from a primitive type to a primitive type. Semantics of casting to and from a derived type are defined in sections , , and .

Casting a value to a derived type can be separated into four cases. Note that xs:untypedAtomic, xs:integer and the two derived types of xs:duration:xs:yearMonthDuration and xs:dayTimeDuration are treated as primitive types.

Except in the case of xs:NOTATION, it is always possible to cast a value of any atomic type to an atomic type from which it is derived, directly or indirectly, by restriction. For example, it is possible to cast an xs:unsignedShort to an xs:unsignedInt, an xs:integer, or an xs:decimal. Since the value space of the original type is a subset of the value space of the target type, such a cast is always successful. The result will have the same value as the original, but will have a new type annotation.

It is possible to cast an SV to a TT if the type of the SV and the TT type are both derived by restriction (directly or indirectly) from the same primitive type, provided that the supplied value conforms to the constraints implied by the facets of the target type. This includes the case where the target type is derived from the type of the supplied value, as well as the case where the type of the supplied value is derived from the target type. For example, an instance of xs:byte can be cast as xs:unsignedShort, provided the value is not negative.

If the value does not conform to the facets defined for the target type, then an error is raised . See . In the case of the pattern facet (which applies to the lexical space rather than the value space), the pattern is tested against the canonical lexical representation of the value, as defined for the source type (or the result of casting the value to an xs:string, in the case of types that have no canonical lexical representation defined for them).

Note that this will cause casts to fail if the pattern excludes the canonical lexical representation of the source type. For example, if the type my:distance is defined as a restriction of xs:decimal with a pattern that requires two digits after the decimal point, casting of an xs:integer to my:distance will always fail, because the canonical representation of an xs:integer does not conform to this pattern.

In some cases, casting from a parent type to a derived type requires special rules. See for rules regarding casting to xs:yearMonthDuration and xs:dayTimeDuration. See , below, for casting to xs:ENTITY and types derived from it.

When the ST and the TT are derived, directly or indirectly, from different primitive types, this is called casting across the type hierarchy. Casting across the type hierarchy is logically equivalent to three separate steps performed in order. Errors can occur in either of the latter two steps.