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:string-join

Category:

String functions – analysis and manipulation

Origin:

XPath 2.0

Return value:

A xs:string string; the concatenated string values of the items of the input sequence with the inserted separator string which is passed on as second argument.

Call/Arguments:

fn:string-join($inputSequence, $separatorString)

$inputSequence:

Obligatory. A sequence of any number of items of xs:string type. The input sequence may be empty – in this case the function returns the empty string. If the item of the argument sequence is not a string, a type error is reported. The empty sequence is permitted as argument and is treated like the empty string.

$separatorString:

Obligatory. A xs:string string which is inserted as separator between the string values of the items of the input sequence. The result of a string expression may be empty. If the empty string is passed on as literal, in this case the string delimiters must be nevertheless availabe in the argument. At this position, the empty sequence must not be passed on.

Purpose of use:

The fn:string-join() function corresponds in its effect to the fn:concat() function, with the additional option of inserting a separator string between the string values of the input sequence to be united.

If the empty string is passed on as separator, the effect of the function is identical to fn:concat(). The string values of the items are concatenated directly. However, the empty sequence is not allowed as argument for the separator.

If the empty sequence is passed on to the function, it always returns – irrespective of the value passed on as separator – the empty string.

If the function receives as first argument a singleton sequence in the form of a single xs:string string, this string is outputted unchanged. A concatenation with the separator argument does not take place in this case.

Example 1 – space character as separator:

fn:string-join( ('This', 'is', 'an', 'example!'), " ")

results in: "This is an example!".

The seperator is inserted between the string items of the input sequence and concatenated. It is not additionally added to the last item of the sequence: If no or only one item is passed on, the separator does not play a role (see examples 3 and 4).

Example 2 – empty string as separator:

fn:string-join( ("Abra", "cadabra"), "")

results in: "Abracadabra".

The empty string as separator makes the function just as effective as fn:concat. However, for fn:string-join() the input sequence may contain as items sequences of strings, instead of – as for fn:concat() – only sequences of arguments in the form of individual strings (see example 5).

Example 3 – empty input sequence:

fn:string-join( (), "XXXX")

results in: "".

The first argument may be an empty sequence. The separator does not play a role in this connection, but must be passed on for formal reasons. In this case, the function returns the empty string and not – like other functions with an empty input argument – the empty sequence!

Example 4 – singleton as input sequence:

fn:string-join("example", "XXXX")

results in: "example".

The first argument may be a singleton sequence of a single xs:string string. The separator also does not play a role in this connection, but must be passed on in this example, too. The function returns the item passed on unchanged.

Example 5 – empty sequence as separator: error!

fn:string-join("example", ())

results in the error "An empty sequence is not allowed as the second argument of string-join()".

It is neither permitted to pass on no separator argument a priori, nor an empty sequence or an expression which leads to an empty sequence are permitted at this position.

Example 6 – sequence included in input sequence:

fn:string-join(

("There are", fn:string(fn:count($seq)),

"items in this sequence:", $seq),

" "

)

results in: "There are 4 items in this sequence: This is an example".

The inserted $seq sequence is ('This', 'is', 'an', 'example').

The items of a sequence used as argument are treated as being equivalent to the string arguments literally passed on. By means of fn:count(), the items of the sequence are counted. However, since the return value of fn:count() is of xs:integer type and would cause a type error, it is necessary to explicitly convert it to a xs:string string by means of fn:string().

Function definition:

XPath 1.0:

The function is not available.

XPath 2.0:

fn:string-join($arg1 as xs:string*,

$arg2 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