Operator Scope of Action:
Operator First Added:
This operator tests whether pattern matches the referenced string attribute in whole or part (for regular expression). Matches are case-sensitive. Also, but 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.
Important: do not omit the enclosing quotes for literal strings or regex. If omitted, Tinderbox will try to evaluate the string as an expression. Doing this may result in the expected result but this is actually a false positive. So, remember to enclose your regex or literals in quotes.
is true if $MyString matches pattern. This is the equivalent to the older form of AttributeName(pattern) which is 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")
Getting the offset of the (first) pattern match
If the regular expression pattern is found the function returns the match offset+1, where offset is the distance from the start of the string to the start of the matched pattern. If there is more than one match, the offset of the first match is returned. Formerly, .contains() returned true if the pattern was found. The '+1' modifier ensures that a match at position 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 gives usable offset information. Thus, if $MyString is "abcdefgehEi":
$MyNumber = $MyString.contains("e"); returns
$MyNumber = $MyString.contains("E"); returns
$MyNumber = $MyString.contains("eh"); returns
Testing "does not contain"
Use a ! prefix to the query argument:
Use of parentheses after the !, around the query, can assist Tinderbox's parsing:
In an agent query or if() conditions the function can return back-references to matches of (sub-)strings.
String.contains() clears the list of back references from previous processes, so $0 and $1 correspond to its own results, not those from prior expressions.
Dealing with inline quote characters