NAME

       Badger::Comparable - base class for comparable objects

SYNOPSIS

           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
           }

DESCRIPTION

       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.

METHODS

   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).

OVERLOADED OPERATORS

   ==
       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
           }

AUTHOR

       Andy Wardley <http://wardley.org>

COPYRIGHT

       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.