freemarker-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ddek...@apache.org
Subject [03/12] incubator-freemarker git commit: Documented extended DecimalFormat. Some other improvements in formatting-related documentation.
Date Thu, 24 Sep 2015 20:21:36 GMT
Documented extended DecimalFormat. Some other improvements in formatting-related documentation.


Project: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/commit/ee7f23f7
Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/tree/ee7f23f7
Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/diff/ee7f23f7

Branch: refs/heads/2.3
Commit: ee7f23f7f55135bd06ace919b6b5db82c36e4b27
Parents: 7f591d1
Author: ddekany <ddekany@apache.org>
Authored: Fri Sep 18 00:50:27 2015 +0200
Committer: ddekany <ddekany@apache.org>
Committed: Fri Sep 18 00:50:57 2015 +0200

----------------------------------------------------------------------
 src/main/java/freemarker/core/Configurable.java |  22 +-
 src/manual/book.xml                             | 311 +++++++++++++++++--
 2 files changed, 300 insertions(+), 33 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/ee7f23f7/src/main/java/freemarker/core/Configurable.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/core/Configurable.java b/src/main/java/freemarker/core/Configurable.java
index f303086..44e3fcb 100644
--- a/src/main/java/freemarker/core/Configurable.java
+++ b/src/main/java/freemarker/core/Configurable.java
@@ -714,19 +714,27 @@ public class Configurable {
     }
 
     /**
-     * Sets the default number format used to convert numbers to strings. Currently, this
is either a
-     * {@link java.text.DecimalFormat} pattern (like {@code "0.##"}), or one of the following
special values:
+     * Sets the default number format used to convert numbers to strings. Currently, this
is one of these:
      * <ul>
      *   <li>{@code "number"}: The number format returned by {@link NumberFormat#getNumberInstance(Locale)}</li>
      *   <li>{@code "currency"}: The number format returned by {@link NumberFormat#getCurrencyInstance(Locale)}</li>
      *   <li>{@code "percent"}: The number format returned by {@link NumberFormat#getPercentInstance(Locale)}</li>
      *   <li>{@code "computer"}: The number format used by FTL's {@code c} built-in
(like in {@code someNumber?c}).</li>
+     *   <li>{@link java.text.DecimalFormat} pattern (like {@code "0.##"}). This syntax
has a FreeMarker-specific
+     *       extension, so that you can specify options like the rounding mode and the symbols
used in this string. For
+     *       example, {@code ",000;; rnd=hu grp=_"} will format numbers like {@code ",000"}
would, but with half-up
+     *       rounding mode, and {@code _} as the group separator. See more about "extended
Java decimal format" in the
+     *       FreeMarker Manual.
+     *       </li>
+     *   <li>If the string starts with {@code @} character, and
+     *       {@link Configuration#setIncompatibleImprovements(Version)} is at least 2.3.24,
then it's interpreted as a
+     *       custom number format. The format of such string is <code>"@<i>name</i>"</code>
or
+     *       <code>"@<i>name</i> <i>parameters</i>"</code>,
where <code><i>name</i></code> is the key in the
+     *       {@link Map} set by {@link #setCustomNumberFormats(Map)}, and <code><i>parameters</i></code>
is parsed by
+     *       the custom {@link TemplateNumberFormat}.
+     *   </li>
      * </ul>
-     * Or, if {@link Configuration#setIncompatibleImprovements(Version)} is at least 2.3.24,
and the string starts
-     * with {@code @} character, it's interpreted as a custom number format. The format of
such string is
-     * <code>"@<i>name</i>"</code> or <code>"@<i>name</i>
<i>parameters</i>"</code>, where <code><i>name</i></code>
-     * is the key in the {@link Map} set by {@link #setCustomNumberFormats(Map)}, and <code><i>parameters</i></code>
-     * is parsed by the custom number format.
+     * 
      *   
      * <p>Defaults to <tt>"number"</tt>.
      */

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/ee7f23f7/src/manual/book.xml
----------------------------------------------------------------------
diff --git a/src/manual/book.xml b/src/manual/book.xml
index b1135ff..17417ec 100644
--- a/src/manual/book.xml
+++ b/src/manual/book.xml
@@ -12335,7 +12335,7 @@ Green Mouse</programlisting>
           such returns exactly the same Java object that the date parser
           (<literal>freemarker.core.TemplateDateFormat</literal>
           implementation) returns, while <literal>?date</literal> without the
-          <literal>()</literal> returns tricky wrapper that's a date and a
+          <literal>()</literal> returns a tricky wrapper that's a date and a
           method and hash on the same time.</para>
         </section>
 
@@ -14473,8 +14473,9 @@ $42.00
 
           <para>Beside the three predefined formats, you can use arbitrary
           number format patterns written in <link
-          xlink:href="http://java.sun.com/j2se/1.4/docs/api/java/text/DecimalFormat.html">Java
-          decimal number format syntax</link>:</para>
+          xlink:href="http://docs.oracle.com/javase/7/docs/api/java/text/DecimalFormat.html">Java
+          decimal number format syntax</link> (with some FreeMarker-specific
+          extensions; see later):</para>
 
           <programlisting role="template">&lt;#assign x = 1.234&gt;
 ${x?string["0"]}
@@ -14494,8 +14495,6 @@ ${2.5?string["0"]} &lt;-- 2.5, rounded towards even neighbor
 
 ${12345?string["0.##E0"]}</programlisting>
 
-          <para>outputs this:</para>
-
           <programlisting role="output">1
 1.2
 1.23
@@ -14526,13 +14525,18 @@ ${12345?string["0.##E0"]}</programlisting>
           <literal>x?string("0.#")</literal>, which does exactly the same as
           <literal>x?string["0.#"]</literal>.</para>
 
-          <para>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.</para>
+          <para>Following the financial and statistics practice, by default
+          the rounding goes according the so called half-even rule, which
+          means rounding towards the nearest <quote>neighbor</quote>, 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. The other popular rounding rule,
+          where we always round up when the neighbors are equidistant (and so
+          2.5 is rounded to 3) is called the half-up rule, and it can be
+          activated as <link
+          linkend="topic.extendedJavaDecimalFormat">described
+          later</link>.</para>
 
           <para>As it was shown for the predefined formats earlier, the
           default formatting of the numbers can be set in the template:</para>
@@ -14540,10 +14544,12 @@ ${12345?string["0.##E0"]}</programlisting>
           <programlisting role="template">&lt;#setting number_format="0.##"&gt;
 ${1.234}</programlisting>
 
-          <para>outputs this:</para>
-
           <programlisting role="output">1.23</programlisting>
 
+          <para>The default number format also can be specified outside the
+          templates with the FreeMarker API (like with
+          <literal>Configuration.setNumberFormat(String)</literal>).</para>
+
           <para>Note that as number formatting is locale sensitive, the locale
           setting also plays role in the formatting:</para>
 
@@ -14553,10 +14559,189 @@ US people write:     ${12345678}
 &lt;#setting locale="hu"&gt;
 German people write: ${12345678}</programlisting>
 
-          <para>outputs this:</para>
-
           <programlisting role="output">US people write:     12,345,678.00
 German people write: 12.345.678,00</programlisting>
+
+          <simplesect xml:id="topic.extendedJavaDecimalFormat">
+            <title>Extended Java decimal format </title>
+
+            <indexterm>
+              <primary>extended Java decimal format</primary>
+            </indexterm>
+
+            <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
+            string, or if you had a negative pattern (which is separated from
+            the normal patter with a semicolon, like in <literal>"0.0;minus
+            0.0"</literal>), the after only one semicolon. For example:</para>
+
+            <programlisting role="template">Standard decimal format: ${10002.5?string[",000"]}
+Extended decimal format: ${10002.5?string[",000<emphasis>;; rnd=hu grp=_</emphasis>"]}</programlisting>
+
+            <programlisting role="output">Standard decimal format: 10,002
+Extended decimal format: 10<emphasis>_</emphasis>00<emphasis>3</emphasis></programlisting>
+
+            <para>Above, in the extended decimal format, we have specified
+            half-up rounding mode (<literal>rnd=hu</literal>), and group
+            separator <literal>"_"</literal> (<literal>grp=_</literal>).
The
+            table of all options:</para>
+
+            <informaltable border="1">
+              <thead>
+                <tr>
+                  <th>Name</th>
+
+                  <th>Meaning / value</th>
+                </tr>
+              </thead>
+
+              <tbody>
+                <tr>
+                  <td><literal>rnd</literal></td>
+
+                  <td>Rounding mode. The value is one of <literal>u</literal>
+                  for up, <literal>d</literal> for down, <literal>c</literal>
+                  for ceiling, <literal>f</literal> for floor,
+                  <literal>hu</literal> for half-up, <literal>hd</literal>
for
+                  half-down, <literal>he</literal> for half-even, and
+                  <literal>un</literal> for unused. (See <link
+                  xlink:href="http://docs.oracle.com/javase/7/docs/api/java/math/RoundingMode.html">the
+                  <literal>java.math.RoundingMode</literal> API</link>
for
+                  explanations.)</td>
+                </tr>
+
+                <tr>
+                  <td><literal>mul</literal></td>
+
+                  <td>Multiplier. The number will be shown after multiplied
+                  with this integer number.</td>
+                </tr>
+
+                <tr>
+                  <td><literal>dec</literal></td>
+
+                  <td>Decimal separator character (like <literal>"."</literal>
+                  in <literal>3.14</literal>).</td>
+                </tr>
+
+                <tr>
+                  <td><literal>mdec</literal></td>
+
+                  <td>Monetary decimal separator character. This is used
+                  instead of <literal>dec</literal> when the pattern contains
+                  parts that make it a monetary format. (See the <link
+                  xlink:href="http://docs.oracle.com/javase/7/docs/api/java/text/DecimalFormat.html">Java
+                  decimal number format documentation</link> for more.)</td>
+                </tr>
+
+                <tr>
+                  <td><literal>grp</literal></td>
+
+                  <td>Grouping separator character. Note that grouping is
+                  turned on by using <literal>","</literal> in the patter, as
+                  shown in the earlier example. If it's not turned on, this
+                  option won't have visible effect.</td>
+                </tr>
+
+                <tr>
+                  <td><literal>exp</literal></td>
+
+                  <td>Exponent separator string. Only has visible effect if
+                  the pattern specifies exponential form, like
+                  <literal>"0.##E0"</literal>.</td>
+                </tr>
+
+                <tr>
+                  <td><literal>min</literal></td>
+
+                  <td>Minus sign character.</td>
+                </tr>
+
+                <tr>
+                  <td><literal>inf</literal></td>
+
+                  <td>The string used to show infinity.</td>
+                </tr>
+
+                <tr>
+                  <td><literal>nan</literal></td>
+
+                  <td>The string used to show not-a-number (NaN).</td>
+                </tr>
+
+                <tr>
+                  <td><literal>prc</literal></td>
+
+                  <td>Percent character.</td>
+                </tr>
+
+                <tr>
+                  <td><literal>prm</literal></td>
+
+                  <td>Per-mill character.</td>
+                </tr>
+
+                <tr>
+                  <td><literal>zero</literal></td>
+
+                  <td>Zero character. This modifies the other digits too, for
+                  example, if zero is <literal>A</literal>, then 1 will
+                  <literal>B</literal>, 2 will be <literal>C</literal>,
and so
+                  on.</td>
+                </tr>
+
+                <tr>
+                  <td><literal>curc</literal></td>
+
+                  <td>Currency ISO 4217 code. Only has effect when the pattern
+                  contains parts that make it a monetary format. It's an error
+                  to specify a code that's not a known ISO 4217 code in the
+                  Java installation.</td>
+                </tr>
+
+                <tr>
+                  <td><literal>curs</literal></td>
+
+                  <td>Currency symbol; shown where the localized currency name
+                  is present in the pattern. Overrides the symbol determined
+                  from <literal>curc</literal>.</td>
+                </tr>
+              </tbody>
+            </informaltable>
+
+            <para>Regarding the syntax of the options:</para>
+
+            <itemizedlist>
+              <listitem>
+                <para>The option name and value are separated by equals
+                character (<literal>=</literal>).</para>
+              </listitem>
+
+              <listitem>
+                <para>Options are separated by whitespace and/or optional
+                comma (<literal>,</literal>)</para>
+              </listitem>
+
+              <listitem>
+                <para>The option value can be quoted with apostrophe
+                (<literal>'</literal>) or normal quotation mark
+                (<literal>"</literal>) , like <literal>exp='*10^'</literal>
or
+                <literal>exp="*10^"</literal>. If the value itself has to
+                contain the character used for quotation, then it has to be
+                entered twice (like <literal>inf='It''s infinite'</literal>,
+                but you could also write <literal>inf="It's
+                infinite"</literal>). Backslash has no special meaning.</para>
+              </listitem>
+
+              <listitem>
+                <para>Non-string values must not be quoted. Strings only has
+                to be quoted if they contain punctuation or whitespace, or any
+                other non-letter non-digit non-<literal>"_"</literal>
+                non-<literal>"$"</literal> characters.</para>
+              </listitem>
+            </itemizedlist>
+          </simplesect>
         </section>
 
         <section xml:id="ref_builtin_upper_abc">
@@ -20362,16 +20547,46 @@ ${"'{}"}
                   <secondary>number</secondary>
                 </indexterm><literal>number_format</literal>: The number
               format that is used to convert numbers to strings when no
-              explicit format is specified. Can be one of predefined values
-              <literal>number</literal> (the default),
-              <literal>computer</literal>, <literal>currency</literal>,
or
-              <literal>percent</literal>. Additionally, arbitrary format
-              pattern written in <link
-              xlink:href="http://java.sun.com/j2se/1.4/docs/api/java/text/DecimalFormat.html">Java
-              decimal number format syntax</link> can also be specified. More
-              information about format patterns:<link
-              linkend="ref_builtin_string_for_number"><literal>string</literal>
-              built-in</link>.</para>
+              explicit format is specified. Can be one of the
+              following:</para>
+
+              <itemizedlist>
+                <listitem>
+                  <para>Predefined values defined by the Java platform:
+                  <literal>number</literal> (the default),
+                  <literal>currency</literal>, or
+                  <literal>percent</literal></para>
+                </listitem>
+
+                <listitem>
+                  <para><literal>computer</literal>, which formats like
<link
+                  linkend="ref_builtin_c">the <literal>c</literal>
+                  built-in</link></para>
+                </listitem>
+
+                <listitem>
+                  <para>Format pattern written in <link
+                  xlink:href="http://java.sun.com/j2se/1.4/docs/api/java/text/DecimalFormat.html">Java
+                  decimal number format syntax</link>, for example
+                  <literal>0.###</literal>. FreeMarker <link
+                  linkend="topic.extendedJavaDecimalFormat">extends this
+                  format</link> to allow specifying rounding mode, symbols
+                  used, etc.</para>
+                </listitem>
+
+                <listitem>
+                  <para>Values starting with <literal>@</literal>, if <link
+                  linkend="pgui_config_incompatible_improvements_how_to_set">the
+                  <literal>incompatible_improvements</literal> setting</link>
+                  is at least 2.3.24, refers to a <link
+                  linkend="pgui_config_custom_formats">custom format</link>.
+                  For example, <literal>"@price"</literal> refers to the
+                  custom format registered with the <literal>"price"</literal>
+                  name. The custom format name is possibly followed by space
+                  or <literal>_</literal> and then format parameters, whose
+                  interpretation depends on the custom format.</para>
+                </listitem>
+              </itemizedlist>
             </listitem>
 
             <listitem>
@@ -20616,6 +20831,19 @@ ${"'{}"}
                   <literal>"medium_medium"</literal> for date-time
                   values.)</para>
                 </listitem>
+
+                <listitem>
+                  <para>Values starting with <literal>@</literal>, if <link
+                  linkend="pgui_config_incompatible_improvements_how_to_set">the
+                  <literal>incompatible_improvements</literal> setting</link>
+                  is at least 2.3.24, refer to a <link
+                  linkend="pgui_config_custom_formats">custom format</link>,
+                  like <literal>"@departure"</literal> refers to the custom
+                  format registered with the <literal>"departure"</literal>
+                  name. The format name is possibly followed by space or
+                  <literal>_</literal> and then format parameters, whose
+                  interpretation depends on the custom format.</para>
+                </listitem>
               </itemizedlist>
             </listitem>
 
@@ -25534,6 +25762,16 @@ TemplateModel x = env.getVariable("x");  // get variable x</programlisting>
             </listitem>
 
             <listitem>
+              <para>Everywhere where Java <literal>DecimalFormat</literal>
+              patterns are used (like in <literal>?string('0.##')</literal> or
+              <literal>&lt;#setting number_format="0.##"&gt;</literal>),
now
+              it's possible to specify options like rounding mode or the
+              symbols used, with a FreeMarker-specific <link
+              linkend="topic.extendedJavaDecimalFormat">extension to the
+              pattern syntax</link>.</para>
+            </listitem>
+
+            <listitem>
               <para>Added new special variable:
               <literal>.incompatible_improvements</literal>, which returns the
               <link
@@ -25730,6 +25968,16 @@ TemplateModel x = env.getVariable("x");  // get variable x</programlisting>
             </listitem>
 
             <listitem>
+              <para>In the <literal>number_format</literal> configuration
+              setting, when it holds a Java <literal>DecimalFormat</literal>
+              pattern (like <literal>"0.##"</literal>), it's now possible to
+              specify options like rounding mode or the symbols used, with a
+              FreeMarker-specific <link
+              linkend="topic.extendedJavaDecimalFormat">extension to the
+              pattern syntax</link>.</para>
+            </listitem>
+
+            <listitem>
               <para>Added
               <literal>freemarker.cache.ByteArrayTemplateLoader</literal>,
               which is similar to <literal>StringTemplateLoader</literal>, but
@@ -25891,6 +26139,17 @@ TemplateModel x = env.getVariable("x");  // get variable x</programlisting>
             </listitem>
 
             <listitem>
+              <para>Everywhere where Java <literal>DecimalFormat</literal>
+              patterns are used (like in the <literal>number_format</literal>
+              configuration setting, or in
+              <literal>?string('0.##')</literal>), now it's possible to
+              specify options like rounding mode or the symbols used, with a
+              FreeMarker-specific <link
+              linkend="topic.extendedJavaDecimalFormat">extension to the
+              pattern syntax</link>.</para>
+            </listitem>
+
+            <listitem>
               <para><literal>?date</literal>, <literal>?time</literal>
and
               <literal>?datetime</literal> now can be called as 0 argument
               method, like <literal>?date()</literal>, etc., which returns the


Mime
View raw message