XSLT and XPath function reference in alphabetical order

(Excerpt from “XSLT 2.0 & XPath 2.0” by Frank Bongers, chapter 5, translated from German)

A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

fn:deep-equal

Category:

Functions for sequences

Origin:

XPath 2.0

Return value:

A Boolean value xs:boolean; the value true or false, depending on whether the sequences compared match or do not match regarding values and order of the items.

Call/Arguments:

fn:deep-equal($sequence1, $sequence2, $collation-URI?)

$sequence1:

A sequence of any number of items of any type. If the first sequence is empty, the function returns false, provided that the second sequence is not empty, too. When comparing two sequences by fn:deep-equal(), the order of the passing on does not matter.

$sequence2:

A sequence of any number of items of any type. If the second sequence is empty, the function returns false, provided that the first sequence is not empty, too.

$collation-URI:

Optional. The third argument consists of a xs:string string which names the URI string of the collation to be applied. The value has to lexically correspond to the xs:anyURI type. If this is not the case, an error message is outputted (»Invalid collationURI«). If no third argument is passed on, the default collation is used for comparing string values. If there are no items of xs:string type contained in the sequences to be compared, the collation instruction is ignored.

Purpose of use:

The fn:deep-equal() function is used in order to determine the equality – not the identity! – of two sequences, and returns the Boolean value true just exactly in case all items of both sequences correspond in terms of value in pairs in the order passed on.

If both input sequences are empty, the function returns true. If the sequences are not empty but of different length, it returns false. When comparing, different methods are used depending on whether the items to be compared are values or nodes.

Comparison of items with atomic values:

Corresponding items with atomic values are directly compared whereby the comparison is made according to the eq operator. For all atomic types, with the exception of strings, the equality can directly be determined by means of the values.

Exception when comparing the NaN value:
If two numerical items to be compared have the value NaN, they are not to be considered as equal (according to the definition of the op:numeric-equal() operator).

For comparisons between strings, the default collation or the collation stated as third argument is used. The actual comparison corresponds to the procedure of fn:compare(), whereas in this case only equality or inequality is crucial.

Comparison of nodes:

If two items to be compared are nodes, a comparison of their contents has to be made on all lower hierarchical levels in order to determine equality (deep equal). In case the tested node contains further nodes inside, the test has to be applied recursively.

For the determination of the equality of two nodes it is not necessary that both nodes have the same type annotation and the same in their scope valid namespaces. For the nodes being directly compared as parts of the sequences, neither their parent nodes nor their base URI play a role.

In case the nodes to be compared are element nodes, the order of possible attributes is not important (but, of course, their existence and their value). However, the order of possible contained child nodes, with the exception of comments and Processing Instructions, is relevant. During the comparison, the PIs only play a role when they directly appear as items in the sequences passed on, in other cases – since they are not information-bearing – they are ignored.

Simply put, two nodes are then considered as equal if they are equal themselves, have the same attributes and their child nodes (except for comments and PIs) are equal in pairs in the predefined order.

More particularly, the comparison fails if:

  • Both nodes belong to different types (node kinds).
  • Both nodes have QNames as identifiers which differ in expanded form.
  • The compared nodes are text nodes, comments, Processing Instructions or namespace nodes whose string values are unequal on the basis of the used collation.
  • They are attribute nodes or element nodes with simple content whose contents, according to the application of fn:data() evaluated as xs:untypedAtomic, are unequal on the basis of the used collation.
  • They are element nodes with attributes and there is no same-named equivalent with the same string value for each attribute.
  • They are element nodes with child nodes and for one of the child nodes (regardless of the comments and PIs) the application of fn:deep-equal() fails.

Example 1 - comparison of two nodes:

Source document:

<?xml version="1.0" encoding="UTF-8"?>
<example>
   <test>
      <a><b><c/></b></a>
   </test>
   <test>
      <a><b><c/></b></a>
   </test>
   <test>
      <a><different/></a>
   </test>
</example>

The document contains three times a <test> element, twice with identical, once with a different content.

The stylesheet (excerpt):

<xsl:template match="example">
<result>
Node 1 and Node 1 are "deep-equal":
<xsl:value-of select="fn:deep-equal((test[1]), (test[1]))"/>
Node 1 and Node 2 are "deep-equal":
<xsl:value-of select="fn:deep-equal((test[1]), (test[2]))"/>
Node 1 and Node 3 are "deep-equal":
<xsl:value-of select="fn:deep-equal((test[1]), (test[3]))"/>
</result>
</xsl:template>

The fn:deep-equal() function receives as input value two sequences of one node each of the source document.

Result:

<?xml version="1.0" encoding="UTF-8"?>
<result>
Node 1 and Node 1 are "deep-equal": true
Node 1 and Node 2 are "deep-equal": true
Node 1 and Node 3 are "deep-equal": false
</result>

The function determines the equality of the first and the second instance of the <test> element and the inequality of the first and the third one.

Although the function also determines the equality of the first instance of the element with itself – this is not suitable as a test for identity.

Function definition:

XPath 1.0:

The function is not available.

XPath 2.0:

fn:deep-equal($parameter1 as item()*,

$parameter2 as item()*) as xs:boolean

fn:deep-equal($parameter1 as item()*,

$parameter2 as item()*,

$collation as string) as xs:boolean

   

<< back next >>

 

 

 


Copyright © Galileo Press, Bonn 2008
Printing of the online version is permitted exclusively for private use. Otherwise this chapter from the book "XSLT 2.0 & XPath 2.0" is subject to the same provisions as those applicable for the hardcover edition: The work including all its components is protected by copyright. All rights reserved, including reproduction, translation, microfilming as well as storage and processing in electronic systems.


Galileo Press, Rheinwerkallee 4, 53227 Bonn, Germany