CorArray: SortKey

SortKey

Sorts an entire array based on an array of keys. An optionally supplied comparer object can be used to compare special elements, such as userdefined values.



 Public Sub SortKey(
	  ByRef Keys As Variant,
	  ByRef Items As Variant,
	  Optional ByRef Comparer As Variant )

Parameters

Keys
[ByRef] Variant. An array the sorting is based on.
Items
[ByRef] Variant. An array that is sorted based on the sorting of keys.
Comparer
[ByRef] Optional. Variant. (Optional) An IComparer object or address of a comparer callback function.

Remarks

The Comparer parameter can be an IComparer interface or a callback address to a compare function using the AddressOf method. The callback method signature is defined as follows:

 Public Function SortCallback(ByRef x As <Type>, ByRef y As <Type>) As Long
     ' return less than zero if x is less than y.
     ' return greater than zero if x is greater than y.
     ' return zero if x equals y.
 End Function
 
The <Type> the type of element of the array. If the array is an array of Variants, then <Type> would be a Variant, not any specific sub-type within the variant elements of the array.

Examples

This example demonstrates how an array can be sorted by using another array to determine the sort order for the original. This demonstration uses an array of type vbLong as the keys to sort the main Values array. Even though Values is a vbString type array, it will follow the Keys array when being sorted. Once the array is sorted using the Keys vbLong array, the Values array is displayed to show how the array did not sort using string text compare. The Values array is then sorted again using the standard sort method on the Values vbString type array and re-displayed. This will show the difference between sorting using a Keys array of a different type to sort an original array and how the original array itself would be sorted on its own.

Private Sub Main()
    Dim Values(14) As String
    Dim Keys(14) As Long
    
    ' Fill both arrays with random values.
    FillKeysAndValues Keys, Values
    
    ' Display the current order of the values array.
    DisplayValues "Unsorted Values Array.", Values
    
    ' Sort the values array using the keys array
    ' to determine the sort order.
    CorArray.SortKey Keys, Values
    
    ' Display the new sorted values array.
    ' The values are sorted numerically because the
    ' keys array is a numeric array.
    DisplayValues t("\nSorted Values array using Keys array for sort order."), Values
    
    ' Re-sort the values array by itself.
    ' The values are sorted as strings.
    CorArray.Sort Values
    
    ' Display the re-sorted values array, showing
    ' the how string comparing affects sort order.
    DisplayValues t("\nRe-sorted Values array using standard sorting with String compares."), Values
End Sub

' Fill Keys and Values array.
Private Sub FillKeysAndValues(ByRef Keys() As Long, ByRef Values() As String)
    Dim i As Long
    
    Rnd -13
    For i = LBound(Keys) To UBound(Keys)
        Keys(i) = Rnd * i
        Values(i) = "Value " & Keys(i)
    Next i
End Sub

' Display Array
Private Sub DisplayValues(ByVal Title As String, ByRef Values() As String)
    Dim i As Long
    
    Debug.Print Title
    For i = LBound(Values) To UBound(Values)
        Debug.Print CorString.Format("  Values({0}) = {1}", i, Values(i))
    Next i
End Sub

' This code produces the following output.
'
'    Unsorted Values Array.
'      Values(0) = Value 0
'      Values(1) = Value 0
'      Values(2) = Value 0
'      Values(3) = Value 1
'      Values(4) = Value 4
'      Values(5) = Value 3
'      Values(6) = Value 1
'      Values(7) = Value 0
'      Values(8) = Value 3
'      Values(9) = Value 8
'      Values(10) = Value 8
'      Values(11) = Value 8
'      Values(12) = Value 10
'      Values(13) = Value 10
'      Values(14) = Value 6
'
'    Sorted Values array using Keys array for sort order.
'      Values(0) = Value 0
'      Values(1) = Value 0
'      Values(2) = Value 0
'      Values(3) = Value 0
'      Values(4) = Value 1
'      Values(5) = Value 1
'      Values(6) = Value 3
'      Values(7) = Value 3
'      Values(8) = Value 4
'      Values(9) = Value 6
'      Values(10) = Value 8
'      Values(11) = Value 8
'      Values(12) = Value 8
'      Values(13) = Value 10
'      Values(14) = Value 10
'
'    Re-sorted Values array using standard sorting with String compares.
'      Values(0) = Value 0
'      Values(1) = Value 0
'      Values(2) = Value 0
'      Values(3) = Value 0
'      Values(4) = Value 1
'      Values(5) = Value 1
'      Values(6) = Value 10
'      Values(7) = Value 10
'      Values(8) = Value 3
'      Values(9) = Value 3
'      Values(10) = Value 4
'      Values(11) = Value 6
'      Values(12) = Value 8
'      Values(13) = Value 8
'      Values(14) = Value 8
As you can see, the Values string array sorted as if numeric when using the Keys array to be sorted by. When it was sorted alone, it was sorted as a string array and the Value 10' appears in its string compared index.

See Also

Project CorLib Overview

Class CorArray Overview

IComparer

Sort

SortEx

SortKeyEx