Built-ins for strings

FAQ: To create substrings, use expressions like myString[first..last]. For more details, read about the expression syntax.

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

uncap_first

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

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.

date, time, datetime

The string converted to a date value. It is recommended to specify a parameter that specifies the format. For example:

<#assign test1 = "10/25/1995"?date("MM/dd/yyyy")>
<#assign test2 = "15:05:30"?time("HH:mm:ss")>
<#assign test3 = "1995-10-25 03:05 PM"?datetime("yyyy-MM-dd hh:mm a")>
${test1}
${test2}
${test3}  

will print something like (depends on the output locale (language) and on other settings):

Oct 25, 1995
3:05:30 PM
Oct 25, 1995 3:05:00 PM  

Note that the dates was converted back to string according to the date_format, time_format and datetime_format settings (for more information about converting dates to strings read: string built-in for dates, date interpolations). It does not mater what format did you use when you have converted the strings to dates.

You don't have to use the format parameter, if you know what the default date/time/datetime format will be when the template is processed:

<#assign test1 = "Oct 25, 1995"?date>
<#assign test2 = "3:05:30 PM"?time>
<#assign test3 = "Oct 25, 1995 03:05:00 PM"?datetime>
${test1}
${test2}
${test3}  

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

ends_with

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

html

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

  • < replaced with &lt;
  • > replaced with &gt;
  • & replaced with &amp;
  • " replaced with &quot;

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

groups

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

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 argument: 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 string argument does not occur as a substring in this string (starting from the given index, if you use the second argument), then it returns -1.

j_string

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 UCS code point 0x20, that has no dedicated escape sequence in Java language, will be replaced with 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 is safe to insert the value into a string literal. Both quotation mark (") and apostrophe-quoate (') are escaped. In additional, all characters under UCS code point 0x20, that has no dedicated escape sequence in JavaScript language, will be replaced with hexadecimal escape (\xXX).

Example:

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

will output:

  alert("Welcome Big Joe\'s \"right hand\"!");  

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 argument indicates the maximum index of the start of the substring. There is no restriction on the numerical value of the second argument: 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 string argument does not occur as a substring in this string (before the given index, if you use the second argument), then it returns -1.

length

The number of characters in the string.

lower_case

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

matches

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

Note

This built-in will work only if you use Java2 platform 1.4 or later. Otherwise it will stop template processing with error.

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:

  • Boolean: true, if it the string exactly matches the pattern, otherwise false. For example, "fooo"?matches('fo*') is true, but "fooo bar"?matches('fo*') is false.

  • Sequence: the list of matched substrings of the string. Possibly a 0 length sequence.

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:

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

This will print:

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

matches accepts an optional 2nd parameter, the flags. Note that it does not support flag r, because it always uses regular expressions.

number

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. "1.23E6", "1.5e-8").

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

Known problem: If you use earlier Java2 platform than v1.3, the built-ins will not recognize + prefix and scientific notation.

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  

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

rtf

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

  • \ replaced with \\

  • { replaced with \{

  • } replaced with \}

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, 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.

starts_with

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

string

Does nothing. Returns the string as-is.

trim

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

(${"  green mouse  "?trim})  

The output:

(green mouse)  

upper_case

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

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]  

xml

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

  • < replaced with &lt;
  • > replaced with &gt;
  • & replaced with &amp;
  • " replaced with &quot;
  • ' replaced with &apos;

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):

  • i: Case insensitive: do not differentiate the lower and upper-case variation of the same letter.

  • f: First only. That is, replace/find/etc. only the first occurrence of something.

  • r: The substring to find is a regular expression. FreeMarker uses the variation of regular expressions described at http://java.sun.com/j2se/1.4.1/docs/api/java/util/regex/Pattern.html. This flag will work only if you use Java2 platform 1.4 or later. Otherwise it will cause template processing to stop with error.

  • m: Multi-line mode for regular expressions. In multi-line mode the expressions ^ and $ 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.

  • s: Enables dotall mode for regular expressions (same as Perl singe-line mode). In dotall mode, the expression . matches any character, including a line terminator. By default this expression does not match line terminators.

  • c: Permits whitespace and comments in regular expressions.

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')}  

Prints:

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

r

m

s

c

f

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

match

Yes

No

Yes

Yes

Yes

No


Page generated: 2004-06-15 22:17:59 GMT FreeMarker Manual -- For FreeMarker 2.3