What Is Static Typing?

Static typing, as the term is used in XQuery, refers to raising all possible type errors at analysis (compile) time rather than evaluation (run) time. This is sometimes referred to as pessimistic static typing, where the philosophy is to raise any errors that could possibly happen, not just those that it knows will happen. The static typing feature of XQuery is optional; implementations are not required to support static typing, and many do not fully support it.

The fact that a processor doesn’t support this feature doesn’t mean that it is doing no compile-time analysis. It might use the analysis transparently for optimization purposes, or it might raise some errors at compile time; but in this case, it will raise errors optimistically. It will only raise errors when it can see that there is definitely something wrong, like in the expression "x" + 3, and not simply in cases of ambiguity, as in $x + 3, where the value of $x depends on some input data.

Static typing has the advantages of allowing type errors to be caught earlier and more reliably, and can help some implementations optimize queries. However, as you will see in this chapter, it can also be an irritation to query authors in that it raises many “false” errors.

As part of the static typing process, the processor checks all expressions in a query and assigns them a static type, which is the supplied type of the expression. For example, the expression "abc" is assigned the static type of xs:string. The expression count(doc("catalog.xml")//product) is assigned the static type of xs:integer, which is the return type of the count function.

A type error is raised when a function or operator expects a value of a certain type and a parameter or operand of an incompatible type is used.

substring(doc("catalog.xml")//product[number = 557]/name, 1, 10)

The Typeswitch Expression

The typeswitch expression provides a convenient syntax for performing special processing based on the type of an expression. An example is shown in Example 15-1. This example uses user-defined schema types, which are explained in the previous chapter.

declare namespace prod = "http://datypic.com/prod";
typeswitch ($myProd)
  case element(*, prod:HatType) return xs:string($myProd/size)
  case element(*, prod:ShirtType)
       return xs:string(concat($myProd/size/@system, ": ",
                               $myProd/size))
  case element(*, prod:UmbrellaType) return "none"
  default return "n/a"

The example assumes that $myProd is bound to a product element. In the schema, assume that product elements are declared to have type prod:ProductType. However, in the input document, a product element may carry an xsi:type attribute that indicates another type that is derived by extension from prod:ProductType, such as prod:HatType, prod:ShirtType, or prod:UmbrellaType.

prod:ProductType itself does not allow a size child. Depending on which subtype it has, it may or may not have a size child. The typeswitch expression will return a different value depending on the type annotation of the product element.

The syntax of a typeswitch expression is shown in Figure 15-1. The typeswitch keyword is followed by an expression in parentheses (called the operand expression), which evaluates to the sequence whose type is to be evaluated. This is followed by one or more case clauses, plus a required default clause that indicates the value if none of the case clauses applies.

Figure 15-1. Syntax of a typeswitch expression

The processor uses sequence type matching (described in “Sequence Type Matching”) to determine whether a case clause applies. This means that if the type of the items in the sequence is the same as, or is derived from, the type identified by the case clause, it matches. If more than one case clause is applicable, the first one is used. Remember, with sequence type matching, it is not enough that the items are valid according to the specified type, they must actually have been validated and have that type (or a type derived from it) as their type annotation.

Starting in version 3.0, you can specify multiple sequence types, separated by vertical bars, in a single case clause. For example, case xs:float | xs:double could be used to choose that case if the expression matches either sequence type xs:float or xs:double.

Each of the case and default clauses can have an optional variable name before the return keyword. That variable is bound to the value of the operand expression. This is useful if the return clause is dependent on the sequence being tested. In Example 15-2, the $h and $s variables are bound to the $myProd value, and the return clause references the variable.

declare namespace prod = "http://datypic.com/prod";
typeswitch ($myProd)
  case $h as element(*, prod:HatType) return xs:string($h/size)
  case $s as element(*, prod:ShirtType)
       return xs:string(concat($s/size/@system, ": ", $s/size))
  case element(*, prod:UmbrellaType) return "none"
  default return "n/a"

The typeswitch expression can serve as shorthand for multiple if-then-else expressions that use instance of expressions to determine the type of the variable. Example 15-3 shows this alternative, which is similar to Example 15-2.

declare namespace prod = "http://datypic.com/prod";
if ($myProd instance of element(*, prod:HatType))
then xs:string($myProd/size)
else if ($myProd instance of element(*, prod:ShirtType))
     then xs:string(concat($myProd/size/@system, ": ", $myProd/size))
     else if ($myProd instance of element(*, prod:UmbrellaType))
          then "none"
          else "n/a"

However, there is an important difference between the two: an implementation that supports static typing will raise a type error with Example 15-3. This is because, as far as the processor knows, $myProd is of type prod:ProductType, which does not allow a size child. Even though the processor is aware that there are subtypes that allow a size child, the static typing feature does not extend to parsing out the test expressions (after if) to determine that you would never evaluate the expression $myProd/size on anything that didn’t allow a size child. The typeswitch expression in Example 15-2, on the other hand, assures the processor that the branch that contains $h/size will only ever be evaluated for elements of type prod:HatType. Remember that static typing is pessimistic; it will give you an error if anything could go wrong, not just if it knows that things will go wrong.

The Treat Expression

The treat expression, like the typeswitch expression, is used to assure the processor that only values of a certain type will participate in a particular function or operation. The syntax of a treat expression is shown in Figure 15-2.

Figure 15-2. Syntax of a treat expression

Building on the prod:ProductType/prod:HatType example from the previous section, suppose you would like to display the size of a product, if it is a hat. Although prod:ProductType doesn’t allow a size child, prod:HatType does. You could use the query shown in Example 15-4.

declare namespace prod = "http://datypic.com/prod";
if ($myProd instance of element(*, prod:HatType))
then <p>The size is: {data($myProd/size)}</p>
else ()

It tests to see if the product is a hat, and if it is, constructs a p element that contains its size. Unfortunately, an implementation that supports static typing will raise a type error with this query. This is because, as far as the processor knows, $myProd has type prod:ProductType, which does not allow a size child. As discussed in the previous section, it does not matter that you check the type of $myProd in the enclosing test expression.

Example 15-5 shows a revised query that uses a treat expression to assure the processor that $myProd is indeed an element of type prod:HatType.

declare namespace prod = "http://datypic.com/prod";
if ($myProd instance of element(*, prod:HatType))
then
  <p>The size is: {data( ($myProd treat as element(*, prod:HatType))/size)}</p>
else ()

Unlike a cast expression or a type constructor, the treat expression does not actually change the type of $myProd. It doesn’t need to, because the type of $myProd should already be prod:HatType or some matching type. Like other static-typing-related expressions, it simply postpones any errors to runtime by saying, “I know that all the values are going to be valid prod:HatType values, so don’t raise an error during the analysis phase.”

If it turns out later during the evaluation phase that there is a $myProd value that does not match prod:HatType, the error is raised at that time. The rules of sequence type matching are used to determine whether the value matches. In this particular example, it will never raise this error because it checks the type of $myProd before evaluating the /size path.

If you’re familiar with casts in Java or C#, you’ll recognize that most casts in those languages are assertions (like treat as) rather than actual type conversions. XQuery uses cast as to mean a type conversion, and treat as to mean a type assertion.

Type Declarations

Some expressions, namely FLWORs, quantified expressions, switch expressions, and global variable declarations, allow the use of a type declaration to force the static type of an expression. A type declaration uses the keyword as, followed by a sequence type. The sequence types used in these expressions follow the syntax described in “Sequence Types”.

declare namespace prod = "http://datypic.com/prod";
for $prod as element(*, prod:ProductType) in doc("catalog.xml")/catalog/*
order by $prod/name
return $prod/name

every $number as element(*, xs:integer) in
  doc("catalog.xml")//number satisfies ($number > 0)

declare variable $prodCount as xs:decimal
  := count(doc("catalog.xml")//product/number);

The zero-or-one, one-or-more, and exactly-one Functions

Three functions relate specifically to static typing: zero-or-one, one-or-more, and exactly-one. These functions are useful when static typing is in effect, to override apparent static type errors.

Each of the functions takes a single argument and either returns the argument as is or raises an error if the argument is a sequence containing the wrong number of items. For example, when calling the zero-or-one function, if the argument is a sequence of zero or one items, it is returned. If it is a sequence of more than one item, error FORG0003 is raised.

Earlier in this chapter, we saw how the expression:

number(doc("prices.xml")//prod[@num = 557]/price)

will cause a static error when static typing is in effect. This is because, as far as the processor knows, there could be more than one price element that matches that criterion, while the number function’s signature requires that only zero or one item be provided. A static error can be avoided by using the expression:

number (zero-or-one(doc("prices.xml")//prod[@num = 557]/price))

In this case, no static error is raised. Rather, a dynamic error is raised if more than one price element is returned by the path expression. This is useful if you know that there will only be one product with number 557 in the document, and wish to override the static error.