List/Set.contains(matchStr)

---

List.contains(matchStr)

This operator tests whether the string matchStr matches a whole discrete value string within a the referenced list/set attribute value. Unlike when used with a String, e.g. String.contains, there is no regex functionality. With lists the function behaves as if the chained list were being iterated and an equality (==) test was being run on each list item.

Matches are always case-sensitive, unlike List/Set.icontains() where the matches are always case-sensitive.

Used with a list (List or Set data types), .contains() cannot match to granularity less than a single whole item in the chained list. Importantly, this differs from the operator's use with String data, e.g. String.contains(), where regular expression matching is applied. If regex parsing is needed, e.g. to match a partial list value, coerce the list to a string and use to operator on that string—see below.

A match gives a numerical result which is the 1-based matched list position. That number coerces to the boolean result needed for use in queries: ) to false and 1 or more to true.

matchStr is one of:

• an action code expression (which includes just referencing a single attribute name)
• a quoted literal string (i.e. actual text). Important: do not omit the enclosing quotes. 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 literals in quotes.

$MyList.contains(matchStr)

The contains operator may also be used with both sets and lists, in which case it tests for set membership, i.e. matching to complete individual values rather than part of values. Thus:

$MyList.contains("Tuesday") 

$MyList(parent).contains("Tuesday") 

are both true if $MyList contains "Monday;Tuesday;Friday". A match can use an attribute value as the matchStr. Consider a single-value String-type attribute 'MyDay':

$MyList.contains($MyDay) 

is true if the value of $MyDay for a given note is any of "Monday", "Tuesday or "Friday". Thus in an agent or find query, the regex varies by the source value in the currently-tested note.

The chained list may also be a literal list:

"Saturday;Sunday".contains("Sunday") 

"Saturday;Sunday".contains($MyDay) 

If the matchStr is found the function returns a number which is the 1-based matched list position. In the last example above the returned value will be 2, because 'Sunday' is the second item in the list.

Testing a negative: "does not contain"

Use a ! prefix to the query argument:

!$MyList.contains("Tuesday") 

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

(!$MyList.contains("Tuesday")) 

Matching partial list values

As changing to list suppresses the normal string regex parsing, interposing the .asString() operator allows the list to be treats a a string so as to behave like a String.contains() test. See the .asString() operator listing for more detail. This is a more elegant replacement for the old workaround of using List.format("#").icontains("some match) as may be seen in some older code samples.