Built-ins for strings

Page Contents

These built-ins act on a string left-value. However, if the left-value is number or date/time/date-time or boolean (since 2.3.20), it will automatically converted to string according the current number-, date/time/date-time- and boolean-format settings (which are the same formatters that are applied when inserting such values with ${...}).

boolean

The string converted to boolean value. The string must be true or false (case sensitive!), or must be in the format specified by the boolean_format setting.

If the string is not in the appropriate format, an error will abort template processing when you try to access this built-in.

cap_first

The string with the very first word of the string capitalized. For the precise meaning of ``word'' see the word_list built-in. Example:

${"  green mouse"?cap_first}
${"GreEN mouse"?cap_first}
${"- green mouse"?cap_first}  

The output:

  Green mouse
GreEN mouse
- green mouse  

In the case of "- green mouse", the first word is the -.

capitalize

The string with all words capitalized. For the precise meaning of ``word'' see the word_list built-in. Example:

${"  green  mouse"?capitalize}
${"GreEN mouse"?capitalize}  

The output:

  Green Mouse
Green Mouse  

chop_linebreak

The string without the line-break at its very end if there was a line-break, otherwise the unchanged string.

contains

Note

This built-in is available since FreeMarker 2.3.1. It doesn't exist in 2.3.

Returns if the substring specified as the parameter to this built-in occurrs in the string. For example:

<#if "piceous"?contains("ice")>It contains "ice"</#if>  

This will output:

It contains "ice"  

date, time, datetime

The string value converted to a date, time, or date-time value. It will expect the format specified by the date_format, time_format and datetime_format settings. If the string is not in the appropriate format, an error will abort template processing when you try to access this built-in.

<#-- The date_format, time_format and datetime_format settings must match this format! -->
<#assign someDate = "Oct 25, 1995"?date>
<#assign someTime = "3:05:30 PM"?time>
<#assign someDatetime = "Oct 25, 1995 03:05:00 PM"?datetime>

<#-- Changing the setting value changes the expected format: -->
<#setting datetime_format="iso">
<#assign someDatetime = "1995-10-25T15:05"?datetime>  

You can also specify the format explicitly like ?datetime.format or ?datetime["format"] (or ?datetime("format") for historical reasons), and the same with ?date and ?time. For the syntax and meaning of format values see the possible values of the date_format, time_format and datetime_format settings. Example:

<#-- Parsing XML Schema xs:date, xs:time and xs:dateTime values: -->
<#assign someDate = "1995-10-25"?date.xs>
<#assign someTime = "15:05:30"?time.xs>
<#assign someDatetime = "1995-10-25T15:05:00"?datetime.xs>

<#-- Parsing ISO 8601 (both extended and basic formats): -->
<#assign someDatetime = "1995-10-25T15:05"?datetime.iso>
<#assign someDatetime = "19951025T1505"?datetime.iso>

<#-- Parsing with SimpleDateFormat patterns: -->
<#assign someDate = "10/25/1995"?date("MM/dd/yyyy")>
<#assign someTime = "15:05:30"?time("HH:mm:ss")>
<#assign someDatetime = "1995-10-25 03:05 PM"?datetime("yyyy-MM-dd hh:mm a")>  

To prevent misunderstandings, the left-hand value need not be a string literal. For example, when you read data from XML DOM (from where all values come as unparsed strings), you may do things like order.confirmDate?date.xs to convert the string value to a real date.

Of course, the format also can be a variable, like in "..."?datetime[myFormat].

ends_with

Returns whether this string ends with the substring specified in the parameter. For example "ahead"?ends_with("head") returns boolean true. Also, "head"?ends_with("head") will return true.

ensure_ends_with

Note

This built-in is available since FreeMarker 2.3.21.

If the string doesn't end with the substring specified as the 1st parameter, it adds it after the string, otherwise it returns the original string. For example, both "foo"?ensure_ends_with("/") and "foo/"?ensure_ends_with("/") returns "foo/".

ensure_starts_with

Note

This built-in is available since FreeMarker 2.3.21.

If the string doesn't start with the substring specified as the 1st parameter, it adds it before the string, otherwise it returns the original string. For example, both "foo"?ensure_starts_with("/") and "/foo"?ensure_starts_with("/") returns "/foo".

If you specify two parameters, then the 1st parameter is interpreted as a Java regular expression, and if it doesn't match the beginning of the string, then the string specified as the 2nd parameter is added before the string. For example someURL?ensure_starts_with("[a-zA-Z]+://", "http://") will check if the string starts with something that matches "[a-zA-Z]+://" (note that no ^ is needed), and if it doesn't, it prepends "http://".

This method also accepts a 3rd flags parameter. As calling with 2 parameters implies "r" there (i.e., regular expression mode), you rarely need this. One notable case is when you don't want the 1st parameter to be interpreted as a regular expression, only as plain text, but you want the comparison to be case-insensitive, in which case you would use "i" as the 3rd parameter.

groups

This is used only with the result of the matches built-in. See there...

html

The string as HTML markup. That is, the string with all:

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 ", not with '):

<input type=text name=user value="${user?html}" 

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 escape directive.

index_of

Returns the index within this string of the first occurrence of the specified substring. For example, "abcabc"?index_of("bc") will return 1 (don't forget that the index of the first character is 0). Also, you can specify the index to start the search from: "abcabc"?index_of("bc", 2) 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.

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.

j_string

Escapes the string with the escaping rules of Java language string literals, so it's safe to insert the value into a string literal. Note that it will not add quotation marks around the inserted value; you meant to use this inside the string literal.

All characters under UCS code point 0x20 will be escaped. When they have no dedicated escape sequence in the Java language (like \n, \t, etc.), they will be replaced with a UNICODE escape (\uXXXX).

Example:

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

will output:

String BEAN_NAME = "The \"foo\" bean.";  

js_string

Escapes the string with the escaping rules of JavaScript language string literals, so it's safe to insert the value into a string literal. Note that it will not add quotation marks around the inserted value; you meant to use this inside the string literal.

Both quotation mark (") and apostrophe-quoate (') are escaped. Starting from FreeMarker 2.3.1, it also escapes > as \> (to avoid </script>).

All characters under UCS code point 0x20 will be escaped. When they have no dedicated escape sequence in JavaScript (like \n, \t, etc.), they will be replaced with a UNICODE escape (\uXXXX).

Example:

<#assign user = "Big Joe's \"right hand\"">
<script>
  alert("Welcome ${user?js_string}!");
</script>  

will output:

<script>
  alert("Welcome Big Joe\'s \"right hand\"!");
</script>  

json_string

Escapes the string with the escaping rules of JSON language string literals, so it's safe to insert the value into a string literal. Note that it will not add quotation marks around the inserted value; you meant to use this inside the string literal.

This will not escape ' characters, since JSON strings must be quoted with ". It will, however escape the / (slash) characters as \/ where they occur directly after a <, to avoid </script> and such. It will also escape the > characters as \u003E where they occur directly after ]], to avoid exiting an XML CDATA section.

All characters under UCS code point 0x20 will be escaped. When they have no dedicated escape sequence in JSON (like \n, \t, etc.), they will be replaced with a UNICODE escape (\uXXXX).

keep_after

Note

This built-in is available since FreeMarker 2.3.21.

Removes the part of the string that is not after the first occurrence of the given substring. For example:

${"abcdefgh"?keep_after("de")}  

will print

fgh  

If the parameter string is not found, it will return an empty string. If the parameter string is a 0-length string, it will return the original string unchanged.

This method accepts an optional flags parameter, as its 2nd parameter:

${"foo : bar"?keep_after(r"\s*:\s*", "r")}  

will print

bar  

keep_before

Note

This built-in is available since FreeMarker 2.3.21.

Removes the part of the string that starts with the given substring. For example:

${"abcdef"?keep_before("de")}  

will print

abc  

If the parameter string is not found, it will return the original string unchanged. If the parameter string is a 0-length string, it will return an empty string.

This method accepts an optional flags parameter, as its 2nd parameter:

${"foo : bar"?keep_before(r"\s*:\s*", "r")}  

will print

foo  

last_index_of

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: "abcabc"?last_index_of("ab") will return 3. Also, you can specify the index to start the search from. For example, "abcabc"?last_index_of("ab", 2) 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.

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.

left_pad

Note

This built-in is available since FreeMarker 2.3.1.

If it'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:

[${""?left_pad(5)}]
[${"a"?left_pad(5)}]
[${"ab"?left_pad(5)}]
[${"abc"?left_pad(5)}]
[${"abcd"?left_pad(5)}]
[${"abcde"?left_pad(5)}]
[${"abcdef"?left_pad(5)}]
[${"abcdefg"?left_pad(5)}]
[${"abcdefgh"?left_pad(5)}]  

will output this:

[     ]
[    a]
[   ab]
[  abc]
[ abcd]
[abcde]
[abcdef]
[abcdefg]
[abcdefgh]  

If it'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:

[${""?left_pad(5, "-")}]
[${"a"?left_pad(5, "-")}]
[${"ab"?left_pad(5, "-")}]
[${"abc"?left_pad(5, "-")}]
[${"abcd"?left_pad(5, "-")}]
[${"abcde"?left_pad(5, "-")}]  

will output this:

[-----]
[----a]
[---ab]
[--abc]
[-abcd]
[abcde]  

The 2nd parameter can be a string whose length is greater than 1. Then the string will be inserted periodically, for example:

[${""?left_pad(8, ".oO")}]
[${"a"?left_pad(8, ".oO")}]
[${"ab"?left_pad(8, ".oO")}]
[${"abc"?left_pad(8, ".oO")}]
[${"abcd"?left_pad(8, ".oO")}]  

will output this:

[.oO.oO.o]
[.oO.oO.a]
[.oO.oOab]
[.oO.oabc]
[.oO.abcd]  

The 2nd parameter must be a string value, and it must be at least 1 character long.

length

The number of characters in the string.

lower_case

The lower case version of the string. For example "GrEeN MoUsE"?lower_case will be "green mouse".

matches

This is a ``power user'' built-in. Ignore it if you don't know regular expressions.

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:

For example:

<#if "fxo"?matches("f.?o")>Matches.<#else>Does not match.</#if>

<#assign res = "foo bar fyo"?matches("f.?o")>
<#if res>Matches.<#else>Does not match.</#if>
Matching sub-strings:
<#list res as m>
- ${m}
</#list>  

will print:

Matches.

Does not match.
Matching sub-strings:
- foo
- fyo  

If the regular expression contains groups (parentheses), then you can access them with the groups built-in:

<#-- Entire input match -->
<#assign res = "John Doe"?matches(r"(\w+) (\w+)")>
<#if res> <#-- Must not try to access groups if there was no match! -->
  First name: ${res?groups[1]}
  Second name: ${res?groups[2]}
</#if>

<#-- Subtring matches -->
<#assign res = "aa/rx; ab/r;"?matches("(.+?)/*(.+?);")>
<#list res as m>
  - "${m}" is "${m?groups[1]}" per "${m?groups[2]}"
</#list>  

This will print:

  First name: John
  Second name: Doe

  - "aa/rx;" is "a" per "a/rx"
  - " ab/r;" is " " per "ab/r"  

Note above that groups has worked both with substring matches and with the result of entire string matching.

matches accepts an optional 2nd parameter, the flags. Note that it doesn't support flag f, and ignores the r flag.

number

The string converted to numerical value. The number must be in "computer language" format. That is, it must be in the locale independent form, where the decimal separator is dot, and there's no grouping.

This built-in recognizes numbers in the format that the FreeMarker template language uses. In additionally, it recognizes scientific notation (e.g. "1.23E6", "1.5e-8"). Since FreeMarker 2.3.21, it also recognizes all XML Schema number formats, like NaN, INF, -INF, plus the Java-native formats Infinity and -Infinity.

If the string is not in the appropriate format, an error will abort template processing when you try to access this built-in.

In fact, the string is parsed by the toNumber method of the current arithmetic_engine, which is configuration setting. However, that method should behave similarly as described above.

replace

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:

${"this is a car acarus"?replace("car", "bulldozer")}  

will print:

this is a bulldozer abulldozerus  

The replacing occurs in left-to-right order. This means that this:

${"aaaaa"?replace("aaa", "X")}  

will print:

Xaa  

If the 1st parameter is an empty string, then all occurrences of the empty string will be replaced, like "foo"?replace("","|") will evaluate to "|f|o|o|".

replace accepts an optional flags parameter, as its 3rd parameter.

right_pad

Note

This built-in is available since FreeMarker 2.3.1. It doesn't exist in 2.3.

This is the same as left_pad, but it inserts the characters at the end of the string instead of the beginning of the string.

Example:

[${""?right_pad(5)}]
[${"a"?right_pad(5)}]
[${"ab"?right_pad(5)}]
[${"abc"?right_pad(5)}]
[${"abcd"?right_pad(5)}]
[${"abcde"?right_pad(5)}]
[${"abcdef"?right_pad(5)}]
[${"abcdefg"?right_pad(5)}]
[${"abcdefgh"?right_pad(5)}]

[${""?right_pad(8, ".oO")}]
[${"a"?right_pad(8, ".oO")}]
[${"ab"?right_pad(8, ".oO")}]
[${"abc"?right_pad(8, ".oO")}]
[${"abcd"?right_pad(8, ".oO")}]  

This will output this:

[     ]
[a    ]
[ab   ]
[abc  ]
[abcd ]
[abcde]
[abcdef]
[abcdefg]
[abcdefgh]

[.oO.oO.o]
[aoO.oO.o]
[abO.oO.o]
[abc.oO.o]
[abcdoO.o]  

remove_beginning

Note

This built-in is available since FreeMarker 2.3.21.

Removes the parameter substring from the beginning of the string, or returns the original string if it doesn't start with the parameter substring. For example:

${"abcdef"?remove_beginning("abc")}
${"foobar"?remove_beginning("abc")}  

will print:

def
foobar  

remove_ending

Note

This built-in is available since FreeMarker 2.3.21.

Removes the parameter substring from the beginning of the string, or returns the original string if it doesn't start with the parameter substring. For example:

${"abcdef"?remove_ending("def")}
${"foobar"?remove_ending("def")}  

will print:

abc
foobar  

rtf

The string as Rich text (RTF text). That is, the string with all:

split

It is used to split a string into a sequence of strings along the occurrences of another string. For example:

<#list "someMOOtestMOOtext"?split("MOO") as x>
- ${x}
</#list>  

will print:

- some
- test
- text  

Note that it is assumed that all occurrences of the separator is before a new item (except with "r" flag - see later), thus:

<#list "some,,test,text,"?split(",") as x>
- "${x}"
</#list>  

will print:

- "some"
- ""
- "test"
- "text"
- ""  

split accepts an optional flags parameter, as its 2nd parameter. There's a historical glitch with the r (regular expression) flag; it removes the empty elements from the end of the resulting list, so with ?split(",", "r") in the last example the last "" would be missing from the output.

Note

To check if a strings ends with something and append it otherwise, use the ensure_ends_with built-in.

starts_with

Returns if this string starts with the specified substring. For example "redirect"?starts_with("red") returns boolean true. Also, "red"?starts_with("red") will return true.

Note

To check if a strings starts with something and prepend it otherwise, use the ensure_starts_with built-in.

string (when used with a string value)

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.

substring

Note

This built-in is deprecated since FreeMarker 2.3.21 by slicing expressions: exp[from..<toExclusive] and exp[from..].

A warning if you are processing XML: Since slicing expressions work both for sequences and strings, and since XML nodes are typically both sequences and strings at the same time, there the equivalent expression is someXmlNode?string[from..<toExclusive] and exp?string[from..], as without ?string it would slice the node sequence instead of the text value of the node.

Synopsis: exp?substring(from, toExclusive), also callable as exp?substring(from)

A substring of the string. from is the index of the first character. It must be a number that is at least 0 and less than or equal with toExclusive, or else an error will abort the template processing. The toExclusive 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 toExclusive 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.

Example:

- ${'abc'?substring(0)}
- ${'abc'?substring(1)}
- ${'abc'?substring(2)}
- ${'abc'?substring(3)}

- ${'abc'?substring(0, 0)}
- ${'abc'?substring(0, 1)}
- ${'abc'?substring(0, 2)}
- ${'abc'?substring(0, 3)}

- ${'abc'?substring(0, 1)}
- ${'abc'?substring(1, 2)}
- ${'abc'?substring(2, 3)}  

The output:

- abc
- bc
- c
-

-
- a
- ab
- abc

- a
- b
- c  

trim

The string without leading and trailing white-space. Example:

(${"  green mouse  "?trim})  

The output:

(green mouse)  

uncap_first

The opposite of cap_first. The string with the very first word of the string un-capitalized.

upper_case

The upper case version of the string. For example "GrEeN MoUsE" will be "GREEN MOUSE".

url

Note

This built-in is available since FreeMarker 2.3.1. It doesn't exist in 2.3.

The string after URL escaping. This means that all non-US-ASCII and reserved URL characters will be escaped with %XX. For example:

<#assign x = 'a/b c'>
${x?url}  

The output will be (assuming that the charset used for the escaping is an US-ASCII compatible charset):

a%2Fb%20c  

Note that it escapes all reserved URL characters (/, =, &, ...etc), so this encoding can be used for encoding query parameter values, for example:

<a href="foo.cgi?x=${x?url}&y=${y?url}">Click here...</a>  

Note

Above no HTML encoding (?html) was needed, because URL escaping escapes all reserved HTML characters anyway. But watch: always quote the attribute value, and always with normal quotation mark ("), never with apostrophe quotation mark ('), because apostrophe quotation mark is not escaped by the URL escaping.

To do URL escaping a charset must be chosen that will be used for calculating the escaped parts (%XX). If you are HTML page author and you don't really understand this, don't worry: the programmers should configure FreeMarker so that it uses the proper charset by default (programmers: see more below...). If you are a more technical minded user, then you may want to know that the charset used is specified by the url_escaping_charset setting, that can be set in template execution time (or, preferably, earlier by the programmers). For example:

<#--
  This will use the charset specified by the programmers
  before the template execution has started.
-->
<a href="foo.cgi?x=${x?url}">foo</a>

<#-- Use UTF-8 charset for URL escaping from now: -->
<#setting url_escaping_charset="UTF-8">

<#-- This will surely use UTF-8 charset -->
<a href="bar.cgi?x=${x?url}">bar</a>  

Furthermore, you can explicitly specify a charset for a single URL escaping as the parameter to the built-in:

<a href="foo.cgi?x=${x?url('ISO-8895-2')}">foo</a>  

If the url built-in has no parameter, then it will use the charset specified as the value of the url_escaping_charset setting. This setting should be set by the software that encloses FreeMarker (e.g. a Web application framework), because it is not set (null) by default. If it is not set, then FreeMarker falls back using the value of the output_encoding setting, which is also not set by default, so it is again the task of the enclosing software. If the output_encoding setting is not set either, then the parameterless url built-in can't be executed, and it will cause execution time error. Of course, the url built-in with parameter always works.

It's possible to set url_escaping_charset in the template with the setting directive, but it is bad practice, at least in true MVC applications. The output_encoding setting can't be set with the setting directive, so that's surely the task of the enclosing software. You may find more information regarding this here...

url_path

Note

This built-in is available since FreeMarker 2.3.21.

This is the same as the url built-in, except that it doesn't escape slash (/) characters. This meant to be used for converting paths (like paths coming from the OS or some content repository) that use slash (not backslash!) to a path the can be inserted into an URL. The most common reason why this conversion is needed is that folder names or file names might contain non-US-ASCII letters ("national" characters).

Note

Just like with the url built-in, the desired URL escaping charset (or as a fall back, the output encoding) must be set in the FreeMarker configuration settings, or else the built-in will give error. Or, you you have to specify the charset like somePath?url_path('utf-8').

word_list

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 white-space. Example:

<#assign words = "   a bcd, .   1-2-3"?word_list>
<#list words as word>[${word}]</#list>  

will output:

[a][bcd,][.][1-2-3]  

xhtml

The string as XHTML text. That is, the string with all:

The only difference between this built-in and the xml built-in is that the xhtml built-in escapes ' as &#39; instead of as &apos;, because some older browsers don't interpret &apos; correctly.

xml

The string as XML text. That is, the string with all:

Common flags

Many string built-ins accept an optional string parameter, the so called ``flags''. In this string, each letter influences a certain aspect of the behavior of the built-in. For example, letter i 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.

This is the complete list of letters (flags):

Example:

<#assign s = 'foo bAr baar'>
${s?replace('ba', 'XY')}
i: ${s?replace('ba', 'XY', 'i')}
if: ${s?replace('ba', 'XY', 'if')}
r: ${s?replace('ba*', 'XY', 'r')}
ri: ${s?replace('ba*', 'XY', 'ri')}
rif: ${s?replace('ba*', 'XY', 'rif')}  

This outputs this:

foo bAr XYar
i: foo XYr XYar
if: foo XYr baar
r: foo XYAr XYr
ri: foo XYr XYr
rif: foo XYr baar  

This is the table of built-ins that use these common flags, and which supports which flags:

Built-in i (ignore case) r (reg. exp.) m (multi-line mode) s (dot-all mode) c (whitesp. and comments) f (first only)
replace Yes Yes Only with r Only with r Only with r Yes
split Yes Yes Only with r Only with r Only with r No
matches Yes Ignored Yes Yes Yes No
FreeMarker Manual -- For FreeMarker 2.3.21
HTML generated: 2014-10-12 19:11:24 GMT
Edited with XMLMind XML Editor
Here!