Operator Overloading and Equality

[<attributes>] Public [Overloads] Shared [Shadows] [Widening | Narrowing]
    Operator operatorsymbol(operand1 [, operand2]) [As type]
    ...
    Return value
End Operator

Option Strict On

Public Class CatalogItem
    Public ReadOnly Property Title As String

    Public Sub New(title As String)
        Me.Title = title
    End Sub

    Public Shared Operator =(left As CatalogItem, right As CatalogItem) As Boolean
        If left Is Nothing OrElse right Is Nothing Then
            Return left Is right
        End If
        Return left.Title = right.Title
    End Operator

    Public Shared Operator <>(left As CatalogItem, right As CatalogItem) As Boolean
        Return Not (left = right)
    End Operator

    Public Overrides Function Equals(obj As Object) As Boolean
        Dim other = TryCast(obj, CatalogItem)
        Return other IsNot Nothing AndAlso Title = other.Title
    End Function

    Public Overrides Function GetHashCode() As Integer
        Return Title.GetHashCode()
    End Function
End Class

Public Class Book
    Inherits CatalogItem

    Public ReadOnly Property Isbn As String

    Public Sub New(title As String, isbn As String)
        MyBase.New(title)
        Me.Isbn = isbn
    End Sub

    Public Shared Overloads Operator =(left As Book, right As Book) As Boolean
        If left Is Nothing OrElse right Is Nothing Then
            Return left Is right
        End If
        Return left.Isbn = right.Isbn
    End Operator

    Public Shared Overloads Operator <>(left As Book, right As Book) As Boolean
        Return Not (left = right)
    End Operator

    Public Overrides Function Equals(obj As Object) As Boolean
        Dim other = TryCast(obj, Book)
        Return other IsNot Nothing AndAlso Isbn = other.Isbn
    End Function

    Public Overrides Function GetHashCode() As Integer
        Return Isbn.GetHashCode()
    End Function
End Class

Module Program
    Sub Main()
        Dim first As New Book("Refactoring", "9780134757599")
        Dim second As New Book("Refactoring", "9780321127426")   ' same title, other edition

        Console.WriteLine("Book = Book:             " & (first = second))

        Dim itemA As CatalogItem = first
        Dim itemB As CatalogItem = second
        Console.WriteLine("CatalogItem = CatalogItem: " & (itemA = itemB))
        Console.WriteLine("Equals (virtual):          " & itemA.Equals(itemB))
        Console.WriteLine("Book.Equals(Book):         " & first.Equals(second))
        Console.WriteLine("same hash code:            " & (itemA.GetHashCode() = itemB.GetHashCode()))
    End Sub
End Module

Book = Book:             False
CatalogItem = CatalogItem: True
Equals (virtual):          False
Book.Equals(Book):         False
same hash code:            False

Option Strict On

Public Structure Money
    Public ReadOnly Cents As Long

    Public Sub New(cents As Long)
        Me.Cents = cents
    End Sub

    Public Shared Operator +(left As Money, right As Money) As Money
        Console.WriteLine("  Money + Money called")
        Return New Money(left.Cents + right.Cents)
    End Operator

    Public Shared Operator =(left As Money, right As Money) As Boolean
        Console.WriteLine("  Money = Money called")
        Return left.Cents = right.Cents
    End Operator

    Public Shared Operator <>(left As Money, right As Money) As Boolean
        Return left.Cents <> right.Cents
    End Operator

    Public Shared Operator <(left As Money, right As Money) As Boolean
        Return left.Cents < right.Cents
    End Operator

    Public Shared Operator >(left As Money, right As Money) As Boolean
        Return left.Cents > right.Cents
    End Operator

    Public Overrides Function ToString() As String
        Return Cents.ToString() & "c"
    End Function
End Structure

Module Program
    Sub Main()
        Dim a As Money? = New Money(100)
        Dim b As Money? = New Money(250)
        Dim none As Money? = Nothing

        Console.WriteLine("a + b:")
        Dim sum = a + b
        Console.WriteLine("  = " & sum.ToString() & " (HasValue " & sum.HasValue & ")")

        Console.WriteLine("a + none:")
        Dim lifted = a + none
        Console.WriteLine("  HasValue: " & lifted.HasValue)

        Console.WriteLine("a = b:")
        Console.WriteLine("  " & (a = b).ToString())

        Console.WriteLine("a = none (the result is Nothing, not False):")
        Dim eq = (a = none)
        Console.WriteLine("  HasValue: " & eq.HasValue)
        Console.WriteLine("  as a condition: " & If(a = none, "true", "false"))
        Console.WriteLine("  a <> none as a condition: " & If(a <> none, "true", "false"))

        Console.WriteLine("a < b: " & (a < b).ToString())
        Console.WriteLine("a Is Nothing: " & (a Is Nothing))
        Console.WriteLine("none Is Nothing: " & (none Is Nothing))
    End Sub
End Module

a + b:
  Money + Money called
  = 350c (HasValue True)
a + none:
  HasValue: False
a = b:
  Money = Money called
  False
a = none (the result is Nothing, not False):
  HasValue: False
  as a condition: false
  a <> none as a condition: false
a < b: True
a Is Nothing: False
none Is Nothing: True

Option Strict On

Public Structure Day
    Public ReadOnly Number As Integer

    Public Sub New(number As Integer)
        Me.Number = number
    End Sub

    Public Shared Operator +(left As Day, right As Day) As Day
        Return New Day(left.Number + right.Number)
    End Operator

    Public Shared Operator -(left As Day, right As Day) As Day
        Return New Day(left.Number - right.Number)
    End Operator

    Public Shared Operator <=(left As Day, right As Day) As Boolean
        Return left.Number <= right.Number
    End Operator

    Public Shared Operator >=(left As Day, right As Day) As Boolean
        Return left.Number >= right.Number
    End Operator

    Public Shared Operator =(left As Day, right As Day) As Boolean
        Console.WriteLine("  (= called)")
        Return left.Number = right.Number
    End Operator

    Public Shared Operator <>(left As Day, right As Day) As Boolean
        Return left.Number <> right.Number
    End Operator

    Public Shared Operator <(left As Day, right As Day) As Boolean
        Return left.Number < right.Number
    End Operator

    Public Shared Operator >(left As Day, right As Day) As Boolean
        Return left.Number > right.Number
    End Operator

    Public Overrides Function ToString() As String
        Return "day " & Number
    End Function
End Structure

Module Program
    Sub Main()
        ' For ... Next over a user-defined type needs +, -, <= and >=.
        For d As Day = New Day(1) To New Day(7) Step New Day(3)
            Console.WriteLine("For: " & d.ToString())
        Next

        ' Select Case uses = for Case x, and the relational operators for Is and To.
        Dim today As New Day(5)
        Select Case today
            Case New Day(1)
                Console.WriteLine("first day")
            Case Is >= New Day(5)
                Console.WriteLine("day 5 or later")
        End Select
        Select Case today
            Case New Day(1) To New Day(10)
                Console.WriteLine("within the first ten days")
        End Select
    End Sub
End Module

For: day 1
For: day 4
For: day 7
  (= called)
day 5 or later
within the first ten days

Option Strict On

' A three-state check result whose AndAlso / OrElse short-circuit through IsFalse / IsTrue.
Public Structure Check
    Public ReadOnly Name As String
    Public ReadOnly Passed As Boolean

    Public Sub New(name As String, passed As Boolean)
        Me.Name = name
        Me.Passed = passed
    End Sub

    Public Shared Operator IsTrue(c As Check) As Boolean
        Return c.Passed
    End Operator

    Public Shared Operator IsFalse(c As Check) As Boolean
        Return Not c.Passed
    End Operator

    ' AndAlso needs And with this exact shape; OrElse needs Or.
    Public Shared Operator And(left As Check, right As Check) As Check
        Return New Check(left.Name & " and " & right.Name, left.Passed AndAlso right.Passed)
    End Operator

    Public Shared Operator Or(left As Check, right As Check) As Check
        Return New Check(left.Name & " or " & right.Name, left.Passed OrElse right.Passed)
    End Operator

    Public Shared Operator Not(c As Check) As Check
        Return New Check("not " & c.Name, Not c.Passed)
    End Operator

    Public Overrides Function ToString() As String
        Return Name & "=" & Passed
    End Function
End Structure

Module Program
    Function Probe(name As String, passed As Boolean) As Check
        Console.WriteLine("  evaluating " & name)
        Return New Check(name, passed)
    End Function

    Sub Main()
        Console.WriteLine("And (both sides always run):")
        Dim a = Probe("isbn-valid", False) And Probe("not-on-loan", True)
        Console.WriteLine("  -> " & a.ToString())

        Console.WriteLine("AndAlso (right side skipped when the left IsFalse):")
        Dim b = Probe("isbn-valid", False) AndAlso Probe("not-on-loan", True)
        Console.WriteLine("  -> " & b.ToString())

        Console.WriteLine("OrElse (right side skipped when the left IsTrue):")
        Dim c = Probe("member", True) OrElse Probe("staff", False)
        Console.WriteLine("  -> " & c.ToString())

        Console.WriteLine("If condition uses IsTrue:")
        If Probe("fine-paid", True) Then
            Console.WriteLine("  can borrow")
        End If

        Console.WriteLine("Not: " & (Not Probe("overdue", False)).ToString())
    End Sub
End Module

And (both sides always run):
  evaluating isbn-valid
  evaluating not-on-loan
  -> isbn-valid and not-on-loan=False
AndAlso (right side skipped when the left IsFalse):
  evaluating isbn-valid
  -> isbn-valid=False
OrElse (right side skipped when the left IsTrue):
  evaluating member
  -> member=True
If condition uses IsTrue:
  evaluating fine-paid
  can borrow
  evaluating overdue
Not: not overdue=True

Option Strict On

' A set of up to 8 permissions as a value type with logical and shift operators.
Public Structure RightSet
    Private ReadOnly _bits As Byte

    Public Sub New(bits As Byte)
        _bits = bits
    End Sub

    Public Shared ReadOnly Property Borrow As New RightSet(1)
    Public Shared ReadOnly Property Renew As New RightSet(2)
    Public Shared ReadOnly Property Reserve As New RightSet(4)

    Public Shared Operator Or(left As RightSet, right As RightSet) As RightSet
        Return New RightSet(left._bits Or right._bits)
    End Operator

    Public Shared Operator And(left As RightSet, right As RightSet) As RightSet
        Return New RightSet(left._bits And right._bits)
    End Operator

    Public Shared Operator Xor(left As RightSet, right As RightSet) As RightSet
        Return New RightSet(left._bits Xor right._bits)
    End Operator

    Public Shared Operator Not(value As RightSet) As RightSet
        Return New RightSet(CByte((Not value._bits) And &H7))     ' only the 3 defined rights
    End Operator

    Public Shared Operator <<(value As RightSet, count As Integer) As RightSet
        Return New RightSet(CByte((CInt(value._bits) << count) And &H7))
    End Operator

    Public Shared Operator >>(value As RightSet, count As Integer) As RightSet
        Return New RightSet(CByte(CInt(value._bits) >> count))
    End Operator

    ' With IsTrue/IsFalse, "If rights Then" means "at least one right".
    Public Shared Operator IsTrue(value As RightSet) As Boolean
        Return value._bits <> 0
    End Operator

    Public Shared Operator IsFalse(value As RightSet) As Boolean
        Return value._bits = 0
    End Operator

    Public Overrides Function ToString() As String
        Dim names As New List(Of String)
        If (_bits And 1) <> 0 Then names.Add("Borrow")
        If (_bits And 2) <> 0 Then names.Add("Renew")
        If (_bits And 4) <> 0 Then names.Add("Reserve")
        Return If(names.Count = 0, "(none)", String.Join("|", names))
    End Function
End Structure

Module Program
    Sub Main()
        Dim member = RightSet.Borrow Or RightSet.Renew
        Console.WriteLine("member:          " & member.ToString())

        Dim student = member
        student = student And Not RightSet.Renew
        Console.WriteLine("student:         " & student.ToString())

        Dim toggled = member Xor RightSet.Reserve
        Console.WriteLine("member Xor Reserve: " & toggled.ToString())

        Dim shifted = RightSet.Borrow << 1
        Console.WriteLine("Borrow << 1:     " & shifted.ToString())
        Console.WriteLine("Reserve >> 2:    " & (RightSet.Reserve >> 2).ToString())

        member = member Or RightSet.Reserve       ' there is no Or= in Visual Basic
        Console.WriteLine("member Or Reserve: " & member.ToString())

        Dim grown = RightSet.Borrow
        grown <<= 1                               ' <<= and >>= exist and use << and >>
        Console.WriteLine("grown <<= 1:     " & grown.ToString())

        Dim none = RightSet.Borrow And RightSet.Renew
        If none Then
            Console.WriteLine("none is true")
        Else
            Console.WriteLine("none is false (IsFalse)")
        End If

        ' AndAlso / OrElse need And / Or plus IsFalse / IsTrue, all declared above.
        Dim allowed = member AndAlso RightSet.Borrow
        Console.WriteLine("member AndAlso Borrow: " & allowed.ToString())
    End Sub
End Module

member:          Borrow|Renew
student:         Borrow
member Xor Reserve: Borrow|Renew|Reserve
Borrow << 1:     Renew
Reserve >> 2:    Borrow
member Or Reserve: Borrow|Renew|Reserve
grown <<= 1:     Renew
none is false (IsFalse)
member AndAlso Borrow: Borrow

Option Strict On

' A shelf mark such as "QA76.73" is a class letter pair plus a number.
Public Structure ShelfMark
    Public ReadOnly Section As String
    Public ReadOnly Number As String

    Public Sub New(section As String, number As String)
        Me.Section = section
        Me.Number = number
    End Sub

    ' Concatenation: the operator & is VB-only and has its own operator name (op_Concatenate).
    Public Shared Operator &(left As ShelfMark, suffix As String) As ShelfMark
        Return New ShelfMark(left.Section, left.Number & suffix)
    End Operator

    Public Shared Operator &(prefix As String, right As ShelfMark) As ShelfMark
        Return New ShelfMark(prefix & right.Section, right.Number)
    End Operator

    ' Like: the right operand is whatever the operator declares, here a pattern over the text form.
    Public Shared Operator Like(mark As ShelfMark, pattern As String) As Boolean
        Return mark.ToString() Like pattern
    End Operator

    Public Overrides Function ToString() As String
        Return Section & Number
    End Function
End Structure

Module Program
    Sub Main()
        Dim mark As New ShelfMark("QA", "76.73")

        Dim revised = mark & ".A"
        Dim moved = "Z-" & mark
        Console.WriteLine("mark & "".A"" = " & revised.ToString())
        Console.WriteLine("""Z-"" & mark = " & moved.ToString())

        Dim tail = mark
        tail &= ".B"                  ' compound assignment uses the & operator
        Console.WriteLine("mark &= "".B"" = " & tail.ToString())

        Console.WriteLine("mark Like ""QA*"" = " & (mark Like "QA*"))
        Console.WriteLine("mark Like ""Q[A-C]##.##"" = " & (mark Like "Q[A-C]##.##"))
        Console.WriteLine("mark Like ""PS*"" = " & (mark Like "PS*"))

        ' The built-in Like on strings follows Option Compare (Binary here).
        Console.WriteLine("""qa76"" Like ""QA*"" = " & ("qa76" Like "QA*"))
    End Sub
End Module

mark & ".A" = QA76.73.A
"Z-" & mark = Z-QA76.73
mark &= ".B" = QA76.73.B
mark Like "QA*" = True
mark Like "Q[A-C]##.##" = True
mark Like "PS*" = False
"qa76" Like "QA*" = False

Option Strict On

Public Structure Isbn
    Implements IEquatable(Of Isbn)

    Public ReadOnly Property Value As String

    Private Sub New(value As String)
        Me.Value = value
    End Sub

    Public Shared Function TryParse(text As String, ByRef result As Isbn) As Boolean
        Dim digits = New String(If(text, "").Where(AddressOf Char.IsLetterOrDigit).ToArray())
        If digits.Length = 13 AndAlso digits.All(AddressOf Char.IsDigit) AndAlso HasValidCheckDigit(digits) Then
            result = New Isbn(digits)
            Return True
        End If
        Return False
    End Function

    Public Shared Function Parse(text As String) As Isbn
        Dim result As Isbn = Nothing
        If Not TryParse(text, result) Then
            Throw New FormatException($"{text} is not a valid ISBN-13.")
        End If
        Return result
    End Function

    Private Shared Function HasValidCheckDigit(digits As String) As Boolean
        Dim sum = 0
        For i = 0 To 12
            Dim d = AscW(digits(i)) - AscW("0"c)
            sum += If(i Mod 2 = 0, d, d * 3)
        Next
        Return sum Mod 10 = 0
    End Function

    ' Every ISBN converts to String without loss, so the conversion is Widening (implicit).
    Public Shared Widening Operator CType(value As Isbn) As String
        Return value.Value
    End Operator

    ' A String may not be a valid ISBN, so the conversion is Narrowing (explicit, may throw).
    Public Shared Narrowing Operator CType(text As String) As Isbn
        Return Parse(text)
    End Operator

    Public Overloads Function Equals(other As Isbn) As Boolean Implements IEquatable(Of Isbn).Equals
        Return Value = other.Value
    End Function

    Public Overrides Function Equals(obj As Object) As Boolean
        Return TypeOf obj Is Isbn AndAlso Equals(DirectCast(obj, Isbn))
    End Function

    Public Overrides Function GetHashCode() As Integer
        Return If(Value, "").GetHashCode()
    End Function
End Structure

Module Program
    Sub Main()
        Dim isbn As Isbn = CType("978-0-13-468599-1", Isbn)

        ' Widening: no cast needed, not even under Option Strict On.
        Dim text As String = isbn
        Console.WriteLine("widened: " & text)

        ' Overload resolution can pick the user-defined widening conversion.
        Console.Write("Console.WriteLine(isbn): ")
        Console.WriteLine(isbn)
        Console.WriteLine("explicit CStr: " & CStr(isbn))

        ' Narrowing needs CType (the operator runs, so it may throw).
        Try
            Dim bad = CType("not an isbn", Isbn)
            Console.WriteLine(bad)
        Catch ex As FormatException
            Console.WriteLine("CType threw: " & ex.Message)
        End Try

        ' DirectCast and TryCast never call user-defined conversions.
        Dim boxed As Object = text
        Try
            Dim viaDirectCast = DirectCast(boxed, Isbn)
            Console.WriteLine(viaDirectCast)
        Catch ex As InvalidCastException
            Console.WriteLine("DirectCast threw: " & ex.GetType().Name)
        End Try
        Dim viaTryCast = TryCast(boxed, String)
        Console.WriteLine("TryCast to String: " & viaTryCast)

        ' CType on an Object that holds the right type just unboxes.
        Dim fromObject = CType(CObj(isbn), Isbn)
        Console.WriteLine("unboxed equals: " & fromObject.Equals(isbn))
    End Sub
End Module

widened: 9780134685991
Console.WriteLine(isbn): 9780134685991
explicit CStr: 9780134685991
CType threw: not an isbn is not a valid ISBN-13.
DirectCast threw: InvalidCastException
TryCast to String: 9780134685991
unboxed equals: True

Option Strict On

Public Structure Isbn
    Implements IEquatable(Of Isbn)

    Public ReadOnly Property Value As String

    Private Sub New(value As String)
        Me.Value = value
    End Sub

    Public Shared Function TryParse(text As String, ByRef result As Isbn) As Boolean
        Dim digits = New String(If(text, "").Where(AddressOf Char.IsLetterOrDigit).ToArray())
        If digits.Length = 13 AndAlso digits.All(AddressOf Char.IsDigit) AndAlso HasValidCheckDigit(digits) Then
            result = New Isbn(digits)
            Return True
        End If
        Return False
    End Function

    Public Shared Function Parse(text As String) As Isbn
        Dim result As Isbn = Nothing
        If Not TryParse(text, result) Then
            Throw New FormatException($"{text} is not a valid ISBN-13.")
        End If
        Return result
    End Function

    Private Shared Function HasValidCheckDigit(digits As String) As Boolean
        Dim sum = 0
        For i = 0 To 12
            Dim d = AscW(digits(i)) - AscW("0"c)
            sum += If(i Mod 2 = 0, d, d * 3)
        Next
        Return sum Mod 10 = 0
    End Function
    ' IEquatable(Of Isbn): the strongly typed Equals, no boxing in generic collections.
    Public Overloads Function Equals(other As Isbn) As Boolean Implements IEquatable(Of Isbn).Equals
        Return String.Equals(Value, other.Value, StringComparison.Ordinal)
    End Function

    ' Object.Equals: the override that non-generic code and old collections call.
    Public Overrides Function Equals(obj As Object) As Boolean
        Return TypeOf obj Is Isbn AndAlso Equals(DirectCast(obj, Isbn))
    End Function

    ' Equal values must give equal hash codes; use only the fields that Equals uses.
    Public Overrides Function GetHashCode() As Integer
        Return If(Value, "").GetHashCode()
    End Function

    Public Overrides Function ToString() As String
        Return If(Value, "(no ISBN)")
    End Function

    Public Shared Operator =(left As Isbn, right As Isbn) As Boolean
        Return left.Equals(right)
    End Operator

    Public Shared Operator <>(left As Isbn, right As Isbn) As Boolean
        Return Not left.Equals(right)
    End Operator
End Structure

Module Program
    Sub Main()
        Dim a = Isbn.Parse("978-0-13-468599-1")
        Dim b = Isbn.Parse("9780134685991")
        Dim c = Isbn.Parse("978-0-13-475759-9")
        Dim unset As Isbn = Nothing

        Console.WriteLine("a = b: " & (a = b) & ", a <> c: " & (a <> c))
        Console.WriteLine("a.Equals(b): " & a.Equals(b))
        Console.WriteLine("a.Equals(CObj(b)): " & a.Equals(CObj(b)))
        Console.WriteLine("a.Equals(""9780134685991""): " & a.Equals("9780134685991"))
        Console.WriteLine("a.Equals(Nothing): " & a.Equals(Nothing))
        Console.WriteLine("unset = unset: " & (unset = unset) & " (prints " & unset.ToString() & ")")
        Console.WriteLine("a hash = b hash: " & (a.GetHashCode() = b.GetHashCode()))

        Dim seen As New HashSet(Of Isbn) From {a, b, c}
        Console.WriteLine("HashSet count: " & seen.Count)

        Dim titles As New Dictionary(Of Isbn, String)
        titles(a) = "first entry"
        titles(b) = "second entry"
        Console.WriteLine("Dictionary count: " & titles.Count & ", value: " & titles(a))

        Dim list As New List(Of Isbn) From {a, c}
        Console.WriteLine("List.Contains(b): " & list.Contains(b))
        Console.WriteLine("List.IndexOf(c): " & list.IndexOf(c))
        Console.WriteLine("Distinct count: " & New Isbn() {a, b, c, a}.Distinct().Count())
    End Sub
End Module

a = b: True, a <> c: True
a.Equals(b): True
a.Equals(CObj(b)): True
a.Equals("9780134685991"): False
a.Equals(Nothing): False
unset = unset: True (prints (no ISBN))
a hash = b hash: True
HashSet count: 2
Dictionary count: 1, value: second entry
List.Contains(b): True
List.IndexOf(c): 1
Distinct count: 2

Option Strict On

Public NotInheritable Class Issue
    Implements IComparable(Of Issue), IComparable, IEquatable(Of Issue)

    Public ReadOnly Property Year As Integer
    Public ReadOnly Property Number As Integer

    Public Sub New(year As Integer, number As Integer)
        Me.Year = year
        Me.Number = number
    End Sub

    ' Convention: any instance sorts after Nothing; two Nothings are equal.
    Public Function CompareTo(other As Issue) As Integer Implements IComparable(Of Issue).CompareTo
        If other Is Nothing Then Return 1
        Dim byYear = Year.CompareTo(other.Year)
        Return If(byYear <> 0, byYear, Number.CompareTo(other.Number))
    End Function

    ' The non-generic interface is used by ArrayList, Array.Sort(Array) and old APIs.
    Private Function CompareToObject(obj As Object) As Integer Implements IComparable.CompareTo
        If obj Is Nothing Then Return 1
        Dim other = TryCast(obj, Issue)
        If other Is Nothing Then
            Throw New ArgumentException("Object must be of type Issue.", NameOf(obj))
        End If
        Return CompareTo(other)
    End Function

    Public Overloads Function Equals(other As Issue) As Boolean Implements IEquatable(Of Issue).Equals
        Return other IsNot Nothing AndAlso CompareTo(other) = 0
    End Function

    Public Overrides Function Equals(obj As Object) As Boolean
        Return Equals(TryCast(obj, Issue))
    End Function

    Public Overrides Function GetHashCode() As Integer
        Return HashCode.Combine(Year, Number)
    End Function

    Public Overrides Function ToString() As String
        Return Year & "/" & Number
    End Function

    ' The operators handle Nothing through a shared helper so that the rules cannot drift.
    Private Shared Function Compare(left As Issue, right As Issue) As Integer
        If left Is Nothing Then Return If(right Is Nothing, 0, -1)
        Return left.CompareTo(right)
    End Function

    Public Shared Operator <(left As Issue, right As Issue) As Boolean
        Return Compare(left, right) < 0
    End Operator

    Public Shared Operator >(left As Issue, right As Issue) As Boolean
        Return Compare(left, right) > 0
    End Operator

    Public Shared Operator <=(left As Issue, right As Issue) As Boolean
        Return Compare(left, right) <= 0
    End Operator

    Public Shared Operator >=(left As Issue, right As Issue) As Boolean
        Return Compare(left, right) >= 0
    End Operator

    Public Shared Operator =(left As Issue, right As Issue) As Boolean
        Return Compare(left, right) = 0
    End Operator

    Public Shared Operator <>(left As Issue, right As Issue) As Boolean
        Return Compare(left, right) <> 0
    End Operator
End Class

Module Program
    Sub Main()
        Dim issues As New List(Of Issue) From {
            New Issue(2025, 11), New Issue(2024, 3), Nothing, New Issue(2025, 2), New Issue(2024, 3)
        }
        issues.Sort()
        Console.WriteLine("List.Sort:        " & String.Join(" ", issues.Select(Function(i) If(i Is Nothing, "(none)", i.ToString()))))

        Dim distinct As New SortedSet(Of Issue)(issues.Where(Function(i) i IsNot Nothing))
        Console.WriteLine("SortedSet count:  " & distinct.Count & " (duplicates collapse via CompareTo)")
        Console.WriteLine("Min / Max:        " & distinct.Min.ToString() & " / " & distinct.Max.ToString())

        Dim a As New Issue(2024, 3)
        Dim b As New Issue(2025, 2)
        Console.WriteLine("a < b: " & (a < b) & ", a >= b: " & (a >= b) & ", a = New Issue(2024, 3): " & (a = New Issue(2024, 3)))
        Console.WriteLine("Nothing < a: " & (Nothing < a))

        ' The non-generic interface rejects other types.
        Dim legacy As IComparable = a
        Try
            legacy.CompareTo("2024/3")
        Catch ex As ArgumentException
            Console.WriteLine("IComparable.CompareTo(String): " & ex.Message)
        End Try

        ' Enumerable.OrderBy, Max and Min use Comparer(Of Issue).Default, i.e. IComparable(Of Issue).
        Dim newest = New Issue() {a, b}.Max()
        Console.WriteLine("Enumerable.Max:   " & newest.ToString())
    End Sub
End Module

List.Sort:        (none) 2024/3 2024/3 2025/2 2025/11
SortedSet count:  3 (duplicates collapse via CompareTo)
Min / Max:        2024/3 / 2025/11
a < b: True, a >= b: False, a = New Issue(2024, 3): True
Nothing < a: True
IComparable.CompareTo(String): Object must be of type Issue. (Parameter 'obj')
Enumerable.Max:   2025/2

Option Strict On

Public Class Book
    Public ReadOnly Property Title As String
    Public ReadOnly Property Year As Integer

    Public Sub New(title As String, year As Integer)
        Me.Title = title
        Me.Year = year
    End Sub

    Public Overrides Function ToString() As String
        Return Title & " (" & Year & ")"
    End Function
End Class

' A comparer is a separate object: one type can have many orderings.
Public NotInheritable Class ByTitleComparer
    Implements IComparer(Of Book)

    Public Function Compare(x As Book, y As Book) As Integer Implements IComparer(Of Book).Compare
        If x Is y Then Return 0
        If x Is Nothing Then Return -1
        If y Is Nothing Then Return 1
        Return StringComparer.OrdinalIgnoreCase.Compare(x.Title, y.Title)
    End Function
End Class

Public NotInheritable Class ByTitleEquality
    Implements IEqualityComparer(Of Book)

    Public Overloads Function Equals(x As Book, y As Book) As Boolean Implements IEqualityComparer(Of Book).Equals
        If x Is y Then Return True
        If x Is Nothing OrElse y Is Nothing Then Return False
        Return StringComparer.OrdinalIgnoreCase.Equals(x.Title, y.Title)
    End Function

    Public Overloads Function GetHashCode(obj As Book) As Integer Implements IEqualityComparer(Of Book).GetHashCode
        Return StringComparer.OrdinalIgnoreCase.GetHashCode(obj.Title)
    End Function
End Class

Module Program
    Sub Main()
        Dim books As New List(Of Book) From {
            New Book("refactoring", 1999), New Book("Domain-Driven Design", 2003),
            New Book("Refactoring", 2018), New Book("Clean Code", 2008)
        }

        books.Sort(New ByTitleComparer())
        Console.WriteLine("IComparer:        " & String.Join("; ", books))

        books.Sort(Function(x, y) y.Year.CompareTo(x.Year))
        Console.WriteLine("Comparison:       " & String.Join("; ", books))

        Dim byYear = Comparer(Of Book).Create(Function(x, y) x.Year.CompareTo(y.Year))
        Console.WriteLine("Comparer.Create:  " & String.Join("; ", books.OrderBy(Function(b) b, byYear)))

        Console.WriteLine("OrderBy/ThenBy:   " & String.Join("; ", books.OrderBy(Function(b) b.Title, StringComparer.OrdinalIgnoreCase).ThenByDescending(Function(b) b.Year)))

        Console.WriteLine("Distinct by title: " & books.Distinct(New ByTitleEquality()).Count() & " of " & books.Count)

        Dim index As New Dictionary(Of Book, Integer)(New ByTitleEquality())
        For Each b In books
            index(b) = b.Year
        Next
        Console.WriteLine("Dictionary keys:  " & index.Count)

        ' Default equality for a class without overrides is reference equality.
        Console.WriteLine("default Distinct:  " & books.Distinct().Count())

        Dim names As New HashSet(Of String)(StringComparer.OrdinalIgnoreCase) From {"Ana", "ANA", "Luis"}
        Console.WriteLine("HashSet(Of String) with a comparer: " & names.Count)
    End Sub
End Module

IComparer:        Clean Code (2008); Domain-Driven Design (2003); refactoring (1999); Refactoring (2018)
Comparison:       Refactoring (2018); Clean Code (2008); Domain-Driven Design (2003); refactoring (1999)
Comparer.Create:  refactoring (1999); Domain-Driven Design (2003); Clean Code (2008); Refactoring (2018)
OrderBy/ThenBy:   Clean Code (2008); Domain-Driven Design (2003); Refactoring (2018); refactoring (1999)
Distinct by title: 3 of 4
Dictionary keys:  3
default Distinct:  4
HashSet(Of String) with a comparer: 2

Option Strict On

Imports System.Numerics

Module Program
    ' Compiles in C# 11 and later; Visual Basic cannot use the operator through the constraint.
    Function Total(Of T As IAdditionOperators(Of T, T, T))(a As T, b As T) As T
        Return a + b
    End Function

    Sub Main()
        Console.WriteLine(Total(1, 2))
    End Sub
End Module

Program.vb(8,16): error BC30452: Operator '+' is not defined for types 'T' and 'T'.

Option Strict On

Imports System.Numerics

Public Structure Meters
    Implements IAdditionOperators(Of Meters, Meters, Meters)

    Public ReadOnly Value As Double

    Public Sub New(value As Double)
        Me.Value = value
    End Sub

    Public Shared Operator +(left As Meters, right As Meters) As Meters
        Return New Meters(left.Value + right.Value)
    End Operator
End Structure

Module Program
    Sub Main()
        Console.WriteLine((New Meters(1) + New Meters(2)).Value)
    End Sub
End Module

Program.vb(6,16): error BC37315: Structure 'Meters' cannot implement interface 'IAdditionOperators(Of Meters, Meters, Meters)' because it contains shared abstract or virtual 'Function op_Addition(left As Meters, right As Meters) As Meters'.
Program.vb(6,16): error BC37315: Structure 'Meters' cannot implement interface 'IAdditionOperators(Of Meters, Meters, Meters)' because it contains shared abstract or virtual 'Function op_CheckedAddition(left As Meters, right As Meters) As Meters'.

Option Strict On

Public Structure Meters
    Public ReadOnly Value As Double

    Public Sub New(value As Double)
        Me.Value = value
    End Sub

    Public Shared Operator +(left As Meters, right As Meters) As Meters
        Return New Meters(left.Value + right.Value)
    End Operator
End Structure

Module Program
    ' Visual Basic cannot call "a + b" through a generic-math constraint,
    ' so pass the operation in as a delegate.
    Function Total(Of T)(items As IEnumerable(Of T), zero As T, add As Func(Of T, T, T)) As T
        Dim result = zero
        For Each item In items
            result = add(result, item)
        Next
        Return result
    End Function

    Sub Main()
        ' The BCL's own generic-math based Sum works fine with the built-in numeric types.
        Console.WriteLine(Enumerable.Sum(New Integer() {1, 2, 3}))
        Console.WriteLine(New Double() {1.5, 2}.Sum())

        Dim lengths = {New Meters(1), New Meters(2.5), New Meters(3)}
        Dim sum = Total(lengths, New Meters(0), Function(a, b) a + b)
        Console.WriteLine(sum.Value)
        Console.WriteLine(lengths.Aggregate(Function(a, b) a + b).Value)
    End Sub
End Module

6
3.5
6.5
6.5