== (equality)

---

---

The operator to test equality (i.e. 'is the same as') is '==', two equals signs. Note that this replaces older syntax where a single equals sign was used contextually for both assignment and equality tests.

This operator is used either in agent queries or in the conditional part of an if(condition){action} code. It is the functional opposite of the '!=' inequality test.

This test cannot be meaningfully applied to Set or List type attribute data, as the entire attribute value is matched, rather than individual values as might otherwise be assumed. For these data types use the .contains() or .icontains() operators instead, noting the scope for ambiguous matching due to stemming of words ("car" will match "car", "cars" and "carrot").

Because equality comparisons of Date-type data match at day scope, rather than full date/time values (for legacy reasons), use interval() to compare Date-type equality.

Equality testing can be negated, i.e. tested for a non-match, or combined with greater/less than for a range of tests as further explored in Basic Comparison Codes.

For a case-insensitive lexical equality test, use a lowercase on-the-fly transform:

"Absquatulate".lowercase == "absquatulate" 

If we set $MyString to "Absquatulate", then:

$MyString.lowercase == "absquatulate" 

If $MyOtherString(Some note) has the value "absquatulate", then:

$MyString.lowercase == $MyOtherString(Some note) 

Note the stored left-side value is not altered, but its transformed version is used in the test giving a case-insensitive comparison. This method only works for upper/lower case comparisons; accented characters are lexically different characters regardless of case.

Equality and List/Sets

Using == (and !=) with Lists & Sets means you are checking the entire literal contents, i.e. a string like "ant;bee;cow" rather than by individual sub-value: "ant" and "bee" and "cow". Thus the equality test cannot be used to check if the attribute contains a discrete value, use .contains() instead (or .icontains() for case-insensitive matches). Importantly, when testing a string (or expression resolving to a string) equivalence against a list, it is the list that must be tested using .contains(). This is best shown using string literals representing a String type and a List type:

"cow".contains("ant;bee;cow") 

"ant;bee;cow".contains("cow") 

"ant;bee;Cow".contains("cow") 

The first, testing the string, resolves to false but the second, testing the list, gives true. The third is false but would be true if using an .icontains() test. Thus when equivalence testing a string against a list, always run the .contains() on the list and not the string.

To test two lists hold the same values (and only those values), in the same case, in the same order, the == equivalence operator can be used as this tests the stored concatenated value lists in each case. To check common items shared by two lists use List/Set.intersect().

Testing a List vs a Set, it would be sensible to apply a .sort() or .isort() to each, reflecting that the sort state of a list is unknown and a == test compares the stored concatenated value string: the test would fail if the lists held the same values but stored in different orders. This shows up a difference between lists and sets. Although the literal value of a set may hold values in any order, when tested in code, they are being tested after sorting into (some**) order. Incidentally, this is why you cannot set a sort order as you can with a list as internally your given sort order is ignored. Consider $MySetA and $MyListA both with the values "ant;bee;cow". $MySetB and $MyListB both have the value "bee;ant". Now:

$MySetA == $MySetB gives FALSE

$MyListA == $MyListB gives FALSE

both are expected. Now make both the B attributes value "bee;ant;cow"

$MySetA == $MySetB gives TRUE

$MyListA == $MyListB gives FALSE

This is because the Set compares the literal result of sorted values, whereas the List

does not. But

$MyListA == $MyListB.sort gives TRUE

This is in effect what's happening with the sets, as in:

$MyListA.sort == $MyListB.sort 

whereas in our last example above, $MyListA was already in default sort order so no applied sort was required. From experiment, this seems to be a (case-sensitive) computer lexical sort, i.e. "Bee;ant;bee" with capitals preceding lowercase letters in the sort.