1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
|
<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
-
- This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
- project.
-
- Copyright (C) 1998-2018 OpenLink Software
-
- This project is free software; you can redistribute it and/or modify it
- under the terms of the GNU General Public License as published by the
- Free Software Foundation; only version 2 of the License, dated June 1991.
-
- This program is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- General Public License for more details.
-
- You should have received a copy of the GNU General Public License along
- with this program; if not, write to the Free Software Foundation, Inc.,
- 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
-
-
-->
<refentry id="xpf_translate">
<refmeta>
<refentrytitle>translate</refentrytitle>
<refmiscinfo>XPATH</refmiscinfo>
</refmeta>
<refnamediv>
<refname>translate</refname>
<refpurpose>Performs char-by-char translation of given string</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis id="xpf_syn_translate">
<funcprototype id="xpf_proto_translate">
<funcdef>string <function>translate</function></funcdef>
<paramdef><parameter>strg</parameter> string</paramdef>
<paramdef><parameter>search_list</parameter> string</paramdef>
<paramdef><parameter>replace_list</parameter> string</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="xpf_desc_translate"><title>Description</title>
<para>
The function returns the <parameter>strg</parameter> with occurrences of
characters in the <parameter>search_list</parameter>
replaced by the character at the corresponding position in the <parameter>replace_list</parameter>.
If there is a character in the <parameter>search_list</parameter> with no character at a
corresponding position in the <parameter>replace_list</parameter>
(because the <parameter>replace_list</parameter> is longer than the <parameter>replace_list</parameter>),
then occurrences of that character in <parameter>strg</parameter> string are removed.
</para>
<para>
If a character occurs more than once in the <parameter>search_list</parameter>,
then the first occurrence determines the replacement character.
If the <parameter>replace_list</parameter> is longer than the <parameter>search_list</parameter>,
then excess characters are ignored.
</para>
<para>
Two popular use cases for this function are case conversion and sorting with collation.
For "to-upper" case conversion,
the <parameter>search_list</parameter> consists of all lowercase characters of some language and
the <parameter>replace_list</parameter> consists of all uppercase characters of that language.
For "to-lower" case conversion, uppercase chars are in the <parameter>search_list</parameter>
and lowercase are in the <parameter>replace_list</parameter>.
For sorting with collation, the function must be used in "select" string expression
attribute of <xsl:sort> element; the <parameter>search_list</parameter> consists of all
characters reordered by collation and the <parameter>replace_list</parameter> consists of
corresponding characters from "collation string".
</para>
</refsect1>
<refsect1 id="xpf_params_translate"><title>Parameters</title>
<refsect2><title>strg</title>
<para>String that must be translated.</para></refsect2>
<refsect2><title>search_list</title>
<para>String of characters that must be edited in the <parameter>strg</parameter>.</para></refsect2>
<refsect2><title>replace_list</title>
<para>String of characters that must be inserted in the <parameter>strg</parameter>.</para></refsect2>
</refsect1>
<refsect1 id="xpf_ret_translate"><title>Return Types</title><para>String</para></refsect1>
<refsect1 id="xpf_errors_translate"><title>Errors</title>
<table><title>Errors signalled by translate()</title>
<tgroup cols="4">
<thead><row><entry>SQLState</entry><entry>Error Code</entry><entry>Error Text</entry><entry>Description</entry></row></thead>
<tbody>
<row>
<entry><errorcode>XP001</errorcode></entry>
<entry><errorcode>XPF07</errorcode></entry>
<entry><errorname>Too long string passed as argument 1 to XPATH function translate(), the result of translation is too long</errorname></entry>
<entry>Virtuoso cannot process strings that are longer than 10M. This limit may be exceed if UTF-8 representations of the replacement characters are longer than representations of replaced characters; even if the number of encoded characters remains the same or decrements.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1 id="xpf_examples_translate"><title>Examples</title>
<example id="xpf_ex_translate"><title>Trivial cases</title>
<para>The following expressions are true:</para>
<screen>
translate("abracadabra","abc","ABC") = "ABrACAdABrA".
translate("ab-ra-ca-dab-ra","abc-","ABC") = "ABrACAdABrA".
</screen>
</example>
<example id="xpf_ex_translate"><title>Sorting with collation in XSL</title>
<para>The following <xsl:sort> will sort records by its titles,
making no difference between spaces and punctuation marks.
In addition, spaces will be normalized after
the collation processing.</para>
<screen>
<xsl:key select="normalize-space(translate('@title','.,:;!?',' '))"/>
</screen>
</example>
</refsect1>
<refsect1 id="xpf_seealso_translate"><title>See Also</title>
<para><link linkend="xpf_replace">replace()</link><link linkend="xpf_normalize_space">normalize-space()</link></para>
</refsect1>
</refentry>
|
