FreeMarker学习（内建函数参考）

内容参考：http://freemarker.foofun.cn/dgui_quickstart_basics.html

一、字符串内建函数

boolean：

　　字符串转为布尔值。字符串必须是 true 或 false (大小写敏感！)。

cap_first：

　　字符串中的首单词的首字母大写。

capitalize：

　　字符串中所有单词的首字母大写。

chop_linebreak：

　　在末尾没有换行符的字符串， 那么可以换行，否则不改变字符串。

contains：

　　如果函数中的参数指定的子串出现在源字符串中， 那么返回true。

date, time, datetime：

　　字符串转换成日期值，时间或日期-时间值。需要一个由 date_format， time_format 和 datetime_format 设置指定的格式。 如果字符串不是适当的格式，那么当访问该内建函数时， 就会发生错误中止模板的处理。

ends_with：

　　是否以某个字符串结尾，返回布尔值。

ensure_ends_with：

　　如果字符串没有以第一个参数指定的子串结尾， 那么就会将它加到字符串后面，否则返回原字符串。比如， "foo"?ensure_ends_with("/") 和 "foo/"?ensure_ends_with("/") 返回 "foo/"。

ensure_starts_with：

　　如果字符串没有以第一个参数指定的子串开头， 那么就会将它加到字符串开头，否则返回原字符串。比如， "foo"?ensure_starts_with("/") 和 "/foo"?ensure_starts_with("/") 返回 "/foo"。

groups：

　　这个函数只作用于内建函数 matches 的结果。

html：字符串按照HTML标记输出。

index_of：

　　返回第一次字符串中出现子串时的索引位置。

j_string：

　　根据Java语言字符串转义规则来转义字符串， 所以它很安全的将值插入到字符串类型中。要注意它 不会 在被插入的值的两侧添加引号； 你需要在字符串值 内部 来使用。　

<#assign beanName = 'The "foo" bean.'>
String BEAN_NAME = "${beanName?j_string}";   --  String BEAN_NAME = "The \"foo\" bean."; 

js_string：

　　根据JavaScript语言字符串转义规则来转义字符串， 所以它很安全的将值插入到字符串类型中。

json_string：

　　根据JSON语言的字符串规则来转义字符串， 所以在字符串中插入值是安全的。 要注意它 不会 在被插入的值两侧添加引号； 你需要在字符串值 内部 来使用。

keep_after：

　　移除字符串中的一部分内容，该部分是给定子串第一次出现之前的部分，保留移除后的部分。

keep_after_last：

　　和 keep_after 相同， 但是它会保留参数最后一次出现后的部分，而不是第一次。

keep_before：

　　移除字符串的一部分，该部分是从给定子串开始的部分。

keep_before_last：

　　和 keep_before 相同， 但是保留参数最后一次出现之前的部分，而不是第一次出现之前。

last_index_of：

　　返回最后一次(最右边)字符串中出现子串时的索引位置。

left_pad：

　　如果它仅仅用1个参数，那么它将在字符串的开始插入空白， 直到整个串的长度达到参数指定的值。 如果字符串的长度达到指定数值或者比指定的长度还长， 那么就什么都不做了。如果用两个参数，则用第二个参数当作空白符进行填充。

length：

　　字符串中字符的数量。

lower_case：

　　字符串的小写形式。比如 "GrEeN MoUsE"?lower_case 将会是 "green mouse"。

matches：

　　字符串是否精确匹配模式，会返回匹配子串的列表。 返回值是多类型值；布尔值：如果字符串整体匹配了模式，就是 true， 否则就是 false。序列：字符串匹配的子串的列表。很有可能是长度为0的序列

number：

　　字符串转化为数字格式。识别科学记数法(比如 "1.23E6"，"1.5e-8") 。

replace：

　　在源字符串中，用另外一个字符串来替换原字符串中出现它的部分

right_pad：

　　它和 left_pad 相同， 但是它从末尾开始插入字符而不是从开头。如果用两个参数，则用第二个参数当作空白符进行填充。

remove_beginning：

　　从字符串的开头移除参数中的子串，如果它不以参数中的子串开头， 那么就或者返回原字符串。

remove_ending：

　　从字符串的结尾移除参数中的子串，如果它不以参数中的子串结尾， 那么就或者返回原字符串。

rtf：

　　字符串作为富文本(RTF 文本)，也就是说，下列字符串：(\ 替换为 \\)、({替换为\{)、(}替换为\})

split：

　　切割字符串。

starts_with：

　　判断字符串是否以指定字符串开头。

string：

　　当被用作是字符串值时什么也不做，仅仅返回和其内容一致的字符串。例外的是， 如果值是一个多类型的值(比如同时有字符串和序列两种)， 那么结果就只是一个简单的字符串，而不是多类型的值。 这可以被用来防止人为多输入

substring：

　　截取字符串，已废弃，使用字符串切分进行截取，如：str[from..<toExclusive]。

trim：

　　去掉字符串首尾的空格。

uncap_first：

　　和 cap_first 相反。 字符串中所有单词的首字母小写。

upper_case：

　　字符串全部转大写。

url：

　　在URL之后的字符串进行转义，支持添加字符集参数。这意味着， 所有非US-ASCII的字符和保留的URL字符将会被 %XX 形式转义。

url_path：

　　它和 url 内建函数 相同，只是它不转义斜杠 (/)字符。

word_list：

　　以空白字符切割字符串，返回值是一个序列，顺序为出现在字符串中的顺序。 单词是不间断的字符序列，包含了任意字符，但是没有空白。

xhtml：

　　字符串作为XHTML格式文本。

xml：

　　字符串作为XML格式文本。

通用标志：

　　多字符串内建函数接受可选的字符串参数， 它们被称为"标志"。在这个字符串中，每个字母影响内建函数一个特定方面的行为。 比如，字母 i 说明内建函数不应该区别相同字母的小写和大写变化。 标志字符串中的字母顺序是不重要的。

• i：大小写敏感： 不区别相同字母的小写和大写变化。
• f：只是第一个。也就是说， 替换/查找/等...，只是第一个出现的地方。
• r：查找的子串是 正则表达式。 FreeMarker 使用的正则表达式变量可以在 http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html 中找到(请注意，一些模式规则特性的出现基于所使用的Java版本)。
• m：正则表达式的多行模式。在多行正则表达式 ^ 和 $ 仅仅匹配之后或之前， 各自匹配行终止符或字符串结尾。默认情况下，这些表达式仅仅匹配完整字符串的开头和结尾。 请注意，^ 和 $ 不匹配换行符字符本身。
• s：开启正则表达式的dot-all模式 (和Perl的单行模式相同)。在dot-all模式下，表达式 . 匹配任意字符串，包含行终止符。 默认情况下，该表达式不匹配行终止符。
• c： 允许正则表达式中的空白和注释。

　　　　下表是支持使用这些通用标志的内建函数：

内建函数	i (忽略大小写)	r (正则表达式)	m (多行模式)	s (dot-all模式)	c (空白和注释)	f (仅第一个)
replace	是	是	仅 r	仅 r	仅 r	是
split	是	是	仅 r	仅 r	仅 r	否
matches	是	忽略	是	是	是	否
keep_after	是	是	是	是	是	忽略
keep_after_last	是	是	是	是	是	忽略
keep_before	是	是	是	是	是	忽略
keep_before_last	是	是	是	是	是	忽略
ensure_starts_with	是	忽略	是	是	是	忽略

二、数字内建函数

abs：

　　给出数字的绝对值。比如 x?abs ，如果 x 是 -5，会得到5。

c：

　　将将 "计算机语言" 的数字转换成字符串，也对布尔值起作用。

is_infinite：

　　辨别数字是否是无限浮点数，结果是 true 或 false。

is_nan：

　　辨别数字是否是浮点数NaN，结果是 true 或 false。

lower_abc：

　　将 1， 2， 3，等...，转换为字符串 "a"， "b"， "c"，等... 当到达 "z"时，那么会继续转换成如 "aa"， "ab"等。
round：

　　返回最近的整数，四舍五入。

floor：

　　返回小于该值的最大整数。

ceiling：

　　返回大于该值的最小整数。

string：

　　当用作是数字类型时，将一个数字转换成字符串。它使用程序员通过 number_format 和 locale 设置的默认格式。也可以明确地用这个内建函数再指定一个数字格式。

　　有四种预定义的数字格式：computer， currency，number 和 percent。这些格式的明确含义是本地化(国家)指定的， 受Java平台安装环境所控制，而不是FreeMarker，除了 computer，用作和 c 内建函数是相同的格式。可以这样来使用预定义的格式：

<#assign x=42>
${x}
${x?string}  <#-- the same as ${x} -->
${x?string.number}
${x?string.currency}
${x?string.percent}
${x?string.computer}

　　如果你本地是US English，将会输出：

42
42
42
$42.00
4,200%
42

　　前三个表达式的输出是相同的，因为前两个表达式是默认格式， 这里是"数字"。可以使用一个设置来改变默认设置：

<#setting number_format="currency">
<#assign x=42>
${x}
${x?string}  <#-- the same as ${x} -->
${x?string.number}
${x?string.currency}
${x?string.percent}

　　输出

$42.00
$42.00
42
$42.00
4,200%

　　因为默认的数字格式被设置成了"货币"。

　　除了这三种预定义格式，还可以使用 Java 数字格式语法 中的任意数字格式：

<#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"]}

　　输出

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

　　请注意，在 FreeMarker 中，foo.bar 和 foo["bar"] 是相同的，也可以将 x?string.currency 写为 x?string["currency"]，当然实际中不这么用。 但是在上述示例中，我们不得不使用方括号语法，因为在语法上， 使用的字符(数字，点，#)不允许在点操作符之后。

　　由于历史原因，也可以编写如下代码 x?string("0.#")，它和 x?string["0.#"] 完全相同。

　　在金融和统计学实践中，四舍五入都是根据所谓的一半原则， 这就意味着对最近的"邻居"进行四舍五入，除非离两个邻居距离相等， 这种情况下，它四舍五入到偶数的邻居。如果你注意看1.5和2.5的四舍五入的话， 这在上面的示例中是可以看到的，两个都被四舍五入到2，因为2是偶数，但1和3是奇数。

　　正如之前展示的预定义格式，数字的默认格式可以在模板中设置：

<#setting number_format="0.##">
${1.234}   -- 1.23

　　请注意，数字格式是本地化敏感的，本地化设置在格式化中起作用：

<#setting number_format=",##0.00">
<#setting locale="en_US">
US people write:     ${12345678}
<#setting locale="hu">
German people write: ${12345678}

　　输出

US people write:     12,345,678.00
German people write: 12.345.678,00

upper_abc：

　　和 lower_abc 相同， 但是它转换成大写字母，比如 "A"， "B"， "C"，… ， "AA"， "AB"， 等...

三、日期内建函数

date, time, datetime：

　　当用于日期/时间/日期-时间值时，这些内建函数用来指定日期变量中的哪些部分被使用：

• date：仅日期部分，没有一天当中的时间部分。
• time：仅一天当中的时间部分，没有日期部分。
• datetime：日期和时间都在

　　可以用来将日期-时间值转换成日期或时间，如果 ? 左边是字符串，那么这些内建函数 将字符串转换成日期/时间/日期时间。

string

　　当用于日期/时间/日期-时间值时，这个内建函数以指定的格式转换日期类型到字符串类型。

四、布尔值内建函数

c：

　　当用于布尔值时，该内建函数将布尔值转换为字符串，针对 "计算机语言" 而不是用户。

string：

　　当用于布尔值时，该内建函数的所有用法已经废弃。将布尔值转换为字符串。可以两种方式来使用：

• foo?string("yes", "no")： 从 FreeMarker 2.3.23 版本开始废弃：使用 ?then("yes", "no") 来替代。
• foo?string： 从 FreeMarker 2.3.20 版本开始废弃：使用 ?c 来代替，或者设置 boolean_format 设置项，比如像 "yes,no"，之后转换会自动发生。

then：

　　根据true或者false返回不同的表现形式，如“yes”或“no”，“0”或“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>

　　输出

  a b c d
  e f g h
  i j 

  a b c d
  e f g h
  i j - - 

first：

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

join：

　　使用给定的分隔符来连接序列中的项为一个独立的字符串。最多可以有3个参数：分隔符、空值、列表结尾。

last：

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

reverse：

　　序列的反序形式。

seq_contains：

　　序列中是否包含某个值，返回布尔值。

seq_index_of：

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

seq_last_index_of：

　　返回序列中最后一次出现值的索引位置， 如果序列不包含指定的值时返回 -1。也就是说，和 seq_index_of 相同， 只是在序列中从最后一项开始向前搜索。

size：

　　序列的长度。

sort：

　　以升序方式返回序列。

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

Order by weight:
<#list ls?sort_by("weight") as i>
- ${i.name}: ${i.weight}
</#list>

　　输出

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

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

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

　　输出

Sorted by name.last:
- Crooger, Fred: 35 years old
- Fox, Amanda: 25 years old
- Smith, Joe: 40 years old

六、哈希表内建函数

keys：

　　返回哈希表键的序列。

values：

　　返回哈希表值得序列。

七、循环变量内建函数

这些内建函数只能用于list 和 items 指令 的循环变量 (也可以用于已经废弃的 foreach 指令)。

counter：

　　返回当前迭代(由循环变量名称识别)从1开始的索引。

has_next：

　　辨别循环项是否是当前迭代(由循环变量名称识别)的最后一项。

index：

　　返回当前迭代(由循环变量名称识别)从0开始的索引。

is_even_item：

　　辨别循环项是否是当前迭代(由循环变量名称识别)间隔1的奇数项。

is_first：

　　辨别循环项是否是当前迭代(由循环变量名称识别)的第一项。

is_last：

　　辨别循环项是否是当前迭代(由循环变量名称识别)的最后一项。

is_odd_item：

　　辨别循环项是否是当前迭代(由循环变量名称识别)间隔1的偶数项。

item_cycle：

　　这是 item_parity 内建函数 更为通用的版本，这里可以指定何值来代替 "odd" 和 "even"。 它也允许多余两个值来循环。

item_parity：

　　基于当前迭代(由循环变量名称识别)间隔为1的索引的奇偶性， 返回字符串值 "odd" 或 "even"。 这通常用于表格中行间的颜色变换：

八、其他内建函数

switch：

　　功能与Java的switch一样，matchedValue?switch(case1, result1, case2, result2, ... caseN, resultN, defaultResult)，这里的 defaultResult 可以被忽略。switch 会找到第一个 case 和参数 (从左到右)值 matchedValue 相等， 之后返回直接在 case 参数后的 result 参数的值， 如果它没有找到一个相等的 case，那么就返回 defaultResult 的值，如果没有 defaultResult 参数 (换言之，参数的个数是基数)，那么就发生错误中止模板处理。

eval：

　　求一个作为FTL表达式的字符串的值。比如 "1+2"?eval返回数字3。

has_content：

　　如果变量(不是Java的 null) 存在而且不是"空"就返回 true，否则返回 false。"空”"含义靠具体的情形来决定。 它是直观的常识性概念。下面这些都是空：长度为0的字符串， 没有子变量的序列或哈希表，一个已经超过最后一项元素的集合。 如果值不是字符串，序列，哈希表或集合，如果它是数字，日期或布尔值 (比如 0 和 false 是非空的)， 那么它被认为是非空的，否则就是空的。注意当你的数据模型实现了多个模板模型接口， 你可能会得到不是预期的结果。然而，当你有疑问时你通常可以使用 expr!?size > 0 或 expr!?length > 0 来代替 expr?has_content。