Comparison

Interfaces and helper trait for comparing objects. Comparator utility class for sort and filter applications.

Current version supports PHP ^7.1|^8.0.

Installation

Install with Composer;

composer require phrity/comparison

The Equalable interface

Interface synopsis

interface Phrity\Comparison\Equalable {

    /* Abstract methods */
    abstract public equals(mixed $compare_with) : bool
}

Examples

// $a must implement Equalable, $b can be anything
$a->equals($b); // True if $a is equal to $b

The Comparable interface

Extends Equalable interface.

Interface synopsis

interface Phrity\Comparison\Comparable
    extends Phrity\Comparison\Equalable {

    /* Abstract methods */
    abstract public greaterThan(mixed $compare_with) : bool
    abstract public greaterThanOrEqual(mixed $compare_with) : bool
    abstract public lessThan(mixed $compare_with) : bool
    abstract public lessThanOrEqual(mixed $compare_with) : bool
    abstract public compare(mixed $compare_with) : int

    /* Inherited from Equalable */
    abstract public equals(mixed $compare_with) : bool
}

Examples

// $a must implement Comparable, $b can be anything
$a->greaterThan($b);        // True if $a is greater than $b
$a->greaterThanOrEqual($b); // True if $a is greater than or equal to $b
$a->lessThan($b);           // True if $a is less than $b
$a->lessThanOrEqual($b);    // True if $a is less than or equal to $b

//  0 if $a is equal to $b
// -1 if $a is less than $b
//  1 if $a is greater than $b
$a->compare($b);

The ComparisonTrait trait

A class using this trait only has to implement the compare() method. Enables all other methods in Equalable and Comparable intefaces.

Trait synopsis

trait Phrity\Comparison\ComparisonTrait
    implements Phrity\Comparison\Comparable {

    /* Methods */
    public equals(mixed $compare_with) : bool
    public greaterThan(mixed $compare_with) : bool
    public greaterThanOrEqual(mixed $compare_with) : bool
    public lessThan(mixed $compare_with) : bool
    public lessThanOrEqual(mixed $compare_with) : bool

    /* Inherited from Comparable */
    abstract public compare(mixed $compare_with) : int
}

The Comparator class

Utility class to sort and filter array objects that implement the Comparable interface.

Class synopsis

class Phrity\Comparison\Comparator {

    /* Methods */
    public __construct(array $comparables = null)
    public sort(array $comparables = null) : array
    public rsort(array $comparables = null) : array
    public equals(Comparable $condition, array $comparables = null) : array
    public greaterThan(Comparable $condition, array $comparables = null) : array
    public greaterThanOrEqual(Comparable $condition, array $comparables = null) : array
    public lessThan(Comparable $condition, array $comparables = null) : array
    public lessThanOrEqual(Comparable $condition, array $comparables = null) : array
    public min(array $comparables = null) : Comparable
    public max(array $comparables = null) : Comparable
}

Examples

$comparables = [$v2, $v1, $v4, $v3];
$condition = $v3;
$comparator = new Comparator();

// Sort and reverse sort array of Comparable
$comparator->sort($comparables); // [$v1, $v2, $v3, $v4]
$comparator->rsort($comparables); // [$v4, $v3, $v2, $v1]

// Filter array of Comparable using a Comparable as condition
$comparator->equals($condition, $comparables); // [$v3]
$comparator->greaterThan($condition, $comparables); // [$v4]
$comparator->greaterThanOrEqual($condition, $comparables); // [$v4, $v3]
$comparator->lessThan($condition, $comparables); // [$v2, $v1]
$comparator->lessThanOrEqual($condition, $comparables); // [$v2, $v1, $v3]

// Select min/max instance
$comparator->min($comparables); // $v1
$comparator->max($comparables); // $v4

// Can also "store" comparables for re-use in multiple operations
$comparables = [$v2, $v1, $v4, $v3];
$comparator = new Comparator($comparables);
$comparator->sort(); // [$v1, $v2, $v3, $v4]
$comparator->equals($condition); // [$v3]
$comparator->min(); // $v1

The IncomparableException class

Must be thrown if comparison methods receive input they can not compare with.

Class synopsis

class Phrity\Comparison\IncomparableException
    extends InvalidArgumentException {

    /* Inherited from InvalidArgumentException */
    public __construct([string $message = '' [, int $code = 0 [, Throwable $previous = null]]])
    public getMessage() : string
    public getPrevious() : Throwable
    public getCode() : mixed
    public getFile() : string
    public getLine() : int
    public getTrace() : array
    public getTraceAsString() : string
    public __toString() : string
}

Versions

Version	PHP
1.4	^8.1
1.3	^7.1|^8.0
1.2	^7.1	The Comparator supports stored content for multiple operations
1.1	>=5.6	The Comparator class for sort and filter
1.0	>=5.6	Equalable and Comparable interface, ComparisonTrait trait