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
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
|
<?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_format_number">
<refmeta>
<refentrytitle>format-number</refentrytitle>
<refmiscinfo>XPATH</refmiscinfo>
</refmeta>
<refnamediv>
<refname>format-number</refname>
<refpurpose></refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis id="xpf_syn_format_number">
<funcprototype id="xpf_proto_format_number">
<funcdef>string <function>format-number</function></funcdef>
<paramdef><parameter>num</parameter> number</paramdef>
<paramdef><parameter>format_pattern</parameter> string</paramdef>
<paramdef><optional><parameter>decimal_format</parameter> string</optional></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="xpf_desc_format_number"><title>Description</title>
<para>
The function converts the <parameter>num</parameter> argument to a string
using the format pattern string specified by the <parameter>format_pattern</parameter>
and the decimal-format named by the <parameter>decimal_format</parameter>,
or the default decimal-format, if there is no third argument.
</para>
<para>
The format pattern string is in the syntax specified by the JDK 1.1 DecimalFormat class.
The following describes the structure of the pattern.
<itemizedlist mark="bullet" spacing="compact">
<listitem><para>The pattern consists of one or two subpatterns, first is for
positive numbers and zero, second is for negative numbers.
Two subpatterns are delimited by semicolon.
If there is only one subpattern, - is prefixed to the positive subpattern.
</para></listitem>
<listitem><para>Every subpattern consists of
optional prefix characters
followed by an integer part
followed by an optional fraction part
followed by an optional suffix characters.
</para></listitem>
<listitem><para>
Prefix and suffix characters are any Unicode characters except special formatting
characters described below, while integer and fraction part consist
only from that special formatting characters. (As an exception,
special characters may appear in prefix in suffix parts if enclosed in single quotes.
</para></listitem>
<listitem><para>
If fractional present, it starts from '.' character, and only one '.'
may occur in the subformat. Thus it is easy to find where each part begins.
</para></listitem>
</itemizedlist>
<para>
By default, the following characters are treated as special when used in the parts of the subpattern:
</para>
<table>
<tgroup cols="2">
<thead><row><entry>Symbol</entry><entry>Meaning</entry></row></thead>
<tbody>
<row><entry>0</entry><entry>A digit, zero will be printed. 0 must be the last character of integer part.</entry></row>
<row><entry>#</entry><entry>A digit, zero will not be printed.</entry></row>
<row><entry>.</entry><entry>Placeholder for decimal separator in the beginning of fraction part.</entry></row>
<row><entry>,</entry><entry>Placeholder for grouping separator. It may appear only in integer part. All commas except the last will be ignored.</entry></row>
<row><entry>;</entry><entry>Separates formats. It may appear only once in the pattern.</entry></row>
<row><entry>-</entry><entry>Placeholder for negative prefix.</entry></row>
<row><entry>%</entry><entry>Indicates that the value must be multiplied by 100 and shown as percentage.</entry></row>
<row><entry>?</entry><entry>Indicates that the value must be multiplied by 1000 and shown as per mille.</entry></row>
</tbody>
</tgroup>
</table>
</para>
<para>
Note that character '' have a special meaning in DecimalFormat of JDK 1.1, but not in XPATH.
</para>
<para>
The format pattern string may be in a localized notation.
The <parameter>decimal_format</parameter> may determine what characters have a special meaning in the pattern
(with the exception of the quote character, which is not localized).
The <parameter>decimal_format</parameter> must be a QName,
and a search will be performed for top-level <xsl:decimal-format> key
whose "key" attribute is equal to <parameter>decimal_format</parameter>;
all names will be expanded before the search.
It is an error if the stylesheet does not contain a declaration of the decimal-format with the specified expanded name.
</para></refsect1>
<refsect1 id="xpf_params_format_number"><title>Parameters</title>
<refsect2><title>num</title><para>Number to format.</para></refsect2>
<refsect2><title>format_pattern</title><para>Format pattern which must be applied to the number.</para></refsect2>
<refsect2><title>decimal_format</title><para>Name of <xsl:decimal-format> element which must be used to parse format pattern.</para></refsect2>
</refsect1>
<refsect1 id="xpf_ret_format_number"><title>Return Types</title><para>String</para></refsect1>
<refsect1 id="xpf_errors_NNN"><title>Errors</title>
<table><title>Errors signalled by</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>XS370</errorcode></entry>
<entry><errorcode>XS036</errorcode></entry>
<entry><errorname>Number format ... is not defined in XPath function format-number()</errorname></entry>
<entry>The function is called outside an XSLT processor or the current stylesheet contains no format definition with the required name.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1 id="xpf_examples_format_number"><title>Examples</title>
<example id="xpf_ex_format_number"><title></title>
<para>If the XSLT stylesheet defines format 'financial' as '###,###.00####', then the following returns '123,456.789':</para>
<screen>format(123456.789, "financial")</screen>
</example>
</refsect1>
</refentry>
|
