# 22. Virtuoso Functions Guide - format-number

Chapter Contents | Prev | Next
Keyword Search:
www.openlinksw.com
docs.openlinksw.com
Book Home
Contents
Preface
Virtuoso Functions Guide
Administration
Aggregate Functions
Array Manipulation
BPEL APIs
Backup
Compression
Cursor
Date & Time Manipulation
Debug
Dictionary Manipulation
Encoding & Decoding
File Manipulation
Free Text
Hashing / Cryptographic
LDAP
Locale
Mail
Miscellaneous
Number
Remote SQL Data Source
Replication
SOAP
SQL
String
Transaction
Type Mapping
UDDI
User Defined Types & The CLR
Virtuoso Java PL API
Virtuoso Server Extension Interface (VSEI)
Web Server & Internet
XML
XPATH & XQUERY
and
append
assign
avg
boolean
ceiling
concat
contains
count
create-attribute
create-comment
create-element
create-pi
current
distinct
doc
document
document-literal
empty
ends-with
every
except
false
filter
floor
fn:collection
for
format-number
function-available
generate-id
id
if
intersect
is_after()
is_before()
key
lang
last
let
list()
local-name
max
min
name
namespace-uri
normalize-space
not
number
or
position
processxquery
processxslt
processxsql
progn()
replace()
round
serialize
shallow
some
starts-with
string
string-length
substring
substring-after
substring-before
sum
system-property
text_contains()
translate
true
tuple()
union
unordered
unparsed-entity-uri
urlify
xmlview
Functions Index

## format-number

string format-number ( num number, format_pattern string, [decimal_format string]);
Description

The function converts the num argument to a string using the format pattern string specified by the format_pattern and the decimal-format named by the decimal_format, or the default decimal-format, if there is no third argument.

The format pattern string is in the syntax specified by the JDK 1.1 DecimalFormat class. The following describes the structure of the pattern.

- 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.

- Every subpattern consists of optional prefix characters followed by an integer part followed by an optional fraction part followed by an optional suffix characters.

- 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.

- 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.

By default, the following characters are treated as special when used in the parts of the subpattern:

Symbol | Meaning
--- | ---
0 | A digit, zero will be printed. 0 must be the last character of integer part.
# | A digit, zero will not be printed.
. | Placeholder for decimal separator in the beginning of fraction part.
, | Placeholder for grouping separator. It may appear only in integer part. All commas except the last will be ignored.
; | Separates formats. It may appear only once in the pattern.
- | Placeholder for negative prefix.
% | Indicates that the value must be multiplied by 100 and shown as percentage.
? | Indicates that the value must be multiplied by 1000 and shown as per mille.

Note that character '¤' have a special meahing in DecimalFormat of JDK 1.1, but not in XPATH.

The format pattern string may be in a localized notation. The decimal_format may determine what characters have a special meaning in the pattern (with the exception of the quote character, which is not localized). The decimal_format must be a QName, and a search will be performed for top-level <xsl:decimal-format> key whose "key" attribute is equal to decimal_format; 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.

Parameters
num – Number to format.
format_pattern – Format pattern which must be applied to the number.
decimal_format – Name of <xsl:decimal-format> element which must be used to parse format pattern.
Return Types

String

Errors

SQLState | Error Code | Error Text | Description
--- | --- | --- | ---
XS370 | XS036 | Number format ... is not defined in XPath function format-number() | The function is called outside an XSLT processor or the current stylesheet contains no format definition with the required name.

Examples

If the XSLT stylesheet defines format 'financial' as '###,###.00####', then the following returns '123,456.789':

    format(123456.789, "fincancial")