Operator Scope of Action:
Operator First Added:
This operator tests whether pattern matches the target string attribute in whole or part (for regular expression). Matches are case-sensitive. From v5.8.0, and only in an agent context (i.e. in $AgentQuery) case-sensitivity can be overridden by $AgentCaseSensitive. The match gives a Boolean result.
Thus in default settings, String.contains is always:
- case-insensitive in an agent (as $AgentCaseSensitive is false by default)
- case-sensitive in all other action code contexts
pattern is one of:
- an action code expression (which includes just referencing a single attribute name')
- a quoted string; quoted strings may be either:
- a literal string (i.e. actual text)
- a regular expression
is true if $MyString matches pattern. This is the equivalent to the older form of AttributeName(pattern) which is now deprecated. Apart from anything else, this newer syntax should remove the confusion over whether/when to use the $ prefix with attribute names in queries. Other more complex usage:
"Any day like Saturday is good".contains($MyDay)
"Any day like Saturday is good".contains("Saturday")
From v5.10.2, if the regular expression pattern is found the function now returns the match offset+1, where offset is the distance from the start of the string to the start of the matched pattern. Formerly, .contains() returned true if the pattern was found. The '+1' modifier ensures that a match at postion zero return a number higher than zero which would otherwise coerce to false. Since 1+offset is always true, no changes are required in existing documents but the function also now gives usable offset information.
Testing "does not contain"
Use a ! prefix to the query argument:
In an agent query or if() conditions the function can return back-references to matches of (sub-)strings.
Dealing with inline quote characters