https://github.com/clojure-finance/clojure-heap
Pure Clojure implementation of a heap, i.e. priority queue
https://github.com/clojure-finance/clojure-heap
clojure heap priority-queue
Last synced: 5 months ago
JSON representation
Pure Clojure implementation of a heap, i.e. priority queue
- Host: GitHub
- URL: https://github.com/clojure-finance/clojure-heap
- Owner: clojure-finance
- License: mit
- Created: 2022-01-17T13:59:49.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2022-12-17T13:36:40.000Z (about 3 years ago)
- Last Synced: 2025-05-07T20:37:16.068Z (8 months ago)
- Topics: clojure, heap, priority-queue
- Language: Clojure
- Homepage:
- Size: 49.8 KB
- Stars: 18
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Clojure Heap
A pure Clojure implementation of mutable binary **heap** / **priority queue**.
### Installation
Available on [](https://clojars.org/com.github.clojure-finance/clojure-heap)
Import it using
```clojure
(require '[clojure-heap.core :as heap])
```
***Or***
Copy the source code in [`src/clojure/clojure_heap/core.clj`](src/clojure/heap/core.clj) to your project.
### Speed
Equal to the theoretical limit.
**Single** **`add`**: O(logn)
**Single** **`poll`**: O(logn)
**Space**: n
### APIs
#### `heap`
Create a heap with a comparator[ and an entry]. O(1)
| Argument | Type | Function | Remarks |
| ------------ | -------- | ------------------------------------------------ | ------------------------------------------------------------ |
| `comparator` | Function | A comparator function, deciding a max / min heap | Two arguments. Return `true` on matching the condition, `false` otherwise |
| [`value`] | Any | The first entry of the heap | |
**Example**
```clojure
;; define a max heap containing maps
(def x (heap (fn [a b] (> (:id a) (:id b))) {:id 3}))
;; without initial value
(def x (heap (fn [a b] (> (:id a) (:id b)))))
```
#### `get-size`
Get the size (length) of heap. O(1)
| Argument | Type | Function | Remarks |
| -------- | -------------- | ------------- | ------- |
| `heap` | heap.core.Heap | A heap object | |
**Example**
```clojure
(def x (heap (fn [a b] (> (:id a) (:id b))) {:id 3}))
(get-size x)
;; return 1
```
#### `peek`
Get the top value of the heap. If it is a min heap, return the smallest value; otherwise return the largest value. Return nil if the heap is empty. O(1)
| Argument | Type | Function | Remarks |
| -------- | -------------- | ------------- | ------- |
| `heap` | heap.core.Heap | A heap object | |
**Example**
```clojure
(def x (heap (fn [a b] (> (:id a) (:id b))) {:id 3}))
(peek x)
;; return {:id 3}
```
#### `add`
Insert an entry to the heap. The heap will be reorganized to fit the new value. O(logn), n = size of the heap
| Argument | Type | Function | Remarks |
| -------- | -------------- | ------------------------------------ | ------------------------------------------------------ |
| `heap` | heap.core.Heap | A heap object | |
| `value` | Any | The value to be inserted to the heap | Should be applicable as one argument of the comparator |
**Example**
```clojure
(def x (heap (fn [a b] (> (:id a) (:id b))) {:id 3}))
(add x {:id 4})
(get-size x)
;; return 2
```
#### `poll`
Delete and return the top value of the heap. If it is a min heap, return the smallest value; otherwise return the largest value. O(logn), n = size of the heap
| Argument | Type | Function | Remarks |
| -------- | -------------- | ------------- | ------- |
| `heap` | heap.core.Heap | A heap object | |
**Example**
```clojure
(def x (heap (fn [a b] (> (:id a) (:id b))) {:id 3}))
(poll x)
;; return {:id 3}
(poll x)
;; return nil
```