| <!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>Formatting for humans, or for computers - 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="Formatting for humans, or for computers"> |
| <meta property="og:locale" content="en_US"> |
| <meta property="og:url" content="https://freemarker.apache.org/docs/dgui_misc_computer_vs_human_format.html"> |
| <link rel="canonical" href="https://freemarker.apache.org/docs/dgui_misc_computer_vs_human_format.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="dgui.html"><span itemprop="name">Template Author's Guide</span></a></li><li class="step-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="dgui_misc.html"><span itemprop="name">Miscellaneous</span></a></li><li class="step-3" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="dgui_misc_computer_vs_human_format.html"><span itemprop="name">Formatting for humans, or for computers</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 Author\'s Guide","Miscellaneous","Formatting for humans, or for computers"];</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="dgui_misc_autoescaping.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_misc_whitespace.html"><span>Next</span></a></div><div class="title-wrapper"> |
| <h1 class="content-header header-section1" id="dgui_misc_computer_vs_human_format" itemprop="headline">Formatting for humans, or for computers</h1> |
| </div></div><p>By default |
| <code class="inline-code">${<em class="code-color">someValue</em>}</code> outputs |
| numbers, date/time/date-time and boolean values in a format that |
| targets normal users ("humans"). You have various |
| settings to specify how that format looks, like |
| <code class="inline-code">number_format</code>, <code class="inline-code">date_format</code>, |
| <code class="inline-code">time_format</code>, <code class="inline-code">datetime_format</code>, |
| <code class="inline-code">boolan_format</code>. The output also often depends on the |
| <code class="inline-code">locale</code> setting (i.e., on the language, and country |
| of the user). 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).</p><p>At some places you need to output values that will be read |
| (parsed) by some program, in which case always use the <a href="ref_builtins_number.html#ref_builtin_c"><code>c</code> built-in</a>, as in |
| <code class="inline-code">${<em class="code-color">someValue</em>?c}</code> (the |
| "c" stands for Computer). <em>Then the formatting |
| depends on the <code class="inline-code">c_format</code> <a href="pgui_config_settings.html">setting</a></em>, which |
| usually refers to a computer language, like <code class="inline-code">"JSON"</code>. |
| The output of <code class="inline-code">?c</code> is not influenced by |
| <code class="inline-code">locale</code>, <code class="inline-code">number_format</code>, |
| etc.</p><p>The <code class="inline-code">c</code> built-in will format string values to |
| string literals. Like if the <code class="inline-code">c_format</code> setting is |
| <code class="inline-code">"JSON"</code>, then <code class="inline-code">{"fullName": |
| ${fullName?c}}</code> will output something like |
| <code class="inline-code">{"fullName": "John Doe"}</code>, where the quotation marks |
| (and <code class="inline-code">\</code> escaping if needed) were added by |
| <code class="inline-code">?c</code>.</p> <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>At least as of 2.3.32, the <code class="inline-code">c</code> built-in |
| doesn't support date/time/datetime values, only numbers, booleans, |
| and strings.</p> |
| </div> |
| <p>When formatting for computers, at some places you want to output |
| a <code class="inline-code">null</code> (or its equivalent in the target language) |
| if the value you print is missing/<code class="inline-code">null</code>. The |
| convenient shortcut for that is using the <code class="inline-code">cn</code> |
| built-in (the "n" stands for Nullable), as in |
| <code class="inline-code">${<em class="code-color">someValue</em>?cn}</code>. It |
| behaves like the <code class="inline-code">c</code> built-in, except that if |
| <code class="inline-code"><em class="code-color">someValue</em></code> evaluates to |
| <code class="inline-code">null</code>/missing, it outputs the |
| <code class="inline-code">null</code> literal in the syntax that the |
| <code class="inline-code">c_format</code> setting specifies, instead of stopping |
| with missing value error.</p><p>For the templates where the output is obviously only for |
| computer consumption, some prefers setting the |
| <code class="inline-code">number_format</code>, and |
| <code class="inline-code">boolean_format</code> settings to <code class="inline-code">"c"</code>. |
| (Before 2.3.32, for <code class="inline-code">number_format</code> you have to use |
| <code class="inline-code">"computer"</code> instead.) Then |
| <code class="inline-code">${<em class="code-color">someValue</em>}</code>, for |
| number, and boolean values will format like <code class="inline-code">?c</code> |
| does. To output string literals (i.e, to add quotation and escaping), |
| you will still need an explicit <code class="inline-code">?c</code>. Also if you |
| need to output <code class="inline-code">null</code> literals, you still have to use |
| <code class="inline-code">?cn</code>.</p><p>These are the table of supported <code class="inline-code">c_format</code> |
| setting values (as of FreeMarker 2.3.32), and their intended |
| use:</p><ul> |
| <li> |
| <p><code class="inline-code">"JSON"</code>: JSON generation. Generally, |
| <code class="inline-code">"JavaScript or JSON"</code> (see later) is recommended |
| over this.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"JavaScript"</code>: JavaScript generation. |
| Generally, <code class="inline-code">"JavaScript or JSON"</code> (see later) is |
| recommended over this.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"Java"</code>: Java source code |
| generation</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"XS"</code>: XML Schema compliant XML |
| generation</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"JavaScript or JSON"</code>: For generating |
| output that's compatible with both JSON and JavaScript. This setup |
| is therefore resilient against configuration mistakes, where we |
| generate output in one language, but use the |
| <code class="inline-code">c_format</code> for the other. The small price to pay |
| is that we can't utilize some language-specific opportunities to |
| make the output a bit shorter, but that hardly matters in |
| practice. This is the default if if the <a href="pgui_config_incompatible_improvements.html"><code>incompatible_improvements</code> |
| setting</a> is at least 2.3.32.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"legacy"</code>: Default for backward |
| compatibility when the <a href="pgui_config_incompatible_improvements.html"><code>incompatible_improvements</code> |
| setting</a> is less than 2.3.32. Avoid! Can have rounding |
| losses, and formatting glitches for infinity and NaN.</p> |
| </li> |
| </ul><p>The behaviour of these is documented at the <code class="inline-code">c</code> |
| built-in: <a href="ref_builtins_number.html#ref_builtin_c">for numbers</a>, <a href="ref_builtins_boolean.html#ref_builtin_c_boolean">for boolean</a>, <a href="ref_builtins_string.html#ref_builtin_c_string">for strings</a>, <a href="ref_builtins_number.html#ref_builtin_cn">for null-s</a>.</p><div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="dgui_misc_autoescaping.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_misc_whitespace.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> |
