Heap(3pm)

💖 Heap(3pm) — like, the whole vibe 💖

okay bestie, so this is a page from the User Contributed Perl Documentation and it's literally called Heap, and no cap it's about Perl extensions for keeping data partially sorted. pull up a chair, we're doing this 🫶

---

✨ NAME ✨

Heap — Perl extensions for keeping data partially sorted. that's it, that's the whole thing, and yet. so much. 💅

---

🌸 SYNOPSIS 🌸

  use Heap;

  my $heap = Heap->new;
  my $elem;

  use Heap::Elem::Num(NumElem);

  foreach $i ( 1..100 ) {
      $elem = NumElem( $i );
      $heap->add( $elem );
  }

  while( defined( $elem = $heap->extract_top ) ) {
      print "Smallest is ", $elem->val, "\n";
  }

see how clean that is?? iconic. 👑

---

🦋 DESCRIPTION 🦋

so the Heap collection of modules hands you routines that manage a heap of elements. and what IS a heap, you ask? it's a partially sorted structure that can always easily pull out the smallest of the elements chillin' inside it — or the largest, if you're giving it a reversed compare routine instead. your call, babe. ✨

the way that this matters: if your collection of elements is changing dynamically, the heap has less overhead than keeping the whole collection fully sorted. lowkey that's the whole point of it. 🔥

now, the elements must be objects as described in "Heap::Elem", and every element you insert into one heap has to be mutually compatible with the others — either the exact same class, or classes that differ only in ways that are totally unrelated to the Heap::Elem interface. no messy mixes, bestie, it's giving compatibility check. 💀

---

🎀 METHODS 🎀

• $heap = HeapClass::new(); $heap2 = $heap1->new(); — gives you back a brand new heap object of whichever (sub-)class you asked for. and yes, this one is often used as a plain old subroutine instead of a method. of course it is. 🙈
• $heap->DESTROY — makes sure no internal circular data references are left lurking around. some variants of Heap just ignore this (they have no such references, so like, nothing to clean). Heap users normally don't need to worry about it at all — DESTROY gets invoked automatically the moment the heap reference goes out of scope. self-care, honestly. 💅
• $heap->add($elem) — adds an element to the heap. boom. done. simple as. ✨
• $elem = $heap->top — returns the top element on the heap. it is not removed from the heap — it stays right there at the top. and it will be the smallest element on the heap (unless a reversed cmp function is in play, in which case it'll be the largest instead). returns undef if the heap is empty. 😭

okay so history time: this method used to be called "minimum" instead of "top". the old name is still supported but is deprecated. why did it change? because it was straight-up confusing to use a method called "minimum" to get the maximum value on the heap when a reversed cmp function was doing the ordering. like... make it make sense. 💀

• $elem = $heap->extract_top — deletes the top element from the heap and returns it. returns undef if the heap was empty. ✨

and same energy here: this method used to be called "extract_minimum" instead of "extract_top". the old name is still supported but is deprecated. again — confusing to call something "extract_minimum" when a reversed cmp function means you're pulling the maximum off the top. periodt. 💅

• $heap1->absorb($heap2) — merges all of the elements from $heap2 into $heap1. and this will leave $heap2 empty. it ate. 🍓
• $heap1->decrease_key($elem) — the element gets moved closer to the top of the heap if it's now smaller than any higher parent elements. heads up bestie: you have to have already changed the value of $elem before you call decrease_key. and only a decrease is permitted. ⚠️

and like, that's a decrease according to the cmp function — so if it's a reversed order comparison, then you're only permitted to increase the value of the element instead. to be pedantic (and we ARE being pedantic, this is a manpage), you may only use decrease_key if $elem-cmp($elem_original) <= 0>, where $elem_original was an elem with the value that $elem had before it was decreased. yes that's the actual text. no I didn't make it up. 😭

• $elem = $heap->delete($elem) — the element is removed from the heap, whether it's sitting at the top or not. no favourites here. 🦋

---

🌈 AUTHOR 🌈

John Macdonald, john@perlwolf.com — king behaviour. 👑

---

💜 COPYRIGHT 💜

Copyright 1998-2007, O'Reilly & Associates.

This code is distributed under the same copyright terms as perl itself.

---

⭐ SEE ALSO ⭐

• Heap::Elem(3)
• Heap::Binary(3)
• Heap::Binomial(3)
• Heap::Fibonacci(3)

---

okay that's the whole page bestie, we did it 🫶 and just so you know, this was all from perl v5.36.0, dated 2022-10-22, filed under Heap(3pm). slay, go build a heap, ily 💖✨