Built-ins for strings

base64

expr?base64

The string encoded in base64 format.  This can be useful in obfuscating personal information to be used in a URL’s query string.

Base64 is an encoding scheme that represents binary data in an ASCII string format by converting non-printable characters into printable characters. Base 64 strings are usually 30% longer that their source (16 bits get converted to 24 bits).

Example:

“Person”?base64

produces this output:

UGVyc29u

boolean

exp?boolean(true-string)
or
exp?boolean(true-string, false-string)

Converts the given expression string into its boolean counterpart. 

If only true-string is given, any value that is not identical to it is considered false.  If both true-string and false-string are given, the string should match either one, otherwise an error occurs.

This comparison is case-sensitive.

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

Example:

<#if isVip?boolean(“true”)>
We love to offer you this great discount!
</#if>

If isVip is true, the output is:

We love to offer you this great discount!

If the value is anything other than true, the returned value is false.

If the strings are stored as “yes” and “no”, you can use the following example:

<#if isVip?boolean(“yes”, “no”)>
We love to offer you this great discount!
</#if>

In this last case, if the isVip value is neither “yes” nor “no”, an error occurs.

cap_first

exp?cap_first

The string with the very first word capitalized. For the exact meaning of “word”, see “word_list built-in”.

Example:

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

produces this output:

  Green mouse
GreEN mouse
- green mouse 

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

capitalize

exp?capitalize

The string with the first letter of each word capitalized. For the exact meaning of “word”, see “word_list built-in”.

Example:

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

produces this output:

  Green Mouse
Green Mouse 

chop_linebreak

exp?chop_linebreak

If the string includes a line break, returns the string without the line break; otherwise returns the unchanged string.

contains

exp?contains(string-expr)

Returns if the string specified as the parameter occurs in the string.

Example:

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

produces this output:

It contains "ice" 

date, time, datetime

exp?date
exp?time
exp?datetime

The string converted to a date value. We recommended including a parameter that specifies the format.

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} 

produces output similar to the following, depending on the output locale and other settings:

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

Note that the dates were converted back to string according to the date_format, time_format, and datetime_format settings. For more information about converting dates to strings, see “String built-in for dates, date interpolations”. It does not matter what format you used when you converted the strings to dates.

If you know what the default date/time/datetime format will be when the template is processed, you do not have to use the format parameter.

Example:

<#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 terminates template processing when you try to access this built-in.

debug

string-exp?debug

Embeds debug information in a message.

If the environment.debug flag is on, the builtin returns the string provided. If the environment.debug flag is off, the builtin returns an empty string.

The environment.debug flag is true only for test and preview launches, and when the debug option was set in the Email Message Designer.

Example:

${(launch.type+’:’)?debug}Welcome to ShopCo

For a standard launch, regardless of the campaign debug flag setting, the example produces the following output:

Welcome to ShopCo.

For a proof launch, if the debug flas is set to “on” in the campaign,  the example produces the following output:

proof:Welcome to ShopCo

For a preview launch, if the debug flag is set to “on” in the campaign, the example produces output similar to the following:

preview:Welcome to ShopCo

For more information, see environment.debug flag.

ends_with

exp?ends_with(string-expr)

Returns true if the string ends with the specified substring. For example "redhead"?ends_with("head") and "head"?ends_with("head") return boolean true.

eval

expr?eval

Evaluates the string in the expression. This built-in is similar to the exec built-in, except that it does not allow directives and executes the string as an expression.  The result of the evaluation is of the proper type.

Example:

“1+2”?eval

produces this output:

3

exec

expr?exec

Uses the script specified in the expression and executes it like a template. This built-in is similar to the eval built-in, except that it allows directives. Expressions must be enclosed in ${}. The result of this built-in is always a string.

Example:

<#assign x=3>
${r”${x+2}”?exec?number + 4>

produces this output:

9

The example first assign a variable x to the value of 3. It then uses a raw string so that it can use ${…} without interpreting it. This is the script, in this case: ${x+2}.  The example then executes the script with the exec built-in. The result of this execution is the string 5, since it is the result of the interpolation. The example then converts the string to a number, and adds 4 to return 9.

groups

expr?groups[index]

Used only with the result of the matches built-in. For more information, see matches built-in.

hex

expr?hex

Converts a string into a hex-encoded string. For each character in the string, a two character representation of the byte in hexadecimal format is produced. This doubles the number of characters needed to represent the originating string.

Example:

“a sample string”?hex

produces this output:

612073616D706C6520737472696E67

To convert a number to hex encoding as described in this section, perform a two-step process as follows:

7371?string?hex

produces this output:

37333731

Note that this built-in applies to strings, and this mechanism is called hex encoding, as opposed to the hex representation of a number.

index_of

exp?index_of(string-expr)

Returns the index of the first occurrence of the specified substring within the string.

Example:

"abcabc"?index_of("bc")

Returns 1. This is because the index of the first character is 0.

You can also start the search from a specific index. For example:

"abcabc"?index_of("bc", 2)

Returns 4. There is no restriction on the numerical value of the second parameter. If it is negative, it is treated as 0. If it is greater than the length of the string, it is treated as equal to the length of this string. Decimal values are truncated to integers. If the substring does not occur in the string (starting from the given index, if you use the second parameter), the built-in returns -1.

html

exp?html

Replaces a string as HTML markup as shown below:

  • < is replaced with &lt;

  • > is replaced with &gt;

  • & is replaced with &amp;

  • " is replaced with &quot;

Note that to insert an attribute value securely, you must quote the attribute value in the HTML template with double quotation mark (") as shown in the following example:

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

In HTML pages, you should use this built-in for all interpolations. This can spare a lot of typing and reduces the chance of mistakes using the escape directive.

interpret

exp?interpret

Interprets a string as an RPL template and returns a user-defined directive that - when applied to any block - executes the template as if it was included at that point. For example:

<#assign x=["a", "b", "c"]>
<#assign templateSource = r"<#list x as y>${y}</#list>">
<#-- Note: That r was needed so that the ${y} is not interpreted above -->
<#assign inlineTemplate = templateSource?interpret>
<@inlineTemplate /> 

produces this output:

abc 

inlineTemplate is a user-defined directive that, when executed, runs the template that was generated on-the-fly using interpret.

You can also apply this built-in to a two-element sequence. In this case, the first element of the sequence is the template source, and the second element is a name for the inline template. This can be useful to give an explicit name to the inline template for debugging purposes. For example, in the above template, you can write the following:

<#assign inlineTemplate = [templateSource, "myInlineTemplate"]?interpret> 

Note that giving the inline template a name has no immediate effect. It is useful only as extra information if an error occurs.

isnull (when used with a string value)

exp?isnull

Returns true if the string is an empty string (“”), otherwise it returns false. When dealing with database fields, NULL and empty string are equivalent. For this reason, this built-in is useful for expressions representing database fields.

Example:

<#if ""?isnull>Empty String is NULL<#else>Empty String is NOT NULL</#if>

poduces this output:

Empty String is NULL

j_string

exp?j_string

Escapes the string with the escaping rules of Java string literals, making it safe to insert the value into a string literal. Note that the built-it does not add quotation marks around the inserted value, you should use it inside a string literal.

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

Example:

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

produces this output:

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

js_string

exp?js_string

Escapes the string with the escaping rules of JavaScript string literals, making it safe to insert the value into a string literal. Note that the built-it does not add quotation marks around the inserted value, you should use it inside a string literal.

Both the single quote (") and the double quote (') are escaped. In addition, the built-in escapes > as \> (to avoid </script>).

All characters under UCS code point 0x20 are escaped. When the characters have no dedicated escape sequence in JavaScript (such as \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> 

produces this output:

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

json_string

exp?json_string

Escapes the string with the escaping rules of JSON language string literals, making it safe to insert the value into a string literal. Note that the built-it does not add quotation marks around the inserted value, you should use it inside a string literal.

The built-in does not escape ' characters, since JSON strings must be quoted with ". However, the built-in does escape the slash (/)as \/ where they occur directly after a < to avoid </script>. The built-in 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 are escaped. When the characters have no dedicated escape sequence in JSON (such as \n, \t, etc.), they will be replaced with a UNICODE escape (\uXXXX).

last_index_of

exp?last_index_of(string-expr)

Returns the index of the last (rightmost) occurrence of the first character of the specified substring within a string.

Example:

"abcabc"?last_index_of("ab")

Returns 3.

You can specify the index from which to start the search.

Example: 

"abcabc"?last_index_of("ab", 2)

Returns 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 the string. Decimal values are truncated to integers.

If the first parameter does not occur as a substring in the string (before the given index, if you use the second parameter), the built-in returns -1.

left_pad

exp?left_pad(numeric-expr)
or
exp?left_pad(numeric-expr, string-expr)

When used with one parameter, the built-in inserts spaces at the beginning of the string until the string reaches the length specified by the parameter. For example:

[${""?left_pad(5)}]

inserts 5 spaces, making the string 5 characters long.

The following example:

[${"a"?left_pad(5)}]

inserts 4 spaces before the a, making the string 5 characters long.

If the string is already as long or longer than the specified number, the built-in does nothing. For example:

[${"abcdefgh"?left_pad(5)}] 

produces this output:

 [abcdefgh] 

If you specify two parameters, the built-in inserts the characters specified by the second parameter at the beginning of the string until the string reaches the length specified by the first parameter.

The following example:

[${""?left_pad(5, "-")}]

inserts 5 dashes (-), making the string 5 characters long.

The following example:

[${"a"?left_pad(5, "-")}]

inserts 4 dashes before the a, making the string 5 characters long.

If the string is already as long as or longer than the specified number, the built-in does nothing. For example:

[${"abcde"?left_pad(5, "-")}] 

produces this output:

 [abcde] 

If the second parameter is longer than one character, the following example:

 [${""?left_pad(8, ".oO")}]

produces this output:

 [.oO.oO.o] 

length

exp?length

The number of characters in the string.

matches

expr?matches(regex-string-expr)
expr?groups[index]

NOTE: Use this built-in only if you are familiar with regular expressions.

Determines whether the string matches the pattern exactly and returns the list of matching sub-strings. The return value is a multi-type value:

  • Boolean: true, if the string exactly matches the pattern; false otherwise. 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.

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> 

produces this output:

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

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

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

produces this output:

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

This built-in accepts an optional second parameter, flags. Note that it does not support the flag f, and ignores the flag r. For more information, see “Common flags for sting built-ins”. 

number

expr?number

The string converted to numerical value. The number must be in the same format as the numerical values specified directly in RPL: it must be in the locale-independent format, where the decimal separator is a dot. In addition, the built-in recognizes scientific notation (e.g. "1.23E6", "1.5e-8").

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

lower_case

exp?lower_case

The lower case version of the string.

Example:

"GrEeN MoUsE"?lower_case

produces this output:

"green mouse".

replace

expr?replace(string-exp-to-find, string exp-new-string)
expr?replace(string-exp-to-find, string exp-new-string, flag)

Replaces all occurrences of a substring with another string.

This built-in does not handle word boundaries.

Example:

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

produces this output:

this is a bulldozer abulldozerus 

The replacing occurs left-to-right. This means that the following example:

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

produces this output:

Xaa 

If the first parameter is an empty string, all occurrences of the empty string are replaced. For example:

 "foo"?replace("","|")

is replaced with:

 "|f|o|o|"

This built-in accepts an optional parameter, flags, as a third parameter. For more information, see “Common flags for sting built-ins”. 

right_pad

exp?left_pad(numeric-expr)
or
exp?left_pad(numeric-expression, string-expr)

Inserts a specified number of spaces or characters at the end of a string.

If  you specify one parameter, the built-in inserts spaces at the end of the string until the string reaches the length specified by the parameter. For example:  

[${""?right_pad(5)}]

inserts 5 spaces, which makes the string 5 characters long.

This example:

[${"a"?right_pad(5)}]

inserts 4 spaces after the a, making the string 5 characters long.

If the string is already as long or longer than the specified number, the built-in does nothing. For example, this code:

[${"abcdefgh"?right_pad(5)}]

produces this output:

 [abcdefgh] 

If you specify two parameters, the built-in inserts the characters specified by the second parameter at the end of the string until the string reaches the length specified by the first parameter.

The second parameter must be a string value, and must be at least one character long.

Example:

[${""?right_pad(8, ".oO")}]

produces this output:

 [.oO.oO.o] 

rtf

expr?rtf

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

  • \ replaced with \\

  • { replaced with \{

  • } replaced with \}

split

expr?split(string-expr)

Splits a string into a sequence of strings.

The built-in assumes that the separator always occurs before a new item. For example, this code:

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

produces this output:

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

The built-in accepts an optional flags parameter, flags, as a second parameter. For more information, see “Common flags for sting built-ins”. 

Example:

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

produces this output:    

- some
- test
- text 

starts_with

expr?starts_with(string-expr)

Checks whether a string begins with the specified substring.

The built-in returns true if the string begins with the substring.

For example, both of the following return true:

 "redhead"?starts_with("red")
 "red"?starts_with("red")

skip 

expr?skip
or
expr?skip(message-str)

A skip is the action of ignoring the current recipient during personalization. This built-in checks whether the value of the field has a null or empty string value, and if it does, causes a skip. In a skip, the email is not sent to the current recipient. The processing of the current record is stopped immediately and control returns to the personalization engine.

Example:

Assume that the profile.firstname field in the database contain the value of ""

Hello ${profile.firstname?skip}
 
Thanks for your recent visit to our site.

Since the value of profile.firstname is empty, the current recipient record is skipped. This is a short form of the skip directive. The previous example could also be written as:

<#if profile.firstname == "">
  <#skip "String is empty">
</#if>
Hello ${profile.firstname}
 
Thanks for your recent visit to our site.

string (when used with a string value)

expr?string

Returns the string as is. The exception is that if the value is a multi-type value (e.g. both a string and a sequence), the resulting value is a simple string, not a multi-type value. This can be utilized to prevent the effects of multi-typing.

substring

exp?substring(from, toExclusive)
or
exp?substring(from)

Returns a substring of the string, starting with the character specified by the from parameter and ending with the character before the toExclusive parameter.

from must be a number that is at least 0 and less than or equal to toExclusive; otherwise, an error occurs that terminates template processing.

toExclusive is the index of the character immediately after the last character to retrieve. It must be a number that is at least 0 and less than or equal to the length of the string; otherwise and error occurs that terminates template processing. If the toExclusive is omitted, 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 is 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)} 

produces this output:

- ab c
- bc
- c
-
 
-
- a
- ab
- abc
 
- a
- b
- c          

trim

expr?trim

The string without leading and trailing white space. For example:

 (${"  green mouse  "?trim}) 

produces this output:

 (green mouse) 

uncap_first

exp?uncap_first

Un-capitalizes the first word of the string.

upper_case

expr?upper_case

Returns the upper case version of the string. For example:

"GrEeN MoUsE"?upper_case

produces this output:

"GREEN MOUSE".

url

expr?url

Returns the string after URL escaping. This means that all non-US-ASCII and reserved URL characters are escaped with %XX. For example:

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

Assuming that the charset used for escaping is an US-ASCII compatible charset, the example produces this output:

a%2Fb%20c 

The built-in 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 that in the above example, no HTML encoding (?htm) was needed, because URL escaping escapes all reserved HTML characters. You should always quote the attribute value with double quotes ("), never with single quotes (') because the single quote is not escaped by URL escaping.

You must select a charset to be used for calculating the escaped parts (%XX). If you do not select a charset, RPL uses a default charset. To set a charset, specify it in the url_escaping_charset setting that can be set in template execution time. For example:

<#--
  This will use the charset specified by the system
  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> 

In addition, you can specify a charset explicitly for a single URL escaping as a parameter:

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

If you do not specify the parameter, the built-in uses the charset specified as the value of the url_escaping_charset setting as set by the system.

word_list

expr?word_list

Returns a sequence that contains all words of the string in the order they appear in the string.

Words are continual character sequences that contain any character except white space. For example:

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

produces this output:

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

xhtml

expr?xhtml

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

< is replaced with &lt;

> is replaced with &gt;

& is replaced with &amp;

" is replaced with &quot;

' is replaced with &#39;

NOTE: 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;. This is because some older browsers do not interpret &apos; correctly.

xml

expr?xml

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

< is replaced with &lt;

> is replaced with &gt;

& is replaced with &amp;

" is replaced with &quot;

' is replaced with &apos;

Common flags

Many string built-ins accept an optional string parameter, called flag.

Each letter in the flag affects a certain aspect of built-in behaviour. For example, the letter i means that the built-in should not differentiate between the lower and upper-case variation of the same letter.

You may use the flags in any order.

Supported flags

The following table lists all supported flags:

Flag

Description

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. RPL uses the variation of regular expressions described below.

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. Note that ^ and $ do not match the line-break character itself.

s

Enables dot-all mode for regular expressions (same as Perl single-line mode). In dot-all 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')} 

produces this output:

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

Supported flags by built-in

The following table lists all built-ins that support flags and shows which flags each one supports.

Built-in name

Flags

c

f

i

m

r

s

replace

Only with r

Yes

Yes

Only with r

Yes

Only with r

split

Only with r

No

Yes

Only with r

Yes

Only with r

match

Yes

No

Yes

Yes

Ignored

Yes