cArray: FindIndex

FindIndex

Finds the index of the first array element that matches the criteria specified by the callback function.



 Public Function FindIndex(
	  ByRef Arr As Variant,
	  ByVal AddressOfMatch As Long,
	  Optional ByRef Index As Variant,
	  Optional ByRef Count As Variant ) As Long

Parameters

Arr
[ByRef] Variant. The array to be searched.
AddressOfMatch
[ByVal] Long. The address of the callback function used to match the array elements.
Index
[ByRef] Optional. Variant. The starting element of the array to beging the matching process.
Count
[ByRef] Optional. Variant. The number of elements to include in the array search.

Return Values

Long -  The index of the matched element, or LowerBound - 1 if none is found.

Remarks

The function signature for the callback has a specific format.

 Public Function FindIndexCallback(ByRef x As [Array Datatype]) As Boolean
     ' return True if x matches your criteria.
 End Sub
 
The [Array Datatype] must be replaced with the datatype of the array. If the array is an array of Variants, then [Array Datatype] would be a Variant, not any specific sub-type within the variants of the array.

The callback method signature needs to have 1 parameter that is of aByRef definition for the the datatype the same as the array. The callbackfunction must return a Boolean value indicating if the passed-by-refelement matches the criteria of the matching routine.

It is extremely important to define the callback method correctly. Ifthe method is incorrect, the application may crash.

Example

This example demonstrates some of the Findmethods and how to define a Callback method that the Find methodsrely on in finding array elements that match a criteria. The criteria logicis defined by the developer. The callback function is used to check if aspecific array element meets the criteria being searched for.

In the examples below, a String array is searched using variouscriteria. The two callback functions (MatchGreetings, MatchNonGreetings) aredefined with 1 parameter of a ByRef String and returns a Boolean. If the array datatype is a Long, the the callback will be defined as aByRef Long.

None of the values should be changed during the search.

Private Sub Main()    FindFirstGreeting    FindLastGreeting    FindAllGreetings    FindAllNonGreetingsEnd Sub' Searches from the beginning of the arry until the first'' successful match from the MatchGreetings function,'' returning the index the element was found at.Private Sub FindFirstGreeting()    Debug.Print cArray.FindIndex(GetStrings, AddressOf MatchGreetings)End Sub'' Searches from the end of the array until the first'' successful match from the MatchGreetings function,'' returning the index the element was found at.Private Sub FindLastGreeting()    Debug.Print cArray.FindLastIndex(GetStrings, AddressOf MatchGreetings)End Sub'' Finds all of the array elements that pass the criteria of the'' MatchGreetings function. The found elements are placed'' into a new array of the same datatype as the original array'' and returned.Private Sub FindAllGreetings()    Dim a() As String    a = cArray.FindAll(GetStrings, AddressOf MatchGreetings)    Debug.Print a(0), a(1)End Sub'' Finds all of the array elements that pass the criteria of the'' MatchNonGreetings function. The found elements are placed'' into a new array of the same datatype as the original array'' and returned.Private Sub FindAllNonGreetings()    Dim i As Long    Dim a() As String        a = cArray.FindAll(GetStrings, AddressOf MatchNonGreetings)    For i = 0 To UBound(a)        Debug.Print a(i),    Next iEnd Sub'' Create a sample array of strings to search.Private Function GetStrings() As String()    GetStrings = cArray.NewArray(ciString, "One", "Two", "Hello", "Four", "Hi", "Six")End Function'' Callback method used to match a string element from'' the array to the possible greetings we are searching for.'' The method signature should be a ByRef of the datatype'' of the specific array being searched.Public Function MatchGreetings(ByRef s As String) As Boolean    MatchGreetings = ((s = "Hello") Or (s = "Hi"))End Function'' Callback method used to match a string element from'' the array to determine that we have matched against a non-greeting.'' The method signature should be a ByRef of the datatype'' of the specific array being searched.Public Function MatchNonGreetings(ByRef s As String) As Boolean    MatchNonGreetings = Not ((s = "Hello") Or (s = "Hi"))End Function'' this code produces the following output.'''' 2'' 4'' Hello         Hi'' One           Two           Four          Six

See Also

Project VBCorLib Overview Class cArray Overview cArray Properties cArray Methods FindAll FindLast