| Operator Type: | Function |
| Operator Scope of Action: | Item |
| Operator Purpose: | Boolean (query) |
String.contains("pattern")
New to v5.7.0, 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
$MyString.contains("pattern")
For example:
$MyString.contains(pattern)
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:
$MyString.contains($MyMatchText)
$MyString.contains($MyString(agent))
$MyString(parent).contains("Tuesday")
"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:
!$MyString.contains("Tuesday")
