add heap

Author: fen-dada

heap/README.md

@@ -0,0 +1,35 @@
+# Heap
+A generic binary heap (priority queue) implemented in the [MoonBit](https://www.moonbitlang.com/) language.
+
+This implementation supports a **custom comparator**, so you can build either a **min-heap** or **max-heap**, or any domain-specific ordering. It aims to be a clean, robust, and idiomatic template for reuse.
+
+## ✨ Features
+- **Generic**: Works with any type `T`.
+- **Customizable Ordering**: Provide `(T, T) -> Bool` to define heap priority.
+- **Linear Build**: `from_vec` constructs the heap in `O(n)`.
+- **Logarithmic Ops**: `add`（push）与 `pop`（extract-top）均为 `O(log n)`.
+- **Safe API**: `pop` 返回 `T?`，空堆时安全退出。
+
+## ✅ Requirements
+- 使用 MoonBit 动态数组作为底层存储。
+- 你需要提供一个比较器 `cmp : (T, T) -> Bool`，其中 `cmp(a, b) = true` 表示 **a 的优先级高于 b**。  
+  - 最小堆：`fn(a, b) { a < b }`  
+  - 最大堆：`fn(a, b) { a > b }`
+
+## 🧩 API Overview
+```moonbit
+pub struct Heap[T] {
+  items : Array[T]
+  comparator : (T, T) -> Bool
+}
+
+pub fn[T] Heap::new(comparator : (T, T) -> Bool) -> Heap[T]
+pub fn[T] Heap::from_vec(items : Array[T], comparator : (T, T) -> Bool) -> Heap[T]
+pub fn[T] Heap::build_heap(self : Heap[T]) -> Unit
+
+pub fn[T] Heap::len(self : Heap[T]) -> Int
+pub fn[T] Heap::is_empty(self : Heap[T]) -> Bool
+pub fn[T] Heap::add(self : Heap[T], value : T) -> Unit         // push
+pub fn[T] Heap::pop(self : Heap[T]) -> T?                      // extract top or None
+pub fn[T] Heap::iter(self : Heap[T]) -> Iter[T]                // internal order (not sorted)
+

heap/heap.mbt

@@ -0,0 +1,213 @@
+///|
+pub struct Heap[T] {
+  items : Array[T]
+  comparator : (T, T) -> Bool
+}
+
+///|
+/// Creates a new, empty heap with a custom comparator function.
+///
+/// # Parameters
+/// - `comparator`: A function that defines the heap's ordering.
+///
+/// # Returns
+/// A new `Heap` instance.
+pub fn[T] Heap::new(comparator : (T, T) -> Bool) -> Heap[T] {
+  Heap::{ items: Array::new(), comparator }
+}
+
+///|
+/// Creates a heap from a vector and a custom comparator function.
+///
+/// # Parameters
+/// - `items`: A vector of items to be turned into a heap.
+/// - `comparator`: A function that defines the heap's ordering.
+///
+/// # Returns
+/// A `Heap` instance with the elements from the provided vector.
+pub fn[T] Heap::from_vec(
+  items : Array[T],
+  comparator : (T, T) -> Bool,
+) -> Heap[T] {
+  let heap = Heap::{ items, comparator }
+  heap.build_heap()
+  heap
+}
+
+///|
+/// Constructs the heap from an unsorted vector by applying the heapify process.
+pub fn[T] Heap::build_heap(self : Heap[T]) -> Unit {
+  let n = self.items.length()
+  if n < 2 {
+    return
+  }
+  let mut idx = n / 2 - 1
+  while true {
+    self.heapify_down(idx)
+    if idx == 0 {
+      break
+    }
+    idx -= 1
+  }
+}
+
+///|
+/// Returns the number of elements in the heap.
+///
+/// # Returns
+/// The number of elements in the heap.
+pub fn[T] Heap::len(self : Heap[T]) -> Int {
+  self.items.length()
+}
+
+///|
+/// Checks if the heap is empty.
+///
+/// # Returns
+/// `true` if the heap is empty, `false` otherwise.
+pub fn[T] Heap::is_empty(self : Heap[T]) -> Bool {
+  self.len() == 0
+}
+
+///|
+/// Adds a new element to the heap and maintains the heap property.
+///
+/// # Parameters
+/// - `value`: The value to add to the heap.
+pub fn[T] Heap::add(self : Heap[T], value : T) -> Unit {
+  self.items.push(value)
+  self.heapify_up(self.len() - 1)
+}
+
+///|
+/// Removes and returns the root element from the heap.
+///
+/// # Returns
+/// The root element if the heap is not empty, otherwise `None`.
+pub fn[T] Heap::pop(self : Heap[T]) -> T? {
+  if self.is_empty() {
+    return None
+  }
+  let next = if self.items.length() > 0 {
+    let val = self.items[0]
+    let last = self.items.pop().unwrap()
+    if self.items.length() > 0 {
+      self.items[0] = last
+    }
+    Some(val)
+  } else {
+    None
+  }
+  if !self.is_empty() {
+    self.heapify_down(0)
+  }
+  next
+}
+
+///|
+/// Returns an iterator over the elements in the heap.
+///
+/// # Returns
+/// An iterator over the elements in the heap, in their internal order.
+pub fn[T] Heap::iter(self : Heap[T]) -> Iter[T] {
+  self.items.iter()
+}
+
+///|
+/// Moves an element upwards to restore the heap property.
+///
+/// # Parameters
+/// - `idx`: The index of the element to heapify up.
+fn[T] Heap::heapify_up(self : Heap[T], idx : Int) -> Unit {
+  let mut idx0 = idx
+  while self.parent_idx(idx0) is Some(pdx) { // while-let 等价写法
+    if (self.comparator)(self.items[idx0], self.items[pdx]) {
+      let tmp = self.items[idx0]
+      self.items[idx0] = self.items[pdx]
+      self.items[pdx] = tmp
+      idx0 = pdx
+    } else {
+      break
+    }
+  }
+}
+
+///|
+/// Moves an element downwards to restore the heap property.
+///
+/// # Parameters
+/// - `idx`: The index of the element to heapify down.
+fn[T] Heap::heapify_down(self : Heap[T], idx : Int) -> Unit {
+  let mut idx0 = idx
+  while self.children_present(idx0) {
+    let cdx = if self.right_child_idx(idx0) >= self.len() {
+      self.left_child_idx(idx0)
+    } else {
+      let ldx = self.left_child_idx(idx0)
+      let rdx = self.right_child_idx(idx0)
+      if (self.comparator)(self.items[ldx], self.items[rdx]) {
+        ldx
+      } else {
+        rdx
+      }
+    }
+    if (self.comparator)(self.items[cdx], self.items[idx0]) {
+      self.items.swap(idx0, cdx)
+      idx0 = cdx
+    } else {
+      break
+    }
+  }
+}
+
+///|
+/// Returns the index of the parent of the element at `idx`.
+///
+/// # Parameters
+/// - `idx`: The index of the element.
+///
+/// # Returns
+/// The index of the parent element if it exists, otherwise `None`.
+fn[T] Heap::parent_idx(self : Heap[T], idx : Int) -> Int? {
+  if idx > 0 {
+    Some((idx - 1) / 2)
+  } else {
+    None
+  }
+}
+
+///|
+/// Checks if the element at `idx` has children.
+///
+/// # Parameters
+/// - `idx`: The index of the element.
+///
+/// # Returns
+/// `true` if the element has children, `false` otherwise.
+fn[T] Heap::children_present(self : Heap[T], idx : Int) -> Bool {
+  self.left_child_idx(idx) < self.len()
+}
+
+///|
+/// Returns the index of the left child of the element at `idx`.
+///
+/// # Parameters
+/// - `idx`: The index of the element.
+///
+/// # Returns
+/// The index of the left child.
+fn[T] Heap::left_child_idx(self : Heap[T], idx : Int) -> Int {
+  idx * 2 + 1
+}
+
+///|
+/// Returns the index of the right child of the element at `idx`.
+///
+/// # Parameters
+/// - `idx`: The index of the element.
+///
+/// # Returns
+/// The index of the right child.
+fn[T] Heap::right_child_idx(self : Heap[T], idx : Int) -> Int {
+  self.left_child_idx(idx) + 1
+}

heap/heap.mbti

@@ -0,0 +1,25 @@
+// Generated using `moon info`, DON'T EDIT IT
+package "Lampese/Algorithms-Moonbit/heap"
+
+// Values
+
+// Errors
+
+// Types and methods
+pub struct Heap[T] {
+  items : Array[T]
+  comparator : (T, T) -> Bool
+}
+fn[T] Heap::add(Self[T], T) -> Unit
+fn[T] Heap::build_heap(Self[T]) -> Unit
+fn[T] Heap::from_vec(Array[T], (T, T) -> Bool) -> Self[T]
+fn[T] Heap::is_empty(Self[T]) -> Bool
+fn[T] Heap::iter(Self[T]) -> Iter[T]
+fn[T] Heap::len(Self[T]) -> Int
+fn[T] Heap::new((T, T) -> Bool) -> Self[T]
+fn[T] Heap::pop(Self[T]) -> T?
+
+// Type aliases
+
+// Traits
+

heap/heap_test.mbt

@@ -0,0 +1,63 @@
+///|
+test "heap_empty_test" {
+  let heap : Heap[Int] = Heap::new(fn(x, y) { true })
+  inspect(heap.pop(), content="None")
+}
+
+///|
+test "heap_max_test" {
+  let heap = Heap::new(fn(x, y) { if x > y { true } else { false } })
+  heap.add(4)
+  heap.add(2)
+  heap.add(9)
+  heap.add(11)
+  assert_eq(heap.len(), 4)
+  assert_eq(heap.pop(), Some(11))
+  assert_eq(heap.pop(), Some(9))
+  assert_eq(heap.pop(), Some(4))
+  heap.add(1)
+  assert_eq(heap.pop(), Some(2))
+  assert_eq(heap.pop(), Some(1))
+  assert_eq(heap.pop(), None)
+}
+
+///|
+test "heap_min_test" {
+  let heap = Heap::new(fn(x, y) { if x < y { true } else { false } })
+  heap.add(4)
+  heap.add(2)
+  heap.add(9)
+  heap.add(11)
+  assert_eq(heap.len(), 4)
+  assert_eq(heap.pop(), Some(2))
+  assert_eq(heap.pop(), Some(4))
+  assert_eq(heap.pop(), Some(9))
+  heap.add(1)
+  assert_eq(heap.pop(), Some(1))
+  assert_eq(heap.pop(), Some(11))
+  assert_eq(heap.pop(), None)
+}
+
+///|
+test "heap_min_from_vec_test" {
+  let vec = [3, 1, 4, 1, 5, 9, 2, 6, 5]
+  let heap = Heap::from_vec(vec, fn(x, y) { if x < y { true } else { false } })
+  assert_eq(heap.len(), 9)
+  assert_eq(heap.pop(), Some(1))
+  assert_eq(heap.pop(), Some(1))
+  assert_eq(heap.pop(), Some(2))
+  heap.add(0)
+  assert_eq(heap.pop(), Some(0))
+}
+
+///|
+test "heap_max_from_vec_test" {
+  let vec = [3, 1, 4, 1, 5, 9, 2, 6, 5]
+  let heap = Heap::from_vec(vec, fn(x, y) { if x > y { true } else { false } })
+  assert_eq(heap.len(), 9)
+  assert_eq(heap.pop(), Some(9))
+  assert_eq(heap.pop(), Some(6))
+  assert_eq(heap.pop(), Some(5))
+  heap.add(10)
+  assert_eq(heap.pop(), Some(10))
+}

heap/moon.pkg.json

@@ -0,0 +1 @@
+{ }