15.5. Containment Operators

The containment operators test whether the value of one thing is to be found "inside" the value of another. For example, the string "test" contains the string "e". Containment may apply to two strings, two lists, or two records. The result is a boolean.

Containment implies comparison, and the nature of comparisons involving strings can be influenced by a considering clause; see Chapter 19.

It is worth stressing that in the case of list containment, both operands must be lists. In other words, the second operand is not an element; it's a sublist. This is a little counterintuitive at first. To complicate matters, AppleScript fools you by apparently letting you say just what you (wrongly) think you should be allowed to say:

{1, 2} contains 2 -- true

You can say that, but not because it is correct on its face; it's because 2 is coerced to {2} implicitly to get the right syntax, which would be this:

{1, 2} contains {2} -- true

Because the second operand is a sublist, you can ask about more than one element at once:

{1, 2, 3} contains {2, 3} -- true

Lists are ordered, so the items of the sublist you ask about must appear consecutively and in the same order in the target list. These are false:

{1, 2, 3} contains {1, 3} -- false
{1, 2, 3} contains {3, 2} -- false

Because lists can contain lists, you may have to use an explicit extra level to say what you mean:

{{1}, {2}} contains {2} -- false
{{1}, {2}} contains {{2}} -- true

The first is false because 2 is not an element of the first list, and {2} is not going to be coerced to {{2}} for youit's a list already, so there's nothing to coerce.

With regard to record containment, both the label and the value must match for containment to be true:

{name:"Matt", age:"51"} contains {name:"Matt"} -- true
{name:"Matt", age:"51"} contains {title:"Matt"} -- false
{name:"Matt", age:"51"} contains {name:"Socrates"} -- false

Records are not internally ordered:

{name:"Matt", age:"51"} contains {age:"51", name:"Matt"} -- true

For purposes of containment, the empty list is treated as the empty record:

{name:"Matt", age:"51"} contains {} -- true
{} contains {name:"Matt", age:"51"} -- false

Because the containment operators are overloaded to apply to both strings and lists, the first operand is never implicitly coerced to a string, because AppleScript can't know that this is what you mean; it is coerced to a list unless it is a string (or record). The second operand is then coerced to match the datatype of the first. For example:

"51" contains 5 -- true; string containment, "51" contains "5"
51 contains 5 -- false; list containment, {51} doesn't contain {5}

It's important not to confuse the implicit coercion rules here with those for certain other operators. For example, your experience with arithmetic operators might lead you to expect a certain kind of implicit coercion:

{"7"} * 7 -- 49

The list of a single string is coerced to a single string and from there to a number. But that isn't going to happen with contains:

{"7"} contains 7 -- false

The first operand isn't coerced at all; the second operand is coerced to {7}, and that's the end. The second operand isn't a sublist of the first, so the comparison is false.

Do not rely on implicit coercion of nonnative classes to a list; it usually doesn't work. For example:

tell application "Microsoft Entourage"
    every contact contains contact 1
    -- error: Can't make «class cAbE» id 1 of application "Microsoft Entourage"
    into type vector
end tell

You should have said {contact 1}, or contact 1 as list (Entourage implements coercion to a list, unlike the Finder example in "Explicit Coercion" in Chapter 14). For the mysterious "vector" type mentioned in the error message, see "List" in Chapter 13.

containment

containment

Syntax

string1 contains string2
string2 is in string1
list1 contains list2
list2 is in list1
record1 contains record2
record2 is in record1

Description

Tests whether the first operand contains the second. The is in synonyms reverse the operand order of the contains synonymsthat is, with is in, the second operand comes physically before the first operand (as deliberately shown in the syntax listings), but it is still the second operand. This is relevant in the rules for implicit coercions.

initial containment

initial containment

Syntax

string1 begins with string2
list1 begins with list2

Description

Same as contains with the additional requirement that the second operand come first in the first operand. Records are not ordered, so they aren't eligible operands. Synonym is starts with.

final containment

final containment

Syntax

string1 ends with string2
list1 ends with list2

Description

Same as contains with the additional requirement that the second operand come last in the first operand. Records are not ordered, so they aren't eligible operands.