Text Operators

SenseTalk includes several operators that you can use specifically for working with text values.

& (Ampersand) Operator

Behavior: Creates a text string by combining values one after another. Both operands are converted to text representations if they are not already text before concatenation.

Syntax:
operand1 & operand2

Example:

put "The answer is:" & answer

&& (Double Ampersand) Operator

Behavior: Joins (concatenates) two values with a space between them. Both operands are converted to text representations if they are not already text before concatenation.

Syntax:
operand1 && operand2

Example:

put "Dear" && correspondent & "," into openingLine

Is In, Is Contained By, Is Not In, Isn't In Operators

Behavior: Tests for the presence or absence of one value within another, returning true or false.

Ordinarily, this operator is not case-sensitive. To force case-sensitivity, use the considering case option.

Syntax:
targetValue is {not} in sourceValue {considering case | ignoring case}
targetValue is {not} contained by sourceValue {considering case | ignoring case}

When sourceValue is a list, this operator tests whether any of its values is equal to targetValue. If targetValue is also a list, it tests whether a consecutive sequence of the values in sourceValue are equal to the values in targetValue.

When sourceValue is a range, it is treated the same as a list (as would be generated by converting the range to a list) with the values in that list checked for the presence of targetValue. This is different from the is within operator which checks whether a value lies anywhere between the start and end values of the range.

When sourceValue is a property list (object), the behavior can be determined by the object itself, or the built-in containsItem function (see Checking Object Contents for details).

When targetValue is a pattern, defined by using SenseTalk's pattern language, this operator tests whether the pattern matches any substring within the sourceValue.

Otherwise, sourceValue is evaluated as text, and tested to see if it contains targetValue as a substring. To force a substring text search when sourceValue is a list or property list, use the asText function or as text operator to convert it to text.

Example:

if "-help" is in commandLine then ...

Example:

if "Johnson" is not in indexList then ...

Example:

put 12 is in [[11,12],[13,14]] -- True

Example:

put [2,3] is in [1,2,3,4,5] -- True

Example:

put [2,3] is contained by 1..5 -- True

Example:

put <"(", chars,")"> is in "Elvis (the King) Presley" -- True

Contains, Does Not Contain, Doesn't Contain Operators

Behavior: Tests for the presence or absence of one value within another, giving true or false. Ordinarily, this operator is not case-sensitive. To force it to be case-sensitive, use the considering case option. This performs exactly the same operation as the is in operator, but allows the relationship to be expressed the other way around. Use whichever one feels more natural in a given context.

Syntax:
sourceValue contains targetValue {considering case | ignoring case}
sourceValue does {not} contain targetValue {considering case | ignoring case}

When sourceValue is a list, this operator tests whether any of its values is equal to targetValue. If targetValue is also a list, it tests whether a consecutive sequence of the values in sourceValue are equal to the values in targetValue.

When sourceValue is a range, it is treated the same as a list (as would be generated by converting the range to a list) with the values in that list checked for the presence of targetValue. This is different from the is within operator which checks whether a value lies anywhere between the start and end values of the range.

When sourceValue is a property list (object), the behavior can be determined by the object itself, or the built-in containsItem function (see Checking Object Contents for details).

Otherwise, sourceValue is evaluated as text, and tested to see if it contains targetValue as a substring. To force a substring text search when sourceValue is a list or property list, use the asText function or as text operator to convert it to text.

Example:

if commandLine contains " -x " considering case then ...

Example:

if word n of partNums doesn't contain "q" then ...

Example:

put nameList contains "Mayfield" into shouldInvite

Example:

put 5..17 by 2 contains 8 --> False  (since only odd numbers are generated)

Example:

put ["abcd","defg"] contains "abc" --> False

Example:

put ["abcd","defg"].asText contains "abc" --> True

Is Among, Is Not Among, Isn't Among Operators

Behavior: Tests for the presence or absence of one value as a whole chunk, list item, key or value within another. Ordinarily, this operator is not case-sensitive. To force it to be case-sensitive, use the considering case option. ChunkTypes can be any of characters, chars, words, lines, items, text items, list items, keys, values, or bytes.

Syntax:
targetValue is {not} among {the} chunkTypes of sourceValue {considering case | ignoring case}

Example:

put "cat" is among the items of "dog,cat,mouse" --> True

Example:

put "be" is not among the words of "bell jibe amber" --> True

Example:

if "cost" isn't among the keys of part then set part's cost to 10

Begins With, Does Not Begin With, Doesn't Begin With Operators

Behavior: Checks whether or not a text string begins with a particular sequence of characters, or whether a list begins with a particular value or sequence of values. Ordinarily, this operator is not case-sensitive. To force it to be case-sensitive, use the considering case option.

Syntax:
operand1 begins with operand2 {considering case | ignoring case}
operand1 does {not} begin with operand2 {considering case | ignoring case}

Example:

if sentence begins with "Joshua " considering case then ...

Example:

if word n of productNames does not begin with "q" then ...

Example:

if [9,12,14,23] begins with [9,12] then put "yes" --> yes

Ends With, Does Not End With, Doesn't End With Operators

Behavior: Checks whether a text string ends with a particular sequence of characters, or whether a list ends with a particular value or sequence of values. Ordinarily, this operator is not case-sensitive. To force it to be case-sensitive, use the considering case option.

Syntax:
operand1 ends with operand2 {considering case | ignoring case}
operand1 does {not} end with operand2 {considering case | ignoring case}

Example:

if sentence ends with "?" then ...

Example:

if word n of plurals does not end with "es" then ...

Example:

if scoresList ends with [98,99,100] then resetScores

Example:

put "size 13W" ends with <2 digits then a letter> --> True

Matches, Does Not Match, Doesn't Match Operators

Behavior: Use the matches operator to test whether a variable or expression is an exact match for a pattern. One of the operands must be a pattern, and the other is treated as a string value. This operator returns true if the pattern fully matches the entire string. If the pattern matches only part of the string or doesn't match at all, the result of the matches operator is false.

The matches operator returns true if the pattern can potentially match the full value, even if the usual match of the pattern might not return the full string due to lazy quantifiers being used (which is the default).

For information about SenseTalk's pattern language, see SenseTalk Pattern Language Basics.

Syntax:
operand1 matches operand2
operand1 [doesn’t | does not] match operand2

Example:

put 83 matches <digit,digit> --> True

Example:

put <"x", 3 chars, "y"> matches "xyzzy" --> True

Example:

put <"$", digits> matches "$895" --> True
put the occurrence of <"$", digits> in "$895" --> "$8"

Example:

set partNum to <"ABC", digit, char in "JQXZ", digit>
put partNum matches "Abc9Q2" --> True ("ABC" is not case sensitive)
put partNum matches "Abc9Q2" with case --> False ("ABC" must match case)