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

Category:

String functions – analysis and manipulation

Origin:

XPath 1.0

Return value:

A xs:string string; the input string with performed character replacements.

Call/Arguments:

fn:translate($input, '$replacedCharacters', '$replacementCharacters')

$input:

Obligatory. The first argument is a xs:string input string in which characters shall be replaced. If this argument is not a string, a type error is reported. The empty sequence is permitted as value and is treated like the empty string.

$replacedCharacters:

Obligatory. The second argument is a xs:string string which is interpreted as a list of characters to be replaced. If a string literal is passed on, it must be surrounded by string delimiters.

$replacementCharacters:

Obligatory. The third argument is the xs:string string which is interpreted as a list of the replacement characters. This string corresponds character for character to the string of the second argument, which means to the characters to be replaced. But it may also be shorter than the string of the second argument. If a string literal is passed on, it must be surrounded by string delimiters.

Purpose of use:

The fn:translate() function can replace any characters within the string passed on by any other characters. Also the space character and the other whitespace characters are considered as normal characters in this context.

If in the original string a character of the string of the characters to be replaced (mapString) is found, it is replaced by its corresponding character in the string of the replacement characters (transString). So, if the found character is in the third position in the string of the characters to be replaced, it is accordingly replaced by the third character from the replacement character string.

If a character in the string of the characters to be replaced occurs several times, it is replaced by the character which corresponds with its first occurence:

fn:translate($text,'aaa','zyx')

always replaces 'a' by 'z' (not the series 'aaa' by 'zyx' – this can be realised by fn:replace()).

If the replacement character string (transString) is shorter than the string of the characters to be replaced (mapString), all those characters from the original string are removed for which no corresponding character can be found in the replacement character string. In the opposite case, the excess characters in the replacement character string are ignored.

If the string of the replacement characters shall be empty (which means that all characters passed on as second argument shall be removed), the third argument must nevertheless be present in the form of the empty string delimiter. The input string is accordingly shortened.

If for the first argument the empty sequence is passed on, the function returns the empty string.

Example 1 – replacing certain letters:

fn:translate( 'This is an example!', 'ie', 'IE'

)

results in: "ThIs Is an ExamplE!".

Example 2 – replacing all lower case letters by upper case letters:

In order to replace in a $x input string all lower case letters by upper case letters, the fn:translate() function can be used as follows:

fn:translate( $x,

'abcdefghijklmnopqrstuvwxyz',

'ABCDEFGHIJKLMNOPQRSTUVWXYZ'

)

If $x is equal to 'This is an example!', the result is 'THIS IS AN EXAMPLE!'.

Example 3 – testing for a series of any digits:

In order to test a string for the occurence of groups of any four digits each, a combination of the functions fn:translate() and fn:contains() can be used.

<xsl:if test="fn:contains(fn:translate($digits,'123456789','000000000'),'0000')">
   <!-- template block -->
</xsl:if>

Any series of digits is translated into a series of four zeros whose existence is simply tested with fn:contains(). For this purpose, the 0 does not need to be specially replaced.

Example 4 – removing certain characters:

The removal of characters can be useful if you want to remove space characters, hyphens, slashes or the like from telephone numbers:

fn:translate( $telephone,

'&#x20;&#x9;&#xA;&#xD;(/)-',

''

)

In this example, the whitespace characters to be deleted are inserted as character entities in the list of the characters to be replaced. It should be noted that also a replacement character list in the form of an empty string must be available.

So, the input (012) 345-67-89 results in:

(012) 345-67-89 => 0122345678

Example 5 – simple cryptography:

By a 1:1 translation of the entire alphabet, a very simple cryptography can be achieved:

fn:translate( 'this is an example!',

'abcdefghijklmnopqrstuvwxyz',

'zyxwvutsrqponmlkjihgfedcba'

)

results in: 'gsrh rh zm vcznkov!'.

The conversion is also possible in the reverse direction for the »decryption«. However, the method is easy to recognise and therefore, it offers no real security.

Function definition:

XPath 1.0:

translate(string, string, string)=> string

XPath 2.0:

fn:translate($arg as xs:string?,

$mapString as xs:string,

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