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:normalize-space

Category:

String functions – analysis and manipulation

Origin:

XPath 1.0

Return value:

A xs:string string; the copy of the input string with performed whitespace normalisation. If the input string is empty, the empty string is returned.

Call/Arguments:

fn:normalize-space($inputString?)

$inputString:

Optional. The argument of the function is a character string to be normalised. If the argument is not a xs:string string, a type error is reported. The empty sequence is permitted as a value and treated like the empty string. (However, in XPath 1.0 the value, if it is not a string, is transformed into a string according to the rules of the conversion function string().) If no argument is passed on, the function refers to the context item.

Purpose of use:

The fn:normalize-space() function removes from a character string passed on to it all leading and trailing spaces and replaces all consecutions of one or several whitespace characters appearing within the string by exactly one space character #x20 (SPC).

The function makes no difference between an empty string and the empty sequence: In both cases the function returns the empty string. In XPath 2.0, this corresponds to the general behaviour of string functions. An exception to this is the fn:normalize-unicode() function. However, for most of the other functions the passing on of the empty sequence results in an also empty result sequence.

If no argument is passed on to the function, it refers to the context item and returns in normalised form its string value determined according to fn:string(). Then, a context item must also be defined, otherwise a runtime error is reported (err:XPDY0002).

In the context of the function the whitespace characters according to XML 1.0 include: the common space characters (SPC) #x20, the tab command (TAB) #x9, the line feed command (LF) #xA as well as the carriage return command (CR) #xD.

In XML 1.1 the stock of whitespace characters has been expanded by the NEL character (Newline, U+0085 or #x85) from the IBM mainframe sector as well as by the Unicode line separator character #x2028. Usuallly, the XML parser already unifies the line end characters to LF when reading in the document, so that no problems should occur when processing parsed XML 1.1 resources.

A resource being read in by means of the XSLT function unparsed-text() should at least not contain any characters forbidden in XML. In case of non-resolvable character octets, this function outputs an error. However, the resource is not parsed before the processing.

Example 1 – fn:normalize-space() applied to a string:

fn:normalize-space(" Hello

World! ")

returns:

Hello World!

Leading and trailing space characters at the beginning and the end of the string passed on are removed. Consecutions of whitespace characters (which, in this example, also include the line break) within the string are united to a single space character (SPC).

Example 2 – fn:normalize-space() applied to the empty sequence:

fn:normalize-space(())

returns: ""

If the input value of the function is an empty sequence, the empty string is returned. In XPath 2.0 this corresponds to the general behaviour of the string functions. By no means the function returns an empty sequence (which means no value).

Example 3 – fn:normalize-space() in connection with keys:

For declarations of keys with xsl:key, the basic use of fn:normalize-space() is of advantage. In this way, an already »normalised« index is built up. When testing a reasonably also normalised key candidate, it is not necessary to take possibly occuring line breaks and the like into account.

At first, a normalised index is built:

Now, books of an author can be found in this way:

The $author variable shall contain the desired name of the author – as a precaution, its content is also normalised.

Function definition:

XPath 1.0:

normalize-space(string?) => string

XPath 2.0:

fn:normalize-space() as xs:string

fn:normalize-space($arg as xs:string?) as xs:string

Possible compatibility problems XPath 2.0 to XPath 1.0:

None. In case of a missing argument in XPath 2.0 also the normalised string value of the context node is returned.