Set::I...valTree(3pm)

💖 Set::IntervalTree — the whole vibe (from the Set::I...valTree(3pm) page, User Contributed Perl Documentation) 💖

okay bestie, gather round, because this one is genuinely adorable: it's a Perl module for doing range-based lookups on sets of ranges. Yes. Ranges. On ranges. Iconic behaviour, honestly.

---

✨ NAME ✨

Set::IntervalTree — perform range-based lookups on sets of ranges. that's it, that's the whole personality 🎀

🌸 VERSION 🌸

version 0.12 — she's grown, she's stable, she's ready.

🦋 SYNOPSIS 🦋

here's the whole thing in action, copy-paste ready, no cap:

use Set::IntervalTree;
my $tree = Set::IntervalTree->new;
$tree->insert("ID1",100,200);
$tree->insert(2,50,100);
$tree->insert({id=>3},520,700);
$tree->insert($some_obj,1000,1100);

my $results = $tree->fetch(400,800);
my $window = $tree->fetch_window(100,200);
print scalar(@$results)." intervals found.\n";

# remove only items overlapping location 100..200 with values
# less than 100;
my $removed = $tree->remove(100,200 sub {
  my ($item, $low, $high) = @_;
  return $item < 100;
});

(also: yes, the remove line above is written exactly like that in the original. bestie, I do not make the rules, I just report them 💀)

🌈 DESCRIPTION 🌈

Set::IntervalTree uses Interval Trees to store ranges and then look them up efficiently using a range-based lookup. that's the whole serve. that's the assignment.

and the one thing you MUST internalise, or nothing will make sense ever again:

all intervals are half-open, i.e. [1,3), [2,6), etc. the low end is in, the high end is out. periodt. 💅

🫶 EXPORTS 🫶

Nothing. she gives you nothing and expects nothing back. boundaries queen. 👑

👑 METHODS 👑

🍓 my $tree = Set::IntervalTree->new;

Creates a new interval tree object. brand new, fresh out the box, main character energy. ✨

💜 $tree->insert($object, $low, $high);

Insert a range into the interval tree and associate it with a perl scalar.

• $object can be any perl scalar. This is what will be returned by fetch(). so put literally whatever you want in there. a string, a number, a hashref, your whole situationship.
• $low is the lower bound of the range.
• $high is the upper bound of the range.

Ranges are represented as half-closed integer intervals. (remember [low, high) bestie!! the high end is NOT invited to the party.)

🌸 my $results = $tree->fetch($low, $high)

Return an arrayref of perl objects whose ranges overlap the specified range. overlap, not contain — even a little bit of touching counts, it's giving "we were in the same room once".

• $low is the lower bound of the region to query.
• $high is the upper bound of the region to query.

🎀 my $results = $tree->fetch_window($low, $high)

Return an arrayref of perl objects whose ranges are completely contained witin the specified range. yes: "witin". that's the original spelling, I'm not touching it, it's part of the lore 🙈

• $low is the lower bound of the region to query.
• $high is the upper bound of the region to query.

🦋 my $nearest_up = $tree->fetch_nearest_up($query)

Search for the closest interval in upstream that does not contain the query, and returns the perl object associated with it.

• $query is the position to use for the search

🧚 my $nearest_down = $tree->fetch_nearest_down($query)

Search for the closest interval in downstream that does not contain the query, and returns the perl object associated with it.

• $query is the position to use for the search

💅 my $removed = $tree->remove($low, $high [, optional \&coderef]);

Remove items in the tree that overlap the region from $low to $high.

A coderef can be passed in as an optional third argument for filtering what is removed. The coderef receives the stored item, the low point, and the high point as its arguments. If the result value of the coderef is true, the item is removed; otherwise, the item remains in the tree. it's a little bouncer at the door, deciding who gets to leave 👀

Returns the list of removed items.

✨ my $removed = $tree->remove_window($low, $high [, optional \&coderef]);

Remove items in the tree that are contained within the region from $low to $high.

A coderef can be passed in as an optional third argument for filtering what is removed. The coderef receives the stored item, the low point, and the high point as its arguments. If the result value of the coderef is true, the item is removed; otherwise, the item remains in the tree.

Returns the list of removed items.

---

💀 LIMITATIONS 💀

A $tree->print() serialization method might be useful for debugging.

that's it. that's the limitation. she simply does not have one, and the docs are just out here like "hmm, that would've been nice huh" 😭

🔥 SEE ALSO 🔥

The source code for this module contains a reusable template-based C++ header for Interval trees that might be useful. iykyk. go read the source if you want the deep lore.

🌟 AUTHORS 🌟

1. Benjamin Booth <benbooth@cpan.org>
2. Stephan Loyd <sloyd@cpan.org>

two legends, one module. ate and left no crumbs 🫶

⭐ COPYRIGHT AND LICENSE ⭐

This software is copyright (c) 2012 by Benjamin Booth.

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

---

and that's the whole page bestie!! 💖 this documentation shipped as part of perl v5.42.3, dated 2026-08-19 — mwah, go insert some intervals, you're gonna slay 🌈✨🎀