Table of Contents

# $EPIC: cofilter.txt,v 1.3 2007/03/02 02:32:04 jnelson Exp $

Synopsis:

$cofilter(<pattern> <var1> <var2>)

Description:

The <pattern> argument is a dword, which is different than most functions.

This function is the complementary operation of copattern

This function is closely related to filter, which returns all of the words in a word list that do not match a wildcard pattern.

All of the co* functions take a wildcard pattern, and two variable names. The variables should contain word lists and each variable should have the same number of words. Each of the words in the first list are matched against the wildcard pattern, and depending on result, the corresponding word in the second list is included or excluded in the return value.

The cofilter function returns all those words in $<var2> that correspond in position to those words in $<var1> that do NOT match the <pattern>.

Parsing ends whenever the shorter of the two word lists runs out of words. Therefore, the two word lists should have the same number of words.

The wildcard <pattern> may be optionally surrounded by double quotes, if the pattern contains spaces. The double quotes are not considered part of the wildcard pattern.

Practical:

When you have two variables, one that contains a list of control data, and another that contains a list of secondary data, and you wish to retrieve the secondary data, but you need to do it based on a query of the control data, you might use this function. One possible use might be if one variable held your friends list, and another held their access levels.

Returns:

The words from $<var2> that correspond to all of the words in $<var1> that are not matched by <pattern>.

Examples:

@ friends = [bob@foo.com tom@bar.com]
@ levels  = [20 10]
$cofilter(*@foo.com friends levels)       returns "10"
$cofilter(*@bar.com friends levels)       returns "20"
$cofilter(*@*.com friends levels)         returns ""      (empty string)
$cofilter(*@*.net friends levels)         returns "10 20"