Badger...arable(3pm)

💖 Badger::Comparable 💖

okay so bestie, welcome to the manual page for Badger::Comparable — it lives in section 3pm, aka the User Contributed Perl Documentation corner of the universe. she's a base class for comparable objects and honestly? iconic behavior. 🎀

---

✨ NAME ✨

Badger::Comparable — the base class for comparable objects. she gives your objects opinions about ordering. 🦋

---

🌸 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 💅

So basically, this module implements a base class for comparable objects. Subclasses need only define a compare() method and can inherit all the other methods provided. the rest of the work? done. handled. not your problem. 💁‍♀️

and because she's generous, overloaded comparison operators are also defined. so your objects can just... do math-adjacent vibes at each other. slay.

---

👑 METHODS 👑

⭐ compare($that)

okay this one is non-negotiable — this method must be defined by subclasses. nobody else can do it for you, bestie. 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. that's it. that's the whole vibe check. ✨

💖 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). they're giving "we are not the same" energy 💀

🦋 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"). main character energy, always first in line ✨

🌸 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). fashionably late, on purpose 💅

🌈 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 🎀

these are the little spells that make your objects play nice with the regular comparison symbols. no cap. 🪄

💜 ==

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> — yes, the legend herself. 🫶

---

💌 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. so go off, share the love, it's giving open source 💖

---

and that's the whole page bestie, ty for coming to my ted talk. this beauty shipped with perl v5.36.0 on 2023-08-28 — go forth and compare things, responsibly. 💅✨🌈