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.

abs

Gives the absolute value of a number. For example x?abs , if x is -5, will evaluate to 5.

c (when used with numerical value)

This built-in converts a number to string for a "computer language" as opposed to for 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 3000000 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).

Note that this built-in also works on booleans.

string (when used with a numerical value)

Converts a number to a string. It uses the default format that the programmer has specified. You can also specify a number format explicitly with this built-in, as it will be shown later.

There are four predefined number formats: computer, currency, number, and percent. The exact meaning of these is locale (nationality) specific, and is controlled by the Java platform installation, rather than by FreeMarker, except for computer, which uses the same formatting as the c built-in. You can use these predefined formats like this:

If your locale is US English, this will certainly 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:

Will now output:

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:

outputs this:

Following the financial and statistics practice, the rounding goes according the so called half-even rule, which means rounding towards the nearest ``neighbor'', unless both neighbors are equidistant, in which case, it rounds towards the even neighbor. This was visible in the above example if you look at the rounding of 1.5 and of 2.5, as both were rounded to 2, since 2 is even, but 1 and 3 are odds.

Apart from the Java decimal syntax patterns, you can also write ${aNumber?string("currency")} and like, that will do the same as ${aNumber?string.currency} and like.

As it was shown for the predefined formats earlier, the default formatting of the numbers can be set in the template:

outputs this:

Note that the number formatting is locale sensitive:

outputs this:

is_infinite

Tells if a number is floating point infinite (according to IEEE 754). For example, someNumber?is_infinite evaluates to true or false depending on if the value of someNumber is infinite or not. Of course, if the underlying number is not of floating point type, this will always return false.

is_nan

Tells if a number is floating point NaN (according to IEEE 754). For example, someNumber?is_nan evaluates to true or false depending on if the value of someNumber is NaN or not. Of course, if the underlying number is not of floating point type, this will always return false.

round, floor, ceiling

Converts a number to a whole number using the specified rounding rule:

Example:

Prints:

These built-ins may be useful in pagination operations and like. If you just want to display numbers in rounded form, then you should rather use the string built-in or the number_format setting.