Number...::Union(3pm)

💖 Number::Tolerant::Union — unions of tolerance ranges 💖

okay bestie, so this is a page from the Number::Tolerant::Union manual, and it's serving version 1.710 realness. come sit with me, we're gonna get into it ✨

---

🌸 SYNOPSIS 🌸

use Number::Tolerant;

my $range1 = tolerance(10 => to => 12);
my $range2 = tolerance(14 => to => 16);

my $union = $range1 | $range2;

if ($11 == $union) { ... } # this will happen
if ($12 == $union) { ... } # so will this

if ($13 == $union) { ... } # nothing will happen here

if ($14 == $union) { ... } # this will happen
if ($15 == $union) { ... } # so will this

like... look at that. $11 and $12 are in, $13 is not in (the gap is gagged), $14 and $15 are in. the vibes are immaculate 👑

---

🦋 DESCRIPTION 🦋

So Number::Tolerant::Union is the little helper that Number::Tolerant pulls in to represent the union of multiple tolerances. Basically: smash a bunch of tolerances together with | and this is what you get 💅

Here's the tea though — only a subset of the operators that work on a single tolerance will work on a union of tolerances. The list of what actually works is right below, no gatekeeping 💖

---

🎀 PERL VERSION 🎀

ngl this one's chill. this library should run on perls released even a long time ago, and it should work on any version of perl released in the last five years. periodt.

That said — and hear me out — even though it may work on older perls, there is no guarantee that the minimum required version won't get bumped. The version may be increased for any reason, and there's no promise that patches will be accepted to lower the minimum required perl. so like... it might work, but don't come for her if it doesn't 🙈

---

✨ METHODS ✨

💜 new

my $union = Number::Tolerant::Union->new(@list_of_tolerances);

Okay so there is a "new" method hanging out on the Number::Tolerant::Union class, but bestie, plot twist: unions are actually meant to be created with the "|" operator on a Number::Tolerant tolerance. the new method is like the back door, yk?

The arguments to "new" are a list of numbers or tolerances to be unioned. simple as that 💫

⚠️ important lore: intersecting ranges are not converted into a single range. like, the union of "5 to 10" and "7 to 12" is not "5 to 12". no merging happening here. that said, this may change in the future, so stay tuned i guess 😭

---

🌈 options

This method will return a list of all the acceptable options for the union. it's giving "here's everything you're allowed to be" 🫶

---

👑 Overloading

Tolerance unions overload a few operations, mostly comparisons. let's go through them one by one:

💀 numification

Unions numify to undef. and honestly? if there's a better idea, the author would love to hear it. iconic honesty tbh.

🌸 stringification

A tolerance stringifies to a short description of itself. Specifically, it's a set of the union's options, parentheses-enclosed and joined by the word "or". cute, right? 🎀

💖 equality

A number is equal to a union if it is equal to any of its options. one of them counts? you're in. slay.

⭐ comparison

• A number is greater than a union if it is greater than all its options.
• A number is less than a union if it is less than all its options.

all of them, not just one. don't get it twisted ✨

🧚 union intersection

An intersection ("&") with a union is commutted across all options. In other words:

 (a | b | c) & d  ==yields==> ((a & d) | (b & d) | (c & d))

Options that have no intersection with the new element are dropped — like, bye, you're not invited anymore 🙈

And the intersection of a constant number and a union yields that number, if the number was in the union's ranges, and otherwise yields nothing. that's the whole rule, no cap 💅

---

🔥 TODO 🔥

Who knows. Collapsing overlapping options, probably. (the author said it, not me 😭)

---

🌟 AUTHOR 🌟

Ricardo Signes <cpan@semiotic.systems> — absolute legend 🫶

---

💌 COPYRIGHT AND LICENSE 💌

This software is copyright (c) 2004 by Ricardo Signes.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. free as in freedom, bestie 💖

---

and that's the whole page, you ate that 🎀 this was perl v5.36.0, dated 2023-01-08, from the Number...::Union(3pm) page. mwah 💋 go forth and union your tolerances, i believe in you ✨💅