91. CONTAINS v. "="
Description
The difference between CONTAINS and "=", and when to use CONTAINS.
Code
Example #1:
IF Address-t CONTAINS "Anytown"
"This is an Anytown resident"
ELSE
"This is not any Anytown resident"
END IF
Example #2:
IF FullName-t = "Bob Johnson"
"This is Bob himself"
ELSE IF FullName-t CONTAINS "Johnson"
"This is a member of the Johnson family"
ELSE
"This is not a Johnson"
END IF
Example #3:
IF "massachusetts~virginia~kentucky~pennsylvania" CONTAINS StateName-t
"The Commonwealth of «StateName-t»"
ELSE
"The State of «StateName-t»"
END IF
Explanation
Most HotDocs users are familiar with the A = B expression. The "=" operator is used to check whether value A is exactly the same as value B (lettercase ignored -- see note below).
But at times an "exact match" is too rigid, so HotDocs has a more flexible way of making comparisons, known as CONTAINS. The A CONTAINS B model also compares two strings, but only looks at whether the second string is contained anywhere in the first. For example, "ABCDE" CONTAINS "C" is TRUE. Notice, then, that string A is the string being searched, and string B is the string you are looking for. If that is confusing, just remember that string A is typically a longer string and string B is a shorter string.
Example #1 above shows a common use for CONTAINS. In this example, we are looking at a complete address and trying to see if it is an "Anytown" address. If the string "Anytown" is found anywhere in Address, the expression is TRUE.
Example #2 uses both CONTAINS and "=". It first checks to see if the name in FullName-t is "Bob Johnson" (exact match). If it is not Bob, then the computation uses CONTAINS to see if maybe this is some Johnson. If the name has "Johnson" anywhere in it, the expression is true and we'll assume this is a member of the Johnson clan. Do note that if FullName-t is "Johnson MacAurthur" or "Johnson & Johnson", the computation will still assume that the person is a Johnson. CONTAINS does not give us any information about where the match is found in the string.
Example #3 demonstrates a powerful use of CONTAINS. This computation is examining a StateName-t to see whether it should be displayed as "The State of ..." or "The Commonwealth of ..." (for the full computation, see Computation 75: State, Commonwealth or D.C.). There are four "Commonwealth" states. While we could say IF StateName-t = "Virginia" OR StateName-t = "Kentucky" OR ... it is much easier to bring all of the "Commonwealth" states together into one string and use CONTAINS. What we have, then, is one long string containing all of these state names, and a statement which checks whether StateName-t is contained in that string. If so, it is a "Commonwealth" state. Note that the state names are separated by a tilde "~" in the string. This is not required, and there's nothing special about the tilde. We chose to insert the tilde as a word separator to prevent matches across word boundaries. Take this example:
SET ApprovedSupplies-t TO "notebook~computer paper~stapler~hole punch"
IF ApprovedSupplies-t CONTAINS RequestedItem-t
"Approved"
ELSE
"Denied"
END IF
If the ApprovedSupplies-t were not separated with tildes, a person could request a "notebook computer" and the computation would approve it. For a rather elaborate example of this principle, see Computation 0089: "a" or "an".
A Note on Lettercase: Comparisons are case insensitive for both CONTAINS and "=". In other words, to HotDocs capital and lower case letters are equal. So for a LastName-t value of "Johnson," all of the following are TRUE:
LastName-t = "Johnson"
LastName-t = "JOHNSON"
LastName-t = "johnson"
LastName-t CONTAINS "Johnson"
LastName-t CONTAINS "JOHNSON"
LastName-t CONTAINS "johnson"
If you need to test for case, use Computation 90: Determine Lettercase.
DOES NOT CONTAIN: "CONTAINS" does not have a negative counterpart. To do a DOES NOT CONTAIN analysis, you must place the CONTAINS comparison in parentheses. Either of the following will work:
IF (FullName-t CONTAINS "Johnson") = FALSE ...
IF NOT (FullName-t CONTAINS "Johnson") ...