| <!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 sequences - 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 sequences"> |
| <meta property="og:locale" content="en_US"> |
| <meta property="og:url" content="http://example.com/ref_builtins_sequence.html"> |
| <link rel="canonical" href="http://example.com/ref_builtins_sequence.html"> |
| <link rel="icon" href="favicon.png" type="image/png"> |
| <link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css?1594338517553"> |
| </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_sequence.html"><span itemprop="name">Built-ins for sequences</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></ul></div></div></div> <div class="main-content site-width"> |
| <div class="content-wrapper no-toc"> |
| <div id="table-of-contents-wrapper" class="col-left"> |
| </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_boolean.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_builtins_hash.html"><span>Next</span></a></div><div class="title-wrapper"> |
| <h1 class="content-header header-section1" id="ref_builtins_sequence" itemprop="headline">Built-ins for sequences</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_first" data-menu-target="ref_builtin_first">first</a></li><li><a class="page-menu-link" href="#ref_builtin_last" data-menu-target="ref_builtin_last">last</a></li><li><a class="page-menu-link" href="#ref_builtin_seq_contains" data-menu-target="ref_builtin_seq_contains">seq_contains</a></li><li><a class="page-menu-link" href="#ref_builtin_seq_index_of" data-menu-target="ref_builtin_seq_index_of">seq_index_of</a></li><li><a class="page-menu-link" href="#ref_builtin_seq_last_index_of" data-menu-target="ref_builtin_seq_last_index_of">seq_last_index_of</a></li><li><a class="page-menu-link" href="#ref_builtin_reverse" data-menu-target="ref_builtin_reverse">reverse</a></li><li><a class="page-menu-link" href="#ref_builtin_size" data-menu-target="ref_builtin_size">size</a></li><li><a class="page-menu-link" href="#ref_builtin_sort" data-menu-target="ref_builtin_sort">sort</a></li><li><a class="page-menu-link" href="#ref_builtin_sort_by" data-menu-target="ref_builtin_sort_by">sort_by</a></li><li><a class="page-menu-link" href="#ref_builtin_chunk" data-menu-target="ref_builtin_chunk">chunk</a></li></ul> </div> |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_first">first</h2> |
| |
| |
| |
| |
| <p>The first subvariable of the sequence. Template processing |
| will die with error if the sequence is empty.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_last">last</h2> |
| |
| |
| |
| |
| <p>The last subvariable of the sequence. Template processing will |
| die with error if the sequence is empty.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_seq_contains">seq_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't exist in 2.3.</p> |
| </div> |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>The <code class="inline-code">seq_</code> prefix is required in the |
| built-in name to differentiate it from the <a href="ref_builtins_string.html#ref_builtin_contains"><code>contains</code> |
| built-in</a> that searches a substring in a string (since a |
| variable can be both string and sequence on the same time).</p> |
| </div> |
| |
| |
| <p>Tells if the sequence contains the specified value. It has 1 |
| parameter, the value to find. Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign x = ["red", 16, "blue", "cyan"]> |
| "blue": ${x?seq_contains("blue")?string("yes", "no")} |
| "yellow": ${x?seq_contains("yellow")?string("yes", "no")} |
| 16: ${x?seq_contains(16)?string("yes", "no")} |
| "16": ${x?seq_contains("16")?string("yes", "no")}</pre></div> |
| |
| <p>The output will be:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">"blue": yes |
| "yellow": no |
| 16: yes |
| "16": no</pre></div> |
| |
| <p>To find the value the built-in uses FreeMarker's comparison |
| rules (as if you was using <a href="dgui_template_exp.html#dgui_template_exp_comparison"><code>==</code> |
| operator</a>), except that comparing two values of different |
| types or of types for which FreeMarker doesn't support comparison |
| will not cause error, just will be evaluated as the two values are |
| not equal. Thus, you can use it only to find scalar values (i.e. |
| string, number, boolean or date/time values). For other types the |
| result will be always <code class="inline-code">false</code>.</p> |
| |
| <p>For fault tolerance, this built-in also works with |
| collections.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_seq_index_of">seq_index_of</h2> |
| |
| |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This built-in is available since FreeMarker 2.3.1. It |
| doesn't exist in 2.3.</p> |
| </div> |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>The <code class="inline-code">seq_</code> prefix is required in the |
| built-in name to differentiate it from the <a href="ref_builtins_string.html#ref_builtin_index_of"><code>index_of</code> |
| built-in</a> that searches a substring in a string (since a |
| variable can be both string and sequence on the same time).</p> |
| </div> |
| |
| |
| <p>Returns the index of the first occurrence of a value in the |
| sequence, or <code class="inline-code">-1</code> if the sequence doesn't contain |
| the specified value. The value to find is specified as the first |
| parameter. For example this template:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign colors = ["red", "green", "blue"]> |
| ${colors?seq_index_of("blue")} |
| ${colors?seq_index_of("red")} |
| ${colors?seq_index_of("purple")}</pre></div> |
| |
| <p>will output this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">2 |
| 0 |
| -1</pre></div> |
| |
| <p>To find the value the built-in uses FreeMarker's comparison |
| rules (as if you was using <a href="dgui_template_exp.html#dgui_template_exp_comparison"><code>==</code> |
| operator</a>), except that comparing two values of different |
| types or of types for which FreeMarker doesn't support comparison |
| will not cause error, just will be evaluated as the two values are |
| not equal. Thus, you can use it only to find scalar values (i.e. |
| string, number, boolean or date/time values). For other types the |
| result will be always <code class="inline-code">-1</code>.</p> |
| |
| <p>The index where the searching is started can be optionally |
| given as the 2nd parameter. This may be useful if the same item can |
| occur for multiple times in the same sequence. 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 the sequence, it has the same effect as |
| if it were equal to the length of the sequence. Decimal values will |
| be truncated to integers. For example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign names = ["Joe", "Fred", "Joe", "Susan"]> |
| No 2nd param: ${names?seq_index_of("Joe")} |
| -2: ${names?seq_index_of("Joe", -2)} |
| -1: ${names?seq_index_of("Joe", -1)} |
| 0: ${names?seq_index_of("Joe", 0)} |
| 1: ${names?seq_index_of("Joe", 1)} |
| 2: ${names?seq_index_of("Joe", 2)} |
| 3: ${names?seq_index_of("Joe", 3)} |
| 4: ${names?seq_index_of("Joe", 4)}</pre></div> |
| |
| <p>will output this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">No 2nd param: 0 |
| -2: 0 |
| -1: 0 |
| 0: 0 |
| 1: 2 |
| 2: 2 |
| 3: -1 |
| 4: -1</pre></div> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_seq_last_index_of">seq_last_index_of</h2> |
| |
| |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This built-in is available since FreeMarker 2.3.1. It |
| doesn't exist in 2.3.</p> |
| </div> |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>The <code class="inline-code">seq_</code> prefix is required in the |
| built-in name to differentiate it from the <a href="ref_builtins_string.html#ref_builtin_last_index_of"><code>last_index_of</code> |
| built-in</a> that searches a substring in a string (since a |
| variable can be both string and sequence on the same time).</p> |
| </div> |
| |
| |
| <p>Returns the index of the last occurrence of a value in the |
| sequence, or <code class="inline-code">-1</code> if the sequence doesn't contain |
| the specified value. That is, it is the same as <a href="#ref_builtin_seq_index_of"><code>seq_index_of</code></a>, |
| just it searches backward starting from the last item of the |
| sequence. It also supports the optional 2nd parameter that specifies |
| the index where the searching is started. For example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign names = ["Joe", "Fred", "Joe", "Susan"]> |
| No 2nd param: ${names?seq_last_index_of("Joe")} |
| -2: ${names?seq_last_index_of("Joe", -2)} |
| -1: ${names?seq_last_index_of("Joe", -1)} |
| 0: ${names?seq_last_index_of("Joe", 0)} |
| 1: ${names?seq_last_index_of("Joe", 1)} |
| 2: ${names?seq_last_index_of("Joe", 2)} |
| 3: ${names?seq_last_index_of("Joe", 3)} |
| 4: ${names?seq_last_index_of("Joe", 4)}</pre></div> |
| |
| <p>will output this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">No 2nd param: 2 |
| -2: -1 |
| -1: -1 |
| 0: 0 |
| 1: 0 |
| 2: 2 |
| 3: 2 |
| 4: 2</pre></div> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_reverse">reverse</h2> |
| |
| |
| |
| |
| <p>The sequence with reversed order.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_size">size</h2> |
| |
| |
| |
| |
| <p>The number of subvariables in sequence (as a numerical value). |
| The highest possible index in sequence <code class="inline-code">s</code> is |
| <code class="inline-code">s?size - 1</code> (since the index of the first |
| subvariable is 0) assuming that the sequence has at least one |
| subvariable.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_sort">sort</h2> |
| |
| |
| |
| |
| |
| |
| <p>Returns the sequence sorted in ascending order. This will work |
| only if all subvariables are strings, or if all subvariables are |
| numbers, or, since FreeMarker 2.3.1, if all subvariables are date |
| values (date, time, or date+time). If the subvariables are strings, |
| it uses locale (language) specific lexical sorting (which is usually |
| not case sensitive). For example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign ls = ["whale", "Barbara", "zeppelin", "aardvark", "beetroot"]?sort> |
| <#list ls as i>${i} </#list></pre></div> |
| |
| <p>will print (with US locale at least):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">aardvark Barbara beetroot whale zeppelin</pre></div> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_sort_by">sort_by</h2> |
| |
| |
| |
| |
| |
| |
| <p>Returns the sequence of hashes sorted by the given hash |
| subvariable in ascending order. The rules are the same as with the |
| <code class="inline-code">sort</code> built-in, except that the subvariables of |
| the sequence must be hashes, and you have to give the name of a hash |
| subvariable that will decide the order. For example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign ls = [ |
| {"name":"whale", "weight":2000}, |
| {"name":"Barbara", "weight":53}, |
| {"name":"zeppelin", "weight":-200}, |
| {"name":"aardvark", "weight":30}, |
| {"name":"beetroot", "weight":0.3} |
| ]> |
| Order by name: |
| <#list ls?sort_by("name") as i> |
| - ${i.name}: ${i.weight} |
| </#list> |
| |
| Order by weight: |
| <#list ls?sort_by("weight") as i> |
| - ${i.name}: ${i.weight} |
| </#list></pre></div> |
| |
| <p>will print (with US locale at least):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">Order by name: |
| - aardvark: 30 |
| - Barbara: 53 |
| - beetroot: 0.3 |
| - whale: 2000 |
| - zeppelin: -200 |
| |
| Order by weight: |
| - zeppelin: -200 |
| - beetroot: 0.3 |
| - aardvark: 30 |
| - Barbara: 53 |
| - whale: 2000</pre></div> |
| |
| <p>Since FreeMarker 2.3.1, if the subvariable that you want to |
| use for the sorting is on a deeper level (that is, if it is a |
| subvariable of a subvariable and so on), then you can use a sequence |
| as parameter, that specifies the names of the subvariables that lead |
| down to the desired subvariable. For example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign members = [ |
| {"name": {"first": "Joe", "last": "Smith"}, "age": 40}, |
| {"name": {"first": "Fred", "last": "Crooger"}, "age": 35}, |
| {"name": {"first": "Amanda", "last": "Fox"}, "age": 25}]> |
| Sorted by name.last: |
| <#list members?sort_by(['name', 'last']) as m> |
| - ${m.name.last}, ${m.name.first}: ${m.age} years old |
| </#list></pre></div> |
| |
| <p>will print (with US locale at least):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">Sorted by name.last: |
| - Crooger, Fred: 35 years old |
| - Fox, Amanda: 25 years old |
| - Smith, Joe: 40 years old</pre></div> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_chunk">chunk</h2> |
| |
| |
| |
| |
| |
| |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This built-in exists since FreeMarker 2.3.3.</p> |
| </div> |
| |
| |
| <p>This built-in splits a sequence into multiple sequences of the |
| size given with the 1st parameter to the built-in (like |
| <code class="inline-code">mySeq?chunk(3)</code>). The result is the sequence of |
| these sequences. The last sequence is possibly shorter than the |
| given size, unless the 2nd parameter is given (like |
| <code class="inline-code">mySeq?chunk(3, '-')</code>), that is the item used to |
| make up the size of the last sequence to the given size. |
| Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign seq = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j']> |
| |
| <#list seq?chunk(4) as row> |
| <#list row as cell>${cell} </#list> |
| </#list> |
| |
| <#list seq?chunk(4, '-') as row> |
| <#list row as cell>${cell} </#list> |
| </#list></pre></div> |
| |
| <p>The output will be:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> |
| a b c d |
| e f g h |
| i j |
| |
| a b c d |
| e f g h |
| i j - - |
| </pre></div> |
| |
| <p>This built in is mostly for outputting sequnces in |
| tabular/columnar format. When used with HTML tables, the 2nd |
| parameter is often <code class="inline-code">"\xA0"</code> (that is the code of |
| the no-break space character, also known as ``nbsp''), so the border |
| of the empty TD-s will not be missing.</p> |
| |
| <p>The 1st parameter must be a number that is at least 1. If the |
| number is not integer, it will be silently rounded down to integer |
| (i.e. both 3.1 and 3.9 will be rounded to 3). The 2nd parameter can |
| be of any type and value.</p> |
| <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="ref_builtins_boolean.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_builtins_hash.html"><span>Next</span></a></div></div></div></div> </div> |
| </div> |
| <div class="site-footer"><div class="site-width"><div class="footer-bottom"> <p class="last-generated"> |
| Last generated: |
| <time itemprop="dateModified" datetime="2020-07-09T23:48:37Z" title="Thursday, July 9, 2020 11:48:37 PM GMT">2020-07-09 23:48:37 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> |
