<?xml version="1.0" encoding="iso-8859-1"?>
<?xml-stylesheet href="../../make-menu.xsl" type="text/xsl"?><html>
<head>
<this-is section="extensibility" page="converting-args.net"
subpage="converting-atomic.net"/>
<!--
Generated at 2011-12-09T20:47:22.916Z--><title>Saxonica: XSLT and XQuery Processing: Converting Atomic Values and Sequences</title>
<meta name="coverage" content="Worldwide"/>
<meta name="copyright" content="Copyright Saxonica Ltd"/>
<meta name="title"
content="Saxonica: XSLT and XQuery Processing: Converting Atomic Values and Sequences"/>
<meta name="robots" content="noindex,nofollow"/>
<link rel="stylesheet" href="../../saxondocs.css" type="text/css"/>
</head>
<body class="main">
<h1>Converting Atomic Values and Sequences</h1>
<p>The following conversions are supported between the static type of the supplied value of the argument,
and the declared
.NET type of the argument. The mappings are given in order of preference; a type that appears earlier
in the list has smaller "conversion distance" than one appearing later. These priorities are used to decide
which method to call when the class has several methods of the same name. Simple classes (such as boolean)
are acceptable wherever the corresponding wrapper class (Boolean) is allowed. Class names shown in
italics are Saxon-specific classes.</p>
<p>If the value is a <i>.NET external object</i> (typically the result of a call to another extension function,
then the underlying .NET object is passed to the method. An error will occur if it is the wrong .NET type.</p>
<p>If the required type is one of the types used in the <code>Saxon.Api</code> namespace to represent XPath values (for example
<code>XdmValue</code>, <code>XdmNode</code>, <code>XdmAtomicValue</code>, then the value is converted to an instance
of this class and passed over unchanged. If the expected type is <code>XdmAtomicValue</code> and the supplied value is
a node, the node will be atomized (this must result in a single atomic value). Use of types such as <code>XdmValue</code>
is available only when the query or transformation is invoked using the .NET API, it does not work when running from the
command line.</p>
<p>If the static type of the supplied value allows a sequence of more than one item, then Saxon looks for a method
that expects a <code>net.sf.saxon.om.SequenceIterator</code>, a <code>net.sf.saxon.value.Value</code>,
an <code>ICollection</code>
or an array in that order. (The first two classes are Saxon-specific). In all these cases except the last the item
type of the supplied value plays no role.</p>
<p>Nodes in the supplied sequence are atomized only if the .NET method requires an atomic type such as an integer
or string. If the method requires an ICollection, then the contents of the sequence will be supplied <i>as is</i>. The objects in
the List will typically be Saxon <a class="bodylink" href="../../javadoc/net/sf/saxon/om/Item.html"><code>net.sf.saxon.om.Item</code></a> objects. (Saxon does not yet recognize the generic types in .NET 2.0,
which allow the item type of a collection to be declared). If atomization is required, you can force it by calling the
<code>data()</code> function.</p>
<p>If the required type is an array, Saxon will attempt to create an array of the required type. This will not always succeed,
for example if the array has type <code>X[]</code> where X is an interface rather than a concrete class. If it is an array of items
or nodes, the nodes in the supplied sequence will be inserted into the array directly; if it is an array of a type such as integer or
double, the sequence will first be atomized.</p>
<p>If the supplied value is a singleton (a sequence of one item) then the type of that item is decisive. If
it is a sequence of length zero or more than one, then the general rules for a sequence are applied, and the
types of the items within the sequence are irrelevant.</p>
<p>If the supplied value contains more than item and only a single item is expected, an error is reported. There is no
implicit extraction of the first value (as happened in earlier releases).</p>
<table>
<tr>
<td content="para">
<p>
<b>Supplied type</b>
</p>
</td>
<td content="para">
<p>
<b>Required type</b>
</p>
</td>
</tr>
<tr>
<td content="para">
<p>boolean</p>
</td>
<td content="para">
<p>
<i>BooleanValue</i>, bool</p>
</td>
</tr>
<tr>
<td content="para">
<p>dateTime</p>
</td>
<td content="para">
<p>
<i>DateTimeValue</i>, Date</p>
</td>
</tr>
<tr>
<td content="para">
<p>date</p>
</td>
<td content="para">
<p>
<i>DateValue</i>, Date</p>
</td>
</tr>
<tr>
<td content="para">
<p>decimal</p>
</td>
<td content="para">
<p>
<i>DecimalValue</i>, decimal, double, float</p>
</td>
</tr>
<tr>
<td content="para">
<p>double</p>
</td>
<td content="para">
<p>
<i>DoubleValue</i>, double</p>
</td>
</tr>
<tr>
<td content="para">
<p>duration</p>
</td>
<td content="para">
<p>
<i>DurationValue</i>
</p>
</td>
</tr>
<tr>
<td content="para">
<p>float</p>
</td>
<td content="para">
<p>
<i>FloatValue</i>, float, double</p>
</td>
</tr>
<tr>
<td content="para">
<p>integer</p>
</td>
<td content="para">
<p>
<i>IntegerValue</i>, decimal, long, integer, short, byte, double, float</p>
</td>
</tr>
<tr>
<td content="para">
<p>string</p>
</td>
<td content="para">
<p>
<i>StringValue</i>, string</p>
</td>
</tr>
<tr>
<td content="para">
<p>anyURI</p>
</td>
<td content="para">
<p>
<i>AnyURIValue</i>, Uri, string</p>
</td>
</tr>
<tr>
<td content="para">
<p>QName</p>
</td>
<td content="para">
<p>
<i>QNameValue</i>
</p>
</td>
</tr>
<tr>
<td content="para">
<p>node</p>
</td>
<td content="para">
<p>
<i>SingletonNodeSet</i>, NodeList, (Element, Attr, Document, DocumentFragment,
Comment, Text, ProcessingInstruction, CharacterData), Node, Boolean,
Byte, Character, Double, Float, Integer, Long, Short, (String, CharSequence), Object</p>
</td>
</tr>
<tr>
<td content="para">
<p>sequence</p>
</td>
<td content="para">
<p>
<i>SequenceIterator</i>, <i>SequenceValue</i>, List, NodeList, <i>NodeInfo</i>, Node, (String, CharSequence), Boolean,
Byte, Character, Double, Float, Integer, Long, Short, Object</p>
</td>
</tr>
</table>
<p>Saxon tries to select the appropriate method based on the <i>static type</i> of the arguments
to the function call. If there are several candidate methods, and there is insufficient information available to decide
which is most appropriate, an error is reported. The remedy is to cast the arguments to a more specific type.</p>
<table width="100%">
<tr>
<td>
<p align="right"><a class="nav" href="converting-node.net.xml">Next</a></p>
</td>
</tr>
</table>
</body>
</html>
