General guidelines and examples

This section describes general guidelines for using functions in XPath expressions. These guidelines apply to all the functions listed. All these examples use tolower, which returns a single argument in lowercase.

You can use a function call wherever you would use a step expression.

Functions used as the top level of an XPath query are called top-level function calls. The following query shows tolower as a top-level function call:

select xmlextract
(’tolower(//book[title="Seven Years in Trenton"]//first-name)’, text_doc) 
from sample_docs where name_doc=’bookstore’

------------------------------------------
joe

The parameters of a top-level function call must be an absolute path expression; that is, the parameter must begin with a slash (/) or a double slash (//).

The parameters of a function call can be complex XPath expressions that include predicates. They can also be nested function calls:

select xmlextract 
('//book[normalize-space(tolower(title))="seven years in trenton"]/author', text_doc)
from sample_docs where name_doc='bookstore'-----------------------------------------
<author>
     <first-name>Joe</first-name>
     <last-name>Bob</last-name>
     <award>Trenton Literary Review 
     Honorable Mention</award>
</author> 

You can use a function as a relative step, also called a relative function call. The following query shows tolower as a relative function call:

select xmlextract
( '//book[title="Seven Years in Trenton"]//tolower(first-name)', text_doc)
from sample_docs where name_doc='bookstore'--------------------------------------joe 

This example shows that the parameters of a relative function must be a relative path expression; that is, it cannot begin with a slash (/) or a double slash(//).

Both top-level and relative functions can use literals as parameters. For example:

select xmlextract( 'tolower("aBcD")' ,text_doc), 
    xmlextract( '/bookstore/book/tolower("aBcD")', text_doc)
from sample_docs where name_doc='bookstore' --------  ---------- abcd      abcd

String functions operate on the text of their parameters. This is an implicit application of text(). For example, this query returns a first-name element as an XML fragment:

select xmlextract
( '//book[title="Seven Years in Trenton"]//firstname’, text_doc)
from sample_docs where name_doc='bookstore'-----------------------------<first-name>Joe</first-name>

The following query returns the text of that first-name XML fragment:

select xmlextract
( '//book[title="Seven Years in Trenton"]//first-name/text()', text_doc)
from sample_docs where name_doc='bookstore'-------------------------------Joe 

The next query applies tolower to the first-name element. This function operates implicitly on the text of the element:

select xmlextract
('//book[title="Seven Years in Trenton"] //tolower(first-name)', text_doc)
from sample_docs where name_doc='bookstore'----------------------------------------------joe 

This has the same effect as the next example, which explicitly passes the text of the XML element as the parameter:

select xmlextract
( '//book[title="Seven Years in Trenton"]//tolower(first-name/text())',
text_doc) 
from sample_docs where name_doc='bookstore'---------------------------------------joe 

You apply a relative function call as a step in a path. Evaluating that path produces a sequence of XML nodes, and performs a relative function call for each node.The result is a sequence of the function call results. For example, this query produces a sequence of first_name nodes:

select xmlextract( '/bookstore/book/author/first-name', text_doc)
from sample_docs where name_doc='bookstore'
---------------------------------
<first-name>Joe</first-name><first-name>Mary</first-name>
<first-name>Toni</first-name> 

The query below replaces the last step of the previous query with a call to toupper, producing a sequence of the results of both function calls.

select xmlextract('/bookstore/book/author/toupper(first-name)', text_doc)
from sample_docs where name_doc='bookstore'
----------------------------------
JOEMARYTONI 

tolower, toupper, and normalize-space each have a single parameter. If you omit the parameter when you specify these functions in a relative function call, the current node becomes the implicit parameter. For instance, this example shows a relative function call of tolower, explicitly specifying the parameter:

select xmlextract
('//book[title="Seven Years in Trenton"]//tolower(first-name)', text_doc)
from sample_docs where name_doc='bookstore'
-----------------------------------------------------
joe 

This example of the same query specifies the parameter implicitly:

select xmlextract
('//book[title="Seven Years in Trenton"]//first-name/tolower()', text_doc)
from sample_docs where name_doc='bookstore'
---------------------------------------------
joe 

You can also specify parameters implicitly in relative function calls when the call applies to multiple nodes. For example:

select xmlextract('//book//first-name/tolower()', text_doc)
from sample_docs where name_doc='bookstore'
----------------------------------------------
joemarymarytoni