XPath/XQuery Functions: Sequence

www.altova.com Expand/Collapse All Print this Topic Previous Page Up One Level Next page

Home >  Appendices > XSLT and XPath/XQuery Functions > Altova Extension Functions >

XPath/XQuery Functions: Sequence

Altova's sequence extension functions can be used in XPath and XQuery expressions and provide additional functionality for the processing of data. The functions in this section can be used with Altova's XPath 3.0 and XQuery 3.0 engines. They are available in XPath/XQuery contexts.

 

Note about naming of functions and language applicability

Altova extension functions can be used in XPath/XQuery expressions. They provide additional functionality to the functionality that is available in the standard library of XPath, XQuery, and XSLT functions. Altova extension functions are in the Altova extension functions namespace, http://www.altova.com/xslt-extensions, and are indicated in this section with the prefix altova:, which is assumed to be bound to this namespace. Note that, in future versions of your product, support for a function might be discontinued or the behavior of individual functions might change. Consult the documentation of future releases for information about support for Altova extension functions in that release.

 

XPath functions (used in XPath expressions in XSLT):

XP1 XP2 XP3.1

XSLT functions (used in XPath expressions in XSLT):

Xslt1 XSLT2 XSLT3

XQuery functions (used in XQuery expressions in XQuery):

XQ1 XQ3.1

 

 

Click to expand/collapseattributes [altova:]

altova:attributes(AttributeName as xs:string) as attribute()*     XP3.1 XQ3.1

Returns all attributes that have a local name which is the same as the name supplied in the input argument, AttributeName. The search is case-sensitive and conducted along the attribute:: axis. This means that the context node must be the parent element node.

altova:attributes("MyAttribute") returns MyAttribute()*

 

altova:attributes(AttributeName as xs:string, SearchOptions as xs:string) as attribute()*     XP3.1 XQ3.1

Returns all attributes that have a local name which is the same as the name supplied in the input argument, AttributeName. The search is case-sensitive and conducted along the attribute:: axis. The context node must be the parent element node. The second argument is a string containing option flags. Available flags are:
r = switches to a regular-expression search; AttributeName must then be a regular-expression search string;
f = If this option is specified, then AttributeName provides a full match; otherwise AttributeName need only partially match an attribute name to return that attribute. For example: if f is not specified, then MyAtt will return MyAttribute;
i = switches to a case-insensitive search;

p = includes the namespace prefix in the search; AttributeName should then contain the namespace prefix, for example: altova:MyAttribute.
The flags can be written in any order. Invalid flags will generate errors. One or more flags can be omitted. The empty string is allowed, and will produce the same effect as the function having only one argument (previous signature). However, an empty sequence is not allowed as the second argument.

altova:attributes("MyAttribute", "rfip") returns MyAttribute()*
altova:attributes("MyAttribute", "pri") returns MyAttribute()*
altova:attributes("MyAtt", "rip") returns MyAttribute()*
altova:attributes("MyAttributes", "rfip") returns no match
altova:attributes("MyAttribute", "") returns MyAttribute()*
altova:attributes("MyAttribute", "Rip") returns an unrecognized-flag error.
altova:attributes("MyAttribute", ) returns a missing-second-argument error.

 

 

Click to expand/collapseelements [altova:]

altova:elements(ElementName as xs:string) as element()*     XP3.1 XQ3.1

Returns all elements that have a local name which is the same as the name supplied in the input argument, ElementName. The search is case-sensitive and conducted along the child:: axis. The context node must be the parent node of the element/s being searched for.

altova:elements("MyElement") returns MyElement()*

 

altova:elements(ElementName as xs:string, SearchOptions as xs:string) as element()*     XP3.1 XQ3.1

Returns all elements that have a local name which is the same as the name supplied in the input argument, ElementName. The search is case-sensitive and conducted along the child:: axis.  The context node must be the parent node of the element/s being searched for. The second argument is a string containing option flags. Available flags are:
r = switches to a regular-expression search; ElementName must then be a regular-expression search string;
f = If this option is specified, then ElementName provides a full match; otherwise ElementName need only partially match an element name to return that element. For example: if f is not specified, then MyElem will return MyElement;
i = switches to a case-insensitive search;

p = includes the namespace prefix in the search; ElementName should then contain the namespace prefix, for example: altova:MyElement.
The flags can be written in any order. Invalid flags will generate errors. One or more flags can be omitted. The empty string is allowed, and will produce the same effect as the function having only one argument (previous signature). However, an empty sequence is not allowed.

altova:elements("MyElement", "rip") returns MyElement()*
altova:elements("MyElement", "pri") returns MyElement()*
altova:elements("MyElement", "") returns MyElement()*
altova:attributes("MyElem", "rip") returns MyElement()*
altova:attributes("MyElements", "rfip") returns no match
altova:elements("MyElement", "Rip") returns an unrecognized-flag error.
altova:elements("MyElement", ) returns a missing-second-argument error.

 

 

Click to expand/collapsefind-first [altova:]

altova:find-first((Sequence as item()*)(Condition( Sequence-Item as xs:boolean)) as item()?     XP3.1 XQ3.1

This function takes two arguments. The first argument is a sequence of one or more items of any datatype. The second argument, Condition, is a reference to an XPath function that takes one argument (has an arity of 1) and returns a boolean. Each item of Sequence is submitted, in turn, to the function referenced in Condition. (Remember: This function takes a single argument.) The first Sequence item that causes the function in Condition to evaluate to true() is returned as the result of altova:find-first, and the iteration stops.

 

altova:find-first(5 to 10, function($a) {$a mod 2 = 0}) returns xs:integer 6

The Condition argument references the XPath 3.0 inline function, function(), which declares an inline function named $a and then defines it. Each item in the Sequence argument of altova:find-first is passed, in turn, to $a as its input value. The input value is tested on the condition in the function definition ($a mod 2 = 0). The first input value to satisfy this condition is returned as the result of altova:find-first (in this case 6).

 

altova:find-first((1 to 10), (function($a) {$a+3=7})) returns xs:integer 4

 

 

Further examples

If the file C:\Temp\Customers.xml exists:

 

altova:find-first( ("C:\Temp\Customers.xml", "http://www.altova.com/index.html"), (doc-available#1) ) returns xs:string C:\Temp\Customers.xml

 

If the file C:\Temp\Customers.xml does not exist, and http://www.altova.com/index.html exists:

 

altova:find-first( ("C:\Temp\Customers.xml", "http://www.altova.com/index.html"), (doc-available#1) ) returns xs:string http://www.altova.com/index.html

 

If the file C:\Temp\Customers.xml does not exist, and http://www.altova.com/index.html also does not exist:

 

altova:find-first( ("C:\Temp\Customers.xml", "http://www.altova.com/index.html"), (doc-available#1) ) returns no result

 

Notes about the examples given above

The XPath 3.0 function, doc-available, takes a single string argument, which is used as a URI, and returns true if a document node is found at the submitted URI. (The document at the submitted URI must therefore be an XML document.)
The doc-available function can be used for Condition, the second argument of altova:find-first, because it takes only one argument (arity=1), because it takes an item() as input (a string which is used as a URI), and returns a boolean value.
Notice that the doc-available function is only referenced, not called. The #1 suffix that is attached to it indicates a function with an arity of 1. In its entirety doc-available#1 simply means: Use the doc-availabe() function that has arity=1, passing to it as its single argument, in turn, each of the items in the first sequence. As a result, each of the two strings will be passed to doc-available(), which uses the string as a URI and  tests whether a document node exists at the URI. If one does, the doc-available() evaluates to true() and that string is returned as the result of the altova:find-first function. Note about the doc-available() function: Relative paths are resolved relative to the the current base URI, which is by default the URI of the XML document from which the function is loaded.

 

 

Click to expand/collapsefind-first-combination [altova:]

altova:find-first-combination((Seq-01 as item()*)(Seq-02 as item()*), (Condition( Seq-01-Item, Seq-02-Item as xs:boolean)) as item()*     XP3.1 XQ3.1

This function takes three arguments:

 

The first two arguments, Seq-01 and Seq-02, are sequences of one or more items of any datatype.
The third argument, Condition, is a reference to an XPath function that takes two arguments (has an arity of 2) and returns a boolean.

 

The items of Seq-01 and Seq-02 are passed in ordered pairs (one item from each sequence making up a pair) as the arguments of the function in Condition. The pairs are ordered as follows.

If   Seq-01 = X1, X2, X3 ... Xn

And  Seq-02 = Y1, Y2, Y3 ... Yn

Then (X1 Y1), (X1 Y2), (X1 Y3) ... (X1 Yn), (X2 Y1), (X2 Y2) ... (Xn Yn)

 

The first ordered pair that causes the Condition function to evaluate to true() is returned as the result of altova:find-first-combination. Note that: (i) If the Condition function iterates through the submitted argument pairs and does not once evaluate to true(), then altova:find-first-combination returns No results; (ii) The result of altova:find-first-combination will always be a pair of items (of any datatype) or no item at all.

 

altova:find-first-combination(11 to 20, 21 to 30, function($a, $b) {$a+$b = 32}) returns the sequence of xs:integers (11, 21)
altova:find-first-combination(11 to 20, 21 to 30, function($a, $b) {$a+$b = 33}) returns the sequence of xs:integers (11, 22)
altova:find-first-combination(11 to 20, 21 to 30, function($a, $b) {$a+$b = 34}) returns the sequence of xs:integers (11, 23)

 

 

Click to expand/collapsefind-first-pair [altova:]

altova:find-first-pair((Seq-01 as item()*)(Seq-02 as item()*), (Condition( Seq-01-Item, Seq-02-Item as xs:boolean)) as item()*     XP3.1 XQ3.1

This function takes three arguments:

 

The first two arguments, Seq-01 and Seq-02, are sequences of one or more items of any datatype.
The third argument, Condition, is a reference to an XPath function that takes two arguments (has an arity of 2) and returns a boolean.

 

The items of Seq-01 and Seq-02 are passed in ordered pairs as the arguments of the function in Condition. The pairs are ordered as follows.

If   Seq-01 = X1, X2, X3 ... Xn

And  Seq-02 = Y1, Y2, Y3 ... Yn

Then (X1 Y1), (X2 Y2), (X3 Y3) ... (Xn Yn)

 

The first ordered pair that causes the Condition function to evaluate to true() is returned as the result of altova:find-first-pair. Note that: (i) If the Condition function iterates through the submitted argument pairs and does not once evaluate to true(), then altova:find-first-pair returns No results; (ii) The result of altova:find-first-pair will always be a pair of items (of any datatype) or no item at all.

 

altova:find-first-pair(11 to 20, 21 to 30, function($a, $b) {$a+$b = 32}) returns the sequence of xs:integers (11, 21)
altova:find-first-pair(11 to 20, 21 to 30, function($a, $b) {$a+$b = 33}) returns No results

 

Notice from the two examples above that the ordering of the pairs is: (11, 21) (12, 22) (13, 23)...(20, 30). This is why the second example returns No results (because no ordered pair gives a sum of 33).

 

 

Click to expand/collapsefind-first-pair-pos [altova:]

altova:find-first-pair-pos((Seq-01 as item()*)(Seq-02 as item()*), (Condition( Seq-01-Item, Seq-02-Item as xs:boolean)) as xs:integer     XP3.1 XQ3.1

This function takes three arguments:

 

The first two arguments, Seq-01 and Seq-02, are sequences of one or more items of any datatype.
The third argument, Condition, is a reference to an XPath function that takes two arguments (has an arity of 2) and returns a boolean.

 

The items of Seq-01 and Seq-02 are passed in ordered pairs as the arguments of the function in Condition. The pairs are ordered as follows.

If   Seq-01 = X1, X2, X3 ... Xn

And  Seq-02 = Y1, Y2, Y3 ... Yn

Then (X1 Y1), (X2 Y2), (X3 Y3) ... (Xn Yn)

 

The index position of the first ordered pair that causes the Condition function to evaluate to true() is returned as the result of altova:find-first-pair-pos. Note that if the Condition function iterates through the submitted argument pairs and does not once evaluate to true(), then altova:find-first-pair-pos returns No results.

 

altova:find-first-pair-pos(11 to 20, 21 to 30, function($a, $b) {$a+$b = 32}) returns 1
altova:find-first-pair-pos(11 to 20, 21 to 30, function($a, $b) {$a+$b = 33}) returns No results

 

Notice from the two examples above that the ordering of the pairs is: (11, 21) (12, 22) (13, 23)...(20, 30). In the first example, the first pair causes the Condition function to evaluate to true(), and so its index position in the sequence, 1, is returned. The second example returns No results because no pair gives a sum of 33.

 

 

Click to expand/collapsefind-first-pos [altova:]

altova:find-first-pos((Sequence as item()*)(Condition( Sequence-Item as xs:boolean)) as xs:integer     XP3.1 XQ3.1

This function takes two arguments. The first argument is a sequence of one or more items of any datatype. The second argument, Condition, is a reference to an XPath function that takes one argument (has an arity of 1) and returns a boolean. Each item of Sequence is submitted, in turn, to the function referenced in Condition. (Remember: This function takes a single argument.) The first Sequence item that causes the function in Condition to evaluate to true() has its index position in Sequence returned as the result of altova:find-first-pos, and the iteration stops.

 

altova:find-first-pos(5 to 10, function($a) {$a mod 2 = 0}) returns xs:integer 2

The Condition argument references the XPath 3.0 inline function, function(), which declares an inline function named $a and then defines it. Each item in the Sequence argument of altova:find-first-pos is passed, in turn, to $a as its input value. The input value is tested on the condition in the function definition ($a mod 2 = 0). The index position in the sequence of the first input value to satisfy this condition is returned as the result of altova:find-first-pos (in this case 2, since 6, the first value (in the sequence) to satisfy the condition, is at index position 2 in the sequence).

 

altova:find-first-pos((2 to 10), (function($a) {$a+3=7})) returns xs:integer 3

 

 

Further examples

If the file C:\Temp\Customers.xml exists:

 

altova:find-first-pos( ("C:\Temp\Customers.xml", "http://www.altova.com/index.html"), (doc-available#1) ) returns 1

 

If the file C:\Temp\Customers.xml does not exist, and http://www.altova.com/index.html exists:

 

altova:find-first-pos( ("C:\Temp\Customers.xml", "http://www.altova.com/index.html"), (doc-available#1) ) returns 2

 

If the file C:\Temp\Customers.xml does not exist, and http://www.altova.com/index.html also does not exist:

 

altova:find-first-pos( ("C:\Temp\Customers.xml", "http://www.altova.com/index.html"), (doc-available#1) ) returns no result

 

Notes about the examples given above

The XPath 3.0 function, doc-available, takes a single string argument, which is used as a URI, and returns true if a document node is found at the submitted URI. (The document at the submitted URI must therefore be an XML document.)
The doc-available function can be used for Condition, the second argument of altova:find-first-pos, because it takes only one argument (arity=1), because it takes an item() as input (a string which is used as a URI), and returns a boolean value.
Notice that the doc-available function is only referenced, not called. The #1 suffix that is attached to it indicates a function with an arity of 1. In its entirety doc-available#1 simply means: Use the doc-availabe() function that has arity=1, passing to it as its single argument, in turn, each of the items in the first sequence. As a result, each of the two strings will be passed to doc-available(), which uses the string as a URI and tests whether a document node exists at the URI. If one does, the doc-available() function evaluates to true() and the index position of that string in the sequence is returned as the result of the altova:find-first-pos function. Note about the doc-available() function: Relative paths are resolved relative to the the current base URI, which is by default the URI of the XML document from which the function is loaded.

 

 

Click to expand/collapsefor-each-attribute-pair [altova:]

altova:for-each-attribute-pair(Seq1 as element()?Seq2 as element()?, Function as function()) as item()*     XP3.1 XQ3.1

The first two arguments identify two elements, the attributes of which are used to build attribute pairs, where one attribute of a pair is obtained from the first element and the other attribute is obtained from the second element. Attribute pairs are selected on the basis of having the same name, and the pairs are ordered alphabetically (on their names) into a set. If, for one attribute no corresponding attribute on the other element exists, then the pair is "disjoint", meaning that it consists of one member only. The function item (third argument Function) is applied separately to each pair in the sequence of pairs (joint and disjoint), resulting in an output that is a sequence of items.

altova:for-each-attribute-pair(/Example/Test-A, /Example/Test-B, function($a, $b){$a+b}) returns ...

 

  (2, 4, 6) if

   <Test-A att1="1" att2="2" att3="3" />

   <Test-B att1="1" att2="2" att3="3" />

 

  (2, 4, 6) if

   <Test-A att2="2" att1="1" att3="3" />

   <Test-B att3="3" att2="2" att1="1" />

 

  (2, 6) if

   <Test-A att4="4" att1="1" att3="3" />

   <Test-B att3="3" att2="2" att1="1" />

 

    Note: The result (2, 6) is obtained by way of the following action: (1+1, ()+2, 3+3, 4+()). If one of the operands is the empty sequence, as in the case of items 2 and 4, then the result of the addition is an empty sequence.

 

altova:for-each-attribute-pair(/Example/Test-A, /Example/Test-B, concat#2) returns ...

 

  (11, 22, 33) if

   <Test-A att1="1" att2="2" att3="3" />

   <Test-B att1="1" att2="2" att3="3" />

 

  (11, 2, 33, 4) if

   <Test-A att4="4" att1="1" att3="3" />

   <Test-B att3="3" att2="2" att1="1" />

 

 

Click to expand/collapsefor-each-combination [altova:]

altova:for-each-combination(FirstSequence as item()*SecondSequence as item()*Function($i,$j){$i || $j} ) as item()*     XP3.1 XQ3.1

The items of the two sequences in the first two arguments are combined so that each item of the first sequence is combined, in order, once with each item of the second sequence. The function given as the third argument is applied to each combination in the resulting sequence, resulting in an output that is a sequence of items (see example).

altova:for-each-combination( ('a', 'b', 'c'), ('1', '2', '3'), function($i, $j){$i || $j} ) returns ('a1', 'a2', 'a3', 'b1', 'b2', 'b3', 'c1', 'c2', 'c3')

 

 

Click to expand/collapsefor-each-matching-attribute-pair [altova:]

altova:for-each-matching-attribute-pair(Seq1 as element()?Seq2 as element()?, Function as function()) as item()*     XP3.1 XQ3.1

The first two arguments identify two elements, the attributes of which are used to build attribute pairs, where one attribute of a pair is obtained from the first element and the other attribute is obtained from the second element. Attribute pairs are selected on the basis of having the same name, and the pairs are ordered alphabetically (on their names) into a set. If, for one attribute no corresponding attribute on the other element exists, then no pair is built. The function item (third argument Function) is applied separately to each pair in the sequence of pairs, resulting in an output that is a sequence of items.

altova:for-each-matching-attribute-pair(/Example/Test-A, /Example/Test-B, function($a, $b){$a+b}) returns ...

 

  (2, 4, 6) if

   <Test-A att1="1" att2="2" att3="3" />

   <Test-B att1="1" att2="2" att3="3" />

 

  (2, 4, 6) if

   <Test-A att2="2" att1="1" att3="3" />

   <Test-B att3="3" att2="2" att1="1" />

 

  (2, 6) if

   <Test-A att4="4" att1="1" att3="3" />

   <Test-B att3="3" att2="2" att3="1" />

 

altova:for-each-matching-attribute-pair(/Example/Test-A, /Example/Test-B, concat#2) returns ...

 

  (11, 22, 33) if

   <Test-A att1="1" att2="2" att3="3" />

   <Test-B att1="1" att2="2" att3="3" />

 

  (11, 33) if

   <Test-A att4="4" att1="1" att3="3" />

   <Test-B att3="3" att2="2" att1="1" />

 

 

Click to expand/collapsesubstitute-empty [altova:]

altova:substitute-empty(FirstSequence as item()*SecondSequence as item()) as item()*     XP3.1 XQ3.1

If FirstSequence is empty, returns SecondSequence. If FirstSequence is not empty, returns FirstSequence.

altova:substitute-empty( (1,2,3), (4,5,6) ) returns (1,2,3)
altova:substitute-empty( (), (4,5,6) ) returns (4,5,6)

 

 

 


© 2019 Altova GmbH