Documented the precision of arithmetical operations
Project: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/commit/2aebfe53 Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/tree/2aebfe53 Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/diff/2aebfe53 Branch: refs/heads/2.3-gae Commit: 2aebfe53331a6306481d44cee94eb45c6f42797b Parents: e3d1bb8 Author: ddekany <ddek...@apache.org> Authored: Sat Aug 5 11:05:32 2017 +0200 Committer: ddekany <ddek...@apache.org> Committed: Sat Aug 5 11:05:32 2017 +0200 ---------------------------------------------------------------------- .../java/freemarker/core/ArithmeticEngine.java | 5 +++-- src/manual/en_US/book.xml | 18 ++++++++++++++++-- 2 files changed, 19 insertions(+), 4 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/2aebfe53/src/main/java/freemarker/core/ArithmeticEngine.java ---------------------------------------------------------------------- diff --git a/src/main/java/freemarker/core/ArithmeticEngine.java b/src/main/java/freemarker/core/ArithmeticEngine.java index c07dc92..5e485b8 100644 --- a/src/main/java/freemarker/core/ArithmeticEngine.java +++ b/src/main/java/freemarker/core/ArithmeticEngine.java @@ -30,9 +30,10 @@ import freemarker.template.utility.OptimizerUtil; import freemarker.template.utility.StringUtil; /** - * Class to perform arithmetic operations. + * Used for implementing the arithmetic operations and number comparisons in the template language. The concrete + * implementation is plugged into the configuration with the {@code arithmetical_engine} setting. + * (See {@link Configurable#setArithmeticEngine(ArithmeticEngine)}.) */ - public abstract class ArithmeticEngine { /** http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/2aebfe53/src/manual/en_US/book.xml ---------------------------------------------------------------------- diff --git a/src/manual/en_US/book.xml b/src/manual/en_US/book.xml index e072d1a..1288f8a 100644 --- a/src/manual/en_US/book.xml +++ b/src/manual/en_US/book.xml @@ -3304,8 +3304,6 @@ Slicing with right-unlimited ranges: </listitem> </itemizedlist> - <remark>Information about the precision?</remark> - <para>Example:</para> <programlisting role="template">${100 - x * x} @@ -3385,6 +3383,22 @@ ${12 % 6.9} <#-- Prints 0 --></programlisting> ${-12 % 5} <#-- Prints -2 --> ${12 % -5} <#-- Prints 2 --> </programlisting> + + <para role="forProgrammers">About the precision of the operations: + By default FreeMarker uses <literal>BigDecimal</literal>-s for all + arithmetical calculations, to avoid rounding and overflow/underflow + artifacts, and also keeps the result as + <literal>BigDecimal</literal>-s. So <literal>+</literal> (addition), + <literal>-</literal> (subtraction) and <literal>*</literal> + (multiplication) are <quote>lossless</quote>. Again by default, + <literal>/</literal> (division) results are calculated to 12 + decimals with half-up rounding (unless some operands have even more + decimals, in which case it's calculated with that much decimals). + All this behavior depends on the + <literal>arithmetic_engine</literal> configuration setting + (<literal>Configurable.setArithmericEngine(ArithmericEngine)</literal>) + though, and some application might use a different value than the + default, although that's highly uncommon.</para> </section> <section xml:id="dgui_template_exp_comparison">