Filter Function

Filter Function

---

Class

Microsoft.VisualBasic.Strings

Syntax

 Filter(   Source   ,   Match   [,   Include   [,   Compare   ]]) 

Source (required; String or Object)

An array containing values to be filtered.

Match (required; String)

The substring of characters to find in the elements of the source array.

Include (optional; Boolean)

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

Compare (optional; CompareMethod enumeration)

A constant whose value can be CompareMethod.Text or CompareMethod.Binary (the default).

Return Value

A 0-based String array of the elements filtered from Source

Description

The Filter function produces an array of matching values from an array of source values that either match or do not match a given filter string.

Put another way, individual elements are copied from a source array to a target array if they either match ( Include is True ) or do not match ( Include is False ) a filter string.A match occurs for an array element if Match is a substring of the array element.

Rules at a Glance

• The default Include value is True .

• The default Compare value is CompareMethod.Binary.

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

• If no matches are found, Filter returns an empty array.

Programming Tips and Gotchas

• Although the Filter function is primarily a string function, you can also filter numeric values. To do this, specify a Source of type Object and populate this array with numeric values. Then assign the string representation of the numeric value you wish to filter on to the Match parameter. Note, though, that the returned string contains string representations of the filtered numbers . For example:

   Dim oArray(  ) As Object = _              {123,222,444,139,1,12,98,908,845,22,3,9,11} Dim sResult(  ) As String = Filter(oArray, "1") 

  In this case, the resulting array contains five elements: 123, 139, 1, 12, and 11.

Example

 Dim sKeys(  ) As String = {"Microsoft Corp.", "AnyMicro Inc.", _                          "Landbor Data", "Micron Co."} Dim sMatch As String = "micro" Dim blnInclude As Boolean = True Dim sFiltered(  ) As String = Filter(sKeys, sMatch, blnInclude, _                             CompareMethod.Text) Dim sElement As String For Each sElement In sFiltered    Console.WriteLine(sElement) Next