Manual: Noting some common pitfalls when using extended Java decimal format
Project: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/commit/c630a41a Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/tree/c630a41a Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/diff/c630a41a Branch: refs/heads/2.3 Commit: c630a41ab68059ba2e658aaea4281cd512b2f38e Parents: 54bd25b Author: ddekany <ddek...@apache.org> Authored: Tue Mar 13 09:48:39 2018 +0100 Committer: ddekany <ddek...@apache.org> Committed: Tue Mar 13 09:48:39 2018 +0100 ---------------------------------------------------------------------- src/manual/en_US/book.xml | 15 +++++++++++++++ 1 file changed, 15 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/c630a41a/src/manual/en_US/book.xml ---------------------------------------------------------------------- diff --git a/src/manual/en_US/book.xml b/src/manual/en_US/book.xml index 231b607..52f67af 100644 --- a/src/manual/en_US/book.xml +++ b/src/manual/en_US/book.xml @@ -15568,6 +15568,13 @@ German people write: 12.345.678,00</programlisting> <primary>extended Java decimal format</primary> </indexterm> + <note> + <para>You need at least FreeMarker 2.3.24 for these to work. + Before that, extended Java decimal format parts are just + silently ignored by + <literal>java.text.DecimalFormat</literal>.</para> + </note> + <para>FreeMarker extends the Java decimal format patterns with extra options. These options are name-value pairs, specified after two semicolons (<literal>;;</literal>) at the end of the format @@ -15581,6 +15588,14 @@ Extended decimal format: ${10002.5?string[",000<emphasis>;; roundingMode=halfUp <programlisting role="output">Standard decimal format: 10,002 Extended decimal format: 10<emphasis>_</emphasis>00<emphasis>3</emphasis></programlisting> + <warning> + <para>A very easy mistake to make is just using a single + semicolon instead of two. It won't even result in an error, as + <literal>java.text.DecimalFormat</literal> thinks you have just + specified some weird format for negative numbers. So remember to + use two semicolons.</para> + </warning> + <para>Above, in the extended decimal format, we have specified half-up rounding mode and group separator <literal>"_"</literal>. The table of all options follows (note that these are defined by
