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:substring-after

Category:

String functions – analysis and manipulation

Origin:

XPath 1.0

Return value:

xs:string string; a substring of an input string, starting with the first character after the first occurrence of a comparison string also passed on up to the end of the input string.

Call/Arguments:

fn:substring-after($input, $comparisonString, $collation-URI?)

$input:

Obligatory. The xs:string string to be examined. If the argument is not a string, a type error is reported. The empty sequence is permitted as value and is treated like the empty string.

$comparisonString:

Obligatory. A xs:string string whose first occurrence is searched for in the input string. The substring starting from the first occurrence of the comparison string up to the end of the input string is outputted. If the argument is not a string, a type error is reported. The empty sequence is permitted as value (even though it makes little sense) and is treated like the empty string.

$collation-URI:

(new in XPath 2.0)

Optional. The third argument consists of a xs:string string which names the URI string of the collation to be used. The value has to lexically correspond to the xs:anyURI type. If no third argument is passed on, the Unicode Codepoint collation is used for the comparison. This argument is not available in XPath 1.0.

Purpose of use:

The fn:substring-after() function returns that part of an input string which follows the first occurrence of a comparison string in the input string. The comparison string should consist of at least one single character or a character string. In case the comparison string appears several times in the examined string, for example a delimiter in a list available as individual string, only its occurrence is taken into account. This can be taken into account by repeated recursive processing (example 2). Alternatively, the fn:tokenize() function can be used.

If the test string passed on as second argument is not contained in the input string or if the input string is empty (or as first argument the empty sequence was passed on), an empty string is returned.

However, the same happens if the input string ends with the comparison string. In order to test this case, fn:contains() can be used. In case the comparison string itself is empty or as second argument the empty sequence was passed on, the complete input string is outputted.

If no third argument for the naming of a collation is passed on to the function, the string comparison takes place by means of the Unicode Codepoint collation. So, the default collation of the system is expressly not used. As a consequence, the behaviour of fn:substring-after() conforms with those string functions using regular expressions, which means fn:matches(), fn:replace() and fn:tokenize().

Behaviour under XPath 1.0:

In XPath 1.0 the arguments, in case they are not strings, are automatically converted to strings according to the rules of the conversion function string(). If the first argument is an empty node set, an empty string is returned. However, in XPath 2.0 an empty sequence () is returned in case any operand of the first two operands is the empty sequence.

Example 1 – simple application on two strings:

fn:substring-after('This is an example', 'is')

results in: ' an example'.

The substring of the input string immediately following the comparison string is returned, in this case with leading space character. (No automatic normalisation!)

Example 2 – empty string as comparison string:

fn:substring-after('This is an example', '')

results in: 'This is an example'.

The entire input string is returned. This is based on the premise that at the start of each string an empty string exists.

Example 3 – application for recursive string processing:

Basically, fn:substring-after() is useful if separators (delimiters) are contained in a longer string. However, the function only finds the first occurrence of a delimiter, so it must be used recursively in case the delimiter appears several times. This is often the case in a list of tokens separated by space characters or the like.

A complex approach, as described in this example, was inevitable in XPath 1.0. In XPath 2.0 the fn:tokenize() function can be used as an alternative.

In the following example a token list available as string and separated by space characters is converted to a list separated by HTML breaks. For this purpose, two templates are required from whom the second calls up itself again and does the actual work.

First, however, the token list must be »prepared«:

<!-- the first template enforces the following space character: -->
<xsl:template select="tokenList">
<xsl:variable name="the_tokenList" select="fn:concat(fn:normalize-space(.),' ')"/>
<xsl:call-template name="listOutput">
   <xsl:with-param name="list" select="$the_tokenList"/>
</xsl:call-template>
</xsl:template>

In order that the conversion works error-free, in the preceded template is ensured that in the token list one space character in a row occurs at the maximum (therefore, also tabulators and line breaks must be removed) and that one space character also comes after the last token.

This is achieved by the usage of the functions fn:normalize-space(), for the removal of surplus space characters, and fn:concat(), in order to add a space character at the end. If one fails to do this, the last application of fn:substring-before() would not recognise the last token, since no space character follows. The space character must be added after the normalisation, because otherwise it would be removed right away.

<!-- the second template outputs the list: -->
<xsl:template name="listOutput">
<xsl:param name="list"/>
<xsl:variable name="token" select="fn:substring-before($list, ' ')"/>
<xsl:variable name="rest" select="fn:substring-after($list, ' ')"/>
<!-- output of the first part of the list: -->
<xsl:value-of select="$token"/>
<!-- testing whether a rest remains ... -->
<xsl:if test="$rest">
   <!-- outputting the break: -->
   <br/>
   <!-- ... and calling up the template again: --> 
   <xsl:call-template name="listOutput">
      <!-- rest of the list becomes the new initial value: -->
      <xsl:with-param name="list" select="$rest"/>
   </xsl:call-template>
</xsl:if>
<xsl:template>

The first list element is separated with fn:substring-before() and, immediately after this, outputted. With

<xsl:if test="$rest">

is tested whether a non-empty rest of the list remains.

The recursiveness is achived when the named template calls up itself again and passes on itself to the rest of the list generated by fn:substring-after() as new initial value.

Function definition:

XPath 1.0:

substring-after(string, string) => string

XPath 2.0:

fn:substring-after($arg1 as xs:string?,

$arg2 as xs:string?) as xs:string

fn:substring-after($arg1 as xs:string?,

$arg2 as xs:string?,

$collation as xs:string) as xs:string

   

<< back next >>

 

 

 


Copyright © Galileo Press, Bonn 2008
Printing of the online version is permitted exclusively for private use. Otherwise this chapter from the book "XSLT 2.0 & XPath 2.0" is subject to the same provisions as those applicable for the hardcover edition: The work including all its components is protected by copyright. All rights reserved, including reproduction, translation, microfilming as well as storage and processing in electronic systems.


Galileo Press, Rheinwerkallee 4, 53227 Bonn, Germany