Calculation Formulas
Back to Calculation Formulas Overview
Back to Functions Overview
Function "SetToString"
SetToString(set [, default [, separator [, delimiter [, delimitAll [, delimiterEscape]]]]])
Function: Converts a set into a text string by listing all values in the set (if any), separating them with a specified separator character and optionally enclosing the values in specified delimiters.
Note: If this function is used with a multi select field from a subscriber list as the set argument, then it can only be used in the message content itself and not on a landing page, because multi select fields are not supported on landing pages.
Important: The final result of a formula in a *Calc system drop-in must not exceed the
maximum length of 900 characters.
Similarly, if the formula is used in the derivation rule of a derived profile field (in a
subscriber list or group), then the result must not exceed the maximum length of 100 characters.
Using SetToString in a formula does however increase the danger of exceeding
these limits, especially if the result of the function is also used as the direct result of the formula (without further
processing by other functions), and if the set contains a large number of values (this may for example easily be
the case if the set is defined by a multiple-select merge field). In such a situation, the mail job delivery may
fail (if used in a *Calc system drop-in) or the recalculation of the derived profile field may fail (if used in a
derivation rule).
If in doubt, it may be better to use the
SetToStringWithMaxLen
function instead, which allows you to control the output length of the result.
If the formula is used in the condition tree of a "Subscriber List" target group, then such a restriction
does not apply.
Return-Type: Text
Arguments:
set - Type Number Set or Text Set: The set that is to be converted into a text.
(The following argument is optional.)
default - Type Text: Defines the default text that shall be the result of the function if the given set is
empty.
If not specified, then an empty text string is used as the result for an empty set.
(The following argument is optional but may be supplied if the "default" argument has been supplied too.)
separator - Type Text: The separator text that is to appear between two values. The separator will only appear
between values, i.e. it will not appear before the first or after the last value. So if the set has less than
two elements, the separator will not appear at all. Note that "separator" may be any text, not only a single
character.
If not specified, the comma "," is used by default as the separator.
(The following argument is optional but may be supplied if the "default" and "separator" arguments have been supplied too.)
delimiter - Type Text: The delimiter text that is to be used to enclose values. In some situations, it may happen
that the values from the set already contain the chosen "separator" as part of their value texts. In such a case,
the occurrences of the separator text in the values may be confusing, as such an occurence may be misinterpreted
as an actual separator, after which a new value starts, while it actually is only part of the value.
To avoid this, it is possible to enclose the values in delimiters, to better mark the beginning and end of a value
(if such a value then contains the separator text, then this does not matter, as the end of the value is no longer
marked by the separator, but instead by the delimiter).
For this, the "delimiter" argument can be used. If specified, then individual
values may be enclosed in the specified delimiter text (depending on the "delimitAll" argument, see below). If a value
is enclosed with delimiters, and the value itself also already contains the delimiter text, then this delimiter text is escaped (in a
way depending on the "delimiterEscape" argument, see below). If not specified, then values are never enclosed with extra delimiters.
Note: "delimiter" may be any text, not only a single character.
(The following argument is optional but may be supplied if the "default", "separator" and "delimiter" arguments have
been supplied too.)
delimitAll - Type Boolean: If set to "true", then all values will be enclosed with the given delimiter text. If
set to "false", then only values that actually contain the separator text will be enclosed with delimiters.
If not specified, then all values will be enclosed with delimiters (default is "true").
(The following argument is optional but may be supplied if the "default", "separator", "delimiter" and "delimitAll" arguments
have been supplied too.)
delimiterEscape - Type Text: Defines which text shall be used to escape an occurrence of the delimiter text in a value.
If a value is enclosed with delimiters, but the value already contains the delimiter text itself, then this contained delimiter text
could be confused with the end-delimiter that ends the value. Therefore, if the delimiter text appears in the value,
it needs to be "escaped". The escaping is done by inserting the "delimiterEscape" text just before the delimiter text
in the value.
If "delimiterEscape" is not specified, then the delimiter text itself will be used for escaping, i.e. this has the
effect that if the delimiter text appears in the value, then it will be escaped by doubling it.
For example, if the delimiter text is the standard quote character <">, and the value already contains quotes, like
this: <value "contains" quotes>, and if no "delimiterEscape" is specified so that the default is applied,
then the escaped value will contain "doubled" quotes, like this: <value ""contains"" quotes>.
If instead the backslash is supplied for "delimiterEscape", then the escaped value will look like this:
<value \"contains\" quotes>.
Note: "delimiterEscape" may be any text, not only a single character.
Examples:
SetToString(&MULTI_SELECT_FIELD;)
SetToString(&MULTI_SELECT_FIELD;, "empty")
SetToString(&MULTI_SELECT_FIELD;, "empty", "; ")
SetToString(&MULTI_SELECT_FIELD;, "empty", "; ", "'")
SetToString(&MULTI_SELECT_FIELD;, "", "; ", "'", false)
SetToString(&MULTI_SELECT_FIELD;, "", "; ", "'", true, "\")