freeMarker模板语言参考：内建函数参考⑤序列内建函数

序列内建函数

• chunk
• first
• join
• last
• reverse
• seq_contains
• seq_index_of
• seq_last_index_of
• size
• sort
• sort_by

1.chunk
该内建函数将序列分隔为多个序列，长度为第一个参数给定的值 (比如 mySeq?chunk(3))。结果是包含这些序列的一个序列。 最后一个序列可能比给定的长度要小，除非第二个参数也给定了 (比如 比如 mySeq?chunk(3, ‘-’))， 这就是用来填充最后一个序列，以达到给定的长度。

<#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>

注：该内建函数通常在输出的序列中使用表格/柱状的格式。 当被用于HTML表格时，第二个参数通常是"\xA0" (也就是不换行的空格代码，也就是我们所知的"nbsp")， 所以空TD的边界就不会不丢失。
第一个参数必须是一个数字，而且至少是1。如果这个数字不是整数， 那么它会被静默地去掉小数部分(也就是说3.1和3.9都会被规整为3)。 第二个参数可以是任意类型的值

2.first
序列的第一个子变量。如果序列为空，那么模板处理将会中止

<#assign seq=[1,2,3,4,5,6,7]>
${seq?first}
<#--  1  -->

3.join
使用给定的分隔符来连接序列中的项为一个独立的字符串

<#assign colors = ["red", "green", "blue"]>
${colors?join(", ")}
<#--  red, green, blue  -->

序列中不是字符串的项会被转换为字符串，使用 ${…} 相同的转换规则 (当然这里不会应用自动转义)。

?join(…) 最多可以有3个参数：

• 分隔符，是必须的:插入到每一项中间的字符串

• 空值，默认是 “” (空字符串)： 如果序列为空，使用该值。

• 列表结尾，默认是 “” (空字符串): 如果列表序列不为空，该值在最后一个值后面输出

<#assign colors = ["red", "green", "blue"]>

${colors?join(", ", "-")}
<#--  red, green, blue   -->
<br>
${[]?join(", ", "-")}
<#--  -  -->
<br>
${colors?join(", ", "-", ".")}
<#--  red, green, blue.   -->
<br>
${[]?join(", ", "-", ".")}
<#--  -  -->

4.last
序列的最后一个子变量。如果序列为空，那么模板处理将会中止。

<#assign seq=[1,2,3,4,5,6,7]>
${seq?first}
<#--  1  -->
${seq?last}
<#--  7  -->

5.reverse
序列的反序形式。

<#assign seq=[1,2,3,4,5,6,7]>
<#list seq?reverse as s>
${s}
</#list>

6.seq_contains
辨别序列中是否包含指定值。它包含一个参数，就是来查找的值
（seq_ 前缀在该内建函数名字中是需要的， 用来和 contains 内建函数 区分开。contains 用来在字符串中查找子串 (因为变量可以同时当作字符串和序列)）

<#assign x = ["red", 16, "blue", "cyan"]>
"blue": ${x?seq_contains("blue")?string("yes", "no")}
<#--  "blue": yes  -->
"green": ${x?seq_contains("green")?string("yes", "no")}
<#--  "green": no  -->
16: ${x?seq_contains(16)?string("yes", "no")}
<#--  16: yes  -->
"16": ${x?seq_contains("16")?string("yes", "no")}
<#--  "16": no  -->

为了查找值，该内建函数使用了 FreeMarker 的比较规则 (就像使用 == 操作符)，除了比较两个不同类型的值，或 FreeMarker 不支持的类型来比较， 其他都不会引起错误，只是会评估两个值不相等。因此，你可以使用它来查找标量值 (也就是字符串，数字，布尔值，或日期/时间类型)。 对于其他类型结果通常都是 false。

对于容错性，该内建函数还对 collection 起作用

7.seq_index_of
seq_ 前缀在该内建函数名字中是需要的， 用来和 index_of 内建函数 区分开。index_of 用来在字符串中查找子串 (因为变量可以同时当作字符串和序列)。

返回序列中第一次出现该值时的索引位置， 如果序列不包含指定的值时返回 -1。 要查找的值作为第一个参数

<#assign colors = ["red", "green", "blue"]>
${colors?seq_index_of("blue")}
<#--  2  -->
${colors?seq_index_of("red")}
<#--  0  -->
${colors?seq_index_of("purple")}
<#--  -1  -->

搜索开始的索引值可以由第二个可选参数来确定。 如果在同一个序列中相同的项可以多次出现时，这是很有用的。 第二个参数的数值没有什么限制：如果它是负数，那么就和它是零的效果一样， 而如果它是比序列长度还大的数，那么就和它是序列长度值的效果一样。 小数值会被切成整数

<#assign names = ["Joe", "Fred", "Joe", "Susan"]>
No 2nd param: ${names?seq_index_of("Joe")}
-2: ${names?seq_index_of("Joe", -2)}
<#--  No 2nd param: 0 -2: 0这说明负数和零一样从序列开头查找  -->
-1: ${names?seq_index_of("Joe", -1)}
<#--  -1: 0  -->
0: ${names?seq_index_of("Joe", 0)}
<#--  0: 0  -->

1: ${names?seq_index_of("Joe", 1)}
<#--  1: 2从数组下标是1 的开始搜索  -->
2: ${names?seq_index_of("Joe", 2)}
<#--  2: 2  -->

3: ${names?seq_index_of("Joe", 3)}
<#--  3: -1当数组下标超过查找的位置的时候，返回值为-1  -->
4: ${names?seq_index_of("Joe", 4)}
<#--  4: -1  -->

8.seq_last_index_of
seq_ 前缀在该内建函数名字中是需要的， 用来和 last_index_of 内建函数 区分开。last_index_of 用来在字符串中查找子串 (因为变量可以同时当作字符串和序列)。

返回序列中最后一次出现值的索引位置， 如果序列不包含指定的值时返回 -1。
也就是说，和 seq_index_of 相同， 只是在序列中从最后一项开始向前搜索。
它也支持可选的第二个参数来确定从哪里开始搜索的索引位置

<#assign names = ["Joe", "Fred", "Joe", "Susan"]>
No 2nd param: ${names?seq_last_index_of("Joe")}
<#--  No 2nd param: 2  -->
-2: ${names?seq_last_index_of("Joe", -2)}
<#--  -2: -1  -->
-1: ${names?seq_last_index_of("Joe", -1)}
<#--  -1: -1  负数返回值是-1 -->

0: ${names?seq_last_index_of("Joe", 0)}
<#--  0: 0  -->
1: ${names?seq_last_index_of("Joe", 1)}
<#--  1: 0  到数组下标为1的位置为止，最后一次出现joe的位置-->

2: ${names?seq_last_index_of("Joe", 2)}
<#--  2: 2  -->
3: ${names?seq_last_index_of("Joe", 3)}
<#--  3: 2  -->
4: ${names?seq_last_index_of("Joe", 4)}
<#--  4: 2 截止到数组下标位置为4的地方，从后开始的出现joe的位置  -->

9.size
序列中子变量的数量(作为数字值)。假设序列中至少有一个子变量，
那么序列 s 中最大的索引是 s?size - 1 (因为第一个子变量的序列是0)。

<#assign names = ["Joe", "Fred", "Joe", "Susan"]>
序列中子变量的数量(作为数字值):${names?size}
<br>
序列 names 中最大的索引是 序列名?size - 1=>${names?size-1}

10.sort
以升序方式返回序列。
(要使用降序排列时，使用它之后使用 reverse 内建函数。) 这仅在子变量都是字符串时有效，或者子变量都是数字，或者子变量都是日期值 (日期，时间，或日期+时间)，或者所有子变量都是布尔值时(从2.3.17版本开始)。
如果子变量是字符串，它使用本地化(语言)的具体单词排序(通常是大小写不敏感的)

升序
<#assign ls = ["whale", "Barbara", "zeppelin", "aardvark", "beetroot"]?sort>
<#list ls as i>${i} </#list>

<#--  升序的翻转--降序  -->
<#assign ls = ["whale", "Barbara", "zeppelin", "aardvark", "beetroot"]?sort?reverse>
<#list ls as i>${i} </#list>

11.sort_by
返回由给定的哈希表子变量来升序排序的哈希表序列。
(要降序排列使用该内建函数后还要使用 reverse 内建函数。) 这个规则和 sort 内建函数 是一样的， 除了序列中的子变量必须是哈希表类型，而且你不得不给哈希变量的命名， 那会用来决定排序顺序

<#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>

<#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 weight:
<#list ls?sort_by("weight") as i>
- ${i.name}: ${i.weight}
</#list>

sort_by降序

<#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")?reverse as i>
- ${i.name}: ${i.weight}
<br>
</#list>

<#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 weight:
<#list ls?sort_by("weight")?reverse as i>
- ${i.name}: ${i.weight}
<br>
</#list>

如果你用来排序的子变量的层次很深 (也就是说，它是子变量的子变量的子变量，以此类推)， 那么你可以使用序列来作为参数，它指定了子变量的名字， 来向下引导所需的子变量

<#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>