The CONTAINS function returns TRUE if a certain value is found in a given list, FALSE if not.
This function takes two pieces of input: a List, and a value of any type that might be contained within that list. It then outputs a boolean indicating whether the list contains said value. (TRUE means it does, FALSE means it doesn't.)
Declaration
CONTAINS(list_of_values, value_to_find) -> contained
Parameters
list_of_values (required, type: list)
A list containing any number of items. These items can be of any type and do not need to be the same type as each other.
value_to_find (required, type: any)
A value to be found among the items in the provided list.
Return Values
contained (type: boolean)
A boolean value indicating whether list_of_values contains a certain item. TRUE means it does, FALSE means it doesn't.
Examples
The following example searches for the number 3 within the list [1, 2, 3]. Because 3 is, in fact, contained within the list [1, 2, 3], it outputs TRUE:
CONTAINS([1, 2, 3], 3) -> TRUE
The above example hardcoded list_of_values, but this doesn't need to be the case. (For that matter, value_to_find doesn't need to be hardcoded either, though for the sake of clarity, it is in all of these examples.) Moving forward, assume all formulas have access to the following list:
example_list = [1, "hello", "this is a string, John", [1, 2, 3], {"name":"John"}]
Note that example_list consists of myriad types of values. The first value is a number (1), the second and third values are strings ("hello" and "this is a string, John"), the forth value is a list ( [1, 2, 3] ), and the fifth value is an object ( {"name" : "John"} ). This list was chosen not because it is particularly likely to be encountered it in the wild, but to emphasize that the values listed in list_of_values do not at all need to be same type as each other.
This next example searches for the string "hello" in the variable example_list. Because example_list contains the string "hello", it outputs TRUE:
CONTAINS(example_list, "hello") -> TRUE
This third example searches for the string "John" in the variable example_list. Because example_list does not contain the string "John" – only the object {"name": "John"} and the string "this is a string, John" – it outputs FALSE:
CONTAINS(example_list, "John") -> FALSE
Note that a list containing the string "this is a string, John" as well as the object {"name": "John"} does not count as a list containing the string "John". This highlights an important subtlety regarding what counts as a "value" within a "list." The CONTAINS function compares value_to_find with only the complete items within list_of_values, not any of their subcomponents.
"John" can be considered a subcomponent of the object {"name": "John"}, and while example_list does not contain "John", it does contain {"name": "John"}. When the last example searches for the object {"name": "John"} within the variable example_list, it outputs TRUE:
CONTAINS(example_list, {"name": "John") -> TRUE