<?xml version="1.0" encoding="iso-8859-1"?>
<?xml-stylesheet href="../../make-menu.xsl" type="text/xsl"?><html>
<head>
<this-is section="extensibility" page="functions" subpage="choosing-overload"/>
<!--
Generated at 2011-12-09T20:47:22.916Z--><title>Saxonica: XSLT and XQuery Processing: Choosing among overloaded methods</title>
<meta name="coverage" content="Worldwide"/>
<meta name="copyright" content="Copyright Saxonica Ltd"/>
<meta name="title"
content="Saxonica: XSLT and XQuery Processing: Choosing among overloaded methods"/>
<meta name="robots" content="noindex,nofollow"/>
<link rel="stylesheet" href="../../saxondocs.css" type="text/css"/>
</head>
<body class="main">
<h1>Choosing among overloaded methods</h1>
<p>If there is no method with the required name and number of parameters, Saxon reports a compile-time error.</p>
<p>If there is only one method with the required name and number of parameters, then Saxon chooses it,
and goes on to the next stage, which allocates converters for the supplied arguments.</p>
<p>If there are several methods in the class that match the localname, and that have the correct number
of arguments, then the system attempts
to find the one that is the best fit to the types of the supplied arguments: for example if the
call is <code>f(1,2)</code> then a method with two <code>int</code> arguments will be preferred
to one with two <code>float</code>
arguments. The rules for deciding between methods are quite complex. Essentially, for each candidate method,
Saxon calculates the "distance" between the types of the supplied arguments and the Java class of the
corresponding method in the method's
signature, using a set of tables. For example, the distance between the XPath data type <code>xs:integer</code>
and the Java class <code>long</code> is very small, while the distance between an XPath <code>xs:integer</code> and a Java <code>Object</code>
is much larger. If there is one candidate method where the distances of all arguments are less-than-or-equal-to
the distances computed for other candidate methods, and the distance of at least one argument is smaller,
then that method is chosen.</p>
<p>If there are several methods with the same name and the correct number of arguments, but none is
preferable to the others under these rules, an error is reported: the message indicates that there is
more than one method that matches the function call.</p>
<p>This binding is carried out statically, using the static types of the supplied arguments, not the dynamic
types obtained when the arguments are evaluated. If there is insufficient static type information to distinguish
the candidate methods, an error is reported. You can supply additional type information using the <code>treat as</code>
expression, or by casting. Often it is enough simply to declare the types of the variables used as arguments to the function call.</p>
<p>The distances are calculated using the following rules (in order).</p>
<ul>
<li content="para">
<p>If the required type is <code>Object</code>, the distance is 100.</p>
</li>
<li>
<p>If the required type is one of the following Saxon-specific classes (or is a superclass of that class), then the distance is
as given:</p>
<ul>
<li content="para">
<p>
<a class="bodylink" href="../../javadoc/net/sf/saxon/om/SequenceIterator.html"><code>net.sf.saxon.om.SequenceIterator</code></a>: 26</p>
</li>
<li content="para">
<p>
<a class="bodylink" href="../../javadoc/net/sf/saxon/om/ValueRepresentation.html"><code>net.sf.saxon.om.ValueRepresentation</code></a>: 25</p>
</li>
<li content="para">
<p>
<a class="bodylink" href="../../javadoc/net/sf/saxon/value/Value.html"><code>net.sf.saxon.value.Value</code></a>: 24</p>
</li>
<li content="para">
<p>
<a class="bodylink" href="../../javadoc/net/sf/saxon/om/Item.html"><code>net.sf.saxon.om.Item</code></a>: 23</p>
</li>
<li content="para">
<p>
<a class="bodylink" href="../../javadoc/net/sf/saxon/om/NodeInfo.html"><code>net.sf.saxon.om.NodeInfo</code></a>: 22</p>
</li>
<li content="para">
<p>
<a class="bodylink" href="../../javadoc/net/sf/saxon/om/DocumentInfo.html"><code>net.sf.saxon.om.DocumentInfo</code></a>: 21</p>
</li>
<li content="para">
<p>
<a class="bodylink" href="../../javadoc/net/sf/saxon/value/AtomicValue.html"><code>net.sf.saxon.value.AtomicValue</code></a>, 20</p>
</li>
</ul>
<p><i>Note that Saxon does not recognize the classes defined in the s9api package for use with extension functions
(for example, <a class="bodylink" href="../../javadoc/net/sf/saxon/s9api/XdmNode.html"><code>XdmNode</code></a> and <a class="bodylink" href="../../javadoc/net/sf/saxon/s9api/XdmAtomicValue.html"><code>XdmAtomicValue</code></a>)</i></p>
</li>
<li>
<p>If the static type of the supplied argument allows more than one item, the distance is the first one of the following that applies:</p>
<ul>
<li content="para">
<p>If the method expects <code>java.lang.Collection</code> or a class that implements <code>Collection</code>: 30</p>
</li>
<li content="para">
<p>If the method expects an array: 31</p>
</li>
<li content="para">
<p>In all other cases: 80</p>
</li>
</ul>
<p>Note that the item
type of the supplied value plays no role in choosing the method to call, even though it could potentially be used to disambiguate
overloaded methods when arrays or parameterized collection types are used.</p>
</li>
<li>
<p>Otherwise (the static type allows only one item):</p>
<ul>
<li content="para">
<p>If the static type of the supplied value matches <code>node()</code>: 80</p>
</li>
<li content="para">
<p>If the static type of the supplied value is a wrapped Java object, then 10 if the class of the object
matches the required Java class, else -1 (meaning this method is not a candidate)</p>
</li>
<li content="para">
<p>Otherwise, the value given in the table of atomic types below.</p>
</li>
</ul>
</li>
</ul>
<p>The distances for atomic types are given below. If there is no entry for the combination of supplied type and required
type, the method is removed from consideration. For unboxed types (int, float, etc) the distance is always one less than
the corresponding boxed type (java.lang.Integer, java.lang.Float).</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>xs:boolean</p>
</td>
<td content="para">
<p>
<i>BooleanValue</i>, Boolean</p>
</td>
</tr>
<tr>
<td content="para">
<p>xs:dateTime</p>
</td>
<td content="para">
<p>
<i>DateTimeValue</i>, Date</p>
</td>
</tr>
<tr>
<td content="para">
<p>xs:date</p>
</td>
<td content="para">
<p>
<i>DateValue</i>, Date</p>
</td>
</tr>
<tr>
<td content="para">
<p>xs:decimal</p>
</td>
<td content="para">
<p>
<i>DecimalValue</i>, BigDecimal, Double, Float</p>
</td>
</tr>
<tr>
<td content="para">
<p>xs:double</p>
</td>
<td content="para">
<p>
<i>DoubleValue</i>, Double</p>
</td>
</tr>
<tr>
<td content="para">
<p>xs:duration</p>
</td>
<td content="para">
<p>
<i>DurationValue</i>
</p>
</td>
</tr>
<tr>
<td content="para">
<p>xs:float</p>
</td>
<td content="para">
<p>
<i>FloatValue</i>, Float, Double</p>
</td>
</tr>
<tr>
<td content="para">
<p>xs:integer</p>
</td>
<td content="para">
<p>
<i>IntegerValue</i>, BigInteger, BigDecimal, Long, Integer, Double, Float</p>
</td>
</tr>
<tr>
<td content="para">
<p>xs:short</p>
</td>
<td content="para">
<p>
<i>IntegerValue</i>, BigInteger, BigDecimal, Long, Integer, Short, Double, Float</p>
</td>
</tr>
<tr>
<td content="para">
<p>xs:byte</p>
</td>
<td content="para">
<p>
<i>IntegerValue</i>, BigInteger, BigDecimal, Long, Integer, Short, Byte, Double, Float</p>
</td>
</tr>
<tr>
<td content="para">
<p>xs:string</p>
</td>
<td content="para">
<p>
<i>StringValue</i>, (String, CharSequence)</p>
</td>
</tr>
<tr>
<td content="para">
<p>xs:anyURI</p>
</td>
<td content="para">
<p>
<i>AnyURIValue</i>, java.net.URI, java.net.URL, (String, CharSequence)</p>
</td>
</tr>
<tr>
<td content="para">
<p>xs:QName</p>
</td>
<td content="para">
<p>
<i>QNameValue</i>, javax.xml.namespace.QName</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>
<p>A required type of one of the Java primitive types such as <code>int</code> or <code>bool</code> is treated as
equivalent to the corresponding boxed type (<code>Integer</code> or <code>Boolean</code>), except that with the boxed
types, an empty sequence can be supplied in the function call and is translated to a Java null value as the actual
argument.</p>
<p>The fact that a particular method is chosen as the target does not give a guarantee that conversion of the arguments
will succeed at run-time. This is particularly true with methods that expect a node in an external object model such as
DOM or XOM.</p>
<table width="100%">
<tr>
<td>
<p align="right"><a class="nav" href="staticmethods.xml">Next</a></p>
</td>
</tr>
</table>
</body>
</html>
