@Keywords (Formula Language)

Given two text lists, returns only those items from the second list that are found in the first list.

Syntax

@Keywords( textList1 ; textList2 ) or @Keywords( textList1 ; textList2 ; separator )

Parameters

textList1

Text list. A list of items.

textList2

Text list. A list of items that you want to compare to textList1.

separator

Text. One or more characters to be used as delimiters between words. @Keywords considers each character (not the combination of multiple characters) to be a delimiter. For example, defining separator as ". ," (period, space, comma) tells the function to separate the text at each period, space, and comma into separate words.

When you do not specify a separator, the following word delimiters are used by default:

?. ,!;:[](){}"<> (question mark, period, space, comma, exclamation point, semicolon, colon, (brackets, parentheses, braces, quotation mark, and angle brackets)

A null separator, represented by an empty string (""), tells the function to use no delimiters.

Return value

resultTextList

Text list. When a separator is in effect, either by default or specification, @Keywords parses textList1 into words delimited by the separator and returns any word that exactly matches a keyword in textList2. When no separator is in effect (when you specify a null separator), @Keywords returns any sequence of characters in textList1 that matches a keyword specified in textList2.

Note: With Release 6, the order of the words returned in resultTextList match the order of textList1. Prior to Release 6, the order of the words returned in resultTextList matched the order of textList2. To retain the pre-Release 6 ordering of the resutlTextList, prepend the formula with another @Keywords function as follows:
@Keywords(textList2;@Keywords(textList1;textList2))

Usage

When a keyword that you specify in textList2 is the very first word in the string you are searching AND you specify separators, @Keywords returns null. To prevent this behavior, prepend textList1 with one of the separators. For example, if you want to find the keyword, Sally, in a text list that contains employee names and positions, use the following formula:

@Keywords(" " + " ,Mary Halen, Director of Sales":" ,Sally Hall, VP of Marketing": " ,Joe Halzy, Order entry"; "Sally"; " ,")

This formula returns Sally. Note that one of the formula's separators, the space(" "), is prepended to textList1. This behavior does not occur if you accept the default separators or specify a null separator.

If one of the strings in textList2 contains any of the default delimiters, @Keywords will not return it. To search for Harvard University, for example, add a null separator to the formula. This tells @Keywords to search for any sequence of characters. If you do not specify a separator, you allow the default delimiters to act. @Keywords does not return Harvard University because when it parses textList1, it breaks the phrase into two separate words, Harvard and University, where it finds the space, which is a default delimiter.

When using the quotation mark separator ("), precede it with a backslash (\) to indicate that the quotation mark is a text constant.

This function is case-sensitive; you must standardize the case of textList1 and textList2 if you want case to be ignored (use @LowerCase, @ProperCase or @UpperCase).

Examples

  1. This formula returns Harvard;Yale.
    @Keywords(@ProperCase("EPA Head speaks at Harvard and yale":"The UCLA Chancellor Retires":"Ohio State wins big game":"Reed and University of Oregon share research facilities");"Harvard":"Brown":"Stanford":"Yale":"Vassar":"UCLA")
  2. This formula returns "", a null string.
    @Keywords("EPA Head speaks at Harvard,Yale":"UCLA Chancellor Retires":"Ohio State wins big game":"Reed and University of Oregon share research facilities";"harvard":"brown":"stanford":"vassar":"ucla")
  3. This formula returns Harvard;Yale. It searches textList1 for the textList2 keywords that follow either a comma or a space.
    @Keywords("EPA Head speaks at Harvard, Yale hosts her next month":"UCLA Chancellor Retires":"Ohio State wins big game":"Reed and University of Oregon share research facilities";"Harvard":"Brown":"Stanford":"Yale":"UCLA";", ")
  4. This formula returns Harvard;Yale University;UCLA.
    @Keywords("EPA Head speaks at Harvard, Yale University hosts her next month":"UCLA Chancellor Retires":"Ohio State wins big game":"Reed and University of Oregon share research facilities";"Harvard":"Brown":"Stanford":"Yale University":"UCLA"; "")
  5. This formula returns Mary Jones. when used in the "Result" field on a form that also contains the "Applicants" field, which has a default value of: ",Mary Jones.":",John Chen.":",Miguel Sanchez.".
    @Keywords(Applicants;"Mary Jones.";",")
  6. This formula returns Mary Jones. when used in the "Result" field on a form that also contains the "Applicants" field, which has a default value of: ",Mary Jones., who works downtown, is being interviewed on Friday.":",John Chen.":",Miguel Sanchez.".
    @Keywords("," + Applicants;"Mary Jones.";",")
  7. This formula returns book.
    @Keywords("<booklist> XML tag that represents a list of our books.":"<book> XML tag that represents a book.":"<sale> XML tag that represents the sale price of a book.";"book";"<>")
  8. If list1 contains "guava":"eggplant":"date":"cherry":"banana":"apple" and list2 contains "apple":"banana":"date," this formula, when triggered from a Release 6 client, returns date, banana, apple. When triggered from a pre-Release 6 client, it returns apple, banana, date.
    @Keywords(list1;list2)
  9. If list1 and list2 contain the same text lists as in the previous example, this formula returns apple, banana, date from all versions of Notes®.
    @Keywords(list2;@Keywords(list1;list2))