CompareTo

Compares the current instance with another object of the same type and returns an integer that indicates whether the current instance precedes, follows, or occurs in the same position in the sort order as the other object.

 Public Function CompareTo(
	  ByRef Value As Variant ) As Long

Parameters

Value

[ByRef] Variant. A value to compare with this instance.

Return Values

Remarks

The CompareTo method is implemented by types whose values can be ordered or sorted. It is called automatically by methods of collection objects, such as CorArray.Sort, to order each member of the array. If a custom class does not implement IComparable, its members cannot be ordered and the sort operation can throw an InvalidOperationException.

This method is only a definition and must be implemented by a specific class or value type to have effect. The meaning of the comparisons specified in the Return Value section ("precedes", "occurs in the same position as", and "follows") depends on the particular implementation.

By definition, any object compares greater than (or follows) Nothing, and two Nothing references compare equal to each other.

The parameter, Value, must be the same type as the class or value type that implements this interface; otherwise, an ArgumentException is thrown.

Exceptions

Exception	Condition
ArgumentException	Value is not of the same type as this instance.

Examples

The following example illustrates the use of CompareTo to compare a Temperature object implementing IComparable with another object. The Temperature object implements CompareTo by simply wrapping a call to the Comparer.Default.Compare method.

There are two modules created for this example. A BAS module containing the Main method and a Class module implementing the IComparable interface.

The following is a Visual Basic Class module named Temperature.

Option Explicit
Implements IComparable

Private mTemperatureF As Double

Public Function CompareTo(ByRef Value As Variant) As Long
    Dim Other As Temperature
    
    On Error GoTo Catch
    Set Other = Value
    
    If Other Is Nothing Then
        CompareTo = 1
    Else
        CompareTo = Comparer.Default.Compare(mTemperatureF, Other.Fahrenheit)
    End If
    Exit Function
    
Catch:
    Throw NewArgumentException("Value is not a Temperature")
End Function

Public Property Get Fahrenheit() As Double
    Fahrenheit = mTemperatureF
End Property

Public Property Let Fahrenheit(ByVal Value As Double)
    mTemperatureF = Value
End Property

Public Property Get Celsius() As Double
    Celsius = (mTemperatureF - 32) * (5# / 9#)
End Property

Public Property Let Celsius(ByVal Value As Double)
    mTemperatureF = (Value * 9# / 5#) + 32
End Property


'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
'   IComparable
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Private Function IComparable_CompareTo(Value As Variant) As Long
    IComparable_CompareTo = CompareTo(Value)
End Function

The following is a Visual Basic BAS module containing Main start-up method.

Public Sub Main()
    Dim Temperatures As New ArrayList
    Dim r As New Random
    Dim i As Long
    Dim Degrees As Double
    Dim Temp As Temperature
    
    For i = 1 To 10
        Degrees = r.NextRange(0, 100)
        Set Temp = New Temperature
        Temp.Fahrenheit = Degrees
        Temperatures.Add Temp
    Next
    
    Temperatures.Sort
    
    For Each Temp In Temperatures
        Debug.Print Temp.Fahrenheit
    Next
End Sub

' This code produces the following output (individual values may vary because they are randomly generated):
'
'    13
'    18
'    31
'    36
'    65
'    65
'    66
'    78
'    92
'    98

See Also

Project CorLib Overview

Class IComparable Overview