Filter Function (VB6)

---

Named Arguments

No

Syntax

Filter(SourceArray, FilterString[, Switch[, Compare]])

SourceArray

Use: Required

Data Type: String or Variant

An array containing values to be filtered.

FilterString

Use: Required

Data Type: String

The string of characters to find in the source array.

Switch

Use: Optional

Data Type: Boolean

A Boolean (True or False) value. If True, the default value, Filter includes all matching values in result; if False, Filter excludes all matching values (or, to put it another way, includes all nonmatching values).

Compare

Use: Optional

Type: Constant of vbCompareMethod Enumeration

An optional constant (possible values are vbBinaryCompare, vbTextCompare, vbDatabaseCompare) that indicates the type of string comparison to use. The default value is vbBinaryCompare.

Return Value

A String array of the elements filtered from SourceArray.

Description

Produces an array of matching values from an array of source values that either match or don't match a given filter string. In other words, individual elements are copied from a source array to a target array if they either match or don't match a filter string.

Rules at a Glance

• The default Switch value is True.

• The default Compare value is vbBinaryCompare.

• vbBinaryCompare is case sensitive; that is, Filter matches both character and case. In contrast, vbTextCompare is case insensitive, matching only character regardless of case.

• The returned array is always base 0, regardless of any Option Base setting.

Programming Tips and Gotchas

• The Filter function ignores zero-length strings ("") if SourceArray is a string array and ignores empty elements if SourceArray is a variant array.

• The array you declare to assign the return value of Filter must be a dynamic, single-dimension String array or a variant.

• Although the Filter function is primarily a string function, you can also filter numeric values. To do this, specify a SourceArray of type Variant and populate this array with numeric values. Although FilterString appears to be declared internally as a string parameter, a String, Variant, Long, or Integer can be passed to the function. Note, though, that the returned string contains string representations of the filtered numbers. For example:

  Dim varSource As Variant, varResult As Variant
  Dim strMatch As String
  
  strMatch = CStr(2)
  varSource = Array(10, 20, 30, 21, 22, 32)
  varResult = Filter(varSource, strMatch, True, _
                     vbBinaryCompare)

  
  

  In this case, the resulting array contains four elements: 20, 21, 22, and 32.

• The Filter function is an ideal companion to the Dictionary object. The Dictionary object is a collection-like array of values, each of which is stored with a unique string key. The Keys method of the Dictionary object allows you to produce an array of these Key values, which you can then pass into the Filter function as a rapid method of filtering the members of your Dictionary, as the following example demonstrates.

Example

Dim i As Integer
Dim sKeys()     As Variant
Dim sFiltered() As String
Dim sMatch      As String
Dim blnSwitch   As Boolean       
Dim oDict       As Dictionary

Set oDict = New Dictionary

oDict.Add "Microsoft", "One Microsoft Way"
oDict.Add "AnyMicro Inc", "31 Harbour Drive"
oDict.Add "Landbor Data", "The Plaza"
oDict.Add "Micron Co.", "999 Pleasant View" 

sKeys = oDict.Keys
sMatch = "micro"
blnSwitch = True
'find all keys that contain the string "micro" - any case
sFiltered() = Filter(sKeys, sMatch, blnSwitch, _
      vbTextCompare)
'now iterate through the resulting array
Debug.Print sFiltered(i)&","&_
      oDictItem(sFiltered(i))
    Set oSupplier = Nothing
Next i