This version is out of date, covering development from v5.0.0 to v5.12.2. It is maintained here only for inbound reference links from elsewhere.

Jump to the current version of aTbRef.

Tinderbox Icon


Operator Type: 

Operator Scope of Action: 

Operator Purpose: 

Operator First Added: 

Operator Altered: 

 Function   [other Function type actions]

 Item   [operators of similar scope]

 Query Boolean   [other Query Boolean operators]



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:

pattern is one of:


For example:


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:


Using back-references

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

Dealing with inline quote characters

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

Possible relevant notes (via "Similar Notes" feature):

A Tinderbox Reference File : Actions & Rules : Operators : Full Operator List : String.contains("pattern")