Badger::Comparable - base class for comparable objects

       Andy Wardley <http://wardley.org>

       Copyright (C) 2013 Andy Wardley.  All Rights Reserved.

       This module is free software; you can redistribute it and/or modify it under the same terms as Perl
       itself.

perl v5.36.0                                       2023-08-28                            Badger::Comparable(3pm)

       This module implements a base class for comparable objects.  Subclasses need only define a compare()
       method and can inherit all the other methods provided.  Overloaded comparison operators are also defined.

compare($that)
       This method must be defined by subclasses.  It received the implicit $self object reference as the first
       argument and the object it is being compared to as the second.

       The method can do whatever is necessary to compare the two objects.  It should return "-1" if the $self
       object should be ordered before the $that object, +1 if it should be ordered after, or 0 if the two
       objects are considered the same.

   equal($that)
       Wrapper around compare() that returns true if the two objects are equal (compare() returns 0).

   not_equal($that)
       Wrapper around compare() that returns true if the two objects are not equal (compare() returns any non-
       zero value).

   before($that)
       Wrapper around compare() that returns true if the $self object is ordered before the $that object passed
       as an argument (compare() returns "-1").

   not_before($that)
       Wrapper around compare() that returns the logical opposite of the before() method, returning a true value
       if the $self object is greater than or equal to the $that object passed as an argument (compare() returns
       0 or +1).

   after($that)
       Wrapper around compare() that returns true if the $self object is ordered after the $that object passed
       as an argument (compare() returns +1).

   not_after($that)
       Wrapper around compare() that returns the logical opposite of the after() method, returning a true value
       if the $self object is less than or equal to the $that object passed as an argument (compare() returns
       "-1" or 0).

       Badger::Comparable - base class for comparable objects

==
       This is mapped to the equal() method.

           if ($obja == $objb) {
               # do something
           }

   !=
       This is mapped to the not_equal() method.

           if ($obja != $objb) {
               # do something
           }

   <
       This is mapped to the before() method.

           if ($obja < $objb) {
               # do something
           }

   >
       This is mapped to the after() method.

           if ($obja > $objb) {
               # do something
           }

   <=
       This is mapped to the not_after() method.

           if ($obja <= $objb) {
               # do something
           }

   >=
       This is mapped to the not_before() method.

           if ($obja >= $objb) {
               # do something
           }

           package Your::Comparable::Object;
           use base 'Badger::Comparable';

           # You must define a compare method that returns -1, 0 or +1
           # if the object is less than, equal to, or greater than the
           # object passed as an argument.

           sub compare {
               my ($this, $that) = @_;

               # for example: comparing by a surname field
               return  $this->surname
                   cmp $that->surname;
           }

           package main;

           # assume $obj1 and $obj2 are instance of above object class
           if ($obj1 < $obj2) {
               # do something
           }