XQuery, concluded - Functions
(Page 4 of 5 )
You already learned that a function is a task that Saxon-B already knows how to perform; all you need to do is to call the function in your XQuery whenever you want Saxon-B to perform that task.
Table 9-2 contains commonly used XQuery functions. You can find a complete list of functions at www.w3.org/2005/02/xpath-functions.
In addition to calling built-in functions, you can also define your own functions that can be called the same way a built-in function is called. Here’s what you need to do. First create the function by writing a function declaration statement.
Function | Description | Example |
upper-case() | Converts the argument to uppercase letters. | upper-case("Led Zeppelin") returns: "LED ZEPPELIN" |
lower-case() | Converts the argument to lowercase letters. | lower-case("Led Zeppelin") returns: "led zeppelin" |
substring() | Returns a substring. | substring("Led Zeppelin",1, 6) returns: "Led Ze" |
string() | Returns the string representation of the argument. | string(645) returns: "645" as a string. |
concat() | Returns the concatenation of two strings. | concat("XQu", "ery") returns: "XQuery" |
string-join() | Returns a concatenation of the arguments separated by the specified separator. The fi rst argument is a list of strings and the second argument is the separator. You may find this particularly useful for displaying names. | string-join(("Mary", "Ellen", "Smith"), " ") returns: "Mary Ellen Smith" |
string-length() | Returns the length of the string. If the argument is a node, then it returns the length of the string data for that node. | string-length("Led Zeppelin") returns: 12 |
Table 9-2 Commonly Used Built-In XQuery Functions
The function declaration statement must have a prefix, a function name, a parameter list, and a return value. In addition, a function declaration statement must also define a code block that contains statements that are executed when the function is called from within an XQuery.
Here’s the structure of a function declaration statement:
declare function prefix:function_name($parameter as datatype, ...)
as returntype
{
... code for the function goes here...
};
Let’s declare a function. You’ll call it convertdate and it will convert the date format 2006-10-04 to October 4, 2006. The prefix will be called local. The parameter is the date that will be converted and the return value is the converted date.
Here’s the function declaration. Notice that the parameter is placed within parentheses. You’ll need to give the parameter a name and specify its data type. The name is always prefaced with a $ symbol. You’ll also need to specify the data type of the value returned by the function. The return type in this example is a string.
The code block is defined with open and closed French braces ({ }). This is where you place statements that execute each time the function is called. The function begins by assigning all the months to an array called $month. An array is a variable that can have many values. Next, the month-from-date() function is called to extract the month of the date and assign it to the $month variable. The day-from-date() function and year-from-date() function are passed to the concat() function in the return clause to return the reformatted date.
The function declaration statement must appear at the top of the XQuery, as we show in the following example. Think of this as defining the function before you call the function within the XQuery. The function is called later in the XQuery {local:convertdate(xs:date($cd/date))}.
declare function local:convertdate($date as xs:date) as xs:string
{
let $months := ("January","February","March","April","May",
"June","July","August","September",
"October","November","December")
let $month := $months[month-from-date($date)]
return
concat($month, " ", string(day-from-date($date)), ", ",
string(year-from-date($date)))
};
<html>
<body>
List of titles in this catalog:<br/>
<table border="1">
<tr>
<td>UPC</td>
<td>Artist</td>
<td>Title</td>
<td>Date</td>
</tr>
{
for $cd in doc("catalog.xml")/catalog/cd
order by $cd/artist
return
<tr>
<td>{data($cd/@upc)}</td>
<td>{data($cd/artist)}</td>
<td>{data($cd/title)}</td>
<td>{local:convertdate(xs:date($cd/date))}</td>
</tr>
}
</table>
</body>
</html>
Here’s the output.html file that the XQuery produces:
<html>
<body>
List of titles in this catalog:<br><table border="1">
<tr>
<td>UPC</td>
<td>Artist</td>
<td>Title</td>
<td>Date</td>
</tr>
<tr>
<td>74646938720</td>
<td>Billy Joel</td>
<td>Songs in the Attic</td>
<td>October 20, 1998</td>
</tr>
<tr>
<td>74640890529</td>
<td>Bob Dylan</td>
<td>The Times They Are A-Changin'</td>
<td>October 25, 1990</td>
</tr>
<tr>
<td>8811160227</td>
<td>Jimi Hendrix</td>
<td>Are You Experienced?</td>
<td>April 22, 1997</td>
</tr>
<tr>
<td>75679244222</td>
<td>Led Zeppelin</td>
<td>Physical Graffiti</td>
<td>August 16, 1994</td>
</tr>
<tr>
<td>75678263927</td>
<td>Led Zeppelin</td>
<td>Houses of the Holy</td>
<td>July 19, 1994</td>
</tr>
<tr>
<td>75678367229</td>
<td>Rush</td>
<td>Rush in Rio</td>
<td>October 21, 2003</td>
</tr>
<tr>
<td>602498678299</td>
<td>U2</td>
<td>How to Dismantle an Atomic Bomb</td>
<td>November 23, 2004</td>
</tr>
</table>
</body>
</html>
Here’s how the output.html file appears when displayed in a browser (see Figure 9-5).
Figure 9-5. Here's how the output. html file is displayed in a browser.
Next: Looking Ahead >>
More XML Articles
More By McGraw-Hill/Osborne
|
 This article is excerpted from chapter nine of the book XML DeMYSTiFieD, written by Jim Keogh and Ken Davidson (McGraw-Hill/Osborne, 2005; ISBN: 0072262109). Check it out today at your favorite bookstore. Buy this book now.
|
|
