Built-ins for numbers

Related FAQs: Do you have things like 1,000,000 or 1 000 000 instead of 1000000, or something like 3.14 instead of 3,14 or vice versa? See this and this FAQ entry, also note the c built-in above.

c

This built-in converts a number to string for ``computer audience'' as opposed to human audience. That is, it formats with the rules that programming languages used to use (concretely the Java programming language), which is independent of all locale and number format settings. No grouping separators, and always uses dot as decimal separator. This is useful because otherwise numbers are converted to strings (like when they are pritend with an interpolation as ${x}) with the locale (language, country) specific number formatting, which is for human readers (like 300000 is printed as 3,000,000). This way when the number is printed not for human audience (e.g. for a database record ID used as the part of an URL or as invisible field value in a HTML form, or for printing CSS/JavaScript numerical literals) this built-in must be used to print the number (i.e. use ${x?c} instead of ${x}), or else the output will be broken depending on the current number formatting settings and locale (like the decimal point is not dot, but comma in many countries) and the value of numbers (like big numbers are possibly ``damaged'' by grouping separators).

string

Converts a number to a string. It uses the default format that the programmer has specified. Note also that you can also explicitly specify a number or date format to use.

Speaking first of number formatting, there are three predefined number formats: number, currency, and percent. In this sense, you can use all of the below expressions:

<#assign answer=42/>
${answer}
${answer?string}  <#-- the same as ${answer} -->
${answer?string.number}
${answer?string.currency}
${answer?string.percent}  

If your locale is US English, this will produce:

42
42
42
$42.00
4,200%  

The output of first three expressions is identical because the first two expressions use the default format, which is "number" here. You can change this default using a setting:

<#setting number_format="currency"/>
<#assign answer=42/>
${answer}
${answer?string}  <#-- the same as ${answer} -->
${answer?string.number}
${answer?string.currency}
${answer?string.percent}  

Will now output:

$42.00
$42.00
42
$42.00
4,200%  

since the default number format was set to "currency".

Beside the three predefined formats, you can use arbitrary number format patterns written in Java decimal number format syntax both as a default setting or as an explicit format selector:

<#setting number_format="0.###E0"/>
${1234}
${12345?string("0.####E0")}  

outputs this:

1.234E3
1.2345E4  

Note that you can also write ${answer?string("number")} that will do the same as ${answer?string.number}.

Note that the number formatting is locale sensitive:

<#setting locale="en_US">
US people writes:        ${12345678?string(",##0.00")}
<#setting locale="hu">
Hungarian people writes: ${12345678?string(",##0.00")}  

outputs this:

US people writes:        12,345,678.00
Hungarian people writes: 12 345 678,00  

You can find information about the formatting of dates here.


Page generated: 2006-03-15 13:49:01 GMT FreeMarker Manual -- For FreeMarker 2.3.6