Introduce a comparison component

[veewee]

This PR introduces a comparison component:

• It provides sensible interfaces for adding a compare and equal function to your own classes:
  • Comparable<T>
  • Equable<T>
• It provide functions for comparing values of the same (base)type:
  • compare(T $a, T $b): Order
  • equal(T $a, T $b): bool
  • not_equal(T $a, T $b): bool
  • less(T $a, T $b): bool
  • less_or_equal(T $a, T $b): bool
  • greater(T $a, T $b): bool
  • greater_or_equal(T $a, T $b): bool
  • sort(T $a, T $b): -1 | 0 | 1 (as shortcut for e.g. vec sorting)
• Comparison of objects that implement Comparable is done based on the internal logic of that specific class. An implementation for the Option component was added.
• Comparison of other types is being done based on PHPs <=> comparison operator
• In case you want to make 2 types incomparable, a user can trhow a IncomparableException
• It's fully typesafe until you end up with mixed. (At that moment, PHPs default compare system kicks in. A user could opt-in on throwing an exception manually in the class that implements Comparable)

Some examples

OPTION

/**
 * @template T
 *
 * @implements Comparison\Comparable<Option<T>>
 * @implements Comparison\Equable<Option<T>>
 */
final class Option implements Comparison\Comparable, Comparison\Equable
{
    /**
     * @param Option<T> $other
     */
    public function compare(mixed $other): Comparison\Order
    {
        $aIsNone = $this->isNone();
        $bIsNone = $other->isNone();

        return match (true) {
            $aIsNone || $bIsNone => Comparison\compare($bIsNone, $aIsNone),
            default => Comparison\compare($this->unwrap(), $other->unwrap())
        };
    }

    /**
     * @param Option<T> $other
     */
    public function equal(mixed $other): bool
    {
        return Comparison\equal($this, $other);
    }
}

COVARIANCE

/**
 * @implements Comparable<Size>
 */
abstract class Size implements Comparable
{
    abstract public function normalizedValue(): int;

    public function compare(mixed $other): Order
    {
        return Comparison\compare($this->normalizedValue(), $other->normalizedValue());
    }
}

class Inches extends Size
{
    public function normalizedValue(): int
    {
        return 1;
    }
}

class Centimeters extends Size
{
    public function normalizedValue(): int
    {
        return 2;
    }
}


function test_covariant_limitations(): Order
{
    $cm = new Centimeters();
    $inch = new Inches();

    return $cm->compare($inch);
}

MIXED

I've tried throwing a lot of different types at the <=> operator and wasn't able to make PHP throw exceptions.
Therefore, any non Comparable object falls back to PHPs internal sorting system.

As long as I cannot find incomparable values, I won't enforce having to deal with IncomparableException from the API.

function test_mixed_limitations(mixed $a, mixed $b): Order
{
    return Comparison\compare($a, $b);
}

(The mutation test issues are solved in #427)

[coveralls]

Pull Request Test Coverage Report for Build 6953644254

• 27 of 27 (100.0%) changed or added relevant lines in 10 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage increased (+0.006%) to 99.005%

---

Totals
Change from base Build 6953598542:	0.006%
Covered Lines:	4179
Relevant Lines:	4221

---

💛 - Coveralls

[veewee]

I was thinking about adding a Equable check here and use the Equable::equals() method if possible. This could work for equal and not equal.
However, it would mean adding additional comparisons for less_or_equal and greater_or_equal. Not sure if it's a good idea and worth adding.