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.
Note
This built-in exists since FreeMarker 2.3.3.
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, which is independent of all the locale and number format settings of FreeMarker. It always uses dot as decimal separator, and it never uses grouping separators (like 3,000,000), nor exponential form (like 5E20), nor superfluous leading or trailing 0-s (like 03 or 1.0), nor + sign (like +1). It will print at most 16 digits after the decimal dot, and thus numbers whose absolute value is less than 1E-16 will be shown as 0. This built-in is crucial because be default (like with ${x}) numbers are converted to strings with the locale (language, country) specific number formatting, which is for human readers (like 300000 is possibly printed as 3,000,000). 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 possibly 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 the number (like big numbers are possibly ``damaged'' by grouping separators).
string (when used with a numerical value)
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:
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:
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.
