| <!doctype html> |
| <!-- Generated by FreeMarker/Docgen from DocBook --> |
| <html lang="en" class="page-type-section"> |
| <head prefix="og: http://ogp.me/ns#"> |
| <meta charset="utf-8"> |
| <title>Built-ins for numbers - Apache FreeMarker Manual</title> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge"> |
| <meta name="viewport" content="width=device-width,initial-scale=1"> |
| <meta name="format-detection" content="telephone=no"> |
| <meta property="og:site_name" content="Apache FreeMarker Manual"> |
| <meta property="og:title" content="Built-ins for numbers"> |
| <meta property="og:locale" content="en_US"> |
| <meta property="og:url" content="https://freemarker.apache.org/docs/ref_builtins_number.html"> |
| <link rel="canonical" href="https://freemarker.apache.org/docs/ref_builtins_number.html"> |
| <link rel="icon" href="favicon.png" type="image/png"> |
| <link rel="stylesheet" type="text/css" href="https://fonts.googleapis.com/css?family=Roboto:500,700,400,300|Droid+Sans+Mono"> |
| <link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css?1707770044859"> |
| <script type="text/javascript" src="https://cdn.jsdelivr.net/npm/cookie-bar/cookiebar-latest.min.js"></script> |
| </head> |
| <body itemscope itemtype="https://schema.org/Code"> |
| <meta itemprop="url" content="https://freemarker.apache.org/docs/"> |
| <meta itemprop="name" content="Apache FreeMarker Manual"> |
| |
| <!--[if lte IE 9]> |
| <div class="oldBrowserWarning" style="display: block"> |
| Unsupported web browser - Use a modern browser to view this website! |
| </div> |
| <![endif]--> <div class="oldBrowserWarning"> |
| Unsupported web browser - Use a modern browser to view this website! |
| </div> |
| <div class="header-top-bg"><div class="site-width header-top"><div id="hamburger-menu" role="button"></div> <div class="logo"> |
| <a href="https://freemarker.apache.org" role="banner"><img itemprop="image" src="logo.png" alt="FreeMarker"></a> </div> |
| <ul class="tabs"><li><a href="https://freemarker.apache.org/">Home</a></li><li class="current"><a href="index.html">Manual</a></li><li><a class="external" href="api/index.html">Java API</a></li></ul><ul class="secondary-tabs"><li><a class="tab icon-heart" href="https://freemarker.apache.org/contribute.html" title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://issues.apache.org/jira/projects/FREEMARKER" title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="https://freemarker.apache.org/freemarkerdownload.html" title="Download"><span>Download</span></a></li></ul></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="index.html" class="navigation-header">Manual</a><div class="navigation-header"></div><form method="get" class="search-form" action="search-results.html"><fieldset><legend class="sr-only">Search form</legend><label for="search-field" class="sr-only">Search query</label><input id="search-field" name="q" type="search" class="search-input" placeholder="Search" spellcheck="false" autocorrect="off" autocomplete="off"><button type="submit" class="search-btn"><span class="sr-only">Search</span></button></fieldset></form></div><div class="site-width breadcrumb-row"> <div class="breadcrumbs"> |
| <ul class="breadcrumb" itemscope itemtype="http://schema.org/BreadcrumbList"><li class="step-0" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="index.html"><span itemprop="name">Apache FreeMarker Manual</span></a></li><li class="step-1" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="ref.html"><span itemprop="name">Template Language Reference</span></a></li><li class="step-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="ref_builtins.html"><span itemprop="name">Built-in Reference</span></a></li><li class="step-3" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="ref_builtins_number.html"><span itemprop="name">Built-ins for numbers</span></a></li></ul> </div> |
| <div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul><li><a href="alphaidx.html">Alpha. index</a></li><li><a href="gloss.html">Glossary</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions</a></li><li><a href="ref_builtins_alphaidx.html">?builtins</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_specvar.html">.spec_vars</a></li><li><a href="app_faq.html">FAQ</a></li></ul></div></div></div> <div class="main-content site-width"> |
| <div class="content-wrapper"> |
| <div id="table-of-contents-wrapper" class="col-left"> |
| <script>var breadcrumb = ["Apache FreeMarker Manual","Template Language Reference","Built-in Reference","Built-ins for numbers"];</script> |
| <script src="toc.js?1707770044859"></script> |
| <script src="docgen-resources/main.min.js?1707770044859"></script> |
| </div> |
| <div class="col-right"><div class="page-content"><div class="page-title"><div class="pagers top"><a class="paging-arrow previous" href="ref_builtins_string.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_builtins_date.html"><span>Next</span></a></div><div class="title-wrapper"> |
| <h1 class="content-header header-section1" id="ref_builtins_number" itemprop="headline">Built-ins for numbers</h1> |
| </div></div><div class="page-menu"> |
| <div class="page-menu-title">Page Contents</div> |
| <ul><li><a class="page-menu-link" href="#ref_builtin_abs" data-menu-target="ref_builtin_abs">abs</a></li><li><a class="page-menu-link" href="#ref_builtin_c" data-menu-target="ref_builtin_c">c (for numbers)</a></li><li><a class="page-menu-link" href="#ref_builtin_cn" data-menu-target="ref_builtin_cn">cn (for numbers)</a></li><li><a class="page-menu-link" href="#ref_builtin_is_infinite" data-menu-target="ref_builtin_is_infinite">is_infinite</a></li><li><a class="page-menu-link" href="#ref_builtin_is_nan" data-menu-target="ref_builtin_is_nan">is_nan</a></li><li><a class="page-menu-link" href="#ref_builtin_lower_abc" data-menu-target="ref_builtin_lower_abc">lower_abc</a></li><li><a class="page-menu-link" href="#ref_builtin_rounding" data-menu-target="ref_builtin_rounding">round, floor, ceiling</a></li><li><a class="page-menu-link" href="#ref_builtin_string_for_number" data-menu-target="ref_builtin_string_for_number">string (when used with a numerical value)</a></li><li><a class="page-menu-link" href="#ref_builtin_upper_abc" data-menu-target="ref_builtin_upper_abc">upper_abc</a></li></ul> </div><p>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 <a href="app_faq.html#faq_number_grouping">this</a> and <a href="app_faq.html#faq_number_decimal_point">this</a> FAQ entry, also note |
| the <code class="inline-code">c</code> built-in above.</p> |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_abs">abs</h2> |
| |
| |
| |
| |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This built-in exists since FreeMarker 2.3.20.</p> |
| </div> |
| |
| |
| <p>Gives the absolute value of a number. For example |
| <code class="inline-code">x?abs</code> , if <code class="inline-code">x</code> is -5, will |
| evaluate to 5.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_c">c (for numbers)</h2> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>The <code class="inline-code">c</code> built-in also works <a href="ref_builtins_boolean.html#ref_builtin_c_boolean">on booleans</a>, and <a href="ref_builtins_string.html#ref_builtin_c_string">on strings</a>!</p> |
| </div> |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>To provide a background, see <a href="dgui_misc_computer_vs_human_format.html">Template Author's Guide/Miscellaneous/Formatting for humans, or for computers</a></p> |
| </div> |
| |
| |
| <p>This built-in converts a number to a "computer |
| language" literal, as opposed to format it for human reading. |
| This format is independent of the <code class="inline-code">locale</code> (human |
| language, country) and <code class="inline-code">number_format</code> settings of |
| FreeMarker. Instead, it depends on the <a href="gloss.html#gloss.c_format"><code>c_format</code> setting</a>, |
| which is usually something like <code class="inline-code">"JSON"</code>; a |
| computer language.</p> |
| |
| <p>This built-in is crucial because by default (like with |
| <code class="inline-code">${x}</code>) numbers are converted to strings with the |
| locale specific number formatting, so 3000000 is possibly printed as |
| <code class="inline-code">3,000,000</code> (i.e., with grouping separators), or |
| <code class="inline-code">3.14</code> is possibly printed as |
| <code class="inline-code">3,14</code> (i.e., with a different decimal separator). |
| 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) you must use this built-in to format the number (i.e., use |
| <code class="inline-code">${x?c}</code> instead of <code class="inline-code">${x}</code>), or |
| else the output will be possibly unparsable for the consumer.</p> |
| |
| <p>The exact format of numbers depend on value of the |
| <code class="inline-code">c_format</code> setting, but for all the |
| <code class="inline-code">c_format</code>-s that are built into FreeMarker, these |
| sand:</p> |
| |
| <ul> |
| <li> |
| <p>It always uses dot as decimal separator</p> |
| </li> |
| |
| <li> |
| <p>It always uses dot as decimal separator</p> |
| </li> |
| |
| <li> |
| <p>Never uses "+" sign (as in +1), except maybe |
| after the "E" that signifies the exponent |
| part</p> |
| </li> |
| |
| <li> |
| <p>No superfluous leading or trailing 0-s (like 03 or |
| 1.0)</p> |
| </li> |
| |
| <li> |
| <p>It usually avoids exponential form (like it will never |
| format 10000000000 as 1E10), but see the details below regarding |
| that.</p> |
| </li> |
| </ul> |
| |
| <p>Finder details:</p> |
| |
| <ul> |
| <li> |
| <p>Rounding:</p> |
| |
| <ul> |
| <li> |
| <p>For all that are built into FreeMarker, except |
| "legacy" <code class="inline-code">c_format </code>: There's |
| no rounding.</p> |
| </li> |
| |
| <li> |
| <p>For the deprecated <code class="inline-code">c_format</code>, |
| "legacy": The numbers are limited to 16 digits |
| after the decimal dot, so rounding can occur. The these |
| formats never use exponential form either, so the decimal |
| point place is fixed. Thus, for example, 1E-17 will be |
| formatted as <code class="inline-code">0</code>.</p> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p>Special floating point values, positive infinity, negative |
| infinity, and NaN (for Not-a-Number):</p> |
| |
| <ul> |
| <li> |
| <p>For <code class="inline-code">c_format</code>-s "JSON", |
| and "JavaScript", "JavaScript or |
| JSON": <code class="inline-code">Infinity</code>, |
| <code class="inline-code">-Infinity</code>, <code class="inline-code">NaN</code></p> |
| </li> |
| |
| <li> |
| <p>For <code class="inline-code">c_format</code> "Java": |
| If the value has Java type <code class="inline-code">double</code> or |
| <code class="inline-code">Double</code>: |
| <code class="inline-code">Double.POSITIVE_INFINITY</code>, |
| <code class="inline-code">Double.NEGATIVE_INFINITY</code>, |
| <code class="inline-code">Double.NaN</code>. If the value has Java type |
| <code class="inline-code">float</code> or <code class="inline-code">Float</code>: |
| <code class="inline-code">Float.POSITIVE_INFINITY</code>, |
| <code class="inline-code">Float.NEGATIVE_INFINITY</code>, |
| <code class="inline-code">Float.NaN</code>.</p> |
| </li> |
| |
| <li> |
| <p>For <code class="inline-code">c_format</code> "XS", and |
| also if <a href="pgui_config_incompatible_improvements.html"><code>incompatible_improvements</code> |
| setting</a> is at least 2.3.21, for |
| <code class="inline-code">c_format</code>, "legacy": |
| <code class="inline-code">INF</code>, <code class="inline-code">-INF</code>, and |
| <code class="inline-code">NaN</code>.</p> |
| </li> |
| |
| <li> |
| <p>For <code class="inline-code">c_format</code> "legacy", |
| if <a href="pgui_config_incompatible_improvements.html"><code>incompatible_improvements</code> |
| setting</a> is less than 2.3.21: Gives what |
| <code class="inline-code">java.text.DecimalFormat</code> does with US |
| locale, which are <code class="inline-code">∞</code>, |
| <code class="inline-code">-∞</code>, and <code class="inline-code">�</code> (U+FFFD, |
| replacement character).</p> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p>Exponential form is used by all |
| <code class="inline-code">c_format</code>-s that are built into FreeMarker, |
| except "legacy":</p> |
| |
| <ul> |
| <li> |
| <p>For a non-whole number whose absolute value is less |
| than 1E-6 (0.000001).</p> |
| </li> |
| |
| <li> |
| <p>For a whole number that has more than 100 digits in |
| non-exponential form</p> |
| </li> |
| |
| <li> |
| <p>For a whole numbers whose absolute value is too big |
| for the backing floating point type to be safe from rounding |
| errors. More specifically:</p> |
| |
| <ul> |
| <li> |
| <p>For a whole number that's stored in a |
| <code class="inline-code">double</code>, or <code class="inline-code">Double</code> |
| on the Java side (i.e., as 64 bit floating point |
| number), and has an absolute value greater than |
| 9007199254740992. It's because that type can't store all |
| whole numbers outside that range. So if the intent was |
| to store some ID-s, they are likely already corrupted |
| (because they had to be rounded to the closest whole |
| number that the type can store), and you should use |
| <code class="inline-code">long</code> or <code class="inline-code">BigInteger</code> |
| on the Java side.</p> |
| </li> |
| |
| <li> |
| <p>For a whole (integer) value that's stored in a |
| <code class="inline-code">float</code>, or <code class="inline-code">Float</code> on |
| the Java side (i.e., as 32 bit floating point number), |
| and has an absolute value greater than 16777216. |
| Reasoning is the same as for |
| <code class="inline-code">double</code>.</p> |
| </li> |
| </ul> |
| |
| <p>Note that by default FreeMarker doesn't use |
| <code class="inline-code">double</code> or <code class="inline-code">float</code>, so |
| such values are likely come from the data-model.</p> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p>Currently, in the <code class="inline-code">c_format</code>-s that are |
| built into FreeMarker, the output never contains superfluous |
| zeros after the decimal point. Thus, unlike in Java, you can't |
| tell apart a <code class="inline-code">double</code> from an |
| <code class="inline-code">int</code>, if they store the same number |
| mathematically, because the output will look the same for both. |
| (This is because the template language only have a single number |
| type, so you don't have a good control over the backing Java |
| type.)</p> |
| </li> |
| </ul> |
| |
| <p>If you only generate output that's computer language and isn't |
| read by end-users, you may prefer to set the |
| <code class="inline-code">number_format</code> configuration setting to |
| <code class="inline-code">"c"</code> (since FreeMarker 2.3.32, |
| <code class="inline-code">"computer"</code> before that), in which case |
| <code class="inline-code">${<em class="code-color">aNumber</em>}</code> will have |
| the same output as |
| <code class="inline-code">${<em class="code-color">aNumber</em>?c}</code>. (In this |
| case you should use a <code class="inline-code">c_format</code> like |
| <code class="inline-code">"JavaScript or JSON"</code>, and not |
| <code class="inline-code">"legacy"</code>, as that emulates some confusing old |
| glitches.)</p> |
| |
| <p>If the value the <code class="inline-code">c</code> built-in is applied on |
| is <code class="inline-code">null</code>/missing, it will stop the template |
| processing with error, just like most other built-ins. If instead |
| you want to output a <code class="inline-code">null</code> literal, see the <a href="#ref_builtin_cn"><code>cn</code> |
| built-in</a>.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_cn">cn (for numbers)</h2> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p><code class="inline-code">cn</code> works with all types that |
| <code class="inline-code">c</code> does, and thus for strings and booleans as |
| well. The formatting of <code class="inline-code">null</code>/missing doesn't |
| depend on the type of course (as we have no value that could have |
| a type).</p> |
| </div> |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>See <a href="dgui_misc_computer_vs_human_format.html">Template Author's Guide/Miscellaneous/Formatting for humans, or for computers</a> for |
| background</p> |
| </div> |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This built-in exists since FreeMarker 2.3.32</p> |
| </div> |
| |
| |
| <p>This is the same as the <a href="#ref_builtin_c"><code>c</code> built-in</a>, except |
| if the value on its left side is <code class="inline-code">null</code>/missing, |
| this won't stop with error, but outputs a <code class="inline-code">null</code> |
| literal that's appropriate for the current |
| <code class="inline-code">c_format</code> setting:</p> |
| |
| <ul> |
| <li> |
| <p>For "JSON", "Java", |
| "JavaScript", and "legacy": |
| <code class="inline-code">null</code></p> |
| </li> |
| |
| <li> |
| <p>For "XS" (used for generating XML that |
| follows XML Schema principles): 0 length string (i.e., |
| <code class="inline-code">${<em class="code-color">thisIsNull</em>?cn}</code> |
| prints nothing), which is often not good enough (see below), but |
| we can't do better with a |
| <code class="inline-code"><em class="code-color">stringValue</em>?c</code> |
| alone. The idea is that you write something like |
| <code class="inline-code"><full-name>${fullName?nc}</full-name></code>, |
| or <code class="inline-code"><user <em class="code-color">...</em> |
| full-name="${fullName?nc}" /></code>, and then, in case |
| <code class="inline-code">fullName</code> is <code class="inline-code">null</code>, the |
| output will be |
| <code class="inline-code"><full-name></full-name></code>, and |
| <code class="inline-code"><user <em class="code-color">...</em> full-name="" |
| /></code>. Some applications accept that as the equivalent |
| of a <code class="inline-code">null</code>, at least where a string value is |
| expected according the XML Schema.</p> |
| |
| <p>Note that the XML Schema approach is that you skip |
| outputting the whole <code class="inline-code">full-name</code> XML element, |
| or XML attribute. For that you have to write <code class="inline-code"><#if |
| fullName??><full-name>${full-name?c}</full-name></#if></code>, |
| and <code class="inline-code"><user <em class="code-color">...</em> <#if |
| fullName??>full-name="${fullName?c}"</#if> |
| /></code>. When using such condition, and the value is a |
| string (as with this example), you might as well just write |
| <code class="inline-code">${fullName}</code>, without the |
| <code class="inline-code">?c</code>.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_is_infinite">is_infinite</h2> |
| |
| |
| |
| |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This built-in exists since FreeMarker 2.3.20.</p> |
| </div> |
| |
| |
| <p>Tells if a number is floating point infinite (according to |
| IEEE 754). For example, <code class="inline-code">someNumber?is_infinite</code> |
| evaluates to <code class="inline-code">true</code> or <code class="inline-code">false</code> |
| depending on if the value of <code class="inline-code">someNumber</code> is |
| infinite or not. Of course, if the underlying number is not of |
| floating point type, this will always return |
| <code class="inline-code">false</code>.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_is_nan">is_nan</h2> |
| |
| |
| |
| |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This built-in exists since FreeMarker 2.3.20.</p> |
| </div> |
| |
| |
| <p>Tells if a number is floating point NaN (according to IEEE |
| 754). For example, <code class="inline-code">someNumber?is_nan</code> evaluates to |
| <code class="inline-code">true</code> or <code class="inline-code">false</code> depending on if |
| the value of <code class="inline-code">someNumber</code> is NaN or not. Of course, |
| if the underlying number is not of floating point type, this will |
| always return <code class="inline-code">false</code>.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_lower_abc">lower_abc</h2> |
| |
| |
| |
| |
| |
| |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This built-in exists since FreeMarker 2.3.22.</p> |
| </div> |
| |
| |
| <p>Converts <code class="inline-code">1</code>, <code class="inline-code">2</code>, |
| <code class="inline-code">3</code>, etc., to the string <code class="inline-code">"a"</code>, |
| <code class="inline-code">"b"</code>, <code class="inline-code">"c"</code>, etc. When reaching |
| <code class="inline-code">"z"</code>, it continues like <code class="inline-code">"aa"</code>, |
| <code class="inline-code">"ab"</code>, etc. This is the same logic that you can |
| see in column labels in spreadsheet applications (like Excel or |
| Calc). The lowest allowed number is <code class="inline-code">1</code>. There's no |
| upper limit. If the number is <code class="inline-code">0</code> or less or it |
| isn't an integer number then the template processing will be aborted |
| with error.</p> |
| |
| <p>Example:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#list 1..30 as n>${n?lower_abc} </#list></pre> </div> |
| |
| |
| <p>Prints:</p> |
| |
| |
| |
| <div class="code-block role-output"> |
| <div class="code-block-label">Output</div><pre class="code-block-body">a b c d e f g h i j k l m n o p q r s t u v w x y z aa ab ac ad </pre> </div> |
| |
| |
| <p>See also: <a href="#ref_builtin_upper_abc"><code>upper_abc</code></a></p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_rounding">round, floor, ceiling</h2> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>The rounding built-ins exist since FreeMarker 2.3.13.</p> |
| </div> |
| |
| |
| <p>Converts a number to a whole number using the specified |
| rounding rule:</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">round</code>: Rounds to the nearest whole |
| number. If the number ends with .5, then it rounds upwards |
| (i.e., towards positive infinity)</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">floor</code>: Rounds the number downwards |
| (i.e., towards neagative infinity)</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">ceiling</code>: Rounds the number upwards |
| (i.e., towards positive infinity)</p> |
| </li> |
| </ul> |
| |
| <p>Example:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#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></pre> </div> |
| |
| |
| <p>Prints:</p> |
| |
| |
| |
| <div class="code-block role-output"> |
| <div class="code-block-label">Output</div><pre class="code-block-body"> 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</pre> </div> |
| |
| |
| <p>These built-ins may be useful in pagination operations and |
| like. If you just want to <em>display</em> numbers in |
| rounded form, then you should rather use the <a href="#ref_builtin_string_for_number"><code>string</code> |
| built-in</a> or the <a href="ref_directive_setting.html#ref.setting.number_format"><code>number_format</code> |
| setting</a>.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_string_for_number">string (when used with a numerical value)</h2> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <p>Converts a number to a string. In its simplest form |
| (<code class="inline-code"><em class="code-color">expression</em>?string</code>) it |
| uses the default format that the programmer has specified via the |
| <code class="inline-code">number_format</code> and the <code class="inline-code">locale</code> |
| configuration settings. You can also specify a number format |
| explicitly with this built-in, as it will be shown later.</p> |
| |
| <p>There are four predefined number formats: <code class="inline-code">c</code> |
| (since 2.3.32, before that it was called |
| <code class="inline-code">computer</code>, which still works), |
| <code class="inline-code">currency</code>, <code class="inline-code">number</code>, and |
| <code class="inline-code">percent</code>. The exact meaning of these is locale |
| (nationality) specific, and is controlled by the Java platform |
| installation, not by FreeMarker, except for <code class="inline-code">c</code>, |
| which uses the same formatting as <a href="#ref_builtin_c">the |
| <code>c</code> built-in</a> (assuming <a href="pgui_config_incompatible_improvements.html">incompatible |
| improvements</a> set to 2.3.31, or higher, or else infinity and |
| NaN isn't formatted like that). There can also be programmer-defined |
| formats, whose name starts with <code class="inline-code">@</code> (programmers |
| <a href="pgui_config_custom_formats.html">see more here...</a>). |
| You can use these predefined formats like this:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#assign x=4200000> |
| ${x} |
| ${x?string} <#-- the same as ${x} --> |
| ${x?string.number} |
| ${x?string.currency} |
| ${x?string.percent} |
| ${x?string.c} <#-- But you should write ${x?c} --></pre> </div> |
| |
| |
| <p>If your locale is US English, this will print:</p> |
| |
| |
| |
| <div class="code-block role-output"> |
| <div class="code-block-label">Output</div><pre class="code-block-body">4,200,000 |
| 4,200,000 |
| 4,200,000 |
| $4,200,000.00 |
| 420,000,000% |
| 4200000</pre> </div> |
| |
| |
| <p>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:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#setting number_format="currency"> |
| <#assign x=4200000> |
| ${x} |
| ${x?string} <#-- the same as ${x} --> |
| ${x?string.number} |
| ${x?string.currency} |
| ${x?string.percent}</pre> </div> |
| |
| |
| <p>Will now output:</p> |
| |
| |
| |
| <div class="code-block role-output"> |
| <div class="code-block-label">Output</div><pre class="code-block-body">$4,200,000.00 |
| $4,200,000.00 |
| 4,200,000 |
| $4,200,000.00 |
| 420,000,000%</pre> </div> |
| |
| |
| <p>since the default number format was set to |
| "currency".</p> |
| |
| <p>You can also refer to named custom formats that were defined |
| when configuring FreeMarker (programmers <a href="pgui_config_custom_formats.html">see more here</a>), |
| like:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body">${x?string.@price} |
| ${x?string.@weight}</pre> </div> |
| |
| |
| <p>where the custom format names were "price" and |
| "weight". This way the templates can just refer to the |
| application-domain meaning, and the exact format can be specified |
| outside the templates, on a single central place. (Programmers can |
| read about <a href="pgui_config_custom_formats.html">defining such |
| named formats here...</a>)</p> |
| |
| <p>Beside named formats, you can specify number format patterns |
| directly, using the <a href="http://docs.oracle.com/javase/7/docs/api/java/text/DecimalFormat.html">Java |
| decimal number format syntax</a> (with some FreeMarker-specific |
| extensions; <a href="#topic.extendedJavaDecimalFormat">see |
| later</a>):</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#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"]}</pre> </div> |
| |
| |
| |
| |
| <div class="code-block role-output"> |
| <div class="code-block-label">Output</div><pre class="code-block-body">1 |
| 1.2 |
| 1.23 |
| 1.234 |
| 1.234 |
| |
| 001.00 |
| 012.10 |
| 123.46 |
| |
| 1 |
| 2 |
| 2 <-- 1.5, rounded towards even neighbor |
| 2 <-- 2.5, rounded towards even neighbor |
| |
| 1.23E4</pre> </div> |
| |
| |
| <p>Note that as in FreeMarker <code class="inline-code">foo.bar</code> is |
| equivalent with <code class="inline-code">foo["bar"]</code>, you could also write |
| <code class="inline-code">x?string.currency</code> as |
| <code class="inline-code">x?string["currency"]</code>, but of course that wouldn't |
| be practical. But in the above examples we have to use the square |
| bracket syntax, because the characters involved (numbers, dot, |
| <code class="inline-code">#</code>) aren't allowed syntactically after the dot |
| operator.</p> |
| |
| <p>For historical reasons, you could also write things like |
| <code class="inline-code">x?string("0.#")</code>, which does exactly the same as |
| <code class="inline-code">x?string["0.#"]</code>.</p> |
| |
| <p>Following the financial and statistics practice, by default |
| 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. 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 <a href="#topic.extendedJavaDecimalFormat">described |
| later</a>.</p> |
| |
| <p>As it was shown for the predefined formats earlier, the |
| default formatting of the numbers can be set in the template:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#setting number_format="0.##"> |
| ${1.234}</pre> </div> |
| |
| |
| |
| |
| <div class="code-block role-output"> |
| <div class="code-block-label">Output</div><pre class="code-block-body">1.23</pre> </div> |
| |
| |
| <p>The default number format also can be specified outside the |
| templates with the FreeMarker API (like with |
| <code class="inline-code">Configuration.setNumberFormat(String)</code>).</p> |
| |
| <p>Note that as number formatting is locale sensitive, the locale |
| setting also plays role in the formatting:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#setting number_format=",##0.00"> |
| <#setting locale="en_US"> |
| US people write: ${12345678} |
| <#setting locale="de_DE"> |
| German people write: ${12345678}</pre> </div> |
| |
| |
| |
| |
| <div class="code-block role-output"> |
| <div class="code-block-label">Output</div><pre class="code-block-body">US people write: 12,345,678.00 |
| German people write: 12.345.678,00</pre> </div> |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-simplesect" id="topic.extendedJavaDecimalFormat">Extended Java decimal format</h3> |
| |
| |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>You need at least FreeMarker 2.3.24 for these to work. |
| Before that, extended Java decimal format parts are just |
| silently ignored by |
| <code class="inline-code">java.text.DecimalFormat</code>.</p> |
| </div> |
| |
| |
| <p>FreeMarker extends the Java decimal format patterns with |
| extra options. These options are name-value pairs, specified after |
| two semicolons (<code class="inline-code">;;</code>) 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 <code class="inline-code">"0.0;minus |
| 0.0"</code>), the after only one semicolon. For example:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body">Standard decimal format: ${10002.5?string[",000"]} |
| Extended decimal format: ${10002.5?string[",000<strong>;; roundingMode=halfUp groupingSeparator=_</strong>"]}</pre> </div> |
| |
| |
| |
| |
| <div class="code-block role-output"> |
| <div class="code-block-label">Output</div><pre class="code-block-body">Standard decimal format: 10,002 |
| Extended decimal format: 10<strong>_</strong>00<strong>3</strong></pre> </div> |
| |
| |
| <div class="callout warning"> |
| <strong class="callout-label">Warning!</strong> |
| |
| <p>A very easy mistake to make is just using a single |
| semicolon instead of two. It won't even result in an error, as |
| <code class="inline-code">java.text.DecimalFormat</code> thinks you have just |
| specified some weird format for negative numbers. So remember to |
| use two semicolons.</p> |
| </div> |
| |
| |
| <p>Above, in the extended decimal format, we have specified |
| half-up rounding mode and group separator <code class="inline-code">"_"</code>. |
| The table of all options follows (note that these are defined by |
| <code class="inline-code">java.text.DecimalFormat</code> and |
| <code class="inline-code">java.text.DecimalFormatSymbols</code>, not by |
| FreeMarker):</p> |
| |
| <div class="table-responsive"> |
| <table class="table"> |
| |
| <thead> |
| <tr> |
| <th>Name</th> |
| |
| |
| <th>Meaning / value</th> |
| |
| </tr> |
| |
| </thead> |
| |
| |
| <tbody> |
| <tr> |
| <td><code class="inline-code">roundingMode</code></td> |
| |
| |
| <td>The value is one of <code class="inline-code">up</code>, |
| <code class="inline-code">down</code>, <code class="inline-code">ceiling</code>, |
| <code class="inline-code">floor</code>, <code class="inline-code">halfUp</code>, |
| <code class="inline-code">halfDown</code>, <code class="inline-code">halfEven</code>, |
| and <code class="inline-code">unnecessary</code>. The behavior that most |
| people learns in school is <code class="inline-code">halfUp</code>, but |
| the Java default is <code class="inline-code">halfEven</code> (also called |
| bankers' rounding). (See <a href="http://docs.oracle.com/javase/7/docs/api/java/math/RoundingMode.html">the |
| <code>java.math.RoundingMode</code> API</a> for |
| explanations.)</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">multiplier</code> since 2.3.29; |
| <code class="inline-code">multipier</code> since 2.3.24</td> |
| |
| |
| <td>The number will be shown after multiplied with this |
| integer number.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">decimalSeparator</code></td> |
| |
| |
| <td>The character separating the integer part from the |
| fraction part (like <code class="inline-code">"."</code> in |
| <code class="inline-code">3.14</code>).</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">monetaryDecimalSeparator</code></td> |
| |
| |
| <td>This is used instead of |
| <code class="inline-code">decimalSeparator</code> when the pattern |
| contains parts that make it a monetary format. (See the |
| <a href="http://docs.oracle.com/javase/7/docs/api/java/text/DecimalFormat.html">Java |
| decimal number format documentation</a> for more.)</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">groupingSeparator</code></td> |
| |
| |
| <td>The single character used for grouping the integer part |
| (like <code class="inline-code">","</code> in |
| <code class="inline-code">1,000,000</code>) Note that grouping is turned |
| on by using <code class="inline-code">","</code> in the pattern, as shown |
| in the earlier example. If it's not turned on, this option |
| won't have visible effect.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">exponentSeparator</code></td> |
| |
| |
| <td>This string (of arbitrary length) is used to separate |
| the exponent from the part before it. (like |
| <code class="inline-code">"E"</code> in <code class="inline-code">1.23E6</code>). Only |
| has visible effect if the pattern specifies exponential |
| (also known as scientific) format, like |
| <code class="inline-code">"0.##E0"</code>.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">minusSign</code></td> |
| |
| |
| <td>The single character used as minus sign (like |
| <code class="inline-code">"-"</code> in <code class="inline-code">-1</code>).</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">infinity</code></td> |
| |
| |
| <td>The string (of arbitrary length) used to show |
| infinity.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">nan</code></td> |
| |
| |
| <td>The string (of arbitrary length) used to show |
| not-a-number (NaN).</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">percent</code></td> |
| |
| |
| <td>The single character used as the percent symbol (like |
| <code class="inline-code">"%"</code> in <code class="inline-code">50%</code>). Only has |
| visible effect if the pattern contains |
| <code class="inline-code">%</code>.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">perMill</code></td> |
| |
| |
| <td>The single character used as the per-mill symbol (like |
| <code class="inline-code">"‰"</code> in <code class="inline-code">50021‰</code>). Only |
| has visible effect if the pattern contains |
| <code class="inline-code">‰</code>.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">zeroDigit</code></td> |
| |
| |
| <td>The first character in the 10 character range (of |
| character codes) that contains the digits to be used. For |
| example, if this is <code class="inline-code">A</code>, then 1 will |
| <code class="inline-code">B</code>, 2 will be <code class="inline-code">C</code>, and so |
| on.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">currencyCode</code></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><code class="inline-code">currencySymbol</code></td> |
| |
| |
| <td>Currency symbol; shown where the localized currency name |
| is present in the pattern. Overrides the symbol determined |
| based on the <code class="inline-code">currencyCode</code>.</td> |
| |
| </tr> |
| |
| </tbody> |
| |
| </table> |
| </div> |
| |
| |
| <p>Regarding the syntax of the options:</p> |
| |
| <ul> |
| <li> |
| <p>The option name and value are separated by equals |
| character (<code class="inline-code">=</code>).</p> |
| </li> |
| |
| <li> |
| <p>Options are separated by whitespace and/or optional |
| comma (<code class="inline-code">,</code>)</p> |
| </li> |
| |
| <li> |
| <p>The option value can be quoted with apostrophe |
| (<code class="inline-code">'</code>) or normal quotation mark |
| (<code class="inline-code">"</code>) , like |
| <code class="inline-code">exponentSeparator='*10^'</code> or |
| <code class="inline-code">exponentSeparator="*10^"</code>. If the value |
| itself has to contain the character used for quotation, then |
| it has to be entered twice (like <code class="inline-code">infinity='It''s |
| infinite'</code>, but you could also write |
| <code class="inline-code">infinity="It's infinite"</code>). Backslash has no |
| special meaning.</p> |
| </li> |
| |
| <li> |
| <p>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-<code class="inline-code">"_"</code> |
| non-<code class="inline-code">"$"</code> characters. Thus, for example, both |
| <code class="inline-code">roundingMode=down</code> and |
| <code class="inline-code">roundingMode="down"</code> are legal.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_upper_abc">upper_abc</h2> |
| |
| |
| |
| |
| |
| |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This built-in exists since FreeMarker 2.3.22.</p> |
| </div> |
| |
| |
| <p>Same as <a href="#ref_builtin_lower_abc"><code>lower_abc</code></a>, |
| but converts to upper case letters, like <code class="inline-code">"A"</code>, |
| <code class="inline-code">"B"</code>, <code class="inline-code">"C"</code>, …, |
| <code class="inline-code">"AA"</code>, <code class="inline-code">"AB"</code>, etc.</p> |
| <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="ref_builtins_string.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_builtins_date.html"><span>Next</span></a></div></div></div></div> </div> |
| </div> |
| <div class="site-footer"><div class="site-width"><div class="footer-top"><div class="col-left sitemap"><div class="column"><h3 class="column-header">Overview</h3><ul><li><a href="https://freemarker.apache.org/">What is FreeMarker?</a></li><li><a href="https://freemarker.apache.org/freemarkerdownload.html">Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="app_faq.html">FAQ</a></li><li><a itemprop="license" href="app_license.html">License</a></li><li><a href="https://privacy.apache.org/policies/privacy-policy-public.html">Privacy policy</a></li></ul></div><div class="column"><h3 class="column-header">Often used / Reference</h3><ul><li><a href="https://try.freemarker.apache.org/">Try template online</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions cheatsheet</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_builtins_alphaidx.html">?built_ins</a></li><li><a href="ref_specvar.html">.special_vars</a></li><li><a href="api/freemarker/core/Configurable.html#setSetting-java.lang.String-java.lang.String-">Configuration settings</a></li></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href="https://github.com/apache/freemarker">Github project page</a></li><li><a href="https://issues.apache.org/jira/projects/FREEMARKER">Report a bug</a></li><li><a href="https://freemarker.apache.org/report-security-vulnerabilities.html">Report security vulnerability</a></li><li><a href="https://stackoverflow.com/questions/ask?tags=freemarker">Get help on StackOverflow</a></li><li><a href="https://twitter.com/freemarker">Announcements on Twitter</a></li><li><a href="https://freemarker.apache.org/mailing-lists.html">Discuss on mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/apache/freemarker">Github</a></li><li><a class="twitter" href="https://twitter.com/freemarker">Twitter</a></li><li><a class="stack-overflow" href="https://stackoverflow.com/questions/ask?tags=freemarker">Stack Overflow</a></li></ul><a class="xxe" href="http://www.xmlmind.com/xmleditor/" rel="nofollow" title="Edited with XMLMind XML Editor"><span>Edited with XMLMind XML Editor</span></a></div></div><div class="footer-bottom"> <p class="last-generated"> |
| Last generated: |
| <time itemprop="dateModified" datetime="2024-02-12T20:34:04Z" title="Monday, February 12, 2024 at 8:34:04 PM Greenwich Mean Time">2024-02-12 20:34:04 GMT</time>, for Freemarker 2.3.32 </p> |
| <p class="copyright"> |
| © <span itemprop="copyrightYear">1999</span>–2024 |
| <a itemtype="http://schema.org/Organization" itemprop="copyrightHolder" href="https://apache.org/">The Apache Software Foundation</a>. Apache FreeMarker, FreeMarker, Apache Incubator, Apache, the Apache FreeMarker logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners. </p> |
| </div></div></div></body> |
| </html> |
