Book HomeXML in a NutshellSearch this book
PreviousNext

23.3. XSLT Functions

XSLT supports all functions defined in XPath. In addition, it defines 10 extra functions. Most XSLT processors also make several extension functions available and allow you to write your own extension functions in Java or other languages. The extension API is nonstandard and processor dependent.

XPath and XSLT functions are weakly typed. Although one type or another is occasionally preferred, the processor normally converts any type you pass in to the type the function expects. Functions that only take node-sets as arguments are an exception to the weak-typing rule. Other data types including strings, numbers, and booleans cannot be converted to node-sets automatically.

XPath and XSLT functions also use optional arguments, which are filled in with defaults if omitted. In the following sections, we list the most common and useful variations of each function.

current( ) 
node-set current( )
The current( ) function returns a node-set containing a single node, the current node. Outside of an XPath predicate, the current node and the context node (represented by a period in the abbreviated XPath syntax) are identical. However, in a predicate, the current node may change based on other contents in the predicate, while the context node stays the same.

document( ) 
node-set document(string uri)
node-set document(node-set uris)
node-set document(string uri, node-set base)
node-set document(node-set uris, node-set base)
The document( ) function loads the XML document at the URI specified by the first argument and returns a node-set containing that document's root node. The URI is normally given as a string, but may be given as another type that is converted to a string. If the URI is given as a node-set, then each node in the set is converted to a string, and the returned node-set includes root nodes of all documents referenced by the URI argument.

If the URI contains a fragment identifier, then the node-set returned may indicate something other than the root node and thus contain more than one node. If an error occurs while retrieving a document, most XSLT processors stop processing the stylesheet.

The document( ) function may also take a node-set as an optional second argument, in which case the first node (in document order) in this set is used as the base URI with which to resolve relative URIs given in the first argument. If the second argument is omitted, then base URIs are resolved relative to the stylesheet's location.

element-available( ) 
boolean element-available(string qualifiedElementName)
element-available( ) returns true if and only if the argument identifies an XSLT element the processor recognizes. If the qualified name maps to a non-null namespace URI, then it refers to an extension element. Otherwise, it refers to a standard XSLT element. Assuming use of a fully conformant processor, you don't need to use this function to test for standard elements; just use it for extension elements.

format-number( ) 
string format-number(number x, string pattern)
string format-number(number x, string pattern, string decimalFormat)
The format-number( ) function converts the number x to a string using the pattern specified by the second argument, as well as the xsl:decimal-format element named by the third argument (or the default decimal format, if the third argument is omitted).

This function's behavior is modeled after the java.text.DecimalFormat class in Java 1.1 (not 1.2 or later). See http://java.sun.com/products/jdk/1.1/docs/api/java.text.DecimalFormat.html for full documentation of the pattern passed as the second argument.

The pattern specifies whether leading and trailing zeros should be printed, whether the number's fractional part is printed, the number of digits in a group, and the leading and trailing suffixes for negative and positive numbers. The patterns are described using an almost Backus-Naur Form grammar, given here: 

pattern     ->  subpattern{;subpattern}
subpattern  ->  {prefix}integer{.fraction}{suffix}
prefix      ->  '\\u0000'..'\\uFFFD' - specialCharacters
suffix      ->  '\\u0000'..'\\uFFFD' - specialCharacters
integer     ->  '#'* '0'* '0'
fraction    ->  '0'* '#'*

The first line is not pure BNF. The first subpattern is used for positive numbers. The second subpattern, which may not be present, is used for negative numbers. If it's not present, negative numbers use the positive format, but are prefixed with a minus sign. Table 23-1 defines the symbols used in the grammar.

Table 23-1. Symbols used in the pattern grammar

Symbol

Meaning

0

A digit, including leading or trailing zeros; may be set to a different character using the zero-digit attribute of xsl:decimal-format.

#

A digit, except for leading or trailing zero; may be set to a different character using the digit attribute of xsl:decimal-format.

.

A decimal separator; may be set to a different character using the decimal-separator attribute of xsl:decimal-format.

,

A grouping separator; may be set to a different character using xsl:decimal-format's grouping-separator attribute.

;

Separates the positive and negative format patterns in a format string; may be set to a different character using the pattern-separator attribute of xsl:decimal-format.

-

A default negative prefix; may be set to a different character using xsl:decimal-format's minus-sign attribute.

%

Multiplies by 100 and shows as percentage; may be set to a different character using xsl:decimal-format's percent attribute.

Figure

Multiplies by 1,000 and shows as per mille; may be set to a different character using xsl:decimal-format's permille attribute.

X

Indicates that any other character can be used in the prefix or suffix.

'

Used to quote special characters in a prefix or suffix.
For instance, #,##0.### is a common decimal-format pattern. The # mark indicates any digit character except a leading or trailing zero. The comma is the grouping separator. The period is the decimal separator. The 0 is a digit that is printed even if it's a nonsignificant zero. This pattern is interpreted as follows:

  1. The integer part contains as many digits as necessary.

  2. The grouping separator separates every three digits.

  3. If the integer part only contains zeros, a single zero is placed before the decimal separator.

  4. Up to three digits are printed after the decimal point. However, any trailing zeros are not printed.

  5. No separate pattern is included for negative numbers. Thus, negative numbers are printed the same as positive numbers, but prefixed with a minus sign.

function-available( ) 
boolean function-available(string qualifiedName)
function-available( ) returns true if the argument identifies a function in the processor's function library; false otherwise. If the qualified name maps to a non-null namespace URI, then it refers to an extension function. Otherwise, it refers to a built-in function from XPath or XSLT. Assuming you're using a fully conformant processor, however, you don't need to test for standard functions, only for extension functions.

generate-id( ) 
string generate-id(node-set node)
string generate-id( )
The generate-id( ) function returns a string that can be used as the value of an ID type attribute. This function always produces the same string for the same node and a different string for a different node. If the node-set contains more than one node, then only the first node in the set is considered. If the argument is omitted, then the node-set is set to the context node. If the node-set is empty, then the empty string is returned.

key( ) 
node-set key(string keyName, string value)
node-set key(string keyName, node-set values)
The key( ) function returns a node-set containing all nodes in the source document that have a key with the name given by the first argument and the value given by the second argument. If the second argument is a node-set, then the node-set returned contains all nodes that have a key with the specified name and a value that matches that of any node in the second argument. Otherwise, the returned node-set contains all nodes that have a key with the specified name and a value that matches the second argument's string value. Key names and values are assigned to nodes using the xsl:key element.

system-property( ) 
object system-property(string qualifiedPropertyName)
The system-property( ) function returns the value of the named property. The type of the returned object is processor- and property-dependent. If the processor does not recognize the property name, then it returns an empty string.

XSLT processors are required to recognize and return values for these three properties:

xsl:version
A number specifying the version of XSLT implemented by the processor; this is normally 1.0, but may become 2.0 during this book's life span.

xsl:vendor
A string identifying the XSLT processor's vendor; for instance, Apache Software Foundation for Xalan or SAXON 6.4.4 from Michael Kay for SAXON.

xsl:vendor-url
A string containing a URL for the XSLT processor's vendor; for instance, http://xml.apache.org/xalan for Xalan or http://saxon.sourceforge.net for SAXON.

Implementations may also recognize and return values for other processor-dependent properties.

unparsed-entity-uri( ) 
string unparsed-entity-uri(string entityName)
The unparsed-entity-uri( ) function returns the URI of the unparsed entity with the specified name declared in the source document's DTD or the empty string, if no unparsed entity with that name exists.

PreviousHomeNext
23.2. XSLT ElementsBook Index23.4. TrAX
Library Navigation Links

Copyright © 2002 O'Reilly & Associates. All rights reserved.