Tuple types

Wherever an item type can be used (for example, in the type signature of a function or variable, or in an instance of expression), Saxon allows a tuple type to appear. The syntax is:

"tuple" "(" fieldName ("as" sequenceType)? ("," fieldName ("as" sequenceType)? )* ("," "*")? ")"

where fieldName is either an NCName or a string literal. A final ", *" at the end of the list of fields indicates that the tuple type is extensible: additional fields beyond those that are explicitly declared are permitted to appear in the map. If the "as" clause is absent for any field, the assumed type is item()+.

For example:

tuple(ssn as xs:string, emp as element(employee))

or:

tuple('first name', 'middle initial', 'last name', *)

The instances of a tuple type are maps. A tuple type is essentially a way of defining a more precise type for maps. The first example will be satisfied by any map that has an entry whose key is "ssn" and whose value is a string, plus an entry whose key is "emp" and whose value is an employee element. The second example matches any map with entries having the keys "first name" and "middle initial" and "last name, regardless of the types of the values. Because the default type item()+ does not permit an empty sequence, all three fields are required.

More formally, a value M is an instance of a tuple type tuple(N1 as T1, N2 as T2, ...) if and only if all the following conditions are true:

M is a map
For every (N, T) pair in the tuple definition map:get(M, N) instance of T returns true. (Note, this allows the case where there is no entry with key M, provided that the type T permits an empty sequence.)
If the tuple type is not extensible (that is, there is no final ", *" after the list of field names), then every key present in the map is a string equal to one of the field names appearing in the tuple definition, when compared using codepoint collation.

So for every field defined in the tuple definition, the map will typically contain an entry whose key matches the field name and whose value matches the corresponding type. The entry is allowed to be absent only if the type definition indicates that an empty sequence would be acceptable. Additional entries are allowed only if the type definition indicates that it is extensible.

The default type is item()+, which allows the value of the corresponding field to be anything other than an empty sequence. If you want to make the field optional, you need to assign a type that allows the empty sequence, for example xs:string?.

Since a tuple is a map, fields can be accessed using the lookup syntax $T?NNN where $T is an expression that returns a tuple, and NNN is the name of the field. Saxon allows the field name to be written as a string in quotes if it is not an NCName, for example $T?"date of birth".

Using tuples makes stronger type checking possible. With a general-purpose map, any atomic value can be supplied as a key, and the map:get() function (or a dynamic call on the map as a function) returns an empty sequence if the entry is not present. With tuples, however, supplying a key value that is not a string, or that is not one of the known field names, results in a static type error if it can be detected at compile time. Furthermore, if $T is known to be a tuple type, then the type of an expression such as $T?field can be statically inferred, which again enables better error detection and better optimization.

Although $T?N results in a static type error if T is a non-extensible tuple type that doesn't define field N, a run-time reference $T("N") works the same way as any other dynamic map lookup, returning an empty sequence.

Tuple types are useful where maps are used to hold information with a regular structure; for example when a function accepts maps as input or returns maps as output. Declaring the argument or result type of a function as a tuple type often gives better information about the expected contents than when it is declared as a map.

Tuple types can be used as patterns, to match maps (regardless whether the value was originally declared as a tuple or not). This can be especially useful when processing JSON. For example, if a JSON document containing the object {'long': 23.1234, 'lat':55.624} is parsed using the parse-json() or json-doc() functions, then the resulting map can be processed using a template rule declared with match="tuple(lat, long)".

Tuple types fit into the type hierarchy as subtypes of maps. A tuple type T1 is a subtype of another tuple type T2 if every possible instance of T1 is a permitted instance of T2 (this takes into account whether either or both tuple types are extensible). Similarly, a tuple type T is a subtype of a map type M if every possible instance of T is a permitted instance of M. By extension, because maps are functions, tuples are also functions, and tuple types are thus subtypes of function types.

In XSLT, as described below, it is possible to declare the type in both portable and Saxon-specific syntax, for example <xsl:param name="location" as="map(xs:string, xs:double)" saxon:as="tuple(x as xs:double, y as xs:double)"/>.

A map that contains additional entries beyond those defined in an extensible tuple type still conforms to the type (so if the expected type of a function argument is tuple(a as xs:integer, b as xs:integer, *), then you can supply any map that contains these two fields, even if it also contains others). A consequence of making a tuple type extensible is that incorrect static references are less likely to result in a compile-time error.

The following XSLT example shows a couple of functions from a library designed to perform complex number arithmetic, where a complex number is defined as the type tuple(r as xs:double, i as xs:double):

<xsl:function name="cx:complex" as="tuple(r as xs:double, i as xs:double)"> <xsl:param name="real" as="xs:double"/> <xsl:param name="imag" as="xs:double"/> <xsl:sequence select="map{'r':$real, 'i':$imag}"/> </xsl:function> <xsl:function name="cx:add" as="tuple(r as xs:double, i as xs:double)"> <xsl:param name="x" as="tuple(r as xs:double, i as xs:double)"/> <xsl:param name="y" as="tuple(r as xs:double, i as xs:double)"/> <xsl:sequence select="cx:complex($x?r + $y?r, $x?i + $y?i)"/> </xsl:function>

The same functions could be written in XQuery:

declare function cx:complex ($real as xs:double, $imag as xs:double) as tuple(r as xs:double, i as xs:double) { map{'r':$real, 'i':$imag} }; declare function cx:add ($x as tuple(r as xs:double, i as xs:double), $y as tuple(r as xs:double, i as xs:double)) as tuple(r as xs:double, i as xs:double) { cx:number($x?r + $y?r, $x?i + $y?i) };

Two additional Saxon extensions help to improve the usability of tuple types:

A commonly used type can be referenced using a type alias, for example as="type(cx:complex)". Type aliases are available in both XSLT and XQuery, and are described in Type Aliases. Type aliases go some way towards hiding the implementation details of the type, and allowing the implementation to be changed without affecting users of the function library; in addition they simply make the code more readable.
In XSLT only, elements that have an as attribute to define the type of a variable, function, or parameter, also have an optional saxon:as attribute which allows additional type information to be supplied using Saxon extension syntax. If both attributes are present, then the type specified in saxon:as must be a subtype of the type specified in the as attribute. Typical usage might be <xsl:param name="x" as="map(*)" saxon:as="tuple(r as xs:double, i as xs:double)"/>. This device allows tuple types to be used without compromising the portability of the stylesheet to an XSLT 3.0 processor that does not recognize Saxon's extension syntax (an XSLT 3.0 processor that does not recognize the saxon:as attribute is required to ignore it).