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:concat

Category:

String functions – manipulation

Origin:

XPath 1.0

Return value:

A xs:string string; consisting of the individual substrings passed on and concatenated.

Call/Arguments:

fn:concat($string_1, $string_2 ..., $string_n)

$string_1:

Obligatory. An argument of xs:anyAtomicType type cast to a xs:string string or a XPath expression which results in a (single) string. If the argument cannot be cast to the xs:string type, a type error is reported. In case the argument passed on is the empty sequence, it is considered as an empty string when concatenated.

$string_2:

Obligatory. An argument of xs:anyAtomicType type which is, as stated above, evaluated to a second xs:string string which shall be concatenated with the first one. In case the argument passed on is the empty sequence, it is considered as an empty string when concatenated.

$string_3, …, $string_n:

Each optional. Any number of arguments of xs:anyAtomicType type which are also cast to xs:string strings being concatenated with the first two arguments in the order passed on.

Purpose of use:

xs:string strings passed on to fn:concat() or expressions whose evaluations result in each case in a string are united to one result string. The cardinality of each argument passed on has to satisfy the fn:zero-or-one() function. Consequently, it is not permitted to pass on sequences consisting of several strings as argument (see example 3).

In the simplest case, the call of fn:concat() would be as follows:

fn:concat("a","b") results in: "ab"

fn:concat() can be useful if for the generation of an output string several xsl:value-of commands would be required:

The above expression outputs consecutively, for example, the contents of the elements <firstName> and <lastName> and inserts between the elments a whitespace character ' '. The element identifiers are replaced by the string values of the elements. A more detailed version would be the following:

The <xsl:text> element is required in this case, since whitespace characters would be otherwise removed by the parser.

Attention! – only individual strings as arguments:
The fn:concat() function accepts – as described above – only individual strings as arguments but no sequences of several strings (or expressions which build string sequences of several items). For these purposes, the fn:string-join() function can be used analogously (see example 6).

Example 1 - concatenation of two strings passed on:

fn:concat('Hello ', 'World!')

results in the string "Hello World!".

The two strings are outputted concatenated in the order of their passing on. A normalisation of the individual strings beforehand does not occur. Therefore, leading and following whitespace characters within the individual strings do not appear in the result.

Example 2 - concatenation of several strings passed on:

fn:concat( 'Good ', 'my ', 'lord', (), ",", "put ", " ",

'your', ' discourse', ' into', ' some ', 'frame!')

results in the string "Good my lord, put your discourse into some frame!" (see Guildenstern in Shakespeare's Hamlet act 3, scene 2).

An empty sequence is transformed into the empty string and concatenated with the other string arguments. In principle, both types of string delimiters can appear in the funcion call, whereas, in practice, the string delimiters of the enclosing XPath expression have to be considered.

Example 3 - error source: sequences as arguments:

fn:concat( ('so','so'),

('yes','yes')

)

This call of fn:concat() results in an error, unless the compatibility mode to XPath 1.0 is activated. In this case, each first item of the sequences passed on (which are treated analogously to node sets) is used as argument and the rest of them are rejected.

fn:concat( ('so','so'),

('yes','yes')

)

when the compatibility mode is activated, this results in "soyes".

Otherwise the arguments passed on, since they have to be of the xs:anyAtomicType type, must not have the form of sequences of two or more items (singleton sequences are permitted – otherwise a cardinality error is reported). Each sequence passed on is regarded as individual argument. Therefore, two sequences passed on as above and consisting of strings are not resolved to individual arguments.

The following applies:

fn:concat( $string_1, $string_2, ..., $string_N

)

is not the same as (note the inner sequence parentheses!):

fn:concat( ($string_1, $string_2, ..., $string_N)

)

The second case is considered as a passing on of an individual argument which is a violation of the required function signature. Even if a second argument is passed on, without an active compatibility mode, the first argument would result in a cardinality error. Otherwise $string_1 is used as first argument and the rest of the sequence is rejected.

Example 4 - application of fn:concat() for the definition of keys:

In connection with a xsl:key key definition, fn:concat() may be useful, since a key must always be a one-piece value.

For example, it is not possible to define for an <employee> element the content of two of its child elements <firstName> and <lastName> as a »concatenated« key. Instead, the fn:concat() function is used as a trick for the definition of the key. A complete key is generated in this way:

and the following key:

Now »Thomas Miller« can be found with

Names which only contain one of the substrings (as in this example »Thomas Smith« or »Stephen Miller«) do not appear in the results anymore.

Function definition:

XPath 1.0:

concat(string, string, string*) => string

XPath 2.0:

fn:concat($arg1 as xs:anyAtomicType?,

$arg2 as xs:anyAtomicType?, ...) as xs:string