Google Git
Sign in
apache / freemarker-docgen / f6eb79676240e0fa3a9154cdb825da28220fc9b9 / . / legacy-tests / build / test / 1 / ref_builtins_string.html
blob: fb673e102ce0e606f7caaa95f578179433a0931f [file] [log] [blame]
<!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 strings - 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="FreeMarker Manual">
<meta property="og:title" content="Built-ins for strings">
<meta property="og:locale" content="en_US">
<meta property="og:url" content="http://example.com/ref_builtins_string.html">
<link rel="canonical" href="http://example.com/ref_builtins_string.html">
<link rel="icon" href="favicon.png" type="image/png">
<link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css?1594338519184">
</head>
<body itemscope itemtype="https://schema.org/Code">
<meta itemprop="url" content="http://example.com/">
<meta itemprop="name" content="FreeMarker Manual">
<!--[if lte IE 9]>
<div style="background-color: #C00; color: #fff; padding: 12px 24px;">Please use a modern browser to view this website.</div>
<![endif]--><div class="header-top-bg"><div class="site-width header-top"><a class="logo" href="http://example.com" role="banner"> <img itemprop="image" src="logo.png" alt="My Logo">
</a></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="index.html" class="navigation-header">FreeMarker Manual</a><div class="navigation-header"></div></div><div class="site-width breadcrumb-row"><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">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">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_string.html"><span itemprop="name">Built-ins for strings</span></a></li></ul><div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><li><a href="alphaidx.html">Index</a></li><li><a href="gloss.html">Glossary</a></li><li><a href="ref.html">Reference</a></li><li><a href="app_faq.html">FAQ</a></li><li><a href="preface.html#test_target">Bőregér</a></li><li><a href="api/index.html">API</a></li><li><a href="../index.html">Home</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 = ["FreeMarker Manual","Reference","Built-in Reference","Built-ins for strings"];</script>
<script src="toc.js?1594338519184"></script>
<script src="docgen-resources/main.min.js?1594338519184"></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.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_builtins_number.html"><span>Next</span></a></div><div class="title-wrapper">
<h1 class="content-header header-section1" id="ref_builtins_string" itemprop="headline">Built-ins for strings</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_substring" data-menu-target="ref_builtin_substring">substring</a></li><li><a class="page-menu-link" href="#ref_builtin_cap_first" data-menu-target="ref_builtin_cap_first">cap_first</a></li><li><a class="page-menu-link" href="#ref_builtin_uncap_first" data-menu-target="ref_builtin_uncap_first">uncap_first</a></li><li><a class="page-menu-link" href="#ref_builtin_capitalize" data-menu-target="ref_builtin_capitalize">capitalize</a></li><li><a class="page-menu-link" href="#ref_builtin_chop_linebreak" data-menu-target="ref_builtin_chop_linebreak">chop_linebreak</a></li><li><a class="page-menu-link" href="#ref_builtin_string_date" data-menu-target="ref_builtin_string_date">date, time, datetime</a></li><li><a class="page-menu-link" href="#ref_builtin_ends_with" data-menu-target="ref_builtin_ends_with">ends_with</a></li><li><a class="page-menu-link" href="#ref_builtin_html" data-menu-target="ref_builtin_html">html</a></li><li><a class="page-menu-link" href="#ref_builtin_groups" data-menu-target="ref_builtin_groups">groups</a></li><li><a class="page-menu-link" href="#ref_builtin_index_of" data-menu-target="ref_builtin_index_of">index_of</a></li><li><a class="page-menu-link" href="#ref_builtin_j_string" data-menu-target="ref_builtin_j_string">j_string</a></li><li><a class="page-menu-link" href="#ref_builtin_js_string" data-menu-target="ref_builtin_js_string">js_string</a></li><li><a class="page-menu-link" href="#ref_builtin_last_index_of" data-menu-target="ref_builtin_last_index_of">last_index_of</a></li><li><a class="page-menu-link" href="#ref_builtin_length" data-menu-target="ref_builtin_length">length</a></li><li><a class="page-menu-link" href="#ref_builtin_lower_case" data-menu-target="ref_builtin_lower_case">lower_case</a></li><li><a class="page-menu-link" href="#ref_builtin_left_pad" data-menu-target="ref_builtin_left_pad">left_pad</a></li><li><a class="page-menu-link" href="#ref_builtin_right_pad" data-menu-target="ref_builtin_right_pad">right_pad</a></li><li><a class="page-menu-link" href="#ref_builtin_contains" data-menu-target="ref_builtin_contains">contains</a></li><li><a class="page-menu-link" href="#ref_builtin_matches" data-menu-target="ref_builtin_matches">matches</a></li><li><a class="page-menu-link" href="#ref_builtin_number" data-menu-target="ref_builtin_number">number</a></li><li><a class="page-menu-link" href="#ref_builtin_replace" data-menu-target="ref_builtin_replace">replace</a></li><li><a class="page-menu-link" href="#ref_builtin_rtf" data-menu-target="ref_builtin_rtf">rtf</a></li><li><a class="page-menu-link" href="#ref_builtin_url" data-menu-target="ref_builtin_url">url</a></li><li><a class="page-menu-link" href="#ref_builtin_split" data-menu-target="ref_builtin_split">split</a></li><li><a class="page-menu-link" href="#ref_builtin_starts_with" data-menu-target="ref_builtin_starts_with">starts_with</a></li><li><a class="page-menu-link" href="#ref_builtin_string_for_string" data-menu-target="ref_builtin_string_for_string">string (when used with a string value)</a></li><li><a class="page-menu-link" href="#ref_builtin_trim" data-menu-target="ref_builtin_trim">trim</a></li><li><a class="page-menu-link" href="#ref_builtin_upper_case" data-menu-target="ref_builtin_upper_case">upper_case</a></li><li><a class="page-menu-link" href="#ref_builtin_word_list" data-menu-target="ref_builtin_word_list">word_list</a></li><li><a class="page-menu-link" href="#ref_builtin_xhtml" data-menu-target="ref_builtin_xhtml">xhtml</a></li><li><a class="page-menu-link" href="#ref_builtin_xml" data-menu-target="ref_builtin_xml">xml</a></li><li><a class="page-menu-link" href="#ref_builtin_string_flags" data-menu-target="ref_builtin_string_flags">Common flags</a></li></ul> </div>
<h2 class="content-header header-section2" id="ref_builtin_substring">substring</h2>
<div class="callout note">
<strong class="callout-label">Note:</strong>
<p>This built-in exists since FreeMarker 2.3.7.</p>
</div>
<p>Synopsis:
<code class="inline-code"><em class="code-color">exp</em>?substring(<em class="code-color">from</em>,
<em class="code-color">toExclusive</em>)</code>, also callable as
<code class="inline-code"><em class="code-color">exp</em>?substring(<em class="code-color">from</em>)</code></p>
<p>A substring of the string.
<code class="inline-code"><em class="code-color">from</em></code> is the index of
the first character. It must be a number that is at least 0 and less
than or equal with
<code class="inline-code"><em class="code-color">toExclusive</em></code>, or else
an error will abort the template processing. The
<code class="inline-code"><em class="code-color">toExclusive</em></code> is the
index of the character position after the last character of the
substring, or with other words, it is one greater than the index of
the last character. It must be a number that is at least 0 and less
than or equal to the length of the string, or else an error will
abort the template processing. If the
<code class="inline-code"><em class="code-color">toExclusive</em></code> is
omitted, then it defaults to the length of the string. If a
parameter is a number that is not an integer, only the integer part
of the number will be used.</p>
<p>Example:</p>
<div class="code-wrapper"><pre class="code-block code-template">- ${&#39;abc&#39;?substring(0)}
- ${&#39;abc&#39;?substring(1)}
- ${&#39;abc&#39;?substring(2)}
- ${&#39;abc&#39;?substring(3)}
- ${&#39;abc&#39;?substring(0, 0)}
- ${&#39;abc&#39;?substring(0, 1)}
- ${&#39;abc&#39;?substring(0, 2)}
- ${&#39;abc&#39;?substring(0, 3)}
- ${&#39;abc&#39;?substring(0, 1)}
- ${&#39;abc&#39;?substring(1, 2)}
- ${&#39;abc&#39;?substring(2, 3)}</pre></div>
<p>The output:</p>
<div class="code-wrapper"><pre class="code-block code-output">- abc
- bc
- c
-
-
- a
- ab
- abc
- a
- b
- c</pre></div>
<h2 class="content-header header-section2" id="ref_builtin_cap_first">cap_first</h2>
<p>The string with the very first word of the string capitalized.
For the precise meaning of ``word&#39;&#39; see the <a href="#ref_builtin_word_list">word_list built-in</a>.
Example:</p>
<div class="code-wrapper"><pre class="code-block code-template">${&quot; green mouse&quot;?cap_first}
${&quot;GreEN mouse&quot;?cap_first}
${&quot;- green mouse&quot;?cap_first}</pre></div>
<p>The output:</p>
<div class="code-wrapper"><pre class="code-block code-output"> Green mouse
GreEN mouse
- green mouse</pre></div>
<p>In the case of <code class="inline-code">&quot;- green mouse&quot;</code>, the first
word is the <code class="inline-code">-</code>.</p>
<h2 class="content-header header-section2" id="ref_builtin_uncap_first">uncap_first</h2>
<p>The opposite of <a href="#ref_builtin_cap_first"><code>cap_first</code></a>.
The string with the very first word of the string
un-capitalized.</p>
<h2 class="content-header header-section2" id="ref_builtin_capitalize">capitalize</h2>
<p>The string with all words capitalized. For the precise meaning
of ``word&#39;&#39; see the <a href="#ref_builtin_word_list">word_list
built-in</a>. Example:</p>
<div class="code-wrapper"><pre class="code-block code-template">${&quot; green mouse&quot;?capitalize}
${&quot;GreEN mouse&quot;?capitalize}</pre></div>
<p>The output:</p>
<div class="code-wrapper"><pre class="code-block code-output"> Green Mouse
Green Mouse</pre></div>
<h2 class="content-header header-section2" id="ref_builtin_chop_linebreak">chop_linebreak</h2>
<p>The string without the <a href="gloss.html#gloss.lineBreak">line-break</a> at its very end if there
was a line-break, otherwise the unchanged string.</p>
<h2 class="content-header header-section2" id="ref_builtin_string_date">date, time, datetime</h2>
<p>The string converted to a date value. It is recommended to
specify a parameter that specifies the format. For example:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#assign test1 = &quot;10/25/1995&quot;?date(&quot;MM/dd/yyyy&quot;)&gt;
&lt;#assign test2 = &quot;15:05:30&quot;?time(&quot;HH:mm:ss&quot;)&gt;
&lt;#assign test3 = &quot;1995-10-25 03:05 PM&quot;?datetime(&quot;yyyy-MM-dd hh:mm a&quot;)&gt;
${test1}
${test2}
${test3}</pre></div>
<p>will print something like (depends on the output locale
(language) and on other settings):</p>
<div class="code-wrapper"><pre class="code-block code-output">Oct 25, 1995
3:05:30 PM
Oct 25, 1995 3:05:00 PM</pre></div>
<p>Note that the dates was converted back to string according to
the <code class="inline-code">date_format</code>, <code class="inline-code">time_format</code>
and <code class="inline-code">datetime_format</code> <a href="ref_directive_setting.html#ref.directive.setting">settings</a> (for more
information about converting dates to strings read: <a href="ref_builtins_date.html#ref_builtin_string_for_date">string built-in for
dates</a>, <a href="dgui_template_valueinsertion.html#dgui_template_valueinserion_universal_date">date
interpolations</a>). It does not mater what format did you use
when you have converted the strings to dates.</p>
<p>You don&#39;t have to use the format parameter, if you know what
the default date/time/datetime format will be when the template is
processed:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#assign test1 = &quot;Oct 25, 1995&quot;?date&gt;
&lt;#assign test2 = &quot;3:05:30 PM&quot;?time&gt;
&lt;#assign test3 = &quot;Oct 25, 1995 03:05:00 PM&quot;?datetime&gt;
${test1}
${test2}
${test3}</pre></div>
<p>If the string is not in the appropriate format, an error will
abort template processing when you try to access this
built-in.</p>
<h2 class="content-header header-section2" id="ref_builtin_ends_with">ends_with</h2>
<p>Returns if this string ends with the specified substring. For
example <code class="inline-code">&quot;redhead&quot;?ends_with(&quot;head&quot;)</code> returns
boolean true. Also, <code class="inline-code">&quot;head&quot;?ends_with(&quot;head&quot;)</code> will
return true.</p>
<h2 class="content-header header-section2" id="ref_builtin_html">html</h2>
<p>The string as HTML markup. That is, the string with
all:</p>
<ul>
<li>
<code class="inline-code">&lt;</code> replaced with
<code class="inline-code">&amp;lt;</code>
</li>
<li>
<code class="inline-code">&gt;</code> replaced with
<code class="inline-code">&amp;gt;</code>
</li>
<li>
<code class="inline-code">&amp;</code> replaced with
<code class="inline-code">&amp;amp;</code>
</li>
<li>
<code class="inline-code">&quot;</code> replaced with
<code class="inline-code">&amp;quot;</code>
</li>
</ul>
<p>Note that if you want to insert an attribute value securely,
you must quote the attribute value in the HTML template with
quotation mark (with <code class="inline-code">&quot;</code>, not with
<code class="inline-code">&#39;</code>):</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;input type=text name=user value=<strong>&quot;</strong>${user?html}<strong>&quot;</strong>&gt;</pre></div>
<p>Note that in HTML pages usually you want to use this built-in
for all interpolations. So you can spare a lot of typing and lessen
the chances of accidental mistakes by using the <a href="ref_directive_escape.html"><code>escape</code>
directive</a>.</p>
<h2 class="content-header header-section2" id="ref_builtin_groups">groups</h2>
<p>This is used only with the result of the
<code class="inline-code">matches</code> built-in. See <a href="#ref_builtin_matches">there...</a></p>
<h2 class="content-header header-section2" id="ref_builtin_index_of">index_of</h2>
<p>Returns the index within this string of the first occurrence
of the specified substring. For example,
<code class="inline-code">&quot;abcabc&quot;?index_of(&quot;bc&quot;)</code> will return 1 (don&#39;t
forget that the index of the first character is 0). Also, you can
specify the index to start the search from:
<code class="inline-code">&quot;abcabc&quot;?index_of(&quot;bc&quot;, 2)</code> will return 4. There
is no restriction on the numerical value of the second parameter: if
it is negative, it has the same effect as if it were zero, and if it
is greater than the length of this string, it has the same effect as
if it were equal to the length of this string. Decimal values will
be truncated to integers.</p>
<p>If the 1st parameter does not occur as a substring in this
string (starting from the given index, if you use the second
parameter), then it returns -1.</p>
<h2 class="content-header header-section2" id="ref_builtin_j_string">j_string</h2>
<p>Escapes the string with the escaping rules of Java language
string literals, so it is safe to insert the value into a string
literal. In additional, all characters under <a href="gloss.html#gloss.UCS">UCS</a> code point 0x20, that has no
dedicated escape sequence in Java language, will be replaced with
UNICODE escape
(<code class="inline-code">\u<em class="code-color">XXXX</em></code>).</p>
<p>Example:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#assign beanName = &#39;The &quot;foo&quot; bean.&#39;&gt;
String BEAN_NAME = &quot;${beanName?j_string}&quot;;</pre></div>
<p>will output:</p>
<div class="code-wrapper"><pre class="code-block code-output">String BEAN_NAME = &quot;The \&quot;foo\&quot; bean.&quot;;</pre></div>
<h2 class="content-header header-section2" id="ref_builtin_js_string">js_string</h2>
<p>Escapes the string with the escaping rules of JavaScript
language string literals, so it is safe to insert the value into a
string literal. Both quotation mark (<code class="inline-code">&quot;</code>) and
apostrophe-quoate (<code class="inline-code">&#39;</code>) are escaped. Starting from
FreeMarker 2.3.1, it also escapes <code class="inline-code">&gt;</code> as
<code class="inline-code">\&gt;</code> (to avoid
<code class="inline-code">&lt;/script&gt;</code>). Furthermore, all characters
under <a href="gloss.html#gloss.UCS">UCS</a> code point 0x20, that has
no dedicated escape sequence in JavaScript language, will be
replaced with hexadecimal escape
(<code class="inline-code">\x<em class="code-color">XX</em></code>). (Of course,
according the JavaScript language string literal syntax, backslash
(<code class="inline-code">\</code>) will be escaped too, line-feed will be
escaped as <code class="inline-code">\n</code>, ...etc.)</p>
<p>Example:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#assign user = &quot;Big Joe&#39;s \&quot;right hand\&quot;&quot;&gt;
&lt;script&gt;
alert(&quot;Welcome ${user?js_string}!&quot;);
&lt;/script&gt;</pre></div>
<p>will output:</p>
<div class="code-wrapper"><pre class="code-block code-output">&lt;script&gt;
alert(&quot;Welcome Big Joe\&#39;s \&quot;right hand\&quot;!&quot;);
&lt;/script&gt;</pre></div>
<h2 class="content-header header-section2" id="ref_builtin_last_index_of">last_index_of</h2>
<p>Returns the index within this string of the last (rightmost)
occurrence of the specified substring. It returns the index of the
first (leftmost) character of the substring. For example:
<code class="inline-code">&quot;abcabc&quot;?last_index_of(&quot;ab&quot;)</code> will return 3. Also,
you can specify the index to start the search from. For example,
<code class="inline-code">&quot;abcabc&quot;?last_index_of(&quot;ab&quot;, 2)</code> will return 0.
Note that the second parameter indicates the maximum index of the
start of the substring. There is no restriction on the numerical
value of the second parameter: if it is negative, it has the same
effect as if it were zero, and if it is greater than the length of
this string, it has the same effect as if it were equal to the
length of this string. Decimal values will be truncated to
inegers.</p>
<p>If the 1st parameter does not occur as a substring in this
string (before the given index, if you use the second parameter),
then it returns -1.</p>
<h2 class="content-header header-section2" id="ref_builtin_length">length</h2>
<p>The number of characters in the string.</p>
<h2 class="content-header header-section2" id="ref_builtin_lower_case">lower_case</h2>
<p>The lower case version of the string. For example
<code class="inline-code">&quot;GrEeN MoUsE&quot;</code> will be <code class="inline-code">&quot;green
mouse&quot;</code>.</p>
<h2 class="content-header header-section2" id="ref_builtin_left_pad">left_pad</h2>
<div class="callout note">
<strong class="callout-label">Note:</strong>
<p>This built-in is available since FreeMarker 2.3.1. It
doesn&#39;t exist in 2.3.</p>
</div>
<p>If it&#39;s used with 1 parameter, then it inserts spaces on the
beginning of the string until it reaches the length that is
specified as the parameter. If the string is already as long or
longer than the specified length, then it does nothing. For example,
this:</p>
<div class="code-wrapper"><pre class="code-block code-template">[${&quot;&quot;?left_pad(5)}]
[${&quot;a&quot;?left_pad(5)}]
[${&quot;ab&quot;?left_pad(5)}]
[${&quot;abc&quot;?left_pad(5)}]
[${&quot;abcd&quot;?left_pad(5)}]
[${&quot;abcde&quot;?left_pad(5)}]
[${&quot;abcdef&quot;?left_pad(5)}]
[${&quot;abcdefg&quot;?left_pad(5)}]
[${&quot;abcdefgh&quot;?left_pad(5)}]</pre></div>
<p>will output this:</p>
<div class="code-wrapper"><pre class="code-block code-output">[ ]
[ a]
[ ab]
[ abc]
[ abcd]
[abcde]
[abcdef]
[abcdefg]
[abcdefgh]</pre></div>
<p>If it&#39;s used with 2 parameters, then the 1st parameter means
the same as if you were using the built-in with only 1 parameter,
and the second parameter specifies what to insert instead of space
characters. For example:</p>
<div class="code-wrapper"><pre class="code-block code-template">[${&quot;&quot;?left_pad(5, &quot;-&quot;)}]
[${&quot;a&quot;?left_pad(5, &quot;-&quot;)}]
[${&quot;ab&quot;?left_pad(5, &quot;-&quot;)}]
[${&quot;abc&quot;?left_pad(5, &quot;-&quot;)}]
[${&quot;abcd&quot;?left_pad(5, &quot;-&quot;)}]
[${&quot;abcde&quot;?left_pad(5, &quot;-&quot;)}]</pre></div>
<p>will output this:</p>
<div class="code-wrapper"><pre class="code-block code-output">[-----]
[----a]
[---ab]
[--abc]
[-abcd]
[abcde]</pre></div>
<p>The 2nd parameter can be a string whose length is greater than
1. Then the string will be inserted periodically, for
example:</p>
<div class="code-wrapper"><pre class="code-block code-template">[${&quot;&quot;?left_pad(8, &quot;.oO&quot;)}]
[${&quot;a&quot;?left_pad(8, &quot;.oO&quot;)}]
[${&quot;ab&quot;?left_pad(8, &quot;.oO&quot;)}]
[${&quot;abc&quot;?left_pad(8, &quot;.oO&quot;)}]
[${&quot;abcd&quot;?left_pad(8, &quot;.oO&quot;)}]</pre></div>
<p>will output this:</p>
<div class="code-wrapper"><pre class="code-block code-output">[.oO.oO.o]
[.oO.oO.a]
[.oO.oOab]
[.oO.oabc]
[.oO.abcd]</pre></div>
<p>The 2nd parameter must be a string value, and it must be at
least 1 character long.</p>
<h2 class="content-header header-section2" id="ref_builtin_right_pad">right_pad</h2>
<div class="callout note">
<strong class="callout-label">Note:</strong>
<p>This built-in is available since FreeMarker 2.3.1. It
doesn&#39;t exist in 2.3.</p>
</div>
<p>This is the same as <a href="#ref_builtin_left_pad"><code>left_pad</code></a>,
but it inserts the characters at the end of the string instead of
the beginning of the string.</p>
<p>Example:</p>
<div class="code-wrapper"><pre class="code-block code-template">[${&quot;&quot;?right_pad(5)}]
[${&quot;a&quot;?right_pad(5)}]
[${&quot;ab&quot;?right_pad(5)}]
[${&quot;abc&quot;?right_pad(5)}]
[${&quot;abcd&quot;?right_pad(5)}]
[${&quot;abcde&quot;?right_pad(5)}]
[${&quot;abcdef&quot;?right_pad(5)}]
[${&quot;abcdefg&quot;?right_pad(5)}]
[${&quot;abcdefgh&quot;?right_pad(5)}]
[${&quot;&quot;?right_pad(8, &quot;.oO&quot;)}]
[${&quot;a&quot;?right_pad(8, &quot;.oO&quot;)}]
[${&quot;ab&quot;?right_pad(8, &quot;.oO&quot;)}]
[${&quot;abc&quot;?right_pad(8, &quot;.oO&quot;)}]
[${&quot;abcd&quot;?right_pad(8, &quot;.oO&quot;)}]</pre></div>
<p>This will output this:</p>
<div class="code-wrapper"><pre class="code-block code-output">[ ]
[a ]
[ab ]
[abc ]
[abcd ]
[abcde]
[abcdef]
[abcdefg]
[abcdefgh]
[.oO.oO.o]
[aoO.oO.o]
[abO.oO.o]
[abc.oO.o]
[abcdoO.o]</pre></div>
<h2 class="content-header header-section2" id="ref_builtin_contains">contains</h2>
<div class="callout note">
<strong class="callout-label">Note:</strong>
<p>This built-in is available since FreeMarker 2.3.1. It
doesn&#39;t exist in 2.3.</p>
</div>
<p>Returns if the substring specified as the parameter to this
built-in occurrs in the string. For example:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#if &quot;piceous&quot;?contains(&quot;ice&quot;)&gt;It contains &quot;ice&quot;&lt;/#if&gt;</pre></div>
<p>This will output:</p>
<div class="code-wrapper"><pre class="code-block code-output">It contains &quot;ice&quot;</pre></div>
<h2 class="content-header header-section2" id="ref_builtin_matches">matches</h2>
<p>This is a ``power user&#39;&#39; built-in. Ignore it if you don&#39;t know
<a href="gloss.html#gloss.regularExpression">regular
expressions</a>.</p>
<div class="callout note">
<strong class="callout-label">Note:</strong>
<p>This built-in will work only if you use Java2 platform 1.4
or later. Otherwise it will stop template processing with
error.</p>
</div>
<p>This built-in determines if the string exactly matches the
pattern. Also, it returns the list of matching sub-strings. The
return value is a multi-type value:</p>
<ul>
<li>
<p>Boolean: <code class="inline-code">true</code>, if it the string exactly
matches the pattern, otherwise <code class="inline-code">false</code>. For
example, <code class="inline-code">&quot;fooo&quot;?matches(&#39;fo*&#39;)</code> is
<code class="inline-code">true</code>, but
<code class="inline-code">&quot;fooo bar&quot;?matches(&#39;fo*&#39;)</code> is
<code class="inline-code">false</code>.</p>
</li>
<li>
<p>Sequence: the list of matched substrings of the string.
Possibly a 0 length sequence.</p>
</li>
</ul>
<p>For example:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#if &quot;fxo&quot;?matches(&quot;f.?o&quot;)&gt;Matches.&lt;#else&gt;Does not match.&lt;/#if&gt;
&lt;#assign res = &quot;foo bar fyo&quot;?matches(&quot;f.?o&quot;)&gt;
&lt;#if res&gt;Matches.&lt;#else&gt;Does not match.&lt;/#if&gt;
Matching sub-strings:
&lt;#list res as m&gt;
- ${m}
&lt;/#list&gt;</pre></div>
<p>will print:</p>
<div class="code-wrapper"><pre class="code-block code-output">Matches.
Does not match.
Matching sub-strings:
- foo
- fyo</pre></div>
<p>If the regular expression contains groups (parentheses), then
you can access them with the <code class="inline-code">groups</code>
built-in:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#assign res = &quot;aa/rx; ab/r;&quot;?matches(&quot;(\\w[^/]+)/([^;]+);&quot;)&gt;
&lt;#list res as m&gt;
- ${m} is ${m?groups[1]} per ${m?groups[2]}
&lt;/#list&gt;</pre></div>
<p>This will print:</p>
<div class="code-wrapper"><pre class="code-block code-output">- aa/rx; is aa per rx
- ab/r; is ab per r</pre></div>
<p><code class="inline-code">matches</code> accepts an optional 2nd parameter,
the <a href="#ref_builtin_string_flags">flags</a>. Note that
it does not support flag <code class="inline-code">r</code>, because it always
uses regular expressions.</p>
<h2 class="content-header header-section2" id="ref_builtin_number">number</h2>
<p>The string converted to numerical value. The number must be in
the same format as you specify numerical values directly in FTL.
That is, it must be in the locale independent form, where the
decimal separator is dot. In additional the built-in recognizes
scientific notation (e.g. <code class="inline-code">&quot;1.23E6&quot;</code>,
<code class="inline-code">&quot;1.5e-8&quot;</code>).</p>
<p>If the string is not in the appropriate format, an error will
abort template processing when you try to access this
built-in.</p>
<p>Known problem: If you use earlier Java2 platform than v1.3,
the built-ins will not recognize + prefix and scientific
notation.</p>
<h2 class="content-header header-section2" id="ref_builtin_replace">replace</h2>
<p>It is used to replace all occurrences of a string in the
original string with another string. It does not deal with word
boundaries. For example:</p>
<div class="code-wrapper"><pre class="code-block code-template">${&quot;this is a car acarus&quot;?replace(&quot;car&quot;, &quot;bulldozer&quot;)}</pre></div>
<p>will print:</p>
<div class="code-wrapper"><pre class="code-block code-output">this is a bulldozer abulldozerus</pre></div>
<p>The replacing occurs in left-to-right order. This means that
this:</p>
<div class="code-wrapper"><pre class="code-block code-template">${&quot;aaaaa&quot;?replace(&quot;aaa&quot;, &quot;X&quot;)}</pre></div>
<p>will print:</p>
<div class="code-wrapper"><pre class="code-block code-output">Xaa</pre></div>
<p>If the 1st parameter is an empty string, then all occurrences
of the empty string will be replaced, like
<code class="inline-code">&quot;foo&quot;?replace(&quot;&quot;,&quot;|&quot;)</code> will evaluate to
<code class="inline-code">&quot;|f|o|o|&quot;</code>.</p>
<p><code class="inline-code">replace</code> accepts an optional <a href="#ref_builtin_string_flags">flags parameter</a>, as its
3rd parameter.</p>
<h2 class="content-header header-section2" id="ref_builtin_rtf">rtf</h2>
<p>The string as Rich text (RTF text). That is, the string with
all:</p>
<ul>
<li>
<p><code class="inline-code">\</code> replaced with
<code class="inline-code">\\</code></p>
</li>
<li>
<p><code class="inline-code">{</code> replaced with
<code class="inline-code">\{</code></p>
</li>
<li>
<p><code class="inline-code">}</code> replaced with
<code class="inline-code">\}</code></p>
</li>
</ul>
<h2 class="content-header header-section2" id="ref_builtin_url">url</h2>
<div class="callout note">
<strong class="callout-label">Note:</strong>
<p>This built-in is available since FreeMarker 2.3.1. It
doesn&#39;t exist in 2.3.</p>
</div>
<p>The string after URL escaping. This means that all
non-US-ASCII and reserved URL characters will be escaped with
<code class="inline-code">%<em class="code-color">XX</em></code>. For
example:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#assign x = &#39;a/b c&#39;&gt;
${x?url}</pre></div>
<p>The output will be (assuming that the charset used for the
escaping is an US-ASCII compatible charset):</p>
<div class="code-wrapper"><pre class="code-block code-output">a%2Fb%20c</pre></div>
<p>Note that it escapes <em>all</em> reserved URL
characters (<code class="inline-code">/</code>, <code class="inline-code">=</code>,
<code class="inline-code">&amp;</code>, ...etc), so this encoding can be used for
encoding query parameter values, for example:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;a href=&quot;foo.cgi?x=${x?url}&amp;y=${y?url}&quot;&gt;Click here...&lt;/a&gt;</pre></div>
<div class="callout note">
<strong class="callout-label">Note:</strong>
<p>Above no HTML encoding (<code class="inline-code">?htm</code>) was needed,
because URL escaping escapes all reserved HTML characters anyway.
But watch: always quote the attribute value, and always with
normal quotation mark (<code class="inline-code">&quot;</code>), never with
apostrophe quotation mark (<code class="inline-code">&#39;</code>), because
apostrophe quotation mark is not escaped by the URL
escaping.</p>
</div>
<p>To do URL escaping a <a href="gloss.html#gloss.charset">charset</a> must be chosen that will be
used for calculating the escaped parts
(<code class="inline-code">%<em class="code-color">XX</em></code>). If you are HTML
page author and you don&#39;t really understand this, don&#39;t worry: the
programmers should configure FreeMarker so that it uses the proper
charset by default (<span class="marked-for-programmers">programmers: see
more below...</span>). If you are a more technical minded user,
then you may want to know that the charset used is specified by the
<code class="inline-code">url_escaping_charset</code> setting, that can be set in
template execution time (or, preferably, earlier by the
programmers). For example:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#--
This will use the charset specified by the programmers
before the template execution has started.
--&gt;
&lt;a href=&quot;foo.cgi?x=${x?url}&quot;&gt;foo&lt;/a&gt;
&lt;#-- Use UTF-8 charset for URL escaping from now: --&gt;
<strong>&lt;#setting url_escaping_charset=&quot;UTF-8&quot;&gt;</strong>
&lt;#-- This will surely use UTF-8 charset --&gt;
&lt;a href=&quot;bar.cgi?x=${x?url}&quot;&gt;bar&lt;/a&gt;</pre></div>
<p>Furthermore, you can explicitly specify a charset for a single
URL escaping as the parameter to the built-in:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;a href=&quot;foo.cgi?x=${x?url<strong>(&#39;ISO-8895-2&#39;)</strong>}&quot;&gt;foo&lt;/a&gt;</pre></div>
<p><span class="marked-for-programmers">If the <code class="inline-code">url</code> built-in has no
parameter, then it will use the charset specified as the value of
the <code class="inline-code">url_escaping_charset</code> setting. This setting
should be set by the software that encloses FreeMarker (e.g. a Web
application framework), because it is not set
(<code class="inline-code">null</code>) by default. If it is not set, then
FreeMarker falls back using the value of the
<code class="inline-code">output_encoding</code> setting, which is also not set by
default, so it is again the task of the enclosing software. If the
<code class="inline-code">output_encoding</code> setting is not set either, then
the parameterless <code class="inline-code">url</code> built-in can&#39;t be executed,
and it will cause execution time error. Of course, the
<code class="inline-code">url</code> built-in with parameter always
works.</span></p>
<p><span class="marked-for-programmers">It&#39;s possible to set
<code class="inline-code">url_escaping_charset</code> in the template with the
<code class="inline-code">setting</code> directive, but it is bad practice, at
least in true MVC applications. The
<code class="inline-code">output_encoding</code> setting can&#39;t be set with the
<code class="inline-code">setting</code> directive, so that&#39;s surely the task of
the enclosing software. You may find more information regarding this
<a href="pgui_misc_charset.html">here...</a></span></p>
<h2 class="content-header header-section2" id="ref_builtin_split">split</h2>
<p>It is used to split a string into a sequence of strings along
the occurrences of another string. For example:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#list &quot;someMOOtestMOOtext&quot;?split(&quot;MOO&quot;) as x&gt;
- ${x}
&lt;/#list&gt;</pre></div>
<p>will print:</p>
<div class="code-wrapper"><pre class="code-block code-output">- some
- test
- text</pre></div>
<p>Note that it is assumed that all occurrences of the separator
is before a new item, thus:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#list &quot;some,,test,text,&quot;?split(&quot;,&quot;) as x&gt;
- &quot;${x}&quot;
&lt;/#list&gt;</pre></div>
<p>will print:</p>
<div class="code-wrapper"><pre class="code-block code-output">- &quot;some&quot;
- &quot;&quot;
- &quot;test&quot;
- &quot;text&quot;
- &quot;&quot;</pre></div>
<p><code class="inline-code">split</code> accepts an optional <a href="#ref_builtin_string_flags">flags parameter</a>, as its
2nd parameter.</p>
<h2 class="content-header header-section2" id="ref_builtin_starts_with">starts_with</h2>
<p>Returns if this string starts with the specified substring.
For example <code class="inline-code">&quot;redhead&quot;?starts_with(&quot;red&quot;)</code> returns
boolean true. Also, <code class="inline-code">&quot;red&quot;?starts_with(&quot;red&quot;)</code> will
return true.</p>
<h2 class="content-header header-section2" id="ref_builtin_string_for_string">string (when used with a string value)</h2>
<p>Does nothing, just returns the string as-is. The exception is
that if the value is a multi-type value (e.g. it is both string and
sequence at the same time), then the resulting value will be only a
simple string, not a multi-type value. This can be utilized to
prevent the artifacts of multi-typing.</p>
<h2 class="content-header header-section2" id="ref_builtin_trim">trim</h2>
<p>The string without leading and trailing white-space.
Example:</p>
<div class="code-wrapper"><pre class="code-block code-template">(${&quot; green mouse &quot;?trim})</pre></div>
<p>The output:</p>
<div class="code-wrapper"><pre class="code-block code-output">(green mouse)</pre></div>
<h2 class="content-header header-section2" id="ref_builtin_upper_case">upper_case</h2>
<p>The upper case version of the string. For example
<code class="inline-code">&quot;GrEeN MoUsE&quot;</code> will be <code class="inline-code">&quot;GREEN
MOUSE&quot;</code>.</p>
<h2 class="content-header header-section2" id="ref_builtin_word_list">word_list</h2>
<p>A sequence that contains all words of the string in the order
as they appear in the string. Words are continual character
sequences that contain any character but <a href="gloss.html#gloss.whiteSpace">white-space</a>. Example:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#assign words = &quot; a bcd, . 1-2-3&quot;?word_list&gt;
&lt;#list words as word&gt;[${word}]&lt;/#list&gt;</pre></div>
<p>will output:</p>
<div class="code-wrapper"><pre class="code-block code-output">[a][bcd,][.][1-2-3]</pre></div>
<h2 class="content-header header-section2" id="ref_builtin_xhtml">xhtml</h2>
<p>The string as XHTML text. That is, the string with all:</p>
<ul>
<li>
<code class="inline-code">&lt;</code> replaced with
<code class="inline-code">&amp;lt;</code>
</li>
<li>
<code class="inline-code">&gt;</code> replaced with
<code class="inline-code">&amp;gt;</code>
</li>
<li>
<code class="inline-code">&amp;</code> replaced with
<code class="inline-code">&amp;amp;</code>
</li>
<li>
<code class="inline-code">&quot;</code> replaced with
<code class="inline-code">&amp;quot;</code>
</li>
<li>
<code class="inline-code">&#39;</code> replaced with
<code class="inline-code">&amp;#39;</code>
</li>
</ul>
<p>The only difference between this built-in and the
<code class="inline-code">xml</code> built-in is that the <code class="inline-code">xhtml</code>
built-in escapes <code class="inline-code">&#39;</code> as
<code class="inline-code">&amp;#39;</code> instead of as
<code class="inline-code">&amp;apos;</code>, because some older browsers don&#39;t
interpret <code class="inline-code">&amp;apos;</code> correctly.</p>
<h2 class="content-header header-section2" id="ref_builtin_xml">xml</h2>
<p>The string as XML text. That is, the string with all:</p>
<ul>
<li>
<code class="inline-code">&lt;</code> replaced with
<code class="inline-code">&amp;lt;</code>
</li>
<li>
<code class="inline-code">&gt;</code> replaced with
<code class="inline-code">&amp;gt;</code>
</li>
<li>
<code class="inline-code">&amp;</code> replaced with
<code class="inline-code">&amp;amp;</code>
</li>
<li>
<code class="inline-code">&quot;</code> replaced with
<code class="inline-code">&amp;quot;</code>
</li>
<li>
<code class="inline-code">&#39;</code> replaced with
<code class="inline-code">&amp;apos;</code>
</li>
</ul>
<h2 class="content-header header-section2" id="ref_builtin_string_flags">Common flags</h2>
<p>Many string built-ins accept an optional string parameter, the
so called ``flags&#39;&#39;. In this string, each letter influences a
certain aspect of the behavior of the built-in. For example, letter
<code class="inline-code">i</code> means that the built-in should not
differentiate the lower and upper-case variation of the same letter.
The order of the letters in the flags string is not
significant.</p>
<p>This is the complete list of letters (flags):</p>
<ul>
<li>
<p><code class="inline-code">i</code>: Case insensitive: do not
differentiate the lower and upper-case variation of the same
letter.</p>
</li>
<li>
<p><code class="inline-code">f</code>: First only. That is,
replace/find/etc. only the first occurrence of something.</p>
</li>
<li>
<p> <code class="inline-code">r</code>: The substring to find is a
<a href="gloss.html#gloss.regularExpression">regular
expression</a>. FreeMarker uses the variation of regular
expressions described at <a href="http://java.sun.com/j2se/1.4.1/docs/api/java/util/regex/Pattern.html">http://java.sun.com/j2se/1.4.1/docs/api/java/util/regex/Pattern.html</a>.
<em>This flag will work only if you use Java2 platform 1.4
or later. Otherwise it will cause template processing to stop
with error.</em></p>
</li>
<li>
<p><code class="inline-code">m</code>: Multi-line mode for regular
expressions. In multi-line mode the expressions
<code class="inline-code">^</code> and <code class="inline-code">$</code> match just after
or just before, respectively, a line terminator or the end of
the string. By default these expressions only match at the
beginning and the end of the entire string.</p>
</li>
<li>
<p><code class="inline-code">s</code>: Enables dotall mode for regular
expressions (same as Perl singe-line mode). In dotall mode, the
expression <code class="inline-code">.</code> matches any character, including
a line terminator. By default this expression does not match
line terminators.</p>
</li>
<li>
<p><code class="inline-code">c</code>: Permits whitespace and comments in
regular expressions.</p>
</li>
</ul>
<p>Example:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#assign s = &#39;foo bAr baar&#39;&gt;
${s?replace(&#39;ba&#39;, &#39;XY&#39;)}
i: ${s?replace(&#39;ba&#39;, &#39;XY&#39;, &#39;i&#39;)}
if: ${s?replace(&#39;ba&#39;, &#39;XY&#39;, &#39;if&#39;)}
r: ${s?replace(&#39;ba*&#39;, &#39;XY&#39;, &#39;r&#39;)}
ri: ${s?replace(&#39;ba*&#39;, &#39;XY&#39;, &#39;ri&#39;)}
rif: ${s?replace(&#39;ba*&#39;, &#39;XY&#39;, &#39;rif&#39;)}</pre></div>
<p>This outputs this:</p>
<div class="code-wrapper"><pre class="code-block code-output">foo bAr XYar
i: foo XYr XYar
if: foo XYr baar
r: foo XYAr XYr
ri: foo XYr XYr
rif: foo XYr baar</pre></div>
<p>This is the table of built-ins that use these common flags,
and which supports which flags:</p>
<div class="table-responsive">
<table class="table">
<thead>
<tr>
<th>Built-in</th>
<th><code class="inline-code">i</code></th>
<th><code class="inline-code">r</code></th>
<th><code class="inline-code">m</code></th>
<th><code class="inline-code">s</code></th>
<th><code class="inline-code">c</code></th>
<th><code class="inline-code">f</code></th>
</tr>
</thead>
<tbody>
<tr>
<td><code class="inline-code">replace</code></td>
<td>Yes</td>
<td>Yes</td>
<td>Only with <code class="inline-code">r</code></td>
<td>Only with <code class="inline-code">r</code></td>
<td>Only with <code class="inline-code">r</code></td>
<td>Yes</td>
</tr>
<tr>
<td><code class="inline-code">split</code></td>
<td>Yes</td>
<td>Yes</td>
<td>Only with <code class="inline-code">r</code></td>
<td>Only with <code class="inline-code">r</code></td>
<td>Only with <code class="inline-code">r</code></td>
<td>No</td>
</tr>
<tr>
<td><code class="inline-code">match</code></td>
<td>Yes</td>
<td>No</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes</td>
<td>No</td>
</tr>
</tbody>
</table>
</div>
<div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="ref_builtins.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_builtins_number.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><div class="col-right"><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="2020-07-09T23:48:39Z" title="Thursday, July 9, 2020 11:48:39 PM GMT">2020-07-09 23:48:39 GMT</time> </p>
<p class="copyright">
© <span itemprop="copyrightYear">1999</span>–2020
<a itemtype="http://schema.org/Organization" itemprop="copyrightHolder" href="https://apache.org/">The Apache Software Foundation</a> </p>
</div></div></div></body>
</html>