This version is out of date, covering development from v9.5.0 to v9.7.3. It is maintained here only for inbound reference links from elsewhere. It is no longer actively updated.

Jump to the current version of aTbRef

Tinderbox v9 Icon

String.icontains(regexStr)


Operator Type: 

Operator Scope of Action: 

Operator Purpose: 

Operator First Added: 

Operator Last Altered: 

Operator Uses Regular Expressions: 


String.icontains(regexStr)

This operator tests whether regular expression pattern regexStr matches the referenced string attribute's value in whole or part. Matches are always case-insensitive, unlike String.contains(). The match gives a coerced boolean result: if regexStr is matched (literally or via regex) the function returns the match offset+1 in the source string, where offset is the distance from the start of the string to the start of the matched regex. No match, coerces to false. The +1 works around the fact the match is zero-based, so a match at position 0 (the start of the string), returns as 1 (0+1) and a value of 1 or more coerces to a boolean true. The boolean allows queries' normal true/false to evaluate as normal.

If needing case-sensitivity, use String.contains() which is always case-sensitive

regexStr is one of:

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.

For example:

$MyString.icontains("regex") 

is true if $MyString matches regexStr's pattern. Other more complex usage:

$MyString.icontains($MyMatchText) 

$MyString.icontains($MyString(agent)) 

$MyString(parent).icontains("Tuesday") 

"Any day like Saturday is good".icontains($MyDay) 

"Any day like Saturday is good".icontains("Saturday") 

Note that regex/literal strings are quoted whilst action expressions are not.

Getting the offset of the (first) regex match

If the regular expression regexStr 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 regex. If there is more than one match, the offset of the first match is returned. Formerly, .contains() returned true if the regex 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.icontains("e"); returns 5.

$MyNumber = $MyString.icontains("E"); returns 5.

$MyNumber = $MyString.icontains("eh"); returns 8.

Testing "does not contain"

Use a ! prefix to the query argument:

!$MyString.icontains("Tuesday") 

Use of parentheses around the negated query term, can assist Tinderbox's parsing:

(!$MyString.icontains("Tuesday")) 

Using back-references

In an agent query or if() conditions the function can return back-references to matches of (sub-)strings.

String.icontains() 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

Because regex is parsed for regular expressions, it may be possible to use the '\xNN' form described here to work around the lack of escaping from single double quotes within strings.

Legacy format

This operator is the replacement of the older form of AttributeName(regex) which is deprecated and should not be used in new work (legacy support may fall away). Apart from anything else, the current syntax should remove the confusion over whether/when to use the $ prefix with attribute names in queries.