FEEL string functions: substring, contains, split, replace and more

FEEL guide · 14 built-in functions · DMN 1.6

FEEL has no methods on strings. Everything you do with text in a DMN decision is a built-in function call or the + operator. This guide covers all of them, with the edge cases that tend to surprise people: positions start at 1 and can be negative, a null argument makes the result null, and three of the functions take a regular expression where you might expect plain text.

Each result on this page was computed by the FEEL engine behind the evaluator at the top. Click Try it to run any example, then change it.

All FEEL string functions at a glance

Rules every string function follows

Positions are 1-based. A negative position counts from the end, so -1 is the last character. DMN 1.6 restricts substring to positions that exist: the start position must not be 0 and must lie within the string, and the length must not run past its end. Outside that range the result is null (Table 75). Some engines are more lenient there, so a portable model does not rely on out-of-range behavior. A fractional position or length is truncated to an integer.

Arguments are not converted. If a string function receives a number, a date or null where it expects a string, the result is null; nothing is turned into a string implicitly. Use string() to convert first.

Comparison is case-sensitive. contains, starts with, ends with and = compare characters exactly. To compare without case, lower-case both sides, or use matches with the i flag.

Concatenating strings

FEEL has no concat function for two strings. Use the + operator. To join a list of strings, use string join, which also takes a separator. Neither one converts numbers for you, so wrap numbers and dates in string().

Regular expressions: matches, replace and split

matches, replace and split take a regular expression in XPath/XQuery syntax, not a plain string. This catches people out most often with ., which matches any character. To match a literal dot, escape it as \\. inside a FEEL string. The FEEL string literal turns \\ into one backslash, and the regex then reads \..

Function reference

Each function with its examples and edge cases. The heading links to the function's own page with its parameter table.

substring

substring(string, start position, length?)

Returns the part of the string that starts at start position. Without length, it runs to the end of the string; a negative start position counts backwards from the end.

A negative start position counts from the end: -1 is the last character, -3 the third from last. DMN 1.6 defines substring only for positions inside the string: the start position must be non-zero and within [-length..length], and the length must be at least 1 and must not run past the end. Anything else is outside the function's domain, and the result is null. A fractional start position or length is truncated, as for every integer parameter of a built-in.

string length

string length(string)

Returns the number of characters in the string.

The length counts characters (Unicode code points), so accented letters and emoji count as one each. Spaces count too. A non-string argument such as a number gives null; convert it with string() first if you want the length of its text.

upper case

upper case(string)

Returns the string with every character converted to upper case.

lower case

lower case(string)

Returns the string with every character converted to lower case.

substring before

substring before(string, match)

Returns everything before the first occurrence of match; the empty string if match does not occur.

substring after

substring after(string, match)

Returns everything after the first occurrence of match; the empty string if match does not occur.

contains

contains(string, match)

Returns true if the string contains match anywhere, false otherwise.

contains takes a plain string, not a pattern, so a dot is just a dot. To test whether a list contains a value, use list contains instead.

starts with

starts with(string, match)

Returns true if the string begins with match.

ends with

ends with(string, match)

Returns true if the string ends with match.

matches

matches(input, pattern, flags?)

Returns true if the input matches the regular expression. Flags: i for case-insensitive, s for dot-all, m for multi-line, x to ignore whitespace in the pattern.

The pattern only has to match somewhere in the input. Anchor it with ^ and $ to test the whole string.

replace

replace(input, pattern, replacement, flags?)

Returns the input with every match of the regular expression replaced by the replacement, which may reference capture groups as $1, $2, ….

split

split(string, delimiter)

Splits the string at every match of the delimiter pattern and returns the parts as a list of strings.

The delimiter is a regular expression. A plain comma or semicolon works as expected, but a dot or a pipe has to be escaped. Empty parts between consecutive delimiters are kept. A pattern such as \\s*,\\s* splits and trims in one step.

string join

string join(list, delimiter?)

Concatenates a list of strings into one string, optionally separated by a delimiter. Null elements in the list are skipped.

This is the list counterpart of the + operator. Elements must be strings: a list of numbers gives null, so convert with for x in list return string(x) first.

string

string(from)

Converts any FEEL value to its string representation.

How B-FEEL differs

In standard FEEL an invalid argument makes the result null. The business-friendly B-FEEL dialect returns a type default instead. Both columns were evaluated by the same engine:

More FEEL guides

FEEL numeric functions · FEEL list functions · FEEL date and time functions · Language constructs · Examples cheat sheet

Defined by the OMG DMN 1.6 specification, chapter 10.3.4 (built-in functions).