Built-ins for numbers

c

expr?c

Converts a number to a string which is independent of any locale and number format settings of RPL.

This built-in is crucial because by default, numbers are converted to strings with the locale-specific number formatting. When the number is not meant for users (for example, for a database record ID used as the part of an URL, or as an invisible field value in an HTML form), you must use this built-in to print the number (i.e., use ${x?c} instead of ${x}); otherwise the output might be incorrect, depending on the current number formatting settings and locale, and the value of the number.

The built-in always uses the dot as decimal separator.

The built-in never uses any of the following:

Grouping separators (such as 3,000,000)
Exponential form (such as 5E20)
Superfluous leading or trailing zeros (such as 03 or 1.0)
Plus sign (for example +1)

The built-in prints at most 16 digits after the decimal dot, thus numbers whose absolute value is less than 1E-16 will be shown as 0.

hex

expr?hex

Converts a number to its hexadecimal representation, without padding. To add padding, convert the number to a string, then use the left_pad built-in for strings.

Example:

<#assign x=32>

${x}

${x?hex}

0x${x?hex?string?left_pad(8, “0”)}

produces this output:

0x00000020

isnull (when used with a numerical value)

exp?isnull

Useful only for expressions representing fields from the database.

When a numeric field in the database is NULL, RPL internally converts it to a zero, but temporarily retains the fact that this field came from a NULL value. This built-in returns true if the number came from a NULL value, otherwise returns false. For non-database fields, the built-in always returns false. When an operation that involves a database field is performed (for instance adding a field to a number), the result does not retain whether the value is NULL in the database.

The following example shows a field in the database that results in a NULL:

<#-- NULL is remembered -->

<#if profile.nullnumber?isnull>

profile.nullnumber is NULL

<#else>

profile.nullnumber is NOT NULL

</#if>

<#-- but zero is assumed, so zero plus one is one -->

${profile.nullnumber+1}

<#-- the result is no longer null -->

<#if (profile.nullnumber+0)?isnull>

profile.nullnumber+0 is NULL

<#else>

profile.nullnumber+0 is NOT NULL

</#if>

produces this output:

profile.nullnumber is NULL

profile.nullnumber+0 is NOT NULL

round, floor, ceiling

expr?round

expr?floor

expr?ceiling

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

round
Rounds to the nearest whole number. If the number ends with .5, then it rounds up (i.e., towards positive infinity).

floor
Rounds the number down (i.e., towards negative infinity).

ceiling
Rounds the number up (i.e., towards positive infinity).

These built-ins are useful for pagination and similar operations. If you want to display numbers in rounded form, use the string built-in or the number_format setting.

Example:

<#assign testlist=[

  0, 1, -1, 0.5, 1.5, -0.5,

  -1.5, 0.25, -0.25, 1.75, -1.75]>

<#list testlist as result>

    ${result} ?floor=${result?floor} ?ceiling=${result?ceiling} ?round=${result?round}

</#list>

produces this output:

    0 ?floor=0 ?ceiling=0 ?round=0

    1 ?floor=1 ?ceiling=1 ?round=1

    -1 ?floor=-1 ?ceiling=-1 ?round=-1

    0.5 ?floor=0 ?ceiling=1 ?round=1

    1.5 ?floor=1 ?ceiling=2 ?round=2

    -0.5 ?floor=-1 ?ceiling=0 ?round=0

    -1.5 ?floor=-2 ?ceiling=-1 ?round=-1

    0.25 ?floor=0 ?ceiling=1 ?round=0

    -0.25 ?floor=-1 ?ceiling=0 ?round=0

    1.75 ?floor=1 ?ceiling=2 ?round=2

    -1.75 ?floor=-2 ?ceiling=-1 ?round=-2

string (when used with a numerical value)

expr?string

expr?string(mask-expr)

Converts a number to a string.

This built-in uses the default format specified by the system. You can also specify a number format explicitly.

RPL supports four predefined number formats: computer, currency, number, and percent. The exact meaning of currency, number, and percent is locale-specific, and is controlled by the Java platform installation rather than by RPL. The computer format uses the same formatting as the c built-in. You can use these predefined

formats as shown in the following example:

<#assign x=42>

${x}

${x?string}  <#-- the same as ${x} -->

${x?string.number}

${x?string.currency}

${x?string.percent}

${x?string.computer}

If your locale is US English, the example produces the following output:

$42.00

4,200%

The output of the 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 x=42>

${x}

${x?string}  <#-- the same as ${x} -->

${x?string.number}

${x?string.currency}

${x?string.percent}

Because the default number format was set to "currency", the example now produces this output:

$42.00

$42.00

$42.00

4,200%

In addition to the three predefined formats, you can use an arbitrary number format patterns written in the standard decimal number format syntax as:

<#assign x = 1.234>

${x?string("0")}

${x?string("0.#")}

${x?string("0.##")}

${x?string("0.###")}

${x?string("0.####")}

${1?string("000.00")}

${12.1?string("000.00")}

${123.456?string("000.00")}

${1.2?string("0")}

${1.8?string("0")}

${1.5?string("0")} <-- 1.5, rounded towards even neighbor

${2.5?string("0")} <-- 2.5, rounded towards even neighbor

${12345?string("0.##E0")}

produces this output:

1.2

1.23

1.234

1.234

001.00

012.10

123.46

2 <-- 1.5, rounded towards even neighbor

2 <-- 2.5, rounded towards even neighbor

1.23E4

Following the financial and statistics practice, RPL rounds according the “half-even” rule. This means rounding towards the nearest ``neighbor'', unless both neighbors are equidistant. If both neighbors are equidistant, RPL rounds to the even neighbor. This rule is illustrated in the above example: 1.5 and 2.5 are both rounded to 2 is even, but 1 and 3 are odds.

In addition to the standard decimal syntax patterns, you can use ${aNumber?string("currency")} and similar formatting. This produces the same result as ${aNumber?string.currency}, etc.

As with predefined formats, you can set the default number formatting in the template. For example:

<#setting number_format="0.##">

${1.234}

produces this outputs:

1.23

Note that the number formatting is locale sensitive. For example:

<#setting locale="en_US">

In US they write:        ${12345678?string(",##0.00")}

<#setting locale="hu">

In Hungary they write: ${12345678?string(",##0.00")}

produces this output:

In US they write:        12,345,678.00

In Hungary they write: 12 345 678,00